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): write streamed log frames in batches (#6658)

Wolf Mermelstein4cad2bf4010f
diff --git a/.sqlx/query-b1ac4ab49729df68d741d817512bb66ad26d937554466326bb17dbf661a4fa1f.json b/.sqlx/query-b1ac4ab49729df68d741d817512bb66ad26d937554466326bb17dbf661a4fa1f.json
new file mode 100644
index 0000000000..8ac0422148
--- /dev/null
+++ b/.sqlx/query-b1ac4ab49729df68d741d817512bb66ad26d937554466326bb17dbf661a4fa1f.json
@@ -0,0 +1,32 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n INSERT INTO agent_session_log (id, agent_session_id, user_id, direction, content, created_at)\n SELECT frame.id, $1, frame.user_id, frame.direction, frame.content,\n now() + (frame.ordinality - 1) * interval '1 microsecond'\n FROM UNNEST($2::uuid[], $3::text[], $4::text[], $5::jsonb[])\n WITH ORDINALITY AS frame(id, user_id, direction, content, ordinality)\n RETURNING id, created_at\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 1,
+ "name": "created_at",
+ "type_info": "Timestamptz"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Uuid",
+ "UuidArray",
+ "TextArray",
+ "TextArray",
+ "JsonbArray"
+ ]
+ },
+ "nullable": [
+ false,
+ false
+ ]
+ },
+ "hash": "b1ac4ab49729df68d741d817512bb66ad26d937554466326bb17dbf661a4fa1f"
+}
diff --git a/crates/agent_session/src/domain/model.rs b/crates/agent_session/src/domain/model.rs
index ee15bcc6c8..5bc0487e1b 100644
--- a/crates/agent_session/src/domain/model.rs
+++ b/crates/agent_session/src/domain/model.rs
@@ -1,5 +1,5 @@
use agent_client_protocol::schema::v1::SessionId;
-use agent_runtime_protocol::domain::schema::v0::SystemEvent;
+use agent_runtime_protocol::domain::schema::v0::{AcpMessage, SystemEvent, ToServerMessage};
use bots::domain::models::BotId;
use chrono::{DateTime, Utc};
use macro_user_id::user_id::MacroUserIdStr;
@@ -367,6 +367,35 @@ impl From<super::ports::QueuedControl> for QueuedActionDto {
}
}
+/// The Cursor run a frame checkpoints, if it is the adapter's empty
+/// `agent_message_chunk` carrying `_meta.macroCursorRunCheckpoint`.
+///
+/// A domain fact rather than a persistence detail: the store projects it
+/// onto `external_agent_session.last_run_id`, and the live writer must know
+/// it to keep such a frame out of a plain batch, so both read one function.
+#[must_use]
+pub fn cursor_run_checkpoint(message: &Message) -> Option<String> {
+ let Message::ToServer(ToServerMessage::Acp(AcpMessage(frame))) = message else {
+ return None;
+ };
+ let value = serde_json::to_value(frame).ok()?;
+ if value.get("method")?.as_str()? != "session/update" {
+ return None;
+ }
+ let params = value.get("params")?;
+ let update = params.get("update")?;
+ if update.get("sessionUpdate")?.as_str()? != "agent_message_chunk"
+ || !update.get("content")?.get("text")?.as_str()?.is_empty()
+ {
+ return None;
+ }
+ params
+ .get("_meta")?
+ .get("macroCursorRunCheckpoint")?
+ .as_str()
+ .map(str::to_owned)
+}
+
/// 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
diff --git a/crates/agent_session/src/domain/ports.rs b/crates/agent_session/src/domain/ports.rs
index 0904849ee8..58be877e1f 100644
--- a/crates/agent_session/src/domain/ports.rs
+++ b/crates/agent_session/src/domain/ports.rs
@@ -538,6 +538,26 @@ pub trait AgentSessionLogRepo: Send + Sync + 'static {
boundary: Option<HistoryBoundary>,
) -> impl Future<Output = Result<StoredAgentSessionLog>> + Send;
+ /// Append a run of plain frames in one write, under the current
+ /// ownership fence, and return them stamped as the log stored them.
+ ///
+ /// Plain means: nothing the store projects - no system event, no load
+ /// boundary, no Cursor checkpoint. Those keep going through
+ /// [`create_fenced_with_boundary`](Self::create_fenced_with_boundary)
+ /// one at a time; this is the fast path for the streamed output that is
+ /// the bulk of every session. Entries carry their ids already - the
+ /// writer hands them out at append time so a caller has a durable
+ /// identity before the flush lands - and arrive in append order, which
+ /// the store must preserve in `(created_at, id)` order for readers.
+ ///
+ /// Every entry must belong to `claim`'s session. An empty batch is a
+ /// no-op.
+ fn create_batch_fenced(
+ &self,
+ entries: Vec<StoredAgentSessionLog>,
+ claim: &SessionClaim,
+ ) -> impl Future<Output = Result<Vec<StoredAgentSessionLog>>> + Send;
+
/// List effective ACP history in deterministic `(created_at, id)` order.
/// Starts at the latest successfully loaded initialization, or the beginning.
/// Raw failed/partial replay frames remain; consumers must stage load attempts.
@@ -626,10 +646,10 @@ 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).
+/// A writer may hold streamed frames back and both write and publish them in
+/// runs: `append` returning `Ok` means the frame is durable *or buffered*,
+/// and [`flush_deadline`](Self::flush_deadline) tells the owning actor when
+/// the buffer must next be forced 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 {
@@ -645,8 +665,9 @@ pub trait AgentSessionLogWriter: Send + 'static {
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.
+ /// Durably write any frames still held back, then push everything
+ /// stored but unpublished 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(()) }
}
diff --git a/crates/agent_session/src/domain/service.rs b/crates/agent_session/src/domain/service.rs
index 5264e82746..e7bbefa80b 100644
--- a/crates/agent_session/src/domain/service.rs
+++ b/crates/agent_session/src/domain/service.rs
@@ -32,7 +32,6 @@ use agent_client_protocol::schema::v1::{
RequestId, Response, SessionId, SetSessionConfigOptionResponse,
};
use agent_fold::domain::lifecycle::LifecycleFold;
-use agent_fold::domain::model::TurnSignal;
use agent_fold::domain::model_selection::model_selection;
use agent_fold::domain::ports::FoldedMessageRepo;
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId, AgentSetModelAction};
@@ -60,6 +59,7 @@ use super::model::{
AuthorKind, ClaimOutcome, CreateAgentSessionParams, LogAppended, MAX_AGENT_SESSION_NAME_CHARS,
MAX_PREVIEW_SESSION_IDS, Message, MessageId, ReplicaId, SandboxSize, SessionClaim, SessionLog,
SessionManagement, SessionPreviewCandidate, StoredAgentSessionLog, ThreadSession,
+ cursor_run_checkpoint,
};
use super::ports::{
AgentConnector, AgentSessionLifecyclePublisher, AgentSessionLogRepo, AgentSessionLogWriter,
@@ -1089,25 +1089,31 @@ 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.
+/// How long a streamed frame may sit buffered before it must be written and
+/// pushed to viewers. The crash window - a process dying loses at most this
+/// much of the *tail* of a session's streamed output; flushes happen in
+/// append order, so a lost suffix never punches a hole in the middle - and
+/// the latency a viewer sees on streamed output.
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.
+/// How many frames may accumulate before a flush happens regardless of age,
+/// bounding memory, the size of one insert and one publish, and what a crash
+/// could lose.
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.
+/// Writes and pushes are batched. Streamed output - the overwhelming bulk of
+/// a live session's frames, and the whole of a `session/load` replay - is
+/// buffered under a claim and, [`MAX_PENDING_LOG_FRAMES`] at a time or every
+/// [`LOG_FLUSH_INTERVAL`], written as one fenced insert and pushed to viewers
+/// as one publish, instead of costing a transaction, an audience lookup and
+/// a gateway round trip each. Only plain to-server notifications take that
+/// path: anything the store projects (system events, a load boundary, a
+/// Cursor checkpoint) or the runtime will act on writes the buffer out
+/// first and then lands at once through the single-frame path, exactly as
+/// before, so history never lacks or reorders a frame the rest of the system
+/// reacted to. A writer without a claim writes every frame at once.
///
/// 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
@@ -1133,11 +1139,36 @@ 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>,
+ /// Frames appended under the claim but not yet written, with the ids
+ /// they were handed at append time, in append order.
+ buffer: Vec<BufferedFrame>,
/// 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.
+ /// When the oldest buffered or pending frame must be flushed by; `None`
+ /// while there is none, so an idle writer never wakes its actor.
flush_due: Option<tokio::time::Instant>,
+ /// The model last projected onto the session row, so a thousand streamed
+ /// frames under one model cost one `UPDATE`, not a thousand.
+ projected_model: Option<String>,
+}
+
+/// One frame waiting for the next write.
+struct BufferedFrame {
+ id: Uuid,
+ log: AgentSessionLog,
+}
+
+/// Frames that may wait for the batch: to-server notifications the store
+/// projects nothing from. Everything else - requests and responses (the
+/// handshake), system events, checkpoints - is durable before `append`
+/// returns, through the single-frame path.
+fn batches(content: &Message) -> bool {
+ matches!(
+ content,
+ Message::ToServer(ToServerMessage::Acp(AcpMessage(
+ RawJsonRpcMessage::Notification(_)
+ )))
+ ) && cursor_run_checkpoint(content).is_none()
}
/// Frames viewers must see as soon as they are stored rather than with the
@@ -1165,8 +1196,10 @@ impl<R, Rt> LiveSessionLogWriter<R, Rt> {
claim: None,
initial_model: None,
initial_model_request: None,
+ buffer: Vec::new(),
pending: Vec::new(),
flush_due: None,
+ projected_model: None,
}
}
@@ -1180,8 +1213,10 @@ impl<R, Rt> LiveSessionLogWriter<R, Rt> {
claim: Some(claim),
initial_model: None,
initial_model_request: None,
+ buffer: Vec::new(),
pending: Vec::new(),
flush_due: None,
+ projected_model: None,
}
}
@@ -1218,40 +1253,81 @@ where
);
}
- // Durable first: projections are rebuildable, but a frame omitted from
- // session history is not.
- let stored = match &self.claim {
- Some(claim) => {
- self.repo
- .create_fenced_with_boundary(log.clone(), claim, boundary)
- .await?
- }
- None if boundary.is_some() => return Err(AgentSessionError::FencedOut(session)),
- None => AgentSessionLogRepo::create(&self.repo, log.clone()).await?,
- };
-
- let signals = if let Some(fold) = &mut self.fold {
- fold.push(log.clone()).signals
- } else {
+ // Fold before anything is written: the fold is in memory, so its
+ // signals are exact whether the frame lands now or with the batch,
+ // and a first frame catches the fold up on everything stored plus
+ // everything still buffered before it.
+ if self.fold.is_none() {
match self.catch_up(session).await {
- Ok((fold, signals)) => {
- self.fold = Some(fold);
- signals
- }
+ Ok(fold) => self.fold = Some(fold),
Err(error) => {
tracing::error!(
error = ?error,
%session,
"failed to fold agent session frame"
);
- Vec::new()
}
}
+ }
+ let signals = self
+ .fold
+ .as_mut()
+ .map(|fold| fold.push(log.clone()).signals)
+ .unwrap_or_default();
+
+ let log_id = match &self.claim {
+ Some(_) if boundary.is_none() && batches(&log.content) => {
+ let id = macro_uuid::generate_uuid_v7();
+ self.buffer.push(BufferedFrame {
+ id,
+ log: log.clone(),
+ });
+ self.flush_due
+ .get_or_insert_with(|| tokio::time::Instant::now() + LOG_FLUSH_INTERVAL);
+ if self.buffer.len() >= MAX_PENDING_LOG_FRAMES {
+ AgentSessionLogWriter::flush(self).await?;
+ }
+ id
+ }
+ Some(claim) => {
+ // Whatever is buffered lands first, so history keeps append
+ // order around a frame the rest of the system reacts to.
+ let claim = *claim;
+ self.flush_writes().await?;
+ let stored = self
+ .repo
+ .create_fenced_with_boundary(log.clone(), &claim, boundary)
+ .await?;
+ let id = stored.id;
+ 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?;
+ }
+ id
+ }
+ None if boundary.is_some() => return Err(AgentSessionError::FencedOut(session)),
+ // Unclaimed writers are outside any live contest and write every
+ // frame at once - the batch exists for streamed output under a
+ // claim, nothing else.
+ None => {
+ let stored = AgentSessionLogRepo::create(&self.repo, log.clone()).await?;
+ let id = stored.id;
+ 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?;
+ }
+ id
+ }
};
- // Projected on every frame - idempotent, rebuildable from the log,
- // and best-effort like the stream below, so a failed write must not
- // fail the append. Batch if the write rate ever matters.
+ // Projected when it changes - idempotent, rebuildable from the log,
+ // and best-effort, so a failed write must not fail the append.
let model = self
.fold
.as_ref()
@@ -1284,30 +1360,27 @@ where
}
if self.initial_model.is_none()
&& let Some(model) = model
- && let Err(error) = self.repo.set_model(session, &model).await
+ && self.projected_model.as_ref() != Some(&model)
{
- tracing::error!(
- error = ?error,
- %session,
- "failed to project agent session model"
- );
+ match self.repo.set_model(session, &model).await {
+ Ok(()) => self.projected_model = Some(model),
+ Err(error) => {
+ tracing::error!(
+ error = ?error,
+ %session,
+ "failed to project agent session model"
+ );
+ }
+ }
}
- // Durable already; the push to viewers waits for the batch unless
- // this frame is one they must see now.
- let log_id = stored.id;
- 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<()> {
+ self.flush_writes().await?;
if self.pending.is_empty() {
+ self.flush_due = None;
return Ok(());
}
let entries = std::mem::take(&mut self.pending);
@@ -1331,6 +1404,43 @@ where
}
}
+impl<R, Rt> LiveSessionLogWriter<R, Rt>
+where
+ R: AgentSessionRepo + AgentSessionLogRepo + Clone,
+ Rt: AgentSessionRealtime + Send + Sync + 'static,
+{
+ /// Land every buffered frame in one fenced write, leaving them pending
+ /// publication.
+ ///
+ /// The buffer is taken, not borrowed: a failed batch is not retried. Its
+ /// commit may have landed, and a retry would duplicate every frame in
+ /// it, so a failed flush loses its frames the way a failed per-frame
+ /// write used to lose its one - and the actor tears the session down
+ /// over the error either way.
+ async fn flush_writes(&mut self) -> Result<()> {
+ if self.buffer.is_empty() {
+ return Ok(());
+ }
+ let Some(claim) = self.claim else {
+ // Nothing is ever buffered without a claim; see `append_with_boundary`.
+ return Ok(());
+ };
+ let entries = std::mem::take(&mut self.buffer)
+ .into_iter()
+ .map(|frame| StoredAgentSessionLog {
+ id: frame.id,
+ // Placeholder; the store stamps the row and hands the real
+ // time back.
+ created_at: chrono::Utc::now(),
+ entry: frame.log,
+ })
+ .collect();
+ let stored = self.repo.create_batch_fenced(entries, &claim).await?;
+ self.pending.extend(stored);
+ Ok(())
+ }
+}
+
/// Pure delegation to the wrapped repository: the actor's shutdown path reads
/// and updates the session through its `Logs` handle, and those operations
/// append nothing, so there is nothing for this writer to do with them.
@@ -1481,14 +1591,14 @@ where
.await
}
- /// Walk this connection's fold through the session's stored log, so it
- /// starts from where the session actually is rather than from nothing.
+ /// Walk this connection's fold through the session's stored log and then
+ /// through anything still buffered, so it starts from where the session
+ /// actually is rather than from nothing.
///
- /// Runs once per connection, on its first frame - by which point that
- /// frame is already in the log. Everything before it is history: folded,
- /// and whatever it signalled discarded, because a reconnect must not
- /// announce past turns again. The frame itself is live, so its signals
- /// are returned like any later frame's.
+ /// Runs once per connection, before its first frame is folded. Everything
+ /// it folds is history, and whatever that signalled is discarded, because
+ /// a reconnect must not announce past turns again. The caller then pushes
+ /// the first frame itself, live, and gets that frame's signals.
///
/// This is what makes re-attaching correct.
/// [`TurnId`](agent_fold::domain::model::TurnId)s are a counter over the
@@ -1499,20 +1609,19 @@ where
async fn catch_up(
&self,
session: AgentSessionId,
- ) -> std::result::Result<(LifecycleFold, Vec<TurnSignal>), rootcause::Report> {
- let mut log = AgentSessionLogRepo::list_by_session(&self.repo, session)
+ ) -> std::result::Result<LifecycleFold, rootcause::Report> {
+ let log = AgentSessionLogRepo::list_by_session(&self.repo, session)
.await
.map_err(|error| rootcause::report!(error))?;
let mut fold = LifecycleFold::new();
- let just_appended = log.pop();
for stored in log {
let _ = fold.push(stored.entry);
}
- let signals = just_appended
- .map(|stored| fold.push(stored.entry).signals)
- .unwrap_or_default();
- Ok((fold, signals))
+ for frame in &self.buffer {
+ let _ = fold.push(frame.log.clone());
+ }
+ Ok(fold)
}
}
diff --git a/crates/agent_session/src/domain/service/test.rs b/crates/agent_session/src/domain/service/test.rs
index 69fbbcbd62..1d2536ad7e 100644
--- a/crates/agent_session/src/domain/service/test.rs
+++ b/crates/agent_session/src/domain/service/test.rs
@@ -635,6 +635,14 @@ impl AgentSessionLogRepo for BlockingPromptLogs {
self.repo.create_fenced(log, claim).await
}
+ async fn create_batch_fenced(
+ &self,
+ entries: Vec<StoredAgentSessionLog>,
+ claim: &SessionClaim,
+ ) -> Result<Vec<StoredAgentSessionLog>> {
+ self.repo.create_batch_fenced(entries, claim).await
+ }
+
async fn create(&self, log: AgentSessionLog) -> Result<StoredAgentSessionLog> {
if self.hang_disconnect
&& matches!(
@@ -2128,3 +2136,223 @@ async fn a_full_pending_run_flushes_itself() {
assert_eq!(published[0].entries.len(), MAX_PENDING_LOG_FRAMES);
assert!(logs.flush_deadline().is_none());
}
+
+// Batched writes: a fenced connection holds streamed notifications back and
+// lands them in one insert, while anything the store projects or the
+// runtime acts on writes the buffer out first and lands at once.
+
+async fn fenced_connection(
+ realtime: RecordingRealtime,
+) -> (
+ InMemoryAgentSessionRepo,
+ LiveSessionLogWriter<InMemoryAgentSessionRepo, RecordingRealtime>,
+) {
+ let repo = InMemoryAgentSessionRepo::new();
+ repo.insert_session(test_agent_session(test_session()));
+ let claim = claim_for_test(&repo, test_session()).await;
+ let logs = LiveSessionLogWriter::fenced(repo.clone(), realtime, claim);
+ (repo, logs)
+}
+
+/// Under a claim, streamed notifications wait for the flush: nothing is
+/// stored or published until then, and the flush lands them all at once, in
+/// order, under the ids the appends already handed out.
+#[tokio::test]
+async fn a_fenced_connection_buffers_streamed_frames_until_it_flushes() {
+ let realtime = RecordingRealtime::new();
+ let (repo, mut logs) = fenced_connection(realtime.clone()).await;
+
+ 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,
+ );
+ }
+
+ assert!(
+ AgentSessionLogRepo::list_by_session(&repo, test_session())
+ .await
+ .unwrap()
+ .is_empty(),
+ "buffered frames are not yet durable"
+ );
+ assert!(realtime.published().is_empty());
+ assert!(logs.flush_deadline().is_some());
+
+ AgentSessionLogWriter::flush(&mut logs)
+ .await
+ .expect("flush succeeds");
+
+ let stored = AgentSessionLogRepo::list_by_session(&repo, test_session())
+ .await
+ .unwrap();
+ assert_eq!(
+ stored.iter().map(|row| row.id).collect::<Vec<_>>(),
+ appended,
+ "the flush stores every frame in append order under the id its append returned"
+ );
+ assert!(
+ stored
+ .windows(2)
+ .all(|pair| pair[0].created_at < pair[1].created_at),
+ "a batch orders strictly by time, as readers expect"
+ );
+ 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
+ );
+ assert!(logs.flush_deadline().is_none());
+}
+
+/// A frame headed to the runtime writes the buffer out ahead of itself and
+/// is durable before `append` returns, so history never lacks a message the
+/// agent received and never reorders around it.
+#[tokio::test]
+async fn frames_headed_to_the_runtime_write_the_buffer_out_first() {
+ let realtime = RecordingRealtime::new();
+ let (repo, mut logs) = fenced_connection(realtime.clone()).await;
+
+ let buffered = AgentSessionLogWriter::append(&mut logs, streamed_frame("buffered"))
+ .await
+ .unwrap()
+ .log_id;
+ 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 stored = AgentSessionLogRepo::list_by_session(&repo, test_session())
+ .await
+ .unwrap();
+ assert_eq!(
+ stored.iter().map(|row| row.id).collect::<Vec<_>>(),
+ vec![buffered, prompt_id],
+ "both durable, buffered frame first"
+ );
+ assert_eq!(realtime.published().len(), 1, "and pushed as one publish");
+ assert!(logs.flush_deadline().is_none());
+}
+
+/// A successful load's boundary selects history at its own row, so the
+/// frames buffered before it must already be rows when it lands.
+#[tokio::test]
+async fn a_load_boundary_lands_after_the_frames_buffered_before_it() {
+ let realtime = RecordingRealtime::new();
+ let (repo, mut logs) = fenced_connection(realtime.clone()).await;
+
+ let initialize = AgentSessionLog {
+ agent_session_id: test_session(),
+ user_id: None,
+ content: Message::ToRuntime(ToRuntimeMessage::Acp(AcpMessage(
+ agent_client_protocol::RawJsonRpcMessage::request(
+ "initialize".to_owned(),
+ serde_json::json!({}),
+ agent_client_protocol::schema::v1::RequestId::Str("init".into()),
+ )
+ .unwrap(),
+ ))),
+ };
+ let initialization_log_id = AgentSessionLogWriter::append(&mut logs, initialize)
+ .await
+ .unwrap()
+ .log_id;
+ let replayed = AgentSessionLogWriter::append(&mut logs, streamed_frame("replayed"))
+ .await
+ .unwrap()
+ .log_id;
+ let load_response = AgentSessionLog {
+ agent_session_id: test_session(),
+ user_id: None,
+ content: Message::ToServer(ToServerMessage::Acp(AcpMessage(
+ agent_client_protocol::RawJsonRpcMessage::response(
+ agent_client_protocol::schema::v1::RequestId::Str("load".into()),
+ Ok(serde_json::json!({})),
+ ),
+ ))),
+ };
+ let response_id = AgentSessionLogWriter::append_with_boundary(
+ &mut logs,
+ load_response,
+ Some(crate::domain::model::HistoryBoundary {
+ initialization_log_id,
+ }),
+ )
+ .await
+ .unwrap()
+ .log_id;
+
+ let history = AgentSessionLogRepo::list_by_session(&repo, test_session())
+ .await
+ .unwrap();
+ assert_eq!(
+ history.iter().map(|row| row.id).collect::<Vec<_>>(),
+ vec![initialization_log_id, replayed, response_id],
+ "history starts at the initialization and keeps append order"
+ );
+}
+
+/// A full buffer flushes itself, bounding what a crash could lose and what
+/// one insert has to write.
+#[tokio::test]
+async fn a_full_buffer_writes_itself_out() {
+ let realtime = RecordingRealtime::new();
+ let (repo, mut logs) = fenced_connection(realtime.clone()).await;
+
+ for index in 0..MAX_PENDING_LOG_FRAMES {
+ AgentSessionLogWriter::append(&mut logs, streamed_frame(&index.to_string()))
+ .await
+ .unwrap();
+ }
+
+ let stored = AgentSessionLogRepo::list_by_session(&repo, test_session())
+ .await
+ .unwrap();
+ assert_eq!(stored.len(), MAX_PENDING_LOG_FRAMES);
+ 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());
+}
+
+/// The fold hands out turn ids over the whole log, so it must count frames
+/// that are only buffered too, and a flushed turn reads back complete and in
+/// order.
+#[tokio::test]
+async fn a_fenced_turn_flushes_complete_and_in_order() {
+ let realtime = RecordingRealtime::new();
+ let (repo, mut logs) = fenced_connection(realtime.clone()).await;
+
+ let log = parse_log_as(test_session(), TURN);
+ for entry in log.clone() {
+ AgentSessionLogWriter::append(&mut logs, entry)
+ .await
+ .unwrap();
+ }
+ AgentSessionLogWriter::flush(&mut logs).await.unwrap();
+
+ let stored = AgentSessionLogRepo::list_by_session(&repo, test_session())
+ .await
+ .unwrap();
+ assert_eq!(
+ stored
+ .into_iter()
+ .map(|row| serde_json::to_value(row.entry.content).unwrap())
+ .collect::<Vec<_>>(),
+ log.into_iter()
+ .map(|entry| serde_json::to_value(entry.content).unwrap())
+ .collect::<Vec<_>>(),
+ );
+}
diff --git a/crates/agent_session/src/outbound/postgres.rs b/crates/agent_session/src/outbound/postgres.rs
index 19debcdc97..0ba660294b 100644
--- a/crates/agent_session/src/outbound/postgres.rs
+++ b/crates/agent_session/src/outbound/postgres.rs
@@ -16,7 +16,7 @@ use crate::domain::model::{
AgentMcpServers, AgentSession, AgentSessionId, AgentSessionLog, AgentSessionPreviewData,
ClaimOutcome, CreateAgentSessionParams, ExternalSession, ManagerFence, Message, ReplicaAddress,
ReplicaId, SandboxSize, SessionBot, SessionClaim, SessionManager, SessionPreviewCandidate,
- SessionStatus, StoredAgentSessionLog, ThreadSession,
+ SessionStatus, StoredAgentSessionLog, ThreadSession, cursor_run_checkpoint,
};
use crate::domain::ports::{
AgentSessionLogRepo, AgentSessionRepo, ExternalSessionRepo, REPLICA_STALE_AFTER,
@@ -110,31 +110,6 @@ fn parse_message(direction: &str, content: serde_json::Value) -> anyhow::Result<
}
}
-fn cursor_run_checkpoint(message: &Message) -> Option<String> {
- let Message::ToServer(ToServerMessage::Acp(
- agent_runtime_protocol::domain::schema::v0::AcpMessage(frame),
- )) = message
- else {
- return None;
- };
- let value = serde_json::to_value(frame).ok()?;
- if value.get("method")?.as_str()? != "session/update" {
- return None;
- }
- let params = value.get("params")?;
- let update = params.get("update")?;
- if update.get("sessionUpdate")?.as_str()? != "agent_message_chunk"
- || !update.get("content")?.get("text")?.as_str()?.is_empty()
- {
- return None;
- }
- params
- .get("_meta")?
- .get("macroCursorRunCheckpoint")?
- .as_str()
- .map(str::to_owned)
-}
-
/// Record that `user_id` accessed the session in their history.
///
/// The `itemType` is the [`EntityType::AgentSession`] wire name, which is
@@ -1132,6 +1107,112 @@ impl AgentSessionLogRepo for PgAgentSessionRepo {
self.create_fenced_with_boundary(log, claim, None).await
}
+ async fn create_batch_fenced(
+ &self,
+ entries: Vec<StoredAgentSessionLog>,
+ claim: &SessionClaim,
+ ) -> Result<Vec<StoredAgentSessionLog>> {
+ if entries.is_empty() {
+ return Ok(entries);
+ }
+ if entries
+ .iter()
+ .any(|stored| stored.entry.agent_session_id != claim.session)
+ {
+ return Err(AgentSessionError::FencedOut(claim.session));
+ }
+ let session = claim.session;
+
+ let mut ids = Vec::with_capacity(entries.len());
+ let mut user_ids: Vec<Option<String>> = Vec::with_capacity(entries.len());
+ let mut directions: Vec<String> = Vec::with_capacity(entries.len());
+ let mut contents = Vec::with_capacity(entries.len());
+ for stored in &entries {
+ let (direction, content) = message_columns(&stored.entry.content)?;
+ ids.push(stored.id);
+ user_ids.push(
+ stored
+ .entry
+ .user_id
+ .as_ref()
+ .map(|user_id| user_id.as_ref().to_owned()),
+ );
+ directions.push(direction.to_owned());
+ contents.push(content);
+ }
+
+ let mut transaction = self
+ .pool
+ .begin()
+ .await
+ .context("begin fenced agent session log batch create")?;
+
+ // Hold the session row through commit, as the single-frame write
+ // does: a takeover updates this same row, so it cannot supersede the
+ // claim between our check and the insert.
+ let locked_session = sqlx::query_scalar!(
+ r#"
+ SELECT id
+ FROM agent_session
+ WHERE id = $1 AND manager_replica_id = $2 AND manager_fence = $3
+ FOR UPDATE
+ "#,
+ session.as_uuid(),
+ claim.replica.as_uuid(),
+ claim.fence.0,
+ )
+ .fetch_optional(&mut *transaction)
+ .await
+ .context("lock fenced agent session for batch")?;
+ if locked_session.is_none() {
+ return Err(AgentSessionError::FencedOut(session));
+ }
+
+ // One transaction means one `now()`, so the batch is spread over
+ // consecutive microseconds in append order: readers order by
+ // `(created_at, id)`, and the ids are v7 without a monotonic
+ // counter, so same-instant rows would otherwise interleave.
+ let stamped = sqlx::query!(
+ r#"
+ INSERT INTO agent_session_log (id, agent_session_id, user_id, direction, content, created_at)
+ SELECT frame.id, $1, frame.user_id, frame.direction, frame.content,
+ now() + (frame.ordinality - 1) * interval '1 microsecond'
+ FROM UNNEST($2::uuid[], $3::text[], $4::text[], $5::jsonb[])
+ WITH ORDINALITY AS frame(id, user_id, direction, content, ordinality)
+ RETURNING id, created_at
+ "#,
+ session.as_uuid(),
+ &ids,
+ &user_ids as &[Option<String>],
+ &directions,
+ &contents,
+ )
+ .fetch_all(&mut *transaction)
+ .await
+ .context("failed to create fenced agent session log batch")?;
+ transaction
+ .commit()
+ .await
+ .context("commit fenced agent session log batch create")?;
+
+ let stamps: std::collections::HashMap<Uuid, chrono::DateTime<chrono::Utc>> = stamped
+ .into_iter()
+ .map(|row| (row.id, row.created_at))
+ .collect();
+ entries
+ .into_iter()
+ .map(|stored| {
+ let created_at = stamps.get(&stored.id).copied().ok_or_else(|| {
+ anyhow::anyhow!("batch insert returned no row for log entry {}", stored.id)
+ })?;
+ Ok(StoredAgentSessionLog {
+ created_at,
+ ..stored
+ })
+ })
+ .collect()
+ }
+
async fn create_fenced_with_boundary(
&self,
log: AgentSessionLog,
diff --git a/crates/agent_session/src/outbound/postgres/test.rs b/crates/agent_session/src/outbound/postgres/test.rs
index 2d61f6d454..f7b9f2eb2c 100644
--- a/crates/agent_session/src/outbound/postgres/test.rs
+++ b/crates/agent_session/src/outbound/postgres/test.rs
@@ -2296,3 +2296,130 @@ impl crate::domain::audience::SessionSubscriptions for DocumentSubscriptions {
Ok(self.candidates.clone())
}
}
+
+/// A batch lands in one write: every frame under the id it arrived with, in
+/// append order by `(created_at, id)` even though one transaction has one
+/// clock.
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn create_batch_fenced_writes_in_order_under_the_given_ids(pool: PgPool) {
+ let repo = PgAgentSessionRepo::new(pool.clone());
+ let bot = create_test_bot(&pool).await;
+ let session = create_session(&repo, new_session(bot, None, None)).await;
+ let claim = claimed(repo.claim(session.id, ReplicaId::mint()).await.unwrap());
+ let before = repo
+ .create_fenced(fenced_log(session.id), &claim)
+ .await
+ .unwrap();
+
+ let streamed = |text: &str| AgentSessionLog {
+ agent_session_id: session.id,
+ user_id: None,
+ content: Message::ToServer(ToServerMessage::Acp(AcpMessage(
+ RawJsonRpcMessage::notification(
+ "session/update".to_owned(),
+ serde_json::json!({ "sessionId": "acp-1", "update": { "text": text } }),
+ )
+ .unwrap(),
+ ))),
+ };
+ let frames: Vec<AgentSessionLog> = ["one", "two", "three"].into_iter().map(streamed).collect();
+ let ids: Vec<Uuid> = (0..frames.len())
+ .map(|_| macro_uuid::generate_uuid_v7())
+ .collect();
+ let entries = ids
+ .iter()
+ .zip(frames.iter().cloned())
+ .map(|(id, entry)| StoredAgentSessionLog {
+ id: *id,
+ created_at: chrono::Utc::now(),
+ entry,
+ })
+ .collect();
+
+ let stored = repo.create_batch_fenced(entries, &claim).await.unwrap();
+ assert_eq!(
+ stored.iter().map(|row| row.id).collect::<Vec<_>>(),
+ ids,
+ "the store keeps the ids the writer handed out"
+ );
+ assert!(
+ stored
+ .windows(2)
+ .all(|pair| pair[0].created_at < pair[1].created_at),
+ "one transaction, one clock, yet strictly increasing stamps"
+ );
+ let after = repo
+ .create_fenced(fenced_log(session.id), &claim)
+ .await
+ .unwrap();
+
+ let history = AgentSessionLogRepo::list_by_session(&repo, session.id)
+ .await
+ .unwrap();
+ assert_eq!(
+ history.iter().map(|row| row.id).collect::<Vec<_>>(),
+ std::iter::once(before.id)
+ .chain(ids.iter().copied())
+ .chain(std::iter::once(after.id))
+ .collect::<Vec<_>>(),
+ "a batch reads back in append order between single-frame writes"
+ );
+ assert_eq!(
+ history[1..4]
+ .iter()
+ .map(|row| serde_json::to_value(&row.entry.content).unwrap())
+ .collect::<Vec<_>>(),
+ frames
+ .iter()
+ .map(|entry| serde_json::to_value(&entry.content).unwrap())
+ .collect::<Vec<_>>(),
+ );
+}
+
+/// The batch is fenced like every other write: a superseded claim appends
+/// nothing, and a frame from another session is refused before anything is
+/// touched.
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn create_batch_fenced_refuses_stale_claims_and_foreign_frames(pool: PgPool) {
+ let repo = PgAgentSessionRepo::new(pool.clone());
+ let bot = create_test_bot(&pool).await;
+ let session = create_session(&repo, new_session(bot, None, None)).await;
+ let other = create_session(&repo, new_session(bot, None, None)).await;
+ // Re-claiming bumps the fence, so the first claim is the superseded one.
+ let replica = ReplicaId::mint();
+ let stale = claimed(repo.claim(session.id, replica).await.unwrap());
+ let current = claimed(repo.claim(session.id, replica).await.unwrap());
+ let entry = |log: AgentSessionLog| StoredAgentSessionLog {
+ id: macro_uuid::generate_uuid_v7(),
+ created_at: chrono::Utc::now(),
+ entry: log,
+ };
+
+ assert!(matches!(
+ repo.create_batch_fenced(vec![entry(fenced_log(session.id))], &stale)
+ .await,
+ Err(AgentSessionError::FencedOut(id)) if id == session.id
+ ));
+ assert!(matches!(
+ repo.create_batch_fenced(
+ vec![entry(fenced_log(session.id)), entry(fenced_log(other.id))],
+ &current,
+ )
+ .await,
+ Err(AgentSessionError::FencedOut(id)) if id == session.id
+ ));
+ assert!(
+ repo.create_batch_fenced(Vec::new(), &current)
+ .await
+ .unwrap()
+ .is_empty(),
+ "an empty batch is a no-op"
+ );
+ assert!(
+ AgentSessionLogRepo::list_by_session(&repo, session.id)
+ .await
+ .unwrap()
+ .is_empty(),
+ "nothing landed from a refused batch"
+ );
+}
diff --git a/crates/agent_session/src/testing.rs b/crates/agent_session/src/testing.rs
index d73b598d8b..fa497a43e6 100644
--- a/crates/agent_session/src/testing.rs
+++ b/crates/agent_session/src/testing.rs
@@ -602,6 +602,49 @@ impl AgentSessionLogRepo for InMemoryAgentSessionRepo {
self.create_fenced_with_boundary(log, claim, None).await
}
+ async fn create_batch_fenced(
+ &self,
+ entries: Vec<StoredAgentSessionLog>,
+ claim: &SessionClaim,
+ ) -> Result<Vec<StoredAgentSessionLog>> {
+ if entries.is_empty() {
+ return Ok(entries);
+ }
+ if entries
+ .iter()
+ .any(|stored| stored.entry.agent_session_id != claim.session)
+ {
+ return Err(AgentSessionError::FencedOut(claim.session));
+ }
+ let _transaction = self.log_transaction.lock().unwrap();
+ let session = claim.session;
+ {
+ let leases = self.leases.lock().unwrap();
+ if !matches!(
+ leases.get(&session), Some((holder, fence))
+ if *holder == Some(claim.replica) && *fence == claim.fence.0
+ ) || !self.sessions.lock().unwrap().contains_key(&session)
+ {
+ return Err(AgentSessionError::FencedOut(session));
+ }
+ }
+ // Consecutive microseconds from one instant, as the Postgres store
+ // does, so a batch orders by `(created_at, id)` in append order.
+ let now = chrono::Utc::now();
+ let mut stored_entries = Vec::with_capacity(entries.len());
+ for (index, stored) in entries.into_iter().enumerate() {
+ let mut created = self.create_log(stored.entry)?;
+ created.id = stored.id;
+ created.created_at = now + chrono::Duration::microseconds(index as i64);
+ let mut logs = self.logs.lock().unwrap();
+ let rows = logs.get_mut(&session).expect("create_log inserted the row");
+ let row = rows.last_mut().expect("create_log inserted the row");
+ *row = created.clone();
+ stored_entries.push(created);
+ }
+ Ok(stored_entries)
+ }
+
async fn create_fenced_with_boundary(
&self,
log: AgentSessionLog,