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.

34.1 KB
Raw Blame
use agent_client_protocol::schema::v1::SessionId;
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;
use macro_uuid::Uuid;
use model_owner::Owner;

use super::error::AgentSessionError;

// The log vocabulary - the session id, the log entry, and the frame it
// carries - is owned by `agent_fold`, the bottom of the agent session stack,
// so that this crate can depend on the fold (see `agent_fold::domain::log`).
// Re-exported here because this is where callers expect session types.
pub use super::sandbox_size::SandboxSize;
pub use agent_fold::domain::log::{AgentSessionId, AgentSessionLog, Message};
pub use agent_fold::domain::model::{
    Author, AuthorKind, FoldEvent, MessageId, OwnedFoldEvent, TurnId,
};

/// The `_meta` key on `session/new`, `session/load` and `session/resume`
/// whose string value is the [`AgentSessionId`] the ACP session serves.
pub const MACRO_AGENT_SESSION_META_KEY: &str = "macro.com/agentSessionId";

/// The `_meta` key on `session/new`, `session/load` and `session/resume`
/// whose string value is how the session answers permission requests
/// (`autoAccept` or `prompt`), so a runtime can tell its agent.
pub const MACRO_PERMISSION_POLICY_META_KEY: &str = "macro.com/permissionPolicy";

/// Identity of one harness participant, minted fresh at construction.
///
/// A restarted process is a new replica: whatever the old identity claimed is
/// released by its heartbeat going stale, never inherited.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ReplicaId(Uuid);

impl ReplicaId {
    /// Mint a fresh replica identity.
    #[must_use]
    pub fn mint() -> Self {
        Self(Uuid::new_v4())
    }

    /// The raw uuid, for persistence.
    #[must_use]
    pub fn as_uuid(&self) -> Uuid {
        self.0
    }

    /// Rebuild an identity from its persisted uuid.
    #[must_use]
    pub fn from_uuid(id: Uuid) -> Self {
        Self(id)
    }
}

impl std::fmt::Display for ReplicaId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.0.fmt(f)
    }
}

/// A replica's own base URL, as peers should dial it for command forwarding.
///
/// Private-network address discovered by the replica itself at boot (the ECS
/// task metadata endpoint in deployments), published with its heartbeat.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReplicaAddress(String);

impl ReplicaAddress {
    /// Wrap a base URL, e.g. `http://10.0.1.7:8100`.
    #[must_use]
    pub fn new(address: impl Into<String>) -> Self {
        Self(address.into())
    }

    /// The base URL as a string.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl std::fmt::Display for ReplicaAddress {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.0.fmt(f)
    }
}

/// The live manager of a session, as read from the lease.
#[derive(Debug, Clone)]
pub struct SessionManager {
    /// The replica holding the claim.
    pub replica: ReplicaId,
    /// Where to forward its commands, when the replica has published one.
    /// `None` means the manager is live but unreachable - hold the error
    /// rather than execute somewhere the actor is not.
    pub address: Option<ReplicaAddress>,
    /// Whether the holder has published that it is shutting down. Still
    /// heartbeating, so still "live" by the lease's own liveness rule, but
    /// no longer somewhere to send work.
    pub draining: bool,
}

/// What the lease says about a session, seen from one replica.
#[derive(Debug, Clone)]
pub struct LeaseView {
    /// The replica holding the lease, when a live one holds it - draining
    /// or not, because who may take over from a draining holder is the
    /// reader's decision, not the store's.
    pub holder: Option<SessionManager>,
    /// Whether the replica that asked has published that it is draining.
    /// Asked in the same statement as the holder: a command's routing turns
    /// on both, and two round trips could straddle the drain.
    pub asking_replica_draining: bool,
}

/// Where a session's live actor runs, from one service instance's viewpoint.
#[derive(Debug, Clone)]
pub enum SessionManagement {
    /// No live replica manages the session; this instance may claim it by
    /// attaching, so commands execute locally.
    Unmanaged,
    /// This instance's replica manages it; commands execute locally.
    Ours,
    /// A live peer manages it; commands belong at its address.
    Peer(SessionManager),
    /// This instance is draining: it is about to stop, so work sent here
    /// would die with it. Commands belong on a replica that is staying.
    Draining,
}

/// A session's takeover counter, bumped by every successful claim.
///
/// Carried by the claim holder into each live-actor write; the store rejects
/// writes whose fence has been superseded, so a stale holder is neutralized
/// by the same statement that would have written (a fencing token).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct ManagerFence(pub i64);

/// Proof that this replica claimed a session's live management.
///
/// Obtained only from [`SessionOwnership::claim`](super::ports::SessionOwnership::claim);
/// holding one is what entitles an actor to attach and write the session's
/// log under its fence.
#[derive(Debug, Clone, Copy)]
pub struct SessionClaim {
    /// The claimed session.
    pub session: AgentSessionId,
    /// The replica holding the claim.
    pub replica: ReplicaId,
    /// The fence this claim writes under.
    pub fence: ManagerFence,
}

/// What claiming a session yielded.
#[derive(Debug, Clone, Copy)]
pub enum ClaimOutcome {
    /// This replica now manages the session.
    Claimed(SessionClaim),
    /// A replica with a fresh heartbeat already manages it. Until command
    /// forwarding exists this surfaces as an error; with it, commands are
    /// routed to the named replica instead.
    ManagedElsewhere(ReplicaId),
}

/// Display name assigned to a newly created agent session.
pub const DEFAULT_AGENT_SESSION_NAME: &str = "Agent Session";

/// Maximum number of Unicode scalar values in a session name.
pub const MAX_AGENT_SESSION_NAME_CHARS: usize = 100;

#[derive(Debug, Clone, Default, PartialEq, Eq, strum::AsRefStr)]
#[strum(serialize_all = "snake_case")]
pub enum SessionStatus {
    /// No status updates received.
    #[default]
    NoMessages,
    /// The latest status received from the container.
    Event(SystemEvent),
    /// The session disconnected without sending a closed event.
    Disconnected,
}

/// Which Pipedream MCP servers a session is handed: the agent's own choice,
/// plus any apps a routine requires, snapshotted onto the session at creation
/// like `instructions`. The servers
/// it resolves to are re-listed before each prompt, so an app the owner
/// connects mid-session reaches a live agent that can `session/resume`;
/// editing the agent's selection applies to its next session.
pub use bots::domain::models::{AgentMcpServer, AgentMcpServers};

/// Why a session is created, which decides where it is shown.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionPurpose {
    /// A regular session opened directly or from a thread mention.
    Standalone,
    /// An unprompted speculative runtime, eligible for warm claim and expiry.
    Warm,
    /// Context backing an agent DM; accessed through its conversation.
    AgentDm,
    /// A session another agent dispatched on its owner's behalf. Listed, and
    /// it notifies like the owner's own sessions.
    Dispatched,
    /// A routine's unattended run. Its successful turns notify nobody, and
    /// the routine's setting decides whether it is listed.
    Routine {
        /// Listed or unlisted, from the routine's setting.
        visibility: SessionVisibility,
    },
}

impl SessionPurpose {
    /// Validate speculative creation against durable conversation provenance.
    /// A legacy standalone caller naming a reserved context adopts DM policy.
    pub fn for_creation(
        self,
        conversation: bool,
        has_message: bool,
    ) -> Result<Self, AgentSessionError> {
        if self == Self::Warm && (conversation || has_message) {
            return Err(AgentSessionError::InvalidSessionPurpose);
        }
        Ok(if conversation { Self::AgentDm } else { self })
    }

    /// Where a session created for this purpose is shown. Speculative,
    /// DM-backing and thread sessions (any agent started by a mention or an
    /// assignment in a thread) are reached through what they back, so they
    /// are hidden until someone prompts them directly (see
    /// [`AgentSessionRepo::add_follower`](super::ports::AgentSessionRepo::add_follower));
    /// a routine's run follows its routine.
    pub fn visibility(self, thread_id: Option<Uuid>, hide_agent_dms: bool) -> SessionVisibility {
        let hidden = match self {
            Self::Warm => true,
            Self::AgentDm => hide_agent_dms,
            Self::Standalone => thread_id.is_some(),
            Self::Dispatched => false,
            Self::Routine { visibility } => return visibility,
        };
        if hidden {
            SessionVisibility::Hidden
        } else {
            SessionVisibility::Listed
        }
    }

    /// Who starts a session created for this purpose.
    pub fn source(self) -> SessionSource {
        match self {
            Self::Dispatched => SessionSource::Agent,
            Self::Routine { .. } => SessionSource::Routine,
            Self::Standalone | Self::Warm | Self::AgentDm => SessionSource::User,
        }
    }
}

/// Who started a session. Stored on the session and carried by its lifecycle
/// events, so lists and notifications can treat unattended runs differently.
#[derive(
    Debug,
    Clone,
    Copy,
    Default,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    strum::EnumString,
    strum::IntoStaticStr,
)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum SessionSource {
    /// A person, directly or through something they did: a prompt, a
    /// mention, or an assignment.
    #[default]
    User,
    /// Another agent, which dispatched the session on its owner's behalf.
    Agent,
    /// A routine's unattended run.
    Routine,
}

/// Where a session is shown. Stored as `agent_session.visibility`, which
/// replaces `list_hidden` (`Hidden`); a trigger keeps that column in step until
/// it is dropped.
#[derive(
    Debug,
    Clone,
    Copy,
    Default,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    strum::EnumString,
    strum::IntoStaticStr,
)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum SessionVisibility {
    /// Shown wherever the owner's sessions are.
    #[default]
    Listed,
    /// Left out of Home and the default Agents list, but a filter can still
    /// ask for it: a routine's run, unless the routine lists its runs.
    Unlisted,
    /// Out of every list and search; reachable only by id, through what it
    /// backs (a thread, a DM) or once a warm claim lists it.
    Hidden,
}

/// Caller-provided values required to create an agent session.
#[derive(Debug, Clone)]
pub struct CreateAgentSessionParams {
    /// Creation policy for visibility and speculative runtime lifecycle.
    pub purpose: SessionPurpose,
    /// Caller-minted session id, available before persistence.
    pub id: AgentSessionId,
    /// Who created and owns the session.
    pub owner_id: Owner,
    /// Bot running the agent.
    pub bot_id: BotId,
    /// Root message identifying the originating thread, if any.
    pub thread_id: Option<Uuid>,
    /// Exact message that invoked the bot, if any.
    pub originating_message_id: Option<Uuid>,
    /// Model slug.
    pub model: String,
    /// Harness slug.
    pub harness: String,
    /// Repository the agent works with, when one was stated.
    pub repo_url: Option<String>,
    /// Starting branch explicitly selected for this session.
    pub repo_branch: Option<super::repository_branch::RepositoryBranch>,
    /// Absolute directory the harness runs in on its runtime.
    pub workspace: String,
    /// Compute tier the managed sandbox was spawned with.
    pub sandbox_size: SandboxSize,
    /// Instructions the session's runtime works under, when any were stated.
    ///
    /// Snapshotted here rather than resolved per turn because they are the
    /// runtime's system prompt: how a harness is handed them differs by
    /// provider, but every provider needs the same answer for the session's
    /// whole life.
    pub instructions: Option<String>,
    /// Which MCP servers the session is handed; see [`AgentMcpServers`].
    pub mcp_servers: AgentMcpServers,
    /// SHA-256 hex of the opaque token the session's sandbox presents to the
    /// egress proxy, or `None` for a session that never gets one.
    ///
    /// The hash and never the token: this row is the only durable record of
    /// the credential, and a database dump must not yield a live one. A session
    /// replayed from a recording, or created without a sandbox, has nothing to
    /// store here.
    pub egress_token_hash: Option<String>,
    /// What opened the session, written with the session's row. `Unknown`
    /// writes nothing: an unclaimed warm session has no cause yet.
    pub origin: trigger_context::TriggerOrigin,
}

/// Who or what archived a session.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    strum::AsRefStr,
    strum::EnumString,
    serde::Serialize,
    serde::Deserialize,
)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum ArchiveCause {
    /// A person archived it.
    User,
    /// Every pull request linked to it closed, with at least one merged.
    PullRequestMerged,
    /// The runtime session backing it was deliberately closed.
    RuntimeClosed,
}

/// A session's archive.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SessionArchive {
    /// Who or what archived it.
    pub by: ArchiveCause,
    /// When it was archived.
    pub at: DateTime<Utc>,
}

/// A running or historical agent coding session.
#[derive(Debug, Clone)]
pub struct AgentSession {
    /// id of the agent session
    pub id: AgentSessionId,
    /// User-facing session name.
    pub name: String,
    /// Who archived the session and when, or `None` while it is active. An archived session
    /// is read-only.
    pub archived: Option<SessionArchive>,
    /// Who created and owns the session. Immutable for its life.
    pub owner_id: Owner,
    /// The root message where the bot was originally invoked, if any.
    pub thread_id: Option<Uuid>,
    /// Entity owning the originating thread, derived from its root message.
    /// The persisted message parent is authoritative for routing and access.
    pub thread_parent: Option<messages::domain::models::MessageParent>,
    /// The exact message that originally invoked the bot, if any.
    pub originating_message_id: Option<Uuid>,
    /// the bot id of the bot running the agent
    pub bot_id: BotId,
    /// model slug - TODO: probably a better type here
    pub model: String,
    /// harness slug - TODO: probably a better type here
    pub harness: String,
    /// repo we are working with, when one was stated
    pub repo_url: Option<String>,
    /// Starting branch explicitly selected for this session.
    pub repo_branch: Option<super::repository_branch::RepositoryBranch>,
    /// The pull request associated with this session, independent of conversation history.
    pub pull_request_url: Option<String>,
    /// The Macro task the session was explicitly linked to.
    pub task_id: Option<String>,
    /// Who started the session.
    pub source: SessionSource,
    /// What opened the session. `Unknown` when nothing recorded it.
    pub origin: trigger_context::TriggerOrigin,
    /// Where the session is shown.
    pub visibility: SessionVisibility,
    /// Directory the harness runs in, snapshotted at creation. The session
    /// actor sends it as the working directory of `session/new`, and resume
    /// and load re-enter it - the directory the session actually ran in,
    /// not whatever the runtime is configured with today.
    pub workspace: String,
    /// Compute tier of the managed sandbox, snapshotted at spawn.
    pub sandbox_size: SandboxSize,
    /// Instructions the session's runtime works under, snapshotted at
    /// creation. Immutable for the session's life; `None` when none were
    /// stated.
    pub instructions: Option<String>,
    /// Which MCP servers the session is handed, snapshotted at creation.
    pub mcp_servers: AgentMcpServers,
    /// ACP session if we have one
    pub acp_session_id: Option<SessionId>,
    /// The provider-side identity, when an external provider serves this
    /// session. `None` for sandboxed sessions and for external sessions
    /// whose agent has not been minted yet.
    pub external: Option<ExternalSession>,
    pub status: SessionStatus,
    pub created_at: DateTime<Utc>,
    pub modified_at: DateTime<Utc>,
}

impl AgentSession {
    /// Whether the session is archived and therefore read-only.
    pub fn is_archived(&self) -> bool {
        self.archived.is_some()
    }

    /// The user this session runs as; see [`session_owner_user`].
    pub fn owner_user(&self) -> Result<&MacroUserIdStr<'static>, AgentSessionError> {
        self.owner_id
            .as_user()
            .ok_or_else(|| AgentSessionError::OwnerNotUser(self.owner_id.owner_type()))
    }
}

/// The user a session runs as.
///
/// A session spends its owner's credentials and bills them, so only a user
/// can own one until the runtime has a bot execution context.
// TODO(ownership-v2): T5.4 admits bot owners once the runtime has a bot execution context.
pub fn session_owner_user(owner: &Owner) -> Result<MacroUserIdStr<'static>, AgentSessionError> {
    owner
        .as_user()
        .cloned()
        .ok_or_else(|| AgentSessionError::OwnerNotUser(owner.owner_type()))
}

/// A persisted agent-session name changed and should be shown to live viewers.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AgentSessionRenamed {
    /// Renamed session.
    pub agent_session_id: AgentSessionId,
    /// New user-facing name.
    pub name: String,
}

/// The provider-side identity of a session served by an external provider.
///
/// For a Cursor-backed session this is the cloud agent: its `bc-…` id, the
/// display name Cursor derived from the prompt, and its page on cursor.com.
/// The stored row is the only durable record of the mapping — Cursor's API
/// has no labels to recover it from — which is why this exists as data
/// rather than being re-derived.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExternalSession {
    /// Which provider serves the session, e.g. `cursor`.
    pub provider: String,
    /// The provider's id for the agent, e.g. `bc-…`.
    pub external_id: String,
    /// The provider's display name for the agent, when it reported one.
    pub external_name: Option<String>,
    /// The agent's page on the provider's site, for opening it there.
    pub external_url: Option<String>,
    /// The last provider run whose output was delivered to this session.
    pub last_run_id: Option<String>,
}

/// The agent behind a session, as much of it as rendering a message needs.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SessionBot {
    /// The bot's id. A message it sent has `"bot|{id}"` as its sender.
    pub id: BotId,
    /// Display name.
    pub name: String,
    /// Stable `@` handle, without a leading `@`.
    pub handle: String,
    /// Avatar, when it has one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub avatar_url: Option<String>,
}

/// The authority behind an invocation. System events never borrow owner access.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, strum::AsRefStr)]
#[strum(serialize_all = "snake_case")]
pub enum PrompterKind {
    /// A human or runtime prompt; user identifies any acting human.
    #[default]
    User,
    /// An internal event with no user authority.
    System,
}

/// Who prompted the turn a session is running, or last ran.
///
/// Written at dispatch, before the runtime can act on the prompt, so the
/// egress proxy - which may be on any replica - can tell a turn the owner
/// prompted from one somebody else did.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TurnPrompter {
    /// Source of the turn's authority.
    pub kind: PrompterKind,
    /// The action that opened the turn.
    pub action_id: agent_runtime_protocol::domain::action::AgentActionId,
    /// The user who prompted it, absent when a bot acted on nobody's behalf.
    pub user: Option<MacroUserIdStr<'static>>,
}

impl TurnPrompter {
    /// Effective human authority. System turns never act as a user even if
    /// malformed or old storage includes a user alongside the system kind.
    pub fn acting_user(&self) -> Option<&MacroUserIdStr<'static>> {
        (self.kind == PrompterKind::User)
            .then_some(self.user.as_ref())
            .flatten()
    }
}

/// One waiting action as the session store records it.
///
/// The harness keeps an in-memory working copy beside the live actor; this
/// is the durable form a restart or a reader on another replica consults.
/// `announce` is the harness's channel/document origin, stored as JSON so
/// this crate does not depend on harness types.
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StoredQueuedAction {
    /// The id the action was accepted under.
    pub action_id: agent_runtime_protocol::domain::action::AgentActionId,
    /// What will be delivered - a prompt's text is the raw user text.
    pub action: agent_runtime_protocol::domain::action::AgentAction,
    /// The user who queued it, absent when a bot acted on nobody's behalf.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub actor: Option<MacroUserIdStr<'static>>,
    /// When it was accepted.
    pub created_at: DateTime<Utc>,
    /// Harness announce origin, opaque to this crate.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub announce: Option<serde_json::Value>,
    /// Chip message id, once posted, so a retry does not announce twice.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub announced_message_id: Option<Uuid>,
    /// Why the agent is being asked, composed into the prompt at dispatch.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub context: Option<trigger_context::TriggerContext>,
}

impl From<&StoredQueuedAction> for super::ports::QueuedControl {
    fn from(stored: &StoredQueuedAction) -> Self {
        Self {
            action_id: stored.action_id,
            action: stored.action.clone(),
            actor: stored.actor.clone(),
            created_at: stored.created_at,
        }
    }
}

/// One action waiting in a session's queue.
///
/// Clients deserialize this, so both derives are used.
// Domain-owned because the queue GET endpoint and the realtime snapshot
// serialize this type byte-identically; that identity is the client contract.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct QueuedActionDto {
    /// The id the action was accepted under.
    pub action_id: agent_runtime_protocol::domain::action::AgentActionId,
    /// What kind of action waits - `prompt` or `compact`; only
    /// turn-occupying actions are ever queued.
    pub kind: String,
    /// The prompt's raw text, present for prompts only. What an edit
    /// replaces.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prompt: Option<String>,
    /// Files the prompt refers to, for prompts only. Kept through an edit,
    /// which replaces the text alone.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub attachments: Vec<agent_runtime_protocol::domain::action::PromptAttachment>,
    /// The user who queued it, absent when a bot acted on nobody's behalf.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub actor_user_id: Option<String>,
    /// When it was accepted.
    pub created_at: DateTime<Utc>,
}

impl From<super::ports::QueuedControl> for QueuedActionDto {
    fn from(queued: super::ports::QueuedControl) -> Self {
        use agent_runtime_protocol::domain::action::AgentAction;
        let (prompt, attachments) = match &queued.action {
            AgentAction::Prompt(action) => {
                (Some(action.prompt.clone()), action.attachments.clone())
            }
            _ => (None, Vec::new()),
        };
        Self {
            action_id: queued.action_id,
            kind: queued.action.as_ref().to_owned(),
            prompt,
            attachments,
            actor_user_id: queued.actor.map(|actor| actor.to_string()),
            created_at: queued.created_at,
        }
    }
}

/// 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
/// for a reader arriving late, this is the frames a reader already here has
/// not seen yet. Both carry the same entry shape, so a client folds them the
/// same way - catching up on the log and then following it is one fold, not
/// two.
///
/// A batch rather than a frame because the writer flushes frames in runs
/// (see `LiveSessionLogWriter`), and every run costs one publish however
/// many frames it holds. `entries` are in log order and never empty.
///
/// Addressed by session: it is the only thing a frame belongs to now that a
/// session does not own a channel.
#[derive(Debug, Clone)]
pub struct LogAppended {
    /// The durable turn projection after these frames, for list viewers that
    /// have not loaded the conversation's history.
    pub turn_state: Option<agent_fold::domain::model::TurnState>,
    /// The session the entries belong to. The fold keys its messages on this,
    /// so a client must pass it through unchanged.
    pub agent_session_id: AgentSessionId,
    /// The frames and the timestamps assigned when they were stored, in the
    /// order the log holds them.
    pub entries: Vec<StoredAgentSessionLog>,
}

/// One entry of a session's log as it was stored, with the time the log
/// recorded it.
///
/// [`AgentSessionLog`] is the frame a writer hands in, and a frame carries no
/// time of its own - `created_at` only exists once the row does. It is kept
/// beside the frame rather than folded into it so the fold's vocabulary stays
/// exactly what a client can replay, while a reader that has to order or merge
/// a session's messages against anything else still has something to order by.
#[derive(Debug, Clone)]
pub struct StoredAgentSessionLog {
    /// Durable row identity, used to select a replay history boundary.
    pub id: Uuid,
    /// When the entry was appended to the log.
    pub created_at: DateTime<Utc>,
    /// The frame, exactly as the log stored it.
    pub entry: AgentSessionLog,
}

/// A session's effective ACP history, from its latest successful load initialization.
/// With no successful load, history starts at the beginning. Failed attempts
/// remain in the stream and must be staged/discarded by fold consumers.
///
/// The web client folds it itself with the same fold compiled to WASM, so a
/// streamed session and a reloaded one are rendered by one implementation.
/// Readers without the fold get [`FoldedSessionLog`] instead.
#[derive(Debug, Clone)]
pub struct SessionLog {
    /// The agent whose messages the log derives.
    ///
    /// Sent because a reader has to render those messages and cannot work out
    /// who sent them: the sender of an agent message is this session's bot,
    /// and nothing else names it.
    pub bot: SessionBot,
    /// Every logged frame, oldest first. Folding depends on this order.
    pub entries: Vec<StoredAgentSessionLog>,
}

/// A session's effective history folded into the messages a reader renders,
/// oldest first: the same fold the web client runs over [`SessionLog`].
#[derive(Debug, Clone)]
pub struct FoldedSessionLog {
    /// The agent whose messages these are; see [`SessionLog::bot`].
    pub bot: SessionBot,
    /// Every message, oldest first.
    pub messages: Vec<agent_fold::domain::model::FoldedMessage>,
}

/// How an incoming channel context relates to an agent session.
///
/// Only the originating thread can match: sessions no longer own a dedicated
/// channel, so there is no channel that is itself a session. Messages sent
/// directly to a session arrive through their own topic, not as channel
/// events, and never pass through this lookup.
#[derive(Debug, Clone)]
#[allow(
    clippy::large_enum_variant,
    reason = "one data variant against None; boxing would only move the size"
)]
pub enum ThreadSession {
    /// No session matched the thread context.
    None,
    /// The bot's session was created from the incoming thread.
    CreatedFromThread(AgentSession),
}

/// Maximum number of session ids one preview request may ask about.
///
/// Bounds the work and the response per call; a mention menu never renders
/// anywhere near this many chips at once.
pub const MAX_PREVIEW_SESSION_IDS: usize = 100;

/// What one requested id resolved to in a batch preview.
///
/// Previews exist so a client can render a chip for a session it was handed a
/// reference to - a mention, a link - without first knowing whether it can
/// open it. Each id is therefore answered with one of three facts rather than
/// an error: the viewer can see it (with the fields a chip renders), the
/// session exists but the viewer holds no grant on it, or nothing by that id
/// exists at all. Only the first carries data, so a viewer without access
/// learns nothing beyond the session's existence - the same fact a `403`
/// from `GET /agent-sessions/{id}` already gives away.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AgentSessionPreview {
    /// The viewer holds at least view access; here is what a chip needs.
    Access(Box<AgentSessionPreviewData>),
    /// The session exists, but the viewer holds no grant on it.
    NoAccess(AgentSessionId),
    /// No session with this id exists.
    DoesNotExist(AgentSessionId),
}

impl AgentSessionPreview {
    /// The id this preview answers for, whichever way it resolved.
    #[must_use]
    pub fn id(&self) -> AgentSessionId {
        match self {
            Self::Access(data) => data.id,
            Self::NoAccess(id) | Self::DoesNotExist(id) => *id,
        }
    }
}

/// One session found by [`AgentSessionRepo::preview`](super::ports::AgentSessionRepo::preview),
/// before access policy: what a chip would show, whether an access row grants
/// the viewer at least view access, and where the session came from, so the
/// service can resolve inherited access that no row materializes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionPreviewCandidate {
    /// What a chip renders once access is settled.
    pub data: AgentSessionPreviewData,
    /// Whether a materialized grant - the viewer, a channel they are in, or a
    /// team they belong to - gives them at least view access.
    pub has_grant: bool,
    /// Parent of the thread the session was opened from, when it was.
    pub thread_parent: Option<messages::domain::models::MessageParent>,
}

/// The subset of an [`AgentSession`] a chip or mention renders.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AgentSessionPreviewData {
    /// The session id.
    pub id: AgentSessionId,
    /// User-facing session name.
    pub name: String,
    /// Who owns the session.
    pub owner_id: Owner,
    /// The bot running the agent, for its avatar.
    pub bot_id: BotId,
    /// Minimal bot identity, hydrated by the service after checking session access.
    pub bot: Option<SessionBot>,
    /// The session's last known status, for a live status indicator.
    pub status: SessionStatus,
    /// When the session was created.
    pub created_at: DateTime<Utc>,
    /// When the session was last modified.
    pub modified_at: DateTime<Utc>,
}

/// Initialization selected by a matching successful load in the session machine.
/// Persistence must append the response and select this row in one fenced transaction.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct HistoryBoundary {
    /// Initialization row in this session's log.
    pub initialization_log_id: Uuid,
}

/// A durable, nonblocking tool card supplied by a trusted session capability.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct SessionToolPresentation {
    /// Stable identity used to complete interrupted presentations without duplicates.
    pub tool_call_id: String,
    /// Tool name rendered by the ordinary ACP component router.
    pub title: String,
    /// Component input; never a request for the runtime to execute a tool.
    pub raw_input: serde_json::Value,
    /// Immediate presentation receipt, independent of any later user decision.
    pub raw_output: serde_json::Value,
}