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
//! The program's data model and its stored JSON form.
use std::fmt;
use bots::domain::models::AgentMcpServer;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use uuid::Uuid;
use crate::knob::Knob;
#[cfg(test)]
mod test;
/// What a routine does each time it runs.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RoutineProgram {
/// Steps run in order. A failed step stops the run.
pub steps: Vec<Step>,
/// Apps the routine requires, handed to its agent on top of the agent's
/// own. The owner must have each one connected to save the routine and
/// for it to run.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mcp_servers: Vec<AgentMcpServer>,
/// Loaded from a single-agent task saved before programs existed, whose
/// instructions had no length or blank limits; validation keeps it so.
#[serde(skip)]
pub(crate) single_agent_task: bool,
/// The SDK its code steps were last type-checked against, recorded by
/// the service that checked them. A run on another SDK checks them again
/// before running them.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub sdk: Option<SdkFingerprint>,
}
/// One step of a routine.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Step {
/// Run TypeScript against Macro's SDK, as the routine owner.
Code(CodeStep),
/// Hand the run to a model or agent with instructions.
Agent(AgentStep),
}
/// TypeScript written against Macro's SDK, usually by the AI that built the
/// routine. It is type-checked before it is saved and runs with its owner's
/// access.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CodeStep {
/// Names this step's output for later steps: `steps.<id>` in later code.
/// Saving gives a step without one an id from its title, e.g.
/// `label_invoices`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub id: Option<StepId>,
/// What the step does, in a few words, e.g. "Label invoices".
pub title: String,
/// One or two sentences on how, for the routine's owner.
#[serde(default, skip_serializing_if = "String::is_empty")]
pub summary: String,
/// A module exporting `async function main({ macro, run, routine,
/// trigger, steps }: StepContext)`: `run` is this run (its time, zone and
/// the previous run), `trigger` what started it (a schedule, an event and
/// its item, or a person), `steps` the typed outputs of the steps before
/// it. What `main` returns, as JSON of at most 64 KB, is the step's output.
pub source: String,
/// Values its owner can change without new code, which the code reads
/// as `knobs.<name>`.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub knobs: Vec<Knob>,
/// What it does as one sentence for its owner, with `{name}` where a
/// knob's value shows and `{?name}` where a question knob's question
/// shows, e.g. "Label it {label} when {?aboutMoney}". Saving checks every
/// slot names one of its knobs.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub sentence: Option<String>,
}
impl CodeStep {
/// Each knob's value by name: `main`'s `knobs`.
pub fn knob_values(&self) -> serde_json::Map<String, Value> {
self.knobs
.iter()
.map(|knob| (knob.name().to_string(), knob.value()))
.collect()
}
}
/// Identifies the SDK API code was type-checked against: its version and a
/// hash of its declarations, e.g. `0.2.2+18cc1c19c35c`.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
pub struct SdkFingerprint(pub(crate) String);
impl SdkFingerprint {
/// The fingerprint as written.
pub fn as_str(&self) -> &str {
&self.0
}
}
impl TryFrom<String> for SdkFingerprint {
type Error = BlankFingerprint;
fn try_from(value: String) -> Result<Self, Self::Error> {
if value.trim().is_empty() {
return Err(BlankFingerprint);
}
Ok(Self(value))
}
}
impl From<SdkFingerprint> for String {
fn from(fingerprint: SdkFingerprint) -> Self {
fingerprint.0
}
}
impl fmt::Display for SdkFingerprint {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
/// An SDK fingerprint that is empty or only whitespace.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error("an SDK fingerprint must not be blank")]
pub struct BlankFingerprint;
/// Names a step's output: a lowercase letter, then up to 31 lowercase
/// letters, digits or underscores.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
pub struct StepId(String);
impl StepId {
/// The id as written.
pub fn as_str(&self) -> &str {
&self.0
}
}
impl TryFrom<String> for StepId {
type Error = InvalidStepId;
fn try_from(value: String) -> Result<Self, Self::Error> {
let mut chars = value.chars();
let valid = value.len() <= 32
&& chars.next().is_some_and(|first| first.is_ascii_lowercase())
&& chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_');
if valid {
Ok(Self(value))
} else {
Err(InvalidStepId(value))
}
}
}
impl From<StepId> for String {
fn from(id: StepId) -> Self {
id.0
}
}
impl fmt::Display for StepId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
/// A step id that is not a lowercase identifier.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error(
"step id `{0}` must be a lowercase letter followed by up to 31 lowercase letters, digits or underscores"
)]
pub struct InvalidStepId(String);
/// Hand the run to a model running as Macro, or to an agent.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AgentStep {
/// Required when no agent is selected; otherwise overrides the agent's default model.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub model: Option<String>,
/// The agent (persona) that runs, by `bot_id` from ListAgents.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub agent: Option<AgentSelection>,
/// What the model or agent should do. It also sees the triggering event
/// and what earlier steps in this run did.
pub instructions: String,
}
/// A persona selection, independent of its runtime and current default model.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "schema", schema(as = AgentTaskAgent))]
#[serde(deny_unknown_fields)]
pub struct AgentSelection {
/// The agent's bot id.
#[cfg_attr(feature = "schema", schema(value_type = String, format = Uuid))]
pub bot_id: Uuid,
}
/// A nonblank model identifier. Runtime catalogs, not the scheduler, own availability.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(try_from = "String", into = "String")]
pub struct RoutineModelId(String);
impl RoutineModelId {
/// The id as written.
pub fn as_str(&self) -> &str {
&self.0
}
}
impl TryFrom<String> for RoutineModelId {
type Error = BlankModelId;
fn try_from(value: String) -> Result<Self, Self::Error> {
if value.trim().is_empty() {
return Err(BlankModelId);
}
Ok(Self(value))
}
}
impl From<RoutineModelId> for String {
fn from(id: RoutineModelId) -> Self {
id.0
}
}
/// A model id that is empty or only whitespace.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error("a supplied model must not be blank")]
pub struct BlankModelId;
/// The single agent task: how routines were stored before they had steps,
/// and still how a routine that is only an agent is saved.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct AgentTask {
/// Required for model targets; overrides the persona default for agent targets.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub model: Option<RoutineModelId>,
/// Absent when using Macro's agent-session runtime with a selected model.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub agent: Option<AgentSelection>,
/// Apps the routine requires on top of the agent's own. The owner must
/// have each one connected to save the routine and for it to run.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub mcp_servers: Vec<AgentMcpServer>,
/// Instructions placed before the user's.
pub prompt: String,
/// What the agent should do.
pub user_prompt: String,
}
/// A stored task that is neither a program nor a pre-program agent task.
#[derive(Debug, thiserror::Error)]
#[error("invalid routine task: {0}")]
pub struct InvalidTask(#[from] serde_json::Error);
impl RoutineProgram {
/// A program of `steps`, without apps or a checked SDK.
pub fn new(steps: Vec<Step>) -> Self {
Self {
steps,
mcp_servers: Vec::new(),
single_agent_task: false,
sdk: None,
}
}
/// Read a stored task: a program (`{"steps": [...]}`), or the single agent
/// task written before routines had steps, which becomes one agent step.
pub fn from_task(task: &Value) -> Result<Self, InvalidTask> {
if task.get("steps").is_some() {
return Ok(serde_json::from_value(task.clone())?);
}
let legacy: AgentTask = serde_json::from_value(task.clone())?;
let instructions = match legacy.prompt.trim() {
"" => legacy.user_prompt,
prompt => format!("{prompt}\n\n{}", legacy.user_prompt),
};
Ok(Self {
steps: vec![Step::Agent(AgentStep {
model: legacy.model.map(String::from),
agent: legacy.agent,
instructions,
})],
mcp_servers: legacy.mcp_servers,
single_agent_task: true,
sdk: None,
})
}
/// Every code step, mutably, in program order.
pub fn code_steps_mut(&mut self) -> Vec<&mut CodeStep> {
self.steps
.iter_mut()
.filter_map(|step| match step {
Step::Code(step) => Some(step),
Step::Agent(_) => None,
})
.collect()
}
/// Every code step, in program order.
pub fn code_steps(&self) -> Vec<&CodeStep> {
self.steps
.iter()
.filter_map(|step| match step {
Step::Code(step) => Some(step),
Step::Agent(_) => None,
})
.collect()
}
/// Every agent step, in program order.
pub fn agent_steps(&self) -> Vec<&AgentStep> {
self.steps
.iter()
.filter_map(|step| match step {
Step::Agent(agent) => Some(agent),
Step::Code(_) => None,
})
.collect()
}
/// The agent the run starts with, when its first step is one. Such a run
/// opens its transcript before anything else happens.
pub fn leading_agent(&self) -> Option<&AgentStep> {
match self.steps.first() {
Some(Step::Agent(agent)) => Some(agent),
_ => None,
}
}
}