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
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::time::Duration;
use uuid::Uuid;
/// Identity assigned by the runner, never by sandbox code.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct RunId(pub Uuid);
/// A JavaScript ES module exporting an async `main` function.
#[derive(Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ExecuteRequest {
/// Complete JavaScript module, including imports and `export async function main`.
pub source: String,
/// Total budget including queueing and API requests.
pub timeout_ms: u64,
}
/// Run-only credentials and destinations supplied by the authenticated host.
/// Never serialize this into journals, tool results, or tracing fields.
#[derive(Clone, Serialize, Default)]
#[serde(rename_all = "camelCase")]
pub struct RunEnvironment {
/// Short-lived user bearer token; no refresh credential is provided.
pub token: String,
/// W3C trace context from the trusted host, sent only on authenticated SDK traffic.
pub trace_headers: std::collections::BTreeMap<String, String>,
/// Authenticated session handle made available to the program.
pub session_id: Option<Uuid>,
/// Current execution handle made available to the program.
pub execution_id: Option<Uuid>,
/// Explicit Macro SDK service base URLs, also used for Deno's network allowlist.
pub hosts: std::collections::BTreeMap<String, String>,
/// Set for a program that runs with nobody watching (a routine step)
/// instead of an agent's or a person's call.
#[serde(skip_serializing_if = "Option::is_none")]
pub unattended: Option<Unattended>,
}
/// How an unattended program runs: its source is TypeScript, and `main`
/// receives `macro` and `arguments` but never the credential.
#[derive(Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Unattended {
/// Spread into `main`'s argument beside `macro`.
pub arguments: serde_json::Map<String, Value>,
/// No write runs: each one returns an empty result to the program and is
/// reported as skipped, so a run shows what it would have done. Writes
/// are every catalog operation that isn't a known read, so an operation
/// missing from the catalog is a write.
pub dry_run: bool,
}
/// Frame bytes kept beside a full-size result for its `{"type":"result",...}` envelope.
pub const RESULT_FRAME_OVERHEAD: usize = 256;
/// Server-owned admission and execution limits.
#[derive(Debug, Clone)]
pub struct Limits {
/// Maximum simultaneous Deno executions.
pub max_running: usize,
/// Additional admitted executions waiting for a process slot.
pub max_queued: usize,
/// Maximum requested execution lifetime.
pub max_duration: Duration,
/// Maximum UTF-8 source length.
pub max_source_bytes: usize,
/// Maximum individual child frame, including the final model-facing result.
pub max_frame_bytes: usize,
/// Combined stdout and stderr budget per execution.
pub max_output_bytes: usize,
/// Largest model-facing result JSON; a larger `data` is replaced by a bounded summary.
pub max_result_bytes: usize,
/// Maximum regular events, plus a separate equal budget for advisory progress.
pub max_events: usize,
/// CPU time a process may use across its threads before the kernel stops
/// it; `None` leaves only the wall-clock deadline.
pub max_cpu: Option<Duration>,
/// Run processes at a lower scheduling priority than the host, so busy
/// background programs yield the CPU to its requests.
pub background: bool,
}
impl Default for Limits {
fn default() -> Self {
Self {
max_running: 8,
max_queued: 16,
max_duration: Duration::from_secs(30),
max_source_bytes: 64 * 1024,
max_frame_bytes: 256 * 1024,
max_output_bytes: 2 * 1024 * 1024,
max_result_bytes: 64 * 1024,
max_events: 1024,
max_cpu: None,
background: false,
}
}
}
impl Limits {
/// Reject unusable or unreasonable deployment settings before serving traffic.
pub fn validate(&self) -> Result<(), AdmissionError> {
if !(1..=64).contains(&self.max_running)
|| self.max_queued > 1024
|| self.max_duration.is_zero()
|| self.max_duration > Duration::from_secs(300)
|| !(1..=1024 * 1024).contains(&self.max_source_bytes)
|| !(1024..=1024 * 1024).contains(&self.max_frame_bytes)
|| self.max_output_bytes < self.max_frame_bytes
|| self.max_output_bytes > 16 * 1024 * 1024
|| self.max_result_bytes < 512
|| self.max_result_bytes + RESULT_FRAME_OVERHEAD > self.max_frame_bytes
|| !(2..=65536).contains(&self.max_events)
|| self
.max_cpu
.is_some_and(|cpu| cpu < Duration::from_secs(1) || cpu > self.max_duration)
{
return Err(AdmissionError::InvalidLimits);
}
Ok(())
}
}
/// Admission fails before a process is started.
#[derive(Debug, thiserror::Error)]
pub enum AdmissionError {
/// Invalid startup configuration.
#[error("invalid execution limits")]
InvalidLimits,
/// Empty or oversized source.
#[error("source must be nonempty and within the configured size limit")]
InvalidSource,
/// A caller cannot raise the server's deadline.
#[error("timeout must be positive and within the configured limit")]
InvalidTimeout,
/// Running and queued slots are both occupied.
#[error("execution capacity exhausted")]
Busy,
/// The runner is draining.
#[error("runner is shutting down")]
ShuttingDown,
}
/// Stable categories suitable for backend retry and presentation decisions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FailureCode {
/// Legacy source compilation failure retained for persisted outcomes.
Compile,
/// Program threw or exited without a result.
Runtime,
/// Invalid, duplicate, or unsolicited bridge messages.
Protocol,
/// Byte, event, or consumer capacity was exceeded.
Limit,
/// Runner infrastructure failed.
Internal,
}
/// A bounded failure description. Source and data must not be traced by callers.
#[derive(Debug, Clone, Serialize, Deserialize, thiserror::Error)]
#[error("{code:?}: {message}")]
pub struct ExecutionFailure {
/// Machine-readable failure category.
pub code: FailureCode,
/// Human-readable diagnostic, potentially containing user data.
pub message: String,
}
impl ExecutionFailure {
/// Construct a failure without attaching source or credentials.
pub fn new(code: FailureCode, message: impl Into<String>) -> Self {
Self {
code,
message: message.into(),
}
}
}
/// Exactly one terminal outcome is emitted after process cleanup.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "status", rename_all = "snake_case")]
pub enum Outcome {
/// JSON returned by the program, not a trusted assertion about external state.
Succeeded {
/// Returned JSON; `undefined` becomes `null`.
value: Value,
},
/// Execution or transport failed.
Failed {
/// Failure details.
error: ExecutionFailure,
},
/// Cancellation was requested, including by disconnect.
Cancelled,
/// Queueing or execution exhausted its wall-clock budget.
TimedOut,
}
impl From<ExecutionFailure> for Outcome {
fn from(error: ExecutionFailure) -> Self {
Self::Failed { error }
}
}
/// Supported console levels.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LogLevel {
/// Debug output.
Debug,
/// Informational output.
Info,
/// Warning output, including raw stderr.
Warn,
/// Error output.
Error,
}
/// Events from the supervisor; program output is untrusted data.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum EventKind {
/// The execution has been admitted.
Queued,
/// A process slot has been acquired.
Started,
/// Program console or process stderr.
Log {
/// Console severity.
level: LogLevel,
/// Untrusted text.
message: String,
},
/// Program-authored progress; not an assertion of external API completion.
Progress {
/// Bounded JSON progress data.
value: Value,
},
/// Terminal event, after reaping the process and releasing its scratch directory.
Finished {
/// Terminal outcome.
outcome: Outcome,
},
}
/// Ordered envelope stamped by the supervisor.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExecutionEvent {
/// Supervisor-assigned identity.
pub run_id: RunId,
/// Monotonic sequence starting at zero, local to the execution.
pub sequence: u64,
/// Event payload.
#[serde(flatten)]
pub kind: EventKind,
}
/// One type-checker problem, as the checker reported it. Locations are
/// `<file>:<line>:<column>`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Diagnostic {
/// The file it is in, when it is in one of the checked files.
pub file: Option<String>,
/// The problem with its code, the offending line and its location.
pub message: String,
}
/// A TypeScript module checked together with others.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SourceFile {
/// Its file name: lowercase letters, digits and `_`, ending in `.ts`.
pub name: String,
/// Its source.
pub source: String,
}
/// The checker couldn't decide whether a program checks.
#[derive(Debug, thiserror::Error)]
pub enum CheckError {
/// Empty or oversized source.
#[error("source must be nonempty and within the configured size limit")]
InvalidSource,
/// Every checker slot is busy.
#[error("type checking is busy; try again later")]
Busy,
/// The checker process failed or ran out of time.
#[error("type checking failed to run")]
Internal,
}