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
//! Composition root for the production turn engine: the shared rig agent loop
//! over the Macro product toolset.
//!
//! Consumption mirrors the scheduled-action executor
//! (`crates/scheduled_action/src/outbound/inprocess_executor/agent_task.rs`):
//! the full static toolset, the agent-session preamble, the static Macro
//! prompt, the agent's name and handle, any session instructions, and the
//! owner's memory, with usage recorded per turn against the session owner.
//!
//! User tools (`SendEmail`, `CreateCalendarEvent`) are the chat host's
//! deferring ones, finished inside the turn: the turn's [`TurnRequest`]
//! carries a reviewer over the ACP connection, and the agent loop's
//! user-tool finisher puts each pending call to it - the session renders the
//! elicitation - then runs or rejects the tool before the model reads the
//! result. Without a reviewer (a client with no form support) a pending call
//! stays pending, as in chat.
//!
//! This is also where a session's own instructions become a system prompt.
//! Nothing has to be transported for it - the loop runs in this process - which
//! is why the in-memory runtime is the one provider that needs no wire format
//! for them. See [`system_prompt`] for how the sections are ordered.
use std::pin::Pin;
use std::sync::Arc;
use agent::{AgentError, AgentLoop, ReadToolResult, StreamPart, SystemPrompt, ToolResultLimit};
use ai_tools::user_tool_review::{ReviewError, UserToolAuthorizer, authorized_user_tool_finisher};
use ai_tools::{AiHost, DeferredToolSet, ToolServiceContext, tools_for};
use ai_toolset::{AsyncToolCollection, ToolSet as AiToolSet};
use axum::extract::FromRef;
use futures::{FutureExt as _, StreamExt as _};
use macro_user_id::user_id::MacroUserIdStr;
use memory::domain::MemoryService as _;
use memory::domain::service::MemoryServiceImpl;
use memory::outbound::pg_memory_repo::PgMemoryRepo;
use model_owner::Owner;
use sqlx::PgPool;
use tokio::sync::mpsc;
use tokio_util::sync::CancellationToken;
use tracing::Instrument as _;
use crate::domain::auto_model::{AutoModelSelector, DefaultAutoModel, JevAutoModel};
use crate::domain::engine::{AgentIdentity, ReplyDelivery, TurnEngine, TurnRequest};
use crate::domain::entity_routing::{EntityRoutingPolicy, NoEntityRouting};
use crate::domain::skill_routing::{NoSkillRouting, SessionSkills, SkillRoutingPolicy};
use crate::domain::tool_gate::{NativeToolGate, NativeToolVerdict, UngatedNativeTools};
use crate::domain::tool_mode::{StandardTools, ToolMode, ToolModeSelector};
use crate::inbound::ask_user::{AskUser, AskUserContext};
#[path = "outbound/rig_engine/opener.rs"]
mod opener;
#[cfg(test)]
#[path = "outbound/rig_engine/test.rs"]
mod test;
#[cfg(test)]
#[path = "outbound/rig_engine/measure_prompt_cache.rs"]
mod measure_prompt_cache;
/// How many stream parts may sit unread before the engine pauses; keeps a
/// slow consumer from buffering a whole turn.
const PART_BUFFER: usize = 256;
const EAGER_INTERNAL_MCP_TOOLS: &[&str] = &[
"mcp__macro_internal__PresentReview",
"mcp__macro_internal__GetReview",
"mcp__macro_internal__DecideReview",
"mcp__macro_internal__ExecuteCode",
"mcp__macro_internal__DescribeCodeTools",
"mcp__macro_internal__ReadCodeDocs",
];
const CODE_MODE_MCP_TOOLS: &[&str] = &[
"mcp__macro_internal__ExecuteCode",
"mcp__macro_internal__DescribeCodeTools",
"mcp__macro_internal__ReadCodeDocs",
];
/// [`TurnEngine`] backed by [`agent::AgentLoop`] and
/// [`ai_tools::tools_for`].
pub struct RigTurnEngine {
memory: Arc<MemoryServiceImpl<PgMemoryRepo>>,
native_tools: Arc<NativeTools>,
code_mode_tools: Arc<NativeTools>,
tool_mode: Arc<dyn ToolModeSelector>,
auto_model: Arc<dyn AutoModelSelector>,
skill_routing: Arc<dyn SkillRoutingPolicy>,
session_skills: Arc<SessionSkills>,
entity_routing: Arc<dyn EntityRoutingPolicy>,
tool_context: ToolServiceContext,
gate: Arc<dyn NativeToolGate>,
}
impl RigTurnEngine {
/// An engine whose tools run against `tool_context` and whose user
/// memory comes from `db`. Every native tool runs ungated until
/// [`Self::with_gate`] says otherwise.
#[must_use]
pub fn new(db: PgPool, tool_context: ToolServiceContext) -> Self {
Self {
memory: Arc::new(ai_tools::memory::build_memory_service(
db,
tool_context.clone(),
)),
native_tools: Arc::new(NativeTools::new()),
code_mode_tools: Arc::new(NativeTools::from_factory(
ai_tools::tools_for_agent_code_mode,
true,
)),
tool_mode: Arc::new(StandardTools),
auto_model: match &tool_context.cognition_tool_context.service {
Some(cognition) => Arc::new(JevAutoModel::new(Arc::clone(cognition))),
None => Arc::new(DefaultAutoModel),
},
skill_routing: Arc::new(NoSkillRouting),
session_skills: Arc::new(SessionSkills::default()),
entity_routing: Arc::new(NoEntityRouting),
tool_context,
gate: Arc::new(UngatedNativeTools),
}
}
/// Ask `gate` before each of Macro's own tools runs.
#[must_use]
pub fn with_gate(mut self, gate: Arc<dyn NativeToolGate>) -> Self {
self.gate = gate;
self
}
/// Select the owner's tool presentation once per conversational turn.
#[must_use]
pub fn with_tool_mode(mut self, selector: Arc<dyn ToolModeSelector>) -> Self {
self.tool_mode = selector;
self
}
/// Decide per turn whether the owner's turns load their skills on their own.
#[must_use]
pub fn with_skill_routing(mut self, policy: Arc<dyn SkillRoutingPolicy>) -> Self {
self.skill_routing = policy;
self
}
/// Decide per turn whether the owner's code-mode turns route SDK entities.
#[must_use]
pub fn with_entity_routing(mut self, policy: Arc<dyn EntityRoutingPolicy>) -> Self {
self.entity_routing = policy;
self
}
}
/// Native tools never gated: asking the user something, and finding or
/// loading a connected app's tools, or reading the rest of a result the
/// turn already got, spend nobody's access.
const UNGATED_NATIVE_TOOLS: [&str; 4] = ["AskUser", "SearchTools", "LoadTools", "ReadToolResult"];
/// A turn's tools, each call to one of Macro's own asked of the gate first.
/// Remote MCP tools are left to the egress proxy, which gates them already.
struct GatedToolSet<Context> {
tools: Arc<dyn AiToolSet<Context> + Send + Sync>,
gate: Arc<dyn NativeToolGate>,
session: agent_session::domain::model::AgentSessionId,
awaiting: Arc<crate::domain::engine::AwaitingUser>,
reviewed_tools: Vec<String>,
}
impl<Context> AiToolSet<Context> for GatedToolSet<Context>
where
Context: Send + Sync + 'static,
{
fn dispatch_tool_call<'a>(
&'a self,
context: Context,
request_context: ai_toolset::RequestContext,
tool_name: &'a str,
json: &'a serde_json::Value,
) -> ai_toolset::ToolCallFuture<'a> {
Box::pin(async move {
let mut request_context = request_context;
let native = !UNGATED_NATIVE_TOOLS.contains(&tool_name)
&& !tool_name.starts_with(mcp_select::MANGLED_PREFIX)
&& agent_egress::domain::approval::spends_owner_access("macro", tool_name);
let arguments = if native {
let _waiting = self.awaiting.begin();
let verdict = if self.reviewed_tools.iter().any(|name| name == tool_name) {
NativeToolVerdict::Run
} else {
self.gate.check(self.session, tool_name, json).await
};
match verdict {
NativeToolVerdict::RunAs(user) => request_context.user_id = user,
NativeToolVerdict::Run => {}
NativeToolVerdict::Refuse(reason) => {
return Ok(Err(ai_toolset::ToolCallError {
internal_error: anyhow::anyhow!("{tool_name} was not approved"),
description: reason,
}));
}
}
match ai_toolset::actor::ToolActor::take(json) {
Ok((_, arguments)) => arguments,
Err(error) => {
return Ok(Err(ai_toolset::ToolCallError {
description: error.to_string(),
internal_error: error.into(),
}));
}
}
} else {
json.clone()
};
self.tools
.dispatch_tool_call(context, request_context, tool_name, &arguments)
.await
})
}
fn request_schemas(&self) -> Option<Vec<ai_toolset::RequestSchema>> {
self.tools.request_schemas().map(|mut tools| {
for tool in &mut tools {
add_native_actor_schema(&tool.name, &mut tool.schema);
}
tools
})
}
fn searchable_catalog(&self) -> Vec<ai_toolset::SearchableTool> {
let mut tools = self.tools.searchable_catalog();
for tool in &mut tools {
add_native_actor_schema(&tool.name, &mut tool.schema);
}
tools
}
fn searchable_toolset_names(&self) -> Vec<String> {
self.tools.searchable_toolset_names()
}
fn routing_description<'a>(&'a self, tool_name: &'a str) -> Option<ai_toolset::ToolInfo> {
self.tools.routing_description(tool_name)
}
}
fn add_native_actor_schema(name: &str, schema: &mut schemars::Schema) {
if !UNGATED_NATIVE_TOOLS.contains(&name)
&& !name.starts_with(mcp_select::MANGLED_PREFIX)
&& agent_egress::domain::approval::spends_owner_access("macro", name)
&& let Some(schema) = schema.as_object_mut()
{
ai_toolset::actor::add_actor_schema(schema);
}
}
#[derive(Clone)]
struct InMemToolContext {
base: ToolServiceContext,
ask_user: AskUserContext,
tool_results: ToolResultLimit,
}
impl FromRef<InMemToolContext> for ToolServiceContext {
fn from_ref(context: &InMemToolContext) -> Self {
context.base.clone()
}
}
impl FromRef<InMemToolContext> for AskUserContext {
fn from_ref(context: &InMemToolContext) -> Self {
context.ask_user.clone()
}
}
impl FromRef<InMemToolContext> for ToolResultLimit {
fn from_ref(context: &InMemToolContext) -> Self {
context.tool_results.clone()
}
}
fn tools_for_turn(
base_tools: ai_tools::AiToolSet,
supports_user_input: bool,
) -> AsyncToolCollection<InMemToolContext> {
let tools = AsyncToolCollection::<InMemToolContext>::new()
.add_subtoolset(base_tools)
.add_tool::<ReadToolResult, ToolResultLimit>();
if supports_user_input {
tools.add_tool::<AskUser, AskUserContext>()
} else {
tools
}
}
/// Native definitions contain schemas and deserializers, not a user's context.
/// Build both client-capability variants once, before the first prompt. Each
/// turn still supplies its own identity, reviewer, gate, MCP tools and memory.
struct NativeTools {
with_user_input: Arc<AsyncToolCollection<InMemToolContext>>,
without_user_input: Arc<AsyncToolCollection<InMemToolContext>>,
prompt: String,
/// [`Self::prompt`] without area guidance, for turns that route SDK
/// entities.
routed_prompt: String,
code_mode: bool,
deferred: Arc<[ai_toolset::SearchableTool]>,
/// Every native tool's name, for the opening line's model to guess the
/// direction a reply will take.
tool_names: String,
}
impl NativeTools {
fn new() -> Self {
Self::from_factory(|| tools_for(AiHost::AgentSession), false)
}
fn from_factory(build: impl Fn() -> ai_tools::ToolSetWithPrompt, code_mode: bool) -> Self {
let tools = build();
let base_tools = Arc::into_inner(tools.toolset)
.expect("tools_for should return a fresh, uniquely owned collection");
let other_tools = Arc::into_inner(build().toolset)
.expect("tools_for should return a fresh, uniquely owned collection");
let with_user_input = tools_for_turn(base_tools, true);
let tool_names = with_user_input
.tools
.keys()
.map(String::as_str)
.chain(tools.deferred.iter().map(|tool| tool.name.as_str()))
.collect::<Vec<_>>()
.join(", ");
Self {
with_user_input: Arc::new(with_user_input),
without_user_input: Arc::new(tools_for_turn(other_tools, false)),
code_mode,
prompt: tools.prompt.to_string(),
routed_prompt: tools.routed_prompt.to_string(),
deferred: tools.deferred,
tool_names,
}
}
fn for_turn(&self, supports_user_input: bool) -> Arc<AsyncToolCollection<InMemToolContext>> {
Arc::clone(if supports_user_input {
&self.with_user_input
} else {
&self.without_user_input
})
}
}
impl TurnEngine for RigTurnEngine {
fn supported_models(&self) -> &[&str] {
crate::domain::models::advertised_models()
}
fn run_turn(&self, request: TurnRequest) -> mpsc::Receiver<Result<StreamPart, AgentError>> {
let (parts, receiver) = mpsc::channel(PART_BUFFER);
let memory = Arc::clone(&self.memory);
let native_tools = Arc::clone(&self.native_tools);
let code_mode_tools = Arc::clone(&self.code_mode_tools);
let tool_mode = Arc::clone(&self.tool_mode);
let auto_model = Arc::clone(&self.auto_model);
let skill_routing = Arc::clone(&self.skill_routing);
let session_skills = Arc::clone(&self.session_skills);
let entity_routing = Arc::clone(&self.entity_routing);
let tool_context = self.tool_context.clone();
let gate = Arc::clone(&self.gate);
let metering = agent::MeteringContext::current();
tokio::spawn(
agent::MeteringContext::carry(metering, async move {
let mut request = request;
let Some(model) = select_auto_model(auto_model.as_ref(), &request).await else {
return;
};
request.model = model;
let (selected, routes, entities_routed) = tokio::join!(
select_tool_mode(tool_mode.as_ref(), &request),
routes_skills(skill_routing.as_ref(), &request),
routes_entities(entity_routing.as_ref(), &request),
);
let Some(selected) = selected else {
return;
};
let native_tools = match selected {
ToolMode::Standard => native_tools,
ToolMode::Code => code_mode_tools,
};
tracing::debug!(?selected, "selected agent tool presentation");
// The product toolset makes this future large. Keep its state
// on the heap when adding the panic boundary, including in
// unoptimized local builds with Tokio's default worker stack.
let skills = TurnRouting {
routes,
sessions: &session_skills,
entities: entities_routed,
};
let turn = Box::pin(drive_turn(
&memory,
&native_tools,
skills,
tool_context,
gate,
request,
&parts,
));
forward_turn_result(turn, &parts).await;
})
.in_current_span(),
);
receiver
}
}
// Closing the stream alone means success to the ACP consumer. A panic in
// provider initialization must therefore become an explicit failed turn.
async fn forward_turn_result(
turn: impl Future<Output = Result<(), AgentError>>,
parts: &mpsc::Sender<Result<StreamPart, AgentError>>,
) {
let result = std::panic::AssertUnwindSafe(turn)
.catch_unwind()
.await
.unwrap_or_else(|_| {
Err(AgentError::Other(anyhow::anyhow!(
"The agent runtime ended unexpectedly. Please retry this message."
)))
});
if let Err(error) = result {
let _ = parts.send(Err(error)).await;
}
}
// Auto is a picker entry, not a routable id: the turn's prompt decides the
// model it runs on. Every other id passes through.
async fn select_auto_model(
selector: &dyn AutoModelSelector,
request: &TurnRequest,
) -> Option<String> {
if request.model != crate::domain::models::AUTO_MODEL {
return Some(request.model.clone());
}
let Owner::User(owner) = &request.owner else {
return Some(crate::domain::models::resolve(&request.model).to_owned());
};
let prompt = request
.messages
.iter()
.rev()
.find(|message| message.role == agent::types::Role::User)
.and_then(|message| message.content.user_message_text())
.unwrap_or_default();
tokio::select! {
biased;
_ = request.cancel.cancelled() => None,
model = selector.select(owner, &prompt) => Some(model.to_owned()),
}
}
// Only conversation turns load skills; summaries read no instructions.
async fn routes_skills(policy: &dyn SkillRoutingPolicy, request: &TurnRequest) -> bool {
let Owner::User(owner) = &request.owner else {
return false;
};
request.purpose == crate::domain::engine::TurnPurpose::Conversation
&& policy.routes(owner).await
}
// Only a user's conversation turns route SDK entities; summaries read none.
async fn routes_entities(policy: &dyn EntityRoutingPolicy, request: &TurnRequest) -> bool {
let Owner::User(owner) = &request.owner else {
return false;
};
request.purpose == crate::domain::engine::TurnPurpose::Conversation
&& policy.routes(owner).await
}
/// What a turn loads on its own: the user's skills (and what its session has
/// loaded already), and the SDK areas its request needs.
struct TurnRouting<'a> {
routes: bool,
sessions: &'a SessionSkills,
entities: bool,
}
/// Route the turn's request to the user's skills. Boxed: the skill service's
/// listing future is deep enough to overflow the turn's own future type.
fn select_skills<'a>(
context: &'a ToolServiceContext,
owner: &'a MacroUserIdStr<'static>,
request: skills::domain::selection::SkillRequest<'a>,
already_loaded: &'a [uuid::Uuid],
cancel: &'a CancellationToken,
) -> Pin<Box<dyn Future<Output = skills::domain::selection::SkillSelection> + Send + 'a>> {
Box::pin(skills::domain::selection::select_skills(
context.skill_tool_context.service.as_ref(),
context.cognition_tool_context.service.as_ref(),
owner,
request,
already_loaded,
cancel,
))
}
// A failed/missing code-mode MCP connection must never leave a turn with only the
// small direct set. Summaries neither evaluate flags nor advertise tools.
async fn select_tool_mode(
selector: &dyn ToolModeSelector,
request: &TurnRequest,
) -> Option<ToolMode> {
if request.purpose != crate::domain::engine::TurnPurpose::Conversation {
return Some(ToolMode::Standard);
}
let (Owner::User(owner), Some(mcp)) = (&request.owner, &request.mcp_tools) else {
return Some(ToolMode::Standard);
};
let catalog = mcp.searchable_catalog();
if !CODE_MODE_MCP_TOOLS
.iter()
.all(|name| catalog.iter().any(|tool| tool.name == *name))
{
return Some(ToolMode::Standard);
}
tokio::select! {
biased;
_ = request.cancel.cancelled() => None,
mode = selector.select(owner) => Some(mode),
}
}
async fn drive_turn(
memory: &MemoryServiceImpl<PgMemoryRepo>,
native_tools: &NativeTools,
skills: TurnRouting<'_>,
base_context: ToolServiceContext,
gate: Arc<dyn NativeToolGate>,
request: TurnRequest,
parts: &mpsc::Sender<Result<StreamPart, AgentError>>,
) -> Result<(), AgentError> {
let TurnRequest {
purpose,
delivery,
session_id,
awaiting,
owner,
model,
reasoning_effort,
speed,
identity,
instructions,
messages,
mcp_tools,
cancel,
user_input,
reviewer,
agent_key,
} = request;
let started = tokio::time::Instant::now();
// A turn runs as a person: tools act with the owner's identity, the
// memory is theirs, and usage is billed to them. A session owned by
// anything else has no turn to run here, and says so instead of running
// as somebody it is not.
let owner = match owner {
Owner::User(owner) => owner,
other => {
return Err(AgentError::Other(anyhow::anyhow!(
"in-process turns run as the session owner, who must be a user; \
this session is owned by a {}",
other.owner_type()
)));
}
};
// A summary turn condenses the conversation for its continuation: it
// reads no memory, offers the model no tools, and is read, not shown, so
// no opening line races it.
let summarizing = purpose == crate::domain::engine::TurnPurpose::Summary;
if let Some(key) = &agent_key
&& agent_api_keys::domain::ModelProvider::of_model(&model) != Some(key.key.provider())
{
return Err(AgentError::Other(anyhow::anyhow!(
"the agent's API key does not serve {model}"
)));
}
// The opening line runs on Macro's own fast model, so a turn the agent's
// key pays for goes without one; so does a reply read only once it is
// finished, which gains nothing from it.
let opening = !summarizing && agent_key.is_none() && delivery == ReplyDelivery::Streamed;
// Started before anything else so its line is out before the turn's
// model has a first token.
let usage_ctx = ai_usage::UsageContext::new(ai_usage::AiFeature::AgentSession, owner.clone());
let agent = identity.as_ref().map_or_else(
|| "Macro".to_owned(),
|identity| format!("{} (@{})", identity.name, identity.handle),
);
// How the race went, on one span per turn. `outcome` is `complete` (the
// line was the whole reply), `opening` (the line opened the turn's
// reply), `silent` (no line fit this follow-up), `turn_first` (the
// turn's model spoke first), `no_verdict` (the
// fast model failed or answered without one) or `timeout`.
let opener_span = if !opening {
tracing::Span::none()
} else {
tracing::info_span!(
"agent.opener",
agent.opener.model = opener::MODEL,
agent.opener.outcome = tracing::field::Empty,
agent.opener.verdict_ms = tracing::field::Empty,
agent.opener.line_chars = tracing::field::Empty,
agent.opener.turn_first_part_ms = tracing::field::Empty,
)
};
// A closed receiver has no verdict, and the turn's own stream follows.
let mut opening_line = if !opening {
mpsc::channel(1).1
} else {
opener_span.in_scope(|| {
opener::spawn(
base_context.recorder.clone(),
usage_ctx.clone(),
&opener::Speaker {
agent: &agent,
model: crate::domain::models::display_name(&model),
},
&native_tools.tool_names,
&messages,
)
})
};
// Chat's tools with the session's prompt: the user tools (`SendEmail`,
// `CreateCalendarEvent`) defer to the user, and this runtime finishes
// them in the turn through `reviewer`.
let (system_prompt, toolset, deferred, loaded_skills) = if summarizing {
(
SystemPrompt::from(instructions.unwrap_or_default()),
Arc::new(AsyncToolCollection::<InMemToolContext>::new()),
Arc::from(Vec::new()),
Vec::new(),
)
} else {
let user_messages: Vec<String> = messages
.iter()
.filter(|message| message.role == agent::types::Role::User)
.filter_map(|message| message.content.user_message_text())
.collect();
let requested = user_messages.last().cloned().unwrap_or_default();
// Routed turns leave area guidance out of the prompt; the entities the
// request needs bring theirs, with their indexes, in the turn's part.
let routed = native_tools.code_mode && skills.entities;
let docs = async {
if native_tools.code_mode {
agent_code_mode::domain::select_documentation(
&owner,
&requested,
base_context.cognition_tool_context.service.as_ref(),
if routed {
agent_code_mode::domain::Guidance::Selected
} else {
agent_code_mode::domain::Guidance::Inline
},
&cancel,
)
.await
} else {
String::new()
}
};
let loaded_skills = async {
if !skills.routes {
return Vec::new();
}
let selection = select_skills(
&base_context,
&owner,
skills::domain::selection::SkillRequest {
latest: &requested,
previous: user_messages
.len()
.checked_sub(2)
.map(|index| user_messages[index].as_str()),
},
&skills.sessions.loaded_ids(session_id),
&cancel,
)
.await;
skills.sessions.add(
session_id,
user_messages.len().saturating_sub(1),
selection.loaded,
)
};
let (user_memory, sdk_docs, loaded_skills) =
tokio::join!(fetch_user_memory(memory, &owner), docs, loaded_skills);
let prompt = system_prompt(
if routed {
&native_tools.routed_prompt
} else {
&native_tools.prompt
},
&sdk_docs,
session_id,
delivery,
identity.as_ref(),
instructions.as_deref(),
user_memory.as_deref(),
);
(
prompt,
native_tools.for_turn(user_input.is_some()),
Arc::clone(&native_tools.deferred),
loaded_skills,
)
};
// Carry the feature on the context so tool-spawned subagents attribute to it.
let mut tool_context = base_context.clone();
tool_context.usage_context = usage_ctx.clone();
// The tools act as the session's bot, delegated for the owner: its writes
// are attributed to it and presented under its name, not Macro's.
if let Some(identity) = &identity {
tool_context = tool_context
.with_actor(identity.bot)
.with_actor_name(&identity.name);
}
// Results too long for the model to read whole are cut, the turn's as
// they arrive and earlier ones as history is replayed below, and kept
// here for `ReadToolResult`.
let tool_results = ToolResultLimit::default();
let tool_context = InMemToolContext {
base: tool_context,
ask_user: AskUserContext {
requester: user_input,
},
tool_results: tool_results.clone(),
};
// GenAI telemetry stays off here: this runtime's turns and tool calls
// reach the session actor as ACP frames, and the actor projects those onto
// `invoke_agent` / `execute_tool` spans for every harness alike. Enriching
// rig's spans too would report each turn twice.
// Calls stream as the model writes them, so the transcript shows a call
// from the moment it is named rather than once its arguments are whole.
let mut agent_loop = AgentLoop::new(base_context.recorder.clone())
.with_model(&model)
.with_reasoning_effort(reasoning_effort)
.with_speed(speed)?
.with_genai_telemetry(false)
.with_streamed_tool_calls()
.with_tool_result_limit(tool_results.clone());
// Only the loop's own model calls run on the agent's key, so only they are
// recorded against it; tools keep `usage_ctx`, since they call models on
// Macro's keys.
let loop_usage = match agent_key {
Some(key) => {
agent_loop = agent_loop.with_provider_api_key(key.key.expose())?;
usage_ctx.with_agent_api_key(key.bot_id)
}
None => usage_ctx,
};
let mut reviewed_tools = Vec::new();
if let Some(reviewer) = reviewer.filter(|_| !summarizing) {
reviewed_tools = toolset.user_tools.keys().cloned().collect();
let tools = Arc::clone(&toolset);
let context = tool_context.clone();
let gate = Arc::clone(&gate);
let cancel = cancel.clone();
let awaiting = Arc::clone(&awaiting);
agent_loop = agent_loop.with_user_tool_finisher(Arc::new(move |mut call: agent::PendingUserTool| {
let tools = Arc::clone(&tools);
let context = context.clone();
let gate = Arc::clone(&gate);
let cancel = cancel.clone();
let reviewer = Arc::clone(&reviewer);
let awaiting = Arc::clone(&awaiting);
Box::pin(async move {
if !tools.user_tools.contains_key(&call.tool_name) { return None; }
let (actor, arguments) = match ai_toolset::actor::ToolActor::take(&call.args) {
Ok(selection) => selection,
Err(error) => return Some(agent::FinishedUserTool::Error(error.to_string())),
};
let authorize_cancel = cancel.clone();
let authorize: UserToolAuthorizer = Arc::new(move |name, mut args| {
let gate = Arc::clone(&gate);
let cancel = authorize_cancel.clone();
let awaiting = Arc::clone(&awaiting);
Box::pin(async move {
args[ai_toolset::actor::ACTING_AS] = serde_json::to_value(actor).map_err(|error| ReviewError::Failed(error.to_string()))?;
let _waiting = awaiting.begin();
let verdict = tokio::select! {
biased;
_ = cancel.cancelled() => return Err(ReviewError::Failed("The turn was cancelled; nothing was done.".into())),
verdict = gate.check(session_id, &name, &args) => verdict,
};
match verdict {
NativeToolVerdict::RunAs(user) => Ok(user),
NativeToolVerdict::Refuse(reason) => Err(ReviewError::Failed(reason)),
NativeToolVerdict::Run => Err(ReviewError::Failed("Could not resolve the tool actor.".into())),
}
})
});
call.args = arguments;
authorized_user_tool_finisher(tools, context, reviewer, cancel, authorize)(call).await
})
}));
}
// Native tools use the actor gate unless the installed finisher authorizes
// their final reviewed arguments. Remote MCP tools use the egress gate.
// Keep remote MCP tools alongside the native and AskUser tools. The
// finisher above reviews only Macro's native user tools.
let toolset: Arc<dyn AiToolSet<_> + Send + Sync> = match mcp_tools.filter(|_| !summarizing) {
Some(mcp) => Arc::new(
mcp_select::CombinedToolSet::new(toolset, mcp)
.with_eager_mcp_tools(EAGER_INTERNAL_MCP_TOOLS),
),
None => toolset,
};
// Most of Macro's tools go out by name only; the model loads the rest.
let toolset: Arc<dyn AiToolSet<_> + Send + Sync> =
Arc::new(DeferredToolSet::new(toolset, deferred));
let toolset: Arc<dyn AiToolSet<_> + Send + Sync> = Arc::new(GatedToolSet {
tools: toolset,
gate,
session: session_id,
awaiting,
reviewed_tools,
});
let session = agent_loop
.session(toolset, Arc::new(tool_context), system_prompt, loop_usage)
.await;
let (mut session, loop_cancel) = session.cancellable();
// Bridge the caller's token onto the loop's own; aborted with the turn so
// an uncancelled token does not strand the forwarder.
let forward = tokio_util::task::AbortOnDropHandle::new(tokio::spawn({
let loop_cancel = loop_cancel.clone();
let cancel = cancel.clone();
async move {
cancel.cancelled().await;
loop_cancel.cancel();
}
}));
// Loaded skills ride with the request that loaded them, in the model's copy
// of the conversation only.
let mut messages = messages;
crate::domain::skill_routing::inject(&mut messages, &loaded_skills);
let rig_messages = agent::to_rig_messages_limited(&messages, &tool_results);
let result = async {
let mut stream = session.send_message(rig_messages).await?;
let mut turn_spoke = false;
// The opening line's model usually has its verdict long before this
// one's first prose. Thinking passes through while the race goes on;
// should this model write prose or call a tool first, its own opening
// stands and the line is dropped.
let race = {
let verdict =
tokio::time::timeout(opener::VERDICT_TIMEOUT, opener::verdict(&mut opening_line));
tokio::pin!(verdict);
loop {
tokio::select! {
biased;
part = stream.next() => {
if !turn_spoke {
turn_spoke = true;
opener_span
.record("agent.opener.turn_first_part_ms", elapsed_ms(started));
}
match part {
Some(Ok(part @ (StreamPart::Thinking(_) | StreamPart::Usage(_)))) => {
if parts.send(Ok(part)).await.is_err() {
loop_cancel.cancel();
return Ok(());
}
}
part => break Race::TurnFirst(part),
}
}
opening = &mut verdict => break Race::Opening(opening),
}
}
};
let mut separate = false;
match race {
Race::TurnFirst(None) => {
opener_span.record("agent.opener.outcome", "turn_first");
return Ok(());
}
Race::TurnFirst(Some(part)) => {
opener_span.record("agent.opener.outcome", "turn_first");
if parts.send(part).await.is_err() {
loop_cancel.cancel();
return Ok(());
}
}
Race::Opening(Ok(Some(verdict))) => {
opener_span.record("agent.opener.verdict_ms", elapsed_ms(started));
let (outcome, line) = match verdict {
opener::Verdict::Complete(head) => ("complete", Some((true, head))),
opener::Verdict::Opening(head) => ("opening", Some((false, head))),
opener::Verdict::Silent => ("silent", None),
};
opener_span.record("agent.opener.outcome", outcome);
if let Some((complete, head)) = line {
let deadline = tokio::time::Instant::now() + opener::LINE_TIMEOUT;
let mut line_chars = 0;
let mut finished = false;
let mut delta = Some(head);
while let Some(text) = delta {
line_chars += text.chars().count();
opener_span.record("agent.opener.line_chars", line_chars);
if !text.is_empty()
&& parts.send(Ok(StreamPart::Content(text))).await.is_err()
{
loop_cancel.cancel();
return Ok(());
}
delta = match tokio::time::timeout_at(deadline, opening_line.recv()).await {
Ok(next) => {
finished = next.is_none();
next
}
Err(_) => None,
};
}
// Only a whole line stands alone: one that stalled or
// came out empty leaves the reply to this model.
if complete && finished && line_chars > 0 {
loop_cancel.cancel();
return Ok(());
}
separate = line_chars > 0;
}
}
Race::Opening(Ok(None)) => {
opener_span.record("agent.opener.outcome", "no_verdict");
}
Race::Opening(Err(_)) => {
opener_span.record("agent.opener.outcome", "timeout");
}
}
drop(opening_line);
while let Some(part) = stream.next().await {
if !turn_spoke {
turn_spoke = true;
opener_span.record("agent.opener.turn_first_part_ms", elapsed_ms(started));
}
let part = match part {
Ok(StreamPart::Content(text)) if separate && !text.trim().is_empty() => {
separate = false;
Ok(StreamPart::Content(format!("\n\n{}", text.trim_start())))
}
other => other,
};
if parts.send(part).await.is_err() {
// The consumer is gone; stop the loop rather than keep
// spending tokens into the void.
loop_cancel.cancel();
break;
}
}
Ok(())
}
.await;
forward.abort();
result
}
/// Which spoke first: the turn's own model, or the opening line's.
enum Race {
TurnFirst(Option<Result<StreamPart, AgentError>>),
/// The verdict, `None` without one, or `Err` past the verdict timeout.
Opening(Result<Option<opener::Verdict>, tokio::time::error::Elapsed>),
}
fn elapsed_ms(since: tokio::time::Instant) -> u64 {
u64::try_from(since.elapsed().as_millis()).unwrap_or(u64::MAX)
}
/// The turn's system prompt, ordered so the longest possible prefix is
/// cached: the agent-session preamble (which notes that an opening line may
/// already be out, see [`opener`]; a session whose replies are read whole is
/// told otherwise in its own part) and the static Macro prompt (how to use the
/// product: mentions, tools, terminology), which are the same for every
/// session of every agent; then the agent's identity, the session's own
/// instructions when there are any, which session this is, and the owner's
/// memory when there is any; and last the SDK documentation picked for this
/// turn.
///
/// The prompt is split after the static Macro prompt, so every session reads
/// it back from the cache whatever its agent or instructions. Identity opens
/// the session's part so a named agent (even one with no instructions) knows
/// who it is before its instructions, and `<session_instructions>` follows
/// the standing prompt so the model reads it as the caller's word — the same
/// reason DCS puts `additional_instructions` after the standing prompt.
/// Memory stays after the instructions so a remembered fact is never read as
/// an instruction. The turn's documentation goes after everything the loop
/// adds, because each turn picks different documentation.
fn system_prompt(
tools_prompt: &impl std::fmt::Display,
sdk_docs: &str,
session_id: agent_session::domain::model::AgentSessionId,
delivery: ReplyDelivery,
identity: Option<&AgentIdentity>,
instructions: Option<&str>,
user_memory: Option<&str>,
) -> SystemPrompt {
let mut shared = String::new();
shared.push_str(&prompt::agent_session::PROMPT.to_string());
shared.push_str(&tools_prompt.to_string());
let mut rest = String::new();
if let Some(identity) = identity {
rest.push('\n');
rest.push_str(&prompt::agent_identity::render(
&identity.name,
&identity.handle,
));
}
// Blank instructions are "none" stated clumsily. A delimited section with
// nothing in it is worse than no section: the model has to decide what an
// empty instruction means.
if let Some(instructions) = instructions.filter(|text| !text.trim().is_empty()) {
rest.push_str("\n<session_instructions>\n");
rest.push_str(instructions);
rest.push_str("\n</session_instructions>");
}
rest.push_str(&format!(
"\n<agent_session>\nThis conversation is agent session {session_id}. Once it grows \
long, its earlier part is summarized to keep it within your context. To find the exact \
words of anything said earlier, summarized or not, run ContentSearch with \
agentSessionIds [\"{session_id}\"]. ContentSearch remains a direct tool for scoped session-history search.\n</agent_session>"
));
if delivery == ReplyDelivery::Whole {
rest.push('\n');
rest.push_str(opener::NOT_OPENED);
}
if let Some(memory) = user_memory {
rest.push_str("\n<user_memory>\n");
rest.push_str(memory);
rest.push_str("\n</user_memory>");
}
SystemPrompt::split(shared, rest).with_turn(sdk_docs)
}
/// The owner's memory block, or `None` when it is missing or failed to load.
async fn fetch_user_memory(
memory_service: &MemoryServiceImpl<PgMemoryRepo>,
owner: &MacroUserIdStr<'static>,
) -> Option<String> {
match memory_service.get_memory(owner.clone()).await {
Ok(memory) => memory.map(|memory| memory.to_string()),
Err(error) => {
tracing::warn!(error=?error, %owner, "failed to fetch user memory; running without it");
None
}
}
}