Snowpea protocol

• Protocol version: 1.25.0 (semver)
• Source of truth: core/snowpea_core/server/protocol.py
• Generator: uv run python scripts/gen_protocol.py
• Bindings: sdk/src/protocol.ts (generated alongside this file — never hand-edit)

Transport

The daemon listens on a loopback-only port chosen at start-up and records it in $SNOWPEA_HOME/daemon.json as {port, pid, token, startedAt, protocolVersion}.

surface	endpoint	purpose
WebSocket	ws://127.0.0.1:<port>/ws	JSON-RPC 2.0, bidirectional
HTTP GET	http://127.0.0.1:<port>/health	liveness probe
HTTP GET	http://127.0.0.1:<port>/protocol.json	this schema as JSON
HTTP GET	http://127.0.0.1:<port>/version	server and protocol versions

Every state-changing method lives on the WebSocket only; the HTTP endpoints are read-only operational helpers.

Handshake

Immediately after connecting, the client calls system.hello with the daemon token, its own clientVersion, and the protocolVersion it was built against. Any other method before a successful system.hello fails with unauthorized. A mismatched major version is rejected with protocol_incompatible.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "system.hello",
  "params": {
    "token": "<contents of $SNOWPEA_HOME/token>",
    "clientVersion": "0.1.0",
    "protocolVersion": "1.25.0"
  }
}

Server capabilities advertised in the system.hello result:

• approvals
• audio
• batchedFileTools
• checkpoints
• commands
• hostToolParallel
• hostTools
• llmSample
• llmTimings
• lsp
• mcp
• onceOnlyScope
• pageActionAlways
• providerModelsError
• readOnlyDelegation
• sessionAttachments
• sessionContinue
• sessionSetAgent
• sessions
• setAgentGuardTurn
• settings
• setup
• siteFrameActions
• siteMemory
• siteRecipes
• snapshotSupersede
• standingOrders
• tabReadAlways
• toolInvokeGuard
• tools
• update
• webSearch

Method index

method	direction	summary
agent.bindChannel	client → server	Route a gateway channel to a named agent.
agent.create	client → server	Define a named agent from a description.
agent.delete	client → server	Delete a named agent.
agent.list	client → server	List the named agents that are defined.
agent.spawn	client → server	Run a named agent on a task.
approval.ask	client → server	Escalate one host action through the approval pipeline. The approver's approval.request carries tool, args with detail nested under args.detail and the site under args.site, note = reason, site, and scopeHint 'site' when a site is known. A local dev server navigation (tool 'repl.navigate', args.reasonCode 'localDevServer', args.url, args.project) gets scopeHint 'project': a 'project' answer stores a rule for the session's project and the URL's origin that only such asks match.
approval.list	client → server	List tool calls still waiting for a decision.
approval.request	server → client	Ask the client to approve a tool call.
approval.respond	client → server	Answer a pending approval and unblock the turn.
audio.capabilities	client → server	Report what voice input and output can do on this machine.
audio.install	client → server	Install a local voice engine (or one of its voices) and re-run detection.
audio.record.start	client → server	Start recording the microphone.
audio.record.stop	client → server	Stop the recording and return the wav it wrote.
audio.speak	client → server	Synthesise speech, optionally playing it on the daemon's machine.
audio.transcribe	client → server	Transcribe recorded audio to text.
audio.voices	client → server	List the voices one speech engine offers here.
backend.set	client → server	Choose where a session's tools execute: local, docker or ssh.
checkpoint.delete	client → server	Delete one checkpoint, or all checkpoints for a session.
checkpoint.diff	client → server	Show what restoring a checkpoint would change from the current workdir.
checkpoint.list	client → server	List restore checkpoints for a session, newest first.
checkpoint.restore	client → server	Restore files to their before-turn state, optionally through later turns.
command.list	client → server	List the slash commands available to a session.
command.run	client → server	Run a slash command; the only execution path for them.
file.complete	client → server	Complete file and directory paths under a session workdir.
gateway.bind	client → server	Attach the daemon to a chat platform channel.
gateway.list	client → server	List live gateway bindings.
gateway.sync	client → server	Reconcile the messenger bindings with settings.gateway.
gateway.unbind	client → server	Detach a gateway binding.
job.cancel	client → server	Cancel a scheduled job.
job.delete	client → server	Delete a job, its schedule and run history; optionally its run sessions.
job.list	client → server	List scheduled jobs and their next run times.
job.nextRunForClient	client → server	When a host should be awake for its routines (addendum 11).
job.preview	client → server	Read a schedule spec without saving anything (1.10.0): its kind and when a job with it would first fire. An unreadable spec is invalid_params with job.schedule's message.
job.runNow	client → server	Fire a scheduled job immediately.
job.schedule	client → server	Schedule a prompt to run unattended.
job.update	client → server	Change an existing job (addendum 12).
llm.sample	client → server	One tool-less model call for a session's browser host (1.14.0): no tools, no history, nothing written to the transcript except a usage event. The session's host only ('unauthorized' otherwise); 'unavailable' when no model can answer; with schema, 'invalid_output' when the answer does not validate.
lsp.catalog	client → server	List every registered language server, regardless of whether it has started.
lsp.status	client → server	Report every language server the daemon has started and its state.
mcp.add	client → server	Write an MCP server into the project or global .mcp.json and start it.
mcp.catalog	client → server	The curated MCP servers a client can offer as presets.
mcp.list	client → server	List every configured MCP server with its scope, state and tools.
mcp.reload	client → server	Restart one MCP server, or every configured one.
mcp.remove	client → server	Delete an MCP server entry and stop the server.
mcp.test	client → server	Probe a saved MCP server or an unsaved draft and report its tools.
mcp.update	client → server	Merge a patch into an existing MCP server entry.
memory.delete	client → server	Forget one stored memory.
memory.ingest	client → server	Remember visited pages in the browser namespace, once per url and text.
memory.list	client → server	List stored memories by scope, newest first.
memory.search	client → server	Recall stored memories matching a query.
memory.write	client → server	Store a memory with tags.
permission.allowlist.add	client → server	Promote a pattern from ask to allow.
permission.allowlist.list	client → server	List stored allowlist patterns.
permission.allowlist.remove	client → server	Delete an allowlist pattern by id.
provider.configure	client → server	Store settings and credentials for a provider.
provider.list	client → server	List chat providers and whether they are configured.
provider.loginWeb	client → server	Start a browser-based login flow for a provider.
provider.models	client → server	Ask a vendor's endpoint which models it serves.
provider.remove	client → server	Forget a configured provider, typically a named local server.
provider.test	client → server	Send one short completion to check a provider and model.
question.list	client → server	List questions the agent is still waiting on.
question.request	server → client	Ask the client to put a question to the human.
question.respond	client → server	Answer a pending question and unblock the turn.
session.artifacts	client → server	Files the session saved for the user under its workspace's artifacts/.
session.attach	client → server	Make this connection the origin of a session (approvals, host tools).
session.attachments	client → server	Files the user attached in this session, with the path of the original bytes the agent may use (1.23.0). A delegated child reports its root's.
session.close	client → server	Close a session and release its resources.
session.compact	client → server	Summarise the conversation so far and replace the history with it.
session.continue	client → server	Continue a chat session on the system's behalf, e.g. after a human hand-back (1.8.0). A running turn gets the note at its next model call (like session.notice); otherwise a turn starts whose input is the [system] note, with turn.started initiator 'system' and no message.user. Same callers as session.setAgent; subagent and scheduled sessions are refused with 'invalid_params'. One system start per session per 10 s, and an idempotencyKey is honoured once; a call inside the 10 s window keeps its note as a notice (queued: true).
session.create	client → server	Open a session rooted at a working directory.
session.deleteSaved	client → server	Delete saved sessions.
session.interrupt	client → server	Stop the running turn as soon as possible.
session.list	client → server	List live or saved sessions.
session.notice	client → server	Queue a [system] line for the model's next call.
session.prompt	client → server	Send user text to a session and start a turn. Events: turn.started {turnId, prompt, queued}, then message.user {text, attachments, refs, steered: false}, then the model's output. message.user.text is what the user typed; a page attachment is listed as {kind: page, name, url, title} and only the model sees the rendered page. A steered prompt emits message.user {steered: true} + turn.dequeued {reason: steered}; a queued one emits turn.queued first.
session.rename	client → server	Set a session's title.
session.resume	client → server	Replay the events a disconnected client missed.
session.setActive	client → server	Mark the session the user is looking at as the active one: a messenger with gateway.<platform>.shareActive posts its questions and approvals to the owner's chat. session.prompt and session.steer from a client do the same. Subagent and scheduled sessions are refused with 'invalid_params'.
session.setAgent	client → server	Run a session as an agent definition, or as none (addendum 17). Only the session's origin connection, a browser session's hostToolsFrom host, or a non-browser surface (for a session it originated or that is not a browser session) may call it; others get 'unauthorized'.
session.setBrowserProvider	client → server	Per-session opt-in to core's own browser; never global (addendum 9).
session.setEffort	client → server	Pin how hard a session's model may think, or clear the pin.
session.setMode	client → server	Switch a session between plan, accept and auto.
session.setModel	client → server	Pin a session to a model profile, or clear the pin.
session.steer	client → server	Inject a user message into a running turn at its next tool round.
session.toolContent	client → server	A host tool result's content blocks with image bytes; results with images are kept on disk.
settings.get	client → server	Read global or project settings, with secrets masked.
settings.set	client → server	Deep-merge a patch into global or project settings and persist it.
setup.applyDefaults	client → server	Apply the profile's defaults for everything optional; idempotent.
setup.catalog	client → server	The setup wizard's vendor, search, browser, tools and gateway catalogs.
setup.status	client → server	What setup still needs; for the browser profile only a tested provider is required.
site.delete	client → server	Site memory (1.9.0): delete one entry, or every entry of an origin, in one browser profile. Same callers as site.list.
site.get	client → server	Site memory (1.9.0): the entries stored for an origin in the caller's browser profile; with path, only those whose urlPattern matches it, most specific first; with pageType, only that one. Stale entries are included, flagged. Browser host clients only; entries are untrusted page-derived data and core never puts them in a prompt.
site.list	client → server	Site memory (1.9.0): one browser profile's remembered sites, by origin, for a settings UI. A browser client sees its own profile; any other owner client names one with hostToolsFrom.
site.mark	client → server	Site memory (1.9.0): 'ok' counts a success, sets lastVerified and clears stale; 'stale' counts a failure and flags the entry until the next put. Browser host clients only.
site.markPart	client → server	Site memory (1.15.0): count one use of a flow or recipe of an entry without a put. The entry's successCount, failureCount, stale and lastVerified are untouched, so this never counts as verification. 'not_found' for an unknown entry, flow or recipe. Browser host clients only.
site.put	client → server	Site memory (1.9.0): upsert an entry by (origin, pageType). Core checks the schema, refuses XPath, values on login fields and strings that look like personal data or credentials, and enforces 24 KB per entry (16 KB before 1.15.0) and 30 entries per origin ('invalid_params' naming the field); past 1,000 origins the least recently verified origin is dropped. A put clears stale and counts as a success. Browser host clients only.
skill.create	client → server	Write a new SKILL.md, generated from a brief or supplied verbatim.
skill.install	client → server	Install a skill from a path, URL or registry.
skill.list	client → server	List installed skills.
skill.read	client → server	Read a skill's SKILL.md.
skill.reload	client → server	Reload skills from disk without restarting.
skill.remove	client → server	Delete an installed skill or plugin.
skill.search	client → server	Search available skills.
skill.write	client → server	Save a skill's SKILL.md verbatim.
system.checkUpdate	client → server	Report whether a newer snowpea release exists; cached for 24h.
system.health	client → server	Liveness probe; answers as long as the daemon serves requests.
system.hello	client → server	Authenticate a connection and agree on the protocol version.
system.info	client → server	Report the daemon's version, pid, port, start time and home.
system.reloadSettings	client → server	Re-read settings.json and rebind the daemon's in-memory state.
system.restart	client → server	Shut the daemon down so the next launch runs the newly installed version.
system.shutdown	client → server	Ask the daemon to shut down gracefully.
system.update	client → server	Upgrade snowpea in a detached subprocess and report progress.
team.guide.delete	client → server	Delete a team guide from the project or global home.
team.guide.get	client → server	Read a team guide for a project or session.
team.guide.list	client → server	List every team guide visible in a project.
team.guide.set	client → server	Write a team guide to the project or global home.
team.start	client → server	Split a task across parallel workers.
team.status	client → server	Inspect a team's task board.
tool.invoke	server → client	Ask the client to run one of its host tools.
tool.list	client → server	List the tools registered for a session.
tool.progress	client → server	Notification: progress of a running tool.invoke, re-emitted as tool.progress.
tool.register	client → server	Register tools this connection runs itself (host tools).
tool.unregister	client → server	Remove some of this connection's host tools.
usage.summary	client → server	Token totals from stored usage events, grouped by provider, model, session or day.
web.search	client → server	Web search for a browser host (1.11.0): the web_search tool's provider chain, settings, caps and timeouts, for the host's own fallback when its search page is blocked. Browser host clients (with a clientId) only; 'unavailable' with details.reason when no provider can answer. Results are untrusted web content.

Methods

agent.bindChannel

Direction: client → server

Route a gateway channel to a named agent.

Params

field	type	required	description
channel	string	yes	Gateway channel that will reach the agent.
credentialsRef	string | null	no	Credential entry the platform account uses; defaults to the platform name, e.g. 'telegram' for channel 'telegram:123'.
name	string	yes	Agent to bind.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

agent.create

Direction: client → server

Define a named agent from a description.

Params

field	type	required	description
description	string	yes	Natural-language brief the daemon turns into an agent.
name	string | null	no	Name for the agent; when omitted the daemon takes the generated one.
named	boolean	no	Also register a persistent named instance: its own session, the memory namespace agent:<name>, and rows that survive a daemon restart.

Result

field	type	required	description
name	string	yes	Name assigned to the new agent.
path	string | null	no	Where the definition was written.

agent.delete

Direction: client → server

Delete a named agent.

Params

field	type	required	description
name	string	yes	Agent to delete.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

agent.list

Direction: client → server

List the named agents that are defined.

Params

No params (send {}).

Result

field	type	required	description
agents	({ active?: boolean | null; agentId?: string | null; agents?: string[]; bindings?: string[]; channel?: string | null; channels?: string[]; description?: string; hasGuide?: boolean | null; jobs?: string[]; kind?: string; name: string; namespace?: string | null; parentSessionId?: string | null; path?: string | null; sessionId?: string | null; source?: string; stages?: Record<string, string>; status?: string | null; task?: string | null; })[]	no	Defined named agents.

agent.spawn

Direction: client → server

Run a named agent on a task.

Params

field	type	required	description
model	string | null	no	Run this one spawn on a specific model: a models.profiles id, a 'vendor:model' pair, or a bare vendor. Outranks the agent's own assignment; null uses the configured routing.
name	string	yes	Agent to run.
sessionId	string | null	no	Parent session, when spawned from one.
task	string	yes	Task handed to the agent.

Result

field	type	required	description
agentId	string	yes	Id correlating the subagent.* events.

approval.ask

Direction: client → server

Escalate one host action through the approval pipeline. The approver's approval.request carries tool, args with detail nested under args.detail and the site under args.site, note = reason, site, and scopeHint 'site' when a site is known. A local dev server navigation (tool 'repl.navigate', args.reasonCode 'localDevServer', args.url, args.project) gets scopeHint 'project': a 'project' answer stores a rule for the session's project and the URL's origin that only such asks match.

Params

field	type	required	description
args	Record<string, unknown>	no	Action details to show.
callId	string | null	no	The tool.invoke callId, if any.
detail	Record<string, unknown> | null	no	What the running code is about to do, e.g. {origin, element, action}; shown with the approval and merged into its args.
forceAsk	boolean	no	Always ask a person: the mode matrix may only deny (plan still denies write, send and config; a read is asked) and never auto-allows, not even in auto mode. The allowlist still applies unless risk is 'payment'. For any client's destructive or irreversible actions.
permission	"read" | "write" | "exec" | "network" | "send" | "config" | "delegate" | "secret"	yes	Permission class of the escalated action.
reason	string	yes	What will happen, shown to the person approving.
risk	string | null	no	Risk hint shown with the approval; default from the permission. 'payment' also means: the allowlist is never consulted and the answer is never stored beyond this one call (scope is coerced to 'once').
sessionId	string	yes	Session whose tool call is running.
site	string | null	no	Origin of the page, e.g. https://github.com; derived from detail.origin or args.url if omitted.
tool	string	yes	Host tool asking; the allowlist is keyed by it.

Result

field	type	required	description
by	string	no	Who decided: 'user' (a person answered), 'allowlist', 'mode' (the mode matrix), 'readOnly' (a read-only delegation refuses changes and never asks; 1.14.0), or 'timeout' / 'interrupted' (denied without an answer).
decision	"allow" | "deny"	yes	allow or deny.
scope	"once" | "session" | "project" | "always" | "site"	no	Scope the answer applies to; always 'once' for payment. 'project' only for project-safe actions (repl.files, a localDevServer repl.navigate); 'always' for a page action only for repl.tabs, repl.clipboard and (1.13.0) repl.read and repl.attach, others are kept to 'once'. For args.onceOnly (1.12.0) the scope the person picked, which core never stores: the host may keep it on its side.

approval.list

Direction: client → server

List tool calls still waiting for a decision.

Params

field	type	required	description
sessionId	string | null	no	Scope the listing to one session; omit for the global set.

Result

field	type	required	description
requests	({ args?: Record<string, unknown>; guard?: string | null; note?: string; requestId: string; risk?: string; scopeHint?: "once" | "session" | "project" | "always" | "site"; sessionId: string; site?: string | null; timeoutSec?: number; tool: string; })[]	no	Approvals still pending.

approval.request

Direction: server → client

Ask the client to approve a tool call.

Params

field	type	required	description
args	Record<string, unknown>	no	Arguments it wants to use.
guard	string | null	no	Why this is asked whatever the mode (1.24.0): 'agent-switch' for a call in the rest of a turn session.setAgent {guardTurn} guarded. Such an answer is never remembered.
note	string	no	Extra warning shown with the prompt, e.g. "modifies snowpea configuration".
requestId	string	yes	Id to answer with approval.respond.
risk	string	no	Risk hint for the UI.
scopeHint	"once" | "session" | "project" | "always" | "site"	no	Scope the UI should preselect.
sessionId	string	yes	Session whose turn is blocked.
site	string | null	no	Origin (scheme://host) a 'site' scope would store the answer for (1.6.0).
timeoutSec	number	no	Seconds before the request auto-denies.
tool	string	yes	Tool the model wants to run.

Result

field	type	required	description
decision	"allow" | "deny"	yes	The human's decision.
reason	string	no	Why the human refused; quoted back to the model as the tool's refusal so the next turn can answer it (M15b §1).
scope	"once" | "session" | "project" | "always" | "site"	no	How long the decision applies.

approval.respond

Direction: client → server

Answer a pending approval and unblock the turn.

Params

field	type	required	description
decision	"allow" | "deny"	yes	allow runs the tool, deny ends the turn.
reason	string	no	Why the human refused; quoted back to the model as the tool's refusal so the next turn can answer it (M15b §1).
requestId	string	yes	Request being answered.
scope	"once" | "session" | "project" | "always" | "site"	no	How long the decision applies.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

audio.capabilities

Direction: client → server

Report what voice input and output can do on this machine.

Params

No params (send {}).

Result

field	type	required	description
autoSpeak	boolean	no	True when replies are spoken without being asked.
play	boolean	no	True when the daemon can play audio itself.
players	string[]	no	Audio players found on PATH.
reasons	Record<string, string>	no	Per-capability explanation of why it is off.
record	boolean	no	True when the microphone can be recorded.
recorders	string[]	no	Recorders found on PATH.
stt	string | null	no	Transcription backend in use, or null when there is none.
sttEffective	string | null	no	The engine actually in use, or null when none is pinned or it is missing.
sttLanguage	string	no	'auto' (the engine detects, or the reply language decides) or the BCP-47 tag audio.stt.language forces.
sttLanguageSource	string	no	Which rung decided it: setting | reply | detect. 'detect' means the engine works it out itself and nothing had to choose.
sttPinned	boolean	no	True when audio.stt.provider names an engine. False means unset, which means voice input is off: there is no fallback chain.
sttProviders	string[]	no	Every usable transcription backend, preferred first.
tts	boolean	no	True when speech synthesis is available.
ttsEffective	string | null	no	The speech engine actually in use, or null.
ttsPinned	boolean	no	True when audio.tts.provider names an engine.
ttsProvider	string | null	no	Speech backend in use.
ttsProviders	string[]	no	Every usable speech backend, preferred first.
voice	string | null	no	Configured voice, when one is set.

audio.install

Direction: client → server

Install a local voice engine (or one of its voices) and re-run detection.

Params

field	type	required	description
engine	string	yes	Engine id from the setup catalog: faster-whisper (or local-whisper), piper, edge-tts. A system package (espeak-ng, say, powershell) answers ok=false with a hint instead.
voice	string | null	no	Install one of the engine's voices rather than the engine itself, e.g. piper's ko_KR-kss-medium. Same staged progress; installing a voice does not select it.
warmup	boolean	no	When true, download first-run assets only — Supertonic's ONNX models — with staged progress, without reinstalling the package.

Result

field	type	required	description
engine	string	yes	Engine that was attempted, after id normalisation.
hint	string | null	no	What to do instead, when ok is false: the platform's own install command for a system package, or why the attempt could not run.
log	string	no	Tail of the installer's combined output, newest last; may be empty.
ok	boolean	yes	True when the engine is installed and now detected.
voice	string | null	no	The voice that was installed, when the request named one.

audio.record.start

Direction: client → server

Start recording the microphone.

Params

field	type	required	description
sessionId	string | null	no	Session the recording belongs to.

Result

field	type	required	description
mime	string	no	Media type of the recording.
path	string	yes	Wav file being written, or the finished recording.
provider	string | null	no	Backend that transcribed it.
recording	boolean	yes	True while capture is still running.
text	string | null	no	Transcript, when 'stop' was asked to transcribe.

audio.record.stop

Direction: client → server

Stop the recording and return the wav it wrote.

Params

field	type	required	description
sessionId	string | null	no	Session that is recording.
transcribe	boolean	no	Also transcribe the recording and return its text.

Result

field	type	required	description
mime	string	no	Media type of the recording.
path	string	yes	Wav file being written, or the finished recording.
provider	string | null	no	Backend that transcribed it.
recording	boolean	yes	True while capture is still running.
text	string | null	no	Transcript, when 'stop' was asked to transcribe.

audio.speak

Direction: client → server

Synthesise speech, optionally playing it on the daemon's machine.

Params

field	type	required	description
language	string | null	no	BCP-47 language for voice selection; defaults to the stt language setting.
play	boolean	no	Play on the daemon's machine instead of returning only a path.
provider	string | null	no	Speech backend to use for this call only. When set, the pinned voice-out engine is not required — settings screens use this to preview before saving.
sessionId	string | null	no	Session the audio belongs to.
text	string	yes	What to say.
voice	string | null	no	Voice id; defaults to the setting.

Result

field	type	required	description
mime	string	yes	Media type of that file.
path	string	yes	Audio file the speech was written to.
played	boolean	no	True when the daemon played it.
provider	string	yes	Backend that synthesised it.
voice	string | null	no	Voice that was used.

audio.transcribe

Direction: client → server

Transcribe recorded audio to text.

Params

field	type	required	description
data	string | null	no	Base64 (or data-URI) audio.
language	string | null	no	BCP-47 hint for the backend.
mime	string | null	no	Media type of the audio, e.g. audio/wav.
path	string | null	no	Audio file on the daemon's machine.
sessionId	string | null	no	Session the audio belongs to.

Result

field	type	required	description
provider	string	yes	Backend that produced the transcript.
text	string	yes	What the backend heard.

audio.voices

Direction: client → server

List the voices one speech engine offers here.

Params

field	type	required	description
engine	string	yes	Engine id, e.g. supertonic, piper, edge-tts.
languages	string[]	no	Filter a large catalogue to these BCP-47 tags; empty uses ko and en plus the session's reply language. Ignored by engines with few voices.

Result

field	type	required	description
voices	({ gender?: string | null; id: string; installed?: boolean; label: string; language?: string; sample?: boolean; sizeBytes?: number | null; })[]	no	Installed voices first, then by language and id.

backend.set

Direction: client → server

Choose where a session's tools execute: local, docker or ssh.

Params

field	type	required	description
config	Record<string, unknown>	no	Backend settings, e.g. container or SSH target.
kind	"local" | "docker" | "ssh"	yes	Where tools execute.
sessionId	string	yes	Session whose execution backend changes.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

checkpoint.delete

Direction: client → server

Delete one checkpoint, or all checkpoints for a session.

Params

field	type	required	description
id	string | null	no	Checkpoint to delete; omitted deletes the whole session set.
sessionId	string	yes	Session whose checkpoints are deleted.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

checkpoint.diff

Direction: client → server

Show what restoring a checkpoint would change from the current workdir.

Params

field	type	required	description
id	string	yes	Checkpoint id.
paths	string[] | null	no	Optional subset of relative paths to diff.
sessionId	string	yes	Session whose checkpoint is inspected.
through	boolean	no	True means restore to before this turn, considering this and all later turns in the session.

Result

field	type	required	description
files	({ binary?: boolean; changedSince?: boolean; patch: string; path: string; restorable?: boolean; })[]	no	Per-file diffs.

checkpoint.list

Direction: client → server

List restore checkpoints for a session, newest first.

Params

field	type	required	description
sessionId	string	yes	Session whose checkpoints are listed.

Result

field	type	required	description
checkpoints	({ createdAt: string; files?: ({ afterSha?: string | null; beforeSha?: string | null; path: string; restorable?: boolean; size?: number; skipped?: "too_large" | "excluded" | "unreadable" | null; source: "tool" | "shell"; status: "modified" | "created" | "deleted"; })[]; id: string; kind: "turn" | "restore"; prompt?: string; sessionId: string; turnId?: string | null; workdir: string; })[]	no	Checkpoints, newest first.

checkpoint.restore

Direction: client → server

Restore files to their before-turn state, optionally through later turns.

Params

field	type	required	description
dryRun	boolean	no	Report what would happen without writing files.
force	boolean	no	Restore even when a file changed since capture.
id	string	yes	Checkpoint id.
paths	string[] | null	no	Optional subset of relative paths to diff.
sessionId	string	yes	Session whose checkpoint is inspected.
through	boolean	no	True means restore to before this turn, considering this and all later turns in the session.

Result

field	type	required	description
checkpointId	string | null	no	Restore checkpoint id, null for dry-run or no writes.
restored	string[]	no	Paths restored.
skipped	({ path: string; reason: "changed_since" | "not_restorable" | "missing_blob" | "excluded"; })[]	no	Paths that were not restored and why.

command.list

Direction: client → server

List the slash commands available to a session.

Params

field	type	required	description
sessionId	string | null	no	Scope the listing to one session; omit for the global set.

Result

field	type	required	description
commands	({ argsSchema?: Record<string, unknown>; name: string; source?: string; summary: string; })[]	no	Available slash commands.

command.run

Direction: client → server

Run a slash command; the only execution path for them.

Params

field	type	required	description
args	string	no	Raw argument string, as typed after the name.
name	string	yes	Command name without the leading slash.
sessionId	string	yes	Session to run the command in.

Result

field	type	required	description
turnId	string	yes	Id of the started turn; turn.done carries it back.

file.complete

Direction: client → server

Complete file and directory paths under a session workdir.

Params

field	type	required	description
limit	number | null	no	Maximum entries to return (default 30, max 200).
query	string	no	Partial path to match.
sessionId	string | null	no	Session whose workdir to complete in.
workdir	string | null	no	Workdir to complete in when no session is set.

Result

field	type	required	description
entries	({ kind: "file" | "dir"; path: string; size?: number | null; })[]	no	Matching paths, best first.
truncated	boolean	no	True when more matches exist than returned.

gateway.bind

Direction: client → server

Attach the daemon to a chat platform channel.

Params

field	type	required	description
channelId	string | null	no	Restrict the binding to one chat, channel or room.
credentialsRef	string	yes	Name of the credential to use: a key in credentials.json or an env var.
platform	string	yes	Chat platform key: telegram, discord or slack.
target	Record<string, unknown>	yes	What the conversation talks to: {'agent': name}, {'session': id} or {'new_session': {'workdir': path, 'mode': mode}}.
userId	string | null	no	Platform user allowed to answer approvals from chat.

Result

field	type	required	description
bindingId	string	yes	Id used to unbind later.

gateway.list

Direction: client → server

List live gateway bindings.

Params

No params (send {}).

Result

field	type	required	description
bindings	({ bindingId: string; channelId?: string | null; credentialsRef?: string; platform: string; source?: string; state?: "active" | "inactive"; target: string; userId?: string | null; })[]	no	Live gateway bindings.

gateway.sync

Direction: client → server

Reconcile the messenger bindings with settings.gateway.

Params

No params (send {}).

Result

field	type	required	description
added	string[]	no	Platforms that started listening.
kept	string[]	no	Platforms that were already listening.
removed	string[]	no	Platforms whose auto binding was dropped.

gateway.unbind

Direction: client → server

Detach a gateway binding.

Params

field	type	required	description
bindingId	string	yes	Binding to remove.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

job.cancel

Direction: client → server

Cancel a scheduled job.

Params

field	type	required	description
jobId	string	yes	Target job.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

job.delete

Direction: client → server

Delete a job, its schedule and run history; optionally its run sessions.

Params

field	type	required	description
deleteRuns	boolean	no	Also delete the sessions its runs opened, with their workspaces, as session.deleteSaved does. A run still in progress is left alone.
jobId	string	yes	Job to delete, with its schedule and run history.

Result

field	type	required	description
deletedSessions	number	no	Run sessions deleted with it.
jobId	string	yes	The deleted job.

job.list

Direction: client → server

List scheduled jobs and their next run times.

Params

No params (send {}).

Result

field	type	required	description
jobs	({ catchUpWindowMinutes?: number; channel?: string | null; createdVia?: "rpc" | "tool"; enabled?: boolean; fingerprint?: string | null; held?: { scheduledAt: string; status: "waiting_for_host" | "missed"; } | null; jobId: string; kind?: "cron" | "once" | "interval"; lastRunAt?: string | null; lastStatus?: "ok" | "error" | "denied_by_timeout" | null; meta?: Record<string, unknown> | null; mode?: "plan" | "accept" | "auto"; nextRunAt?: string | null; originSessionId?: string | null; owned?: boolean; ownerClientId?: string | null; spec: string; state?: "scheduled" | "running" | "cancelled"; task: string; })[]	no	Known jobs.

job.nextRunForClient

Direction: client → server

When a host should be awake for its routines (addendum 11).

Params

field	type	required	description
clientId	string	yes	A host's clientId (a browser profile).

Result

field	type	required	description
nextRunAt	string | null	no	Earliest run that needs this client's host: a held (waiting_for_host) occurrence or the next firing of a job whose hostToolsFrom is this clientId; null when none.

job.preview

Direction: client → server

Read a schedule spec without saving anything (1.10.0): its kind and when a job with it would first fire. An unreadable spec is invalid_params with job.schedule's message.

Params

field	type	required	description
spec	string	yes	A schedule spec, read exactly as job.schedule reads it (1.10.0).

Result

field	type	required	description
kind	"cron" | "once" | "interval"	yes	What the spec turned into.
nextRunAt	string | null	no	UTC ISO-8601 time a job with this spec would first fire if saved now. A spec that would never fire is invalid_params, as for job.schedule.
normalized	string | null	no	The parsed schedule: the cron expression for 'cron', 'every <n>s' for 'interval', 'once at <UTC ISO>' for 'once'.

job.runNow

Direction: client → server

Fire a scheduled job immediately.

Params

field	type	required	description
jobId	string	yes	Target job.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

job.schedule

Direction: client → server

Schedule a prompt to run unattended.

Params

field	type	required	description
agent	string | null	no	Named agent that runs the task.
channel	string | null	no	Gateway channel that receives the output.
meta	Record<string, unknown> | null	no	Opaque data for the host, at most 4 KB of JSON (1.23.0). Only a connection whose system.hello said clientKind 'browser' with a clientId may set it; the job is then owned by that clientId: only it may update, cancel, delete or run it now, see its meta, and no agent tool can change or cancel it.
mode	"plan" | "accept" | "auto"	no	Permission mode for the unattended run.
sessionTemplate	{ agent?: string | null; catchUpWindowMinutes?: number; hostToolsFrom?: string | null; hostWaitSec?: number; mode?: "plan" | "accept" | "auto" | null; } | null	no	Session setup for each run, incl. host tools (1.7.0).
spec	string	yes	Cron expression or natural-language schedule.
task	string	yes	Prompt run on each firing.
workdir	string | null	no	Working directory for the run; defaults to the daemon's home.

Result

field	type	required	description
fingerprint	string | null	no	For a job with meta, the fingerprint its runs' tool.invoke job will carry (1.23.0). Seal this value; do not recompute it.
jobId	string	yes	Id of the scheduled job.
nextRunAt	string | null	no	UTC ISO-8601 time of the first firing.

job.update

Direction: client → server

Change an existing job (addendum 12).

Params

field	type	required	description
enabled	boolean | null	no	False pauses the job (no next firing); true resumes it from now on its schedule.
jobId	string	yes	Job to change.
schedule	string | null	no	A new schedule spec, parsed like job.schedule's spec; the next run is recomputed.
sessionTemplate	{ catchUpWindowMinutes?: number | null; hostWaitSec?: number | null; } | null	no	Template fields to change.

Result

field	type	required	description
catchUpWindowMinutes	number	no	How long a held run waits for its host before it is missed.
channel	string | null	no	Channel that receives the output.
createdVia	"rpc" | "tool"	no	'rpc' for job.schedule, 'tool' for schedule_create or /schedule (1.23.0).
enabled	boolean	no	False once the job is cancelled or has run out.
fingerprint	string | null	no	The fingerprint tool.invoke job carries; only the owner sees it.
held	{ scheduledAt: string; status: "waiting_for_host" | "missed"; } | null	no	The newest occurrence when it is waiting for its host or was missed (addendum 12); null otherwise.
jobId	string	yes	Job id.
kind	"cron" | "once" | "interval"	no	How the spec repeats: a cron rule, a one-shot, or a fixed interval.
lastRunAt	string | null	no	UTC ISO-8601 time of the last firing, null before the first.
lastStatus	"ok" | "error" | "denied_by_timeout" | null	no	How the last run ended.
meta	Record<string, unknown> | null	no	The job's meta; only the owner connection sees it.
mode	"plan" | "accept" | "auto"	no	Permission mode for the run.
nextRunAt	string | null	no	UTC ISO-8601 time of the next firing.
originSessionId	string | null	no	TUI/chat session that also receives every result.
owned	boolean	no	True for a job with meta: only its owner may change, run or delete it.
ownerClientId	string | null	no	The owning browser clientId; only the owner sees it.
spec	string	yes	Schedule as given.
state	"scheduled" | "running" | "cancelled"	no	Current job state.
task	string	yes	Prompt run on each firing.

llm.sample

Direction: client → server

One tool-less model call for a session's browser host (1.14.0): no tools, no history, nothing written to the transcript except a usage event. The session's host only ('unauthorized' otherwise); 'unavailable' when no model can answer; with schema, 'invalid_output' when the answer does not validate.

Params

field	type	required	description
input	string	yes	Page-derived text; sent as the user message, fenced and marked untrusted.
maxTokens	number	no	Output token cap, at most 4096.
modelCategory	"fast" | "default"	no	'fast' = browser.fastModel (then models.categories.fast, then the session's model); 'default' = the session's model.
schema	Record<string, unknown> | null	no	JSON Schema the answer must match. With it the model is told to answer JSON only, and an answer that does not validate is 'invalid_output'.
schemaAfterInput	boolean	no	Put the schema instruction after the fenced input (with task) instead of in the system message, for a schema that varies per call (1.21.0).
sessionId	string	yes	Session whose provider settings and bill this call uses; its host only.
system	string | null	no	Instructions the host wrote.
task	string | null	no	Trusted per-call instruction from the host, placed after the fenced input, so system + page stay a prefix several samples of one page share (1.21.0).

Result

field	type	required	description
json	unknown	no	The validated JSON value, when a schema was given.
model	string	yes	'vendor:model' that answered.
text	string | null	no	The answer, when no schema was given.
usage	{ inputTokens?: number; outputTokens?: number; }	yes	Tokens the call used.

lsp.catalog

Direction: client → server

List every registered language server, regardless of whether it has started.

Params

No params (send {}).

Result

field	type	required	description
servers	({ disabled: boolean; extensions?: string[]; id: string; installHint?: string | null; installable: boolean; languageIds?: string[]; })[]	no	One row per registered server id.

lsp.status

Direction: client → server

Report every language server the daemon has started and its state.

Params

No params (send {}).

Result

field	type	required	description
servers	({ id: string; languageId?: string; pid?: number | null; root: string; state: "starting" | "ready" | "broken" | "stopped"; })[]	no	One row per (server, root) pair.

mcp.add

Direction: client → server

Write an MCP server into the project or global .mcp.json and start it.

Params

field	type	required	description
args	string[] | null	no	Arguments, argv style; never a shell string.
command	string | null	no	Executable for a stdio server.
cwd	string | null	no	Working directory for a stdio server.
disabled	boolean | null	no	Keep the entry but never start the server.
env	Record<string, string> | null	no	Environment for the child process.
force	boolean	no	Overwrite an existing entry and accept the security findings.
headers	Record<string, string> | null	no	HTTP headers sent with every request.
name	string	yes	Server name; ^[a-zA-Z0-9_-]{1,64}$.
permission	"read" | "write" | "exec" | "network" | "send" | "config" | "delegate" | "secret" | null	no	Permission tag for the server's tools; stored in settings.
preset	string | null	no	Catalog id copied before the explicit fields are applied.
scope	"project" | "global"	no	Which file to write: $SNOWPEA_HOME/.mcp.json (global, the default since 1.23.0, so every project sees it) or the project's .mcp.json.
sessionId	string | null	no	Session whose workdir to use.
test	boolean	no	Probe the server before saving; nothing is written if it fails.
timeoutSec	number | null	no	Startup cap, in seconds.
toolTimeoutSec	number | null	no	Per-call cap, in seconds.
toolsExclude	string[] | null	no	Never register these tools of the server.
toolsInclude	string[] | null	no	Register only these tools of the server.
type	"stdio" | "http" | "sse" | null	no	Force a transport instead of inferring it.
url	string | null	no	Endpoint for an http or sse server.
workdir	string | null	no	Project directory for scope=project.

Result

field	type	required	description
error	string | null	no	Why the server did not start.
ok	boolean	no	True when the entry was written.
path	string	yes	File the entry was written to.
state	"stopped" | "starting" | "ready" | "error"	no	State of the server after the write.
tools	({ description?: string; name: string; })[]	no	Tools the probe found, so a client can offer a picker.
warnings	string[]	no	Security findings that --force accepted.

mcp.catalog

Direction: client → server

The curated MCP servers a client can offer as presets.

Params

No params (send {}).

Result

field	type	required	description
entries	({ description?: string; entry?: Record<string, unknown>; homepage?: string; id: string; label: string; needs?: string[]; transport: "stdio" | "http" | "sse"; })[]	no	Curated servers, in display order.

mcp.list

Direction: client → server

List every configured MCP server with its scope, state and tools.

Params

field	type	required	description
sessionId	string | null	no	Session whose workdir to read.
workdir	string | null	no	Project directory; defaults to the session's, then the daemon's.

Result

field	type	required	description
servers	({ args?: string[]; command?: string | null; cwd?: string | null; disabled?: boolean; envKeys?: string[]; error?: string | null; headerKeys?: string[]; name: string; permission?: "read" | "write" | "exec" | "network" | "send" | "config" | "delegate" | "secret"; plugin?: string | null; scope: "project" | "global" | "plugin" | "settings"; state?: "stopped" | "starting" | "ready" | "error"; timeoutSec?: number | null; toolCount?: number; toolTimeoutSec?: number | null; tools?: ({ description?: string; name: string; })[]; toolsExclude?: string[]; toolsInclude?: string[]; transport: "stdio" | "http" | "sse"; url?: string | null; })[]	no	One row per configured server, project entries winning.

mcp.reload

Direction: client → server

Restart one MCP server, or every configured one.

Params

field	type	required	description
name	string | null	no	Server to restart; all of them when absent.
sessionId	string | null	no	Session whose workdir to use.
workdir	string | null	no	Project directory to rediscover from.

Result

field	type	required	description
ok	boolean	no	True when the reload ran.
servers	string[]	no	Servers that were restarted.

mcp.remove

Direction: client → server

Delete an MCP server entry and stop the server.

Params

field	type	required	description
name	string	yes	Server name.
scope	"project" | "global" | null	no	Which file to rewrite; omitted, the one that declares it.
sessionId	string | null	no	Session whose workdir to use.
workdir	string | null	no	Project directory for scope=project.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

mcp.test

Direction: client → server

Probe a saved MCP server or an unsaved draft and report its tools.

Params

field	type	required	description
args	string[] | null	no	Arguments, argv style; never a shell string.
command	string | null	no	Executable for a stdio server.
cwd	string | null	no	Working directory for a stdio server.
disabled	boolean | null	no	Keep the entry but never start the server.
env	Record<string, string> | null	no	Environment for the child process.
headers	Record<string, string> | null	no	HTTP headers sent with every request.
name	string | null	no	Saved server to probe.
permission	"read" | "write" | "exec" | "network" | "send" | "config" | "delegate" | "secret" | null	no	Permission tag for the server's tools; stored in settings.
scope	"project" | "global" | "plugin" | "settings" | null	no	Scope of the saved server.
sessionId	string | null	no	Session whose workdir to use.
timeoutSec	number | null	no	Startup cap, in seconds.
toolTimeoutSec	number | null	no	Per-call cap, in seconds.
toolsExclude	string[] | null	no	Never register these tools of the server.
toolsInclude	string[] | null	no	Register only these tools of the server.
type	"stdio" | "http" | "sse" | null	no	Force a transport instead of inferring it.
url	string | null	no	Endpoint for an http or sse server.
workdir	string | null	no	Project directory for scope=project.

Result

field	type	required	description
elapsedMs	number	no	How long the probe took.
error	string | null	no	Spawn or protocol error, verbatim.
ok	boolean	yes	True when the server answered tools/list.
state	"stopped" | "starting" | "ready" | "error"	yes	ready when the probe succeeded, error otherwise.
tools	({ description?: string; name: string; })[]	no	What the server exposes.

mcp.update

Direction: client → server

Merge a patch into an existing MCP server entry.

Params

field	type	required	description
name	string	yes	Server name.
patch	{ args?: string[] | null; command?: string | null; cwd?: string | null; disabled?: boolean | null; env?: Record<string, string> | null; headers?: Record<string, string> | null; permission?: "read" | "write" | "exec" | "network" | "send" | "config" | "delegate" | "secret" | null; timeoutSec?: number | null; toolTimeoutSec?: number | null; toolsExclude?: string[] | null; toolsInclude?: string[] | null; type?: "stdio" | "http" | "sse" | null; url?: string | null; }	no	Keys to change; anything absent is kept.
scope	"project" | "global" | null	no	Which file to rewrite; omitted, the one that declares it.
sessionId	string | null	no	Session whose workdir to use.
workdir	string | null	no	Project directory for scope=project.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

memory.delete

Direction: client → server

Forget one stored memory.

Params

field	type	required	description
before	string | null	no	With source: UTC ISO time; forget visits before it.
id	string | null	no	Memory id to forget.
source	"browser" | null	no	"browser" forgets browsing memories instead: those of url (a page, or a whole site when it has no path), those visited before before, or all (1.7.0).
url	string | null	no	With source: the page or site.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

memory.ingest

Direction: client → server

Remember visited pages in the browser namespace, once per url and text.

Params

field	type	required	description
items	({ text?: string; title?: string; url: string; visitedAt?: string | null; })[]	yes	Visited pages to remember.
sessionId	string | null	no	Session they came from, if any.

Result

field	type	required	description
added	number	no	Pages stored.
removed	number	no	For memory.delete by source: how many.
skipped	number	no	Pages already stored (same url and text).

memory.list

Direction: client → server

List stored memories by scope, newest first.

Params

field	type	required	description
limit	number	no	Maximum number of entries.
project	string | null	no	Project root to use instead of a session's, so a CLI in a checkout can list that project's memories without opening a session.
query	string | null	no	Free-text filter; omit to list newest first.
scope	"project" | "global" | "agent" | "all" | null	no	Which scopes to list: "project", "global", "agent" or "all" (default).
sessionId	string | null	no	Session whose project and agent scopes to resolve; omit for global only.

Result

field	type	required	description
entries	({ createdAt?: string; id: string; project?: string; scope?: "project" | "global" | "agent" | "all"; tags?: string[]; text: string; })[]	no	Matching memories, newest or best first.

memory.search

Direction: client → server

Recall stored memories matching a query.

Params

field	type	required	description
limit	number	no	Maximum number of hits.
namespace	string | null	no	Memory namespace to search; defaults to "default". Never crosses namespaces.
query	string	yes	Free-text query.

Result

field	type	required	description
hits	({ id: string; project?: string; scope?: "project" | "global" | "agent" | "all"; score?: number; tags?: string[]; text: string; })[]	no	Matches, best first.

memory.write

Direction: client → server

Store a memory with tags.

Params

field	type	required	description
namespace	string | null	no	Memory namespace to write into; defaults to "default".
tags	string[]	no	Tags for later filtering.
text	string	yes	Text to remember.

Result

field	type	required	description
id	string	yes	Id of the stored memory.

permission.allowlist.add

Direction: client → server

Promote a pattern from ask to allow.

Params

field	type	required	description
pattern	string	yes	Glob or command prefix promoted from ask to allow.
scope	"session" | "project" | "always"	no	Where the pattern is stored.
workdir	string | null	no	Absolute folder of the project to use (its .snowpea/settings.json). Default: the caller's most recent session's workdir (1.7.0).

Result

field	type	required	description
patternId	string	yes	Id used to remove the pattern later.

permission.allowlist.list

Direction: client → server

List stored allowlist patterns.

Params

field	type	required	description
hostToolsFrom	string | null	no	Only this browser profile's global entries (plus project entries); omit for every entry (addendum 8).
scope	"session" | "project" | "always" | null	no	Filter by scope; omit for all.
workdir	string | null	no	Absolute folder of the project to use (its .snowpea/settings.json). Default: the caller's most recent session's workdir (1.7.0).

Result

field	type	required	description
patterns	({ createdAt?: string | null; hostToolsFrom?: string | null; origin?: string | null; pattern: string; patternId: string; reasonCode?: string | null; scope: "session" | "project" | "always"; tool?: string | null; })[]	no	Stored allowlist entries.

permission.allowlist.remove

Direction: client → server

Delete an allowlist pattern by id.

Params

field	type	required	description
hostToolsFrom	string | null	no	When given, a global entry is removed only if it belongs to this browser profile (addendum 8).
patternId	string	yes	Pattern to delete.
workdir	string | null	no	Absolute folder of the project to use (its .snowpea/settings.json). Default: the caller's most recent session's workdir (1.7.0).

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

provider.configure

Direction: client → server

Store settings and credentials for a provider.

Params

field	type	required	description
config	Record<string, unknown>	no	Vendor-specific settings, including credentials.
vendor	string	yes	Vendor to configure.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

provider.list

Direction: client → server

List chat providers and whether they are configured.

Params

No params (send {}).

Result

field	type	required	description
providers	({ authMethods?: string[]; authStatus?: "unconfigured" | "active" | "expired"; baseUrl?: string; configured?: boolean; custom?: boolean; default?: boolean; defaultBaseUrl?: string; defaultModel?: string; label?: string; models?: string[]; preset?: string; supportsEffort?: boolean; variant?: string; vendor: string; })[]	no	Known chat providers.

provider.loginWeb

Direction: client → server

Start a browser-based login flow for a provider.

Params

field	type	required	description
method	string	yes	Login flow to start: 'browser_pkce' or 'google_oauth' (browser), 'device_code' or 'google_adc' (headless), 'oauth_pkce' (OpenRouter). 'web' or an empty value picks the best flow this machine can complete.
vendor	string	yes	Vendor to log into.

Result

field	type	required	description
expiresInSec	number | null	no	Seconds until the code or session expires, when known.
ok	boolean	no	True when the call succeeded.
status	"await_user" | "done" | "failed"	no	'await_user' once userCode/verificationUri are ready and polling has started in the background; 'done' or 'failed' if the flow finished synchronously before this response was sent.
userCode	string | null	no	Short code the user types in, for device-code flows.
verificationUri	string | null	no	URL to open to approve the login.
verificationUriComplete	string | null	no	verificationUri with the code already embedded, when known.

provider.models

Direction: client → server

Ask a vendor's endpoint which models it serves.

Params

field	type	required	description
vendor	string | null	no	Vendor to query; defaults to the configured one.

Result

field	type	required	description
current	string	no	Model this vendor uses today.
detail	string	no	One line naming the source, for a picker to show.
error	string | null	no	Why the live listing could not be used, when source is not 'live' (1.17.0); absent when the vendor answered or publishes no listing.
models	string[]	no	Model ids the vendor's endpoint reports. Whatever the source, models[0] is the recommended default (a ChatGPT account's first-priority model, the newest chat model for an API key), so a picker can take current or models[0].
source	string	no	Which rung answered: live (the vendor's endpoint), settings (providers.<vendor>.models), cache (the last good listing) or curated (this build's list, merged with models.dev).
vendor	string	yes	Vendor the listing came from.
vision	Record<string, boolean>	no	Which of the listed models can be sent images, when that is known. A model missing from this map is unknown rather than text-only, so a picker draws no badge for it instead of a negative one.

provider.remove

Direction: client → server

Forget a configured provider, typically a named local server.

Params

field	type	required	description
vendor	string	yes	Provider to forget: its credentials, its model profiles and the agent assignments that used them.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

provider.test

Direction: client → server

Send one short completion to check a provider and model.

Params

field	type	required	description
model	string | null	no	Model; defaults to the vendor's default.
provider	string	yes	Vendor to test.

Result

field	type	required	description
error	string | null	no	Why it failed.
latencyMs	number	no	Round-trip time of the test call.
model	string	no	Model the request used.
modelEcho	string | null	no	Model name the server reported, when it did.
ok	boolean	yes	True when a one-line completion came back.
provider	string	yes	Vendor tested.
reply	string | null	no	The model's reply, trimmed.

question.list

Direction: client → server

List questions the agent is still waiting on.

Params

field	type	required	description
sessionId	string | null	no	Scope the listing to one session; omit for the global set.

Result

field	type	required	description
requests	({ questions?: ({ allowOther?: boolean; header?: string; multi?: boolean; options?: ({ description?: string; label: string; preview?: string; })[]; question: string; secret?: boolean; })[]; requestId: string; sessionId: string; timeoutSec?: number; })[]	no	Questions still waiting for an answer.

question.request

Direction: server → client

Ask the client to put a question to the human.

Params

field	type	required	description
questions	({ allowOther?: boolean; header?: string; multi?: boolean; options?: ({ description?: string; label: string; preview?: string; })[]; question: string; secret?: boolean; })[]	no	The questions, in the order they were asked.
requestId	string	yes	Id to answer with question.respond.
sessionId	string	yes	Session whose turn is blocked.
timeoutSec	number	no	Seconds before the batch gives up.

Result

field	type	required	description
answers	({ selected?: string[]; text?: string | null; })[]	no	One entry per question, in question order.

question.respond

Direction: client → server

Answer a pending question and unblock the turn.

Params

field	type	required	description
answers	({ selected?: string[]; text?: string | null; })[]	no	One entry per question, in question order; empty declines the batch.
requestId	string	yes	Batch being answered.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

session.artifacts

Direction: client → server

Files the session saved for the user under its workspace's artifacts/.

Params

field	type	required	description
sessionId	string	yes	Target session.

Result

field	type	required	description
artifacts	({ mimeType?: string | null; modifiedAt: string; name: string; path: string; size: number; })[]	no	Files under artifacts/, newest first.
workspaceDir	string	yes	The session workspace.

session.attach

Direction: client → server

Make this connection the origin of a session (approvals, host tools).

Params

field	type	required	description
hostToolsFrom	string | null	no	Re-point the session's host tools to this clientId (or surface id). It must name an open connection whose clientKind is 'browser'. Persisted; emits sessions.changed (reason 'host').
locale	string | null	no	The client's UI language as a BCP 47 tag (1.7.0), as on session.create. Kept in memory only, so a client re-sends it after a daemon restart; omitted leaves the session's current locale.
sessionId	string	yes	Session this connection becomes the origin of (1.6.0).

Result

field	type	required	description
hostTools	string[]	no	Host tools the session now sees.
hostToolsFrom	string | null	no	The session's hostToolsFrom after the call; older cores omit it.
sessionId	string	yes	The attached session.

session.attachments

Direction: client → server

Files the user attached in this session, with the path of the original bytes the agent may use (1.23.0). A delegated child reports its root's.

Params

field	type	required	description
sessionId	string	yes	Target session.

Result

field	type	required	description
attachments	({ byPath?: boolean; messageId?: string | null; mime: string; name: string; path: string; size: number; })[]	no	This session's attachments, oldest first.

session.close

Direction: client → server

Close a session and release its resources.

Params

field	type	required	description
sessionId	string	yes	Target session.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

session.compact

Direction: client → server

Summarise the conversation so far and replace the history with it.

Params

field	type	required	description
instructions	string | null	no	Extra guidance for the summary, e.g. 'keep the API design decisions'.
sessionId	string	yes	Session whose history to compact.

Result

field	type	required	description
after	number	no	Estimated tokens the history holds now.
before	number	no	Estimated tokens the history held before.
summaryChars	number	no	Length of the summary in characters.

session.continue

Direction: client → server

Continue a chat session on the system's behalf, e.g. after a human hand-back (1.8.0). A running turn gets the note at its next model call (like session.notice); otherwise a turn starts whose input is the [system] note, with turn.started initiator 'system' and no message.user. Same callers as session.setAgent; subagent and scheduled sessions are refused with 'invalid_params'. One system start per session per 10 s, and an idempotencyKey is honoured once; a call inside the 10 s window keeps its note as a notice (queued: true).

Params

field	type	required	description
idempotencyKey	string | null	no	The same key twice: the second call is a no-op.
note	string	yes	The [system] line the model sees, e.g. 'the tab is back'.
reason	string	no	Why the session continues, e.g. 'handback'.
sessionId	string	yes	A chat session the caller may drive.

Result

field	type	required	description
duplicate	boolean | null	no	True when idempotencyKey was already used.
queued	boolean | null	no	True when a turn was running and the note joins its next model call.
started	boolean	yes	True when a new system-initiated turn started.
turnId	string | null	no	The turn that started, if any.

session.create

Direction: client → server

Open a session rooted at a working directory.

Params

field	type	required	description
agent	string | null	no	Named agent whose persona to load.
browserMemory	boolean | null	no	Recall also searches pages the browser ingested. Default: on when a browser client (clientKind 'browser') creates the session (1.7.0).
denyExec	boolean | null	no	When true, refuse exec-tagged tools without prompting (headless CI).
effort	"low" | "medium" | "high" | "max" | null	no	Reasoning effort for this session; null follows the settings.
hostToolsFrom	string | null	no	Whose host tools this session sees: a connection's clientId (or surface id). Default: the creating connection (1.6.0).
locale	string | null	no	The client's UI language as a BCP 47 tag, e.g. 'ko-KR' (1.7.0). With agent.replyLanguage 'auto', text the core writes for this session (/init, /ralph and delegated briefs) is in this language before any guess from what the user typed. Ignored when not a language tag.
maxConcurrent	number | null	no	Override for concurrent subagents.
mode	"plan" | "accept" | "auto" | null	no	Starting mode; defaults to the project setting.
model	string | null	no	Model id; defaults to the provider's default.
originSurface	string | null	no	Surface that owns approvals for this session (TUI, gateway, ...).
provider	string | null	no	Chat provider vendor; defaults to configured.
workdir	string	yes	Absolute path the session operates in.

Result

field	type	required	description
delegation	boolean	no	Whether the session starts in delegation mode (the lead hands the work to its team): the session pin, else agents.delegateByDefault.
sessionId	string	yes	Id of the new session.
workspaceDir	string | null	no	Session workspace with tmp/ and artifacts/ (1.7.0).

session.deleteSaved

Direction: client → server

Delete saved sessions.

Params

field	type	required	description
all	boolean	no	Delete saved sessions from every directory.
deleteWorkspace	boolean	no	Also delete each session's workspace ($SNOWPEA_HOME/sessions/<date>_<id>: tmp/, artifacts/, downloads) — it can hold page text the user deleted the chat to get rid of. false keeps it (1.7.0).
sessionId	string | null	no	Delete one saved session.
workdir	string | null	no	Delete saved sessions rooted here.

Result

field	type	required	description
deleted	number	no

session.interrupt

Direction: client → server

Stop the running turn as soon as possible.

Params

field	type	required	description
sessionId	string	yes	Target session.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

session.list

Direction: client → server

List live or saved sessions.

Params

field	type	required	description
hostToolsFrom	string | null	no	Only sessions owned by this client (a browser profile's clientId); omit for every session (addendum 8).
includeClosed	boolean	no	Include persisted closed sessions.
includeUnhosted	boolean	no	With hostToolsFrom: also return sessions with no host (IDE, TUI, CLI), which a browser shows in every profile.
kinds	string[] | null	no	Only sessions of these kinds; omit for every kind. A surface that shows human threads asks for ["chat"] (CORE-session-kind).
workdir	string | null	no	Only sessions rooted here.

Result

field	type	required	description
sessions	({ agent?: string | null; browserProvider?: "host" | "local" | null; contextUsed?: number; contextWindow?: number | null; createdAt: string; effort?: "low" | "medium" | "high" | "max" | null; hostToolsFrom?: string | null; jobId?: string | null; kind?: "chat" | "scheduled" | "subagent" | "agent"; lastActivityAt?: string | null; lastPrompt?: string | null; mode: "plan" | "accept" | "auto"; model?: string | null; originSurface?: string | null; parentSessionId?: string | null; pendingApprovals?: number; pendingQuestions?: number; provider?: string | null; running?: boolean; seq?: number; sessionId: string; status?: "idle" | "running" | "awaiting_approval" | "awaiting_question" | "error"; title?: string | null; turnStartedAt?: string | null; workdir: string; workspaceDir?: string | null; })[]	no	Every live session.

session.notice

Direction: client → server

Queue a [system] line for the model's next call.

Params

field	type	required	description
sessionId	string	yes	Session to tell.
text	string	yes	Something that happened outside a tool call (a popup opened, a download finished). Reaches the model as a [system] line before its next call; it starts no turn (1.7.0).

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

session.prompt

Direction: client → server

Send user text to a session and start a turn. Events: turn.started {turnId, prompt, queued}, then message.user {text, attachments, refs, steered: false}, then the model's output. message.user.text is what the user typed; a page attachment is listed as {kind: page, name, url, title} and only the model sees the rendered page. A steered prompt emits message.user {steered: true} + turn.dequeued {reason: steered}; a queued one emits turn.queued first.

Params

field	type	required	description
attachments	({ data?: string | null; kind?: "file" | "image" | "text" | "page"; mimeType?: string | null; name?: string | null; path?: string | null; selection?: string | null; size?: number | null; snapshot?: string | null; text?: string | null; title?: string | null; url?: string | null; })[] | null	no	Files or images to include.
sessionId	string	yes	Session to prompt.
text	string	yes	User text; a leading '/' is parsed as a slash command.
whenBusy	"queue" | "steer" | null	no	If a turn is running: 'queue' waits for it, 'steer' folds this prompt into it at the next tool round. Default: the agent.busy setting (1.7.0).

Result

field	type	required	description
turnId	string	yes	Id of the started turn; turn.done carries it back.

session.rename

Direction: client → server

Set a session's title.

Params

field	type	required	description
sessionId	string	yes	Session to rename.
title	string	yes	New title; empty clears it (1.7.0).

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

session.resume

Direction: client → server

Replay the events a disconnected client missed.

Params

field	type	required	description
afterSeq	number | null	no	Replay only events with a greater seq.
locale	string | null	no	The client's UI language as a BCP 47 tag (1.7.0), as on session.create. Kept in memory only, so a client re-sends it after a daemon restart; omitted leaves the session's current locale.
sessionId	string	yes	Session to resume.

Result

field	type	required	description
delegation	boolean	no	Whether delegation mode is in force: the session pin, else the default.
effort	string | null	no	Reasoning effort pinned on the session.
events	({ kind: string; payload?: Record<string, unknown>; seq: number; sessionId: string; ts: string; })[]	no	Missed events in seq order.
mode	"plan" | "accept" | "auto" | null	no	The session's permission mode as restored, so a surface that resumes adopts it instead of keeping the mode it launched with.
model	string | null	no	Model id in use.
provider	string | null	no	Chat provider vendor in use.
sessionId	string	yes	Session that was resumed.

session.setActive

Direction: client → server

Mark the session the user is looking at as the active one: a messenger with gateway.<platform>.shareActive posts its questions and approvals to the owner's chat. session.prompt and session.steer from a client do the same. Subagent and scheduled sessions are refused with 'invalid_params'.

Params

field	type	required	description
sessionId	string	yes	Target session.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

session.setAgent

Direction: client → server

Run a session as an agent definition, or as none (addendum 17). Only the session's origin connection, a browser session's hostToolsFrom host, or a non-browser surface (for a session it originated or that is not a browser session) may call it; others get 'unauthorized'.

Params

field	type	required	description
agent	string | null	no	Agent definition to run as from the next model call: its prompt (persona layer), tools allowlist ('*' = all) and max_tool_rounds. null clears it.
guardTurn	boolean	no	Guard the running turn (1.24.0): from now on every call that is not a read (read-only web tools included) and every mcp__ call is asked with forceAsk semantics — plan still denies; no mode, allowlist or cached answer allows it; approval.ask answers come back as 'once'. It covers sessions delegated from this one (also ones started later), a steer, and turns the agent queues for itself, and ends when the person's own next prompt starts a turn. No turn running: no effect.
sessionId	string	yes	Session to switch.

Result

field	type	required	description
agent	string | null	no	Agent now in force.
guarded	boolean	no	True when a running turn is now guarded (guardTurn).
sessionId	string	yes	The session.

session.setBrowserProvider

Direction: client → server

Per-session opt-in to core's own browser; never global (addendum 9).

Params

field	type	required	description
provider	"host" | "local"	yes	'host': only the Snowpea browser (the default for browser sessions; with no browser attached, browser tools fail with host_unavailable). 'local': the user explicitly allows core's own browser for this session only.
sessionId	string	yes	Session whose browser tools to point (addendum 9).

Result

field	type	required	description
browserProvider	"host" | "local"	yes	What it uses now.
sessionId	string	yes	The session.

session.setEffort

Direction: client → server

Pin how hard a session's model may think, or clear the pin.

Params

field	type	required	description
effort	"low" | "medium" | "high" | "max" | null	no	One of 'low', 'medium', 'high', 'max'. Null clears the pin and lets agent.effortBy / agent.effort decide again.
sessionId	string	yes	Session to pin.

Result

field	type	required	description
effort	"low" | "medium" | "high" | "max" | null	no	Effective reasoning effort after the change, clamped to what the model offers; null when the model has no effort setting.
effortSource	"session" | "model" | "vendor" | "default"	yes	Rule that decided it: the session pin, a model or vendor rule, or the default.
efforts	("low" | "medium" | "high" | "max")[] | null	no	Tiers the session's model offers; [] means it has no effort setting.
pinned	"low" | "medium" | "high" | "max" | null	no	The session's own pin; null when it follows the settings.
sessionId	string	yes	Session that was pinned.

session.setMode

Direction: client → server

Switch a session between plan, accept and auto.

Params

field	type	required	description
mode	"plan" | "accept" | "auto"	yes	New permission mode.
sessionId	string	yes	Session to change.

Result

field	type	required	description
mode	"plan" | "accept" | "auto"	yes	Mode now in effect.

session.setModel

Direction: client → server

Pin a session to a model profile, or clear the pin.

Params

field	type	required	description
model	string | null	no	A models.profiles id, a 'vendor:model' pair, or a bare vendor name. Null or 'inherit' clears the pin and lets the configured routing decide.
sessionId	string	yes	Session to pin.

Result

field	type	required	description
model	string | null	no	Model id now in effect.
pinned	boolean	no	False when the pin was cleared.
provider	string | null	no	Vendor now in effect.

session.steer

Direction: client → server

Inject a user message into a running turn at its next tool round.

Params

field	type	required	description
sessionId	string	yes	Session with a running turn.
text	string	yes	User message injected at the running turn's next tool-round boundary; with no turn running it starts one like session.prompt (1.6.0).

Result

field	type	required	description
ok	boolean	no	True when accepted.
started	boolean	no	True when no turn was running and a new one started.

session.toolContent

Direction: client → server

A host tool result's content blocks with image bytes; results with images are kept on disk.

Params

field	type	required	description
callId	string	yes	tool.result callId whose content to fetch.
sessionId	string	yes	Session the tool ran in.

Result

field	type	required	description
callId	string	yes	The call.
content	({ contentRef?: string | null; data?: string | null; mediaType?: string | null; text?: string | null; type: "text" | "image"; })[]	no	The content blocks, images with their bytes.

settings.get

Direction: client → server

Read global or project settings, with secrets masked.

Params

field	type	required	description
scope	"global" | "project"	no	"global" reads $SNOWPEA_HOME/settings.json; "project" reads <workdir>/.snowpea/settings.json.
workdir	string | null	no	Project root; required when scope is "project".

Result

field	type	required	description
settings	Record<string, unknown>	yes	The effective settings document. Fields named api_key, token, refresh_token or password are masked as '***'.

settings.set

Direction: client → server

Deep-merge a patch into global or project settings and persist it.

Params

field	type	required	description
patch	Record<string, unknown>	yes	Fields to deep-merge into the existing settings.
scope	"global" | "project"	no	"global" writes $SNOWPEA_HOME/settings.json; "project" writes <workdir>/.snowpea/settings.json.
workdir	string | null	no	Project root; required when scope is "project".

Result

field	type	required	description
settings	Record<string, unknown>	yes	The effective settings document. Fields named api_key, token, refresh_token or password are masked as '***'.

setup.applyDefaults

Direction: client → server

Apply the profile's defaults for everything optional; idempotent.

Params

field	type	required	description
profile	"default" | "browser"	no	Which defaults to apply.

Result

field	type	required	description
applied	string[]	no	Setting keys this call filled in because they were unset (absent or null).
skipped	string[]	no	Profile keys left alone because settings.json already holds a value.
status	{ configuredProviders?: string[]; existingInstall?: boolean; optional?: ({ defaultApplied?: boolean | null; done: boolean; id: string; title: string; })[]; required?: ({ defaultApplied?: boolean | null; done: boolean; id: string; title: string; })[]; }	yes	setup.status after applying.

setup.catalog

Direction: client → server

The setup wizard's vendor, search, browser, tools and gateway catalogs.

Params

No params (send {}).

Result

field	type	required	description
browser	({ active?: boolean; default?: boolean; defaultModel?: string; defaultModelSource?: string; description?: string; id: string; installHint?: string | null; installable?: boolean; key: string; label: string; recommended?: boolean; tags?: string[]; tier: string; })[]	no	Browser-control providers.
gateway	({ active?: boolean; default?: boolean; defaultModel?: string; defaultModelSource?: string; description?: string; id: string; installHint?: string | null; installable?: boolean; key: string; label: string; recommended?: boolean; tags?: string[]; tier: string; })[]	no	Chat gateways (telegram, discord, slack), all off.
search	({ active?: boolean; default?: boolean; defaultModel?: string; defaultModelSource?: string; description?: string; id: string; installHint?: string | null; installable?: boolean; key: string; label: string; recommended?: boolean; tags?: string[]; tier: string; })[]	no	Web-search providers, ddgs first.
stt	({ active?: boolean; default?: boolean; defaultModel?: string; defaultModelSource?: string; description?: string; id: string; installHint?: string | null; installable?: boolean; key: string; label: string; recommended?: boolean; tags?: string[]; tier: string; })[]	no	Speech-to-text choices; active reflects what is usable on this machine.
tools	({ active?: boolean; default?: boolean; defaultModel?: string; defaultModelSource?: string; description?: string; id: string; installHint?: string | null; installable?: boolean; key: string; label: string; recommended?: boolean; tags?: string[]; tier: string; })[]	no	Tool categories and their default on/off state.
tts	({ active?: boolean; default?: boolean; defaultModel?: string; defaultModelSource?: string; description?: string; id: string; installHint?: string | null; installable?: boolean; key: string; label: string; recommended?: boolean; tags?: string[]; tier: string; })[]	no	Text-to-speech choices; active reflects what is usable on this machine.
vendors	({ active?: boolean; default?: boolean; defaultModel?: string; defaultModelSource?: string; description?: string; id: string; installHint?: string | null; installable?: boolean; key: string; label: string; recommended?: boolean; tags?: string[]; tier: string; })[]	no	LLM vendors.

setup.status

Direction: client → server

What setup still needs; for the browser profile only a tested provider is required.

Params

field	type	required	description
profile	"default" | "browser"	no	Which setup flow is asking (1.6.0).

Result

field	type	required	description
configuredProviders	string[]	no	Vendors with credentials or a local endpoint.
existingInstall	boolean	no	True when this home already has a configured provider from an earlier setup.
optional	({ defaultApplied?: boolean | null; done: boolean; id: string; title: string; })[]	no	Items with a usable default.
required	({ defaultApplied?: boolean | null; done: boolean; id: string; title: string; })[]	no	Items that must be done before first use.

site.delete

Direction: client → server

Site memory (1.9.0): delete one entry, or every entry of an origin, in one browser profile. Same callers as site.list.

Params

field	type	required	description
entryId	string | null	no	One entry; omitted = all of them.
hostToolsFrom	string | null	no	The browser profile (its clientId). Required from a UI client; a browser client may only name its own.
origin	string	yes	Origin.

Result

field	type	required	description
deleted	number	yes	Entries removed.

site.get

Direction: client → server

Site memory (1.9.0): the entries stored for an origin in the caller's browser profile; with path, only those whose urlPattern matches it, most specific first; with pageType, only that one. Stale entries are included, flagged. Browser host clients only; entries are untrusted page-derived data and core never puts them in a prompt.

Params

field	type	required	description
origin	string	yes	Origin, e.g. 'https://www.example.com'.
pageType	string | null	no	Only this page type.
path	string | null	no	Path (and query) on the origin: only entries whose urlPattern matches.

Result

field	type	required	description
entries	({ actions?: ({ frames?: ({ origin: string; path: string; selector: string; })[] | null; kind: "click" | "fill" | "select" | "toggle" | "submit"; locators: ({ by: "role" | "label" | "text" | "placeholder" | "testid" | "css"; name?: string | null; role?: string | null; value?: string | null; })[]; loginField?: boolean; name: string; })[]; createdAt: string; entryId: string; failureCount?: number; fingerprint?: string | null; flows?: ({ expect?: "page" | "update" | null; name: string; stats?: { lastRun?: string | null; missed?: number; ok?: number; } | null; steps?: (string | { action?: string | null; intent?: string | null; verb: "fill" | "click" | "select" | "enter"; })[]; })[]; landmarks?: string[]; lastVerified: string; origin: string; pageType: string; pitfalls?: string[]; recipes?: ({ fields: ({ attr?: string | null; name: string; selector: string; })[]; intent?: string | null; item: string; name: string; stale?: boolean; stats?: { day?: number | null; hits?: number; misses?: number; } | null; })[]; stale?: boolean; successCount?: number; summary?: string; urlPattern: string; })[]	no	Most specific urlPattern first; stale entries included, flagged.

site.list

Direction: client → server

Site memory (1.9.0): one browser profile's remembered sites, by origin, for a settings UI. A browser client sees its own profile; any other owner client names one with hostToolsFrom.

Params

field	type	required	description
cursor	string | null	no	From the previous page.
hostToolsFrom	string | null	no	The browser profile (its clientId). Required from a UI client; a browser client may only name its own.
limit	number	no	Most sites per page.
origin	string | null	no	Only this origin.

Result

field	type	required	description
cursor	string | null	no	Pass back for the next page.
sites	({ entries: number; failureCount?: number; lastVerified: string; origin: string; pageTypes?: string[]; stale: number; successCount?: number; })[]	no	Sites, by origin.

site.mark

Direction: client → server

Site memory (1.9.0): 'ok' counts a success, sets lastVerified and clears stale; 'stale' counts a failure and flags the entry until the next put. Browser host clients only.

Params

field	type	required	description
detail	string | null	no	For the UI and log only.
entryId	string	yes	The entry.
origin	string	yes	Origin of the entry.
outcome	"ok" | "stale"	yes	'ok' = verified use; 'stale' = it failed.

Result

field	type	required	description
entry	{ actions?: ({ frames?: ({ origin: string; path: string; selector: string; })[] | null; kind: "click" | "fill" | "select" | "toggle" | "submit"; locators: ({ by: "role" | "label" | "text" | "placeholder" | "testid" | "css"; name?: string | null; role?: string | null; value?: string | null; })[]; loginField?: boolean; name: string; })[]; createdAt: string; entryId: string; failureCount?: number; fingerprint?: string | null; flows?: ({ expect?: "page" | "update" | null; name: string; stats?: { lastRun?: string | null; missed?: number; ok?: number; } | null; steps?: (string | { action?: string | null; intent?: string | null; verb: "fill" | "click" | "select" | "enter"; })[]; })[]; landmarks?: string[]; lastVerified: string; origin: string; pageType: string; pitfalls?: string[]; recipes?: ({ fields: ({ attr?: string | null; name: string; selector: string; })[]; intent?: string | null; item: string; name: string; stale?: boolean; stats?: { day?: number | null; hits?: number; misses?: number; } | null; })[]; stale?: boolean; successCount?: number; summary?: string; urlPattern: string; }	yes	The entry after the mark.

site.markPart

Direction: client → server

Site memory (1.15.0): count one use of a flow or recipe of an entry without a put. The entry's successCount, failureCount, stale and lastVerified are untouched, so this never counts as verification. 'not_found' for an unknown entry, flow or recipe. Browser host clients only.

Params

field	type	required	description
entryId	string	yes	The entry.
name	string	yes	The flow's or recipe's name.
origin	string	yes	Origin of the entry.
outcome	"ok" | "miss" | "stale"	yes	flow: ok (stats.ok+1, lastRun) | miss (stats.missed+1). recipe: ok (hits+1, day, not stale) | miss (misses+1) | stale (misses+1, stale).
part	"flow" | "recipe"	yes	Which list the part is in.

Result

field	type	required	description
entry	{ actions?: ({ frames?: ({ origin: string; path: string; selector: string; })[] | null; kind: "click" | "fill" | "select" | "toggle" | "submit"; locators: ({ by: "role" | "label" | "text" | "placeholder" | "testid" | "css"; name?: string | null; role?: string | null; value?: string | null; })[]; loginField?: boolean; name: string; })[]; createdAt: string; entryId: string; failureCount?: number; fingerprint?: string | null; flows?: ({ expect?: "page" | "update" | null; name: string; stats?: { lastRun?: string | null; missed?: number; ok?: number; } | null; steps?: (string | { action?: string | null; intent?: string | null; verb: "fill" | "click" | "select" | "enter"; })[]; })[]; landmarks?: string[]; lastVerified: string; origin: string; pageType: string; pitfalls?: string[]; recipes?: ({ fields: ({ attr?: string | null; name: string; selector: string; })[]; intent?: string | null; item: string; name: string; stale?: boolean; stats?: { day?: number | null; hits?: number; misses?: number; } | null; })[]; stale?: boolean; successCount?: number; summary?: string; urlPattern: string; }	yes	The entry after the count.

site.put

Direction: client → server

Site memory (1.9.0): upsert an entry by (origin, pageType). Core checks the schema, refuses XPath, values on login fields and strings that look like personal data or credentials, and enforces 24 KB per entry (16 KB before 1.15.0) and 30 entries per origin ('invalid_params' naming the field); past 1,000 origins the least recently verified origin is dropped. A put clears stale and counts as a success. Browser host clients only.

Params

field	type	required	description
entry	{ actions?: ({ frames?: ({ origin: string; path: string; selector: string; })[] | null; kind: "click" | "fill" | "select" | "toggle" | "submit"; locators: ({ by: "role" | "label" | "text" | "placeholder" | "testid" | "css"; name?: string | null; role?: string | null; value?: string | null; })[]; loginField?: boolean; name: string; })[]; fingerprint?: string | null; flows?: ({ expect?: "page" | "update" | null; name: string; stats?: { lastRun?: string | null; missed?: number; ok?: number; } | null; steps?: (string | { action?: string | null; intent?: string | null; verb: "fill" | "click" | "select" | "enter"; })[]; })[]; landmarks?: string[]; lastVerified?: string | null; pageType: string; pitfalls?: string[]; recipes?: ({ fields: ({ attr?: string | null; name: string; selector: string; })[]; intent?: string | null; item: string; name: string; stale?: boolean; stats?: { day?: number | null; hits?: number; misses?: number; } | null; })[]; summary?: string; urlPattern: string; }	yes	The entry; upserted by (origin, pageType).
origin	string	yes	Origin the entry belongs to.

Result

field	type	required	description
created	boolean	yes	True when no entry for (origin, pageType) existed.
entryId	string	yes	The entry's id.

skill.create

Direction: client → server

Write a new SKILL.md, generated from a brief or supplied verbatim.

Params

field	type	required	description
content	string | null	no	A complete SKILL.md body. When given, it is validated and written directly — no model turn runs.
description	string | null	no	Natural-language brief. Used only when 'content' is omitted: the daemon starts the same generating turn '/skill create' runs and answers with a turnId rather than waiting for it.
force	boolean	no	Overwrite an existing SKILL.md at the target.
name	string	yes	Skill name; also its directory and the future /<name>.
scope	"project" | "global"	no	Where to write the skill.
sessionId	string | null	no	Draft mode only ('content' omitted): run the generating turn on this existing session instead of creating a headless one. Must be rooted at 'workdir'; invalid_params otherwise. Ignored when 'content' is given.
workdir	string	yes	Project directory the skill is written under (or read/create a session from).

Result

field	type	required	description
name	string | null	no	Skill name, once known.
path	string | null	no	Where the SKILL.md was written.
sessionId	string | null	no	Set alongside turnId: the session the turn ran on — the caller's own 'sessionId', or a new headless one created for 'workdir'.
turnId	string | null	no	Set instead of name/path when generation was started as a turn.

skill.install

Direction: client → server

Install a skill from a path, URL or registry.

Params

field	type	required	description
link	boolean	no	Local plugin directory only: install it as a symlink instead of a copy, so edits are live after skill.reload (development). skill.remove drops the link and leaves the directory alone.
source	string	yes	Path, URL or registry name to install from.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

skill.list

Direction: client → server

List installed skills.

Params

No params (send {}).

Result

field	type	required	description
skills	({ downloads?: number; id?: string; installSpec?: string; installed?: boolean; kind?: "skill" | "agent" | "command" | "plugin"; name: string; rating?: number; source?: string; summary?: string; })[]	no	Installed skills.

skill.read

Direction: client → server

Read a skill's SKILL.md.

Params

field	type	required	description
name	string	yes	Skill to read.
workdir	string	yes	Project directory to resolve a project-scoped skill in.

Result

field	type	required	description
content	string	yes	Its full text.
path	string	yes	Where the SKILL.md was found.
scope	"project" | "global"	yes	'project' or 'global', wherever it was found.

skill.reload

Direction: client → server

Reload skills from disk without restarting.

Params

No params (send {}).

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

skill.remove

Direction: client → server

Delete an installed skill or plugin.

Params

field	type	required	description
name	string	yes	Installed plugin or skill to delete.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

skill.search

Direction: client → server

Search available skills.

Params

field	type	required	description
query	string	yes	Free-text query over skill names and summaries.

Result

field	type	required	description
notIncluded	({ label: string; reason?: string; })[]	no	Hubs the registry has deliberately switched off (not failures). Clients should mention them quietly, never as an outage.
skills	({ downloads?: number; id?: string; installSpec?: string; installed?: boolean; kind?: "skill" | "agent" | "command" | "plugin"; name: string; rating?: number; source?: string; summary?: string; })[]	no	Matching skills.
unavailable	string[]	no	Sources that could not be reached, as ': <reason>'. Empty skills with a non-empty list means offline, not no match.

skill.write

Direction: client → server

Save a skill's SKILL.md verbatim.

Params

field	type	required	description
content	string	yes	Full SKILL.md text to save.
name	string	yes	Skill to write.
scope	"project" | "global"	no	Where to write the skill.
workdir	string	yes	Project directory, when scope is 'project'.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

system.checkUpdate

Direction: client → server

Report whether a newer snowpea release exists; cached for 24h.

Params

field	type	required	description
force	boolean	no	Ignore the 24h cache and ask the network right now.

Result

field	type	required	description
available	boolean	yes	True when latest is strictly newer than current.
cached	boolean	no	True when this came from $SNOWPEA_HOME/update-check.json.
channel	"git" | "pypi"	yes	Where the answer came from: 'pypi' or 'git'.
checkedAt	string	yes	UTC ISO-8601 timestamp of the answer.
current	string	yes	Version of the running daemon (snowpea_core.version).
error	string | null	no	Why the check could not complete; available is false whenever it is set.
latest	string	yes	Newest version found; equal to current when nothing is known.
releaseUrl	string | null	no	Human page for the release, when one exists.
source	string	yes	What an installer would be handed to get 'latest'.

system.health

Direction: client → server

Liveness probe; answers as long as the daemon serves requests.

Params

No params (send {}).

Result

field	type	required	description
status	"ok"	no	Always 'ok' when the daemon answers.

system.hello

Direction: client → server

Authenticate a connection and agree on the protocol version.

Params

field	type	required	description
clientId	string | null	no	Id stable across restarts of this client install (1.6.0). Sessions a previous connection with the same clientId started re-bind to this one.
clientKind	string | null	no	What the client is, e.g. "tui", "desktop", "browser" (1.6.0).
clientVersion	string	yes	Version string of the connecting client.
instanceId	string | null	no	Id of this run of the client (1.6.0).
keepAlive	boolean	no	Keep the daemon from its idle shutdown while this client is connected (1.6.0).
protocolVersion	string	yes	Protocol semver the client speaks; major must match.
token	string	yes	Shared secret read from $SNOWPEA_HOME/token or daemon.json.

Result

field	type	required	description
capabilities	string[]	no	Feature flags this daemon supports.
protocolVersion	string	yes	Protocol semver the daemon speaks.
serverVersion	string	yes	Version of the running daemon.

system.info

Direction: client → server

Report the daemon's version, pid, port, start time and home.

Params

No params (send {}).

Result

field	type	required	description
counters	Record<string, number>	no	Lifecycle counters: sessions, jobs, gateway_bindings, named_agents.
home	string	yes	Resolved SNOWPEA_HOME directory.
lifecycle	{ reason?: string; reasons?: string[]; secondsUntilExit?: number | null; summary?: string | null; willExit?: boolean; } | null	no	Idle-shutdown status, omitted by older daemons.
pid	number	yes	Process id of the daemon.
platform	string | null	no	The daemon machine's sys.platform (darwin, linux, win32), for engine and permission guidance that depends on where the core runs.
port	number	yes	TCP port the daemon is listening on (127.0.0.1 only).
protocolVersion	string	yes	Protocol semver the daemon speaks.
restartRequired	boolean	no	True once system.update finished; the daemon runs the old code until restarted.
startedAt	string	yes	UTC ISO-8601 timestamp of daemon start.
version	string	yes	Daemon version.

system.reloadSettings

Direction: client → server

Re-read settings.json and rebind the daemon's in-memory state.

Params

No params (send {}).

Result

field	type	required	description
changedKeys	string[]	no	Top-level settings sections that changed, e.g. ['providers'].
reloaded	boolean	yes	True when settings.json differed from what the daemon held and the in-memory state was rebound; false when it was already current.

system.restart

Direction: client → server

Shut the daemon down so the next launch runs the newly installed version.

Params

No params (send {}).

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

system.shutdown

Direction: client → server

Ask the daemon to shut down gracefully.

Params

No params (send {}).

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

system.update

Direction: client → server

Upgrade snowpea in a detached subprocess and report progress.

Params

No params (send {}).

Result

field	type	required	description
command	string	yes	The command line that runs, or that has to be run by hand.
error	string | null	no	Why nothing was started; null on the happy path.
log	string	yes	Absolute path of the file the upgrade writes its output to.
started	boolean	yes	True when the upgrade subprocess was spawned.

team.guide.delete

Direction: client → server

Delete a team guide from the project or global home.

Params

field	type	required	description
scope	"project" | "global"	yes	Which copy to delete.
sessionId	string | null	no	Session whose workdir to use when workdir is omitted.
team	string	yes	Team name, or 'default'.
workdir	string | null	no	Project directory.

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

team.guide.get

Direction: client → server

Read a team guide for a project or session.

Params

field	type	required	description
sessionId	string | null	no	Session whose workdir to use when workdir is omitted.
team	string | null	no	Team to read; omit to use the effective team for this session.
workdir	string | null	no	Project directory.

Result

field	type	required	description
effectiveTeam	string	yes	Team name the guide lookup used.
guide	{ description?: string; path?: string | null; persona?: string; routing?: ({ agent: string; known?: boolean; when: string; })[]; source: "project" | "global"; team: string; } | null	no	The guide, if one exists.

team.guide.list

Direction: client → server

List every team guide visible in a project.

Params

field	type	required	description
sessionId	string | null	no	Session whose workdir to use when workdir is omitted.
workdir	string | null	no	Project directory.

Result

field	type	required	description
guides	({ description?: string; path?: string | null; persona?: string; routing?: ({ agent: string; known?: boolean; when: string; })[]; source: "project" | "global"; team: string; })[]	no	Every visible guide.

team.guide.set

Direction: client → server

Write a team guide to the project or global home.

Params

field	type	required	description
description	string | null	no	One-line summary.
persona	string	yes	Persona body to store.
routing	({ agent: string; when: string; })[]	no	Routing rules to store.
scope	"project" | "global"	yes	Where to write the guide.
sessionId	string | null	no	Session whose workdir to use when workdir is omitted.
team	string	yes	Team name, or 'default' for sessions with no active team.
workdir	string | null	no	Project directory.

Result

field	type	required	description
guide	{ description?: string; path?: string | null; persona?: string; routing?: ({ agent: string; known?: boolean; when: string; })[]; source: "project" | "global"; team: string; }	yes	The guide that was written.

team.start

Direction: client → server

Split a task across parallel workers.

Params

field	type	required	description
n	number	yes	Number of workers to run in parallel.
sessionId	string	yes	Session the team works under.
task	string	yes	Task the team splits between workers.

Result

field	type	required	description
teamId	string	yes	Id to poll with team.status.

team.status

Direction: client → server

Inspect a team's task board.

Params

field	type	required	description
teamId	string	no	Team to inspect; empty means the most recent one.

Result

field	type	required	description
state	"running" | "done" | "failed" | "interrupted"	no	Overall state.
task	string	no	The task the team was given.
tasks	({ agentN?: number | null; assignee?: string | null; branch?: string; conflictHunks?: string; conflictSummary?: string; dependsOn?: string[]; note?: string; retries?: number; status?: "pending" | "queued" | "claimed" | "running" | "done" | "conflict" | "merged" | "failed"; taskId: string; title: string; })[]	no	Task board contents.
teamId	string	yes	Team that was inspected.
workers	number	no	How many workers the run was started with.
worktrees	string[]	no	Worker worktrees that exist right now.

tool.invoke

Direction: server → client

Ask the client to run one of its host tools.

Params

field	type	required	description
args	Record<string, unknown>	no	Arguments from the model.
attachments	({ byPath?: boolean; messageId?: string | null; mime: string; name: string; path: string; size: number; })[]	no	Files the user attached in the root conversation (1.23.0), as session.attachments lists them: the paths a host may hand to a page upload.
callId	string	yes	Id of the tool call; tool.progress refers to it.
guard	string | null	no	'agent-switch' while session.setAgent {guardTurn} guards this session or one it was delegated from (1.25.0): a host asks before its own acting tools, whatever tag they were registered with.
job	{ createdVia: "rpc" | "tool"; fingerprint: string; id: string; meta?: Record<string, unknown> | null; ownerClientId?: string | null; runId: string; scheduledAt: string; trigger: "schedule" | "runNow"; } | null	no	The scheduled run behind the root's running turn (1.23.0); set only when origin is 'schedule'. A delegated child reports its root's.
mode	"plan" | "accept" | "auto"	no	The session's mode. A code-running tool registered as 'read' must refuse mutations in plan mode itself and escalate the rest with approval.ask.
name	string	yes	Host tool name.
origin	"human" | "agent" | "member" | "schedule" | "system" | null	no	Who started the root conversation's running turn (1.23.0): the session's own person, the agent, a schedule, another gateway group member or the system. A delegated child reports its root's.
parentSessionId	string | null	no	The session that spawned this one (a subagent's parent); null for a root session. A browser host shares the parent's agent tabs with it.
sessionId	string	yes	Session whose turn called the tool.
turnId	string	no	Turn the call belongs to.
userTurn	{ current?: boolean; messageId: string; steers?: string[]; text: string; } | null	no	The root conversation's latest message the user typed, trusted (1.22.0); 'current' says whether it started the running turn. For a delegated child it is the root's, never the parent agent's task text; only the session's own person's words count (not an agent's, a schedule's or another group member's), and null until the person has typed one.
workdir	string	no	The session's project folder, absolute (Projects, 1.7.0).
workspaceDir	string	no	The session workspace (tmp/, artifacts/); the workdir when it has none.

Result

field	type	required	description
content	({ contentRef?: string | null; data?: string | null; mediaType?: string | null; text?: string | null; type: "text" | "image"; })[] | null	no	Rich result blocks. Images reach vision models as image input; text blocks are appended to output.
error	string | null	no	Error text when ok is false.
meta	Record<string, unknown> | null	no	Extra facts. meta.sensitive=true keeps the output out of the session store ([redacted]), memory and compaction summaries.
ok	boolean	yes	False reports the call as a tool error.
output	string	no	Text result the model reads.

tool.list

Direction: client → server

List the tools registered for a session.

Params

field	type	required	description
sessionId	string | null	no	Scope the listing to one session; omit for the global set.

Result

field	type	required	description
tools	({ category: string; deferred?: boolean; description?: string; name: string; permissionTag: "read" | "write" | "exec" | "network" | "send" | "config" | "delegate" | "secret"; provider?: string; reason?: string; server?: string; source?: string; state?: "active" | "inactive"; })[]	no	Registered tools.

tool.progress

Direction: client → server

Notification: progress of a running tool.invoke, re-emitted as tool.progress.

Params

field	type	required	description
callId	string	yes	The tool.invoke callId this progress belongs to.
message	string	no	Progress text; re-emitted as session.event tool.progress. Any tool.progress, an empty keepalive included, restarts the call's deadline (addendum 15).

Result

field	type	required	description
ok	boolean	no	True when the call succeeded.

tool.register

Direction: client → server

Register tools this connection runs itself (host tools).

Params

field	type	required	description
tools	({ agents?: string[] | null; category?: string | null; deferred?: boolean; description: string; inputSchema?: Record<string, unknown>; name: string; parallel?: "safe" | "never"; permission: "read" | "write" | "exec" | "network" | "send" | "config" | "delegate" | "secret"; timeoutMs?: number | null; })[]	yes	Tools to add or replace for this connection; all-or-nothing.

Result

field	type	required	description
registered	string[]	no	Names now registered.

tool.unregister

Direction: client → server

Remove some of this connection's host tools.

Params

field	type	required	description
names	string[]	yes	This connection's tools to remove.

Result

field	type	required	description
removed	string[]	no	Names actually removed.

usage.summary

Direction: client → server

Token totals from stored usage events, grouped by provider, model, session or day.

Params

field	type	required	description
groupBy	"provider" | "model" | "session" | "day"	no	How to group the totals.
since	string | null	no	UTC ISO start (inclusive).
until	string | null	no	UTC ISO end (exclusive).

Result

field	type	required	description
groupBy	string	yes	The grouping used.
inputTokens	number	no	Sum over all rows.
outputTokens	number	no	Sum over all rows.
rows	({ calls?: number; inputTokens?: number; key: string; outputTokens?: number; })[]	no	Totals, largest first.

web.search

Direction: client → server

Web search for a browser host (1.11.0): the web_search tool's provider chain, settings, caps and timeouts, for the host's own fallback when its search page is blocked. Browser host clients (with a clientId) only; 'unavailable' with details.reason when no provider can answer. Results are untrusted web content.

Params

field	type	required	description
num	number	no	How many results, 1-20 (default 10).
query	string	yes	What to search for.

Result

field	type	required	description
provider	string	yes	The search provider that answered, e.g. 'ddgs'.
results	({ snippet?: string; title: string; url: string; })[]	no

Notifications

approval.pending

field	type	required	description
hostToolsFrom	string | null	no	The session's owning client (addendum 8). A browser profile shows only its own cards and those with null.
request	{ args?: Record<string, unknown>; guard?: string | null; note?: string; requestId: string; risk?: string; scopeHint?: "once" | "session" | "project" | "always" | "site"; sessionId: string; site?: string | null; timeoutSec?: number; tool: string; }	yes	The request now in the shared queue.

approval.resolved

field	type	required	description
by	string	yes	Surface or user that answered.
decision	"allow" | "deny"	yes	The decision that was recorded.
requestId	string	yes	Request that was resolved.

audio.install.progress

field	type	required	description
bytesDone	number | null	no	Bytes transferred so far.
bytesTotal	number | null	no	Total bytes, from Content-Length when the server sends one.
engine	string	yes	Engine being installed, always the bare id.
line	string	no	One line of the installer's output.
percent	number | null	no	0-100 within the stage, when it can be known.
stage	string	no	resolve | download | extract | verify | install | check. 'install' is the package manager, 'verify' is the checksum, 'check' is the detection that runs afterwards.
step	number	no	1-based place of this stage in the sequence.
steps	number	no	How many stages this engine has in total.
voice	string	no	Set when a voice of that engine is installing, e.g. ko_KR-kss-medium; empty for the engine itself. A surface keys its progress row on the pair, so an engine install and a voice install never share a row.

commands.changed

field	type	required	description
commands	({ argsSchema?: Record<string, unknown>; name: string; source?: string; summary: string; })[]	no	The command table as it stands now.
reason	string	no	Why the table changed.

gateway.event

field	type	required	description
bindingId	string	yes	Binding the event belongs to.
kind	string	yes	Event kind, e.g. 'message' or 'error'.
payload	Record<string, unknown>	no	Kind-specific body.

job.event

field	type	required	description
jobId	string	yes	Job the event belongs to.
kind	"started" | "finished" | "failed" | "denied" | "deleted" | "updated" | "waiting_for_host" | "missed" | "notify"	yes	Where the run got to. 'notify' (1.23.0) follows the finish of a job with meta, payload {status, sessionId, text}: its host shows the user a notification.
payload	Record<string, unknown>	no	Kind-specific body.

mcp.changed

field	type	required	description
error	string | null	no	Why the server is in the error state.
name	string	yes	Server name.
removed	boolean	no	True when the entry itself is gone.
scope	"project" | "global" | "plugin" | "settings"	no	Scope the server is declared in.
state	"stopped" | "starting" | "ready" | "error"	yes	stopped, starting, ready or error.
toolCount	number	no	Tools the server currently contributes.

provider.loginProgress

field	type	required	description
expiresInSec	number | null	no	Seconds until the code or session expires, when known.
message	string | null	no	One line for humans.
method	string	yes	Login flow in progress, e.g. 'device_code' or 'oauth_pkce'.
phase	"started" | "await_user" | "polling" | "done" | "failed"	yes	Where the login got to.
userCode	string | null	no	Short code the user types in, for device-code flows.
vendor	string	yes	Vendor being logged into.
verificationUri	string | null	no	URL to open to approve the login.
verificationUriComplete	string | null	no	verificationUri with the code already embedded, when known.

question.pending

field	type	required	description
hostToolsFrom	string | null	no	The session's owning client (addendum 8). A browser profile shows only its own cards and those with null.
request	{ questions?: ({ allowOther?: boolean; header?: string; multi?: boolean; options?: ({ description?: string; label: string; preview?: string; })[]; question: string; secret?: boolean; })[]; requestId: string; sessionId: string; timeoutSec?: number; }	yes	The question now in the shared queue.

question.resolved

field	type	required	description
by	string	yes	Surface or user that answered.
requestId	string	yes	Question that was resolved.

session.event

field	type	required	description
hostToolsFrom	string | null	no	The session's owning client (addendum 8); null for unhosted sessions.
kind	string	yes	Event kind; see sessionEventKinds for the payload schema.
payload	Record<string, unknown>	no	Kind-specific body.
seq	number	yes	Monotonic per-session sequence number.
sessionId	string	yes	Session the event belongs to.
ts	string	yes	UTC ISO-8601 timestamp.

sessions.changed

field	type	required	description
browserProvider	"host" | "local" | null	no	A browser session's browser: 'host' (Snowpea browser only) or 'local' (the user opted in to core's own browser); null for non-browser sessions.
hostToolsFrom	string | null	no	The session's owning client (addendum 8); null for unhosted sessions.
reason	string	yes	create, prompt, turn, renamed, close, ...
sessionId	string	yes	Session that changed.
status	string | null	no	Its status now, when known.
title	string | null	no	Its title, when it has one.

settings.changed

field	type	required	description
keys	string[]	no	Top-level settings sections that changed, e.g. ['providers'].
scope	"global" | "project"	no	Which document was reloaded; "global" for $SNOWPEA_HOME/settings.json.

system.updateProgress

field	type	required	description
message	string	no	One line for humans.
phase	"started" | "done" | "failed"	yes	Where the upgrade got to.

teams.changed

field	type	required	description
reason	string	yes	Why the guide list changed.
team	string | null	no	Team that changed, when known.

tool.cancel

field	type	required	description
callId	string	yes	The tool.invoke callId to stop.
sessionId	string	yes	Session whose turn was interrupted.

session.event kinds

Every session event carries a monotonically increasing per-session seq. After a reconnect, session.resume(sessionId, afterSeq) replays anything missed.

kind agent.changed

field	type	required	description
agent	string | null	no	Agent definition now in force (prompt, tools, rounds); null for none.
kind	"agent.changed"	no

kind audio.spoken

field	type	required	description
kind	"audio.spoken"	no
mime	string	no	Media type of that file.
path	string	yes	Audio file the speech was written to.
played	boolean	no	True when the daemon played it.
provider	string	no	Backend that synthesised it.
utterance	string	no	reply = the turn's answer; ack = the opening acknowledgement the agent writes before its first tool call. A surface may label or skip an ack; one that does not know the field treats everything as a reply.
voice	string | null	no	Voice that was used.

kind backend.changed

field	type	required	description
backend	"local" | "docker" | "ssh"	yes	Where tools now execute.
kind	"backend.changed"	no

kind checkpoint.restored

field	type	required	description
checkpointId	string | null	no	Undo checkpoint for the restore, null when none was written.
kind	"checkpoint.restored"	no
restored	string[]	no	Paths restored.
skipped	({ path: string; reason: "changed_since" | "not_restorable" | "missing_blob" | "excluded"; })[]	no	Paths skipped and their reasons.

kind checkpoint.updated

field	type	required	description
checkpoint	{ createdAt: string; files?: ({ afterSha?: string | null; beforeSha?: string | null; path: string; restorable?: boolean; size?: number; skipped?: "too_large" | "excluded" | "unreadable" | null; source: "tool" | "shell"; status: "modified" | "created" | "deleted"; })[]; id: string; kind: "turn" | "restore"; prompt?: string; sessionId: string; turnId?: string | null; workdir: string; }	yes	The whole checkpoint manifest so far.
kind	"checkpoint.updated"	no

kind command.progress

field	type	required	description
command	"ralph" | "ultrawork"	yes	Command reporting.
iteration	number	no	0 for the plan, then 1, 2, ….
kind	"command.progress"	no
outcome	string | null	no	Set on the last event only: ralph 'complete', 'rejected', 'stopped', 'max_iterations' or 'error'; ultrawork 'complete' or 'partial'.
stories	({ id: string; note?: string; status: "pass" | "fail" | "pending"; title: string; })[]	no	Every story, in plan order.

kind compaction

field	type	required	description
after	number	no	Estimated tokens the history holds now.
auto	boolean	no	True when the auto-compaction threshold triggered it.
before	number	no	Estimated tokens the history held before.
kept	number	no	Messages kept verbatim after the summary.
kind	"compaction"	no
summaryChars	number	no	Length of the summary in characters.

kind compaction.started

field	type	required	description
before	number	no	Estimated tokens the history holds now.
kind	"compaction.started"	no
reason	"manual" | "auto"	no	auto = the auto-compaction threshold triggered it.

kind context

field	type	required	description
estimated	boolean	no	True while 'used' is a local estimate; false once the provider reported it.
kind	"context"	no
model	string | null	no	Model the window belongs to.
percent	number | null	no	used/window as a percentage, null when the window is unknown.
provider	string | null	no	Vendor serving that model.
used	number	no	Tokens the current prompt occupies.
window	number | null	no	Context window of the model in tokens; null when unknown.

kind diff

field	type	required	description
kind	"diff"	no
patch	string	yes	Unified diff of the change.
path	string	yes	File that changed.

kind error

field	type	required	description
code	string	yes	One of the protocol error codes.
kind	"error"	no
message	string	yes	Human-readable detail.

kind hook.continue

field	type	required	description
count	number	yes	How many times Stop hooks continued this turn so far.
kind	"hook.continue"	no
reason	string	yes	The hook's instruction, handed to the model.

kind job.done

field	type	required	description
jobId	string	yes	Job that ran.
kind	"job.done"	no
sessionId	string | null	no	Session the run used.
status	string	no	Job status as the scheduler recorded it.
text	string	no	What the run reported.

kind job.failed

field	type	required	description
jobId	string	yes	Job that ran.
kind	"job.failed"	no
sessionId	string | null	no	Session the run used.
status	string	no	Job status as the scheduler recorded it.
text	string	no	What the run reported, or the error.

kind loop.suspected

field	type	required	description
count	number	no	Repeats seen in the last 20 tool calls.
kind	"loop.suspected"	no
tool	string	yes	Tool whose call repeated.

kind lsp.diagnostics

field	type	required	description
count	number	no	Diagnostics of every severity.
errors	number	no	How many of them are errors.
kind	"lsp.diagnostics"	no
path	string	yes	File the diagnostics are about.
warnings	number	no	How many of them are warnings.

kind message.delta

field	type	required	description
kind	"message.delta"	no
text	string	yes	Text fragment to append to the current message.

kind message.done

field	type	required	description
continuations	number	no	How many times the turn was resumed after hitting the output limit.
kind	"message.done"	no
messageKind	"" | "interrupted"	no	Optional message classification inside the message.done payload, for example 'interrupted' for the post-stop system note.
role	"assistant" | "user" | "system"	no	Who produced the message.
text	string	yes	Full message text.
truncated	boolean	no	The answer still hit the output limit and is incomplete.

kind message.reasoning

field	type	required	description
chars	number	no	Characters of reasoning so far in this turn.
kind	"message.reasoning"	no
text	string	no	Reasoning fragment; not part of the answer.

kind message.user

field	type	required	description
attachments	({ kind?: "file" | "image" | "text" | "page"; name?: string; title?: string | null; url?: string | null; })[]	no	Files sent along with the prompt.
expansion	{ kind?: "skill" | "command"; name: string; text: string; } | null	no	Set when text is a skill command: the skill body the model was given instead. Surfaces show it folded, like a tool call, not inline.
kind	"message.user"	no
refs	(Record<string, unknown>)[]	no	Resolved @ references (path, kind, lines, truncated).
steered	boolean	no	True when this prompt was queued behind a running turn and then folded into that same turn before its next model call.
text	string	yes	Prompt text as the user typed it.

kind mode.changed

field	type	required	description
delegation	boolean | null	no	Whether delegation mode is now in force, sent when /delegation changes it; absent when only the permission mode moved.
kind	"mode.changed"	no
mode	"plan" | "accept" | "auto"	yes	Mode now in effect.

kind model.changed

field	type	required	description
effort	"low" | "medium" | "high" | "max" | null	no	Effective reasoning effort for the session (CORE-effort).
effortSource	"session" | "model" | "vendor" | "default" | null	no	Rule that decided the effort: 'session', 'model', 'vendor' or 'default'.
efforts	("low" | "medium" | "high" | "max")[] | null	no	Tiers this model offers, weakest first; [] means it has no effort setting (effort is then null). E.g. Qwen3.8 Flash Next offers low, medium, high.
kind	"model.changed"	no
model	string | null	no	Model id now in effect.
provider	string | null	no	Vendor now in effect.

kind plan.updated

field	type	required	description
done	number	no	Steps marked done.
kind	"plan.updated"	no
next	string | null	no	The next pending step as 'S3 <title>'; null when none is left.
path	string	yes	The plan file, relative to the workdir.
status	"active" | "done" | "archived"	yes	Where the plan stands.
title	string	yes	The plan's title.
total	number	no	Steps in the plan.

kind subagent.done

field	type	required	description
agentId	string	yes	Subagent that finished.
budget	number	no	Tool-round budget cap.
deniedCalls	number	no	How many child tool calls were denied in this run.
deniedTools	string[]	no	Unique names of tools whose calls were denied.
kind	"subagent.done"	no
name	string	no	Named agent that ran, when there was one.
ok	boolean	no	False when it failed.
reason	string	no	Why it ended: complete, budget, timeout, error, interrupted or denied.
result	string	no	Final report.
rounds	number	no	Tool rounds used by the subagent.
sessionId	string | null	no	The subagent's own session.
status	"queued" | "running" | "done" | "error" | "interrupted"	no	Terminal state: done, error or interrupted.
summary	string	no	The subagent's final answer.
title	string	no	One-line label for the delegation, written by the delegating model in the user's language; empty when it wrote none.
usage	{ inputTokens?: number; outputTokens?: number; }	no	Tokens the subagent consumed.

kind subagent.spawn

field	type	required	description
agentId	string	yes	Id correlating this subagent's events.
kind	"subagent.spawn"	no
name	string	no	Named agent that was spawned.
sessionId	string | null	no	The subagent's own session, once it has one.
status	"queued" | "running" | "done" | "error" | "interrupted"	no	State at spawn: queued until a concurrency slot frees up.
task	string	no	Task it was given.
title	string	no	One-line label for the delegation, written by the delegating model in the user's language; empty when it wrote none.

kind subagent.update

field	type	required	description
agentId	string	yes	Subagent reporting progress.
kind	"subagent.update"	no
lastText	string	no	Most recent text the subagent produced.
name	string	no	Named agent that is running, when there is one.
sessionId	string | null	no	The subagent's own session.
status	"queued" | "running" | "done" | "error" | "interrupted"	no	Lifecycle state.
text	string	no	Human-readable progress text.
title	string	no	One-line label for the delegation, written by the delegating model in the user's language; empty when it wrote none.
usage	{ inputTokens?: number; outputTokens?: number; } | null	no	Tokens the subagent has used so far, cumulative; sent with every update so a surface can show a long delegation is still moving.

kind team.task.update

field	type	required	description
agentN	number | null	no	1-based worker index that owns the task.
assignee	string | null	no	Worker that owns the task.
kind	"team.task.update"	no
retries	number	no	How many times a merge conflict re-queued it.
status	"pending" | "queued" | "claimed" | "running" | "done" | "conflict" | "merged" | "failed"	no	New state.
taskId	string	yes	Task that changed.
teamId	string	yes	Team the task belongs to.

kind todos.updated

field	type	required	description
kind	"todos.updated"	no
todos	({ content: string; id: string; status: "pending" | "in_progress" | "completed"; })[]	no	The whole list, in order.

kind tool.call

field	type	required	description
args	Record<string, unknown>	no	Arguments supplied.
callId	string	yes	Id pairing this call with its tool.result.
kind	"tool.call"	no
name	string	yes	Tool being called.

kind tool.progress

field	type	required	description
callId	string	yes	Id of the tool.call this output belongs to.
chunk	string	no	Raw output fragment, in order.
kind	"tool.progress"	no
name	string	yes	Tool that is running.
seq	number	no	0-based index of this progress within the call.
stream	"stdout" | "stderr"	no	Which stream the chunk came from.
truncated	boolean	no	True on the final progress when the byte cap stopped the tail.

kind tool.result

field	type	required	description
callId	string	yes	Id of the matching tool.call.
content	({ contentRef?: string | null; data?: string | null; mediaType?: string | null; text?: string | null; type: "text" | "image"; })[] | null	no	A host tool's content blocks: text inline, images as contentRef (session.toolContent). Absent for sensitive results (1.7.0).
error	string | null	no	Failure detail when ok is false.
kind	"tool.result"	no
meta	Record<string, unknown> | null	no	Host-tool facts for surfaces (e.g. pages for page preview cards); not shown to the model. Forwarded as the host gave it, also for sensitive results; dropped above 16 KB (addendum 13).
name	string	yes	Tool that ran.
ok	boolean	yes	False when the tool failed.
output	string	no	Output handed back to the model.

kind turn.dequeued

field	type	required	description
kind	"turn.dequeued"	no
queued	number	no	Prompts still waiting after this one left.
reason	"started" | "dropped" | "steered"	no	started = it is now running, dropped = it was discarded, steered = it was merged into the running turn.
turnId	string	yes	Turn id that left the queue.

kind turn.done

field	type	required	description
kind	"turn.done"	no
reason	"complete" | "interrupted" | "error" | "denied" | "timeout" | "budget" | "stalled" | "empty_response"	no	Why the turn ended. budget = the tool-round budget ran out; the turn reported what it had done before ending. stalled = consecutive rounds made no new tool or file progress. empty_response = the model ended with no text and no tool call, again after one nudge (1.23.0); an error event with code empty_response precedes it.
synthetic	boolean	no	True when the daemon wrote this event itself to close a turn a crash left open, rather than the turn reporting its own end (CORE-dangling-turns). The turn produced no further output after the events already stored.
turnId	string	yes	Turn that ended.

kind turn.queued

field	type	required	description
kind	"turn.queued"	no
position	number	yes	1-based place in the queue behind the running turn.
queued	number	yes	Prompts waiting in the queue after this one was added.
turnId	string	yes	Turn id assigned to the queued prompt.

kind turn.started

field	type	required	description
initiator	"user" | "system"	no	Who started the turn (1.8.0). 'system' = session.continue: the input is a [system] note, no message.user is emitted, and surfaces show a status line instead of a user bubble.
kind	"turn.started"	no
prompt	string | null	no	The prompt that opened it; null when there is none.
queued	boolean	no	True when this turn waited in the prompt queue first.
reason	string | null	no	Why a system turn started, e.g. 'handback' (1.8.0).
turnId	string	yes	Turn that is now running.

kind usage

field	type	required	description
cachedInputTokens	number | null	no	Of inputTokens, how many the server answered from its prompt cache, when it reports that (1.20.0).
inputTokens	number	no	Prompt tokens consumed.
kind	"usage"	no
model	string | null	no	Model that served the call (1.7.0).
outputTokens	number	no	Completion tokens produced.
provider	string | null	no	Vendor that served the call (1.7.0).
timings	Record<string, number> | null	no	llama.cpp's own timings when the server sends them (1.25.0): prompt_n, prompt_ms, cache_n, predicted_n, predicted_ms. A first token much later than prompt_ms was spent waiting for a slot.

Error codes

Returned as the string error.data.code of a JSON-RPC error response.

The numeric error.code: -32601 means only that the method does not exist (method_not_found), so a client can feature-detect an older daemon by it; a missing session, job, memory, content or other entity is -32004 (not_found, mcp_not_found); -32602 invalid params; -32603 internal; -32000 everything else. Before protocol 1.7.0 a missing entity also answered -32601.

code	meaning
approval_denied	The user denied the approval request.
approval_timeout	No approval arrived before approvals.timeoutSec elapsed.
auth_expired
empty_response
internal	Unexpected server-side failure.
invalid_output
invalid_params	Params failed schema validation.
login_unsupported	The vendor does not support the requested login method.
mcp_exists
mcp_invalid
mcp_not_found
mcp_read_only
mcp_start_failed
mcp_unsafe
method_not_found	No such method (-32601).
mode_denied	The session mode forbids this tool or action.
not_found	No such session, request, job, agent or content (-32004).
not_implemented	Defined in the schema but not implemented in this milestone.
protocol_incompatible	Client and server protocol majors differ.
session_busy
tool_inactive	The tool exists but is disabled for this session.
unauthorized	Missing or invalid token, or a call before system.hello.
unavailable