Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.rs
index 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 log
diff --git a/crates/agent_session/src/domain/ports.rs b/crates/agent_session/src/domain/ports.rs
index 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.rs
index 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 @@ where
async 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.rs
index 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.rs
index 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 @@ where
std::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.rs
index 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.rs
index 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: PgPool
let 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.