SDK Surface

The @downcity/agent root exports the complete extension surface, but ordinary applications do not need every export. Start with the everyday core, then enter the Session, Plugin, or transport integration layer only when required.

Layer 1: everyday core

Most local applications need only:

• Workspace: create the project resource and security boundary and receive Shell.
• Agent: compose the model, instructions, Tools, plugins, and enter Workspaces.
• agent.sessions.create({ workspace }) / get(): create or restore a Session in the current scope.
• session.prompt(): start one Turn.
• turn.finished: await the final result.
• agent.dispose(): release every Workspace scope entered by the Agent.

const workspace = new Workspace({ id: workspace_id, path, shell });
const agent = new Agent({ id, model });
// Session 在创建时选择 Workspace。

try {
  const session = await agent.sessions.create({ workspace });
  const turn = await session.prompt({ query: "Inspect the project" });
  const result = await turn.finished;
} finally {
  await agent.dispose();
}

The local SDK is session-first: Agent performs composition, while Session owns interaction and execution state.

Layer 2: common advanced APIs

Agent and Workspace

• Agent construction starts Plugin runtime; Session execution waits for initialization internally.
• agent.set_instruction(): update static Agent instructions.
• agent.plugins: inspect, control, or call plugins.
• workspace.get_env() / set_env() / patch_env(): manage the project execution environment.
• agent.get_logger() / get_shell(): host integration entry points.

Session

• get_info(): read Session state.
• subscribe(): subscribe to live Mutations.
• messages(): load message snapshots.
• stop(): stop the current execution.
• system(): load the current system.
• interactions() / respond(): handle approvals, questions, and other user interactions.
• fork(): branch from an existing Session.
• snapshot() / syncshot(): manage local Session system snapshots.
• set({ model }): override the model for one local Session.

For a live UI, load initial Session and Message snapshots before calling subscribe(). Reload snapshots after reconnecting; the event stream is not a complete database.

Layer 3: framework integration

Use these capabilities only when building plugins, servers, or custom runtime components:

• PluginContext: the stable capability view projected from Agent to a Plugin; hosts should not acquire or retain it.
• SessionTurnContext: the execution context that coordinates identity, lifecycle, steps, input, and output for one Turn; plugins receive only its read-only PluginExecutionContext projection.
• create_session_turn_context(...): the standard factory used by custom executors or runtime components to create that Turn Context.
• Interfaces such as AgentSession and SessionExecutor: replace or extend default implementations.
• RPC/HTTP types: implement a custom transport or protocol integration.

Network server implementations belong to @downcity/agent. Local Agent does not listen on ports or manage transport lifecycle.

Local and remote

The server host always owns the model and system persistence policy for a remote Session.

Lifecycle rules

one Agent → multiple `agent.sessions.create({ workspace })` Sessions → one agent.dispose()

• Agent is not bound to one Workspace; one Agent can enter multiple Workspaces.
• Each AgentWorkspace owns an Agent-filtered Session view, Shell, and Plugin context; entries for the same Workspace share one internal data root.
• agent.dispose() releases every AgentWorkspace, Plugin runtime, Shell, PTYs, and Sandbox.
• RemoteAgent.close() closes only the client connection, not the server-side Agent.

Continue with the Agent API and Sessions overview.