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): write streamed log frames in batches (#6658)
Wolf Mermelstein4cad2bf4010f
diff --git a/.sqlx/query-b1ac4ab49729df68d741d817512bb66ad26d937554466326bb17dbf661a4fa1f.json b/.sqlx/query-b1ac4ab49729df68d741d817512bb66ad26d937554466326bb17dbf661a4fa1f.jsonnew file mode 100644index 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.rsindex 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 windowdiff --git a/crates/agent_session/src/domain/ports.rs b/crates/agent_session/src/domain/ports.rsindex 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.rsindex 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 @@ whereasync 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.rsindex 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.rsindex 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.rsindex 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))],+ ¤t,+ )+ .await,+ Err(AgentSessionError::FencedOut(id)) if id == session.id+ ));+ assert!(+ repo.create_batch_fenced(Vec::new(), ¤t)+ .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.rsindex 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,