Architecture

A3S Code is organized around a small runtime kernel and a harness that controls the execution loop.

Prompt
  -> context assembly
  -> optional planning and automatic subagent delegation
  -> tool selection
  -> LLM generation
  -> programmatic tool calling
  -> configured permission/security integration
  -> tool execution
  -> observation
  -> verification
  -> trace storage
  -> compaction

Kernel

The kernel maintains sessions, calls providers, executes tools through one executor, records observations, and returns structured events and results.

Harness

The harness coordinates:

• which context is load-bearing
• which tools are visible
• configured permission, hook, AHP, and security-provider integration points
• how outputs are summarized before they re-enter context
• which verification evidence is required before completion
• how run snapshots, TaskList state, and trace events are exposed to host applications

PTC Path

Programmatic Tool Calling is a harness path for deterministic workflows. The program tool runs a JavaScript script in an embedded QuickJS VM with a controlled ctx object. By default, scripts may call every registered tool except program; callers can narrow that surface with allowed_tools. The docs contract verifies scripts that compose readFile, read, glob, grep, ls, bash, git, and generic tool(name, args), then return one structured result to the agent.

Use PTC when the operation is mostly mechanical:

• repository search and snippet collection
• test discovery and verification command selection
• package metadata inspection
• release preflight evidence gathering
• log parsing and summarization
• trace indexing

Use ordinary model tool calls when the next action requires judgment. Use PTC when the action sequence is known and the model only needs the result. Scripts can be passed inline as source or loaded from a workspace-relative .js or .mjs file path; the VM itself gets no direct filesystem, network, subprocess, or environment access.

Extension Points

Use session options, skills, agent definitions, .a3s/agents, hooks, MCP servers, memory/session stores, security providers, queue configuration, and AHP transports to adapt the runtime.

Design Direction

Prefer compact evidence over full transcripts, programmatic tool calls over repeated LLM tool loops, and explicit verification over "looks done" responses.