use std::collections::BTreeMap;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
pub const SCHEMA_VERSION: u32 = 8;
pub const DEFAULT_TELEMETRY_INTERVAL_MS: u64 = 250;
pub const DEFAULT_TELEMETRY_MAX_BYTES: u64 = 64 * 1024 * 1024;
#[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>,
#[serde(default)]
pub expect: Option<PollCondition>,
}
#[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,
},
Poll {
target: PollTarget,
schedule: PollSchedule,
#[serde(default)]
condition: Option<PollCondition>,
#[serde(default)]
max_iterations: Option<u64>,
#[serde(default)]
duration_ms: Option<u64>,
#[serde(default)]
iteration_timeout_ms: Option<u64>,
},
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum PollTarget {
Command {
argv: Vec<String>,
#[serde(default)]
shell: bool,
},
ApocCall {
method: String,
#[serde(default)]
arguments: serde_json::Value,
},
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum PollSchedule {
FixedDelay {
interval_ms: u64,
},
Backoff {
initial_interval_ms: u64,
multiplier: f64,
max_interval_ms: u64,
},
FixedRate {
interval_ms: u64,
},
}
impl Default for PollSchedule {
fn default() -> Self {
Self::FixedDelay { interval_ms: 1000 }
}
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum PollCondition {
ExitCode {
codes: Vec<i32>,
},
StdoutRegex {
pattern: String,
},
StderrRegex {
pattern: String,
},
JsonEquals {
pointer: String,
value: serde_json::Value,
},
Javascript {
expression: String,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum PollIterationStatus {
Accepted,
Running,
Observed,
Canceled,
Failed,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct PollIteration {
pub id: String,
pub poll_id: String,
pub number: u64,
pub status: PollIterationStatus,
pub started_at: u64,
pub completed_at: Option<u64>,
pub execution_id: Option<String>,
pub payload_id: Option<String>,
pub observation: Option<serde_json::Value>,
pub matched: bool,
#[serde(default)]
pub evaluated: bool,
pub error_code: Option<String>,
pub error: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct PollIterationSummary {
pub id: String,
pub poll_id: String,
pub number: u64,
pub status: PollIterationStatus,
pub started_at: u64,
pub completed_at: Option<u64>,
pub execution_id: Option<String>,
pub payload_id: Option<String>,
pub matched: bool,
pub error_code: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct PollIterationPage {
pub iterations: Vec<PollIterationSummary>,
pub next_cursor: Option<String>,
}
#[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>,
#[serde(default)]
pub memory_bytes: Option<u64>,
#[serde(default)]
pub cpu_percent: Option<f32>,
#[serde(default)]
pub cpu_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, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "mode", rename_all = "snake_case")]
pub enum TelemetryPolicy {
#[default]
Off,
Sample {
interval_ms: u64,
max_bytes: u64,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum TelemetryCaptureStatus {
Active,
Stopped,
Completed,
Degraded,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TelemetryCapture {
pub schema_version: u32,
pub id: String,
pub execution_id: String,
pub interval_ms: u64,
pub max_bytes: u64,
pub status: TelemetryCaptureStatus,
pub started_at: u64,
pub stopped_at: Option<u64>,
pub next_sequence: u64,
pub sample_count: u64,
pub retained_bytes: u64,
pub dropped_samples: u64,
pub error: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TelemetryProcessSample {
pub identity: ProcessIdentity,
pub cpu_percent: f32,
pub cpu_time_ms: u64,
pub memory_bytes: u64,
pub virtual_memory_bytes: u64,
pub disk_read_bytes: u64,
pub disk_written_bytes: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TelemetrySample {
pub sequence: u64,
pub sampled_at: u64,
pub wall_time_ms: u64,
pub process_count: u64,
pub cpu_percent: f32,
pub cpu_time_ms: u64,
pub memory_bytes: u64,
pub virtual_memory_bytes: u64,
pub disk_read_bytes: u64,
pub disk_written_bytes: u64,
pub processes: Vec<TelemetryProcessSample>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TelemetrySummary {
pub capture: TelemetryCapture,
pub latest: Option<TelemetrySummarySample>,
pub peak_cpu_percent: Option<f32>,
pub peak_memory_bytes: Option<u64>,
pub peak_process_count: Option<u64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TelemetrySummarySample {
pub sequence: u64,
pub sampled_at: u64,
pub wall_time_ms: u64,
pub process_count: u64,
pub cpu_percent: f32,
pub cpu_time_ms: u64,
pub memory_bytes: u64,
pub virtual_memory_bytes: u64,
pub disk_read_bytes: u64,
pub disk_written_bytes: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TelemetryLine {
pub sequence: u64,
pub text: String,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TelemetrySlice {
pub capture_id: String,
pub total_lines: u64,
pub total_matches: u64,
pub lines: Vec<TelemetryLine>,
pub truncated: 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 backend: ExecutionBackendSpec,
#[serde(default)]
pub workspace: WorkspaceContext,
#[serde(default)]
pub env: BTreeMap<String, String>,
#[serde(default)]
pub secrets: BTreeMap<String, SecretRef>,
#[serde(default)]
pub profile_selection: Option<ProfileSelection>,
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,
#[serde(default)]
pub telemetry: TelemetryPolicy,
#[serde(default)]
pub expect: Option<PollCondition>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ExecutionBackendSpec {
#[default]
Native,
Isolated {
isolation: IsolatedExecutionSpec,
},
Provider {
name: String,
generation: String,
#[serde(default)]
options: serde_json::Value,
},
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct IsolatedExecutionSpec {
pub image: String,
#[serde(default)]
pub workspace: IsolatedWorkspaceMode,
#[serde(default)]
pub guest_cwd: Option<String>,
#[serde(default)]
pub memory_mb: Option<u64>,
#[serde(default)]
pub cpu_count: Option<u32>,
#[serde(default)]
pub pids_max: Option<u32>,
#[serde(default)]
pub network: IsolatedNetworkPolicy,
#[serde(default)]
pub exports: Vec<ExecutionExportSpec>,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum IsolatedWorkspaceMode {
None,
#[default]
ReadWrite,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum IsolatedNetworkPolicy {
#[default]
None,
Nat,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionExportSpec {
pub source: String,
pub destination: String,
#[serde(default)]
pub when: ExecutionExportWhen,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecutionExportWhen {
#[default]
Success,
Failure,
Always,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionArtifactRef {
pub name: String,
pub source: String,
pub id: String,
pub bytes: u64,
pub guest_sha256: String,
pub media_type: String,
}
#[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 ProfileSelectionSource {
Explicit,
Workspace,
UserDefault,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProfileSelection {
pub name: String,
pub generation: String,
pub source: ProfileSelectionSource,
#[serde(default)]
pub matched_root: Option<String>,
#[serde(default)]
pub variables: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProfileEntry {
pub name: String,
pub kind: String,
pub resolvable: bool,
#[serde(default)]
pub error_code: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProfileView {
pub name: String,
pub generation: String,
pub is_default: bool,
#[serde(default)]
pub roots: Vec<String>,
#[serde(default)]
pub entries: Vec<ProfileEntry>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProfileResolution {
#[serde(default)]
pub cwd: Option<String>,
#[serde(default)]
pub selection: Option<ProfileSelection>,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ProfileMode {
#[default]
None,
Optional,
Required,
}
#[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>,
}
pub const RESULT_SKIPPED: &str = "skipped";
pub const RESULT_EXIT_CODE: &str = "exit_code";
pub const RESULT_COUNTS: &str = "counts";
pub const RESULT_EXPECTATION_MET: &str = "expectation_met";
pub const RESULT_EXPECTATION_ERROR: &str = "expectation_error";
pub const RESULT_DISPLACED: &str = "result";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ExpectationState {
NotDeclared,
Met,
Unmet,
Unevaluated,
}
impl Execution {
pub fn recorded_error_code(&self) -> Option<&str> {
self.attempts
.last()
.and_then(|attempt| attempt.error_code.as_deref())
.or_else(|| {
self.passes
.last()
.and_then(|pass| pass.error_code.as_deref())
})
.or_else(|| {
self.result
.as_ref()
.and_then(|result| result.get("error_code"))
.and_then(serde_json::Value::as_str)
})
}
fn result_key(&self, key: &str) -> Option<&serde_json::Value> {
self.result.as_ref().and_then(|result| result.get(key))
}
pub fn skipped(&self) -> bool {
self.result_key(RESULT_SKIPPED)
.and_then(serde_json::Value::as_bool)
.unwrap_or(false)
}
pub fn exit_code(&self) -> Option<i32> {
self.result_key(RESULT_EXIT_CODE)
.and_then(serde_json::Value::as_i64)
.and_then(|code| i32::try_from(code).ok())
.or_else(|| self.attempts.last().and_then(|attempt| attempt.exit_code))
}
pub fn reached_verdict(&self) -> bool {
self.exit_code().is_some() || self.result_key(RESULT_COUNTS).is_some()
}
pub fn expectation(&self) -> ExpectationState {
if self.spec.expect.is_none() {
return ExpectationState::NotDeclared;
}
match self
.result_key(RESULT_EXPECTATION_MET)
.and_then(serde_json::Value::as_bool)
{
Some(true) => ExpectationState::Met,
Some(false) => ExpectationState::Unmet,
None => ExpectationState::Unevaluated,
}
}
pub fn record_expectation(&mut self, met: bool, error: Option<String>) {
let mut result = match self.result.take() {
Some(serde_json::Value::Object(map)) => map,
Some(other) => {
let mut map = serde_json::Map::new();
map.insert(RESULT_DISPLACED.to_string(), other);
map
}
None => serde_json::Map::new(),
};
result.insert(
RESULT_EXPECTATION_MET.to_string(),
serde_json::Value::Bool(met),
);
if let Some(error) = error {
result.insert(
RESULT_EXPECTATION_ERROR.to_string(),
serde_json::Value::String(error),
);
}
self.result = Some(serde_json::Value::Object(result));
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecutionTreeState {
Pending,
Active,
Terminal,
Inconsistent,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionTreeRoot {
pub execution_id: String,
pub attempt_id: String,
pub identity: ProcessIdentity,
pub live: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionTree {
pub execution_id: String,
pub status: ExecutionStatus,
pub state: ExecutionTreeState,
pub observed_at: u64,
pub roots: Vec<ExecutionTreeRoot>,
pub processes: Vec<ProcessInfo>,
}
#[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,
}
pub const VERBOSITY_ENV: &str = "APOC_VERBOSITY";
pub const RESPONSE_VIEW_ENV: &str = "APOC_VIEW";
#[derive(
Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "snake_case")]
pub enum Verbosity {
Off,
Error,
Warn,
Info,
Debug,
Trace,
}
impl Verbosity {
pub const DEFAULT: Self = Self::Error;
pub fn as_str(self) -> &'static str {
match self {
Self::Off => "off",
Self::Error => "error",
Self::Warn => "warn",
Self::Info => "info",
Self::Debug => "debug",
Self::Trace => "trace",
}
}
pub fn parse(value: &str) -> Result<Self, String> {
match value.trim() {
"off" | "silent" | "none" => Ok(Self::Off),
"error" => Ok(Self::Error),
"warn" | "warning" => Ok(Self::Warn),
"info" => Ok(Self::Info),
"debug" => Ok(Self::Debug),
"trace" => Ok(Self::Trace),
value => Err(format!(
"Unknown verbosity \"{value}\". Use off, error, warn, info, debug, or trace."
)),
}
}
pub fn parse_view(value: &str) -> Result<Self, String> {
match value.trim() {
"outcome" => Ok(Self::DEFAULT),
"full" => Ok(Self::Trace),
value => Err(format!("Unknown view \"{value}\". Use full or outcome.")),
}
}
pub fn shift(self, steps: i32) -> Self {
const STEPS: [Verbosity; 5] = [
Verbosity::Off,
Verbosity::Error,
Verbosity::Info,
Verbosity::Debug,
Verbosity::Trace,
];
if steps == 0 {
return self;
}
let current = STEPS.iter().position(|level| *level == self).unwrap_or(1) as i32;
let index = (current + steps).clamp(0, STEPS.len() as i32 - 1) as usize;
STEPS[index]
}
pub fn from_env() -> Option<Result<Self, String>> {
if let Ok(value) = std::env::var(VERBOSITY_ENV)
&& !value.trim().is_empty()
{
return Some(Self::parse(&value));
}
if let Ok(value) = std::env::var(RESPONSE_VIEW_ENV)
&& !value.trim().is_empty()
{
return Some(Self::parse_view(&value));
}
None
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecutionVerdict {
Passed,
Failed,
Error,
Skipped,
Pending,
}
impl ExecutionVerdict {
pub fn of_execution(execution: &Execution) -> Self {
if execution.skipped() {
return Self::Skipped;
}
match execution.status {
ExecutionStatus::Completed => match (execution.expectation(), execution.exit_code()) {
(ExpectationState::Unevaluated, _) => Self::Error,
(ExpectationState::Unmet, _) => Self::Failed,
(ExpectationState::Met, _) => Self::Passed,
(ExpectationState::NotDeclared, Some(0) | None) => Self::Passed,
(ExpectationState::NotDeclared, Some(_)) => Self::Failed,
},
ExecutionStatus::Failed if execution.reached_verdict() => {
match execution.expectation() {
ExpectationState::Unevaluated => Self::Error,
ExpectationState::Met => Self::Passed,
ExpectationState::Unmet | ExpectationState::NotDeclared => Self::Failed,
}
}
ExecutionStatus::Failed | ExecutionStatus::Canceled | ExecutionStatus::Stalled => {
Self::Error
}
ExecutionStatus::Queued | ExecutionStatus::Running | ExecutionStatus::Interrupted => {
Self::Pending
}
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionOutcome {
pub id: String,
pub outcome: ExecutionVerdict,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub status: Option<ExecutionStatus>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub exit_code: Option<i32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error_code: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub replayed: Option<bool>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stdout_bytes: Option<usize>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stderr_bytes: Option<usize>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub truncated: Option<bool>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub inspect: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub logs: Option<crate::run::RunLogs>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ExecutionListPage {
pub executions: Vec<ExecutionSummary>,
pub next_cursor: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum InvocationSource {
Native,
Devsql,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum InvocationSurface {
Cli,
Mcp,
Code,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum InvocationStatus {
Running,
Succeeded,
Failed,
Incomplete,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum InvocationScopeKind {
GitWorktree,
Cwd,
Unknown,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct InvocationRecord {
pub id: String,
pub parent_id: Option<String>,
pub execution_id: Option<String>,
pub source: InvocationSource,
pub source_id: Option<String>,
pub source_order: Option<i64>,
pub source_path: Option<String>,
#[serde(default)]
pub accepted_sequence: u64,
pub surface: InvocationSurface,
pub actor: Option<String>,
pub agent: bool,
pub command_path: String,
#[serde(default)]
pub purpose: Option<String>,
#[serde(default)]
pub normalized_input: serde_json::Value,
pub search_text: String,
#[serde(default)]
pub pattern_signature: String,
#[serde(default)]
pub variable_paths: Vec<String>,
pub cwd: Option<String>,
pub scope_kind: InvocationScopeKind,
pub scope_key: Option<String>,
#[serde(default)]
pub recording_id: Option<String>,
#[serde(default)]
pub recording_take: Option<u32>,
pub started_at: u64,
pub completed_at: Option<u64>,
pub updated_at: u64,
pub status: InvocationStatus,
pub exit_code: Option<i32>,
pub error_code: Option<String>,
pub error: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct InvocationTimelinePage {
pub invocations: Vec<InvocationRecord>,
pub next_cursor: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct InvocationSummary {
pub id: String,
pub parent_id: Option<String>,
pub execution_id: Option<String>,
pub source: InvocationSource,
pub surface: InvocationSurface,
pub actor: Option<String>,
pub agent: bool,
pub command_path: String,
pub purpose: Option<String>,
pub cwd: Option<String>,
pub scope_kind: InvocationScopeKind,
pub scope_key: Option<String>,
pub started_at: u64,
pub completed_at: Option<u64>,
pub updated_at: u64,
pub status: InvocationStatus,
pub exit_code: Option<i32>,
pub error_code: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct InvocationPage {
pub invocations: Vec<InvocationSummary>,
pub next_cursor: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct HistoryQueryOutput {
pub columns: Vec<String>,
pub rows: Vec<Vec<serde_json::Value>>,
pub truncated: bool,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct InvocationQuery {
pub limit: usize,
pub cursor: Option<String>,
pub exclude_id: Option<String>,
pub search: Option<String>,
pub scope_kind: Option<InvocationScopeKind>,
pub scope_key: Option<String>,
pub source: Option<InvocationSource>,
pub surface: Option<InvocationSurface>,
pub command_path: Option<String>,
pub status: Option<InvocationStatus>,
pub error_code: Option<String>,
pub actor: Option<String>,
pub execution_id: Option<String>,
pub since_ms: Option<u64>,
pub until_ms: Option<u64>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct InvocationPatternQuery {
pub min_count: usize,
pub limit: usize,
pub exclude_id: Option<String>,
pub scope_kind: Option<InvocationScopeKind>,
pub scope_key: Option<String>,
pub source: Option<InvocationSource>,
pub command_path: Option<String>,
pub since_ms: Option<u64>,
pub until_ms: Option<u64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct InvocationPattern {
pub signature: String,
pub command_path: String,
pub occurrences: usize,
pub succeeded: usize,
pub failed: usize,
pub incomplete: usize,
pub first_seen: u64,
pub last_seen: u64,
pub variable_paths: Vec<String>,
pub sample_invocation_ids: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct HistoryPatternOutput {
pub patterns: Vec<InvocationPattern>,
pub scanned: usize,
pub truncated: bool,
}
#[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,
#[serde(default)]
pub closing: bool,
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, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct IsolationBootDiagnostics {
pub strategy: String,
pub boot_ms: Option<u64>,
pub warmup_ms: Option<u64>,
pub reconnect_ms: Option<u64>,
pub total_ms: u64,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct IsolationPoolStatus {
pub idle: u64,
pub waiters: u64,
pub in_flight: u64,
pub live: u64,
pub checked_out: u64,
pub target: u64,
pub per_vm_memory_mb: u64,
pub max_pool_memory_mb: u64,
pub draining: bool,
pub shutting_down: bool,
pub last_boot: Option<IsolationBootDiagnostics>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct IsolationStatus {
pub provider_version: String,
pub initialized: bool,
pub configured_image_path: Option<String>,
pub image_path: Option<String>,
pub image_digest: Option<String>,
pub cpu_count: Option<u64>,
pub memory_mb: Option<u64>,
pub snapshot_restore_enabled: Option<bool>,
pub snapshot_available: Option<bool>,
pub idle_drain_seconds: Option<f64>,
pub pool: Option<IsolationPoolStatus>,
pub drained: Option<bool>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct IsolationMutationResponse {
pub receipt: OperationReceipt,
pub status: Option<IsolationStatus>,
pub replayed: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ImageImportResponse {
pub receipt: OperationReceipt,
pub source_bundle: String,
pub target_bundle: Option<String>,
pub image_digest: Option<String>,
pub files: u64,
pub bytes: u64,
pub already_present: bool,
pub replayed: bool,
}
#[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,
#[serde(default)]
pub cpu_time_ms: u64,
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>,
#[serde(default)]
pub verbosity: Option<String>,
#[serde(default)]
pub profile_selection: Option<ProfileSelection>,
#[serde(default)]
pub hook_depth: u32,
#[serde(default, skip_serializing_if = "is_zero")]
pub decider_depth: u32,
}
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,
verbosity: Verbosity::from_env()
.and_then(Result::ok)
.map(|level| level.as_str().to_string()),
profile_selection: None,
hook_depth: 0,
decider_depth: 0,
}
}
}
#[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(crate) enum RunLifetime {
Execution,
Persistent,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub(crate) enum RestartPolicy {
Never,
OnFailure,
Always,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub(crate) 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>,
#[serde(skip, default)]
#[schemars(skip)]
pub resolved_env: std::collections::BTreeMap<String, String>,
#[serde(default)]
pub suppressed_env: Vec<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(crate) 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 Recipe {
pub name: String,
pub description: String,
pub code: String,
#[serde(default)]
pub input_schema: Option<serde_json::Value>,
#[serde(default)]
pub output_schema: Option<serde_json::Value>,
#[serde(default)]
pub dependencies: Vec<String>,
#[serde(default)]
pub required_env: Vec<String>,
#[serde(default)]
pub annotations: RecipeAnnotations,
#[serde(default = "default_recipe_scope_kind")]
pub scope_kind: RecipeScopeKind,
#[serde(default)]
pub scope_key: Option<String>,
#[serde(default)]
pub generation: String,
#[serde(default)]
pub expires_at: Option<u64>,
#[serde(default)]
pub last_used_at: Option<u64>,
pub created_at: u64,
pub updated_at: u64,
#[serde(default)]
pub origin_suggestion_id: Option<String>,
#[serde(default)]
pub origin_recording_id: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum RecipeScopeKind {
Global,
GitWorktree,
Cwd,
}
fn default_recipe_scope_kind() -> RecipeScopeKind {
RecipeScopeKind::Global
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct RecipeAnnotations {
#[serde(default)]
pub read_only: Option<bool>,
#[serde(default)]
pub destructive: Option<bool>,
#[serde(default)]
pub idempotent: Option<bool>,
#[serde(default)]
pub open_world: Option<bool>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecipePortableDefinition {
pub name: String,
pub description: String,
pub code: String,
#[serde(default)]
pub input_schema: Option<serde_json::Value>,
#[serde(default)]
pub output_schema: Option<serde_json::Value>,
#[serde(default)]
pub dependencies: Vec<String>,
#[serde(default)]
pub required_env: Vec<String>,
#[serde(default)]
pub annotations: RecipeAnnotations,
pub generation: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum RecipeSuggestionStatus {
Pending,
Adopted,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecipeEvidenceRange {
pub start_id: String,
pub end_id: String,
pub invocation_ids: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecipeSuggestion {
pub id: String,
pub candidate: RecipePortableDefinition,
pub positive_evidence: Vec<RecipeEvidenceRange>,
#[serde(default)]
pub counterexamples: Vec<RecipeEvidenceRange>,
pub rationale: String,
pub scope_kind: RecipeScopeKind,
pub scope_key: Option<String>,
pub status: RecipeSuggestionStatus,
pub adopted_generation: Option<String>,
pub created_at: u64,
pub adopted_at: Option<u64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecipeBundleV1 {
pub schema_version: u32,
pub namespace: String,
pub recipes: Vec<RecipePortableDefinition>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum RecordingStatus {
Active,
Stopped,
Discarded,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecordingParam {
pub name: String,
pub value: serde_json::Value,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecordingTake {
pub index: u32,
pub started_at: u64,
pub stopped_at: Option<u64>,
#[serde(default)]
pub params: Vec<RecordingParam>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecordingStep {
pub invocation_id: String,
pub take: u32,
pub command_path: String,
pub method: String,
pub input: serde_json::Value,
pub pattern_signature: String,
#[serde(default)]
pub variable_paths: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Recording {
pub id: String,
pub name: String,
pub status: RecordingStatus,
pub scope_kind: RecipeScopeKind,
pub scope_key: Option<String>,
pub takes: Vec<RecordingTake>,
#[serde(default)]
pub literal_paths: Vec<String>,
#[serde(default)]
pub skipped: Vec<String>,
#[serde(default)]
pub evidence: Vec<RecipeEvidenceRange>,
#[serde(default)]
pub recipe_generation: Option<String>,
#[serde(default)]
pub suggestion_id: Option<String>,
pub created_at: u64,
pub updated_at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecordingDetail {
pub recording: Recording,
pub steps: Vec<RecordingStep>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RecordingStopOutput {
pub recording: Recording,
pub recipe: Option<Recipe>,
pub suggestion: Option<RecipeSuggestion>,
}
#[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 profile_mode: ProfileMode,
#[serde(default)]
pub profile_env: BTreeMap<String, String>,
#[serde(default)]
pub profile_headers: BTreeMap<String, String>,
#[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
}
fn is_zero(value: &u32) -> bool {
*value == 0
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn publishes_the_v8_execution_contract() {
assert_eq!(SCHEMA_VERSION, 8);
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("memory_bytes"));
assert!(text.contains("cpu_percent"));
assert!(text.contains("cpu_time_ms"));
assert!(text.contains("commands"));
assert!(text.contains("parallel"));
assert!(text.contains("pipeline"));
assert!(text.contains("max_parallel"));
assert!(text.contains("pipefail"));
assert!(text.contains("profile_selection"));
assert!(!text.contains("environment_generations"));
assert!(text.contains("backend"));
assert!(text.contains("isolated"));
assert!(text.contains("image"));
assert!(text.contains("workspace"));
assert!(text.contains("guest_cwd"));
assert!(text.contains("memory_mb"));
assert!(text.contains("cpu_count"));
assert!(text.contains("pids_max"));
assert!(text.contains("network"));
assert!(text.contains("exports"));
assert!(text.contains("telemetry"));
assert!(text.contains("sample"));
}
#[test]
fn preserves_a_provider_backend_in_the_execution_contract() {
let mut value = serde_json::to_value(asserted(None, None).spec).unwrap();
value["backend"] = serde_json::json!({
"kind": "provider",
"name": "exeggutor",
"generation": "sha256:provider-v1",
"options": { "image": "local" }
});
let spec = serde_json::from_value::<ExecutionSpec>(value).unwrap();
let encoded = serde_json::to_value(spec).unwrap();
assert_eq!(
encoded.pointer("/backend/kind"),
Some(&serde_json::json!("provider"))
);
assert_eq!(
encoded.pointer("/backend/name"),
Some(&serde_json::json!("exeggutor"))
);
assert_eq!(
encoded.pointer("/backend/generation"),
Some(&serde_json::json!("sha256:provider-v1"))
);
assert_eq!(
encoded.pointer("/backend/options/image"),
Some(&serde_json::json!("local"))
);
}
#[test]
fn preserves_an_isolated_backend_in_the_execution_contract() {
let mut value = serde_json::to_value(asserted(None, None).spec).unwrap();
value["backend"] = serde_json::json!({
"kind": "isolated",
"isolation": {
"image": "local",
"workspace": "read_write",
"guest_cwd": "/workspace/src",
"memory_mb": 2048,
"cpu_count": 4,
"pids_max": 256,
"network": "none",
"exports": []
}
});
let spec = serde_json::from_value::<ExecutionSpec>(value).unwrap();
let encoded = serde_json::to_value(spec).unwrap();
assert_eq!(
encoded.pointer("/backend/kind"),
Some(&serde_json::json!("isolated"))
);
assert_eq!(
encoded.pointer("/backend/isolation/guest_cwd"),
Some(&serde_json::json!("/workspace/src"))
);
assert_eq!(
encoded.pointer("/backend/isolation/memory_mb"),
Some(&serde_json::json!(2048))
);
}
fn asserted(expect: Option<PollCondition>, result: Option<serde_json::Value>) -> Execution {
Execution {
id: "execution".to_string(),
parent_id: None,
session_id: None,
spec: ExecutionSpec {
schema_version: SCHEMA_VERSION,
idempotency_key: None,
name: "assertion".to_string(),
purpose: Some("Judging a declared expectation.".to_string()),
labels: BTreeMap::new(),
program: ExecutionProgram::Command {
argv: vec!["/bin/echo".to_string()],
shell: false,
},
backend: ExecutionBackendSpec::default(),
workspace: WorkspaceContext::default(),
env: BTreeMap::new(),
secrets: BTreeMap::new(),
profile_selection: None,
io: IoMode::Pipes,
owner_kind: LeaseOwnerKind::Execution,
owner_id: None,
expires_at: None,
retry: RetryPolicy::default(),
budget: ExecutionBudget::default(),
telemetry: TelemetryPolicy::default(),
expect,
},
status: ExecutionStatus::Completed,
passes: Vec::new(),
attempts: Vec::new(),
created_at: 0,
updated_at: 0,
last_progress_at: 0,
result,
}
}
fn stdout_regex() -> Option<PollCondition> {
Some(PollCondition::StdoutRegex {
pattern: "ready".to_string(),
})
}
#[test]
fn an_unevaluated_expectation_is_a_fault_rather_than_a_pass() {
let unevaluated = asserted(stdout_regex(), Some(serde_json::json!({"exit_code": 0})));
assert_eq!(unevaluated.expectation(), ExpectationState::Unevaluated);
assert_eq!(
ExecutionVerdict::of_execution(&unevaluated),
ExecutionVerdict::Error
);
let undeclared = asserted(None, Some(serde_json::json!({"exit_code": 0})));
assert_eq!(undeclared.expectation(), ExpectationState::NotDeclared);
assert_eq!(
ExecutionVerdict::of_execution(&undeclared),
ExecutionVerdict::Passed
);
}
#[test]
fn recording_a_judgment_never_silently_does_nothing() {
for result in [
None,
Some(serde_json::Value::Null),
Some(serde_json::json!("opaque")),
Some(serde_json::json!({"exit_code": 0})),
] {
let mut execution = asserted(stdout_regex(), result.clone());
execution.record_expectation(false, Some("regex failed".to_string()));
assert_eq!(
execution.expectation(),
ExpectationState::Unmet,
"{result:?} lost its judgment"
);
assert_eq!(
ExecutionVerdict::of_execution(&execution),
ExecutionVerdict::Failed
);
}
let mut opaque = asserted(stdout_regex(), Some(serde_json::json!("opaque")));
opaque.record_expectation(true, None);
assert_eq!(opaque.result.as_ref().unwrap()[RESULT_DISPLACED], "opaque");
assert_eq!(
ExecutionVerdict::of_execution(&opaque),
ExecutionVerdict::Passed
);
}
#[test]
fn a_skipped_command_outranks_every_other_signal() {
let mut skipped = asserted(stdout_regex(), Some(serde_json::json!({"skipped": true})));
assert_eq!(
ExecutionVerdict::of_execution(&skipped),
ExecutionVerdict::Skipped
);
skipped.status = ExecutionStatus::Failed;
assert_eq!(
ExecutionVerdict::of_execution(&skipped),
ExecutionVerdict::Skipped,
"a command that never launched cannot have failed its assertion"
);
}
#[test]
fn a_command_group_that_counted_its_children_reached_a_verdict() {
let mut group = asserted(None, Some(serde_json::json!({"counts": {"failed": 1}})));
group.status = ExecutionStatus::Failed;
assert_eq!(
ExecutionVerdict::of_execution(&group),
ExecutionVerdict::Failed
);
let mut broken = asserted(
None,
Some(serde_json::json!({"error_code": "EXECUTION_CLEANUP_FAILED"})),
);
broken.status = ExecutionStatus::Failed;
assert_eq!(
ExecutionVerdict::of_execution(&broken),
ExecutionVerdict::Error
);
}
#[test]
fn a_deprecated_view_keeps_the_contract_it_named() {
assert_eq!(
Verbosity::parse_view("outcome").unwrap(),
Verbosity::DEFAULT
);
assert_eq!(Verbosity::parse_view("full").unwrap(), Verbosity::Trace);
}
#[test]
fn defaults_and_verbosity_cover_every_public_value() {
assert_eq!(
serde_json::to_value(PollSchedule::default()).unwrap(),
serde_json::json!({ "kind": "fixed_delay", "interval_ms": 1000 })
);
for (level, name) in [
(Verbosity::Off, "off"),
(Verbosity::Error, "error"),
(Verbosity::Warn, "warn"),
(Verbosity::Info, "info"),
(Verbosity::Debug, "debug"),
(Verbosity::Trace, "trace"),
] {
assert_eq!(level.as_str(), name);
}
assert_eq!(Verbosity::parse(" silent ").unwrap(), Verbosity::Off);
assert!(Verbosity::parse("verbose").unwrap_err().contains("verbose"));
assert!(
Verbosity::parse_view("debug")
.unwrap_err()
.contains("debug")
);
assert_eq!(Verbosity::Info.shift(0), Verbosity::Info);
assert_eq!(Verbosity::Off.shift(-10), Verbosity::Off);
assert_eq!(Verbosity::Trace.shift(10), Verbosity::Trace);
assert_eq!(Verbosity::Warn.shift(1), Verbosity::Info);
assert_eq!(Verbosity::Debug.shift(-2), Verbosity::Error);
let legacy: RunSpec = serde_json::from_value(serde_json::json!({
"name": "legacy",
"argv": ["true"],
"cwd": null,
"env": {},
"shell": false,
"io": "pipes",
"lifetime": "persistent",
"restart": "never",
"timeout_ms": null,
"replicas": 1
}))
.unwrap();
assert_eq!(legacy.max_attempts, 1);
assert_eq!(legacy.retry_backoff_ms, 500);
assert_eq!(legacy.retry_max_backoff_ms, 30_000);
}
#[test]
fn a_completed_nonzero_command_is_a_failed_verdict() {
let execution = asserted(None, Some(serde_json::json!({"exit_code": 9})));
assert_eq!(
ExecutionVerdict::of_execution(&execution),
ExecutionVerdict::Failed
);
}
#[test]
fn a_declared_nonzero_exit_can_pass_its_expectation() {
let mut execution = asserted(
Some(PollCondition::ExitCode { codes: vec![1] }),
Some(serde_json::json!({"exit_code": 1})),
);
execution.record_expectation(true, None);
assert_eq!(execution.expectation(), ExpectationState::Met);
assert_eq!(
ExecutionVerdict::of_execution(&execution),
ExecutionVerdict::Passed
);
}
#[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_v3_provider_contract() {
assert_eq!(SCHEMA_VERSION, 8);
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"));
assert!(text.contains("profile_mode"));
assert!(text.contains("profile_headers"));
assert!(text.contains("profile_env"));
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(""));
}
}