zidane/ipc

Connects to a daemon over its unix socket and completes the ipc.hello handshake. On a protocol, build or code version mismatch it throws IpcVersionMismatchError. Unless drainOnMismatch is false, it first asks the stale daemon to drain. Rejects when nothing listens on the socket.

One-call convenience for windows: make sure a daemon is up (spawning if needed), connect, and — when the running daemon speaks an older protocol — drain it and spawn a fresh one before retrying once.

The daemon's environment: its own config, per-cwd extension discovery, multi-process.

File-backed pending-approvals persistence (pending-approvals.json next to state.json). Small, rewritten atomically enough for its purpose — the queue holds at most a handful of rows.

Disk-backed host environment: the daemon's, or (with shared) a host sharing the window's process and setup.

The image port of a host's ctx.generate (GeneratePort.image).

A host's pager. The worker is used only for a store that is a SQLite file (sqliteStoreFile), with the kill switch off; it spawns lazily, on the first page, for the first such file (one host, one store).

Builds the machines.list, machines.forget and machines.listDirs handlers. machines.forget broadcasts a machine:status signal with the machine offline when it removed one. machines.listDirs is confined to the machine's declared roots and throws for a path outside them.

Builds the machines.share.*, machines.useServer and machines.links.status handlers. The links load lazily and only while remote hosts are enabled. On a zidane-server every method throws. Turning remote hosts off stops every link.

A client of the history worker over dbPath. The worker spawns on the first page.

A replay and document cache.

A worker RPC client. The worker spawns on the first request.

Socket file name. Dev builds (ZIDANE_DEV=1, set by every dev script in the repo) get their OWN socket so a checkout's TUI, GUI and zidane daemon pair up among themselves and never attach to — or get refused by — the installed daemon. Without this, a protocol bump in the working tree turned the dev GUI's dot red against the stable daemon, and a dev daemon could drain the one the installed TUI relies on.

Path of the daemon socket this process uses. The ZIDANE_DAEMON_SOCKET environment variable wins. Otherwise it is <stateDir>/daemon/<socket name>, see daemonSocketName.

Makes sure a daemon is listening on the socket, spawning one when nothing is. Concurrent calls for the same socket share one start. Rejects when the spawn fails or the daemon does not accept connections within timeoutMs.

Per turn: does a run start there (a parent-run user turn carrying no tool result, not loop-injected)?

Merge the login shell's PATH into process.env.PATH. No-op on Windows or when no shell answers.

The history worker's module: the sibling source file in development, the sibling history-worker.js entry in the published dist, and the entry embedded under the binary's root in a compiled executable (scripts/build-executables.ts, scripts/build-server.ts).

The host's identity from a hello (or daemon.info) reply; null from a host that predates it.

Whether a string is a ClientScope.

A session's whole transcript, loaded a page at a time from the end so no single reply carries it all (a long session with images can outgrow a transport's message size). A page refused as too large is asked again at half the turns, down to one; a single turn that still doesn't fit fails the load. An older host answers the whole transcript to the first call.

One page of sessions.loadEvents (see its paging). An older host answers the whole transcript: it comes back as one page with no cursor.

A session's whole document, read a page of turns at a time so no reply carries it all (sessions.getTurns pages, then the sessions.get turns: false head; a page refused as too large is asked again at half the turns). Every page and the head name the snapshot they come from: a version change mid-read (a turn appended, a compaction) starts the read over, so the result is one version, never pages of two. After SESSION_DOCUMENT_RESTARTS restarts (a session busier than the read), the whole document comes in one reply. A host that predates sessions.getTurns sends it that way too; one that names no version is read as before. null when the host doesn't know the session.

ctx.mcp.list() of a folder, for hosts that run extensions outside a daemon (the desktop app's in-process host).

Entries of current the shell doesn't know about (ad-hoc prepends from the launching terminal) stay in front; then the shell's PATH in its own order. From the Dock every launchd entry is already in the shell PATH, so the result is exactly the shell PATH, with the shell's precedence intact.

True when something accepts connections on socketPath. Distinguishes a live daemon from a stale socket file left by a crashed one.

Every turn (with its seq) and run of a session; null when it does not exist.

The session's turns stored at seqs, in seq order; a missing or corrupt row is skipped.

Runs the zidane attach terminal client: picks or creates a session on the daemon (or a remote server), replays its transcript, and relays input and live signals until the user detaches. Rejects when the connection to the daemon or server drops. It does not exit the process.

Runs the client half of a remote OAuth sign-in against a host. Starts the flow on the host, opens the URL through the UI, forwards the code from the loopback listener or from paste, and resolves with the host's outcome, which never carries a token. Rejects when aborted or when the UI cannot answer a question the provider asks.

Runs a command in a session's workspace on a host and streams its output. The result has the shape of a local ! run. A host without sessions.workspaceExecStream gets the buffered sessions.workspaceExec instead, and then an abort stops the wait, not the command.

Serve handler on this worker thread.

Reads the PATH of the user's interactive login shell, blocking until it answers. Tries the user's shell, then /bin/zsh and /bin/bash. Returns undefined on Windows, or when no shell answers in time.

shellPath without blocking the event loop: same shells, args, timeout and parsing, run with runBounded (a timeout ends the shell's whole tree; under Bun its output survives a shell that exits before Bun watches it). For hosts (the GUI main process) that can start on a cached PATH and refresh in the background.

Starts a chat host in this process. Clients from connect behave like socket clients, without a socket or a second process.

Starts a unix-socket daemon around a chat host. Each peer must open with ipc.hello. A stale socket file left by a dead daemon is replaced. Throws when a live daemon already listens on socketPath.

[from, to) of the page, and the cursor of the one before it, over the turns' exchangeBoundaries (run starts) and turnCutPoints (where a run too long to send whole may be split; run starts when absent).

Per turn: can a page start there without leaving a tool call's result behind (not a tool-result turn)?

Call onChange after file changes. Returns the function that stops watching.

Thrown when the host refuses the handshake because its protocol, build or code version does not match the client's.

The worker's handler threw: remoteName and message are the thrown error's.

No worker served the request: do the work on this thread. degraded: none will until the client is recreated.

Kill switch: 1 pages on the host's thread, with no worker.

Largest limit a host honors.

Turns per sessions.loadEvents page when only before is given.

Bumped on an incompatible change; a host refuses any other version.

Error codes of the machine protocol (JSON-RPC server-error range, apart from IpcErrorCode).

Every secret-bearing value of a catalog entry is replaced by this.

Largest limit a host honors for sessions.getTurns.

Turns per sessions.getTurns page by default.

Session-scoped signals fanned out to every peer carry their number in their session as this extra field on the ipc.signal params (clients predating it ignore it; IpcClient strips it and hands it to listeners as SignalMeta). Per session, from 1, gap-free within one host process.

A run longer than this many pages is split (by limit, so the client's halving retry on a reply too large still converges).

Options for runAttach.

Params of sessions.create.

The host environment of a daemon or an embedded host: a ChatHostEnvironment backed by disk, with settings writes and runtime-config control.

The extension host of one daemon or server process.

Options for ensureDaemonRunning.

One folder in an FsDirListing.

A folder listing from fs.listDirs.

Folders a host lets clients browse, from fs.roots.

Params of the hello handshake.

What ./worker.ts takes as init.

One credential source of a host's provider (auth.status); no secret.

A config file that failed to parse (or an informational skip).

An extension in the host's catalog.

An MCP server in the host's catalog. Secret values are redacted.

A plugin in the host's catalog.

A skill in the host's catalog.

Options for createHostEnvironment.

What createHostImagePort reads at call time.

ModelInfo as it crosses the wire.

One provider a host can run, with its models (models.list).

Result of auth.oauth.begin.

auth.oauth.complete: the outcome, never a token.

Sign-in state of one provider on a host, from auth.status. Holds no secret.

Which host a client is talking to, as clients keep it (from hostRefOf).

Where a host's paged sessions.loadEvents are served: the history worker when it can, else the in-thread cache.

Options for InProcessHost.connect.

A chat host running in the caller's process, with clients that call it directly.

Options for startInProcessHost.

A connected host client, shared by every transport. Requests are checked against IpcMethods.

Options for connectIpcClient.

A running unix-socket daemon.

Options for startIpcDaemon.

Paging options of sessions.loadEvents.

Options for createMachineLinkHandlers: the host, settings access and the signal sink.

One ordered model-fallback target (primary excluded).

Result of auth.oauth.begin.

Hooks a window supplies to runRemoteOAuth: open the browser, take pasted input, answer the provider's questions, and abort.

What a client's own load gives replay.

A client's own read of a stored session, for replay.

A session signal with its position in the session, as kept in the host's replay log.

One page of a session's stream events, as sessions.loadEvents answers it.

One row of a cross-window session list.

What a host in the window's own process takes from the window.

A client of the history worker, from createTranscriptHistoryWorker.

A whole session as a replay needs it.

Whole-session reads, from createTranscriptReader.

A whole-session replay: pages are transcriptPage slices of it.

Whole-session replays and documents, kept per session version (see the module header).

A worker from either runtime: Bun / Web Worker (addEventListener) or Node worker_threads.Worker (on).

A worker's port to its parent, from either runtime.

The calling side of a worker RPC, from createWorkerRpcClient.

How createWorkerRpcClient spawns and supervises its worker.

What a handler can do besides answering.

What serveWorkerRpc runs in the worker.

Options for runWorkspaceExecStream.

Outcome of runWorkspaceExecStream, shaped like a local ! run.

The history worker's requests.

What a host process is: a window's own (in-process), the local shared daemon (daemon), or a remote zidane-server (server).

A question the provider's sign-in asks before (or after) its URL: a choice between flows, or a free text. The client shows it and answers with auth.oauth.respond; the host never picks for the user.

What queue.add does with a message while a run works: auto follows Settings.messageDelivery, steer and followUp hand it to the run, queue keeps it in the queue until the run ends.

What to sign in to: a provider by key (account: the stored OAuth account, by its stable id, whose tokens it replaces), or an MCP server by name.

What sessions.get answers: the document; with turns: false, the version of the snapshot it was cut from, the one sessions.getTurns pages carry.

Result of sessions.resume. On success, the signals the client missed after its last position. Otherwise the reason it must reload instead.