#A3S Code

A3S Code is a Rust coding-agent runtime (a3s-code-core). Embed it in an IDE, runner, service, or desktop app when you need an agent loop with tools, permissions, child tasks, workspace search, and session save/resume.

The default profile is local-code: the agent loop, workspace tools, policy, events, and pure-Rust a3s-vec lexical search. read returns JPEG/PNG/GIF/WebP as image attachments, and the OpenAI-compatible path keeps image_url parts in tool results. Project rules live in AGENTS.md, and workers live under .a3s/agents/.

#Design rules

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 v9.0.0

v9.0.0 also carries the changes tagged as v8.7.0. That tag was never published, so they first ship here.

#Changed

• Fact-log control. The fact log is the only coding control source. send, stream, attachment turns, resume_run, and exact recovery choose the next transition by folding it. A stored model turn is not sent to the model again, and a loop checkpoint does not choose the next model call. Confirmations and questions park until an answer fact arrives. A missing tool result runs once on resume. A steer is another user.message fact. The tool-round cap sends an empty tool list on the next completion instead of a synthetic user message. See Architecture.
• Go module major is v9. Import github.com/A3S-Lab/Code/sdk/go/v9.
• a3s-vec lexical FTS. Workspace FTS uses pure-Rust a3s-vec 0.1.8 (a3s_vec_fts_v1) through the a3s-vec-fts feature. Release packages no longer stage a native FTS sidecar. Older on-disk FTS generations are incompatible and are rebuilt.
• Sandbox. Core requires a3s-sandbox 0.2.1.
• Thinner builds. Thin coding builds no longer link a3s-flow; named Flow capability projection needs the dynamic-workflow feature (included in advanced-harness). PDF text extraction in web_fetch is behind web-fetch-pdf (included in local-code). The server profile is local-code + s3 + telemetry.
• web_search success contract. The cascade tries API, then HTTP/RSS, then headless (headless only in builds with the headless-search feature, which no published SDK package enables). Non-empty usable rows succeed as complete or partial; the structural gate only decides whether to continue the cascade. JSON output stays a result array. Empty results, unknown engines, and invalid arguments are still errors (#161).

#Added

• Meta Harness. Hosts compose ordered components over the one fact log: stock system, tools, budget, compact, and infer, plus host:<id> mounts from a HostHarnessRegistry. Node.js and Python expose Harness; Go exposes SessionOptions.Harness. Omit harness to keep the default tree. See Meta Harness.
• Host-only CompletionAttestor (#160). A Rust host can install SessionOptions::with_completion_attestor. It receives the mutation digest and each mutated path with its content digest (MutatedPathRecord), and may return a verification report before the completion gate decides. The gate still requires a Passed, digest-bound report.
• Go planning override. Go Session exposes SetPlanningMode and ClearPlanningModeOverride, matching Node.js and Python.

#Removed

• The filesystem-first agent mode: the serve feature, the AgentDir primary-agent convention (instructions.md, schedules/, tools/), the cron daemon, and AgentDirScriptTool. Worker and subagent agent_dirs scanning remains.

#Fixed

• NO_PROXY / no_proxy is honored when an explicit HTTP(S)_PROXY is set for MCP HTTP transports, OAuth, and model HTTP clients (#171). See Providers.
• Python SessionOptions.verifier_enabled has a getter and setter (#163).
• Rolling context compaction re-pins the original ## Goal when the summary omits it (#174).

Earlier releases are recorded in the CHANGELOG.

#Install

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/v9

The Python package requires CPython 3.10 or newer and ships one abi3 wheel per platform. See SDKs and APIs for wheel platforms, the Go bridge, and the bootstrap flow.

To install the a3s CLI, which ships the a3s code terminal app on its own release line, 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. The published CLI (0.17.1) pins a3s-code-core =8.7.0 at a pre-9.0 commit; see A3S Code TUI for what that means.

#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
    }
  }
}

agent_dirs = ["./.a3s/agents"]
skill_dirs = ["./skills"]
storage_backend = "file"
sessions_dir = ".a3s/sessions"

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.

Local session persistence pairs storage_backend = "file" with sessions_dir. SDK embeds can pass a typed FileSessionStore instead.

#Use the TUI

The 9.0.0 terminal client is the a3s-code-tui crate. Build and run it from a Code checkout:

cargo run -p a3s-code-tui -- --workspace /path/to/workspace --home "$HOME"

Without --config, it merges <home>/.a3s/config.acl with the nearest .a3s/config.acl found walking upward from the workspace, then applies A3S_DEFAULT_MODEL. It offers /help, /model, /clear, and /exit, and each prompt runs one fact-log send in a new session that reuses the workspace's tui-turn fact log. See A3S Code TUI.

#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.

#Use an SDK

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');
const session = agent.session('/path/to/workspace', {
  planningMode: 'auto',
  permissionPolicy: {
    allow: ['read(*)', 'search(*)'],
    ask: ['bash(*)', 'write(*)'],
    deny: ['write(**/.env*)', 'bash(rm -rf*)'],
    defaultDecision: 'ask',
    enabled: true,
  },
});

const result = await session.send('Find the authentication entry points.');
console.log(result.text);
console.log(result.verificationSummaryText);

session.close();
await agent.close();

#Continue reading

• Architecture explains fact-log control, the kernel wrappers, and the invocation boundaries.
• Meta Harness explains how hosts compose the coding actor.
• A3S Code TUI explains the 9.0.0 terminal client, its configuration layers, and how it relates to the a3s CLI.
• SDKs and APIs explains Go module and bridge installation; the Go examples then stay beside Node.js and Python throughout the shared guides.
• Sessions covers creation, streaming, run state, saving, resuming, and cancellation.
• Tools covers direct calls, typed errors, structured output, and QuickJS programs.
• Security, hooks, and verification cover checks before, during, and after execution.
• Workspace retrieval covers opt-in semantics, chunking, lifecycle, quality metrics, and safe CPU-only defaults.
• Tasks and orchestration cover child agents and fixed workflows.
• Memory and persistence cover reusable facts and session recovery.
• Filesystem conventions covers AGENTS.md, ACL, Skills, and .a3s/agents/ workers.
• API contract lists the Node.js API covered by integration tests.