[feat] Session control: server-held pending input, Queue then Steer

[mmabrouk]

Context

Today a message sent while a turn runs is refused, and the desktop keeps a local queue in the browser that other tabs and the mobile app cannot see. Increment 7 of the session-control design (PR #6495) moves pending input to the server: Queue first, then Steer. It builds on the durable approvals of #6530 because Steer extends the same command path.

What this adds

• Pending input on the server. An invoke that arrives with on_busy=queue while a turn runs is stored as a pending input with a stable position and an idempotency key, and the API answers 202 with the input id. A pending input can be removed until it is promoted. The session snapshot lists pending inputs in order. Migration oss000000028 adds the table, nullable and with a downgrade, after 027.
• Promotion. When the running turn completes normally, exactly one pending input is promoted in first-in first-out order and starts through the same admission and command path as a Send. A manual Stop and a failed turn promote nothing; the queue pauses until the next Send.
• Steer. A steer saves its input before it stops the current work, is positioned ahead of older queued inputs, and is bound to the Stop's settlement; if the Stop fails or is refused the input stays pending.
• Clients. Desktop and mobile composers show Queue and Steer controls only when the server advertises the capability; every browser renders the server rows as ordered, non-editable, removable entries, with the "Stop pauses the queue" copy.

Both behaviours ship dark behind their own switches in env.py, default off. With the switches off a busy session still answers 409 as today.

Tests

• Seven Postgres transaction tests: single FIFO promotion, manual Stop, concurrent idempotent retry, conflict 409, removal after promotion, save-before-failed-Stop, steer-bound promotion.
• API sessions, runner, SDK, and web suites green on the branch; SDK sweep 2,557 passed with one unrelated pre-existing failure in the runner CLI empty-request test.
• Not yet done: a Codex review, a rebase onto the current feat(sessions): make approval answers and continuation durable #6530 head, and the browser pass (Queue and Steer controls during a busy session, rows visible across browsers, removal before promotion, Steer running first, Stop keeping queued work, switches off).

Agent-generated, low weight. Draft until the review and the browser pass are done.

https://claude.ai/code/session_0164kzT6ttwpBtzvcDC6YzYk

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
agenta-documentation	Ready	Preview	Sep 5, 2026 1:42pm UTC

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• release/.*

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Team

Run ID: ca3f83b9-3550-454e-8680-3e3bc9fda465

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

Agent-generated Codex review, low weight.

CHANGES NEEDED

Seven inline correctness findings block this increment: successful-completion classification, admission/settlement fencing, retry idempotency, cross-tab admission, Steer binding, recoverable-input visibility, and an optional delivery receipt dereference.

The oss000000028 migration is additive; its nullable audit/promotion columns are safe, and the expanded command-kind check accepts every previously valid live value. I found no dropped release code in the removed lines. With Queue and Steer disabled, existing clients omit on_busy and both desktop and mobile retain the legacy send path. The runner's explicit error stopReason does not itself add a terminal event or change parking, but the completion watchdog must honor that new non-completing value as noted inline.

Validation: api/oss/tests/pytest/unit/sessions/test_session_inputs_dao.py passed 7 tests with xdist explicitly disabled; web/packages/agenta-chat/tests/unit/hooks/useAgentChatQueue.test.ts passed 21 tests with maxWorkers=2. Both ran serially at nice 19. The API file was rerun with -n 0 after the repository defaults unexpectedly started xdist on the first invocation.

Non-blocking simplification: SessionReadSnapshot/read is a constant latest_sequence=0, history_complete=true placeholder unused by Queue or Steer. It and its generated client type can be deferred until replay/cursor support without losing this milestone's RFC behavior.

[mmabrouk]

Agent-generated Codex review, low weight.

CHANGES NEEDED

Two P1 interleavings remain. The other five findings and the SessionReadSnapshot cut are closed. The 408023c admission lock adds no cycle with normal completion or answer transactions, and no external delivery or invoke work runs while it is held. bb6b6fe preserves the Queue-off Send control flow. e9ce73d removes only unused projection definitions, generated export, schema default, and fixtures.

Focused checks passed at nice 19: test_session_inputs_dao.py, 8 tests with pytest -n 0; useAgentChatQueue.test.ts, 22 tests with maxWorkers=2.

[mmabrouk]

Agent-generated Codex review, low weight.

CHANGES NEEDED

The Stop/Steer lock inversion and stale command read are fixed: terminal settlement and collapsed binding now both acquire the source execution before the command. The non-empty settlement regression covers a recoverable successor, but the first P1 remains when that promoted continuation has successfully started; see the inline finding.

[mmabrouk]

Agent-generated Codex review, low weight.

SHIP

Reviewed 47bbb114d3..1d7d250b3e as one unit. The round 4-6 fixes preserve durable retry identity, serialize admission with settlement, keep promoted/recoverable work visible without changing the running snapshot semantics, bind Steer to the winning Stop under a consistent execution-first lock order, and handle lost delivery reservations. The final active-successor revalidation also locks the unsettled successor while inserting, so a running continuation cannot be overtaken or settle past the new input.

No remaining correctness findings. The full API sessions suite passed (744 tests), Ruff 0.15.12 format and lint passed, the pushed SHA matches the remote, and all review threads are resolved.

[mmabrouk]

SHIP

The shared capability helper now keeps the stream and snapshot responses aligned for durable approvals, queue, and queue-gated steer. The API regression covers enabled and disabled flag combinations. Desktop and mobile both use the shared snapshot-backed session-input adapter, and the new client regression verifies that a queue-capable snapshot produces durable admission with on_busy: "queue".

Validated with the API sessions suite (746 passed), chat unit suite (674 passed), OSS unit suite (431 passed, 1 skipped), both package typechecks and lints, and Ruff 0.15.12.

Reviewed-by: Codex

[mmabrouk]

SHIP

Agent-generated, low weight.

Reviewed the two Round 8 commits at 7f6fd63. Stop and Escape now remain available for both locally streaming and server-owned durable runs on desktop and mobile, including a server-busy turn with one queued input. Enter and the Queue action now share awaited durable on_busy admission; a failed admission restores the draft instead of creating a browser-only queued badge.

No blocking findings. Full @agenta/chat, @agenta/oss, and @agenta/mobile unit suites, type checks, package lint, repository lint-fix, and the @agenta/chat dependency build passed.

[mmabrouk]

SHIP

Round 9 review: the live delay came from the done-record settlement promoting immediately while the completed runner generation still owned Redis liveness; the continuation heartbeat was rejected, leaving the abandoned-command sweep to retry it 98 seconds later. The shared normal-completion settlement now reconciles that source generation after commit and before delivery, so both record-ingest and watchdog completion paths admit the promoted continuation immediately. The regression requires done-record-to-admission latency below one second and makes delivery contingent on source reconciliation.

The client now suppresses the stale running-elsewhere banner only when the authoritative session snapshot is idle and a durable queued item is visible; genuinely running remote work still shows the warning and the queued badge remains.

Reviewed the round-9 diff and the live thread set (10/10 resolved). Validation: API sessions 747 passed; ruff 0.15.12 format/check clean; chat 677 passed plus types/lint; OSS 434 passed, 1 skipped, plus types/lint.

[mmabrouk]

SHIP

Round 10 review found the live Steer loss was confined to the client admission path. The initial fresh-run HTTP 200 kept the composer single-flight guard locked for the full SSE lifetime, so the later Steer click returned without issuing a second admission request. The Steer promise was also fire-and-forget, which prevented a real admission refusal from reaching the existing draft-restoration failure card.

The pushed fix releases the submit guard once accepted response headers arrive while draining the active stream in the background, and propagates Steer admission failures through both desktop and shared/mobile conversation paths. The API/runner chain remains intact: durable priority insert -> Stop command bound to steer_input_id -> registered execution abort -> atomic promotion of only that Steer input.

Verified locally: API sessions 747 passed; runner 2712 passed; chat 681 passed; OSS 434 passed with 1 skipped; mobile 150 passed. Chat/OSS/mobile and runner typechecks pass; requested lint and Ruff 0.15.12 checks pass. No blocking findings remain.

[mmabrouk]

SHIP

Round 11 reviewer pass found no blocking findings.

The 8880 API and runner logs confirm the reported Queue losses died before durable admission: neither 08:17:47Z nor 08:22:11Z has an inputs/admit request or control event. Round 10 already fixed the shared cause for both Queue and Steer: the fresh 200 admission releases the common submit guard at response headers, and both policies then route through the same durable server adapter.

The new regression recreates the detached local stream/server-running state while the first response body remains open. Enter, the Queue button, and Steer each send the expected on_busy admission and render the pending badge; a 409 restores the draft and shows the failure card.

Local validation: chat 685 passed; OSS 434 passed and 1 skipped; mobile 150 passed; runner 2712 passed. Chat, OSS, mobile, and runner type checks passed; lints passed with the three pre-existing mobile hook warnings.

[mmabrouk]

Agent-generated Codex review, low weight.

CHANGES NEEDED

The 24-commit range-diff preserves the reviewed queue/steer ordering and delivery invariants, and the unified model/client supplies both reader contracts. One availability regression remains: the queue half is unreachable with the shared-reader flag off or before a fresh session has its first stream row, so desktop and mobile disable durable Queue/Steer and use the browser-local fallback. See the inline P1.

Focused validation: unified snapshot tests 4 passed; API client, entities, and chat typechecks passed.

[mmabrouk]

Agent-generated, low weight.

SHIP

Reviewed dcf4753 as the Round 12 fix. The unified snapshot now preserves the queue/steer control plane when reconnect data is unavailable, keeps reconnect fields nullable across the API, Fern, and Zod contracts, and guards both milestone-2 reconnect reads. The shared-reader-off, fresh-session, full-contract, schema-boundary, queue-hook, and null-session reader paths are covered.

Validation: API sessions 859 passed; chat 815 passed; entities 1,553 passed; OSS 483 passed with 1 skipped; mobile 163 passed. Ruff 0.15.12, generated client build, all requested typechecks, and lint completed cleanly (mobile retained 3 pre-existing warnings).

[github-actions]

Railway Preview Environment

Preview URL	https://gateway-pr-6555.up.railway.app/w
Project	agenta-oss-clone-spike
Image tag	pr-6555-5f74809
Status	Deployed
Railway logs	Open logs
Workflow logs	View workflow run
Updated at 2026-09-05T13:57:09.328Z