docs(sessions): draft session control and shared live-events RFC - #6495
docs(sessions): draft session control and shared live-events RFC#6495mmabrouk wants to merge 65 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 SummarySummary by CodeRabbit
WalkthroughThis PR adds a documentation baseline for session control and live events. It defines contracts, architecture, durable history, live delivery, recovery, rollout increments, work packages, review decisions, and QA evidence. ChangesSession control and live events
Estimated code review effort: 3 (Moderate) | ~25 minutes Merge Risk: 🟡 Moderate · up to This RFC defines session Stop, recovery, live-event, and durable-history behavior, but conflicting and incomplete contract details could lead implementations to use inconsistent recovery, replay, and validation behavior. Resolve the documented inconsistencies before treating this baseline as merge-ready. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
…e Codex approval gap Claude-Session: https://claude.ai/code/session_01GAqSs7fw6QRi2n1ZJ2tmAV
… the reap fix Claude-Session: https://claude.ai/code/session_01GAqSs7fw6QRi2n1ZJ2tmAV
… 2026-09-04 Sequence cursor on the analytics database, quarantine for late output, the Codex reap now and the pin bump as its own PR, one global switch per increment, keep /cancel, a 30 s runner grace period, keep not_running past teardown. Claude-Session: https://claude.ai/code/session_01GAqSs7fw6QRi2n1ZJ2tmAV
📘 Docs preview
This comment updates in place on every push. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Team
Run ID: c7a94f4d-ae79-48e6-bb5c-40f27ed83ee4
📒 Files selected for processing (32)
docs/design/session-control-and-live-events/README.mddocs/design/session-control-and-live-events/architecture.mddocs/design/session-control-and-live-events/context.mddocs/design/session-control-and-live-events/contracts/commands.mddocs/design/session-control-and-live-events/contracts/events.mddocs/design/session-control-and-live-events/contracts/persistence.mddocs/design/session-control-and-live-events/contracts/public-api.mddocs/design/session-control-and-live-events/decisions.mddocs/design/session-control-and-live-events/evidence/README.mddocs/design/session-control-and-live-events/handoff.mddocs/design/session-control-and-live-events/live-frame-envelope.mddocs/design/session-control-and-live-events/open-questions.mddocs/design/session-control-and-live-events/plan.mddocs/design/session-control-and-live-events/qa.mddocs/design/session-control-and-live-events/records-invariants.mddocs/design/session-control-and-live-events/requirements.mddocs/design/session-control-and-live-events/research.mddocs/design/session-control-and-live-events/review-standard.mddocs/design/session-control-and-live-events/reviews/codex-gpt-5.6-sol-2026-09-03.mddocs/design/session-control-and-live-events/reviews/decision-list-2026-09-03.mddocs/design/session-control-and-live-events/reviews/fable-2026-09-03.mddocs/design/session-control-and-live-events/reviews/opus-practices-interfaces-2026-09-03.mddocs/design/session-control-and-live-events/reviews/qa-audit-2026-09-03.mddocs/design/session-control-and-live-events/rfc.mddocs/design/session-control-and-live-events/status.mddocs/design/session-control-and-live-events/tonight-handoff.mddocs/design/session-control-and-live-events/work-packages/README.mddocs/design/session-control-and-live-events/work-packages/durable-approvals.mddocs/design/session-control-and-live-events/work-packages/durable-history.mddocs/design/session-control-and-live-events/work-packages/live-relay.mddocs/design/session-control-and-live-events/work-packages/queue-steer.mddocs/design/session-control-and-live-events/work-packages/stop-and-recovery.md
Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
| The runner wraps invoke frames in the shared envelope and posts them through the existing records | ||
| ingest stream. A relay consumer reads temporary frames and forwards them through Server-Sent Events | ||
| (SSE). The records worker ignores temporary frames and persists durable events. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🔎 Supported by static analysis
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- architecture excerpt ---'
sed -n '35,125p' docs/design/session-control-and-live-events/architecture.md
printf '%s\n' '--- records invariants ---'
sed -n '1,220p' docs/design/session-control-and-live-events/records-invariants.md
printf '%s\n' '--- related files ---'
git ls-files 'docs/design/session-control-and-live-events/*'Repository: Agenta-AI/agenta
Length of output: 18523
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions
Length of output: 21940
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- recovery and durable-delivery references ---'
rg -n -i -C 3 'outbox|reconstruct|recovery source|durable incompleteness|bounded.*retry|drop|message\.completed|tool\.completed|records ingest|record ingest|turn-end drain|terminal outcome' \
docs/design/session-control-and-live-events \
-g '*.md'Repository: Agenta-AI/agenta
Length of output: 50374
Define recovery for durable events lost before Redis acceptance.
The runner can drop a durable record after bounded ingest retries. The records worker can recover only records that entered the ingest stream. Define a durable runner outbox, a watchdog or API reconstruction path, or an explicit durable incompleteness outcome. Add failure-injection coverage.
| ```text | ||
| pending -> claimed -> applied | ||
| -> obsolete | ||
| -> lost | ||
| ``` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Complete the command recovery state machine.
claim_expires_at and the lease-expiry rule require a claimed -> pending transition for redelivery. The diagram also omits the documented pending -> lost path when the runner is gone. Define these transitions, their compare-and-set predicates, and the behavior after bounded attempts. Without these rules, an accepted Stop can remain claimed or pending without a deterministic recovery outcome.
| frame_or_event_id | ||
| entity_id | ||
| type | ||
| payload |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🔎 Supported by static analysis
🏁 Script executed:
printf '%s\n' '--- target contract ---'
cat -n docs/design/session-control-and-live-events/contracts/events.md
printf '%s\n' '--- related identity contracts ---'
cat -n docs/design/session-control-and-live-events/contracts/persistence.md
printf '%s\n' '--- invariant files ---'
fd -i 'records-invariants' . -t f -x sh -c 'cat -n "$1"' sh {}
printf '%s\n' '--- identity references ---'
rg -n -C 3 'frame_or_event_id|record_id|event_id|frame_index|dedup|idempot' docs/design/session-control-and-live-eventsRepository: Agenta-AI/agenta
Length of output: 50375
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings
Length of output: 9275
🏁 Script executed:
printf '%s\n' '--- envelope specification ---'
cat -n docs/design/session-control-and-live-events/live-frame-envelope.md | sed -n '30,55p'
printf '%s\n' '--- requirements around durable identity ---'
cat -n docs/design/session-control-and-live-events/requirements.md | sed -n '88,104p'
printf '%s\n' '--- decisions around ingest and ordering ---'
cat -n docs/design/session-control-and-live-events/decisions.md | sed -n '128,148p'
printf '%s\n' '--- exact identity declarations in this design ---'
rg -n -C 2 --glob '*.md' 'frame_or_event_id|producer-generated stable|stable (record|event) ID|event_id|record_id' docs/design/session-control-and-live-eventsRepository: Agenta-AI/agenta
Length of output: 14968
Define the durable deduplication identity mapping.
Specify whether frame_or_event_id, record_id, and event_id are identical, how each identifier is scoped, and which identifier becomes the Postgres key. The current contracts define retry stability but no cross-contract mapping, so ingress deduplication and durable idempotency can diverge.
| Ingress accepts an identical retry and rejects conflicting reuse of an ID or index. It records a | ||
| frame gap. Clients order frames by `(execution_id, frame_index)` and durable events by `sequence`. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🔎 Supported by static analysis
🏁 Script executed:
printf '%s\n' '--- events.md ---'
sed -n '1,125p' docs/design/session-control-and-live-events/contracts/events.md
printf '%s\n' '--- related contract files ---'
find docs/design/session-control-and-live-events -maxdepth 3 -type f -print | sort
printf '%s\n' '--- references to frame_index and execution_id in the design scope ---'
rg -n -C 3 'frame_index|execution_id|sequence|frame_or_event_id' docs/design/session-control-and-live-eventsRepository: Agenta-AI/agenta
Length of output: 50375
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings
Length of output: 10657
🏁 Script executed:
printf '%s\n' '--- architecture execution and live-path sections ---'
sed -n '1,115p' docs/design/session-control-and-live-events/architecture.md
printf '%s\n' '--- requirements and public event contract ---'
sed -n '65,110p' docs/design/session-control-and-live-events/requirements.md
sed -n '113,132p' docs/design/session-control-and-live-events/contracts/public-api.md
printf '%s\n' '--- live envelope and records invariants ---'
sed -n '1,180p' docs/design/session-control-and-live-events/live-frame-envelope.md
sed -n '1,75p' docs/design/session-control-and-live-events/records-invariants.md
printf '%s\n' '--- execution/frame ordering statements outside events.md ---'
rg -n -C 2 'one execution|current execution|late output|stale|frame.*order|order.*frame|frame_index|execution_id' docs/design/session-control-and-live-events --glob '!reviews/**'Repository: Agenta-AI/agenta
Length of output: 50374
🏁 Script executed:
printf '%s\n' '--- stop/recovery rules for stale frames and execution transitions ---'
sed -n '1,180p' docs/design/session-control-and-live-events/work-packages/stop-and-recovery.md
printf '%s\n' '--- decisions around frame ordering and late output ---'
sed -n '115,150p' docs/design/session-control-and-live-events/decisions.md
printf '%s\n' '--- event and client behavior requirements ---'
sed -n '1,90p' docs/design/session-control-and-live-events/contracts/events.md
sed -n '116,130p' docs/design/session-control-and-live-events/contracts/public-api.mdRepository: Agenta-AI/agenta
Length of output: 10652
Define ordering across executions.
frame_index resets for each execution_id, and the contract provides no session-level order for temporary frames. If a session receives frames from multiple executions, (execution_id, frame_index) does not establish their temporal order. Define a per-session live order, or state that clients accept only the current execution and discard stale frames.
| The runner sends frames and events through the existing Redis records ingest stream. The relay | ||
| consumer reads frames. The records worker ignores frames and stores durable events. | ||
|
|
||
| The worker acknowledges an entry only after the analytics Postgres transaction commits. A storage | ||
| failure leaves it pending for retry. One invalid record cannot discard unrelated valid records in | ||
| the same batch. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🔎 Supported by static analysis
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings
Length of output: 9717
🏁 Script executed:
#!/bin/bash
set -eu
file='docs/design/session-control-and-live-events/contracts/persistence.md'
printf '%s\n' '--- target contract ---'
cat -n "$file" | sed -n '1,90p'
printf '%s\n' '--- related session-control/live-events files ---'
git ls-files | rg '(^|/)(session-control-and-live-events|.*session.*control.*|.*live.*event.*)' | sed -n '1,160p'
printf '%s\n' '--- Redis stream and consumer-group references ---'
rg -n -i --glob '!node_modules' --glob '!dist' '(records ingest|ingest stream|consumer group|xgroup|xreadgroup|redis.*stream|stream.*redis|relay consumer|records worker)' . | sed -n '1,240p'Repository: Agenta-AI/agenta
Length of output: 50373
🏁 Script executed:
#!/bin/bash
set -eu
target='docs/design/session-control-and-live-events'
printf '%s\n' '--- persistence contract ---'
cat -n "$target/contracts/persistence.md" | sed -n '1,90p'
printf '%s\n' '--- design files ---'
git ls-files "$target" | sed -n '1,160p'
printf '%s\n' '--- stream-related text in the design ---'
rg -n -i '(redis|stream|consumer|acknowledge|pending|relay|records worker|fan.?out|broadcast)' "$target" | sed -n '1,240p'
printf '%s\n' '--- repository-owned matching implementation/config references, excluding generated/vendor trees ---'
rg -n -i --glob '!**/openapi.json' --glob '!**/openapi.yaml' --glob '!**/package-lock.json' --glob '!**/pnpm-lock.yaml' --glob '!**/yarn.lock' --glob '!**/poetry.lock' --glob '!**/uv.lock' --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/.venv/**' '(records ingest|ingest stream|consumer group|xreadgroup|xgroup|redis.*stream|stream.*redis|records worker|relay consumer)' services api web docs | sed -n '1,260p'Repository: Agenta-AI/agenta
Length of output: 50374
🏁 Script executed:
#!/bin/bash
set -eu
base='docs/design/session-control-and-live-events'
printf '%s\n' '--- architecture stream path ---'
cat -n "$base/architecture.md" | sed -n '38,58p'
printf '%s\n' '--- event routing and retention ---'
cat -n "$base/contracts/events.md" | sed -n '68,88p'
printf '%s\n' '--- decisions on temporary frames ---'
cat -n "$base/decisions.md" | sed -n '128,148p'
printf '%s\n' '--- live relay work package ---'
cat -n "$base/work-packages/live-relay.md" | sed -n '1,75p'
printf '%s\n' '--- records invariants acknowledgement sections ---'
cat -n "$base/records-invariants.md" | sed -n '100,125p'
cat -n "$base/records-invariants.md" | sed -n '190,205p'
printf '%s\n' '--- all explicit group/fan-out/independent-delivery terms in this design ---'
rg -n -i '(consumer group|separate group|independent delivery|fan.?out|broadcast|shared consumer|shared reader|acknowledg)' "$base" | sed -n '1,220p'Repository: Agenta-AI/agenta
Length of output: 19251
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- candidate record worker and stream files ---'
fd -i -t f '(records|stream|relay|watch)' api services | rg -i '(record.*worker|worker.*record|redis.*stream|stream.*redis|relay|watch)' | sed -n '1,180p'
printf '%s\n' '--- record ingest route and worker symbols ---'
rg -n -i --glob '*.py' --glob '!**/openapi*' '(records_worker|append_many|processed_ids|records/ingest|xreadgroup|xack|consumer_group|consumer group|group_name)' api | sed -n '1,240p'Repository: Agenta-AI/agenta
Length of output: 16293
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- records stream wiring ---'
cat -n api/entrypoints/worker_streams.py | sed -n '70,100p'
cat -n api/entrypoints/worker_streams.py | sed -n '155,175p'
printf '%s\n' '--- records worker contract and processing ---'
cat -n api/oss/src/tasks/asyncio/sessions/records_worker.py | sed -n '40,105p'
cat -n api/oss/src/tasks/asyncio/sessions/records_worker.py | sed -n '145,190p'
cat -n api/oss/src/tasks/asyncio/sessions/records_worker.py | sed -n '220,285p'
printf '%s\n' '--- shared Redis consumer read and acknowledgement ---'
cat -n api/oss/src/tasks/asyncio/shared/consumer.py | sed -n '88,160p'Repository: Agenta-AI/agenta
Length of output: 13496
🌐 Web query:
Redis Streams XREADGROUP consumer groups distribute messages within a group and XDEL deletes entries globally official documentation
💡 Result:
Redis Streams provides powerful mechanisms for message distribution and stream management through consumer groups and specific deletion commands. Message Distribution with XREADGROUP When using XREADGROUP, Redis streams enable server-side load balancing of messages to a group of consumers [1][2]. - Distribution: Within a consumer group, messages are distributed among consumers [3][2]. While a specific message has a single owner at any given time, the group tracks which consumer is processing which message [3][4]. - Pending Entries List (PEL): When a consumer reads a message via XREADGROUP, that message is added to the consumer's Pending Entries List (PEL) [3][4][2]. The message remains in the PEL until the consumer explicitly acknowledges it using the XACK command [3][2]. - Message Ownership: If a consumer fails to process a message, other consumers in the group can use XCLAIM or XAUTOCLAIM to take ownership of those pending messages [2]. Message Deletion: XDEL vs. XDELEX The behavior of deleting messages depends on the command used and your Redis version: 1. XDEL (Standard Deletion) - XDEL removes entries from the stream itself [5][6]. - Crucially, XDEL does not clean up references to the deleted message in consumer group PELs [7][8]. If a message was already delivered to a consumer and added to its PEL, it will persist in the PEL even after an XDEL operation until an XACK is issued [7][8]. This can lead to memory growth if not managed [8]. 2. XDELEX (Advanced Deletion, available since Redis 8.2) - To address the limitations of XDEL regarding consumer groups, Redis 8.2 introduced XDELEX [9][10]. - XDELEX provides fine-grained control: - KEEPREF (Default): Functions like XDEL, leaving PEL references intact [9]. - DELREF: Deletes the entries from the stream AND removes all associated references from all consumer group PELs, effectively cleaning up all traces of the messages [9]. - ACKED: Only deletes entries that have already been read and acknowledged by all consumer groups [9]. In summary, while XREADGROUP facilitates distributed consumption, XDEL is a stream-level operation that does not automatically synchronize with consumer group state. For scenarios requiring simultaneous cleanup of stream entries and PEL references, XDELEX is the recommended command in supported versions [9][8][10].
Citations:
- 1: https://groups.google.com/g/redis-db/c/td-aPJKycH0
- 2: https://redis.io/docs/latest/develop/use-cases/streaming/
- 3: https://redis.io/docs/latest/commands/XREADGROUP/
- 4: https://redis.io/docs/latest/commands/xreadgroup/
- 5: https://redis.io/docs/latest/commands/xdel/
- 6: https://redis.io/docs/latest/commands/XDEL/
- 7: https://upstash.com/docs/redis/commands/streams/xdel
- 8: GitHub issue 13314 in redis/redis (link omitted to avoid creating a cross-reference)
- 9: https://redis.io/docs/latest/commands/xdelex/
- 10: https://redis.io/docs/latest/develop/data-types/streams/
Define independent delivery and coordinated deletion for streams:records.
RecordsWorker uses XREADGROUP with worker-records, then calls XACK and XDEL. Redis distributes entries within a consumer group, and XDEL removes entries from the stream for all groups. Define separate consumer groups and a deletion rule that preserves entries until both consumers finish. Specify handling for ignored kinds and mixed frame/event batches.
| Deploy #6496 on main, #6503 on #6496, #6501 on #6503, and #6504 on #6503 after the pure fixes. | ||
| Run control, failure, provider, harness, retry, settlement, and rollback rows in `qa.md`. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
printf '%s\n' '--- plan.md ---'
sed -n '1,110p' docs/design/session-control-and-live-events/plan.md
printf '%s\n' '--- status.md ---'
sed -n '1,180p' docs/design/session-control-and-live-events/status.md
printf '%s\n' '--- durable-approvals.md ---'
sed -n '1,220p' docs/design/session-control-and-live-events/work-packages/durable-approvals.mdRepository: Agenta-AI/agenta
Length of output: 13332
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions
Length of output: 18447
🏁 Script executed:
printf '%s\n' '--- references to `#6504`, approvals, and increment 6 ---'
rg -n -C 3 '`#6504`|increment 6|durable approval|approval|continuation' docs/design/session-control-and-live-events \
-g '*.md' | head -n 260
printf '%s\n' '--- package files ---'
find docs/design/session-control-and-live-events/work-packages -maxdepth 1 -type f -print | sortRepository: Agenta-AI/agenta
Length of output: 34003
Define the approval scope of #6504 before the Stop checkpoint.
#6504 is described as covering “approvals,” while increment 6 separately owns durable answer acceptance and continuation delivery. Distinguish approval cancellation and execution guards from increment-6 behavior. If #6504 includes durable approvals, add the required switch, QA rows, and rollback path.
| ## Dependency to verify early | ||
|
|
||
| Another design review reports that the vendored sandbox-agent cannot cancel an execution while | ||
| preserving the harness session, and that a patch would require a Daytona snapshot rebuild. This | ||
| has not yet been verified in this workspace. It is the first research task for the Stop track. |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- changed hunk ---'
git diff -- docs/design/session-control-and-live-events/research.md
printf '%s\n' '--- research context ---'
sed -n '1,100p' docs/design/session-control-and-live-events/research.md
printf '%s\n' '--- related requirements and review guidance ---'
find . -iname 'requirements.md' -o -iname '*review*standard*' -o -iname '*review*'
printf '%s\n' '--- vendored sandbox-agent references ---'
rg -n -i --glob '!node_modules' --glob '!dist' 'sandbox-agent|warm.?stop|preserv(e|ing).*harness|cancel.*execution|Daytona|snapshot rebuild|continuation' .Repository: Agenta-AI/agenta
Length of output: 50373
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions
Length of output: 24647
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- changed hunk ---'
git diff --no-ext-diff --unified=30 -- docs/design/session-control-and-live-events/research.md
printf '%s\n' '--- research document ---'
sed -n '1,110p' docs/design/session-control-and-live-events/research.md
printf '%s\n' '--- scoped design files ---'
find docs/design/session-control-and-live-events -maxdepth 2 -type f -print
printf '%s\n' '--- requirements and warm-stop claims in scoped docs ---'
rg -n -i 'warm|stop|continu|release|guarantee|sandbox-agent|Daytona|snapshot|harness|cancel' docs/design/session-control-and-live-events docs -g 'requirements.md' -g '*.md'
printf '%s\n' '--- runner sandbox-agent implementation map ---'
find services/runner/src/engines/sandbox_agent services/runner/tests -maxdepth 3 -type f -print 2>/dev/null | head -200
printf '%s\n' '--- runner references ---'
rg -n -i 'warm|stop|continu|cancel|snapshot|harness|sandbox-agent|daytona' services/runner/src/engines/sandbox_agent services/runner/src/engines/sandbox_agent.ts services/runner/tests 2>/dev/nullRepository: Agenta-AI/agenta
Length of output: 50373
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- design scope files ---'
find docs/design/session-control-and-live-events -maxdepth 2 -type f -print | sort
printf '%s\n' '--- exact research excerpt ---'
nl -ba docs/design/session-control-and-live-events/research.md | sed -n '45,70p'
printf '%s\n' '--- scoped design claims ---'
rg -n -i 'warm|stop|continu|release|guarantee|sandbox-agent|Daytona|snapshot|harness|cancel' docs/design/session-control-and-live-events -g '*.md' || true
printf '%s\n' '--- requirements files near the design ---'
find docs/design -iname 'requirements.md' -print | sort
printf '%s\n' '--- sandbox-agent source files ---'
find services/runner/src/engines/sandbox_agent -maxdepth 1 -type f -print | sort
printf '%s\n' '--- directly relevant source matches ---'
rg -n -i 'warm|stop|continu|cancel|snapshot|harness|daytona' \
services/runner/src/engines/sandbox_agent/engine.ts \
services/runner/src/engines/sandbox_agent/run-turn.ts \
services/runner/src/engines/sandbox_agent/session-pool.ts \
services/runner/src/engines/sandbox_agent/acp-http-client.ts \
services/runner/src/engines/sandbox_agent/daemon.ts 2>/dev/null || trueRepository: Agenta-AI/agenta
Length of output: 50373
🏁 Script executed:
#!/bin/bash
set -e
line_range() { awk -v a="$1" -v b="$2" 'NR>=a && NR<=b {printf "%6d %s\n", NR, $0}' "$3"; }
printf '%s\n' '--- research lines 50-65 ---'
line_range 50 65 docs/design/session-control-and-live-events/research.md
printf '%s\n' '--- requirements lines 1-42 ---'
line_range 1 42 docs/design/session-control-and-live-events/requirements.md
printf '%s\n' '--- review standard lines 55-82 and 185-212 ---'
line_range 55 82 docs/design/session-control-and-live-events/review-standard.md
line_range 185 212 docs/design/session-control-and-live-events/review-standard.md
printf '%s\n' '--- status lines 50-90 ---'
line_range 50 90 docs/design/session-control-and-live-events/status.md
printf '%s\n' '--- evidence README ---'
cat docs/design/session-control-and-live-events/evidence/README.md
printf '%s\n' '--- QA warm-stop rows ---'
rg -n -i -C 3 'warm|daytona|codex|cancel|continu' docs/design/session-control-and-live-events/qa.md
printf '%s\n' '--- diff summary and research diff ---'
git diff --stat -- docs/design/session-control-and-live-events
git diff --no-ext-diff --unified=8 -- docs/design/session-control-and-live-events/research.mdRepository: Agenta-AI/agenta
Length of output: 26715
Update this section to match the release evidence.
status.md and qa.md record warm Stop and continuation passes for Daytona. The remaining gaps are the full Codex 1.1.7/1.8.0 comparison, Daytona Codex child cleanup, and the final combined qa.md run. Remove the blanket “not verified” statement and the snapshot-rebuild claim unless they have specific evidence paths.
| A4. Collapse the six milestones to increments in this order: (1) pure fixes #6502 and #6500; | ||
| (2) Stop and recovery behind the flag; (3) history producer plus retention separation, no | ||
| client change; (4) shared reading for secondary readers (relay + sequence + snapshot + | ||
| one reducer, sender stays on invoke); (5) sender on the shared path; (6) durable approvals; | ||
| (7) Queue, then Steer. Merge work-packages/shared-client-reader.md into live-relay.md. | ||
| Split approvals out of queue-steer-approvals.md as the earlier increment. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the rollout count consistent.
A4 says “six milestones” but lists seven increments. This conflicts with the seven-increment structure in README.md and requirements.md. Clarify whether six refers to the former milestone count. Otherwise change it to “seven increments” so implementation order and rollback references use one count.
| ## Part 2: open for Mahmoud (write as Option 1 / Option 2 with recommendation in open-questions.md) | ||
|
|
||
| O1. Sequence home: cursor table on the analytics engine (recommend) vs move records to core. | ||
| O2. Late output: quarantine (Fable, Opus recommend: built, keeps usage and tool result, one | ||
| predicate on reads) vs reject (Codex recommends: fail closed, no second class of rows). | ||
| Code stays quarantine behind the flag until decided. | ||
| O3. Codex child: ship the reap from #6496 now, pin bump 1.1.7 -> 1.8.0 as a separate PR | ||
| (recommend) vs bump first. | ||
| O4. Rollout granularity: global env switch per increment (recommend for version one, simpler) | ||
| vs kill switch plus project allowlist plus capability advertisement (Codex). | ||
| O5. Stop verb: keep /cancel (recommend) vs add /stop. | ||
| O6. Runner stop grace period in the shared compose file (needs a number above 15 s). | ||
| O7. `not_running` vs `lost` past teardown on the `running` key (multi-runner only). |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Synchronize the open-question status with the settled contracts.
The PR objective and the final baseline state that the remaining design questions are settled, but this file still labels O1-O7 open. commands.md still makes the obsolete versus lost behavior depend on O7, while public-api.md already specifies not_running after teardown. Keep one authoritative decision state before implementation branches consume these contracts.
docs/design/session-control-and-live-events/reviews/decision-list-2026-09-03.md#L99-L111: close O1-O7 or record the settled option for each.docs/design/session-control-and-live-events/README.md#L37-L37: keep the reading guide consistent with the authoritative question status.docs/design/session-control-and-live-events/contracts/commands.md#L75-L76: replace the O7-dependent transition with the settled teardown behavior.docs/design/session-control-and-live-events/requirements.md#L151-L152: align package status with the actual decision state.docs/design/session-control-and-live-events/contracts/public-api.md#L85-L86: keep thenot_runningresult consistent with the closed teardown decision.
📍 Affects 5 files
docs/design/session-control-and-live-events/reviews/decision-list-2026-09-03.md#L99-L111(this comment)docs/design/session-control-and-live-events/README.md#L37-L37docs/design/session-control-and-live-events/contracts/commands.md#L75-L76docs/design/session-control-and-live-events/requirements.md#L151-L152docs/design/session-control-and-live-events/contracts/public-api.md#L85-L86
| | 3 | `AGENTA_SESSIONS_HISTORY_WRITES` | Flip off. Nullable fields remain and old record writes stay mounted. | | ||
| | 4 and 5 | `AGENTA_SESSIONS_SHARED_READER` | Flip off. Clients return to invoke or watch-and-refetch. | |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make history rollback preserve sequence semantics.
Flag-off behavior keeps old record writes mounted, but the compatibility contract also requires every post-migration durable write to receive a sequence and disables paths that cannot allocate one. These rules permit incompatible outcomes. If rollback writes null-sequence rows, the snapshot/replay contract can leave new history outside ordered replay. Keep rollback writes sequence-aware, or define null-sequence handling and re-enable behavior explicitly.
Also applies to: 118-119
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Team
Run ID: 31c97950-3931-40d6-a4cd-5e4f81d4b639
📒 Files selected for processing (2)
docs/design/session-control-and-live-events/contracts/events.mddocs/design/session-control-and-live-events/contracts/public-api.md
Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
| not wait for a contiguous sequence. After applying an event, they advance their reconnect cursor to | ||
| the greater of `sequence` and `watermark`. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Use a delivery-safe reconnect cursor rule.
A client can receive sequence 10 with watermark 11, disconnect before sequence 11, and reconnect after 11. That skips event 11. Advance only to the largest delivered event sequence until ready confirms delivery through the watermark.
docs/design/session-control-and-live-events/contracts/events.md#L57-L58: change the durable-event cursor rule.docs/design/session-control-and-live-events/contracts/public-api.md#L138-L139: apply the same rule to public client behavior.
📍 Affects 2 files
docs/design/session-control-and-live-events/contracts/events.md#L57-L58(this comment)docs/design/session-control-and-live-events/contracts/public-api.md#L138-L139
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Team
Run ID: 6da3bb43-e6a4-492e-a258-f0f3f97bb558
📒 Files selected for processing (1)
docs/design/session-control-and-live-events/status.md
Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.
| - Increments 1 to 3 (pure fixes, the Stop package, the history producer) are on PRs #6496, #6503, | ||
| #6501, #6517, #6504, and #6518. A merged head of these lanes runs on an integration stack. The |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Complete the pull request role and base mapping.
Lines 104-105 reference #6517 and #6518. Lines 110-113 reference #6522, #6524, #6531, and #6530. The “Pull request roles and bases” table at Lines 88-100 has no rows for these pull requests. Add each purpose and base, or remove the references until they are recorded. Without this mapping, readers cannot verify the increment dependency order from this status document.
Also applies to: 110-113
mmabrouk
left a comment
mmabrouk
left a comment
There was a problem hiding this comment.
🤖 The AI agent says:
This design establishes durable session control, shared history, and the later Queue/Steer lifecycle.
Focused simplification review using the new simplify skill: one non-blocking suggestion below. This is a static design/code review, not a rerun of the live release gate or a replacement for existing correctness reviews.
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Team
Run ID: 5e891816-5d37-4974-a472-2b20cfd612a4
📒 Files selected for processing (3)
docs/design/session-control-and-live-events/plan.mddocs/design/session-control-and-live-events/status.mddocs/design/session-control-and-live-events/work-packages/queue-steer.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/design/session-control-and-live-events/plan.md
Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
| Mahmoud settled all seven open choices on 2026-09-04. No open design questions remain. | ||
| The product owner settled the warm park duration and continuation message behavior on 2026-09-05. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Keep the decision status and date consistent.
Line 57 says that no design questions remain, but the PR objectives still list open decisions for sequence ownership, late-output handling, post-Stop liveness, retention limits, and final Queue, Steer, approval, and endpoint behavior. Line 58 also records a September 5, 2026 decision as settled, while the current date is September 4, 2026. Keep these decisions open until they are resolved, then record the actual settlement date. This prevents the status from being used as an implementation contract before the RFC is approved.
1 participant
Agenta currently ties live output to the browser that started a turn, delivers Stop through delayed coordination state, keeps queued input in browser memory, and has no replay cursor for another reader.
This draft RFC separates session control from session reading. It defines durable commands, direct Stop delivery through a replaceable runner adapter, warm cancellation, shared temporary live frames, durable replay, and server-held pending input.
Confirmed direction
Open decisions
Evidence and implementation branches
Spikes and code are in #6496 through #6506. The tracking board is https://trello.com/b/O9N0MioN/sesssions. The RFC remains AI-generated, low weight, and unapproved.
How to review
Review round of 2026-09-03
Three reviewers read the RFC head
3a3374df02againstreview-standard.md: a Claude Fable subagent, Codex GPT-5.6 sol at high effort, and a Claude Opus subagent for repository practices and interface design. An Opus QA audit graded every row ofqa.md. The four files sit underreviews/, with the decision list the edit followed. Commit949577a563applies the agreed changes;4d07bdd96dand014e9381c8fix the contradictions a second Opus review found. Everything is agent-generated and low weight.What changed:
/cancelstay; the error envelope fromapi/AGENTS.mdand one error table are incontracts/public-api.md.AGENTA_SESSIONS_DURABLE_STOP,AGENTA_SESSIONS_HISTORY_WRITES,AGENTA_SESSIONS_SHARED_READER, andAGENTA_SESSIONS_LATE_OUTPUT.kindandframe_index; six durable events are frozen with payloads; the rest wait for their package. Measured stream: 10 to 75 frames per second, 63-byte median frame (live-frame-envelope.md).qa.mdhas a proven column (13 proven, 17 partly, 26 not run before tonight) and ten new race and failure rows.Seven decisions wait for Mahmoud in
open-questions.md, each as Option 1 / Option 2 with a recommendation: sequence home, quarantine or reject, Codex reap or pin bump, rollout granularity, Stop verb, runner grace period, andnot_runningversuslost.The plain-English protocol for the night: https://claude.ai/code/artifact/8712db25-719d-45bc-a67b-f47014ab0eb8
https://claude.ai/code/session_01GAqSs7fw6QRi2n1ZJ2tmAV