Crate a3s_code_core 

A3S Code Core Library

Harness-driven runtime for coding agents.

Agent and AgentSession are the primary 2.0 API. Lower-level session runtime state is internal; persistence data flows through store::SessionData.

Quick Start

use a3s_code_core::{Agent, AgentEvent};

// From an ACL-compatible config file path (.acl)
let agent = Agent::new("agent.acl").await?;

// Create a workspace-bound session
let session = agent.session_async("/my-project", None).await?;

// Non-streaming
let result = session.send("What files handle auth?", None).await?;
println!("{}", result.text);

// Streaming (AgentEvent is #[non_exhaustive])
let (mut rx, _handle) = session.stream("Refactor auth", None).await?;
while let Some(event) = rx.recv().await {
    match event {
        AgentEvent::TextDelta { text } => print!("{text}"),
        AgentEvent::End { .. } => break,
        _ => {} // required: #[non_exhaustive]
    }
}

Disposable Workers

use a3s_code_core::{Agent, SessionOptions, WorkerAgentSpec};

let agent = Agent::new("agent.acl").await?;
let frontend = WorkerAgentSpec::implementer(
    "frontend-cow",
    "Small verified frontend fixes",
)
.with_model_ref("openai/gpt-4o")
.with_max_steps(24);

let session = agent.session_async(
    "/my-project",
    Some(SessionOptions::new().with_worker_agent(frontend)),
).await?;

Architecture

Agent (config-driven facade)
  +-- AgentSession (workspace-bound execution API)
      +-- internal turn runner
      +-- ContextAssembler / ContextProvider
      +-- ToolSelector
      +-- ToolExecutor
      +-- ProgramExecutor (PTC)
      +-- SkillRegistry
      +-- Permission / confirmation
      +-- Trace / artifacts / verification evidence

Advanced infrastructure:
  +-- optional lane queues for explicit external/hybrid dispatch

Re-exports

pub use agent_protocol::AgentProtocolChangeSetRequestV1;

pub use agent_protocol::AgentProtocolChangeSetV1;

pub use agent_protocol::AgentProtocolCommandActionV1;

pub use agent_protocol::AgentProtocolCommandReceiptV1;

pub use agent_protocol::AgentProtocolCommandV1;

pub use agent_protocol::AgentProtocolError;

pub use agent_protocol::AgentProtocolEventPageRequestV1;

pub use agent_protocol::AgentProtocolEventPageV1;

pub use agent_protocol::AgentProtocolEventRecordV1;

pub use agent_protocol::AgentProtocolRunCancelV1;

pub use agent_protocol::AgentProtocolRunIdentityV1;

pub use agent_protocol::AgentProtocolRunRecoverV1;

pub use agent_protocol::AgentProtocolRunStartV1;

pub use agent_protocol::AgentProtocolRunStateV1;

pub use agent_protocol::AGENT_PROTOCOL_CHANGE_SET_ENCODING_V1;

pub use agent_protocol::AGENT_PROTOCOL_CHANGE_SET_FORMAT_V1;

pub use agent_protocol::AGENT_PROTOCOL_CHANGE_SET_HTTP_PATH_V1;

pub use agent_protocol::AGENT_PROTOCOL_COMMAND_HTTP_PATH_V1;

pub use agent_protocol::AGENT_PROTOCOL_EVENT_PAGE_HTTP_PATH_V1;

pub use agent_protocol::AGENT_PROTOCOL_MAX_CHANGE_SET_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_CHANGE_SET_RESPONSE_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_EVENTS_PER_PAGE;

pub use agent_protocol::AGENT_PROTOCOL_MAX_EVENT_METADATA_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_EVENT_PAGE_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_EVENT_PAYLOAD_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_EVENT_RECORD_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_EVENT_TYPE_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_ID_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_PROMPT_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_MAX_REASON_BYTES;

pub use agent_protocol::AGENT_PROTOCOL_V1;

pub use agent_protocol_harness::AgentProtocolHarness;

pub use agent_protocol_harness::AgentProtocolHarnessError;

pub use agent_protocol_harness::AGENT_PROTOCOL_HARNESS_MAX_SESSIONS;

pub use agent_protocol_host::AgentProtocolHost;

pub use agent_protocol_host::AgentProtocolHostError;

pub use code_intelligence::CodeDiagnostic;

pub use code_intelligence::CodeDiagnosticSeverity;

pub use code_intelligence::CodeIntelligenceCapabilities;

pub use code_intelligence::CodeIntelligenceError;

pub use code_intelligence::CodeIntelligenceLanguageStatus;

pub use code_intelligence::CodeIntelligenceResult;

pub use code_intelligence::CodeIntelligenceState;

pub use code_intelligence::CodeIntelligenceStatus;

pub use code_intelligence::CodeLocation;

pub use code_intelligence::CodePosition;

pub use code_intelligence::CodeQueryResult;

pub use code_intelligence::CodeRange;

pub use code_intelligence::CodeSymbolKind;

pub use code_intelligence::DocumentRevision;

pub use code_intelligence::DocumentSnapshot;

pub use code_intelligence::DocumentSymbol;

pub use code_intelligence::LanguageId;

pub use code_intelligence::LocalCodeIntelligence;

pub use code_intelligence::NavigationKind;

pub use code_intelligence::SymbolInformation;

pub use code_intelligence::WorkspaceCodeIntelligence;

pub use cognitive_context::CognitiveContextDocumentV1;

pub use cognitive_context::CognitiveContextError;

pub use cognitive_context::CognitiveContextLimits;

pub use cognitive_context::CognitiveContextProvider;

pub use cognitive_context::CognitiveContextRequestV1;

pub use cognitive_context::CognitiveContextResponseV1;

pub use cognitive_context::CognitiveContextResult;

pub use cognitive_context::CognitiveContextSession;

pub use cognitive_context::CognitiveKnowledgeBindingV1;

pub use cognitive_context::CognitiveKnowledgeCitationV1;

pub use cognitive_context::CognitivePackageBindingV1;

pub use cognitive_context::COGNITIVE_CONTEXT_REQUEST_DIGEST_DOMAIN;

pub use cognitive_context::COGNITIVE_CONTEXT_REQUEST_SCHEMA;

pub use cognitive_context::COGNITIVE_CONTEXT_RESPONSE_SCHEMA;

pub use cognitive_context::COGNITIVE_KNOWLEDGE_BINDING_SCHEMA;

pub use cognitive_context::COGNITIVE_PACKAGE_BINDING_SCHEMA;

pub use cognitive_context::OKF_KNOWLEDGE_CITATION_SCHEMA;

pub use cognitive_context::OKF_KNOWLEDGE_READ_REQUEST_SCHEMA;

pub use cognitive_context::OKF_KNOWLEDGE_SEARCH_REQUEST_SCHEMA;

pub use config::AutoDelegationConfig;

pub use config::CodeConfig;

pub use config::ModelConfig;

pub use config::ModelCost;

pub use config::ModelLimit;

pub use config::ModelModalities;

pub use config::OsConfig;

pub use config::ProviderConfig;

pub use dynamic_workflow::dynamic_workflow_store_path;

pub use dynamic_workflow::DynamicWorkflowRuntime;

pub use dynamic_workflow::DynamicWorkflowScriptLimits;

pub use dynamic_workflow::DynamicWorkflowTool;

pub use dynamic_workflow::DYNAMIC_WORKFLOW_STORE_RELATIVE_PATH;

pub use error::SessionBuildResource;

pub use error::CodeError;

pub use error::Result;

pub use event_protocol::run_event_envelope_v1;

pub use event_protocol::AgentEventProjectionV1;

pub use event_protocol::AgentEventTypeV1;

pub use event_protocol::EventEnvelopeV1;

pub use event_protocol::EventProtocolError;

pub use event_protocol::AGENT_EVENT_TYPES_V1;

pub use event_protocol::EVENT_ENVELOPE_V1_VERSION;

pub use flow_graph::run_object_id as flow_run_object_id;

pub use flow_graph::step_object_id as flow_step_object_id;

pub use flow_graph::FileFlowDecisionLedger;

pub use flow_graph::FlowDecision;

pub use flow_graph::FlowDecisionClaimOutcome;

pub use flow_graph::FlowDecisionDispatchError;

pub use flow_graph::FlowDecisionDispatcher;

pub use flow_graph::FlowDecisionHealthSnapshot;

pub use flow_graph::FlowDecisionHealthStatus;

pub use flow_graph::FlowDecisionLedger;

pub use flow_graph::FlowDecisionRequest;

pub use flow_graph::FlowDecisionSink;

pub use flow_graph::FlowDecisionStep;

pub use flow_graph::FlowGraphHealthSnapshot;

pub use flow_graph::FlowGraphHealthStatus;

pub use flow_graph::FlowGraphObserver;

pub use flow_graph::MemoryFlowDecisionLedger;

pub use flow_graph::FLOW_GRAPH_SOURCE;

pub use llm::clear_http_metrics_callback;

pub use llm::set_http_metrics_callback;

pub use llm::AnthropicClient;

pub use llm::Attachment;

pub use llm::ContentBlock;

pub use llm::HttpMetricsCallback;

pub use llm::HttpMetricsRecord;

pub use llm::ImageSource;

pub use llm::LlmClient;

pub use llm::LlmResponse;

pub use llm::Message;

pub use llm::ModelGenerationAdmission;

pub use llm::ModelGenerationAdmissionError;

pub use llm::ModelGenerationConcurrency;

pub use llm::ModelGenerationPermit;

pub use llm::OpenAiClient;

pub use llm::TokenUsage;

pub use orchestration::execute_loop;

pub use orchestration::execute_pipeline;

pub use orchestration::execute_steps_parallel;

pub use orchestration::execute_steps_parallel_resumable;

pub use orchestration::AgentExecutor;

pub use orchestration::AgentStepSpec;

pub use orchestration::BudgetSnapshot;

pub use orchestration::LoopDecision;

pub use orchestration::PipelineStage;

pub use orchestration::StepOutcome;

pub use orchestration::Workflow;

pub use orchestration::WorkflowBudget;

pub use orchestration::WorkflowBuilder;

pub use orchestration::WorkflowCheckpoint;

pub use orchestration::WorkflowEvent;

pub use orchestration::WorkflowStepRecord;

pub use orchestration::WORKFLOW_CHECKPOINT_SCHEMA_VERSION;

pub use rl_trajectory::RlTrajectoryConfig;

pub use rl_trajectory::RlTrajectoryMode;

pub use rl_trajectory::RlTrajectoryRecorder;

pub use run::ActiveToolSnapshot;

pub use run::InMemoryRunStore;

pub use run::RunEventRecord;

pub use run::RunHandle;

pub use run::RunRecord;

pub use run::RunReservation;

pub use run::RunSnapshot;

pub use run::RunStatus;

pub use run::RunWorkspaceChangeSet;

pub use run::RunWorkspaceChangeSetError;

pub use state_graph::graph_event_head;

pub use state_graph::Behavior;

pub use state_graph::BehaviorContext;

pub use state_graph::BehaviorError;

pub use state_graph::EventFilter;

pub use state_graph::ExternalEvent;

pub use state_graph::ExternalProjectionOutcome;

pub use state_graph::FileGraphEventStore;

pub use state_graph::FnBehavior;

pub use state_graph::GraphDiff;

pub use state_graph::GraphEvent;

pub use state_graph::GraphEventRecord;

pub use state_graph::GraphEventStore;

pub use state_graph::GraphObject;

pub use state_graph::GraphPatch;

pub use state_graph::GraphRelation;

pub use state_graph::GraphRuntime;

pub use state_graph::GraphSaveOutcome;

pub use state_graph::MemoryGraphEventStore;

pub use state_graph::ObjectId;

pub use state_graph::PatchOperation;

pub use state_graph::RelationId;

pub use state_graph::ReplayError;

pub use state_graph::RuntimeError as GraphRuntimeError;

pub use state_graph::RuntimeLimits;

pub use state_graph::StateGraph;

pub use state_graph::GRAPH_EVENT_SCHEMA_VERSION;

pub use subagent::AgentDefinition;

pub use subagent::AgentRegistry;

pub use subagent::CattleAgentKind;

pub use subagent::CattleAgentSpec;

pub use subagent::ConfirmationInheritance;

pub use subagent::WorkerAgentKind;

pub use subagent::WorkerAgentSpec;

pub use subagent_task_tracker::InMemorySubagentTaskTracker;

pub use subagent_task_tracker::SubagentProgressEntry;

pub use subagent_task_tracker::SubagentStatus;

pub use subagent_task_tracker::SubagentTaskSnapshot;

pub use task_scheduler::TaskPriority;

pub use task_scheduler::TaskPriorityCounts;

pub use task_scheduler::TaskScheduler;

pub use task_scheduler::TaskSchedulerConfig;

pub use task_scheduler::TaskSchedulerError;

pub use task_scheduler::TaskSchedulerStats;

pub use tools::ToolCapabilities;

pub use tools::ToolErrorKind;

pub use tools::ToolOutputKind;

pub use workspace::CommandOutput;

pub use workspace::CommandOutputObserver;

pub use workspace::CommandOutputSummary;

pub use workspace::CommandRequest;

pub use workspace::LocalWorkspaceAccessPolicy;

pub use workspace::LocalWorkspaceBackend;

pub use workspace::LocalWorkspaceFile;

pub use workspace::LocalWorkspaceFileStatus;

pub use workspace::LocalWorkspaceManifest;

pub use workspace::LocalWorkspaceManifestSnapshot;

pub use workspace::ManifestWorkspaceBackend;

pub use workspace::RecentWorkspaceFile;

pub use workspace::RemoteGitBackend;

pub use workspace::RemoteGitBackendConfig;

pub use workspace::RemoteGitConflict;

pub use workspace::VirtualPathResolver;

pub use workspace::WorkspaceCapabilities;

pub use workspace::WorkspaceCommandRunner;

pub use workspace::WorkspaceDirEntry;

pub use workspace::WorkspaceError;

pub use workspace::WorkspaceFileChange;

pub use workspace::WorkspaceFileChangeKind;

pub use workspace::WorkspaceFileSystem;

pub use workspace::WorkspaceFileSystemExt;

pub use workspace::WorkspaceFileType;

pub use workspace::WorkspaceGit;

pub use workspace::WorkspaceGitBranch;

pub use workspace::WorkspaceGitCheckoutOutput;

pub use workspace::WorkspaceGitCheckoutRequest;

pub use workspace::WorkspaceGitCommit;

pub use workspace::WorkspaceGitCreateBranchRequest;

pub use workspace::WorkspaceGitCreateWorktreeRequest;

pub use workspace::WorkspaceGitDiffRequest;

pub use workspace::WorkspaceGitRemote;

pub use workspace::WorkspaceGitRemoveWorktreeRequest;

pub use workspace::WorkspaceGitStash;

pub use workspace::WorkspaceGitStashProvider;

pub use workspace::WorkspaceGitStashRequest;

pub use workspace::WorkspaceGitStatus;

pub use workspace::WorkspaceGitWorktree;

pub use workspace::WorkspaceGitWorktreeMutation;

pub use workspace::WorkspaceGitWorktreeProvider;

pub use workspace::WorkspaceGlobRequest;

pub use workspace::WorkspaceGlobResult;

pub use workspace::WorkspaceGrepOutcome;

pub use workspace::WorkspaceGrepRequest;

pub use workspace::WorkspaceGrepResult;

pub use workspace::WorkspacePath;

pub use workspace::WorkspacePathResolver;

pub use workspace::WorkspaceRef;

pub use workspace::WorkspaceResult;

pub use workspace::WorkspaceSearch;

pub use workspace::WorkspaceServices;

pub use workspace::WorkspaceServicesBuilder;

pub use workspace::WorkspaceTextRange;

pub use workspace::WorkspaceTextReader;

pub use workspace::WorkspaceVersionConflict;

pub use workspace::WorkspaceWriteOutcome;

Modules

agent_protocol

Versioned headless protocol owned by A3S Code.

agent_protocol_harness

Code-owned multi-session kernel for the native a3s code harness process.

agent_protocol_host

Code-owned adapter from the versioned headless protocol to AgentSession.

budget

Budget / cost / quota contract for cluster-grade hosts.

code_intelligence

Workspace-scoped semantic code intelligence contracts.

cognitive_context

Exact-generation cognitive-package context injected by an embedding host.

commands

Slash Commands — Interactive session commands

config

Configuration module for A3S Code

context

Context Provider Extension Point

dynamic_workflow

A3S Flow-backed dynamic workflow runtime.

error

Typed error enum for A3S Code Core

event_protocol

Versioned wire protocol for AgentEvent.

flow_graph

One-way projection from committed A3S Flow history into the state graph.

hitl

Human-in-the-Loop (HITL) confirmation mechanism

hooks

Hooks System for A3S Code Agent

host_env

Host-environment plumbing: ID generation and time.

llm

LLM client abstraction layer

loop_checkpoint

Per-tool-round loop checkpoints for crash-tolerant runs (P3 cut 1).

mcp

MCP (Model Context Protocol) Support

memory

Memory and learning system for the agent.

orchestration

Programmable, deterministic multi-agent orchestration.

permissions

Permission system for tool execution control

planning

Planning, Goal Tracking, and Task Management

program

Programmatic tool calling primitives.

queue

Per-session command queue with lane-based priority scheduling

release

Immutable, bounded Agent release manifests.

retention

In-memory retention limits for long-running sessions.

rl_trajectory

RL trajectory recording primitives.

run

Durable run primitives for agent executions.

sandbox

Sandbox integration for bash tool execution.

search_runtime

Browser runtime lifecycle API for headless web search.

security

Security Module

skills

Skill System

state_graph

Event-sourced reactive state graph for auditable agent workflows.

store

Session persistence layer

subagent

Delegated Agent System

subagent_task_tracker

In-memory tracker for delegated subagent tasks.

task_scheduler

Agent-wide admission scheduler for top-level and background work.

telemetry

Telemetry Module (Core)

tools

Extensible Tool System

trace

Runtime trace primitives.

verification

Verification contracts for A3S Code 2.0.

workspace

Workspace capability abstractions.

Structs

Agent

High-level agent facade.

AgentResult

Result of agent execution

AgentSession

Workspace-bound session. All LLM and tool operations happen here.

ReadFileOptions

Optional line-range controls for direct read tool calls.

SessionBuilder

Async-first session construction API.

SessionOptions

Optional per-session overrides.

SystemPromptSlots

Slot-based system prompt customization with intent-based style selection.

ToolCallResult

Result of a direct tool execution (no LLM).

Enums

AgentEvent

Events emitted during agent execution

AgentRunSpawn

Result of admitting a host-selected run identity for detached execution.

AgentStyle

Agent style — determines which system prompt template is used.

DetectionConfidence

Detection confidence level for style detection.

PlanningMode

Planning mode — controls when planning phase is used.