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.

14.8 KB
Raw Blame
//! Per-session conversational state, held in memory.
//!
//! The durable record of a session is its frame log; what lives here is only
//! the model-facing conversation the next turn is built from. It survives a
//! reattach within one process lifetime, and a cold attach after a restart
//! rebuilds it from the frame log (see [`crate::domain::replay`]).

use std::collections::HashMap;

use agent::ReasoningEffort;
use agent::types::{AssistantMessagePart, ChatMessage, ChatMessageContent, Role};
use agent_client_protocol::schema::v1::{ContentBlock, PromptRequest, RequestId, SessionId};
use agent_runtime_protocol::domain::action::PromptAttachment;
use agent_session::domain::model::AgentSessionId;
use attachment::image::ImageData;
use attachment::{AttachmentContent, AttachmentPart, Attachments};
use dashmap::DashMap;
use model_entity::EntityType;
use non_empty::NonEmpty;
use tokio_util::sync::CancellationToken;

#[cfg(test)]
mod test;

/// What a user said in one turn: the prompt's text, and the files it named.
///
/// Files arrive as ACP `resource_link` blocks - URLs, never bytes. HTTPS
/// images go to the model as image URLs, which the provider fetches itself;
/// anything else is described to the model by name and URL, since there is
/// no way to show it the bytes and the URL is still something its tools can
/// fetch.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UserPrompt {
    /// The prompt's text blocks, joined.
    pub text: String,
    /// The prompt's `resource_link` blocks, in order.
    pub attachments: Vec<PromptAttachment>,
}

impl UserPrompt {
    /// A prompt of text alone.
    #[must_use]
    pub fn text(text: impl Into<String>) -> Self {
        Self {
            text: text.into(),
            attachments: Vec::new(),
        }
    }

    /// Read a prompt off the content blocks of a `session/prompt`. Block kinds
    /// this agent has no use for (inline images, audio, embedded resources -
    /// none of which it advertises) are skipped.
    #[must_use]
    pub fn from_blocks(blocks: &[ContentBlock]) -> Self {
        let mut prompt = Self::text(String::new());
        for block in blocks {
            match block {
                ContentBlock::Text(text) => prompt.text.push_str(&text.text),
                block => {
                    if let Some(attachment) = PromptAttachment::from_content_block(block) {
                        prompt.attachments.push(attachment);
                    }
                }
            }
        }
        prompt
    }

    /// Read a prompt off a `session/prompt` request.
    #[must_use]
    pub fn from_request(request: &PromptRequest) -> Self {
        Self::from_blocks(&request.prompt)
    }

    /// The attached files that reach the model as images: HTTPS images,
    /// which the provider fetches. Any other file is named in text.
    pub fn images(&self) -> impl Iterator<Item = &PromptAttachment> {
        self.attachments
            .iter()
            .filter(|attachment| is_image(attachment) && attachment.uri.starts_with("https://"))
    }

    /// The model-facing form of the attached files, `None` without any.
    #[must_use]
    pub fn to_attachments(&self) -> Option<Attachments<'static>> {
        let resolved: Vec<_> = self
            .attachments
            .iter()
            .map(|attachment| Ok(attachment_content(attachment)))
            .collect();
        NonEmpty::new(resolved).ok().map(Attachments::new)
    }

    /// The message this prompt is to the model.
    #[must_use]
    pub fn to_chat_message(&self) -> ChatMessage {
        ChatMessage {
            content: ChatMessageContent::Text(self.text.clone()),
            role: Role::User,
            attachments: self.to_attachments(),
        }
    }
}

/// The image file extensions the composer's chips classify as images, so a
/// file the user sees as a thumbnail is one the model sees as an image. Keep
/// in step with `CHANNEL_IMAGE_FILE_EXTENSIONS` on the web side.
const IMAGE_EXTENSIONS: &[&str] = &[
    "apng", "avif", "bmp", "gif", "heic", "heif", "jpeg", "jpg", "png", "svg", "tif", "tiff",
    "webp",
];

/// The media type browsers give `.psd` and `.psb` files.
const PHOTOSHOP_MIME: &str = "image/vnd.adobe.photoshop";

/// Whether this file is an image, by media type and then by name.
///
/// A browser can report no media type at all for a `.png`, and the composer
/// still shows it as a thumbnail, so the name decides when the type cannot.
fn is_image(attachment: &PromptAttachment) -> bool {
    let mime = attachment.mime_type.as_deref().unwrap_or_default();
    // Photoshop documents carry an image media type, but they are layered
    // design files no image pipeline decodes: they are named in text.
    if mime == PHOTOSHOP_MIME {
        return false;
    }
    if mime.starts_with("image/") {
        return true;
    }
    // Mirrors the composer's own order: a media type naming another medium
    // wins, and otherwise the name decides.
    if mime.starts_with("video/") {
        return false;
    }
    attachment
        .name
        .rsplit_once('.')
        .map(|(_, extension)| extension.to_ascii_lowercase())
        .is_some_and(|extension| IMAGE_EXTENSIONS.contains(&extension.as_str()))
}

/// One attached file as resolved attachment content.
///
/// Only an HTTPS image is handed over as an image URL: providers refuse plain
/// HTTP, and history keeps every attachment for the rest of the session, so
/// one such link would fail every later turn. Anything else is named in text.
fn attachment_content(attachment: &PromptAttachment) -> AttachmentContent<'static> {
    let is_image = is_image(attachment);
    let fetchable = attachment.uri.starts_with("https://");
    let part = if is_image && fetchable {
        AttachmentPart::Image(ImageData::StaticUrl(attachment.uri.clone()))
    } else {
        let kind = attachment.mime_type.as_deref().unwrap_or("unknown type");
        AttachmentPart::Content(format!(
            "Attached file \"{}\" ({kind}): {}",
            attachment.name, attachment.uri
        ))
    };
    let mut content = NonEmpty::one(part);
    if is_image && fetchable {
        // The model conversion emits content parts, not AttachmentContent's
        // name/reference fields. Keep the source visible even when a local
        // adapter replaces the image URL with inline bytes, so tools can reuse
        // an uploaded reference. This describes any image URL without claiming
        // that a third-party image is a Macro static file.
        content.push(AttachmentPart::Metadata {
            key: "image_file_name".to_owned(),
            value: attachment.name.clone(),
        });
        content.push(AttachmentPart::Metadata {
            key: "image_source_uri".to_owned(),
            value: attachment.uri.clone(),
        });
    }
    AttachmentContent {
        // The static file id is the URL's last path segment; a URL shaped
        // some other way is identified by the whole URL.
        reference: EntityType::StaticFile.with_entity_string(
            attachment
                .uri
                .rsplit('/')
                .next()
                .filter(|id| !id.is_empty())
                .unwrap_or(&attachment.uri)
                .to_owned(),
        ),
        name: Some(attachment.name.clone()),
        content,
    }
}

use super::engine::AgentIdentity;

/// One entry of the conversation, in the shape
/// [`agent::to_rig_messages`] round-trips.
#[derive(Debug, Clone)]
pub enum HistoryEntry {
    /// A prompt from a user.
    User {
        /// What they said.
        prompt: UserPrompt,
        /// The JSON-RPC id of the `session/prompt` request it came in. The
        /// log keeps the request whole, so the live agent and a replay of
        /// its log know the turn by the same id even where their entries
        /// differ, and a summary names the last turn it covers by it.
        request_id: RequestId,
    },
    /// One assistant turn: text, tool calls, and tool results, flattened.
    Assistant(Vec<AssistantMessagePart>),
    /// What a summary says of the conversation before it, which it stands
    /// in for. The model reads it as history it has already acted on.
    Summary(String),
}

/// What the model reads ahead of a summary, so it takes the summary as what
/// already happened rather than as work to do, and knows where the exact
/// words went.
pub const SUMMARY_PREAMBLE: &str = "The earlier conversation was summarized to keep it within \
your context. The summary below is history: the actions it records already happened, so do \
not repeat them. ContentSearch over this agent session finds the exact words of anything it \
covers.";

/// A summary being written in the background. A session has at most one.
#[derive(Debug)]
pub struct PendingSummary {
    /// Stops it. A summary whose history was reset under it is cancelled,
    /// so it never lands on a conversation it was not written from.
    pub cancel: CancellationToken,
    /// Closes once the summary has landed or been abandoned.
    pub settled: tokio::sync::watch::Receiver<()>,
}

impl PendingSummary {
    /// Whether it is still being written. One whose task is gone - its
    /// agent was replaced mid-summary - is not.
    #[must_use]
    pub fn is_running(&self) -> bool {
        self.settled.has_changed().is_ok()
    }
}

/// Where a session's summaries stand: the one being written, and what an
/// attempt that failed leaves the next.
#[derive(Debug, Default)]
pub struct Summarizing {
    /// The summary being written in the background, if any.
    pub pending: Option<PendingSummary>,
    /// How many tokens the conversation took when the last summary to
    /// settle failed; `None` once one lands. Another is not tried until the
    /// conversation has grown well past it, so a summary that keeps failing
    /// is not paid for on every message.
    pub failed_at: Option<u64>,
    /// What each image a summary read shows, by the image's URI, kept until
    /// a summary lands so that trying again does not read them again.
    pub descriptions: HashMap<String, String>,
}

/// The in-memory state of one agent session.
#[derive(Debug)]
pub struct SessionState {
    /// The ACP session id minted by `session/new`, `None` until then.
    pub acp_session_id: Option<SessionId>,
    /// Model id turns run on; `session/set_config_option` moves it.
    pub model: String,
    /// Reasoning effort applied to subsequent turns.
    pub reasoning_effort: ReasoningEffort,
    /// Inference speed applied to subsequent turns.
    pub speed: agent::ModelSpeed,
    /// Who this agent is, snapshotted from the session's bot at attach.
    pub identity: Option<AgentIdentity>,
    /// Instructions every turn runs under, snapshotted from the session row
    /// at attach. Nothing moves them: they are the session's system prompt,
    /// and a conversation whose system prompt changed halfway is one the
    /// agent never agreed to.
    pub instructions: Option<String>,
    /// The conversation the model reads, oldest first: a summary of what
    /// came before, if there was one, then everything since.
    pub history: Vec<HistoryEntry>,
    /// The summary being written in the background, if any, and what the
    /// last attempt left for the next.
    pub summarizing: Summarizing,
}

impl SessionState {
    /// A fresh session on `model` with no conversation yet.
    #[must_use]
    pub fn new(model: String) -> Self {
        Self {
            acp_session_id: None,
            model,
            reasoning_effort: ReasoningEffort::default(),
            speed: agent::ModelSpeed::Standard,
            identity: None,
            instructions: None,
            history: Vec::new(),
            summarizing: Summarizing::default(),
        }
    }

    /// Start the conversation over: what the model reads and what it no
    /// longer does, and any summary of it still being written or tried.
    pub fn clear_history(&mut self) {
        self.history.clear();
        if let Some(summary) = std::mem::take(&mut self.summarizing).pending {
            summary.cancel.cancel();
        }
    }
}

/// Put a summary in place of the first `replaces` entries of `history`. The
/// log keeps what they said, and an earlier summary among them is covered
/// by the new one.
pub fn splice_summary(history: &mut Vec<HistoryEntry>, text: String, replaces: usize) {
    let replaces = replaces.min(history.len());
    history.drain(..replaces);
    history.insert(0, HistoryEntry::Summary(text));
}

/// Where the turn of the prompt that request `id` carried ends in
/// `history`: right after its last entry, where the next prompt starts.
/// `None` when `history` holds no such prompt.
#[must_use]
pub fn end_of_turn(history: &[HistoryEntry], id: &RequestId) -> Option<usize> {
    let start = history.iter().position(
        |entry| matches!(entry, HistoryEntry::User { request_id, .. } if request_id == id),
    )?;
    let after = start + 1;
    Some(
        history[after..]
            .iter()
            .position(|entry| matches!(entry, HistoryEntry::User { .. }))
            .map_or(history.len(), |next| after + next),
    )
}

/// Session state by Macro session id, shared between the manager (which
/// creates and tears down entries) and the agent tasks (which read and extend
/// them). Entries outlive individual agent tasks so a reattach keeps its
/// conversation.
pub type SessionStore = DashMap<AgentSessionId, SessionState>;

/// Materialize the conversation for one turn: the recorded history followed
/// by the prompt being answered.
#[must_use]
pub fn messages_for_turn(history: &[HistoryEntry], prompt: &UserPrompt) -> Vec<ChatMessage> {
    history
        .iter()
        .flat_map(|entry| match entry {
            HistoryEntry::User { prompt, .. } => vec![prompt.to_chat_message()],
            HistoryEntry::Assistant(parts) => vec![assistant_message(parts.clone())],
            HistoryEntry::Summary(summary) => vec![
                UserPrompt::text(SUMMARY_PREAMBLE).to_chat_message(),
                assistant_message(vec![AssistantMessagePart::Text {
                    text: summary.clone(),
                }]),
            ],
        })
        .chain(std::iter::once(prompt.to_chat_message()))
        .collect()
}

fn assistant_message(parts: Vec<AssistantMessagePart>) -> ChatMessage {
    ChatMessage {
        content: ChatMessageContent::AssistantMessageParts(parts),
        role: Role::Assistant,
        attachments: None,
    }
}

/// Whether resolved attachments contain images, including nested attachments.
pub(super) fn contains_images(attachments: &Attachments<'_>) -> bool {
    fn content_has_images(content: &AttachmentContent<'_>) -> bool {
        content.content.iter().any(|part| match part {
            AttachmentPart::Image(_) => true,
            AttachmentPart::Child(child) => child.as_ref().as_ref().is_ok_and(content_has_images),
            _ => false,
        })
    }
    attachments
        .parts()
        .iter()
        .filter_map(|part| part.as_ref().ok())
        .any(content_has_images)
}