car_engine/
lib.rs

1#![recursion_limit = "256"]
2
3//! Core runtime engine for Common Agent Runtime.
4//!
5//! The runtime loop:
6//! 1. Receive a proposal (batch of actions from a model)
7//! 2. Build a DAG from state_dependencies
8//! 3. Execute each level (concurrent if no ABORT actions, sequential otherwise)
9//! 4. Validate, execute with idempotency + timeout + retry, commit
10//! 5. On abort: rollback state to pre-proposal snapshot
11
12/// How long a test waits for something it does not control to happen: a
13/// spawned process, a supervised agent, a file another task writes. The wait
14/// ends as soon as the thing happens, so this costs nothing when the test
15/// passes; it exists only to end a real hang. A full-suite run on a loaded
16/// operator Mac has stretched a supervised agent's start past 10 s (car#3744),
17/// and every shorter bound was a test of the machine's load as well as of the
18/// behaviour it names (car#3763). `scripts/check-test-wait-bounds.sh` holds
19/// test waits to it.
20#[cfg(test)]
21pub(crate) const LOADED_WAIT: std::time::Duration = std::time::Duration::from_secs(60);
22
23pub mod admission;
24pub mod agent_basics;
25pub mod agent_capability;
26pub mod authz;
27pub mod builtin_agents;
28pub mod cache;
29pub mod capabilities;
30pub mod checkpoint;
31mod executor;
32pub mod flow;
33pub mod goal;
34pub mod intent_gate;
35pub mod mcp;
36pub mod messaging;
37pub mod rate_limit;
38pub mod registry;
39pub mod scope;
40pub mod skill_ceiling;
41pub mod spawn;
42pub mod subprocess;
43pub mod substrate;
44pub mod taint;
45pub mod tool_handles;
46pub mod verify_gate;
47pub mod voice_turn;
48/// Windows `cmd.exe` over-long-`PATH` repair. Lives in its own zero-dep leaf
49/// crate (`car-winenv`) so low-level crates like `car-registry` can use it
50/// without pulling in car-engine; re-exported here so existing
51/// `car_engine::win_env::…` call sites keep working unchanged.
52pub use car_winenv as win_env;
53
54pub use admission::{AdmissionDecision, AdmissionGate, GateContext, GateOutcome};
55pub use agent_basics::entries as agent_basic_entries;
56pub use agent_capability::AgentCapabilityRegistry;
57pub use authz::{
58    AllowAllPermissions, AuthzDecision, AuthzPipeline, AuthzResult, AuthzStage, PermissionHandler,
59    Restriction, TierPermissionHandler,
60};
61pub use builtin_agents::{
62    agent_metadata, format_capability_payload, register_builtins, BuiltinAgent,
63    CapabilityPayloadError, BUILTIN_AGENTS,
64};
65pub use cache::ResultCache;
66pub use capabilities::CapabilitySet;
67pub use checkpoint::Checkpoint;
68pub use executor::{
69    format_tool_result, format_tool_result_for_model, is_command_tool, parse_rendered_output,
70    parse_tool_output, render_tool_output, truncate_keeping_ends, validate_proposal_action_ids,
71    CostBudget, FailedActionSummary, ReplanCallback, ReplanConfig, ReplanContext, Runtime,
72    ToolExecution, ToolExecutor, TransactionCheckMode, CANCELED_PREFIX, ELIDED_MARKER,
73    MODEL_OBSERVATION_FORMAT,
74};
75pub use flow::{
76    builtin_tool_labels, load_tool_labels, tool_output_is_external, FlowLoadError,
77    InformationFlowGate, ToolLabelConfig, NET_SEND,
78};
79pub use goal::GoalGather;
80pub use mcp::{McpServer, McpServerConfig, McpSession, McpToolExecutor, McpToolInfo};
81pub use messaging::{MessageReceipt, MessageSink, OutboundMessage, Recipient};
82pub use rate_limit::{RateLimit, RateLimiter};
83pub use registry::{ToolEntry, ToolPermission, ToolRegistry, ToolSource};
84pub use scope::RuntimeScope;
85pub use skill_ceiling::{SkillCeilingGate, SKILL_CONTEXT_KEY};
86pub use subprocess::{SubprocessTool, SubprocessToolExecutor};
87pub use substrate::{
88    CommandOutput, LocalSubstrate, McpSubstrate, PathState, Substrate,
89    SUBSTRATE_TRANSPORT_ERR_PREFIX,
90};
91pub use taint::TaintLedger;
92pub use verify_gate::StaticVerificationGate;
93pub use voice_turn::{
94    dispatch_voice_turn, dispatch_voice_turn_sidecar_only,
95    dispatch_voice_turn_sidecar_only_with_classifier,
96    dispatch_voice_turn_sidecar_only_with_telemetry, dispatch_voice_turn_with_telemetry,
97    fast_done_frame, DirectDataFetcher, SidecarResult, VoiceTelemetry, VoiceTurnControl,
98    VoiceTurnError, VoiceTurnHandle,
99};
100
101// === Umbrella re-exports (car#205) ===
102//
103// car-engine is one of the published umbrella crates external Rust
104// consumers cargo-add against. Re-exporting the engine-cluster
105// types here lets tokhn (and future consumers) depend on a single
106// crate instead of a dozen internal workspace crates. Internal
107// crates stay separate for compile-time and target-gating reasons
108// (CLAUDE.md forbids cargo feature flags), but they ship via
109// path-deps once the publish-set trim lands in a follow-up.
110//
111// Re-exports are selective (not `pub use car_*::*`) so adding or
112// renaming internal symbols doesn't silently leak to the
113// umbrella's public surface — every type listed here is one the
114// surveyed external consumer (tokhn) actually uses. Adding new
115// re-exports is intentional and visible.
116//
117// The submodule pattern for ir / eventlog mirrors the way
118// consumers reach into existing public submodules of car-memgine
119// (`car_memgine::distill::*`) or car-inference
120// (`car_inference::hardware::*`) — keeps grouping legible.
121
122pub use car_eventlog::{EventKind, EventLog, SpanStatus};
123pub use car_ir::{
124    Action, ActionProposal, ActionType, AgentOutcome, Evidence, EvidenceKind, FailureBehavior,
125    OutcomeMetrics, OutcomeStatus, ProposalResult, ToolSchema,
126};
127pub use car_planner::{Planner, PlannerConfig, ToolFeedback};
128pub use car_policy::{
129    ApprovalDecision, ApprovalLedger, ApprovalRecord, GateDecision, PermissionGate, PermissionTier,
130    PolicyCheck, PolicyEngine, RiskClassifier,
131};
132pub use car_state::StateStore;
133pub use car_validator::validate_tool_output;
134pub use car_verify::VerifyIssue;
135// car-sandbox / car-active-planner aren't re-exported here — both
136// depend on car-engine, so the umbrella inclusion would cycle.
137// They stay as their own publishable crates; tokhn keeps
138// `use car_sandbox::*` / `use car_active_planner::*` direct.
139
140#[cfg(test)]
141mod tests;
car_engine/lib.rs

car_engine/
lib.rs
