zidane/ipc/browser

The JSON-RPC error code (IpcErrorCode names zidane's own).

The error's data, when it had some (a Forbidden refusal's required scope).

The client's state when the call failed: refused names why, for good.

Why it failed.

The HTTP status, when the server answered.

Calls a method on the host.

Hears the host's signals; returns the unsubscribe.

Output as it arrives.

Stops the run on the host.

The extension names the source holds.

The installer's error code: name-mismatch, multiple-candidates or no-extension.

Tells the host what this window shows (send on focus and session change).

Where each item of a catalog (kind) comes from, for a folder.

The commands and keymap modes extensions register.

The extensions of a folder (status, tui entry, ui bundle), and when to list them again.

The integrations extensions declare, and their connections.

The extensions' link handlers.

Hears each event an extension's RPC contract emits.

Calls an RPC method. Rejects with RpcCallError when the call fails (rpc.forbidden: the method's scope is above this connection's token).

Answers the dialogs and UI requests the host routes to this window.

The extensions' settings, with where each value comes from.

Sources of extensions: what one holds, and moving an installed extension to another.

The extensions' synced storage.

The UI items of extensions and the callbacks they register.

Hears every signal the host sends.

Sends an IPC request and resolves with its result.

Runs a UI request (panel, navigate, composer); resolves with its result (boolean, or the open panel ids). notify resolves nothing.

Shows a dialog; resolves with the raw answer (undefined: cancelled). signal aborts when the host gives up on it. A form dialog calls validate(key, value) as the user edits a field and before answering, and shows the message (null: valid) under the field. Answer only once every field validates: the host checks the answer again, and an invalid one makes the extension's form reject.

daemon.info only: a run, compaction, / command or background task is in flight on this host (open terminals do not count). zidane server wait-idle waits for false before a restart. Additive.

How to get an admin token on this zidane-server: the commands to run on its machine, with its own binary, user and data dir (<device> is the name to fill in). token prints a token to paste into an app; pair prints a code for a browser. Absent: not a zidane-server. Additive.

zidane version of the host.

Build fingerprint of the host code. 'unknown' in compiled binaries.

Clients may clone repositories into its workspace roots (git.clone). A zidane-server's allowClone; a local host always does. Absent: an older host, where git.clone needs an admin token. Additive.

Version of the zidane code the host runs.

Clients may create folders in its workspace roots (fs.mkdir). A zidane-server's allowCreateFolders; a local host always does. Absent: an older host, without fs.mkdir. Additive.

The host process's home folder (os.homedir()). Clients show it as ~ in the paths they display; nothing else reads it. Absent: an older host. Additive.

Host identity (additive). hostId is a UUID persisted once in the host's data dir, so it survives restarts; the in-process host and the local daemon share the data dir, and so the id: they are the same computer.

What kind of host this is.

Display name of the host.

This server lends itself as a machine to the hosts of its clients (machine.attach, allowAsMachine on). Absent: it doesn't. Additive.

The methods this connection may call on this host: the ones it handles, within scope. Clients show what is offered instead of failing on what isn't. Additive.

The oldest version the host still speaks (IPC_MIN_PROTOCOL_VERSION). Additive.

The version this connection speaks: the lower of the client's and the host's. Additive: absent, the connection speaks protocolVersion.

Process id of the host.

This host runs terminals without a session (terminal.openInProject and the other project / draft terminal methods). Absent: sessions only. Additive.

Protocol version the host speaks.

This server takes installs and removals from its clients (catalog.install / remove / update, mcp.upsert / remove; allowRemoteInstalls on). Absent: it doesn't (or predates them). Additive.

The daemon is older than a client that attached while it had active work: it accepted the handshake instead of draining (which would abort those runs) and exits once idle. Clients attach normally; their reconnect path lands on a fresh daemon after the exit.

The client scope this connection's token grants (./scopes): calls above it are refused. Absent: every method (a local window). Additive.

Names this host process's signal numbering (SIGNAL_SEQ_FIELD): a position from another epoch cannot be resumed. Additive.

Start time of the host process, epoch ms.

This server takes settings sync from a client's computer (sync.*). Absent: it doesn't. Additive.

The sync categories it takes. Absent with sync: the ones before environments. Additive.

The agent profiles cwd offers ('': no folder), as the agent picker lists them: a profile a setting turns off (Codemode) is left out. Additive.

Denies every pending approval, or only those of sessionId when given.

Lists the approval requests waiting for an answer.

Answers a pending approval request with a decision.

The badges under sessions' titles (commits, pull requests, extension kinds with a badge), for up to ARTIFACT_BADGES_MAX sessions at once, keyed by session id. Each session's badges come from the extensions of the folder its newest artifact landed in. They change with the session's artifact:recorded / artifact:changed and with catalog:changed (extensions): read them again then. Additive.

Remove one artifact. false when the store has no artifact support. Fans out artifact:changed.

Artifacts across sessions, filtered by project root (null = untagged sessions, omitted = every project) and/or kind/uri (reverse lookup).

Re-resolves one stored artifact (is the pull request merged?): its kind's resolve() runs on the host, with the extensions of the folder the artifact landed in. A change is stored and fans out artifact:changed. force asks past the kind's own freshness window. null when nothing changed (no resolver, nothing new, an unknown artifact). Additive.

Upsert an artifact — the lazy resolve() write-back (refreshed label / meta). Same merge semantics as SessionStore.upsertArtifact; null when the session is unknown or the store lacks support.

Stores a provider's API key and its custom fields (a local server's URL, a cloud's region; onboarding.providers lists them), merged into the stored credential: a field left out keeps its value, an empty one is removed (a blank secret keeps the stored one), a required one may not be emptied, no value keeps the stored key. Additive.

Abandon a flow of this connection.

Deliver the code (code + state from the loopback, or input: what the user pasted) once, then wait for the host's token exchange; without either, just wait (device and polling flows). A wrong state or another connection's flow is refused. Tokens stay on the host: the result says what changed, never a secret.

Answer the step a flow is waiting on (HostOAuthBegin.step before its URL, HostOAuthComplete.step after): a select's option id (none: cancel), a prompt's text. Answers with where the flow is now: its URL, or the next step. Then complete as before. Additive.

Remove one stored credential (account: its key from auth.status) or, without one, every stored credential of the provider; then as auth.setApiKey. A key the host only has from its own environment is left alone. Additive.

Rename a stored OAuth account (account: its key from auth.status). Presentation only: nothing is rebuilt. Additive.

Store an API key for one of the host's providers as its active credential, apply it to the host's environment, and rebuild agents (idle now, busy ones at run end). Returns the provider's new status. OAuth sign-in goes through auth.oauth.*. Additive.

Make one of a provider's stored credentials the active one (target: an account key from auth.status, or the first stored one of a source), then as auth.setApiKey. A credential no longer stored is refused. Additive.

The host's provider credentials, as the host's agents use them (its data dir's credentials.json and environment): per provider, whether something is configured, its stored API key / OAuth accounts (labels, which is active) and an env var it reads. Never a secret. Additive.

The extensions' items (ctx.registerBadgeActions) of a badge's menu in cwd; the built-in ones are the client's. Additive.

Runs an extension's badge item; the effect (copy, open, a notice) is the client's to apply. Additive.

Dev browser: a window offers to host the pages the agent's browser_* tools drive (the GUI's main process). Released when the connection drops. It then answers each browser:request signal addressed to it.

Answers a browser:request signal with the host's result.

Withdraws a window as dev browser host.

Extensions installed for cwd.

Install a skill or an extension on the host, in its user's scope only (scope may only be 'user'): a GitHub (owner/repo[#ref][:dir], a GitHub URL, a skills.sh URL) or npm spec; paths are refused. skills / all pick from a multi-skill source (the multiple-candidates error lists them), extension from a multi-extension one (an extension's multiple-candidates or no-extension error carries the names found as ExtensionInstallErrorData). Runs the host's package managers and fetches code there: a zidane-server's allowRemoteInstalls gates it, every attempt is audited. Bounded in time; the progress lines come back with the result. Every window gets catalog:changed. Additive (remoteInstalls on ipc.hello).

MCP servers: env and headers values, URL credentials and query values are redacted.

Plugins installed for cwd, with what each contributes.

Remove a user-scope skill or extension of the host by name (its directory). As catalog.install.

What the host discovered for the settings tabs, each entry with whether the host's settings enable it (an unset allowlist enables everything). cwd adds the project scope of that folder (inside the workspace roots on a server); without it, the user scope (the host user's home). The enabled lists are written with settings.set. Installing, removing and MCP sign-in stay on the host's machine. Additive.

Update a user-scope extension installed from a source. As catalog.install.

Cancels one tracked work item by id, or every visible item with "all". Resolves true when something was cancelled. reason is passed to a cancelled tool call.

What became of a send, by its requestId, its clientMessageId, or both: the send request record, then the last announced delivery:changed state, then the queue and the transcript (origin.messageId). Resolves a send answered "already accepted" (SendRequestPendingError). state: the last known DeliveryState, or unknown when the host holds no trace. runId: the run that took it, when known. settled: nothing more will happen to it: a final state (answered, failed, interrupted, dropped), or, with unknown, it is in neither the queue nor the transcript and the send request record says no send of it runs (it never landed: send it again with a new requestId); without a requestId an unknown is never settled. Additive.

Aborts the session's live run. Does nothing when no run is live.

Resolves true while the session has a live run.

Lists the tool calls and background tasks the session's live run tracks and can cancel. Empty when no run is live. children: true adds the subagents' running calls (childId set), for their starts: a transcript read from disk times them too. Older hosts ignore it.

Delivers a queued message. Steers a live run, otherwise starts a run or runs it as a command. delivered says which path it took. keepDraft keeps the shared composer draft instead of clearing it on the other clients. The message goes through the prompt interceptors first, as chat.send; consumed says one took it (delivered is then send for handled, steer otherwise). Additive.

Retire the session's live agent so the next run rebuilds against fresh config/credentials (MCP login, extension reload). Run-end deferred when a run is in flight; HITL/queue state survives.

wake is host-internal (see SendOptions.wake) — not accepted over the wire. requestId: see SendRequestId. The prompt goes through the extensions' prompt transforms and prompt interceptors of the session's folder first, once per submission, on the host (clients never run them). consumed says one took it instead of a run (runId is then ''): handled (an extension consumed it), steer / followUp (delivered to the live run). Additive.

What ~/.claude on the host holds: whether there is a setup, and its transcripts for cwd and in every project. Additive.

What each piece of the Claude Code import would copy and skip. Additive.

Imports a Claude Code setup into the host's own places: conversations into its session store, MCP servers, skills, commands and subagents into the host user's files. Idempotent (what is there is skipped, never overwritten). It copies commands the host will run: a zidane-server's allowRemoteInstalls gates it, every attempt is audited. Every window gets catalog:changed. Additive.

Argument suggestions for /name <prefix> — best-effort, empty on failure.

Extension-contributed / commands discovered for cwd.

The extension completion providers (ctx.registerCompletionProvider) of cwd a composer can render: a one-character trigger each, @ / # left to the built-in completers, first wins on id and trigger. Additive.

Runs the providers' submit hooks (resolveReferences, onSubmit) on a prompt about to be sent; resolves after them, or after 5 s. Additive.

Daemon identity and version: protocolVersion, appVersion, pid, startedAt and the host identity fields of the hello result.

The processes the daemon started for its own work (MCP servers, bounded tool runs such as git and linters), which lead their own process group like a session's command does. The desktop app's performance monitor counts them as the app's. Additive: an older daemon answers "method not found", read as none.

The processes the daemon started for a session (its shell tool's commands and background tasks, its terminals, its own MCP servers), by session id. The desktop app's performance monitor shows what each session uses. Additive: an older daemon answers "method not found", read as none.

Send one tiny decision with this host's credentials, to check a decision model works. model is "providerKey/modelId", tested exactly; omitted = the host's Settings.decisionModel (or the first available). Never fails: a broken model comes back as ok: false with a reason. Additive.

Current shared draft for a session — backfill on window attach.

Replace the shared draft's composing attachments (notification).

Every environment kind the host can create, described for a new session in cwd (availability, default, branch suggestion, options — secrets only as "configured"). What pickers and the Environments settings render. kind: a machine kind (local@laptop) says cwd is that machine's folder, checked against its roots instead of this host's (docs/MACHINES.md § Folders); the same on commands.*, catalog.* and models.list. Additive.

Apply one Environments-settings edit (enable, default, options, secrets), validated against the kind's schema. Settings changes fan out as settings:changed; secrets are stored host-side and never returned.

"Test connection" for a kind with its current options.

The action rows (registerConfigItem type 'action') the enabled extensions declare for cwd. Additive.

The actions' passive status() probes, keyed extension:key; a probe that throws or takes over 3 s is left out. Additive.

The extensions of a source (owner/repo[#ref][:dir], a GitHub URL, an npm package, or a folder on the host), read from their manifests by the host with its GitHub login; nothing runs. Never fails for an unreadable source: the listing carries error (the default source Tahul/zidane then lists the native catalog, builtin: true). Each row's install is what catalog.install takes (spec, extension). Additive.

Which catalog items of cwd extensions added, changed or removed, with the extension that did it (Settings shows it). Additive.

Install an installed extension again from another source (GitHub or npm): the source must hold an extension of the same name (else the name-mismatch install error, its data an ExtensionInstallErrorData with the names found); the folder is replaced only once the new copy validated, and .install.json records the new source, which catalog.update then follows. A zidane-server takes scope: 'user' only, gated and audited as catalog.install. Additive.

Runs a command by its published id (an extension command or a built-in). false when nothing ran. Additive.

The extension commands of cwd with their effective bindings, scopes and modes, and the keymap mode on top for sessionId. Additive.

The options the enabled extensions declare for cwd (registerConfigItem), without the action items or the callbacks; the values live on the settings' extensionConfig. Additive.

Scaffolds a new extension and reloads the registries: in the host user's extensions folder (scope: 'user', the default), or in a project (scope: 'project': cwd's checkout, which must lie in the workspace roots; it loads once the project is trusted). Sessions stay in the roots: one may open in a project extension's folder, never in a user extension's. It writes code the host will run: a zidane-server's allowRemoteInstalls gates it, every attempt is audited. Every window gets catalog:changed. Additive.

The extensions of cwd: status, folder, tui entry and compiled ui bundle. What a window draws extensions from in daemon mode, without running their setup. extensions:entries says when to list again. Additive.

Connects with an API key: verified by the extension, then kept in the credentials file. Additive.

Removes the connection of account, or every connection of the integration when it is absent. Additive.

Answers a flow step that asked for input (inputId). value absent cancels the flow. Additive.

The extension integrations of cwd (ctx.integrations.register) and their connections. Additive.

Makes the connection of account the integration's default. Additive.

Runs an OAuth or command method. Its steps (open this URL, enter this code, paste the redirect) come to this connection as extensions:integration-flow with the returned flowId; the call resolves when the flow ends. Additive.

Every command of cwd with its effective bindings, scope and mode (ctx.keymap.list), and the active mode stack for sessionId (ctx.keymap.active). Additive.

Pops a mode this connection pushed. Additive.

Activates a keymap mode on the host for cwd (as ctx.keymap.mode.push) until extensions.keymap.pop or this connection closes. Returns its handle. Additive.

Offers a link the user opened to cwd's extensions' link handlers (LinkHandler), higher priority first; a handler that returns false, throws or times out passes it on. handled: false: open it the app's own way. Apps call it for every link they open, except with Alt held. Additive.

Runs an action on the host. The config patch it returns comes back sanitized, not written: the client saves it (settings.set). One run of an action at a time. A token needs the action's scope (the action row's scope; default, and for config-declared actions, admin). Additive.

The extensions' settings of cwd with values, locks and the layer each value comes from. sessionId adds that session's layer. Additive.

Writes one extension setting at a scope: user in the settings file, project in the project's extension-settings.json, session in memory; a secret goes to the credentials file, never a settings file. Refused for a locked, unknown or action key, a scope the setting doesn't allow, or a value that fails its checks. Additive.

Everything stored at a location of cwd's extension storage, and the project root its project/session files live under. Additive.

Writes (or, value absent, deletes) one storage entry. The extensions holding it see the change at once; every other connection gets extensions:storage. A stores write must be a { v, value } record of the store's version whose value passes its schema (checked against every runtime of the folder holding the store); otherwise it is refused and nothing changes. The result says which, with the entry as the host holds it now, for the client to reconcile. Additive (the result was void).

Runs one callback of a UI item by its id (a panel's load / onAction, a reference resolve, a badge menu or action, a settings page action, status or check). Callbacks run on the host under their extension's guard. Additive.

Every UI item of cwd's extensions, per token, in wire form, and each active extension's compiled ui bundle (bundles, by extension id). extensions:ui pushes each change after it. Additive.

Runs the project's own linters and typecheckers on paths (relative to cwd), cached until the files move. disabled: tool ids switched off; timeoutMs: per tool.

Drops the cached diagnostics of cwd: the next run checks again.

The diagnostics tools and whether each runs for cwd (configured, missing its binary, not used).

The files under cwd and the folders holding them, as @ completes them: git's list (ignore rules kept), else a walk; capped.

Where cwd sits: its git checkout (the folder itself outside git) and its project (the main checkout for a worktree).

Lets this connection's media play from GET /zidane/media (SERVER_MEDIA_PATH): ?ticket&cwd&path serves a file of a folder in the workspace roots, &side=old|new one side of its git change, with byte ranges, for an image, a video or audio only. The client picks the ticket (at least 32 random URL-safe characters) so an address is known before the call lands; it is good while this connection is open and carries its token's scope. One per connection: a new one replaces it. Only a zidane-server serves media. Additive.

What names in prose point at (files, folders, else branches), in order: what a transcript's path chips open.

Lines containing query (fixed string, at most 500 characters) under cwd: ripgrep, else git grep, else a walk. A later search with the same searchId on the connection cancels this one.

The folders in path (default: the first root), for a folder picker on the host's machine. Only inside the roots (real paths: .. and symlinks out are refused), no dotfiles. Additive.

Creates folder name in parent (inside the roots, real paths: .. and symlinks out are refused). name is one path segment and does not start with a dot. Refused when the host turns it off (a zidane-server's allowCreateFolders, the hello's createFolders). Additive.

Where this host lets a session's folder be: a server's workspace roots (confined: sessions.create / setFolder refuse anything outside), or the user's home on a local host (unconfined). Additive.

The folders whose name holds query (case-insensitive), in path and below it (default: every root). Bounded: four levels down, 200 results, no dot folders, no node_modules, symlinks not followed. truncated: the result or read bound cut the search short. Additive.

The local branches, most recently committed first, each against the default branch.

branch's open (or draft) pull request, or null. fresh: past the cache.

Switches the checkout to a branch or a pull request ({ pr }, through gh). Never forced; refused while an agent runs in the checkout (sessionId: the asking session, counted too). A branch another worktree holds is git's refusal plus that worktree and its sessions (sessionId left out).

Clones input (a git or forge URL, or owner/repo) into a new folder of parent (inside the roots). A folder already holding that repository is answered as existed. One clone per connection; git's progress comes as git:clone:progress signals to the caller only. A dropped connection cancels it. Refused when the host turns cloning off (a zidane-server's allowClone, the hello's clone).

Cancels this connection's clone: the half-cloned folder is removed and git.clone answers cancelled.

One commit's facts, for a sha chip; null when the repository has no such commit.

Starts branch name from the current checkout and switches to it; refused while an agent runs in it.

The working tree against HEAD as a unified patch (untracked files as new files), the whole checkout or one path, with context lines (absent: 3; null: whole files).

Each changed path's status against HEAD, untracked files included.

Open pull requests (gh): waiting on you, yours, then recent others; search searches every open one. null without gh (or signed out); rateLimited while GitHub refuses and nothing is cached.

Where the checkout stands (branch, upstream, ahead / behind, uncommitted changes); null outside a checkout.

Pulls (merging) then pushes the current branch, or publishes it without an upstream; refused while an agent runs in it.

Releases one git.watch of cwd by this connection.

Follows cwd's checkout: once its refs move (a commit, a fetch, a push, a branch switch, from this host or any other process), this connection gets git:refs for cwd. false: not a repository, nothing watched. Calls count: each git.watch takes one git.unwatch; a dropped connection releases its own. Additive.

Cross-session content search, daemon-side. One RPC replaces a window's per-session index/build/search round-trips — indexes are built once in the daemon and shared by every window.

Transcript search over ONE session, daemon-side. The daemon owns the authoritative turns (live wrapper when an agent is active — fresh mid-run, which a window's load-time snapshot is not) and an LRU index cache shared by every window, so repeat queries pay match cost only. Results come back in TURN ORDER (search is a transcript filter).

What this host can do: OS, tools on PATH, sandbox, environment kinds, what it allows. Cached a minute; refresh probes again.

Install a missing tool on this host, as the host's user, when it can without root (toolInstall says run). Then probes again: capabilities is the new answer.

The integrations registered on this host, in registration order. Additive.

Report an integration this client runs (a channel). Registering a name again from the same connection replaces it; a name another live connection registered is refused. It goes away when this connection closes. Every window gets integrations:changed. Additive.

Change the state of an integration this connection registered; detail replaces the previous one (absent clears it). Additive.

Cancels a pending interaction. reason is passed back to the agent.

Lists pending interactions (questions and prompts the agent asked the user), optionally for one session.

Re-sends the session's pending interactions, for a client that connected after they were raised.

interactions.rehydrate for each of sessionIds not running on this host, loading only those whose run waits to be resumed or whose last turns hold an unanswered question or plan (a channel start, over every conversation it had).

Answers a pending interaction.

A zidane-server's recent log records, oldest first: its own lines and its extensions' (setup, runtime warnings), from a bounded in-memory buffer. Other hosts refuse it. Additive.

Release one logs.watch of this connection.

Follow the log: this connection gets logs:record for each new record. Calls count; a dropped connection releases its own. Additive.

Reverse direction (docs/MACHINES.md § Reverse direction): a client asks this server to lend itself as a machine over this very connection (allowAsMachine on, else refused). hostId names the asking host, so a reconnect finds its tasks and terminals again. Then machine.call carries each host→machine request (MachineMethods), answered by the server's confined executor; machine notifications come back as machine:notification signals on this connection only.

Runs one machine-protocol method on this server's executor and resolves with its JSON result. Refused when the server does not lend itself as a machine.

Ends this connection's machine attachment. detached is false when it had none.

Forgets a machine. It disconnects and its kinds stop resolving.

State of this host's machine links: the shares it offers and the servers it uses.

The machines this host knows (docs/MACHINES.md), online or not, and forgetting one (it disconnects; its local@ / worktree@ kinds stop resolving). Additive.

Folders of a machine, for a client's folder picker: the host proxies a listing to the machine (fs.list, confined to its roots there): the folders in path (absent: its first root), and every root. Additive.

A local host's machine links (docs/MACHINES.md § Client UI), behind remote hosts: share this computer with a saved server (the machine agent runs in this host's process, with the machine token token or the one already stored for that server), stop sharing, use a saved server as a machine (reverse direction), and read their state. Refused while remote hosts are off. Additive.

Stops sharing this computer with a server.

Turns on or off using a server as this computer's linked server.

The host's shared MCP server processes (src/mcp/server-pool.ts), cwd's only when given: name, folder, shared or per session, how many sessions hold it, its pid, whether it is retired. Remote servers and scope: 'context' ones are never listed (they are per session). Additive.

Remove an MCP server from the host user's mcps.json; removed: false when it has none. As catalog.install.

End name's process now (in cwd only, when given) for every session holding it. Calls in flight fail with "<name> restarted" and are not retried; the next call starts a fresh process. Answers how many processes were restarted (0: none was running). Additive.

Forget an MCP server's sign-in on the host (its tokens). Every window gets catalog:changed. Additive.

Connect to one of cwd's MCP servers (as catalog.mcps), list its tools into the host's tools cache and record how it went: the server's new status. Every window gets catalog:changed. Additive.

Add or replace an MCP server in the host user's mcps.json, or with scope: 'project' in cwd's project (a folder inside the workspace roots on a server). Its env / headers values are stored there and never come back (catalog.mcps redacts them, the reply names the server only). clientSecret, the secret of its oauth client, goes to the host's MCP credential store, never to mcps.json; an entry without an oauth client drops a stored one. As catalog.install.

The host's credentialed providers (what its agents can run) and their models, for a model picker of a session on that host. cwd adds the providers its extensions contribute there. Additive.

Send one tiny prompt with this host's credentials, to check a chat model answers. model is "providerKey[@account]/modelId", tested exactly. Never fails: a broken model comes back as ok: false with a reason. Additive.

The setup wizard's write: settings.set sets (settings.reset back to their defaults, unless also set), as settings.set applies them, and records (the run finished, its steps) merged into the host's stored ones. Returns the settings in effect. Additive.

What the setup wizard finds on the host's machine for cwd (default: the host user's home): the providers and their credentials, other agents to import from, local model servers and the install signals. Additive.

The providers as the wizard's Connect step lists them, with their custom fields and the model each runs when none is picked. Additive.

Answers a question or a plan, recording the connection as answeredBy. false when it was answered first.

Decides a tool approval (an approve token), recording the connection as answeredBy. false when it was decided first.

Cancels a session's run.

Creates a session (optionally holding orchestration tools and a subscription) and resolves with its id.

Searches the recent session events (runs ended, sessions blocked), newest first.

Lists sessions with their live status, newest first, up to limit. The list can be partial.

The main session id, creating it (directory-less) when the setting is on and none exists.

The prompts waiting for an answer (questions, plans, tool approvals), of one session or all.

Summary of one session (with its link); rejects when unknown. lastMessage is cut at 600 characters; full: true returns it whole.

Queues a prompt as the session's next turn; false when declined (the person stopped the session, or their queued prompts go first).

Sends a steering message, with optional attachments, to a session's live run.

The last limit turns of a session as plain text, each cut at 1200 characters; full: true returns them whole.

Resolves once the session is idle or blocked, or after timeoutSec (default 30, at most 50).

The command palette items cwd's extensions contribute (each item's source is its provider), and running one. A provider that fails lists one disabled row naming why; a failed run answers ok: false. Additive.

Run itemId on its provider (source); a nested list, a prompt or a draft comes back as result. Additive.

Release one palette.watch of this connection.

As panels.watch, for every provider of cwd: palette:changed. Additive.

Run one of a panel's actions (a row's or the footer's actionId, its payload). Additive.

The side panels cwd's extensions register. A panel's load and onAction run on the host, bound to cwd and the session ctx names, with a hard timeout: a failing panel answers an empty content naming why (load) or ok: false (action), never an error. Additive.

One panel's content for ctx (the session it shows beside, what opened it). Additive.

Release one panels.watch of this connection.

Keep a panel's live updates on: this connection gets panel:changed when its content changes. Calls count; a dropped connection releases its own. Additive.

The samples the host holds (the last 5 minutes of watching), oldest first. Additive.

The OS threads of one of the processes the host lists (its own tree), busiest first. Refuses any other pid. Additive.

Release one perf.watch of this connection. Additive.

Follow the host's own performance (Settings › Performance on a server): this connection gets perf:sample every 2 s. The host samples only while a connection watches. Calls count; a dropped connection releases its own. Additive.

Stop or drop a plan. Stopping or dropping the plan a live run applies interrupts that run. Resume is a message (buildPlanResumeMessage), not a call.

A user edit to a plan's steps: rename, add or cancel (a step is never deleted). Through the live agent's session, else the store; refused while another process runs the session. The host fans plans:snapshot out to every window; the result is that snapshot. A refused edit is an error carrying the gate's reason.

The session's plans (from its live agent, else the store), or null for an unknown session.

The picks remembered across apps (state.json): effort and options per model, the next chat's model chain. null when none is. Additive.

Merges picks into state.json (each top-level key replaces). Additive.

Current presence snapshot — backfill for a freshly opened session list.

Tag the calling peer as watching a session (one per connection; the TUI opens one connection per activated session). Sent as a notification right after the handshake. Detach is implicit — the daemon recomputes presence when the socket drops.

Sends a message: right away when the session is idle; while a run works, into the run or into the queue (delivery). delivered says which: sent, steer (the run took it, as a steer or a follow-up) or queued. The message goes through the prompt interceptors first, as chat.send; consumed says one took it (delivered is then sent for handled, steer otherwise).

A queued entry's attachments with their bytes; null when already sent / dropped.

Type-ahead queue, host-owned so every window sees and can manipulate the same list. queue.add queues when a run is in flight and sends immediately otherwise; the host auto-drains the queue FIFO at run end.

Steer a queued entry, attachments included, into the live run now (falls back to send when idle).

Removes a queued entry by id. Resolves true when it was removed.

Edit a queued entry in place; order is kept. attachments replaces the entry's list when given. false when already sent / dropped.

The extension text reference providers (ctx.registerReferences) of cwd: the patterns a client matches prose with. peek: only from a registry already built for cwd (null when none is), so a list of titles across projects never builds one per project. Additive.

The views of the keys a client found, in order: null for one that names nothing. At most 50 keys per call. Additive.

Calls an extension's RPC method as this connection. Never throws for a failed call: a declared error, invalid input, a missing provider or a method whose scope this connection's token does not reach (rpc.forbidden; a local connection is not limited) comes back as ok: false with its type. directory (or cwd) picks the runtime; without it, the newest runtime that has the contract. callId lets rpc.cancel abort it. Also served as POST /rpc/<contract>/<method> on a zidane-server, with the same token. Additive.

Aborts this connection's rpc.call of callId; it answers rpc.aborted. false when none is in flight. Additive.

Drop the daemon's cached runtime configs (extension registries, per cwd) and retire every live agent so the next command or run rebuilds against what is on disk now. Sent by a window after it reloaded its own extensions (install, update, remove, /reload): extension / commands execute daemon-side, so without this the daemon keeps running the code it loaded at boot. Busy sessions rebuild at run end.

The host's "Always allow" entries, per project (its projects.json): what approving with accept-safelist added. Additive.

Revoke one "Always allow" entry of a project; removed: false when it was not there. Additive.

Create a schedule. The fields are a ScheduleInput.

Remove a schedule and its fires. false when it was gone.

An extension was removed: turn off the schedules whose action calls it (kept, marked, for the person to delete). A no-op while the feature is off.

A schedule's fires, newest first (limit default 20, at most 50).

The stored schedules, oldest first, each with its last fire. sessionId: only those whose prompt goes to it.

Run a schedule's action now; its next fire does not move.

Whether the feature is on (enabled) and whether this host's store keeps schedules (supported).

Change the fields of patch. A new trigger, or turning it on, counts its next fire from now.

Replace the shared transcript-search state (notification, per keystroke).

The secrets of the session's project (Settings.secrets): names and expiry times, never values.

Remove a secret of the session's project.

Add or replace a secret of the session's project. Refused over a plain-text connection from another machine.

Check for a newer zidane-server release now. With auto-update on, a newer one installs; off, it is downloaded and verified, and the state turns ready.

Turn the zidane-server's self-update on or off.

Install the release that is ready or waiting now, without waiting for background work to finish.

A zidane-server's self-update: its state, the setting, the newest release seen.

ctx.appendNote outside a run: a display-only note, rendered live and persisted (ChatHost.appendNote). False for an unknown session or no blocks.

Turns written outside a run, e.g. ! shell output (ChatHost.appendTurns). whenIdle: refused while a run is live or an interrupted run waits (a channel's context messages).

Artifacts one session recorded (PRs, branches, commits, files, extension kinds — see session/artifacts.ts), newest first. Empty on stores without artifact support. Additive; pre-artifact daemons reject the method and clients treat that as empty.

The session's saved block runs, by key (blockRunKey).

What a switch would cost the session's prompt cache, as the host applies it (ChatHost.cacheImpact): what pickers show next to each option. null without a live agent or for an empty change. Additive: an older host answers "method not found", and clients show no estimate.

The session's last requests and what the cache did for each (ChatHost.cacheReport): what /cache prints, for the GUI's session details. null for an unknown session. Additive: an older host answers "method not found".

Compact now (ChatHost.compactSessionNow): what was done, null when nothing was. Older daemons resolve null.

The session's context usage broken down by category, or null when unknown.

Every chunk of the session's system prompt with provenance — the Instructions tab. Built from the live agent's assembly, so it reflects MCP instructions, extension fragments and the resolved SYSTEM.md.

Creates a session and resolves with its row.

Seed a user-scope SYSTEM.md from the session's doctrine; throws when an override could not apply.

Resolves with what happened to the session's environment (a provider may keep it).

History edits (ChatHost.deleteTurn / editTurnText): refused while the session runs.

Replaces the text of one turn. Refused while the session runs.

The per-session commands the session's environment offers right now (push, open PR, …).

The session's transcript rendered as a file to hand to the user: Markdown (title, metadata, every turn) or the session's JSON. Nothing is written on the host. Additive (no version bump).

Fork at turnId into a new session (ChatHost.forkSession); announced as a sessions:changed create.

Title the session ON the host: its providers and credentials (a server session's transcript never goes to the window's provider), the same generator (generateSessionTitle), written as sessions.setTitle does. providerKey / model: the window's pick, used when the host has that provider; otherwise the session's own provider and model. The Main session is refused (it keeps its name). Additive: an older host answers "method not found".

The whole session document as the host holds it: the live copy when an agent is live (turns persisted mid-run, todos kept in memory), else the stored one, a stale running marker demoted. null when unknown.

One session's header: its list row plus metadata, profile and status, without turns or runs (the live copy when an agent holds it). What a window re-reads on sessions:changed. Additive. usage: true adds the footer's numbers, computed host-side from the turns and runs (contextTokens, costUsd, and while the host runs the session runStartedAt / runOutputTokens): a client needs no document for its context gauge, cost pill or run readout. Older hosts ignore it.

One SessionMeta by id (rows a filtered list can't return, e.g. the main); null when unknown.

The full text of one tool result (callId; turnId, when known, the turn that holds it): what a clipped tool row shows on expand, without the session crossing the wire. null when no such result. Additive.

One turn of a session by id, or null when unknown.

A slice of a session's turns, [from, from + limit) (default from 0, SESSION_TURNS_PAGE turns, at most SESSION_TURNS_MAX_PAGE), from the same copy sessions.get reads, and how many turns it has: a client reads a long session's document a page at a time (loadSessionDocument) instead of in one reply. With sessions.get turns: false (the document without its turns), what an export needs. Pages and that head come from one snapshot of the document per content version (read once, not per page), and name it (version): a client that sees it change mid-load starts over rather than mix two versions (loadSessionDocument). null when unknown. Additive: an older host answers "method not found", ignores turns: false, and names no version.

Lists session rows. projectRoot filters by project, archive picks active, archived or all sessions.

The session list as a window renders it (SessionMeta: title, turn / message / run counts, project, cwd, environment, artifact count, the orchestration main flag), newest first. projectRoot: omitted = every project, null = untagged sessions.

The session's transcript as canonical events. Without before / limit: every turn, as a plain array (the shape every client predating paging reads). With either: one page, { events, cursor? }, the last limit turns (default LOAD_EVENTS_PAGE_TURNS, at most LOAD_EVENTS_MAX_PAGE_TURNS) before turn position before (default: the end), its start moved back to an exchange boundary when one is near so a tool call is never cut from its result. cursor: the before of the previous page, absent at the first turn. Typed here as the unpaged call every client makes; a paged call goes through loadEventsPage. Paging is additive: an older host ignores the fields and answers the whole array.

Move an idle session to another environment (local, worktree, local@M, worktree@M, any direction), in cwd on the target; provisioning continues in the background.

Forgets a block's saved run.

Reattach without a reload: the session's signals numbered after afterSeq (see SIGNAL_SEQ_FIELD), in order, as long as this host process (epoch, from HelloResult.signalEpoch) still holds them all. Otherwise refused, and the client reloads with sessions.loadEvents. Additive: an older host answers "method not found", same fallback.

Provision a failed (or restart-stranded) environment again.

Cut the history at turnId in place (ChatHost.rewindSession); inclusive keeps the turn. Refused while the session runs.

Runs a shell block of a reply (Run here) in the session's folder, with no input. The reply names the run; its output follows as block-run:data signals and ends with one block-run:end carrying the saved run, to this connection only. Nothing enters the conversation; the run becomes the block's last (sessions.blockRuns), announced to every window by block-runs:changed. A dropped connection stops what it started.

Stops a Run here this connection started (cancelled: false when it is not running).

Run one of them in the session's environment (resumed when suspended).

Switches the agent the session runs as.

Archives or restores a session.

Sets the thinking effort of the session.

One key of an extension's per-session state (metadata.extensions, the bag ctx.session and renderer useSessionState share), written by the host into its copy of the session. value omitted deletes the key.

Keep the session at the top of lists (metadata.favorite). Not activity: no recency bump. Additive.

Bind to a folder, or back to a plain chat with cwd: '' (ChatHost.setSessionFolder).

zidane run --system / --mcp for a host-backed window: launch overrides for the session's agent (ChatHost.setLaunchOverrides), owned by the calling client and dropped when it disconnects. A call with neither field clears them.

The one model-swap contract (ChatHost.setSessionModel). A pick is a whole: fallbacks (ordered, primary excluded) REPLACES the persisted metadata.modelChain (omitted/empty clears it); effort and modelOptions are reset to the supplied values (omitted clears them — per-model knobs never leak onto the new model). The live agent is retired so the next run rebuilds on the new pick (run-end deferred while a run is in flight).

Replaces the model-specific boolean options of the session.

Replaces the session's rules (metadata.policy, SessionPolicy); {} clears them. Loosening the current rules (a looser approvalMode, 'ask' > 'decide' > 'off', removing a rule, raising a ceiling) needs an approve token. Additive.

Move the session to a space (metadata.spaceId); the Default space id clears it. See chat/spaces.

Renames a session.

A session's /side session (sessions.create with sideOf; hidden from sessions.list), the newest when there are several, with the session's own row (null: unknown). Additive.

How the session's title came about, as the session details dialog words it (describeTitleStatus): where it came from (auto, typed by you, untitled, …), then the last automatic titling attempt when there was one (generated 2h ago, check failed 5m ago (…)). Additive.

A window appended transcript content OUT-OF-BAND (local / command output, ! shell turns — written straight to the shared store, not through a host run). The daemon fans out sessions:changed so every window (issuer included) re-converges on the canonical replay NOW instead of at the next run end. Sent as a notification.

Copies from into folder toDir ('': the root) under a free name.

Creates a file (content: base64 bytes, default empty) or a folder; freeName takes the next free name instead of refusing a taken one.

The workspace's empty folders, relative to its root (a file listing leaves them out), capped.

The session's workspace (ChatHost.workspace*): its execution context, rooted inside the environment when the files live there, else at the session's cwd. Paths and exec cwd resolve against the root as the execution context resolves them; containment is the context's own. cwd / env on exec and the list / size methods are additive: an older daemon ignores the former and answers "method not found" to the latter (active clients are build-fenced, so this is a transient case).

Kill a streamed command's process group (this connection's only; cancelled: false otherwise or when it already ended).

The same command, streamed (! on a remote host): the reply names the exec, its output follows as workspace:exec:data signals and ends with one workspace:exec:exit, all to this connection only (signals may precede the reply). Bounded per connection (concurrent commands, chunk size, total output: past it the process is stopped and the exit says truncated). A dropped connection kills what it started. Additive: an older host answers "method not found" and clients use workspaceExec.

Size in bytes of a file in the session's workspace, or null when it does not exist.

Lists the entries under path in the session's workspace.

Moves (renames) from to to.

Reads a text file from the session's workspace.

Removes path (a folder whole), for good.

Writes a text file in the session's workspace.

Reads the host settings.

Applies a partial settings patch and resolves with the full settings after it.

The space a client's sidebar showed last, null when none was saved. Additive.

The sidebar views a client saved on this host, by space id (state.json's sidebarViews): each client checks what it reads. Additive.

Saves the space the sidebar shows. Additive.

Saves one space's sidebar view (at most 4 KiB of JSON), stored as given: the kit's record is the filter axes plus session, the conversation last open in that space. Additive.

The skills of a source (owner/repo[#ref][:dir], a GitHub or skills.sh URL), fetched by the host with its GitHub login; catalog.install with skills installs picked ones. Additive.

Resolve inline ghost-text autocomplete daemon-side (the typing window's request IS the single computation): canonical resolver against the session cwd's extension registry. Latest-wins per session — a seq older than the newest seen returns { suggestion: null } without computing, and a newer request aborts an in-flight compute. The result additionally fans out as suggest:changed to every OTHER peer.

Makes the caller the settings source device. When another device is the source, the result says which, unless takeover is set. categories and keys narrow what it syncs.

Applies one category's snapshot from the source device.

Stops the source device's sync.

Drops the local override of one field so sync applies to it again.

Settings sync, a client's computer → this server (docs/SERVER.md § Settings sync). A zidane-server only; other hosts refuse. One source device per server: sync.claim makes the caller it (or says who is, unless takeover), sync.push applies one category's snapshot through the host's own setters, skipping fields edited here since (overrides), sync.reset drops an override, sync.release stops the source. Every call is audited with its token. Additive.

Acknowledges terminal output up to offset, so the host keeps it flowing.

The draft became sessionId: its terminals move there in one pass (over the cap: back to the project).

maxLines caps the history snapshot to the last lines a view can show (0 or absent: no cap).

Closes a terminal.

Detaches a view from a terminal.

Opens a terminal in a session's environment.

Opens a terminal bound to a project rather than a session.

Terminals without a session: a shell on the host's machine in a project's folder, or in a new-chat draft's (draftId). Agents never see them. terminal:project-changed carries a scope's full list.

This connection can show terminals (the desktop app). While at least one viewer is attached, agents get the terminal tools; the registration is dropped with the connection.

The draft was discarded (or became a server session): its terminals go back to the project.

Resizes the terminal to a view's size. claim makes this view own the size.

Restarts a terminal's process and resolves with its info.

Hides a terminal from the agent, or shows it again.

Terminals, run by the host in the session's environment. clientId names one view (a window's drawer or panel); views attached through a connection are detached when it drops. Output arrives as terminal:output signals; ack what was written to keep it flowing.

Withdraws a viewer registered with terminal.registerViewer.

clientId + response: bytes the view's emulator generated (DSR/DA replies), dropped unless that view owns the size.

Create a token with a scope (./scopes; machine lends a computer). The secret is in the result only: show it once. Bound to the calling token (createdBy), so revoking that one revokes this one too. Audited. Additive.

Mint a machine-scoped token on this server (a zidane-server only), so a window can share its computer in one step. An admin token may (./scopes). Audited.

This server's tokens, revoked ones included, never their secrets (a zidane-server only). Additive.

Issue a one-time machine join code (a zidane-server only): a machine posts it to POST /zidane/pair and gets a machine token named name. A public server caps ttlMs at 10 minutes. Audited as pair.create with scope machine. Additive.

Issue a one-time pairing code (XXXX-XXXX, a zidane-server only): a browser posts it to POST /zidane/pair and gets a token of scope, named browser: <name> and bound to the calling token (createdBy). ttlMs: 30000 to 3600000, default 600000. Single use; five wrong secrets burn it. Audited. Additive.

Revoke a live token by id, with the live tokens it minted; their connections drop and the runs and terminals they started stop. Audited. Additive.

Revoke the token this connection authenticated with, and the live tokens it minted (a browser's sign out). Any client scope may: it only gives up its own access. Audited. Additive.

What this connection shows and whether it shows dialogs: dialogs (ui:dialog) and UI requests (ui:client) go to the client viewing the session, else the last active one. Only announced clients get them. Send again on focus or session change. Additive.

Answers a ui:client request sent to this connection. false when it is no longer pending. Additive.

Answers a ui:dialog shown on this connection (answer absent: cancelled). false when it is no longer pending. Additive.

Checks one value of a form dialog shown on this connection: the field's error message, or null when it is valid (or the dialog is no longer pending here). Clients call it as the user edits a field and before they answer, and show the message under the field. The host checks the answer again: an answer with an invalid value makes the extension's ctx.ui.form reject, so a client must not answer until every field validates. Additive.

GitHub's API limits as the host's GitHub client last saw them, per GitHub host; probe asks GitHub (/rate_limit, which costs no call). Additive.

The plan and subscription windows of each provider the host holds a credential for (every account), probed with the host's credentials and cached a few minutes; refresh probes past the cache. A provider that can't be read reports status: 'unavailable'. Additive.

Token spend, models, streaks and activity over range, from the host's session store, as the desktop app's welcome screen shows its own (summarizeUsage). Days are the host's local days; userName is null (the host's user is not the reader). Refused by a store that keeps no usage history (not a SQLite file). Additive.

The fetch to use. Default: globalThis.fetch.

The token's id, the one tokens.list and tokens.revoke use. Absent from servers older than it.

The scope the code was issued with.

The server's name, when it has one (--name).

The token, for createServerClient({ token }). Keep it; it is shown once.

Calls a method. Waits while (re)connecting; fails when the connection drops mid-call.

Whether this connection may call method: the host offers it and the token reaches it. true against a host that predates the list. false while not open.

Closes the connection and stops reconnecting.

The current connection's hello, null while not open.

Sends a notification (no answer). Dropped while not open.

Called after every handshake, reconnected after the first: re-read or resume what the page shows. Returns its unsubscribe.

Called with every signal the host fans out, and its position in its session; returns its unsubscribe.

Called on every state change; returns its unsubscribe.

Resolves with the first hello; rejects when the client is refused or closed before it.

The connection's state now.

Reported in the server's logs and audit (default 'web').

How long an attempt may take to open and finish its handshake before it is dropped and retried, in ms (default 10 000).

fetch, for the auth check after a failed connect. Default: the global one.

Ping interval in ms; a ping unanswered by the next one drops the connection (default 20 000; 0: off).

Called on every state change.

First reconnect delay and its ceiling, in ms (default 500 doubling to 15 000). false: never reconnect.

A client token (zidane server token create --scope chat). Absent: a server without auth.

ws:// or wss:// URL of the server.

WebSocket constructor. Default: the global one.

Position of the signal in its session. Starts at 1 and has no gaps within one host process.