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
//! Serial cloud conversations, durable launch receipts, and provider-grounded completion.
use super::cloud::{CloudEvent, CloudId, Launch, NativeRecord, TurnId};
use super::journal::{JournalEntry, JournalInput, ReplayMachine};
use super::runtime::{CloudRuntime, CloudTarget};
mod metadata;
use futures::StreamExt as _;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::sync::{
Arc,
atomic::{AtomicBool, Ordering},
};
use std::time::Duration;
use tokio::sync::Mutex;
/// Durable conversation state. Pending writes are never retried automatically.
#[derive(Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StoredSession {
/// Account binding prevents replay after switching OAuth accounts.
pub account_id: String,
/// Connection generation pinned for hosted account reconnects.
pub connection_id: String,
/// Destination pinned before the first cloud submission; absent until selection succeeds.
pub target: Option<CloudTarget>,
/// The single remote task backing this conversation.
pub task: Option<String>,
/// Latest assistant turn used as the parent for continuation.
pub turn: Option<String>,
/// A write began without a durably recorded receipt.
pub uncertain_write: bool,
}
/// Persistence boundary for conversation identity and replay.
pub trait SessionStore: Send + Sync {
/// Read a previously created session.
fn load(
&self,
id: &str,
) -> impl Future<Output = Result<Option<StoredSession>, rootcause::Report>> + Send;
/// Atomically checkpoint a session before acknowledging provider writes.
fn save(
&self,
id: &str,
state: &StoredSession,
) -> impl Future<Output = Result<(), rootcause::Report>> + Send;
/// Read the complete ordered native input journal.
fn read(
&self,
id: &str,
) -> impl Future<Output = Result<Vec<JournalEntry>, rootcause::Report>> + Send;
/// Append only if the expected sequence and attachment fence still match.
fn append(
&self,
id: &str,
expected: i64,
turn: Option<&TurnId>,
input: &JournalInput,
) -> impl Future<Output = Result<JournalEntry, rootcause::Report>> + Send;
/// Verify this attachment still owns its management generation before provider calls.
fn validate(&self) -> impl Future<Output = Result<(), rootcause::Report>> + Send;
}
/// Session event delivery implemented by the inbound connection.
pub trait SessionSink: Send + Sync {
/// Queue one ordered event; errors stop local observation.
fn emit(&self, event: &CloudEvent) -> Result<(), rootcause::Report>;
/// Request a transactional replacement after silently captured recovery output.
/// Return true when the host must load before another prompt may run.
fn recovered(&self) -> Result<bool, rootcause::Report> {
Ok(false)
}
}
struct Discard;
impl SessionSink for Discard {
fn emit(&self, _: &CloudEvent) -> Result<(), rootcause::Report> {
Ok(())
}
}
/// Verified provider terminal outcome.
pub enum Outcome {
/// Provider completed successfully.
Completed,
/// Provider explicitly reports cancellation.
Cancelled,
}
struct Session {
state: Mutex<StoredSession>,
machine: Mutex<ReplayMachine>,
turn_lock: Arc<tokio::sync::Mutex<()>>,
recovery_gate: std::sync::Mutex<bool>,
cancel: AtomicBool,
reload_pending: AtomicBool,
changed: tokio::sync::Notify,
metadata_lock: Mutex<()>,
published_pr: Mutex<Option<String>>,
}
/// Exclusive recovery reservation retained across the ACP load response.
pub struct Recovery {
session: Arc<Session>,
guard: Option<tokio::sync::OwnedMutexGuard<()>>,
}
impl Drop for Recovery {
fn drop(&mut self) {
let mut recovering = self
.session
.recovery_gate
.lock()
.expect("recovery gate poisoned");
drop(self.guard.take());
*recovering = false;
self.session.changed.notify_waiters();
}
}
/// Owns serial turns while cancellation remains independently runnable.
pub struct SessionService<R, J> {
probe: Arc<R>,
fixed_session: Option<String>,
journal: J,
explicit_target: Option<CloudTarget>,
sessions: Mutex<HashMap<String, Arc<Session>>>,
metadata_changed: tokio::sync::Notify,
}
impl<R: CloudRuntime, J: SessionStore> SessionService<R, J> {
/// Compose cloud and persistence ports with an explicit remote target.
pub fn new(probe: Arc<R>, journal: J, explicit_target: Option<CloudTarget>) -> Self {
Self {
probe,
fixed_session: None,
journal,
explicit_target,
sessions: Mutex::new(HashMap::new()),
metadata_changed: tokio::sync::Notify::new(),
}
}
/// Pin ACP identity to the host session so a lost new-session response cannot orphan a launch.
pub fn with_session_id(mut self, id: String) -> Self {
self.fixed_session = Some(id);
self
}
/// Create a local session without starting cloud execution.
pub async fn new_session(&self) -> Result<String, rootcause::Report> {
let id = self
.fixed_session
.clone()
.unwrap_or_else(|| uuid::Uuid::now_v7().to_string());
if self.journal.load(&id).await?.is_some() {
self.session(&id).await?;
self.metadata_changed.notify_one();
return Ok(id);
}
let auth = self.probe.identity().await?;
self.journal
.save(
&id,
&StoredSession {
account_id: auth.account_id,
connection_id: auth.connection_id,
..StoredSession::default()
},
)
.await?;
self.journal
.append(&id, 0, None, &JournalInput::HistoryComplete)
.await?;
self.session(&id).await?;
self.metadata_changed.notify_one();
Ok(id)
}
async fn session(&self, id: &str) -> Result<Arc<Session>, rootcause::Report> {
self.journal.validate().await?;
let current_identity = self.probe.identity().await?;
let mut sessions = self.sessions.lock().await;
if let Some(session) = sessions.get(id) {
let state = session.state.lock().await;
if state.account_id != current_identity.account_id
|| state.connection_id != current_identity.connection_id
{
return Err(rootcause::report!(
"saved session belongs to a different account or connection"
));
}
return Ok(session.clone());
}
let state = self
.journal
.load(id)
.await?
.ok_or_else(|| rootcause::report!("unknown session"))?;
if (state.task.is_some() || state.turn.is_some()) && state.target.is_none() {
return Err(rootcause::report!("saved cloud task has no pinned target"));
}
let auth = self.probe.identity().await?;
if state.account_id != auth.account_id || state.connection_id != auth.connection_id {
return Err(rootcause::report!(
"saved session belongs to a different account or remote target"
));
}
let entries = self.journal.read(id).await?;
if entries.is_empty() {
return Err(rootcause::report!(
"native journal has no complete history boundary"
));
}
let mut machine = ReplayMachine::default();
for entry in &entries {
machine.push(entry)?;
}
machine.finish();
let session = Arc::new(Session {
machine: Mutex::new(machine),
state: Mutex::new(state),
turn_lock: Arc::new(tokio::sync::Mutex::new(())),
recovery_gate: std::sync::Mutex::new(false),
cancel: AtomicBool::new(false),
reload_pending: AtomicBool::new(false),
changed: tokio::sync::Notify::new(),
metadata_lock: Mutex::new(()),
published_pr: Mutex::new(None),
});
sessions.insert(id.to_owned(), session.clone());
Ok(session)
}
/// Replay the durable conversation without launching or continuing work.
pub async fn replay(&self, id: &str, sink: &impl SessionSink) -> Result<(), rootcause::Report> {
let session = self.session(id).await?;
let _guard = session
.turn_lock
.try_lock()
.map_err(|_| rootcause::report!("session is busy"))?;
self.replay_entries(id, sink).await
}
async fn replay_entries(
&self,
id: &str,
sink: &impl SessionSink,
) -> Result<(), rootcause::Report> {
let session = self.session(id).await?;
let state = session.state.lock().await.clone();
let entries = self.journal.read(id).await?;
if entries.is_empty() {
return Err(rootcause::report!(
"native journal has no complete history boundary"
));
}
// Associations can arrive after a later prompt. Rebuild their tool activity
// beside the originating turn rather than attributing it to that later turn.
let mut catalog = ReplayMachine::default();
for entry in &entries {
catalog.push(entry)?;
}
let mut machine = ReplayMachine::default();
let mut current_turn = None;
let emit = |event: CloudEvent, turn: &mut Option<String>| {
if event.method == "session/turn_complete"
&& let Some(turn) = turn.as_deref()
&& let Some(pr) = metadata::pull_request_event(&catalog, &state, turn)
{
sink.emit(&pr)?;
}
if event.method == "user/message" {
*turn = None;
}
sink.emit(&event)
};
for entry in &entries {
if let JournalInput::PromptAccepted { turn, .. } = &entry.input {
current_turn = turn.clone();
}
for event in machine.push(entry)? {
emit(event, &mut current_turn)?;
}
}
for event in machine.finish() {
emit(event, &mut current_turn)?;
}
Ok(())
}
async fn finish_events(
&self,
session: &Session,
sink: &impl SessionSink,
) -> Result<(), rootcause::Report> {
let state = session.state.lock().await.clone();
let mut machine = session.machine.lock().await;
for event in machine.finish() {
if event.method == "session/turn_complete"
&& let Some(turn) = state.turn.as_deref()
&& let Some(pr) = metadata::pull_request_event(&machine, &state, turn)
{
sink.emit(&pr)?;
}
sink.emit(&event)?;
}
Ok(())
}
async fn record(
&self,
id: &str,
session: &Session,
input: JournalInput,
sink: &impl SessionSink,
) -> Result<Vec<CloudEvent>, rootcause::Report> {
let turn = match &input {
JournalInput::PromptAccepted { turn, .. } => turn.clone(),
_ => session.state.lock().await.turn.clone(),
}
.map(TurnId::new)
.transpose()?;
let mut machine = session.machine.lock().await;
machine.ensure_appendable(&input)?;
let entry = self
.journal
.append(id, machine.sequence(), turn.as_ref(), &input)
.await?;
let events = machine.push(&entry)?;
if matches!(&input, JournalInput::Poll {snapshot,..} if !snapshot.pull_requests.is_empty())
{
self.metadata_changed.notify_one();
}
for event in &events {
sink.emit(event)?;
}
Ok(events)
}
async fn observe_event(
&self,
id: &str,
session: &Session,
task: &CloudId,
record: NativeRecord,
sink: &impl SessionSink,
) -> Result<(), rootcause::Report> {
let events = self
.record(id, session, JournalInput::Native(record), sink)
.await?;
if events.iter().any(|event| {
event.method.contains("requestApproval")
|| event.method.contains("requestUserInput")
|| event.method.contains("elicitation")
}) {
self.journal.validate().await?;
self.probe.cancel(task).await?;
return Err(rootcause::report!(
"cloud turn requested interactive input or approval unsupported by this adapter; remote cancellation requested"
));
}
Ok(())
}
/// Signal and perform remote cancellation without waiting for the turn lock.
pub async fn cancel(&self, id: &str) -> Result<(), rootcause::Report> {
self.journal.validate().await?;
let session = self.session(id).await?;
self.record(id, &session, JournalInput::CancellationRequested, &Discard)
.await?;
session.cancel.store(true, Ordering::SeqCst);
session.changed.notify_waiters();
let task = session.state.lock().await.task.clone();
if let Some(task) = task {
self.probe.cancel(&CloudId::new(task)?).await?;
}
Ok(())
}
/// Preserve the client's original text blocks in the native input journal.
pub async fn prompt(
&self,
id: &str,
blocks: Vec<agent_client_protocol::schema::v1::ContentBlock>,
sink: &impl SessionSink,
) -> Result<Outcome, rootcause::Report> {
let prompt = blocks
.iter()
.map(|block| match block {
agent_client_protocol::schema::v1::ContentBlock::Text(text) => {
Ok(text.text.as_str())
}
_ => Err(rootcause::report!("only text prompt blocks are supported")),
})
.collect::<Result<Vec<_>, _>>()?
.join("\n");
self.journal.validate().await?;
if prompt.trim().is_empty() || prompt.len() > 64 * 1024 {
return Err(rootcause::report!(
"provide a nonempty prompt (maximum 64 KiB)"
));
}
let session = self.session(id).await?;
let _guard = loop {
let changed = session.changed.notified();
tokio::pin!(changed);
changed.as_mut().enable();
if session.reload_pending.load(Ordering::SeqCst) {
changed.await;
continue;
}
// Classify the held lock atomically with recovery reservation/drop.
let immediate =
{
let recovering = session
.recovery_gate
.lock()
.expect("recovery gate poisoned");
if *recovering {
None
} else {
Some(session.turn_lock.try_lock().map_err(|_| {
rootcause::report!("session already has a running prompt")
})?)
}
};
let guard = match immediate {
Some(guard) => guard,
None => session.turn_lock.lock().await,
};
if !session.reload_pending.load(Ordering::SeqCst) {
break guard;
}
drop(guard);
};
self.journal.validate().await?;
session.cancel.store(false, Ordering::SeqCst);
let previous = session.state.lock().await.clone();
if previous.uncertain_write {
return Err(rootcause::report!(
"previous submission has an uncertain outcome; inspect cloud tasks before starting another session"
));
}
if let Some(task) = &previous.task {
let mut snapshot = self.probe.snapshot(&CloudId::new(task.clone())?).await?;
let native = snapshot.native.take();
self.record(
id,
&session,
JournalInput::Poll {
snapshot: snapshot.clone(),
native,
},
sink,
)
.await?;
if let Some(current) = snapshot
.turns
.iter()
.find(|turn| turn.source == "current_assistant_turn")
.and_then(|turn| turn.id.as_ref())
&& previous.turn.as_ref() != Some(current)
{
return Err(rootcause::report!(
"cloud conversation advanced outside this session; refusing to branch from an older turn"
));
}
if !snapshot.terminal() {
return Err(rootcause::report!(
"existing cloud task is still running or has unknown status; cancel it or wait before continuing"
));
}
}
let target = match previous.target {
Some(target) => target,
None => {
let selecting = self
.probe
.resolve_target(&prompt, self.explicit_target.as_ref());
tokio::pin!(selecting);
let target = loop {
let changed = session.changed.notified();
tokio::pin!(changed);
changed.as_mut().enable();
if session.cancel.load(Ordering::SeqCst) {
return Ok(Outcome::Cancelled);
}
tokio::select! {
result = &mut selecting => {
if session.cancel.load(Ordering::SeqCst) { return Ok(Outcome::Cancelled); }
break result?;
}
_ = changed => {}
}
};
target.validate()?;
self.journal.validate().await?;
if session.cancel.load(Ordering::SeqCst) {
return Ok(Outcome::Cancelled);
}
let mut state = session.state.lock().await;
let mut updated = state.clone();
updated.target = Some(target.clone());
self.journal.save(id, &updated).await?;
*state = updated;
target
}
};
if session.cancel.load(Ordering::SeqCst) {
return Ok(Outcome::Cancelled);
}
let request = Launch {
environment: target.environment,
branch: target.branch,
prompt,
};
self.record(id, &session, JournalInput::Prompt(blocks), sink)
.await?;
{
let mut state = session.state.lock().await;
let mut updated = state.clone();
updated.uncertain_write = true;
self.journal.save(id, &updated).await?;
*state = updated;
}
let receipt = match (&previous.task, &previous.turn) {
(Some(task), Some(turn)) => {
self.probe
.follow_up(
&CloudId::new(task.clone())?,
&TurnId::new(turn.clone())?,
&request.prompt,
)
.await
}
(None, None) => self.probe.launch(&request).await,
_ => {
return Err(rootcause::report!(
"saved task has no assistant turn; inspect it before continuing"
));
}
};
let receipt = match receipt {
Ok(receipt) => receipt,
Err(error) => {
let message = error.format_current_context().to_string();
self.record(id, &session, JournalInput::SubmissionError(message), sink)
.await?;
return Err(error);
}
};
self.record(
id,
&session,
JournalInput::PromptAccepted {
task: receipt.task_id.as_str().to_owned(),
turn: receipt
.assistant_turn_id
.as_ref()
.map(|turn| turn.as_str().to_owned()),
},
sink,
)
.await?;
let task = receipt.task_id;
{
let mut state = session.state.lock().await;
let mut updated = state.clone();
updated.task = Some(task.as_str().to_owned());
updated.turn = receipt
.assistant_turn_id
.as_ref()
.map(|turn| turn.as_str().to_owned());
updated.uncertain_write = updated.turn.is_none();
self.journal.save(id, &updated).await?;
*state = updated;
}
let turn = receipt.assistant_turn_id.ok_or_else(|| {
rootcause::report!(
"provider created task without assistant turn; submission will not be retried"
)
})?;
if session.cancel.load(Ordering::SeqCst) {
self.probe.cancel(&task).await?;
}
let outcome = self.observe(id, session.clone(), task, turn, sink).await;
self.finish_events(&session, sink).await?;
outcome
}
async fn reserve_recovery(&self, id: &str) -> Result<Recovery, rootcause::Report> {
self.journal.validate().await?;
let session = self.session(id).await?;
let guard = loop {
let changed = session.changed.notified();
tokio::pin!(changed);
changed.as_mut().enable();
let guard = {
let mut recovering = session
.recovery_gate
.lock()
.expect("recovery gate poisoned");
if *recovering {
None
} else {
let guard = session
.turn_lock
.clone()
.try_lock_owned()
.map_err(|_| rootcause::report!("session is busy"))?;
*recovering = true;
Some(guard)
}
};
if let Some(guard) = guard {
break guard;
}
changed.await;
};
let recovery = Recovery {
session,
guard: Some(guard),
};
if recovery.session.state.lock().await.uncertain_write {
return Err(rootcause::report!(
"previous submission has an uncertain outcome; inspect cloud tasks before continuing"
));
}
Ok(recovery)
}
/// Replay and reserve the old turn before the client can send a new prompt.
pub async fn prepare_recovery(
&self,
id: &str,
sink: &impl SessionSink,
) -> Result<Recovery, rootcause::Report> {
let recovery = self.reserve_recovery(id).await?;
self.replay_entries(id, sink).await?;
self.metadata_changed.notify_one();
recovery
.session
.reload_pending
.store(false, Ordering::SeqCst);
recovery.session.changed.notify_waiters();
Ok(recovery)
}
/// Reattach observation to a durably recorded turn, never creating provider work.
pub async fn resume_observation(
&self,
id: &str,
sink: &impl SessionSink,
) -> Result<Option<Outcome>, rootcause::Report> {
let recovery = self.reserve_recovery(id).await?;
self.finish_recovery(id, recovery, sink).await
}
/// Observe the reserved turn while follow-up prompts wait for its verified outcome.
pub async fn finish_recovery(
&self,
id: &str,
recovery: Recovery,
sink: &impl SessionSink,
) -> Result<Option<Outcome>, rootcause::Report> {
let session = recovery.session.clone();
let state = session.state.lock().await.clone();
if state.uncertain_write {
return Err(rootcause::report!(
"previous submission has an uncertain outcome; inspect cloud tasks before continuing"
));
}
let (Some(task), Some(turn)) = (state.task, state.turn) else {
return Ok(None);
};
self.record(id, &session, JournalInput::RecoveryStarted, sink)
.await?;
let outcome = self
.observe(
id,
session.clone(),
CloudId::new(task)?,
TurnId::new(turn)?,
sink,
)
.await
.map(Some);
self.finish_events(&session, sink).await?;
if sink.recovered()? {
session.reload_pending.store(true, Ordering::SeqCst);
}
drop(recovery);
outcome
}
async fn observe(
&self,
id: &str,
session: Arc<Session>,
task: CloudId,
turn: TurnId,
sink: &impl SessionSink,
) -> Result<Outcome, rootcause::Report> {
let mut stream = match self.probe.stream(&task, &turn).await {
Ok(stream) => Some(stream),
Err(error) => {
let message = error.format_current_context().to_string();
self.record(id, &session, JournalInput::TransportError(message), sink)
.await?;
None
}
};
let mut reconnects = 0_u8;
let mut interval = tokio::time::interval(Duration::from_secs(5));
loop {
tokio::select! {
event = async { match &mut stream { Some(stream) => stream.next().await, None => std::future::pending().await } } => {
match event {
Some(Ok(event)) => {
self.observe_event(id, &session, &task, event, sink).await?;
}
Some(Err(error)) => { let message = error.format_current_context().to_string(); self.record(id, &session, JournalInput::TransportError(message), sink).await?; stream = None; }
None => { self.record(id, &session, JournalInput::TransportError("stream ended".into()), sink).await?; stream = None; }
}
}
_ = interval.tick() => {
self.journal.validate().await?;
let mut snapshot = self.probe.turn(&task, &turn).await?;
let native = snapshot.native.take();
self.record(id, &session, JournalInput::Poll { snapshot: snapshot.clone(), native }, sink).await?;
match snapshot.assistant_status.as_deref() {
Some("completed") => {
// A terminal snapshot can race queued SSE records; drain available
// history before reconciling the authoritative final message.
if let Some(active) = &mut stream {
let drain = async {
while let Some(Ok(event)) = active.next().await {
self.observe_event(id, &session, &task, event, sink).await?;
}
Ok::<(), rootcause::Report>(())
};
if let Ok(result) = tokio::time::timeout(Duration::from_secs(2), drain).await { result?; }
}
// The completed replay can expose records absent from the live
// stream. Stable outer IDs suppress records already journaled.
if let Ok(mut replay) = self.probe.stream(&task, &turn).await {
let drain = async {
while let Some(Ok(event)) = replay.next().await { self.observe_event(id, &session, &task, event, sink).await?; }
Ok::<(), rootcause::Report>(())
};
if let Ok(result) = tokio::time::timeout(Duration::from_secs(2), drain).await { result?; }
}
self.record(id, &session, JournalInput::Terminal("completed".into()), sink).await?;
return Ok(Outcome::Completed);
}
Some("cancelled") => { self.record(id, &session, JournalInput::Terminal("cancelled".into()), sink).await?; return Ok(Outcome::Cancelled); },
Some("failed") => { self.record(id, &session, JournalInput::Terminal("failed".into()), sink).await?; return Err(rootcause::report!("cloud assistant turn failed")); },
_ => {
if stream.is_none() && reconnects < 3 {
reconnects += 1;
stream = self.probe.stream(&task, &turn).await.ok();
}
}
}
}
}
}
}
}
#[cfg(test)]
mod test;