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.

15.4 KB
Raw Blame
//! Static prompt fragments used to compose AI system prompts.
//!
//! Each module holds one prompt section as static strings and exports a
//! `PROMPT` static — a [`StaticPrompt`] borrowing string data with `'static`
//! lifetime. Prompts chain together via [`StaticPrompt::compose`].
#![deny(missing_docs)]

pub mod about_macro;
pub mod agent_identity;
pub mod agent_session;
pub mod channel_mention;
pub mod citations;
pub mod code_mode;
pub mod coding_agents;
pub mod connected_toolsets;
pub mod databases;
pub mod deferred_tools;
pub mod do_not;
pub mod math;
pub mod mcp_item_links;
pub mod mentions;
pub mod privacy;
pub mod pull_requests;
pub mod skills;
pub mod tone;
mod types;
pub mod user_tools;

pub use types::{ComposedPrompt, Section, StaticPrompt};

/// The base prompt: tone, math, citations, mentions, do-not rules, and Macro
/// terms. Contains no tool use instructions.
pub static BASE_PROMPT: ComposedPrompt = tone::PROMPT
    .compose(&math::PROMPT)
    .compose(&citations::PROMPT)
    .compose(&mentions::PROMPT)
    .compose(&do_not::PROMPT)
    .compose(&about_macro::PROMPT);

/// [`BASE_PROMPT`] without its tone section, for agent sessions, whose
/// preamble ([`agent_session`]) sets their own tone.
static SESSION_BASE_PROMPT: ComposedPrompt = math::PROMPT
    .compose(&citations::PROMPT)
    .compose(&mentions::PROMPT)
    .compose(&do_not::PROMPT)
    .compose(&about_macro::PROMPT);

/// The tool-enabled prompt for hosts whose tools all execute directly in the
/// agent loop (the channel-mention bot, the MCP server): [`BASE_PROMPT`] with
/// the skill-following rules appended. How each area of Macro works is the
/// SDK's `@agent` guidance, which `ai_tools` composes after this. Says nothing about
/// composer-confirmed user tools — those hosts' toolsets execute
/// `CreateCalendarEvent` directly and have no `SendEmail` at all.
pub static DIRECT_TOOL_USE_PROMPT: ComposedPrompt = BASE_PROMPT.compose(&skills::PROMPT);

/// The chat tool-enabled prompt: [`DIRECT_TOOL_USE_PROMPT`] plus the rules
/// for composer-confirmed user tools (`SendEmail`, deferred execution), which
/// only apply on surfaces that can render the composer card.
pub static TOOL_USE_PROMPT: ComposedPrompt = BASE_PROMPT
    .compose(&user_tools::PROMPT)
    .compose(&skills::PROMPT);

/// The agent-session tool-enabled prompt: [`TOOL_USE_PROMPT`] on
/// [`SESSION_BASE_PROMPT`], with the user tool rules restated for a host that
/// reviews those calls in the turn - a review card the user answers while the
/// agent waits, not a composer left pending after it.
pub static SESSION_TOOL_USE_PROMPT: ComposedPrompt = SESSION_BASE_PROMPT
    .compose(&user_tools::SESSION_PROMPT)
    .compose(&skills::PROMPT);

/// Agent-session instructions in code mode: [`SESSION_TOOL_USE_PROMPT`] with
/// the [`code_mode`] section and nonblocking saved reviews.
pub static CODE_MODE_SESSION_TOOL_USE_PROMPT: ComposedPrompt = SESSION_BASE_PROMPT
    .compose(&code_mode::PROMPT)
    .compose(&user_tools::CODE_MODE_SESSION_PROMPT)
    .compose(&skills::PROMPT);

/// Database question instructions for hosts that only discover and read data.
pub static DATABASE_READ_ONLY_TOOL_USE_PROMPT: ComposedPrompt =
    BASE_PROMPT.compose(&databases::READ_ONLY_PROMPT);

/// Citation, do-not, Macro-terms and pull-request rules surfaced
/// to external MCP clients, composed together. These are static; the
/// item-linking rules for the model's own replies are not, because they
/// depend on the runtime app base URL — see [`mcp_instructions`].
///
/// Deliberately omits the in-app [`mentions`] section (MCP clients cannot render
/// `<m-document-mention>` tags in a chat reply) as well as chat tone/style and
/// general tool-use instructions, which belong to the host client, not to Macro.
/// The areas MCP clients write into (databases, CRM, document content) are the
/// SDK's `@agent` guidance, which the MCP server appends.
static MCP_STATIC_INSTRUCTIONS: ComposedPrompt = citations::PROMPT
    .compose(&do_not::PROMPT)
    .compose(&about_macro::PROMPT)
    .compose(&pull_requests::PROMPT);

/// Builds the instructions surfaced to external MCP clients via the server
/// `instructions` field.
///
/// Carries the formatting/correctness rules Macro features depend on so that AI
/// used through MCP produces valid output. Item links in the model's own chat
/// replies are rendered as plain Markdown URLs (built from `base_url`, the
/// runtime `APP_BASE_URL` value) and lists of items as Markdown tables — NOT
/// the in-app `<m-document-mention>` markup, which MCP clients cannot render.
/// Content the model writes *into* a Macro document via `CreateDocument` or
/// `EditDocument` is the opposite: it must still use `<m-document-mention>`
/// tags (`DocumentNamespace`'s `@agent` guidance, which the MCP server
/// appends), since the Macro app renders that
/// content regardless of which surface created it. `base_url` should already
/// have any trailing slash trimmed.
pub fn mcp_instructions(base_url: &str) -> String {
    format!(
        "{}\n{MCP_STATIC_INSTRUCTIONS}",
        mcp_item_links::render(base_url)
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn mcp_instructions_link_items_as_urls_built_from_base_url() {
        let instructions = mcp_instructions("https://macro.com");

        // Item links are plain URLs built from the base url, including a
        // worked example for a document.
        assert!(instructions.contains("https://macro.com/app/<type>/<id>"));
        assert!(instructions.contains("[Name](https://macro.com/app/md/<id>)"));
        assert!(instructions.contains("[Name](https://macro.com/app/routines/<id>)"));
    }

    #[test]
    fn mcp_instructions_forbid_mention_tags_but_in_app_prompt_keeps_them() {
        let instructions = mcp_instructions("https://macro.com");

        // MCP responses must steer away from the in-app mention markup...
        assert!(instructions.contains("Do NOT emit `<m-document-mention>`"));

        // ...while the in-app base prompt still instructs the model to use it.
        let in_app = BASE_PROMPT.to_string();
        assert!(in_app.contains("<m-document-mention>"));
        assert!(in_app.contains("use XML mention tags"));
    }

    #[test]
    fn mcp_instructions_describe_item_table_columns() {
        let instructions = mcp_instructions("https://macro.com");

        for column in ["number", "name", "link"] {
            assert!(
                instructions.contains(column),
                "instructions should describe the {column} table column"
            );
        }
    }

    #[test]
    fn direct_tool_use_prompt_omits_composer_confirmed_user_tool_rules() {
        // Hosts on the direct prompt (channel bot, MCP) have no composer and
        // no SendEmail tool; describing deferred user tools there would tell
        // the model the opposite of what its tools actually do.
        let direct = DIRECT_TOOL_USE_PROMPT.to_string();
        assert!(!direct.contains("PendingUserExecution"));
        assert!(!direct.contains("MUST use the `SendEmail` tool"));

        // The chat prompt keeps both rules.
        let chat = TOOL_USE_PROMPT.to_string();
        assert!(chat.contains("PendingUserExecution"));
        assert!(chat.contains("MUST use the `SendEmail` tool"));
    }

    #[test]
    fn session_tool_use_prompt_describes_a_review_in_the_turn_not_a_pending_composer() {
        // An agent session finishes user tools in the turn: the model never
        // sees "PendingUserExecution" there, and telling it about a composer
        // to confirm in later would have it say so to the user.
        let session = SESSION_TOOL_USE_PROMPT.to_string();
        assert!(!session.contains("PendingUserExecution"));
        assert!(session.contains("review card"));
        assert!(session.contains("MUST use the `SendEmail` tool"));
        assert!(session.contains("do not ask for confirmation in prose"));
    }

    #[test]
    fn code_mode_presents_views_unasked_and_mentions_leave_what_they_show_unmentioned() {
        let code_mode = CODE_MODE_SESSION_TOOL_USE_PROMPT.to_string();
        assert!(
            code_mode.contains("present them with `execution.views.present` without being asked")
        );
        assert!(
            !SESSION_TOOL_USE_PROMPT
                .to_string()
                .contains("execution.views.present` without")
        );
        // The mention rule is the base prompt's; a view's items are its one
        // exception, or the agent names them again under the view.
        assert!(
            BASE_PROMPT
                .to_string()
                .contains("the view already opens them")
        );
    }

    #[test]
    fn session_tool_use_prompt_routes_thread_prompts_to_prose_and_the_confirmed_send() {
        // A prompt read out of a channel or document thread has no review
        // card anyone is watching: the model asks in the thread, then sends
        // on the user's reply through SendConfirmedEmail, quoting it.
        let session = SESSION_TOOL_USE_PROMPT.to_string();
        assert!(session.contains("channel or document thread"));
        assert!(session.contains("context block names a conversation parent"));
        assert!(session.contains("`SendConfirmedEmail`"));
        assert!(session.contains("quoted verbatim"));
        assert!(session.contains("`userConfirmation`"));
        assert!(session.contains("`AskUser`"));
        assert!(session.contains(
            "`SendConfirmedEmail` and `CreateConfirmedCalendarEvent` are never right here"
        ));

        // The thread rule is to restate what the tool would have done, whole,
        // so the user can approve it without opening the session - and it
        // covers every user tool, not just email: an approved event goes
        // through the calendar twin of the confirmed send.
        assert!(session.contains("written out verbatim"));
        assert!(session.contains("the whole calendar event"));
        assert!(session.contains("`CreateConfirmedCalendarEvent` for the event"));

        // Which prompt is being answered decides it, not the session.
        assert!(session.contains("decided per"));
    }

    #[test]
    fn session_tool_use_prompt_treats_a_private_conversation_like_the_session_view() {
        // A DM with the agent is read live: its questions and review cards
        // appear there, so the thread rule does not apply to it.
        let session = SESSION_TOOL_USE_PROMPT.to_string();
        assert!(session.contains("private conversation with the user is the exception"));
        assert!(session.contains("like one typed in the agent session view"));
    }

    #[test]
    fn session_tool_use_prompt_keeps_the_thread_mechanics_away_from_the_user() {
        // The thread rule explains review cards and the session view so the
        // model knows why it writes the draft out. None of that is for the
        // user, who asked for an email or an event and should just get the
        // draft and a question - not a note about where their prompt came from.
        let session = SESSION_TOOL_USE_PROMPT.to_string();
        assert!(session.contains("The rule above is for you, not the user"));
        assert!(session.contains("Never explain why you are writing the draft out"));
        assert!(session.contains("not mention the agent session view, review cards"));
        assert!(session.contains("does not know or care"));
        assert!(session.contains("with no preamble about"));
    }

    #[test]
    fn chat_prompt_names_the_confirmed_tools_only_to_rule_them_out() {
        // The chat host has the same toolset and a composer, so the direct
        // tools are visible there and must be steered away from; the direct
        // prompt's hosts do not register them and say nothing about them.
        let chat = TOOL_USE_PROMPT.to_string();
        assert!(chat.contains("`SendConfirmedEmail`"));
        assert!(chat.contains("`CreateConfirmedCalendarEvent`"));
        assert!(chat.contains("never use them here"));
        let direct = DIRECT_TOOL_USE_PROMPT.to_string();
        assert!(!direct.contains("SendConfirmedEmail"));
        assert!(!direct.contains("CreateConfirmedCalendarEvent"));
    }

    #[test]
    fn agent_session_preamble_tells_the_model_to_emit_mention_tags() {
        let preamble = agent_session::PROMPT.to_string();
        assert!(preamble.contains("XML mention tag"));
        assert!(preamble.contains("clickable chips"));
        assert!(preamble.contains("agent session"));
        assert!(preamble.contains("date/time"));
    }

    #[test]
    fn mentions_prompt_says_a_shared_calendar_event_previews_for_channel_members() {
        let instructions = mentions::PROMPT.instructions.as_ref();
        assert!(instructions.contains("read-only preview"));
        assert!(instructions.contains("Private and confidential events are never shared"));
    }

    #[test]
    fn mentions_prompt_writes_whole_days_as_local_dates_from_the_current_time() {
        let instructions = mentions::PROMPT.instructions.as_ref();
        assert!(instructions.contains("bare local calendar date (`2025-12-01`)"));
        assert!(instructions.contains("never midnight UTC"));
        assert!(instructions.contains("`<current_time>`"));
    }

    #[test]
    fn mentions_prompt_covers_date_and_agent_session_chips() {
        let instructions = mentions::PROMPT.instructions.as_ref();
        assert!(instructions.contains("<m-date-mention>"));
        assert!(instructions.contains("<m-agent-session-mention>"));
        assert!(instructions.contains("<m-user-mention>"));
        assert!(instructions.contains("\"expanded\":true"));
        assert!(instructions.contains("\"blockName\":\"skill\""));
        assert!(instructions.contains("\"blockName\":\"initiative\""));
        assert!(instructions.contains("\"blockName\":\"pipeline\""));
        assert!(instructions.contains("\"blockName\":\"routine\""));
    }

    #[test]
    fn mcp_and_coding_agents_open_ready_pull_requests_with_ci_passing() {
        assert!(mcp_instructions("https://macro.com").contains(pull_requests::READY_PULL_REQUEST));

        let coding = coding_agents::PROMPT.to_string();
        assert!(coding.contains("ready for review, not a draft"));
        assert!(coding.contains("CI passing"));
    }

    #[test]
    fn agent_identity_names_the_agent_before_the_session_preamble() {
        let identity = agent_identity::render("Grunk", "grunk");
        assert!(identity.starts_with("# Identity\n"));
        assert!(identity.contains("You are Grunk (@grunk)."));
    }

    #[test]
    fn markdown_surface_scope_names_every_surface_but_the_reply_tone_exception() {
        // The mention rule must name every Markdown-authoring surface and the
        // non-Markdown-document exception, and the tool-use tone rule must not
        // silently bleed into tool-authored content.
        let in_app = TOOL_USE_PROMPT.to_string();
        for surface in [
            "SendChannelMessage",
            "SendEmail",
            "CreateDocument",
            "agent session",
        ] {
            assert!(
                in_app.contains(surface),
                "markdown surface scope should name {surface}"
            );
        }
        assert!(in_app.contains("non-Markdown documents"));
        assert!(in_app.contains("apply to your own conversational replies only"));
    }
}

/// Compose runtime sections in their supplied order without retaining their data.
pub fn compose(sections: &[&dyn std::fmt::Display]) -> String {
    sections
        .iter()
        .map(ToString::to_string)
        .collect::<Vec<_>>()
        .join("\n")
}