Proposal: track all long-running gateway work in the kanban store, with origin, progress and chat delivery

Aperta
#6,045 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
12/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
python, sqlite
Ambito
ai, backend

Direzione di ricerca

This is a multi-phase design proposal, not a starting task. Read the kanban store at src/praisonai-bot/praisonai_bot/kanban/sqlite_store.py and the protocol at src/praisonai-agents/praisonaiagents/kanban/protocols.py, then the delivery path _deliver_scheduled_result in src/praisonai-bot/praisonai_bot/gateway/server.py. Done means the phase 1 acceptance criteria pass, which requires agreeing the design with maintainers first.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

bug claude enhancement javascript origin/outsider

Summary

Long-running work started through the gateway is spread over seven separate job stores. Each has its own idea of status, ownership and restart behaviour, and none of them shares a record of who asked, from which chat, how far it has got, and where the result goes. That missing shared record is why background results never reach the user, why /tasks is empty, why restarts lose work silently, and why the kanban dispatcher can run a healthy task twice. This proposal makes the existing kanban store the single job registry and routes completion through the existing durable gateway outbox. It consolidates existing parts rather than adding a new subsystem.

Impact

Without a shared job record, every new long-running feature re-implements claims, persistence, delivery and cancellation, and each gets a different part wrong:

  • Results stay in a store the chat never reads.
  • Restarts mark work LOST or FAILED and tell no one.
  • Chat commands look at the wrong store.
  • Operators cannot answer "what is running for this user right now?"

The kanban store already has the hardest parts (CAS claims, leases, PIDs, run history, a circuit breaker, worktrees, hooks). The scheduler path already has the delivery side (a durable outbox and origin-aware routing). They are simply not connected.

Where it happens

The seven stores, verified on a28549c:

# Store Location Persistence Origin chat / owner Delivers to chat
1 Kanban tasks src/praisonai-bot/praisonai_bot/kanban/sqlite_store.py:51 SQLite (WAL) with claims, leases, worker_pid, task_runs, worktrees none (free-form metadata only) no
2 Gateway scheduler src/praisonai-agents/praisonaiagents/scheduler/config_store.py:4 (~/.praisonai/config.yaml; legacy scheduler/store.py jobs.json is migrated) YAML file yes (DeliveryTarget) yes, via the outbox
3 Background subagent jobs src/praisonai-agents/praisonaiagents/background/sqlite_store.py:34, src/praisonai-agents/praisonaiagents/background/job_manager.py:689 SQLite origin dict (empty in practice) no
4 BackgroundRunner (/tasks) src/praisonai-agents/praisonaiagents/background/runner.py:71 memory metadata.user_id, never set no
5 /v1/responses background runs src/praisonai-bot/praisonai_bot/gateway/api_endpoints.py:111 memory (capped at 1024) HTTP caller only n/a
6 Wrapper Jobs API src/praisonai/praisonai/jobs/server.py:36-51 memory unless PRAISONAI_JOBS_DB_PATH is set none no
7 Hook coalescer src/praisonai-bot/praisonai_bot/gateway/hook_coalescer.py:52 memory hook route via hook reply

There is an eighth, unused store: the run ledger (src/praisonai-agents/praisonaiagents/runs/sqlite_ledger.py:69), which gateway boot reads (src/praisonai-bot/praisonai_bot/gateway/server.py:2668) but nothing writes.

How the kanban dispatcher is run today:

  • The gateway never starts it. grep -n start_kanban_dispatcher src/praisonai-bot/praisonai_bot/gateway/server.py finds nothing.
  • Only the UI host bridge starts it (src/praisonai-bot/praisonai_bot/integration/bridges/kanban_bridge.py:84-113):
        async def _startup_handler():
            """Startup handler for kanban dispatcher."""
            try:
                if not is_dispatcher_running():
                    await start_kanban_dispatcher()
  • The CLI praisonai-bot kanban dispatch (src/praisonai-bot/praisonai_bot/cli/commands/kanban.py:314-327) runs a single dispatch_once and exits, leaving the workers it started unsupervised.

The delivery model to reuse is _deliver_scheduled_result (src/praisonai-bot/praisonai_bot/gateway/server.py:7429): it enqueues into scheduled_outbox (src/praisonai-bot/praisonai_bot/gateway/server.py:6304, SQLite, UNIQUE idempotency key) and sends through the shared DeliveryRouter.

Reproduction

This is a design proposal. The evidence comes from three companion bug reports, each reproduced on a28549c with stub workers and no LLM:

  • The dispatcher runs a healthy long task more than once. With scaled timeouts, one task had 4 concurrent workers and 4 open run rows after 7 s, because only the spawn writes a heartbeat.
  • Finished background work never reaches the user. spawn_subagent(background=True, deliver="origin") records an empty platform and chat, no delivery callback is registered, and /tasks answers "No background tasks" right after a task is submitted.
  • A restart drops in-flight work. A running background job with an origin comes back as LOST, fires no hook and sends no message. A kanban task whose worker died restarts from zero, its first run stays open, and no comment is written.

Root cause

Each store was added for one surface (board, schedule, subagent, CLI, OpenAI API, HTTP jobs, webhooks), with no shared job contract. Origin capture, progress, cancellation and completion delivery were each solved, or left unsolved, per store. The one store with solid execution semantics (kanban) has no idea of origin. The one path with solid delivery (the scheduler) has no idea of long-running execution.

Proposed fix

Make the kanban store the job registry for long-running work launched by the gateway, and the gateway its supervisor. No new store, service or Agent parameter.

Data model. Extend the existing KanbanTaskProtocol (src/praisonai-agents/praisonaiagents/kanban/protocols.py:29) with optional fields. Existing rows and callers are unaffected:

    origin: dict | None        # DeliveryTarget-shaped: platform, chat_id, thread_id, session_id, user_id
    progress: float | None     # 0..1, plus a short progress note (latest comment)
    checkpoint_ref: str | None # opaque pointer (branch/commit, session id, file) for resume
    kind: str | None           # "board" (default) | "subagent" | "schedule" | ...

Store these in the existing metadata JSON first, and promote them to columns only if they need indexing.

Phases

  1. Supervision. The gateway starts the dispatcher at boot, with configurable max_concurrent and poll interval in gateway config and PRAISONAI_KANBAN_DISPATCH=0 to opt out, and stops it on shutdown. The dispatcher heartbeats and extends the lease for every child it holds, never overwrites a live handle, and runs git off the event loop.
    Closes: duplicate runs of healthy long tasks, the event-loop freeze during git, and the "only the UI host runs the board" gap.
  2. Origin and delivery. Cards created from chat (kanban_create and the chat commands) record origin from get_session_context(). The gateway subscribes once to kanban_task_done, kanban_task_blocked and kanban_task_failed, and enqueues the outcome (the run summary) into scheduled_outbox with key kanban:{task_id}:{run_id}.
    Closes: finished background work never reaching the user.
  3. Chat control. /tasks lists the caller's jobs (filtered on origin.user_id) with status, progress and the last run summary. /tasks cancel <id> terminates the child, closes the run as cancelled and moves the card. Existing /stop is unchanged.
    Closes: /tasks always being empty, and the lack of any way to cancel background work from chat.
  4. Restart semantics. At boot, reclaim closes the interrupted run as crashed, counts it, records checkpoint_ref if the worker left one (for worktree tasks, the branch is a natural checkpoint), and sends an "interrupted, retrying" or "interrupted, needs you" notice to the origin through the outbox. The run ledger is either fed from here or retired.
    Closes: in-flight jobs lost or failed silently on restart.
  5. Route other launchers through it. spawn_subagent(background=True) inside a gateway turn creates a kind="subagent" card. Its in-process executor can stay as it is (the card is the record, and the job manager is the runner). Long scheduled runs can optionally do the same. Pure in-process callers keep BackgroundJobManager and BackgroundRunner unchanged.
    Closes: the split between /tasks and background subagents, and gives one place to answer "what is running for this user right now?"

Scope boundaries. The /v1/responses store and the wrapper Jobs API serve HTTP API clients rather than chat users. They can adopt the registry later, but phases 1-4 do not depend on them. The hook coalescer should become restart-safe on its own (record its idempotency key after the run), not become a kanban card.

What NOT to do: do not add an eighth store or a new "jobs service". Do not move kanban into core, because core keeps only the protocol and the SQLite implementation stays in praisonai-bot. Do not have the model choose the delivery target. It comes from the session context.

Acceptance criteria

  • Phase 1: the gateway runs the dispatcher by default (opt-out via config or env). The heartbeat and non-blocking-git regression tests pass.
  • Phase 2: a chat-created card posts its outcome to the originating chat exactly once, across restarts.
  • Phase 3: /tasks and /tasks cancel work on cards and subagent jobs, scoped per user.
  • Phase 4: after a simulated crash, an interrupted card has a closed crashed run, an incremented failure count and an origin notice.
  • Phase 5: spawn_subagent(background=True) inside a gateway turn appears in /tasks and delivers through the same path.
  • KanbanTaskProtocol changes are additive. Existing kanban tests (src/praisonai/tests/unit/test_kanban_sqlite_store.py, src/praisonai-agents/tests/unit/test_kanban_protocol.py, src/praisonai-bot/tests/unit/gateway/test_kanban_dispatcher_*.py) pass unchanged.
  • New tests: src/praisonai-bot/tests/unit/gateway/test_kanban_origin_delivery.py and src/praisonai-bot/tests/unit/bots/test_tasks_command_kanban.py.

Related

  • #5429: durable workflow suspend/resume with persisted execution state (open, TypeScript package). This is the same need for a durable, resumable job record, and phase 4's checkpoint_ref should follow the same shape.
  • #3819: commitment and promise follow-through (open). A promise like "I'll get back to you when the build finishes" needs exactly this: a job record with an origin plus completion delivery.
  • #1117: proposal for git-native durable task persistence (open). The kanban store plus per-task worktrees already covers much of it, and this issue would make it the default path.
  • #5880: Jobs API reconcile failed other processes' jobs (closed; fixed by #5881 with owner-scoped reconcile using a pid and start-time owner id). That ownership check is the model for phase 1's "only reclaim what is not owned by a live dispatcher".
  • #1720: original kanban store, tools and dispatcher (closed).
  • #2537 and #4698: background delivery and durable background store (closed). Their pieces are reused here, not replaced.

Filed together: #6025 (dispatcher re-runs healthy tasks); #6037 (results never reach the chat); #6038 (restart drops in-flight work); #6039 (git blocks the event loop); #6036 (one-shot schedules erased on claim); #6035 (scheduler serial, no timeout); #6034 (hooks block the HTTP reply); #6028 (loop crash recovery)


Generated by Claude Code

Lingua principale
Python
Stelle
9.3k
Fork
1.5k
Merge medio
1g 5h
PR unite (30g)
520

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.