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 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 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::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::RunSnapshot;

pub use run::RunStatus;

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 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::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

budget

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

code_intelligence

Workspace-scoped semantic code intelligence contracts.

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

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.

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

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.