Agent Runtime Architecture

Session execution, checkpoints, message persistence, security boundaries, and cross-platform behavior

The runtime is designed to execute every input in a deterministic order, expose intermediate model and Tool state, and recover Sessions after process interruption.

Session is the execution boundary

Each Session owns independent:

  • ID, metadata, and model override.
  • Message history and System Snapshot.
  • Prompt/Command queue.
  • Tool approval state.
  • Composer and Executor.
  • Live Mutation stream.
// Session 在创建时选择 Workspace。
const session = await agent.sessions.create({ workspace });
const turn = await session.prompt({ query: "Inspect and fix the project" });
const result = await turn.finished;

prompt() returns a Turn Handle instead of direct text. finished resolves for both success and failure; inspect result.success and result.error for the outcome.

How one Prompt runs

The runtime guarantees:

  1. The canonical input is persisted before the model call: a User Message for a person, an Agent input Part for runtime input.
  2. Streaming Assistant output is first written as a recoverable draft.
  3. Text, Reasoning, Tool Calls, and Tool Results preserve canonical model-stream order.
  4. Complete model Steps and Tool state changes commit to canonical history.
  5. An interrupted run can recover from the draft and Action state.

State checkpoints

Only one execution loop is active per Session. Every input that can affect the next Step enters one ordered queue:

  • Human Prompts and runtime input inputs, including Task, delegation, background results, and tool media.
  • Workspace environment updates.
  • Power registry updates.
  • Session model updates.
  • Composer context advancement.

Changes are committed at Step boundaries, never halfway through a model call or Tool execution. An active Step uses the stable execution view created for it. Runtime input inputs append through the current Turn's unique writer without closing the Agent Message or being registered as User Messages. A new human input establishes a reply boundary. Background results keep input identity even under a user occupation; stop generations and original-Turn reception rules prevent late results from leaking into unrelated work.

Model resolution order is:

Session model > Agent model

Agent and Session hold model instances supplied by the host. The SDK does not select or restore model services from a string model ID.

Composer and Executor

SessionComposer owns model-context policy: returning base system blocks, dynamic system context for this step, a history view, and tools, and advancing its own derived state through advance_context(). The default Composer reads the latest summary from the current checkpoint and returns it in context_system_blocks.

StepInput freezes base blocks and assembles the base snapshot followed by the Composer's current dynamic blocks each step. Executor uses that input for model requests and Tool execution, handling aborts, retries, and context-limit recovery. SessionLoop owns the queue and Turn orchestration.

These components do not depend on physical Session storage paths, the Agent list, or HTTP/RPC transports.

System Snapshot

Base system instructions and dynamic system context have different lifetimes:

  • First assembly: freeze Agent identity, instruction, core, Power system, and stable Session context.
  • snapshot(): persist the current base snapshot.
  • syncshot(): regenerate the base snapshot from current Agent instructions and Power system; replace an existing persisted snapshot, or update only memory if none exists.

The Composer's system / system_blocks are base instructions; optional context_system_blocks are regenerated each step. Neither snapshot() nor syncshot() freezes dynamic summaries.

system() previews follow the same order as model requests: the base snapshot first, then the latest dynamic context. Agent instruction updates do not automatically rewrite existing base snapshots; checkpoint summary updates require no base instruction refresh.

Messages and persistence

Persisted Sessions belong to the Agent storage scope provided by City. Without City, the default is in-memory storage. A default local Session contains:

~/.downcity/agents/<agent_id>/sessions/<origin_type>/<session_id>/
├─ session.db
└─ attachments/
  • session_state.system_snapshot stores explicitly persisted base system text.
  • messages and message_parts store canonical history.
  • The Composer's own derived tables store checkpoint summaries and boundaries.

Agent Messages persist a stable_part_sequence watermark for their immutable committed prefix. Complete Step and input commits can advance it while the writer stays open. The Composer summarizes complete Step/input units within that prefix, preserves the latest request unit, and stops before unfinished Tool or Action units. A Step's tool-call/result group is never split, and an open Message's watermark blocks scanning later Messages.

Compaction changes only the history view sent to the model; canonical history is neither deleted nor rewritten. Recovery reads the base snapshot and current checkpoint separately, and builds the history view from canonical Parts. Without a base snapshot, base instructions are regenerated from the Agent's current instruction and powers.

Agent input Parts carry input_id, kind, optional source Tool/Turn IDs, content, and per-request meta for actor, Powers, and callback bindings. Idempotency and occupation recovery read those canonical input facts. Interactions are nested in the owning Tool Part's interactions array.

The model projection wraps runtime input in escaped runtime_input text at the user-role protocol boundary; canonical ownership remains Agent. Native media is emitted as separate content items using the shared attachment and image budgets. Source metadata is JSON text inside the wrapper, text nodes escape &, <, and >, and context blocks use safe semantic tags. Summary projection includes references without media binary content.

Session databases require schema v7. Other schema versions are rejected without automatic migration. Use the standalone scripts/migrate-session-sqlite-v7.mjs tool for read-only v5/v6 preflight; applying requires approved scope, all writers to have exited, and mandatory backups. Historical anomalies require a reviewed repair manifest bound to original source fingerprints and exact identities. See Session offline migration for execution and recovery boundaries.

Ordinary model chunks drive live rendering and in-memory assembly. Stable semantic checkpoints, including complete model Steps, Tool state changes, and Message closure, commit to SQLite. Hosts read structured state through session.messages(), get_info(), and system().

Live observation

subscribe() emits Mutations that occur after subscription:

const unsubscribe = session.subscribe((mutation) => {
  if (mutation.variant === "delta" && mutation.type === "text") {
    process.stdout.write(mutation.delta);
  }
});

Mutations cover complete Messages, Assistant Parts, text/reasoning deltas, Turn state, and Session state. After a disconnect, reload the canonical snapshot with messages() before establishing a new subscription.

Power runtime

Powers belong to City, not Agent or Workspace. City owns one instance per Power ID and projects its Actions, System text, Hooks, Resolve Points, and HTTP routes into every Agent/Workspace execution entry.

PowerRegistry projection changes take effect at Session checkpoints. A Power initialization failure isolates that Power without blocking others. Agent disposal stops Sessions and ActionSchedule; City closes the Power initialize/dispose lifecycle.

ActionSchedule is a local delayed Power Action scheduler owned by the Agent. Events are stored in the Agent's storage scope; after restart, abandoned running entries recover to pending. It is not a distributed scheduler and provides no cross-machine leader election.

City Powers

Every Agent receives three City-owned powers. They are the single entry point for "what only the harness knows" plus the generation models City itself holds.

{ "action": "sandbox.explain_path", "args": { "path": "~/.downcity/powers/messenger" } }
PowerAction groupsAnswers
contextenv, sandbox, workspaces, usageWhich Agent, Session, Workspace, model, timezone and local date this turn runs under; which sandbox backend and instance this Session runs in, which host directories are mounted, and why a path is blocked; every Workspace registered in this City; user-level token usage
aiimage, soundGenerate images; transcribe audio and synthesize speech
agentagentEvery Agent registered in this City

An action id is group.action, independent of which power owns it: env.get belongs to context, and both image.* and sound.* belong to ai. Calling a power with no arguments lists its actions; nothing here returns credential values, and each action declares read or write so you can see which ones consume quota or change state before calling them.

Availability follows the same rule as Powers: everything City registers is available to every Agent, with no per-Agent gating and no configuration file.

Image and sound

Both use the models available to your Federation account, so there is no separate configuration and nothing to set up. Because there is no configured default, pass model explicitly or take it from image.models / sound.models; asr and tts fall back to the first suitable model when none is given.

Image generation is a two-step job: create returns a job_id, result reads it. Creating an image consumes quota, so the model must confirm with you first. result writes the generated images into the power's private directory and returns their local paths; render them with ![](path).

Automatic transcription of inbound voice messages belongs to the Messenger power, which calls the ai power's sound.asr when a channel delivers a voice or audio attachment. If transcription fails for one attachment, the message still arrives.

Security model

Security is enforced at distinct capability boundaries:

CapabilityEnforced boundaryPermission semantics
File/Search ToolsProject path policy and Session read-only attachment capabilityProject files follow Workspace policy; read can also access attachments registered as owned by the current Session, without expanding write / edit / grep / find access
Sandbox ShellWorkspace SandboxCommands run in the Workspace's isolated, persistent environment
Host ShellApproval gatewayThe user explicitly authorizes one host command with a recorded reason
PowerPower business authorizationWorkspace does not own all Power resource access
City PowerDeclared per actionAnswers runtime facts and runs declared read actions; write actions consume quota or write files under the Agent's directory
Custom ToolRegistering hostAgent Core does not infer business permissions

Attachments always provide paths and metadata. Static PNG, JPEG, and WebP confirmed from file headers can also be included automatically within a 2 MiB per-image limit, a 4 MiB total for all request media, and the remaining model input budget. Recent images take priority with output order preserved, using the same rules for current and historical messages. PDFs and other files require explicit read; images omitted for budget retain their references. Attachment read authorization comes from registration and actual ownership by the current Session. An absolute path alone grants no access to private files of other Sessions or Agents; project files continue to follow Workspace path policy.

Cross-platform strategy

Node.js already normalizes files, paths, networking, JSON, timers, AbortController, and basic child processes. Agent, Session, Store, and Workspace therefore contain no operating-system branches.

Isolation differences are contained by the neutral Sandbox Provider protocol. Each Shell receives its Provider explicitly and owns the isolated, persistent Sandbox created when it binds a Workspace. City only manages Workspace resources and does not know whether their Shell uses a local container, microVM, remote host, or another backend. The default implementation uses microsandbox microVMs.

Lifecycle

Sessions wait for the Agent's City execution binding before execution. agent.dispose() does not stop City Power instances. city.close() closes Transports, Agents, Powers, Workspaces, and Shells after active Hook/Action leases finish.

Continue with Agent Lifecycle.