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:
- The canonical input is persisted before the model call: a User Message for a person, an Agent input Part for runtime input.
- Streaming Assistant output is first written as a recoverable draft.
- Text, Reasoning, Tool Calls, and Tool Results preserve canonical model-stream order.
- Complete model Steps and Tool state changes commit to canonical history.
- 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 modelAgent 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_snapshotstores explicitly persisted base system text.messagesandmessage_partsstore 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" } }| Power | Action groups | Answers |
|---|---|---|
context | env, sandbox, workspaces, usage | Which 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 |
ai | image, sound | Generate images; transcribe audio and synthesize speech |
agent | agent | Every 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 .
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:
| Capability | Enforced boundary | Permission semantics |
|---|---|---|
| File/Search Tools | Project path policy and Session read-only attachment capability | Project files follow Workspace policy; read can also access attachments registered as owned by the current Session, without expanding write / edit / grep / find access |
| Sandbox Shell | Workspace Sandbox | Commands run in the Workspace's isolated, persistent environment |
| Host Shell | Approval gateway | The user explicitly authorizes one host command with a recorded reason |
| Power | Power business authorization | Workspace does not own all Power resource access |
| City Power | Declared per action | Answers runtime facts and runs declared read actions; write actions consume quota or write files under the Agent's directory |
| Custom Tool | Registering host | Agent 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.