A3S Code

A Rust agent runtime and the execution core behind the a3s code terminal coding workspace.

A3S Code gives a coding agent the parts it should not improvise: context assembly, tool visibility, permission checks, human approval, memory, delegation, dynamic workflow execution, persistence, verification evidence, and event replay. The interactive product surface is the a3s code TUI, shipped by the a3s CLI and rendered with the a3s-tui terminal framework.

A3S Code is a local runtime, not a hosted agent service. It owns the agent loop and exposes it through a Rust crate. The TUI is one application built on that runtime.

prompt
  -> context assembly
  -> optional planning and goal tracking
  -> tool selection / delegated child tasks / dynamic workflow steps
  -> permission and confirmation checks
  -> execution
  -> events, artifacts, memory, and verification evidence
  -> compaction and persistence

Repository boundaries:

Use a3s code when you want the full terminal product. Use a3s-code-core when you are building another Rust host, runner, IDE bridge, or controlled agent service around the same runtime.

Install the a3s CLI to use the TUI:

brew install A3S-Lab/tap/a3s

# or from crates.io
cargo install a3s

# or from source
cargo install --git https://github.com/A3S-Lab/Cli

Run it from the workspace the agent should inspect:

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

Common first-run flow:

/init          # inspect the repository and create or update AGENTS.md
/model         # pick a configured provider, OS gateway model, or account 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

Install the Rust runtime crate when embedding A3S Code:

cargo add a3s-code-core

a3s code is a complete agentic workspace in the terminal. It combines the coding chat loop, file and config editing, durable context, local asset development, OS asset publishing, Runtime fan-out, RemoteUI views, and engineered automation loops.

The TUI command palette is intentionally small at the top level. Parameterized forms live under the asset or context family that owns them.

Config discovery checks:

1. A3S_CONFIG_FILE
2. .a3s/config.acl while walking upward from the current directory
3. ~/.a3s/config.acl

On first launch, the TUI can create a starter user config. Project-local config can set models, providers, OS endpoint, flow_dir, agent_dir, mcp_dir, skill_dir, storage, memory, delegation, and asset paths.

Sessions auto-save under the workspace session store. Exiting prints the exact resume command; a3s code resume without an id resumes the newest saved session in the current workspace. /fork copies the current transcript into a new session id while keeping the original, and /clear starts a fresh conversation.

The TUI owns human-in-the-loop approval. In default mode, mutating tools prompt through an approval overlay. a or /auto approves later tool calls for the session. Shift+Tab cycles default, plan, and auto modes. Plan mode auto-approves read-only discovery tools but still asks before writes. Tool execution timeouts and confirmation timeouts are tracked separately, so waiting for a human does not consume the command runtime budget.

All local filesystem work stays under the active workspace services and A3S Code permission policy. OS operations require /login; before login the TUI can still author local assets, run local subagents, use memory, and execute DynamicWorkflowRuntime, but OS runtime, RemoteUI ViewLinks, OS asset publishing, and OS service activity panels are unavailable.

The UI keeps long-running work observable. The transcript shows streamed model text, tool input/output, progress deltas, approvals, RemoteUI view buttons, dynamic-workflow artifacts, subagent activity, queue entries, and context-fill warnings. /output opens a normalized tool-call log for the current session, while /top shows host-side process activity using the same collector as a3s top.

/effort rebuilds the active session with a different depth profile. The design scales work on three axes:

• Thinking budget for providers that expose extended thinking.
• Tool-round budget and continuation count for all providers.
• Model-agnostic prompt guidance for rigor, verification, and decomposition.

All effort levels keep local task and parallel_task available, with the TUI session limiting sibling fan-out through max_parallel_tasks. ultracode adds automatic planning, goal tracking, and dynamic-workflow guidance, but the pre-analysis gate still decides whether a turn actually needs a plan or fan-out.

Planning is a governed runtime phase, not just prompt text. Hosts that attach a HookExecutor receive:

• PrePlanning before plan generation. This hook includes the session id, task description, available planning strategies, tool names, goal-tracking flag, and max_parallel_tasks. Returning Block, Retry, or Escalate stops the planning phase before PlanningStart is emitted. Returning modified data with modified_task, task_description, or prompt changes the planner input; selected_strategy, planning_template, and hints are appended as planning guidance. If an auto pre-analysis plan was already available, a modified planning task discards that candidate plan and forces planning from the modified input.
• PostPlanning after a plan is generated or planning fails. This hook reports the strategy used, generated subtasks, success flag, and error text when available.

The normal event stream still emits PlanningStart, PlanningEnd, TaskUpdated, StepStart, and StepEnd for UI rendering and replay. Hooks are for host policy, supervision, and observability around that same lifecycle.

A3S Code has two workflow concepts and they are intentionally different:

Dynamic workflow scripts are runtime artifacts, not a separate TypeScript SDK. They run inside the existing program QuickJS sandbox and may call only the tools that the host allows through ctx.

export default async function run(ctx, inputs) {
  if (inputs.kind === "workflow") {
    return {
      type: "schedule_steps",
      steps: [
        {
          step_id: "inspect",
          step_name: "inspect_workspace",
          input: { query: inputs.input.query }
        },
        {
          step_id: "fanout",
          step_name: "parallel_task",
          input: {
            tasks: [
              {
                task_id: "tests",
                agent: "explore",
                description: "Inspect test coverage",
                prompt: "Find relevant tests and gaps."
              },
              {
                task_id: "risk",
                agent: "review",
                description: "Review implementation risk",
                prompt: "Review the current approach for likely regressions."
              }
            ]
          }
        }
      ]
    };
  }

  if (inputs.step_name === "inspect_workspace") {
    const hits = await ctx.grep(inputs.input.query, { glob: "*.rs" });
    return { hits };
  }

  return { ok: true };
}

Important runtime rules:

• Ordinary PTC steps can call ctx.read, ctx.grep, ctx.glob, ctx.tool("runtime", ...), and other allowed tools.
• The signed-in runtime tool is available only after /login.
• parallel_task stays native. A workflow schedules a Flow step with step_name: "parallel_task" and the host executes it outside QuickJS.
• program, dynamic_workflow, and recursive parallel_task calls are removed from the default PTC allow-list.
• Local workflow history is stored under .a3s-flow/dynamic-workflows when the workspace has a local root; otherwise it uses an in-memory store.

DeepResearch uses the same boundary. A ? prompt asks the host-controlled dynamic workflow to gather evidence first. When OS Runtime is available, the workflow can call runtime for remote batch execution; otherwise it schedules a host-side parallel_task step for local subagents. The final synthesis turn must cite the gathered evidence and link the generated report or RemoteUI view.

A3S Code treats context as a managed runtime resource rather than a pile of text in the prompt. The TUI assembles context from project instructions, active workspace files, recent-file and ripgrep providers, skills, MCP tools, memory recall, run observations, and user-attached transcript windows.

The memory system has two practical loops:

• Short-term session context is compacted when the context fill ratio crosses the configured threshold. /compact triggers this manually.
• Durable memory stores reusable facts, decisions, preferences, failures, and workflow notes. /ctx save <n> promotes a past transcript hit into memory, /sleep performs end-of-day consolidation, and /memory opens a graph view with aliases, tiers, relations, conflicts, provenance, and forget candidates.

TUI memory defaults to the user's durable memory store, while embedded Rust sessions can provide a typed memory store or a file memory directory through SessionOptions.

Add an OS endpoint to config and sign in from the TUI:

os = "https://os.example.com"

/login

After login, A3S Code can use OS capabilities from normal model turns, asset commands, loops, DeepResearch, and dynamic workflow steps.

A3S Code keeps durable agent behavior in files before APIs. This makes instructions, worker roles, reusable skills, schedules, and local asset definitions reviewable in normal code review.

repo/
├── AGENTS.md          # project instructions loaded into context
├── agent.acl          # model/provider/runtime policy for Rust sessions
└── .a3s/
    ├── agents/        # worker/subagent definitions
    ├── skills/        # reusable project skills
    ├── loops/         # engineered loop specs and logs
    ├── workflows/     # workflow asset designs for /flow
    └── okf/           # knowledge package assets

agent-dir/
├── instructions.md    # AgentDir main-agent role slot
├── agent.acl          # optional AgentDir runtime config
├── skills/            # AgentDir-private skills
├── tools/             # MCP or sandboxed PTC tool specs
└── schedules/         # cron-driven recurring turns

These files do not bypass harness boundaries. Permissions, confirmation, tool visibility, response contracts, sandboxing, memory extraction, and verification remain part of the runtime execution path.

Use ACL for product configuration. Keep real keys and private base URLs in the environment; commit templates, not local secrets.

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

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

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

os = env("A3S_OS_URL")

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

auto_delegation {
  enabled                 = false
  auto_parallel           = false
  allow_manual_delegation = true
  min_confidence          = 0.72
  max_tasks               = 4
}

Do not commit .a3s/config.acl, local provider URLs, access tokens, API keys, or real tenant/user identifiers.

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(
        "/path/to/workspace",
        Some(
            SessionOptions::new()
                .with_planning(true)
                .with_max_parallel_tasks(4)
                .with_tool_timeout(120_000),
        ),
    )?;

    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 hosts can call tools directly when they want deterministic control-plane behavior instead of asking the model to select a tool.

use a3s_code_core::Agent;
use serde_json::json;

async fn inspect_workspace() -> anyhow::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let session = agent.session("/path/to/workspace", None)?;

    let source = session.read_file("src/main.rs").await?;
    let hits = session.grep("PermissionPolicy").await?;
    let files = session.glob("**/*.rs").await?;
    let test_output = session.bash("cargo test -p a3s-code-core").await?;

    let dynamic = session
        .tool(
            "dynamic_workflow",
            json!({
                "source": "export default async function run(ctx, inputs) { return { type: 'complete', output: inputs.input }; }",
                "input": { "message": "hello from Flow" }
            }),
        )
        .await?;

    println!("{source} {hits} {files:?} {test_output}");
    println!("{}", dynamic.output);
    Ok(())
}

Direct host calls are privileged. Gate them in the embedding application before exposing them to end users.

Run commands from this crate workspace, not from the monorepo root:

cargo fmt --all --check
cargo test -p a3s-code-core
cargo test -p a3s-code-core --test test_program_script_quickjs_integration
cargo test -p a3s-code-core --test test_prompt_boundaries_and_log_redaction

Real LLM tests are ignored by default and require explicit provider configuration through A3S_CONFIG_FILE or a local git-ignored config:

A3S_CONFIG_FILE=/path/to/local/config.acl \
  cargo test -p a3s-code-core --test test_real_config_env_integration -- --ignored --nocapture

A3S_CONFIG_FILE=/path/to/local/config.acl \
  cargo test -p a3s-code-core --test test_orchestration_real_llm -- --ignored --nocapture

Do not paste real provider values into test commands, logs, commits, or pull request descriptions.

Full guides live in the docs site:

• A3S Code docs
• A3S Code TUI
• Filesystem-First
• Sessions
• Commands
• Tools
• Verification
• Providers
• Workspace Backends
• Orchestration
• Security
• Hooks
• Agent Directory

The repository root is not a Rust crate. Work from this crate workspace:

cargo fmt --all
cargo test -p a3s-code-core
cargo clippy -p a3s-code-core -- -D warnings

MIT