Crate car_engine 

Core runtime engine for Common Agent Runtime.

The runtime loop:

1. Receive a proposal (batch of actions from a model)
2. Build a DAG from state_dependencies
3. Execute each level (concurrent if no ABORT actions, sequential otherwise)
4. Validate, execute with idempotency + timeout + retry, commit
5. On abort: rollback state to pre-proposal snapshot

Re-exports

pub use admission::AdmissionDecision;

pub use admission::AdmissionGate;

pub use admission::GateContext;

pub use admission::GateOutcome;

pub use agent_basics::entries as agent_basic_entries;

pub use agent_capability::AgentCapabilityRegistry;

pub use authz::AllowAllPermissions;

pub use authz::AuthzDecision;

pub use authz::AuthzPipeline;

pub use authz::AuthzResult;

pub use authz::AuthzStage;

pub use authz::PermissionHandler;

pub use authz::Restriction;

pub use authz::TierPermissionHandler;

pub use builtin_agents::agent_metadata;

pub use builtin_agents::format_capability_payload;

pub use builtin_agents::register_builtins;

pub use builtin_agents::BuiltinAgent;

pub use builtin_agents::CapabilityPayloadError;

pub use builtin_agents::BUILTIN_AGENTS;

pub use cache::ResultCache;

pub use capabilities::CapabilitySet;

pub use checkpoint::Checkpoint;

pub use flow::builtin_tool_labels;

pub use flow::load_tool_labels;

pub use flow::tool_output_is_external;

pub use flow::FlowLoadError;

pub use flow::InformationFlowGate;

pub use flow::ToolLabelConfig;

pub use flow::NET_SEND;

pub use goal::GoalGather;

pub use mcp::McpServer;

pub use mcp::McpServerConfig;

pub use mcp::McpSession;

pub use mcp::McpToolExecutor;

pub use mcp::McpToolInfo;

pub use messaging::MessageReceipt;

pub use messaging::MessageSink;

pub use messaging::OutboundMessage;

pub use messaging::Recipient;

pub use rate_limit::RateLimit;

pub use rate_limit::RateLimiter;

pub use registry::ToolEntry;

pub use registry::ToolPermission;

pub use registry::ToolRegistry;

pub use registry::ToolSource;

pub use scope::RuntimeScope;

pub use skill_ceiling::SkillCeilingGate;

pub use skill_ceiling::SKILL_CONTEXT_KEY;

pub use subprocess::SubprocessTool;

pub use subprocess::SubprocessToolExecutor;

pub use substrate::CommandOutput;

pub use substrate::LocalSubstrate;

pub use substrate::McpSubstrate;

pub use substrate::PathState;

pub use substrate::Substrate;

pub use substrate::SUBSTRATE_TRANSPORT_ERR_PREFIX;

pub use taint::TaintLedger;

pub use verify_gate::StaticVerificationGate;

pub use voice_turn::dispatch_voice_turn;

pub use voice_turn::dispatch_voice_turn_sidecar_only;

pub use voice_turn::dispatch_voice_turn_sidecar_only_with_classifier;

pub use voice_turn::dispatch_voice_turn_sidecar_only_with_telemetry;

pub use voice_turn::dispatch_voice_turn_with_telemetry;

pub use voice_turn::DirectDataFetcher;

pub use voice_turn::SidecarResult;

pub use voice_turn::VoiceTelemetry;

pub use voice_turn::VoiceTurnControl;

pub use voice_turn::VoiceTurnError;

pub use voice_turn::VoiceTurnHandle;

pub use car_winenv as win_env;

Modules

admission

Proposal-admission gates — the executor’s pre-execution safety seam (EPIC A, task A1).

agent_basics

agent_capability

Agent capability registry — maps capability id → agents that implement it.

authz

Authorization pipeline for tool execution.

builtin_agents

Built-in agent vocabulary — single source of truth across FFI surfaces.

cache

Cross-proposal result cache for tool call results.

capabilities

Per-agent capability permissions for the Common Agent Runtime.

checkpoint

Checkpoint and resume support for the Common Agent Runtime.

flow

Information-flow admission gate + tool-label loading (EPIC A / A3+A4).

goal

Live bridge for the goal loop: project GoalInputs from a Runtime’s ground truth — its event-log receipts, its shared state, its transactional consistency — so car-verify’s pure car_verify::goal::evaluate_goal decides completion against what actually happened, not a transcript read.

intent_gate

VIGIL intent gate — the live in-loop verify-before-commit call-site (arXiv 2601.05755; docs/proposals/intent-grounded-verification.md).

mcp

MCP (Model Context Protocol) server integration.

messaging

Outbound human-directed messaging as a runtime capability.

rate_limit

Token bucket rate limiter for tool calls with backpressure support.

registry

Canonical tool registry — single source of truth for tool identity.

scope

RuntimeScope — per-execution caller identity surface for the multi-tenant work tracked in Parslee-ai/car#187.

skill_ceiling

Skill deployment-tier ceiling enforcement (EPIC A / A8).

spawn

Cross-platform spawning for an external program named by a bare command string — an MCP server’s command, a subprocess tool’s command, a foreman verify command’s program.

subprocess

Subprocess tool executor — runs tools as external processes via stdin/stdout JSON-RPC.

substrate

Execution substrate — the single environment an agent acts within.

taint

Runtime taint provenance — which state keys currently hold a value derived from an untrusted tool result.

tool_handles

Per-runtime registry of detached tool invocations (C2).

verify_gate

Static plan verification as an admission gate.

voice_turn

Two-track voice turn orchestration.

Structs

Action

A single unit of agent intent compiled into IR.

ActionProposal

A batch of actions proposed by a model for runtime validation and execution.

AgentOutcome

The outcome of an agent execution loop.

ApprovalLedger

An append-only ledger of human-in-the-loop decisions, keyed by fingerprint (last decision wins). Optionally persisted as JSONL so the approval state survives restarts — HITL decisions are durable harness state, not transient prompts.

ApprovalRecord

A durable record of a human-in-the-loop decision — the auditable state transition §5.2.5 calls for: what was proposed, who decided, why, and against what evidence.

CostBudget

Budget constraints for proposal execution.

EventLog

Append-only event log with optional JSONL journal.

Evidence

Evidence supporting an outcome classification.

FailedActionSummary

Summary of a failed action, included in ReplanContext.

OutcomeMetrics

Execution metrics associated with an outcome.

PermissionGate

The permission gate: a session’s standing authority plus the classifier and the durable approval ledger. Pure and synchronous so it can be embedded anywhere; the engine wraps it for its async pipeline.

Planner

Proposal scorer and ranker.

PlannerConfig

Configuration for proposal scoring.

PolicyEngine

Evaluates actions against registered policies.

ProposalResult

The complete result of processing a proposal through the runtime.

ReplanConfig

Configuration for the replan loop.

ReplanContext

Context provided to the replan callback so the model can generate an alternative.

RiskClassifier

Classifies an Action into the minimum PermissionTier required to perform it. Combines a built-in heuristic with optional custom rules; the result is the highest tier any signal implies, since risk is monotonic (one high-risk signal escalates the whole action).

Runtime

Common Agent Runtime — deterministic execution layer.

StateStore

Thread-safe state store with transition logging.

ToolExecution

Result of a tool dispatch before the Runtime commits observed state.

ToolFeedback

Historical tool success rates computed from the trajectory store. Pass to rank_with_feedback() to bias scoring based on past outcomes.

ToolSchema

Rich schema describing a tool’s interface and runtime configuration.

VerifyIssue

A single verification finding.

Enums

ActionType

What kind of action this is.

ApprovalDecision

Whether a recorded human decision approved or rejected an operation.

EventKind

Event kinds matching the Python EventKind enum.

EvidenceKind

Types of evidence that can support an outcome.

FailureBehavior

What to do when an action fails.

GateDecision

The outcome of evaluating an action against the gate.

OutcomeStatus

Outcome classification for an agent execution.

PermissionTier

Permission tiers — who may authorize this action? — ordered by the authority an action demands (survey §3.4.3). The Ord derive makes ReadOnly < SandboxEdit < FullAccess, so “does the granted tier cover the required tier?” is a single >=.

SpanStatus

Status of a trace span.

TransactionCheckMode

How the runtime treats a proposal that conflicts with the current shared state on a pre-execution transactional check (survey §4.3/§5.2.4 — car_verify::check_transaction against the versioned StateStore).

Constants

CANCELED_PREFIX

Prefix on the error field of an ActionResult that distinguishes “the user pulled the plug” from “earlier abort cascaded.” The ActionStatus itself is Skipped in both cases (introducing a new variant ripples through every IR consumer + FFI binding); the prefix lets callers like the A2A bridge tell the cases apart without string-matching a magic literal.

Traits

ReplanCallback

Callback trait for replanning failed proposals. Implement this to let the runtime ask the model for an alternative plan when a proposal aborts.

ToolExecutor

Trait for tool execution. Implement this to provide tools to the runtime.

Functions

format_tool_result

Format a tool result for feeding back to a model.

validate_proposal_action_ids

Validate the proposal-local action identity boundary used by DAG execution, action receipts, results, and state-transition attribution. A retry reuses one admitted action id across attempts; two declared actions may not share an id because every downstream join would become ambiguous.

validate_tool_output

Validate a tool result against its declared return schema.

Type Aliases

PolicyCheck

Policy check function: (action, state) -> Option<violation_reason>