#A3S Code

A3S Code is the Rust runtime behind the a3s code terminal application. You can also embed it in an IDE, runner, service, or desktop application. It handles the agent loop, context, tool calls, permission checks, child tasks, asynchronous Workspace retrieval, durable evidence, and session recovery.

Version 8.3.0 hardens the durability and trust kernel: negotiated session-store guarantees, typed tool-result trust labels, workspace source snapshots, fallible SDK runtime init, and host-owned immutable-content / checkpoint / capability hooks across Node.js, Python, and Go. Persistent BM25 retrieval and Windows native index paths are production-ready for the release matrix.

Install the a3s CLI when you want to work in a terminal. When building a product, use the Rust crate, Node.js package, Python package, or Go module with its matching native bridge. They emit the same events, so every UI does not need its own agent loop.

#Choose an entry point

#What it includes

#What is new in v8.3.0

• Session-store durability is negotiable (KRN-6). Built-in memory and file adapters advertise exact guarantees such as aggregate CAS, append-only WAL, writer lease fencing, optional AES-256-GCM encryption at rest, commit watch notifications, and reference-aware artifact GC. Hosts must check SessionStoreCapabilities before relying on a semantic.
• Every tool result carries a typed trust label (KRN-5): trusted, workspace data, or external. Run-bound model calls admit prompt trust before budget/evidence/generation stages; external results fail closed until redaction review. Sessions expose secret-free model_middleware_health counters on Rust and all four SDKs.
• Workspace retrieval binds results to a tamper-evident source snapshot (KRN-4). Served chunks stay current across derived-index rebuilds and go stale when the manifest, eligibility, catalog, or content changes.
• Node.js and Python FFI runtime initialization is fallible (KRN-9): Tokio spawn/import failures surface stable errors instead of process panics. TASK_ADMISSION_AT_CAPACITY maps consistently across SDKs.
• Node.js, Python, and Go expose host-owned immutable-content adapters, live checkpoint export sinks, Skill-only capability batch application, and projected middleware health. Shared evaluation fixtures under sdk/evaluation/ document the wire contracts.
• Primary-session prompts stay aligned with explicit capability boundaries: Auto/pre-analysis no longer silently swaps specialty Explore/Plan prompts; host-selected AgentStyle installs matching permission and tool contracts.
• Persistent BM25/zvec indexing is release-qualified on Windows and Linux, including stripping Windows \\?\ verbatim paths before native opens and keeping the persistent coordinator alive past the initial Absent state.
• Linux arm64 Python wheels ship as manylinux_2_39_aarch64 (glibc 2.39+) to match the bundled zvec runtime; x86_64 Linux remains manylinux_2_28.

#Earlier v8.2.0 additions

• steer adds a newer instruction to the active Run at its next safe point; interrupt cooperatively stops provider, Tool, workflow, and delegated work. Idempotent receipts and optional expected-turn fields prevent duplicate or stale UI actions.
• pre_run_control can gate a control request and post_run_control observes every durable receipt transition. run_control_applied is available through the shared event protocol and persisted Run history.
• The default prompt now composes a compact operating loop, a runtime authority contract, repository Tool schemas, and safety boundaries. It treats files, Tool output, and web content as untrusted data and requires evidence before a completion claim without replacing host permissions or approvals.
• Real-provider release tests exercise both configured DeepSeek models across tools and Hook rewrites, long-horizon coding, SubAgents, Skills, PTC, replayable dynamic workflows, and live steer/interrupt behavior.
• Dynamic workflows no longer need a duplicate permission grant for their private program implementation step, while inner Tool calls remain fully governed. QuickJS ctx.readFile() now returns file text; ctx.read() keeps the line-numbered Tool result for audit-oriented code.

#Earlier v8.1 additions

• web_search is powered by a3s-search v3.1.0. Google, Baidu, Bing, and Brave browser engines use Moli by default; Chrome/Chromium and Lightpanda remain explicit compatibility backends. The first-use runtime is selected in this order: package sidecar, verified per-user cache, system executable, and finally a digest-pinned HTTPS download.
• The Moli installer uses an atomic staging/receipt protocol and a cross-process lock at ~/.cache/a3s-code/moli (or A3S_CODE_MOLI_CACHE_DIR). A second A3S Code process waits for the first install and reuses the same executable. Set autoDownloadMoli: false when a host must fail closed rather than access the network.
• Rust, Node.js, Python, and Go expose the same sdk_capabilities inventory, state-graph operations, Moli diagnostics, and typed search configuration. Use the inventory to feature-detect a build instead of parsing package files.
• Native Node packages and Python wheels include their target Moli sidecar and provenance metadata. Linux musl packages explicitly carry an MOLI_UNAVAILABLE marker because upstream Moli does not publish a musl binary; those hosts must provide a system Moli executable or choose another backend.

#Earlier v7.0 additions

• Session-owned Workspace Retrieval builds one bounded text catalog asynchronously, reuses incremental BM25 postings, and can publish exact in-memory vector partitions without delaying session construction or adding a vector database.
• Dense semantics are explicitly host-enabled. Exact search, glob, BM25, Code Intelligence, RRF, and the optional deterministic reranker run locally on CPU; a host can inject an in-process CPU embedding callback when semantic search is useful.
• Rust, Node.js, Python, and Go expose typed line, fixed-window, and recursive chunking, readiness and batching metrics, optional deterministic reranking, cancellation, current-source digest verification, and bounded cleanup. Non-text assets are rejected before chunking or embedding.
• Product builds use zvec-rust for lexical FTS/BM25 and A3S Memory for exact semantic vectors. Native lexical handles are bounded and temporary; semantic vectors are released with the owning session.
• Model-bound run evidence records the effective capability and policy identity, retrieval generation, input shape, repeated Tool-result context, and normalized usage without retaining new prompt, source, vector, credential, or endpoint plaintext.

Go consumers must use the v7 module path: github.com/A3S-Lab/Code/sdk/go/v8.

v6.9 introduced the shared priority/FIFO scheduler, bounded personal and project instruction chains, governed lifecycle hooks, isolated Harness Git worktrees, deterministic Tool-result evidence, and exact cognitive-package generation bindings.

v6.8 presents one compact search schema for grep, glob, and dependency-free BM25 ranking, plus one model-visible task schema for focused or bounded fan-out delegation. Legacy direct host aliases remain readable without consuming model schema tokens. The same release adds exact, replay-safe run admission for headless hosts and exposes its snapshot/replay result through the Node.js, Python, and Go SDKs.

The v6.7 local download tool streams HTTP(S) resources through SSRF-safe redirect validation into adjacent temporary files, supports adaptive 1–4 connection Range transfers, and can verify a 64-character expected_sha256 before atomic promotion. It is a permission- and HITL-governed workspace mutation and is not registered for remote workspace backends. See Tools.

Search uses a structurally gated cascade: a Moli tier included in the default Core feature set, HTTP/RSS engines, then native APIs. A completed cascade that remains below the structural retrieval requirements fails closed instead of presenting weak candidates as successful evidence. No external semantic verifier or reranker is required. Delegated contexts share bulkheads, retry budgets, and identical-request coalescing; see Tools.

A run roughly follows this path:

Agent / AgentSession
  -> collect project context
  -> optional plan
  -> select tools or child tasks
  -> check permission and ask the user when needed
  -> execution
  -> publish events and verification results
  -> save the session

#Install

For the interactive terminal workspace, run the installer for your platform:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.sh | sh

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
irm https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.ps1 | iex

The scripts select the release archive for the current system and architecture and verify its SHA-256 digest. You can also use brew install a3s-lab/tap/a3s or cargo install a3s.

Install an SDK when embedding A3S Code:

npm install @a3s-lab/code
pip install a3s-code
cargo add a3s-code-core
go get github.com/A3S-Lab/Code/sdk/go/v8

The v8.3.0 Python package supports CPython 3.10–3.14 through one cp310-abi3 wheel per platform. Intel Macs use the macosx_12_0_x86_64 wheel and require macOS 12 or newer. See Python wheel platforms for the bootstrap flow and the No module named pip repair command.

#Configure

A3S Code uses ACL. Keep real API keys, private model endpoints, local config paths, and tenant/user identifiers out of commits. Commit templates that resolve credentials from the environment.

default_model = "provider/model-id"
max_parallel_tasks = 4
auto_parallel = false

providers "provider" {
  apiKey = env("PROVIDER_API_KEY")
  baseUrl = env("PROVIDER_BASE_URL")

  models "model-id" {
    tool_call = true
    limit = {
      context = 128000
      output = 4096
    }
  }
}

storage_backend = "file"
sessions_dir = ".a3s/sessions"

search {
  headless {
    backend = "moli"
    auto_download_moli = true
    max_tabs = 4
  }
}

auto_parallel = false disables automatic parallel child-agent fan-out only. Manual task calls and SDK session.tasks(...) fan-out remain available unless manual delegation is disabled separately.

The Moli sidecar is selected automatically by the SDK package. For a source checkout or a minimal Core build, set A3S_CODE_MOLI_EXECUTABLE to a verified executable, or let the first search call download the pinned release into the shared cache.

#Use the TUI

Run a3s code from the workspace you want the agent to inspect:

a3s code
a3s code resume <session-id>
a3s code update

The TUI discovers config from A3S_CONFIG_FILE, then .a3s/config.acl walking upward from the current directory, then ~/.a3s/config.acl.

Common first-run flow:

/init          # inspect the repository and create or update AGENTS.md
/model         # pick a configured provider or account-backed model
/effort        # choose low, medium, high, xhigh, max, or ultracode
/ide           # open the workspace tree and terminal editor
/help          # open the full command and shortcut guide

#Rust Runtime Quick Start

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

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let session = agent
        .session_builder("/path/to/workspace")
        .options(
            SessionOptions::new()
                .with_planning(true)
                .with_max_parallel_tasks(4)
                .with_tool_timeout(120_000),
        )
        .build()
        .await?;

    let result = session
        .send("Find the authentication entry points.", None)
        .await?;
    println!("{}", result.text);

    let (mut rx, _handle) = session
        .stream("Summarize the test strategy.", None)
        .await?;
    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::TextDelta { text } => print!("{text}"),
            AgentEvent::End { .. } => break,
            _ => {}
        }
    }

    Ok(())
}

Rust construction is async-first. The synchronous Agent::session method only works when memory and the other required resources are already initialized; options that require async setup return CodeError::AsyncSessionBuildRequired. A session-option MCP manager always uses the async path while discovering tools.

Calls such as session.tool(...) come from your application, not the model. Check access in your application before exposing them to users.

#Continue reading

• A3S Code TUI explains installation, config discovery, slash commands, and effort profiles.
• SDKs and APIs explains Go module and bridge installation; the Go examples then stay beside Node.js and Python throughout the shared guides.
• Filesystem-first covers AGENTS.md, ACL, AgentDir, Skills, tools, and schedules.
• API contract lists the Node.js API covered by integration tests.
• Sessions covers creation, streaming, run state, saving, resuming, and cancellation.
• Tools covers direct calls, typed errors, structured output, and QuickJS programs.
• Workspace retrieval covers opt-in semantics, chunking, lifecycle, quality metrics, and safe CPU-only defaults.
• Tasks and orchestration cover child agents and fixed workflows.
• Security, hooks, and verification cover checks before, during, and after execution.
• Memory and persistence cover reusable facts and session recovery.