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.

17.2 KB
Raw Blame
//! Unconfirmed client actions folded on a fork of the confirmed history.
//!
//! A client that issues an action knows exactly which frame the harness will
//! log for it, because the harness builds that frame with
//! [`AgentAction::to_runtime`] and this module builds its copy the same way.
//! So the fold can show the action's effect before the log confirms it:
//! the confirmed machine stays authoritative, and the unconfirmed frames form
//! a *suffix* replayed on a clone of it. Three things can then happen to a
//! suffix entry:
//!
//! - **Promote.** A confirmed row matches it - same request id, or for a
//!   frame that carries none the same method or content - and the entry is
//!   dropped. The committed machine now derives what the fork already
//!   showed, minus the pending mark.
//! - **Rebase.** A confirmed row matches nothing while the suffix is
//!   non-empty. It belongs *before* the suffix, so the fork is rebuilt:
//!   clone the committed machine, replay the suffix.
//! - **Retract.** The caller learns the server will never log it (the POST
//!   failed, the control was rejected) and the suffix loses it. Rebase.
//!
//! Only frames this client causes are ever synthesized. What the runtime
//! answers is never predicted: a speculated stop renders as stopping and a
//! speculated prompt as starting, and the turn closes when the log says so.
//!
//! Think of a git rebase: the confirmed log is upstream, the suffix is the
//! local commits replayed on top, and each one disappears the moment upstream
//! contains it.

use std::borrow::Cow;

use agent_client_protocol::RawJsonRpcMessage;
use agent_client_protocol::schema::v1::SessionId;
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId};
use agent_runtime_protocol::domain::schema::v0::ToRuntimeMessage;
use macro_user_id::user_id::MacroUserIdStr;

use super::fold::FoldMachineImpl;
use super::ingestion::{LogCursor, LogIngestion};
use super::log::{AgentSessionId, AgentSessionLog, Message};
use super::model::{FoldEvent, FoldedMessage, SessionMetadata};

#[cfg(test)]
mod test;

/// The ACP session id a synthesized frame names before the log has shown the
/// real one - a first prompt into a session whose runtime is still booting.
/// The fold's handlers ignore it; only the replay gate reads it, and that gate
/// is closed while nothing has been opened yet. The confirmed frame carries
/// the real id and promotes by request id - or, for a stop, by method - so
/// the placeholder never sticks.
const PLACEHOLDER_ACP_SESSION: &str = "pending";

/// One thing that can happen to a client's view of a session log.
#[derive(Debug)]
pub enum FoldInput {
    /// Authoritative history from the top of the log. Resets the committed
    /// tier, drops every suffix entry the rows already confirm, and rebuilds
    /// the fork. Must come first; a fresh fold refuses everything else.
    Snapshot(Vec<(LogCursor, AgentSessionLog)>),
    /// One durable row, in delivery order.
    Confirmed(LogCursor, AgentSessionLog),
    /// An action this client issued that the log has not confirmed.
    Speculated(Speculation),
    /// An action the server will never log: the request that carried it
    /// failed, or the control was refused.
    Retracted(AgentActionId),
}

/// An action to fold before the log confirms it.
#[derive(Debug, Clone)]
pub struct Speculation {
    action_id: AgentActionId,
    action: AgentAction,
    user_id: Option<MacroUserIdStr<'static>>,
}

impl Speculation {
    /// An action under the id the client will send it with. The id is what a
    /// confirmed row is matched on where the wire carries one; a stop and an
    /// elicitation answer carry no id, and are matched as described on
    /// [`Pending::is_confirmed_by`].
    #[must_use]
    pub fn new(
        action_id: AgentActionId,
        action: AgentAction,
        user_id: Option<MacroUserIdStr<'static>>,
    ) -> Self {
        Self {
            action_id,
            action,
            user_id,
        }
    }
}

/// Why an input could not be folded.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum SpeculationError {
    /// A live or speculative frame arrived before any snapshot. Folding from
    /// the middle of a log derives a session that never happened, so the
    /// caller has to fetch first.
    #[error("the fold has no snapshot yet; a snapshot must be the first input")]
    NoSnapshot,
    /// The action could not be encoded as the frame the harness would log.
    #[error("the action could not be encoded as an ACP frame: {0}")]
    Encode(String),
}

/// A confirmed fold with this client's unconfirmed actions replayed on top.
///
/// [`Self::messages`] and [`Self::metadata`] read the fork while anything is
/// pending and the committed machine otherwise, so a reader never sees two
/// machines - only one conversation that occasionally gets ahead of the log.
pub struct SpeculativeFold {
    session: AgentSessionId,
    /// Everything the durable log has confirmed.
    committed: LogIngestion,
    /// Whether a snapshot has been folded. Nothing else is accepted before.
    snapshotted: bool,
    /// Frames this client caused that the log has not confirmed, in order.
    suffix: Vec<Pending>,
    /// `committed` plus `suffix`. `None` whenever the suffix is empty.
    fork: Option<FoldMachineImpl>,
}

/// One suffix entry: the frame as it was folded, and what a confirmed row
/// has to look like to be it.
#[derive(Debug, Clone)]
struct Pending {
    action_id: AgentActionId,
    frame: AgentSessionLog,
}

impl Pending {
    /// Whether `row` is the log's confirmation of this entry.
    ///
    /// A request carries the action id on the wire, so it matches on that
    /// alone: the harness composes prompts (mentions, context) after
    /// accepting them, so the confirmed text may legitimately differ from
    /// what was speculated, and the confirmed content wins.
    ///
    /// A notification - a stop - carries no id, and its content is no help
    /// either: `session/cancel` is byte-identical for every stop in a
    /// session, and one speculated before the log showed the ACP session
    /// names [`PLACEHOLDER_ACP_SESSION`] where the confirmed frame names the
    /// real id, so full content never matches. It matches on the method
    /// instead, and on the user where both rows name one.
    ///
    /// Everything else - an elicitation answer, which is a response on the
    /// agent's own request id - matches on content, which is deterministic:
    /// the agent's id plus the answer, encoded the one way
    /// [`AgentAction::to_runtime`] encodes it.
    fn is_confirmed_by(&self, row: &AgentSessionLog) -> bool {
        if let Some(id) = request_action_id(row) {
            return id == self.action_id;
        }
        if request_action_id(&self.frame).is_some() {
            return false;
        }
        match (notification_method(&self.frame), notification_method(row)) {
            (Some(mine), Some(theirs)) => mine == theirs && self.same_user_as(row),
            _ => {
                serde_json::to_value(&self.frame.content).ok()
                    == serde_json::to_value(&row.content).ok()
            }
        }
    }

    /// Whether `row` was issued by whoever issued this entry. A row that
    /// names no user cannot contradict one that does, so it is accepted.
    fn same_user_as(&self, row: &AgentSessionLog) -> bool {
        match (&self.frame.user_id, &row.user_id) {
            (Some(mine), Some(theirs)) => mine == theirs,
            _ => true,
        }
    }
}

/// The method of a notification frame, if the row is one.
fn notification_method(row: &AgentSessionLog) -> Option<&str> {
    match &row.content {
        Message::ToRuntime(ToRuntimeMessage::Acp(acp))
        | Message::Notification(ToRuntimeMessage::Acp(acp)) => match &acp.0 {
            RawJsonRpcMessage::Notification(notification) => Some(notification.method.as_ref()),
            _ => None,
        },
        _ => None,
    }
}

/// The action id a runtime-bound request carries, if the row is one.
fn request_action_id(row: &AgentSessionLog) -> Option<AgentActionId> {
    match &row.content {
        Message::ToRuntime(ToRuntimeMessage::Acp(acp))
        | Message::Notification(ToRuntimeMessage::Acp(acp)) => match &acp.0 {
            RawJsonRpcMessage::Request(request) => AgentActionId::from_request_id(&request.id),
            _ => None,
        },
        _ => None,
    }
}

impl SpeculativeFold {
    /// A fold for `session` that has seen nothing. The first input must be a
    /// [`FoldInput::Snapshot`].
    #[must_use]
    pub fn new(session: AgentSessionId) -> Self {
        Self {
            session,
            committed: LogIngestion::default(),
            snapshotted: false,
            suffix: Vec::new(),
            fork: None,
        }
    }

    /// Every message as the reader should see it: the fork's while anything
    /// is pending, the committed machine's otherwise.
    #[must_use]
    pub fn messages(&self) -> &[FoldedMessage] {
        self.tier().messages()
    }

    /// Session metadata, from the same tier as [`Self::messages`].
    #[must_use]
    pub fn metadata(&self) -> &SessionMetadata {
        self.tier().metadata()
    }

    /// The action ids still waiting on the log.
    pub fn pending(&self) -> impl Iterator<Item = AgentActionId> + '_ {
        self.suffix.iter().map(|pending| pending.action_id)
    }

    fn tier(&self) -> &FoldMachineImpl {
        self.fork.as_ref().unwrap_or(&self.committed.machine)
    }

    /// Fold one input, reporting what it changed in the same vocabulary a
    /// plain machine push does. A rebase or snapshot reports
    /// [`FoldEvent::MessagesReplaced`]; everything else reports only what
    /// moved, which for a promotion is the confirmed message losing its
    /// pending mark.
    ///
    /// # Errors
    ///
    /// See [`SpeculationError`].
    pub fn push(&mut self, input: FoldInput) -> Result<Vec<FoldEvent<'_>>, SpeculationError> {
        match input {
            FoldInput::Snapshot(rows) => {
                self.snapshotted = true;
                for (_, row) in &rows {
                    self.settle(row);
                }
                self.committed.replace_snapshot(rows);
                Ok(self.rebase())
            }
            FoldInput::Confirmed(cursor, row) => {
                if !self.snapshotted {
                    return Err(SpeculationError::NoSnapshot);
                }
                let promoted = self.settle(&row);
                if self.suffix.is_empty() {
                    // Nothing pending after this row: the fork, if any, is
                    // now redundant and the committed machine's own report
                    // describes the change - for a promotion, the message
                    // the reader already has, minus its pending mark.
                    self.fork = None;
                    let events: Vec<FoldEvent<'static>> = self
                        .committed
                        .push(cursor, row)
                        .into_iter()
                        .map(FoldEvent::into_owned)
                        .collect();
                    // A promoted row the snapshot already held reports
                    // nothing from the machine, yet the reader still shows
                    // the fork's pending message: restate the committed view.
                    if promoted && events.is_empty() {
                        return Ok(self.replaced());
                    }
                    return Ok(events);
                }
                let _ = self.committed.push(cursor, row);
                Ok(self.rebase())
            }
            FoldInput::Speculated(speculation) => {
                if !self.snapshotted {
                    return Err(SpeculationError::NoSnapshot);
                }
                // The log got there first: the confirmed row can land over
                // the socket before the control response names its id, and
                // a client re-speculating under that id must not double it.
                if self.already_reflected(&speculation) {
                    return Ok(Vec::new());
                }
                let frame = self.synthesize(&speculation)?;
                let fork = self
                    .fork
                    .get_or_insert_with(|| self.committed.machine.clone());
                let events: Vec<FoldEvent<'static>> = fork
                    .push_speculative(frame.clone())
                    .into_iter()
                    .map(FoldEvent::into_owned)
                    .collect();
                self.suffix.push(Pending {
                    action_id: speculation.action_id,
                    frame,
                });
                Ok(events)
            }
            FoldInput::Retracted(action_id) => {
                let before = self.suffix.len();
                self.suffix.retain(|pending| pending.action_id != action_id);
                if self.suffix.len() == before {
                    return Ok(Vec::new());
                }
                Ok(self.rebase())
            }
        }
    }

    /// The frame the harness will log for `speculation`, built the way the
    /// harness builds it.
    fn synthesize(&self, speculation: &Speculation) -> Result<AgentSessionLog, SpeculationError> {
        let acp_session = self
            .committed
            .machine
            .acp_session_id()
            .cloned()
            .unwrap_or_else(|| SessionId::from(PLACEHOLDER_ACP_SESSION));
        let message = speculation
            .action
            .to_runtime(&acp_session, speculation.action_id.to_request_id())
            .map_err(|error| SpeculationError::Encode(error.to_string()))?;
        Ok(AgentSessionLog {
            agent_session_id: self.session,
            user_id: speculation.user_id.clone(),
            content: Message::ToRuntime(message),
            logged_at: None,
        })
    }

    /// Whether the fold already shows what this speculation would add, so
    /// folding it again would only double it.
    ///
    /// A prompt, a compact and a model change carry their action id on the
    /// wire, so the committed fold answers for them directly - and only the
    /// committed fold, because a second prompt while one is still pending is
    /// an ordinary queued prompt, not a duplicate.
    ///
    /// A stop and an elicitation answer carry no action id, so each is
    /// recognized by the effect it has already had, on the fork as much as on
    /// the committed machine: two of either add nothing the first did not,
    /// and a second suffix entry that nothing distinguishes would outlive the
    /// one confirmed row that could settle it.
    fn already_reflected(&self, speculation: &Speculation) -> bool {
        match &speculation.action {
            AgentAction::Stop => self.tier().stop_requested(),
            AgentAction::RespondElicitation(answer) => {
                !self.tier().metadata().pending_elicitation().is_some_and(|pending| pending.request_id == answer.request_id)
                    && self.tier().elicitation_answered(&answer.request_id)
            }
            AgentAction::RespondToPermission(answer) => !self.tier().metadata().pending_interactions.iter().any(|pending| {
                matches!(pending, super::model::PendingInteraction::Permission(permission)
                    if permission.request_id == super::model::AgentRequestId::from(&answer.request_id))
            }) && self
                .tier()
                .messages()
                .iter()
                .flat_map(|message| message.parts.iter())
                .any(|part| {
                    matches!(part,
                        super::model::MessagePart::Permission { request_id, outcome, .. }
                            if *request_id == super::model::AgentRequestId::from(&answer.request_id)
                                && !matches!(outcome, super::model::PermissionOutcome::Pending)
                    )
                }),
            AgentAction::Prompt(_) | AgentAction::Compact | AgentAction::SetModel(_) | AgentAction::SetConfigOption(_) => self
                .committed
                .machine
                .messages()
                .iter()
                .any(|message| message.request_id == Some(speculation.action_id)),
        }
    }

    /// Drop the suffix entry `row` confirms, if any. `true` when one was.
    fn settle(&mut self, row: &AgentSessionLog) -> bool {
        let Some(index) = self
            .suffix
            .iter()
            .position(|pending| pending.is_confirmed_by(row))
        else {
            return false;
        };
        self.suffix.remove(index);
        true
    }

    /// Rebuild the fork from the committed machine and the suffix, and report
    /// the whole view - the only honest report when what changed is "where
    /// the suffix sits".
    fn rebase(&mut self) -> Vec<FoldEvent<'_>> {
        if self.suffix.is_empty() {
            self.fork = None;
        } else {
            let mut fork = self.committed.machine.clone();
            for pending in &self.suffix {
                let _ = fork.push_speculative(pending.frame.clone());
            }
            self.fork = Some(fork);
        }
        self.replaced()
    }

    fn replaced(&self) -> Vec<FoldEvent<'_>> {
        vec![
            FoldEvent::MessagesReplaced(Cow::Borrowed(self.messages())),
            FoldEvent::MetadataUpdated(Cow::Borrowed(self.metadata())),
        ]
    }
}