spec(api-server): add SessionEvent Kind for durable AG-UI event store#1475
Draft
jsell-rh wants to merge 4 commits intoambient-code:mainfrom
Draft
spec(api-server): add SessionEvent Kind for durable AG-UI event store#1475jsell-rh wants to merge 4 commits intoambient-code:mainfrom
jsell-rh wants to merge 4 commits intoambient-code:mainfrom
Conversation
Introduces SessionEvent as the canonical append-only record of all AG-UI protocol events in a session, replacing agui-events.jsonl and the overloaded non-user rows that grpc_push_middleware wrote to session_messages. Key design decisions: - SessionMessage narrowed to runner inbox (user messages only); matches the existing WatchSessionMessages watcher which discards non-user events - SessionEvent stores raw AG-UI JSON verbatim; SSE replay pipes payload directly without transformation (fixes the legacy wrapper format bug) - run_id and thread_id are first-class columns enabling per-run compaction and targeted queries - Compaction: TEXT_MESSAGE_CONTENT rows marked superseded=true after RUN_FINISHED; MESSAGES_SNAPSHOT appended as canonical transcript - /agui-events endpoint with since=<seq> (reconnect) and run_id= filters - grpc_push_middleware must migrate to PushSessionEvent; GRPCMessageWriter is retired Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for cheerful-kitten-f556a0 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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 |
Fix all 8 blockers and 7 majors identified by the 10-agent review:
B1/B7: Add PushSessionEvent proto contract with run_id + thread_id fields
B2: Specify session_events DB migration requirement (table + indexes)
B3: Document AGUIEvents handler migration from ephemeral proxy to DB-backed
B4: Document DeriveAgentStatus() migration path from JSONL to session_events
B5: Fix event type enum — remove nonexistent TOOL_CALL_RESULT, add STEP_*,
STATE_DELTA, ACTIVITY_SNAPSHOT/DELTA, REASONING_MESSAGE_* (5 new types)
B6: Expand compaction scope — supersede all streaming deltas (TEXT_MESSAGE_CONTENT,
TOOL_CALL_ARGS, REASONING_MESSAGE_CONTENT, STATE_DELTA, ACTIVITY_DELTA),
not just TEXT_MESSAGE_CONTENT as previously stated
B8: Correct seq to global BIGSERIAL (not per-session unique); add design decision
M1: Add required indexes: (session_id, seq), (session_id, run_id), replay partial
M2: Define live-tail mechanism (subscribe-before-replay fan-out pattern)
M3: Add retention note and ?limit parameter
M4: Document write throughput guidance (individual inserts ok; batching future)
M5: Add RBAC requirements for GET /agui-events and PushSessionEvent gRPC
M6: Document StreamTextMessages() migration from session_messages to session_events
T1: Fix Overview "Message" bullet to reference SessionEvent
T2: Fix String Tree "SessionMessage is one turn" — add SessionEvent line
T3: Fix Inbox comparison table "Created by" to user-only
Also: document payload encoding bug (model_dump needs by_alias=True),
GRPCMessageWriter retirement, and session_messages narrowing cleanup path.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Resolves all design-level inputs and second-round factual issues: - Fix endpoint path: agui-events → agui/events (slash, sub-resource) - Add TOOL_CALL_RESULT to event_type enum; remove incorrect denial - Add THINKING_* deprecation note (match agui.go, not ag_ui library) - Fix compaction SQL: IS NOT DISTINCT FROM for nullable run_id - Fix live-tail: PostgreSQL LISTEN/NOTIFY replaces in-memory channel (cross-replica fan-out); add 4-step subscribe/replay/drain/live procedure - Fix gRPC auth: service-caller boolean (IsServiceCaller), not RBAC role - Fix run_id/thread_id plumbing: extend grpc_push_middleware signature, remove wrong grpc_transport.py:281-282 attribution - PushSessionEventResponse now returns seq for reconnect cursor - Add explicit CREATE TABLE DDL for session_events with all column types, NOT NULL constraints, DEFAULT FALSE on superseded - Add migration registration guidance (function name, ID format, rollback) - StreamTextMessages: implement+register route from session_events; acpctl session messages migrates to this endpoint - DeriveAgentStatus: event-type-filtered query instead of LIMIT 50; document case-insensitive + non-alpha-strip normalization for AskUserQuestion - GRPCMessageWriter: add _synthesize_run_error dependency; atomic deployment requirement; 7-step implementation checklist including buf generate and Go handler authorship Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
"inbox" is reserved for the Inbox Kind (Agent persistent message queue).
Replace all session_messages-related uses of "inbox" with "delivery queue"
or "runner delivery queue":
- ERD comment: runner inbox → runner delivery queue
- ERD relationship label: "inbox" → "messages"
- Event streams table description
- API reference descriptions for GET/POST /sessions/{id}/messages
- String Tree description of SessionMessage
- Design Decisions table entry
- Section heading: Runner Inbox → Runner Delivery Queue
No Inbox Kind references changed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduces SessionEvent as the canonical append-only record of all AG-UI protocol events in a session, replacing agui-events.jsonl and the overloaded non-user rows that grpc_push_middleware wrote to session_messages.
Key design decisions: