use std::collections::BTreeMap;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
pub const SCHEMA_VERSION: u32 = 4;
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct CommandUnit {
pub id: String,
pub argv: Vec<String>,
#[serde(default)]
pub cwd: Option<String>,
#[serde(default)]
pub env: BTreeMap<String, String>,
#[serde(default)]
pub secrets: BTreeMap<String, SecretRef>,
#[serde(default)]
pub shell: bool,
#[serde(default)]
pub timeout_ms: Option<u64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum CommandTopology {
Parallel {
max_parallel: u32,
#[serde(default)]
fail_fast: bool,
},
Pipeline {
#[serde(default = "pipefail_default")]
pipefail: bool,
},
}
fn pipefail_default() -> bool {
true
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
pub struct ProcessIdentity {
#[serde(default)]
pub boot_id: String,
pub pid: u32,
pub ppid: Option<u32>,
pub pgid: Option<u32>,
pub started_at: u64,
#[serde(default)]
pub started_at_ns: u64,
pub name: String,
pub executable: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ExecutionProgram {
Command {
argv: Vec<String>,
shell: bool,
},
Commands {
commands: Vec<CommandUnit>,
topology: CommandTopology,
},
Javascript {
source: String,
#[serde(default)]
input: serde_json::Value,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum LeaseOwnerKind {
Execution,
Session,
Persistent,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RetryPolicy {
pub max_attempts: u32,
pub backoff_ms: u64,
pub max_backoff_ms: u64,
}
impl Default for RetryPolicy {
fn default() -> Self {
Self {
max_attempts: 1,
backoff_ms: 500,
max_backoff_ms: 30_000,
}
}
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionBudget {
pub wall_time_ms: Option<u64>,
pub child_processes: Option<u32>,
pub artifact_bytes: Option<u64>,
pub progress_timeout_ms: Option<u64>,
#[serde(default)]
pub cancel_on_stall: bool,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct WorkspaceContext {
pub cwd: Option<String>,
pub repository: Option<String>,
pub worktree: Option<String>,
pub commit: Option<String>,
pub branch: Option<String>,
pub dirty_digest: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionSpec {
pub schema_version: u32,
#[serde(default)]
pub idempotency_key: Option<String>,
pub name: String,
pub purpose: Option<String>,
#[serde(default)]
pub labels: BTreeMap<String, String>,
pub program: ExecutionProgram,
#[serde(default)]
pub workspace: WorkspaceContext,
#[serde(default)]
pub env: BTreeMap<String, String>,
#[serde(default)]
pub secrets: BTreeMap<String, SecretRef>,
pub io: IoMode,
pub owner_kind: LeaseOwnerKind,
pub owner_id: Option<String>,
pub expires_at: Option<u64>,
#[serde(default)]
pub retry: RetryPolicy,
#[serde(default)]
pub budget: ExecutionBudget,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct SecretRef {
pub provider: String,
pub reference: String,
pub version: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecutionStatus {
Queued,
Running,
Stalled,
Interrupted,
Completed,
Failed,
Canceled,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionPass {
pub id: String,
pub number: u32,
pub started_at: u64,
pub completed_at: Option<u64>,
pub status: ExecutionStatus,
pub error_code: Option<String>,
pub error: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionAttempt {
pub id: String,
pub number: u32,
#[serde(default)]
pub processes: Vec<ProcessIdentity>,
pub started_at: u64,
pub completed_at: Option<u64>,
pub exit_code: Option<i32>,
pub error_code: Option<String>,
pub stdout_artifact: Option<String>,
pub stderr_artifact: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Execution {
pub id: String,
pub parent_id: Option<String>,
pub session_id: Option<String>,
pub spec: ExecutionSpec,
pub status: ExecutionStatus,
#[serde(default)]
pub passes: Vec<ExecutionPass>,
#[serde(default)]
pub attempts: Vec<ExecutionAttempt>,
pub created_at: u64,
pub updated_at: u64,
pub last_progress_at: u64,
pub result: Option<serde_json::Value>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionProgramSummary {
pub kind: String,
pub executable: Option<String>,
pub argument_count: usize,
pub command_count: usize,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionSummary {
pub id: String,
pub parent_id: Option<String>,
pub session_id: Option<String>,
pub idempotency_key: Option<String>,
pub name: String,
pub name_truncated: bool,
pub status: ExecutionStatus,
pub program: ExecutionProgramSummary,
pub cwd: Option<String>,
pub cwd_truncated: bool,
pub attempt_count: usize,
pub exit_code: Option<i32>,
pub error_code: Option<String>,
pub created_at: u64,
pub updated_at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionListPage {
pub executions: Vec<ExecutionSummary>,
pub next_cursor: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct AgentSession {
pub id: String,
pub actor: String,
#[serde(default)]
pub labels: BTreeMap<String, String>,
pub created_at: u64,
pub heartbeat_at: u64,
pub expires_at: u64,
pub closed: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Lease {
pub id: String,
pub owner_kind: LeaseOwnerKind,
pub owner_id: String,
#[serde(default)]
pub resources: Vec<String>,
pub created_at: u64,
pub renewed_at: u64,
pub expires_at: Option<u64>,
pub released: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ReservationKind {
Port,
Path,
Process,
Device,
Custom,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Reservation {
pub id: String,
pub kind: ReservationKind,
pub key: String,
pub lease_id: String,
pub created_at: u64,
pub expires_at: Option<u64>,
pub external_conflict: bool,
pub released: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ReceiptState {
Applied,
Partial,
Failed,
Unknown,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct OperationTarget {
pub key: String,
pub applied: bool,
pub error_code: Option<String>,
pub error: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct OperationReceipt {
pub id: String,
pub idempotency_key: String,
pub operation: String,
pub actor: String,
pub execution_id: Option<String>,
pub state: ReceiptState,
pub targets: Vec<OperationTarget>,
pub started_at: u64,
pub completed_at: Option<u64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct CausalEvent {
pub sequence: u64,
pub id: String,
pub at: u64,
pub kind: String,
pub subject: String,
pub actor: String,
pub correlation_id: String,
pub causation_id: Option<String>,
pub execution_id: Option<String>,
pub session_id: Option<String>,
pub payload_id: Option<String>,
#[serde(default)]
pub details: serde_json::Value,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ArtifactMetadata {
pub id: String,
pub kind: String,
pub execution_id: Option<String>,
pub bytes: u64,
pub created_at: u64,
pub accessed_at: u64,
pub pinned: bool,
pub pruned: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessInfo {
pub identity: ProcessIdentity,
pub status: String,
#[serde(default)]
pub user_id: Option<String>,
#[serde(default)]
pub effective_user_id: Option<String>,
#[serde(default)]
pub group_id: Option<String>,
#[serde(default)]
pub session_id: Option<u32>,
pub cpu_percent: f32,
pub memory_bytes: u64,
pub virtual_memory_bytes: u64,
pub runtime_seconds: u64,
pub command: Vec<String>,
pub cwd: Option<String>,
pub disk_read_bytes: u64,
pub disk_written_bytes: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessSample {
pub at: u64,
pub processes: Vec<ProcessInfo>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessWait {
pub selector: String,
pub condition: String,
pub satisfied: bool,
pub elapsed_ms: u64,
pub processes: Vec<ProcessIdentity>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct PortInfo {
pub protocol: String,
pub address: String,
pub port: u16,
pub state: Option<String>,
pub pids: Vec<u32>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessFile {
pub process: ProcessIdentity,
pub fd: i32,
pub kind: String,
pub path: String,
pub open_flags: u32,
pub offset: i64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessProbe {
pub target: String,
pub exists: bool,
pub processes: Vec<ProcessIdentity>,
pub observed_at: u64,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct ProcessPredicate {
pub pid: Option<u32>,
pub ppid: Option<u32>,
pub pgid: Option<u32>,
pub name: Option<String>,
pub name_regex: Option<String>,
pub argv_regex: Option<String>,
pub cwd_prefix: Option<String>,
pub status: Option<String>,
pub user_id: Option<String>,
pub port: Option<u16>,
pub protocol: Option<String>,
pub actor: Option<String>,
pub execution_id: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessQuery {
#[serde(default)]
pub all: Vec<ProcessPredicate>,
#[serde(default)]
pub any: Vec<ProcessPredicate>,
#[serde(default)]
pub not: Vec<ProcessPredicate>,
pub sort: String,
pub limit: usize,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessInsight {
pub kind: String,
pub target: String,
pub processes: Vec<ProcessInfo>,
pub executions: Vec<Execution>,
pub leases: Vec<Lease>,
pub reservations: Vec<Reservation>,
pub events: Vec<CausalEvent>,
pub limitations: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessSelection {
pub id: String,
pub selector: String,
pub resolved_at: u64,
pub processes: Vec<ProcessIdentity>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessController {
pub invocation_id: String,
pub agent: bool,
pub actor: String,
pub controller_pid: u32,
pub parent_pid: Option<u32>,
pub cwd: Option<String>,
pub argv: Vec<String>,
pub execution_id: Option<String>,
}
impl ProcessController {
pub fn capture(agent: bool, execution_id: Option<String>) -> Self {
Self {
invocation_id: uuid::Uuid::now_v7().to_string(),
agent,
actor: std::env::var("APOC_ACTOR").unwrap_or_else(|_| {
if agent {
"agent".to_string()
} else {
"human".to_string()
}
}),
controller_pid: std::process::id(),
parent_pid: {
let pid = unsafe { libc::getppid() };
(pid > 0).then_some(pid as u32)
},
cwd: std::env::current_dir()
.ok()
.map(|path| path.to_string_lossy().into_owned()),
argv: std::env::args().collect(),
execution_id,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessContext {
pub key: String,
pub first_observed_at: u64,
pub last_observed_at: u64,
pub observations: u64,
#[serde(default)]
pub snapshot_id: Option<String>,
pub origin: String,
#[serde(default, alias = "run_id")]
pub execution_id: Option<String>,
pub latest: ProcessInfo,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessEvent {
pub id: String,
pub process_key: String,
pub at: u64,
pub operation: String,
pub phase: String,
pub selector: Option<String>,
pub controller: ProcessController,
#[serde(default, alias = "run_id")]
pub execution_id: Option<String>,
pub details: serde_json::Value,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct ProcessEventQuery {
pub limit: usize,
pub process_key: Option<String>,
pub pid: Option<u32>,
pub operation: Option<String>,
pub phase: Option<String>,
pub actor: Option<String>,
pub controller_execution_id: Option<String>,
pub execution_id: Option<String>,
pub since_ms: Option<u64>,
pub until_ms: Option<u64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProcessDossier {
pub context: ProcessContext,
pub events: Vec<ProcessEvent>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ActionResult {
pub process: ProcessIdentity,
pub action: String,
pub applied: bool,
pub exited: bool,
pub error: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ActionReceipt {
pub id: String,
pub selector: String,
pub action: String,
pub started_at: u64,
pub completed_at: u64,
pub results: Vec<ActionResult>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum IoMode {
Pipes,
Pty,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum RunLifetime {
Execution,
Persistent,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum RestartPolicy {
Never,
OnFailure,
Always,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RunSpec {
pub name: String,
#[serde(default)]
pub purpose: Option<String>,
#[serde(default)]
pub labels: std::collections::BTreeMap<String, String>,
#[serde(default)]
pub requested_by: Option<ProcessController>,
pub argv: Vec<String>,
pub cwd: Option<String>,
pub env: std::collections::BTreeMap<String, String>,
pub shell: bool,
pub io: IoMode,
pub lifetime: RunLifetime,
pub restart: RestartPolicy,
pub timeout_ms: Option<u64>,
pub replicas: u32,
#[serde(default = "one_attempt")]
pub max_attempts: u32,
#[serde(default = "default_retry_backoff")]
pub retry_backoff_ms: u64,
#[serde(default = "default_retry_max_backoff")]
pub retry_max_backoff_ms: u64,
}
fn one_attempt() -> u32 {
1
}
fn default_retry_backoff() -> u64 {
500
}
fn default_retry_max_backoff() -> u64 {
30_000
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ManagedRun {
pub id: String,
pub spec: RunSpec,
pub status: String,
pub processes: Vec<ProcessIdentity>,
#[serde(default)]
pub process_history: Vec<ProcessIdentity>,
pub created_at: u64,
pub updated_at: u64,
pub exit_code: Option<i32>,
pub stdout_path: Option<String>,
pub stderr_path: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Service {
pub name: String,
pub spec: RunSpec,
pub enabled: bool,
pub run_id: Option<String>,
pub created_at: u64,
pub updated_at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ServiceInfo {
pub service: Service,
pub run: Option<ManagedRun>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Recipe {
pub name: String,
pub description: String,
pub code: String,
#[serde(default)]
pub input_schema: Option<serde_json::Value>,
pub created_at: u64,
pub updated_at: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ProviderKind {
Builtin,
McpHttp,
McpStdio,
OpenApi,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ProviderConfig {
pub name: String,
pub kind: ProviderKind,
#[serde(default)]
pub url: Option<String>,
#[serde(default)]
pub base_url: Option<String>,
#[serde(default)]
pub command: Option<String>,
#[serde(default)]
pub args: Vec<String>,
#[serde(default)]
pub cwd: Option<String>,
#[serde(default)]
pub env: BTreeMap<String, String>,
#[serde(default)]
pub secret_env: BTreeMap<String, SecretRef>,
#[serde(default)]
pub headers: std::collections::BTreeMap<String, String>,
#[serde(default)]
pub secret_headers: BTreeMap<String, SecretRef>,
#[serde(default)]
pub instructions: Option<String>,
#[serde(default = "provider_enabled")]
pub enabled: bool,
#[serde(default)]
pub generation: String,
pub created_at: u64,
pub updated_at: u64,
}
fn provider_enabled() -> bool {
true
}
pub fn valid_provider_name(value: &str) -> bool {
let mut characters = value.chars();
let Some(first) = characters.next() else {
return false;
};
(first.is_ascii_alphabetic() || matches!(first, '_' | '$'))
&& characters
.all(|character| character.is_ascii_alphanumeric() || matches!(character, '_' | '$'))
}
pub type ConnectorKind = ProviderKind;
pub type ConnectorConfig = ProviderConfig;
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct CapabilityAnnotations {
pub read_only: Option<bool>,
pub destructive: Option<bool>,
pub idempotent: Option<bool>,
pub open_world: Option<bool>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum IdentityMode {
Exact,
Stable,
Opaque,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum CoordinationMode {
Resource,
Provider,
None,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum VerificationMode {
Readback,
Receipt,
Unavailable,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct CapabilityDescriptor {
pub provider: String,
pub method: String,
pub description: Option<String>,
pub input_schema: serde_json::Value,
pub output_schema: Option<serde_json::Value>,
pub annotations: CapabilityAnnotations,
pub identity_mode: IdentityMode,
pub coordination_mode: CoordinationMode,
pub verification_mode: VerificationMode,
pub generation: String,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ResourceIdentity {
pub provider: String,
pub kind: String,
pub key: String,
pub version: Option<String>,
pub mode: IdentityMode,
}
pub fn now_ms() -> u64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_millis() as u64
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn publishes_the_v4_execution_contract() {
assert_eq!(SCHEMA_VERSION, 4);
let schema = serde_json::to_value(schemars::schema_for!(ExecutionSpec)).unwrap();
let text = serde_json::to_string(&schema).unwrap();
assert!(text.contains("schema_version"));
assert!(text.contains("idempotency_key"));
assert!(text.contains("javascript"));
assert!(text.contains("max_attempts"));
assert!(text.contains("progress_timeout_ms"));
assert!(text.contains("commands"));
assert!(text.contains("parallel"));
assert!(text.contains("pipeline"));
assert!(text.contains("max_parallel"));
assert!(text.contains("pipefail"));
}
#[test]
fn retry_policy_is_finite_by_default() {
let retry = RetryPolicy::default();
assert_eq!(retry.max_attempts, 1);
assert!(retry.max_backoff_ms >= retry.backoff_ms);
}
#[test]
fn publishes_the_v2_provider_contract() {
assert_eq!(SCHEMA_VERSION, 4);
let schema = serde_json::to_value(schemars::schema_for!(ProviderConfig)).unwrap();
let text = serde_json::to_string(&schema).unwrap();
assert!(text.contains("mcp_stdio"));
assert!(text.contains("secret_headers"));
assert!(text.contains("secret_env"));
assert!(text.contains("command"));
let capability = CapabilityDescriptor {
provider: "fixture".to_string(),
method: "apply".to_string(),
description: Some("Apply one fixture mutation.".to_string()),
input_schema: serde_json::json!({"type": "object"}),
output_schema: None,
annotations: CapabilityAnnotations {
destructive: Some(true),
..CapabilityAnnotations::default()
},
identity_mode: IdentityMode::Opaque,
coordination_mode: CoordinationMode::Provider,
verification_mode: VerificationMode::Unavailable,
generation: "fixture-generation".to_string(),
};
assert_eq!(capability.coordination_mode, CoordinationMode::Provider);
}
#[test]
fn provider_names_are_javascript_namespace_bindings() {
assert!(valid_provider_name("macos"));
assert!(valid_provider_name("github_v2"));
assert!(valid_provider_name("$host"));
assert!(!valid_provider_name("mac-os"));
assert!(!valid_provider_name("2mac"));
assert!(!valid_provider_name(""));
}
}