Silo

Interface: AgentSessionHandle ​

Defined in: packages/sdk/src/agents-service.ts:1013

Beta

A live handle to one Chat session (RFC 0038) — an Agent Client Protocol child Silo spawned from a user-authored Chat profile, speaking structured JSON-RPC over piped stdio. Returned by AgentSessionsService.connect.

The same session shows up in AgentsService.getState as an AgentInfo with kind: "chat" and this handle's id — so the Agents navigator, attention badges and status all work for it exactly as for a Terminal session, with no extra wiring.

Drive one turn at a time: call prompt, await its AgentPromptResult, then prompt again.

Properties ​

id ​

ts
readonly id: string;

Defined in: packages/sdk/src/agents-service.ts:1019

Beta

This session's AgentInfo.id — the key AgentsService.reveal, AgentsService.resume and AgentsService.acknowledge take. Stable across a AgentsService.resume.

sessionId ​

ts
readonly sessionId: string;

Defined in: packages/sdk/src/agents-service.ts:1029

Beta

The agent's own session id (session/new's sessionId, or the fresh id session/load adopted) — what to pass back as AgentSessionRestore.sessionId on a future AgentSessionsService.connect to restore this conversation (RFC 0042). Distinct from AgentSessionHandle.id, which is namespaced for ctx.agents and does not change even when this does (an adopted id after session/load).

agentId? ​

ts
readonly optional agentId?: string;

Defined in: packages/sdk/src/agents-service.ts:1032

Beta

The user's asserted catalog agent id for the profile, if any — the same value that selects the profile's +-menu icon.

agentName ​

ts
readonly agentName: string;

Defined in: packages/sdk/src/agents-service.ts:1035

Beta

Display name for the agent: what it declared at connect (initialize), falling back to the profile label when it declared none (recon Finding 4).

canResume ​

ts
readonly canResume: boolean;

Defined in: packages/sdk/src/agents-service.ts:1041

Beta

Whether the agent advertises session/resume or session/load, i.e. whether AgentsService.resume can bring this conversation back after the process dies. Mirrors AgentInfo.canResume.

resumeOutcome ​

ts
readonly resumeOutcome: "resumed" | "journal-only" | "new";

Defined in: packages/sdk/src/agents-service.ts:1056

Beta

How this handle came to be connected (RFC 0042) — see AgentSessionRestore:

  • "new" — an ordinary session/new (no AgentSessionConnectOptions.resume was given, or the persisted session had gone stale and connect() fell through to a fresh one).
  • "resumed" — a persisted session reconnected, via session/resume or session/load.
  • "journal-only" — the agent could do neither. There is no live session: prompt rejects. Reconnect with resume: { sessionId, startFresh: true } to continue in a new one, preserving journal for continuity.

journal ​

ts
readonly journal: readonly AgentSessionUpdate[];

Defined in: packages/sdk/src/agents-service.ts:1066

Beta

Prior turns to paint before subscribing to onUpdate — the transcript journal (RFC 0042), read from disk. Empty when resumeOutcome is "new" and nothing preceded this connection; populated for "resumed" (a session/resume reconnect, which itself replays nothing — this is the only record) and "journal-only". Feed these through the same reducer as onUpdate before subscribing to it, e.g. journal.reduce(applyUpdate, emptyTranscript).

configOptions ​

ts
readonly configOptions: readonly AgentSessionConfigOption[];

Defined in: packages/sdk/src/agents-service.ts:1106

Beta

The session-level controls the agent advertised at connect — mode, model, and whatever else it offers, each a self-describing AgentSessionConfigOption. Empty when it advertised none.

This is a live snapshot: setConfigOption and a mode the agent changes itself both update it in place. Subscribe with onConfigOptionsChanged and re-read.

commands ​

ts
readonly commands: readonly AgentCommand[];

Defined in: packages/sdk/src/agents-service.ts:1147

Beta

The commands the agent advertises, live — a / palette's data source (RFC 0040). Empty until the agent's first available_commands_update: both agents probed send one at connect, before any prompt, but nothing in the protocol requires it, and pi took ~12.5s to get there (behind its startup banner) — connect() does not wait for it. Subscribe with onCommandsChanged and re-read.

There is no runCommand(). Invoke one the same way you'd send anything else: prompt([{ type: "text", text: "/" + command.name }]).

promptCapabilities ​

ts
readonly promptCapabilities: AgentPromptCapabilities;

Defined in: packages/sdk/src/agents-service.ts:1156

Beta

What this session accepts as prompt content, read once from initialize and fixed for its life (RFC 0040) — unlike commands, this never changes, so there is no change event for it.

Methods ​

prompt() ​

ts
prompt(blocks): Promise<AgentPromptResult>;

Defined in: packages/sdk/src/agents-service.ts:1074

Beta

Send a prompt turn and resolve when it ends. Content is structured blocks, never a shell string. Rejects if the turn cannot be completed (connection lost, agent error) — with the agent's message where it gave one. Also rejects immediately when resumeOutcome is "journal-only" — there is no live agent to prompt.

Parameters ​

blocks ​

readonly AgentPromptBlock[]

Returns ​

Promise<AgentPromptResult>

cancel() ​

ts
cancel(): void;

Defined in: packages/sdk/src/agents-service.ts:1080

Beta

Ask the agent to stop the current turn (Agent Client Protocol session/cancel). The in-flight prompt promise then resolves with stopReason: "cancelled" rather than rejecting.

Returns ​

void

onUpdate() ​

ts
onUpdate(listener): Disposable;

Defined in: packages/sdk/src/agents-service.ts:1090

Beta

Subscribe to the turn's AgentSessionUpdate stream — streaming text, tool calls, plans. Not confined to between prompt and its resolution: some agents send one at connect, before any prompt at all (pi's own startup banner arrives as an agent_message_chunk — recon 2026-09-09), and a replay of prior turns can follow AgentsService.resume. Subscribe before assuming nothing will arrive yet. Returns a Disposable.

Parameters ​

listener ​

(update) => void

Returns ​

Disposable

onPermission() ​

ts
onPermission(listener): Disposable;

Defined in: packages/sdk/src/agents-service.ts:1096

Beta

Subscribe to AgentPermissionRequests. Returns a Disposable. With at least one listener registered, answering is your responsibility; with none, Silo answers cancelled.

Parameters ​

listener ​

(request) => void

Returns ​

Disposable

setConfigOption() ​

ts
setConfigOption(id, value): Promise<void>;

Defined in: packages/sdk/src/agents-service.ts:1128

Beta

Change one advertised control. id names an entry in configOptions; value is one of that entry's AgentSessionConfigChoice.values.

Works for any category the agent advertises, including ones Silo has never heard of — the host writes through the protocol's generic session/set_config_option, falling back to the typed session/set_mode / session/set_model only for an agent that does not implement it.

Rejects, with nothing written, on an unknown id or a value outside that entry's options — and with the agent's own message when the agent refuses (an adapter may advertise an entry its own handler does not know). A rejection is a signal to stop offering that control.

Resolves once the agent has acknowledged the change. configOptions is then replaced from the agent's own updated list — setting one option can move another — and onConfigOptionsChanged fires just before it resolves.

Parameters ​

id ​

string

value ​

string

Returns ​

Promise<void>

onConfigOptionsChanged() ​

ts
onConfigOptionsChanged(listener): Disposable;

Defined in: packages/sdk/src/agents-service.ts:1135

Beta

Fires whenever configOptions changes — a setConfigOption landing, or the agent moving a value on its own (an ACP current_mode_update). Re-read configOptions from the handle. Returns a Disposable.

Parameters ​

listener ​

() => void

Returns ​

Disposable

onCommandsChanged() ​

ts
onCommandsChanged(listener): Disposable;

Defined in: packages/sdk/src/agents-service.ts:1150

Beta

Fires whenever commands is replaced. Returns a Disposable.

Parameters ​

listener ​

() => void

Returns ​

Disposable

dispose() ​

ts
dispose(): void;

Defined in: packages/sdk/src/agents-service.ts:1163

Beta

Tear the session down: kill the agent process and drop it from AgentsService.getState. Idempotent. The process is a piped child of Silo — it does not survive this, and closing the workspace or quitting the app reaps it the same way.

Returns ​

void