Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(agent_session): publish log frames to viewers in batches (#6655)
Wolf Mermelstein33cd8b50626e
diff --git a/apps/web/src/features/block-agent/debug/replay/driver.ts b/apps/web/src/features/block-agent/debug/replay/driver.tsindex 70e6070be4..d86f46758f 100644--- a/apps/web/src/features/block-agent/debug/replay/driver.ts+++ b/apps/web/src/features/block-agent/debug/replay/driver.ts@@ -119,7 +119,7 @@ export function createReplayDriver(options: ReplayDriverOptions): ReplayDriver {let timer: ReturnType<typeof setTimeout> | undefined;const emit = (entry: AgentSessionLogEntryDto) => {- AgentSession.ingest({ agentSessionId, ...entry });+ AgentSession.ingest({ agentSessionId, entries: [entry] });};const pause = () => {diff --git a/apps/web/src/lib/core/agent-session/AgentSession.test.ts b/apps/web/src/lib/core/agent-session/AgentSession.test.tsindex a7b304535c..1623abf4dd 100644--- a/apps/web/src/lib/core/agent-session/AgentSession.test.ts+++ b/apps/web/src/lib/core/agent-session/AgentSession.test.ts@@ -105,8 +105,8 @@ describe('AgentSession', () => {harness.getLog.mockReturnValue(log.promise);const live = AgentSession.acquire(SESSION);- AgentSession.ingest({ agentSessionId: SESSION, ...row(2) });- AgentSession.ingest({ agentSessionId: SESSION, ...row(3) });+ AgentSession.ingest({ agentSessionId: SESSION, entries: [row(2)] });+ AgentSession.ingest({ agentSessionId: SESSION, entries: [row(3)] });log.resolve(logOf([row(1), row(2)]));const record = await live.load();@@ -120,7 +120,7 @@ describe('AgentSession', () => {});it('ignores rows for sessions nobody has open', () => {- AgentSession.ingest({ agentSessionId: 'other', ...row(1) });+ AgentSession.ingest({ agentSessionId: 'other', entries: [row(1)] });expect(fold.pushSession).not.toHaveBeenCalled();});@@ -373,7 +373,7 @@ describe('AgentSession', () => {fold.pushSession.mockResolvedValueOnce([{ kind: 'metadata', metadata: { turn: 'running' } },]);- AgentSession.ingest({ agentSessionId: SESSION, ...row(2) });+ AgentSession.ingest({ agentSessionId: SESSION, entries: [row(2)] });await settle();await live.issue({ type: 'prompt', prompt: 'later' });diff --git a/apps/web/src/lib/core/agent-session/AgentSession.ts b/apps/web/src/lib/core/agent-session/AgentSession.tsindex ca10446c9f..289da98647 100644--- a/apps/web/src/lib/core/agent-session/AgentSession.ts+++ b/apps/web/src/lib/core/agent-session/AgentSession.ts@@ -21,10 +21,7 @@ import {type SessionFoldSnapshot,} from '@core/agent-fold/client';import { subscribeSocketSessionStarted } from '@queries/agent-session/queue-sync';-import {- type AgentSessionLogEvent,- entryOf,-} from '@queries/agent-session/realtime-protocol';+import type { AgentSessionLogEvent } from '@queries/agent-session/realtime-protocol';import type {FoldedStreamEvent,TurnState,@@ -81,14 +78,15 @@ export class AgentSession {}/**- * Realtime ingress: one persisted row, addressed by session. The socket- * dispatch and the replay driver both call this; a session nobody has open- * ignores it.+ * Realtime ingress: a run of persisted rows in log order, addressed by+ * session. The socket dispatch and the replay driver both call this; a+ * session nobody has open ignores it. The run reaches the machine as one+ * push, so a flush of many frames costs one worker round trip.*/static ingest(event: AgentSessionLogEvent): void {AgentSession.open.get(event.agentSessionId)- ?.enqueue({ kind: 'confirmed', row: entryOf(event) });+ ?.enqueueAll(event.entries.map((row) => ({ kind: 'confirmed', row })));}readonly id: string;@@ -340,11 +338,16 @@ export class AgentSession {}private enqueue(input: FoldInput): Promise<void> {+ return this.enqueueAll([input]);+ }++ private enqueueAll(inputs: FoldInput[]): Promise<void> {+ if (inputs.length === 0) return Promise.resolve();if (!this.ready) {- this.buffered.push(input);+ this.buffered.push(...inputs);return Promise.resolve();}- return this.apply([input]);+ return this.apply(inputs);}private apply(inputs: FoldInput[]): Promise<void> {diff --git a/apps/web/src/lib/queries/agent-session/realtime-protocol.ts b/apps/web/src/lib/queries/agent-session/realtime-protocol.tsindex bd0bc98d7f..d56a1f9ee6 100644--- a/apps/web/src/lib/queries/agent-session/realtime-protocol.ts+++ b/apps/web/src/lib/queries/agent-session/realtime-protocol.ts@@ -1,4 +1,7 @@-/** The Connection Gateway event type for one appended agent-session frame. */+/**+ * The Connection Gateway event type for a run of appended agent-session+ * frames - everything the harness flushed to the log at once.+ */export const AGENT_SESSION_LOG_EVENT = 'agent_session_log';/** The Connection Gateway event type for a persisted session-name change. */@@ -16,14 +19,17 @@ import type {} from '@service-agent-harness/generated/schemas';/**- * One persisted log entry, addressed by session for realtime delivery.+ * A run of persisted log entries, in log order, addressed by session for+ * realtime delivery. Each entry is the exact row `GET /agent-sessions/{id}/log`+ * serves, so the socket and the fetched log fold through one code path.** This mirrors `AgentSessionLogEvent` in* `crates/agent_session/src/outbound/connection_gateway_realtime.rs`.*/export type AgentSessionLogEvent = {agentSessionId: string;-} & AgentSessionLogEntryDto;+ entries: AgentSessionLogEntryDto[];+};/** Mirrors `AgentSessionRenamedEvent` in the backend realtime adapter. */export type AgentSessionRenamedEvent = {@@ -45,12 +51,6 @@ export type AgentSessionQueueEvent = {entries: QueuedActionDto[];};-/** Remove the realtime address, leaving the exact persisted entry shape. */-export function entryOf(event: AgentSessionLogEvent): AgentSessionLogEntryDto {- const { agentSessionId: _agentSessionId, ...entry } = event;- return entry;-}-/** A persisted session changed; consumers reload its current metadata. */export const AGENT_SESSION_UPDATED_EVENT = 'agent_session_updated';export type AgentSessionUpdatedEvent = { agentSessionId: string };diff --git a/crates/agent_session/src/domain/model.rs b/crates/agent_session/src/domain/model.rsindex 4bfe5da605..ee15bcc6c8 100644--- a/crates/agent_session/src/domain/model.rs+++ b/crates/agent_session/src/domain/model.rs@@ -367,22 +367,28 @@ impl From<super::ports::QueuedControl> for QueuedActionDto {}}-/// One frame appended to a live session's log, for anyone watching.+/// A run of frames appended to a live session's log, for anyone watching.////// The streaming counterpart of [`SessionLog`]: that is the selected history window-/// for a reader arriving late, this is one frame for a reader already here.-/// Both carry the same entry shape, so a client folds them the same way --/// catching up on the log and then following it is one fold, not two.+/// for a reader arriving late, this is the frames a reader already here has+/// not seen yet. Both carry the same entry shape, so a client folds them the+/// same way - catching up on the log and then following it is one fold, not+/// two.+///+/// A batch rather than a frame because the writer flushes frames in runs+/// (see `LiveSessionLogWriter`), and every run costs one publish however+/// many frames it holds. `entries` are in log order and never empty.////// Addressed by session: it is the only thing a frame belongs to now that a/// session does not own a channel.#[derive(Debug, Clone)]pub struct LogAppended {- /// The session the entry belongs to. The fold keys its messages on this,+ /// The session the entries belong to. The fold keys its messages on this,/// so a client must pass it through unchanged.pub agent_session_id: AgentSessionId,- /// The frame and the timestamp assigned when it was stored.- pub entry: StoredAgentSessionLog,+ /// The frames and the timestamps assigned when they were stored, in the+ /// order the log holds them.+ pub entries: Vec<StoredAgentSessionLog>,}/// One entry of a session's log as it was stored, with the time the logdiff --git a/crates/agent_session/src/domain/ports.rs b/crates/agent_session/src/domain/ports.rsindex 476ff257e9..0904849ee8 100644--- a/crates/agent_session/src/domain/ports.rs+++ b/crates/agent_session/src/domain/ports.rs@@ -625,6 +625,11 @@ pub struct Appended {}/// Sequential live log writer owned by one session actor.+///+/// A writer may hold the *publishing* of appended frames back and push them+/// to viewers in runs; the durable append itself is never deferred.+/// [`flush_deadline`](Self::flush_deadline) tells the owning actor when the+/// held frames must next be pushed out with [`flush`](Self::flush).pub trait AgentSessionLogWriter: Send + 'static {/// Persist and fold one frame into this connection's live projection.fn append(&mut self, log: AgentSessionLog) -> impl Future<Output = Result<Appended>> + Send {@@ -639,6 +644,18 @@ pub trait AgentSessionLogWriter: Send + 'static {log: AgentSessionLog,boundary: Option<HistoryBoundary>,) -> impl Future<Output = Result<Appended>> + Send;++ /// Push any frames still held back to the session's viewers. A writer+ /// that holds nothing back has nothing to do.+ fn flush(&mut self) -> impl Future<Output = Result<()>> + Send {+ async { Ok(()) }+ }++ /// When held frames must be flushed by - `None` while nothing is held,+ /// so an idle writer never wakes its owner.+ fn flush_deadline(&self) -> Option<tokio::time::Instant> {+ None+ }}/// A session's queue changed; this is the whole queue as it stands now.@@ -663,7 +680,7 @@ pub struct AgentSessionQueueChanged {/// they reload, and the log it was derived from is already durable - so an/// implementation may drop, and callers must not fail an append over it.pub trait AgentSessionRealtime {- /// Publish one appended frame to the session's viewers.+ /// Publish a run of appended frames to the session's viewers.fn publish(&self,event: LogAppended,diff --git a/crates/agent_session/src/domain/service.rs b/crates/agent_session/src/domain/service.rsindex 6ef880cee9..5264e82746 100644--- a/crates/agent_session/src/domain/service.rs+++ b/crates/agent_session/src/domain/service.rs@@ -1089,9 +1089,26 @@ fn validate_agent_session_name(raw: &str) -> Result<&str> {Ok(name)}+/// How long a stored frame may wait before it is pushed to viewers. The+/// latency a viewer sees on streamed output; durability is never deferred.+const LOG_FLUSH_INTERVAL: std::time::Duration = std::time::Duration::from_millis(1500);+/// How many stored frames may accumulate before they are pushed regardless+/// of age, bounding the size of one publish.+const MAX_PENDING_LOG_FRAMES: usize = 256;+/// The [`AgentSessionLogRepo`] a session's actor writes through: the durable/// append, then the push to whoever is watching the session right now.///+/// The push is batched. Every frame is stored at once, as before, but+/// streamed output - the overwhelming bulk of a live session's frames, and+/// the whole of a `session/load` replay - is pushed to viewers+/// [`MAX_PENDING_LOG_FRAMES`] at a time or every [`LOG_FLUSH_INTERVAL`],+/// whichever comes first, as one publish, instead of costing an audience+/// lookup and a gateway round trip each. Frames the rest of the system+/// reacts to right away - anything headed to the runtime, and system events,+/// which move the composer's idea of whether the agent is working - push+/// everything pending through with themselves before `append` returns.+////// This is also where a writer's fold lives, and the fold is what makes/// re-attaching correct: [`TurnId`](agent_fold::domain::model::TurnId)s are a/// counter over the log, so a connection has to know how far along the session@@ -1116,6 +1133,21 @@ pub struct LiveSessionLogWriter<R, Rt> {/// default reported by session/new replaces it even when selection fails.initial_model: Option<String>,initial_model_request: Option<RequestId>,+ /// Stored frames not yet pushed to viewers, in log order.+ pending: Vec<StoredAgentSessionLog>,+ /// When the oldest pending frame must be pushed by; `None` while nothing+ /// is pending, so an idle writer never wakes its actor.+ flush_due: Option<tokio::time::Instant>,+}++/// Frames viewers must see as soon as they are stored rather than with the+/// next batch: anything the runtime will act on, and anything that projects+/// onto the session's status.+fn flushes_through(content: &Message) -> bool {+ matches!(+ content,+ Message::ToRuntime(_) | Message::ToServer(ToServerMessage::Event { .. })+ )}impl<R, Rt> LiveSessionLogWriter<R, Rt> {@@ -1133,6 +1165,8 @@ impl<R, Rt> LiveSessionLogWriter<R, Rt> {claim: None,initial_model: None,initial_model_request: None,+ pending: Vec::new(),+ flush_due: None,}}@@ -1146,6 +1180,8 @@ impl<R, Rt> LiveSessionLogWriter<R, Rt> {claim: Some(claim),initial_model: None,initial_model_request: None,+ pending: Vec::new(),+ flush_due: None,}}@@ -1257,18 +1293,41 @@ where);}- // Best-effort once the durable append has succeeded: the port drops- // frames by contract, and the log this was derived from is already- // durable, so the worst a failure costs is a viewer who has to reload.+ // Durable already; the push to viewers waits for the batch unless+ // this frame is one they must see now.let log_id = stored.id;- if let Err(error) = self.stream(session, stored).await {+ let flush_now = flushes_through(&stored.entry.content);+ self.pending.push(stored);+ self.flush_due+ .get_or_insert_with(|| tokio::time::Instant::now() + LOG_FLUSH_INTERVAL);+ if flush_now || self.pending.len() >= MAX_PENDING_LOG_FRAMES {+ AgentSessionLogWriter::flush(self).await?;+ }+ Ok(Appended { log_id, signals })+ }++ async fn flush(&mut self) -> Result<()> {+ if self.pending.is_empty() {+ return Ok(());+ }+ let entries = std::mem::take(&mut self.pending);+ self.flush_due = None;+ let session = entries[0].entry.agent_session_id;+ // Best-effort: the port drops frames by contract, and every frame+ // here is already durable, so the worst a failure costs is a viewer+ // who has to reload.+ if let Err(error) = self.stream(session, entries).await {tracing::error!(error = ?error,%session,- "failed to stream agent session frame"+ "failed to stream agent session frames");}- Ok(Appended { log_id, signals })+ Ok(())+ }++ fn flush_deadline(&self) -> Option<tokio::time::Instant> {+ self.flush_due}}@@ -1386,16 +1445,17 @@ where{/// Push the frame just appended out to whoever is watching the session.///- /// The frame's kind rides along because this span is the only per-frame- /// signal a session emits: a status event here is what moves the- /// composer's whole notion of whether the agent is working, and without- /// naming it "a frame was published" answers nothing.+ /// The last frame's kind rides along because this span is the only+ /// per-flush signal a session emits: a status event here is what moves+ /// the composer's whole notion of whether the agent is working, and+ /// without naming it "frames were published" answers nothing.#[tracing::instrument(name = "agent.session.realtime.publish",err,- skip(self, agent_session_id, entry),+ skip(self, agent_session_id, entries),fields(agent.session.id = %agent_session_id,+ agent.log.frame_count = entries.len(),agent.log.frame_kind = tracing::field::Empty,agent.log.event = tracing::field::Empty,)@@ -1403,18 +1463,20 @@ whereasync fn stream(&mut self,agent_session_id: AgentSessionId,- entry: StoredAgentSessionLog,+ entries: Vec<StoredAgentSessionLog>,) -> std::result::Result<(), rootcause::Report> {let span = tracing::Span::current();- let (frame_kind, event) = frame_telemetry(&entry.entry.content);- span.record("agent.log.frame_kind", frame_kind);- if let Some(event) = event {- span.record("agent.log.event", event);+ if let Some(last) = entries.last() {+ let (frame_kind, event) = frame_telemetry(&last.entry.content);+ span.record("agent.log.frame_kind", frame_kind);+ if let Some(event) = event {+ span.record("agent.log.event", event);+ }}self.realtime.publish(LogAppended {agent_session_id,- entry,+ entries,}).await}diff --git a/crates/agent_session/src/domain/service/test.rs b/crates/agent_session/src/domain/service/test.rsindex 8767899547..69fbbcbd62 100644--- a/crates/agent_session/src/domain/service/test.rs+++ b/crates/agent_session/src/domain/service/test.rs@@ -1259,21 +1259,32 @@ async fn a_connections_frames_are_published_to_its_channel() {.expect("append succeeds");}+ AgentSessionLogWriter::flush(&mut logs)+ .await+ .expect("flush succeeds");let published = realtime.published();- assert_eq!(published.len(), log.len(), "one event per frame, no more");assert!(published.iter().all(|event| event.agent_session_id == test_session()),"every event names the session");+ let published: Vec<StoredAgentSessionLog> = published+ .into_iter()+ .flat_map(|event| event.entries)+ .collect();+ assert_eq!(+ published.len(),+ log.len(),+ "every frame goes out exactly once"+ );let stored = AgentSessionLogRepo::list_by_session(&repo, test_session()).await.expect("stored log can be read");assert_eq!(published.iter()- .map(|event| event.entry.created_at)+ .map(|event| event.created_at).collect::<Vec<_>>(),stored.iter()@@ -1292,7 +1303,7 @@ async fn a_connections_frames_are_published_to_its_channel() {assert_eq!(published.into_iter()- .map(|event| frame(event.entry.entry))+ .map(|event| frame(event.entry)).collect::<Vec<_>>(),log.into_iter().map(frame).collect::<Vec<_>>(),"the frames go out as they were logged"@@ -1955,3 +1966,165 @@ mod fold_signals {assert!(appended.signals.is_empty(), "{:#?}", appended.signals);}}++// Batching: streamed output is stored at once but pushed to viewers in runs+// - one publish per flush - while anything they must see now goes through+// immediately.++/// A streamed ACP notification: the frame kind that is the bulk of every+/// session and the whole of a `session/load` replay.+fn streamed_frame(text: &str) -> AgentSessionLog {+ AgentSessionLog {+ agent_session_id: test_session(),+ user_id: None,+ content: Message::ToServer(ToServerMessage::Acp(AcpMessage(+ agent_client_protocol::RawJsonRpcMessage::notification(+ "session/update".to_owned(),+ serde_json::json!({+ "sessionId": "acp-1",+ "update": {+ "sessionUpdate": "agent_thought_chunk",+ "content": { "type": "text", "text": text }+ }+ }),+ )+ .unwrap(),+ ))),+ }+}++/// Streamed frames are durable at once but published only on flush, all+/// together, in log order, as one event.+#[tokio::test]+async fn streamed_frames_are_stored_at_once_and_published_on_flush() {+ let repo = InMemoryAgentSessionRepo::new();+ repo.insert_session(test_agent_session(test_session()));+ let realtime = RecordingRealtime::new();+ let mut logs = streaming_connection(repo.clone(), realtime.clone());++ let mut appended = Vec::new();+ for text in ["one", "two", "three"] {+ appended.push(+ AgentSessionLogWriter::append(&mut logs, streamed_frame(text))+ .await+ .expect("append succeeds")+ .log_id,+ );+ }++ let stored = AgentSessionLogRepo::list_by_session(&repo, test_session())+ .await+ .unwrap();+ assert_eq!(+ stored.iter().map(|row| row.id).collect::<Vec<_>>(),+ appended,+ "every frame is durable before its append returns"+ );+ assert!(+ realtime.published().is_empty(),+ "nothing is published before the flush"+ );+ assert!(+ logs.flush_deadline().is_some(),+ "a pending frame gives the actor a deadline to flush by"+ );++ AgentSessionLogWriter::flush(&mut logs)+ .await+ .expect("flush succeeds");++ let published = realtime.published();+ assert_eq!(published.len(), 1, "one flush is one publish");+ assert_eq!(+ published[0]+ .entries+ .iter()+ .map(|row| row.id)+ .collect::<Vec<_>>(),+ appended,+ "the publish carries the stored frames in log order"+ );+ assert!(+ logs.flush_deadline().is_none(),+ "nothing pending needs no wake-up"+ );+}++/// A frame headed to the runtime pushes everything pending through with+/// itself, so a viewer never sees a prompt before the output it followed.+#[tokio::test]+async fn frames_headed_to_the_runtime_flush_pending_frames_through() {+ let repo = InMemoryAgentSessionRepo::new();+ repo.insert_session(test_agent_session(test_session()));+ let realtime = RecordingRealtime::new();+ let mut logs = streaming_connection(repo.clone(), realtime.clone());++ AgentSessionLogWriter::append(&mut logs, streamed_frame("pending"))+ .await+ .unwrap();+ let prompt = parse_log_as(test_session(), TURN)+ .into_iter()+ .find(|entry| matches!(entry.content, Message::ToRuntime(_)))+ .expect("the fixture turn prompts the runtime");+ let prompt_id = AgentSessionLogWriter::append(&mut logs, prompt)+ .await+ .unwrap()+ .log_id;++ let published = realtime.published();+ assert_eq!(published.len(), 1, "flushed through as one publish");+ assert_eq!(published[0].entries.len(), 2);+ assert_eq!(published[0].entries[1].id, prompt_id);+ assert!(logs.flush_deadline().is_none());+}++/// System events move the composer's idea of whether the agent is working,+/// so they go out at once, with whatever was pending ahead of them.+#[tokio::test]+async fn system_events_flush_pending_frames_through() {+ let repo = InMemoryAgentSessionRepo::new();+ repo.insert_session(test_agent_session(test_session()));+ let realtime = RecordingRealtime::new();+ let mut logs = streaming_connection(repo.clone(), realtime.clone());++ AgentSessionLogWriter::append(&mut logs, streamed_frame("pending"))+ .await+ .unwrap();+ AgentSessionLogWriter::append(+ &mut logs,+ AgentSessionLog {+ agent_session_id: test_session(),+ user_id: None,+ content: Message::ToServer(ToServerMessage::Event {+ event: SystemEvent::AcpReady,+ }),+ },+ )+ .await+ .unwrap();++ let published = realtime.published();+ assert_eq!(published.len(), 1);+ assert_eq!(published[0].entries.len(), 2);+ assert!(logs.flush_deadline().is_none());+}++/// Enough pending frames flush themselves, bounding one publish.+#[tokio::test]+async fn a_full_pending_run_flushes_itself() {+ let repo = InMemoryAgentSessionRepo::new();+ repo.insert_session(test_agent_session(test_session()));+ let realtime = RecordingRealtime::new();+ let mut logs = streaming_connection(repo.clone(), realtime.clone());++ for index in 0..MAX_PENDING_LOG_FRAMES {+ AgentSessionLogWriter::append(&mut logs, streamed_frame(&index.to_string()))+ .await+ .unwrap();+ }++ let published = realtime.published();+ assert_eq!(published.len(), 1);+ assert_eq!(published[0].entries.len(), MAX_PENDING_LOG_FRAMES);+ assert!(logs.flush_deadline().is_none());+}diff --git a/crates/agent_session/src/domain/session/actors.rs b/crates/agent_session/src/domain/session/actors.rsindex 8cf5a1ea9b..a37dbfb938 100644--- a/crates/agent_session/src/domain/session/actors.rs+++ b/crates/agent_session/src/domain/session/actors.rs@@ -211,8 +211,29 @@ wherestd::future::pending::<()>().await;}};+ let log_flush_deadline = self.logs.flush_deadline();+ let log_flush_due = async {+ match log_flush_deadline {+ Some(deadline) => tokio::time::sleep_until(deadline).await,+ None => std::future::pending().await,+ }+ };let input = tokio::select! {() = handshake_timeout => Input::Closed(CloseReason::HandshakeTimedOut),+ // Buffered log frames have waited long enough; write them out. A+ // failed flush is a failed log write, and the machine decides+ // what that means, same as a failed append.+ () = log_flush_due => match self.logs.flush().await {+ Ok(()) => continue,+ Err(error) => {+ tracing::error!(+ error = ?error,+ id = %self.machine.id(),+ "agent session failed to flush buffered log frames"+ );+ Input::Closed(CloseReason::LogFailed)+ }+ },command = self.commands.recv() => match command {Some(SessionCommand { user_id, action, action_id, completed, span, enqueued_at }) => {span.record(diff --git a/crates/agent_session/src/outbound/connection_gateway_realtime.rs b/crates/agent_session/src/outbound/connection_gateway_realtime.rsindex cb0c44aa37..4bcb94223e 100644--- a/crates/agent_session/src/outbound/connection_gateway_realtime.rs+++ b/crates/agent_session/src/outbound/connection_gateway_realtime.rs@@ -10,23 +10,30 @@//! agreement.//!//! Messages go out as type [`AGENT_SESSION_LOG`] with a-//! [`AgentSessionLogEvent`] body:+//! [`AgentSessionLogEvent`] body: the session, and the run of frames the+//! writer just flushed, in log order.//!//! ```json//! {//! "agentSessionId": "019f…",-//! "createdAt": "2026-08-13T12:34:56.789Z",-//! "userId": "macro|[email protected]",-//! "direction": "to_server",-//! "content": { "type": "acp", "jsonrpc": "2.0", … }+//! "entries": [+//! {+//! "id": "019f…",+//! "createdAt": "2026-08-13T12:34:56.789Z",+//! "userId": "macro|[email protected]",+//! "direction": "to_server",+//! "content": { "type": "acp", "jsonrpc": "2.0", … }+//! }+//! ]//! }//! ```//!-//! The last four fields are exactly the entry shape-//! `GET /agent-sessions/{id}/log` serves, flattened in the same way. That is-//! the point of the contract rather than an accident of it: a client catching-//! up on a log and a client following one are folding the same bytes, so they-//! can share one fold and cannot disagree about what a frame means.+//! Each entry is exactly the entry shape `GET /agent-sessions/{id}/log`+//! serves, flattened in the same way. That is the point of the contract+//! rather than an accident of it: a client catching up on a log and a client+//! following one are folding the same bytes, so they can share one fold and+//! cannot disagree about what a frame means. A batch rather than a frame+//! because the writer publishes once per flush, however many frames that is.//!//! `agentSessionId` both addresses the frame and is what the fold keys its//! messages on, so it must be passed through unchanged: a message is@@ -45,7 +52,7 @@ use model_entity::EntityType as GatewayEntityType;use serde::Serialize;use std::sync::Arc;-/// The realtime message type carrying one appended log frame.+/// The realtime message type carrying a run of appended log frames.////// Matched on by the web client's websocket dispatch; changing it breaks/// streaming silently, since an unrecognized type is ignored rather than@@ -72,12 +79,19 @@ pub const AGENT_SESSION_CHANGES: &str = "agent_session_changes";/// contract.#[derive(Debug, Serialize)]pub struct AgentSessionLogEvent {- /// Durable row identity, matching the GET log entry and breaking timestamp ties.- pub id: Uuid,- /// The session the frame belongs to, and half of the composite id its+ /// The session the frames belong to, and half of the composite id their/// folded messages are keyed by.#[serde(rename = "agentSessionId")]pub agent_session_id: Uuid,+ /// The flushed frames, in log order. Never empty.+ pub entries: Vec<AgentSessionLogEventEntry>,+}++/// One frame of an [`AgentSessionLogEvent`]: the GET log entry shape.+#[derive(Debug, Serialize)]+pub struct AgentSessionLogEventEntry {+ /// Durable row identity, matching the GET log entry and breaking timestamp ties.+ pub id: Uuid,/// When the durable log recorded the frame.#[serde(rename = "createdAt")]pub created_at: chrono::DateTime<chrono::Utc>,@@ -143,23 +157,30 @@ impl From<AgentSessionQueueChanged> for AgentSessionQueueEvent {}impl AgentSessionLogEvent {- /// The event for one appended frame.+ /// The event for one flushed run of frames.#[must_use]pub fn new(event: LogAppended) -> Self {- let StoredAgentSessionLog {- id,- created_at,- entry: AgentSessionLog {- user_id, content, ..- },- } = event.entry;-Self {- id,agent_session_id: event.agent_session_id.as_uuid(),- created_at,- user_id: user_id.map(|user| user.to_string()),- message: content,+ entries: event+ .entries+ .into_iter()+ .map(+ |StoredAgentSessionLog {+ id,+ created_at,+ entry:+ AgentSessionLog {+ user_id, content, ..+ },+ }| AgentSessionLogEventEntry {+ id,+ created_at,+ user_id: user_id.map(|user| user.to_string()),+ message: content,+ },+ )+ .collect(),}}}diff --git a/crates/agent_session/src/outbound/postgres/test.rs b/crates/agent_session/src/outbound/postgres/test.rsindex f41661d595..2d61f6d454 100644--- a/crates/agent_session/src/outbound/postgres/test.rs+++ b/crates/agent_session/src/outbound/postgres/test.rs@@ -1871,14 +1871,14 @@ async fn history_boundary_range_uses_order_index_and_uuid_tie_break(pool: PgPoollet event = crate::outbound::connection_gateway_realtime::AgentSessionLogEvent::new(crate::domain::model::LogAppended {agent_session_id: session.id,- entry: stored.clone(),+ entries: vec![stored.clone()],},);let dto = serde_json::to_value(dto).unwrap();let event = serde_json::to_value(event).unwrap();assert_eq!(dto["id"], stored.id.to_string());- assert_eq!(dto["id"], event["id"]);- assert_eq!(dto["createdAt"], event["createdAt"]);+ assert_eq!(dto["id"], event["entries"][0]["id"]);+ assert_eq!(dto["createdAt"], event["entries"][0]["createdAt"]);}// Explain the production query itself so this check cannot drift from the reader.