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("/my-project", None)?;

// 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(
    "/my-project",
    Some(SessionOptions::new().with_worker_agent(frontend)),
)?;

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

pub use error::CodeError;

pub use error::Result;

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

pub use workspace::CommandOutput;

pub use workspace::CommandOutputObserver;

pub use workspace::CommandRequest;

pub use workspace::LocalWorkspaceBackend;

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

pub use workspace::WorkspaceWriteOutcome;

Modules

budget

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

commands

Slash Commands — Interactive session commands

config

Configuration module for A3S Code

context

Context Provider Extension Point

error

Typed error enum for A3S Code Core

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.

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.

run

Durable run primitives for agent executions.

sandbox

Sandbox integration for bash tool execution.

security

Security Module

skills

Skill System

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.

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.