zidane/chat

File key holding one of a provider's non-active OAuth accounts.

Same sibling-key reasoning as alternateCredKey: the canonical key is the active one, so a provider with three OAuth grants stores the active one canonically and the other two under #account:N. #alt stays dedicated to the other-kind (API key) alternate so files written by builds that predate multi-account keep meaning the same thing.

File key holding a provider's second credential, when it has one of each kind.

The canonical key always holds the credential the user prefers; this sibling holds the other. That one invariant is what makes preference selection free: every existing reader (applyApiKeyEnv, the harness provider factories) already resolves the canonical key, so "switch priority" is just moving two objects between two keys — no precedence flag to interpret, no resolution order to keep in sync across layers.

A sibling key rather than a nested field because the canonical entry gets REPLACED wholesale on token refresh; anything nested inside it would be dropped by the next rotation. And older zidane versions look credentials up by credKeyOf, so a suffixed key is simply invisible to them — they read the preferred credential and behave exactly as before, which is why this needs no migration or schema version.

Reconcile process.env with the stored credentials so the harness providers pick up the wizard's output via their existing env-var resolution. Each host (TUI, daemon, desktop app) calls it at launch after the credentials file has been resolved, and again after a credential change.

Precedence: stored credential > ambient env. When the user has run the auth wizard, that's an explicit, recent action — it MUST win over whatever ambient value is already in process.env. Otherwise an upgrade reliably breaks for anyone whose cwd happens to contain a stale .env: Bun auto-loads .env from cwd into process.env before our code runs, older versions of bun run auth upserted tokens into cwd/.env, and even a one-off export ANTHROPIC_API_KEY=… from months ago in the user's shell rc can outlive its usefulness. None of those should override a key the user just typed into the wizard.

Three cases per registered provider with an envKey:

1. Stored kind: 'apikey' → overwrite env with the stored value. Wizard wins. A debug log fires when this clobbers a different ambient value.
2. Stored kind: 'oauth' → DELETE env, so resolveOAuthApiKey falls through to the file-read + refresh path. A stale OAuth token in env would otherwise short-circuit refresh and get rejected.
3. No stored entry → leave env alone. Env-only setups (no wizard run yet, hosts driving zidane purely from secrets management) keep working.

To opt out and force ambient env to win again, the user signs the provider out via the wizard (which deletes the stored entry → case 3 above).

Descriptors without an envKey (OAuth-only providers, custom providers that bypass env-var resolution) are skipped silently.

What auto-titling should do for this session now:

• generate: no title yet and the first exchange happened.
• check: an auto title, with enough new prompts since the last check.
• skip: a user title, too few turns, or checked recently.

Record a checkpoint. No-op unless ZIDANE_BOOT_PROFILE is truthy in the environment.

The leading delta is the time since the PREVIOUS tick (so a long delta highlights the immediately-preceding work); the trailing total is the time since the profiler started. Both round to one decimal of a millisecond.

Compose the Build-mode system prompt.

Layout (top to bottom):

identity → doctrine → guidance → user instructions ─── SYSTEM_PROMPT_BOUNDARY ─── env (cwd / project root / date / platform)

Everything ABOVE the boundary is byte-stable for the lifetime of the run and rides the prompt cache across turns + sessions. The env block sits BELOW so a moved cwd or rolled-over date doesn't invalidate the doctrine.

The fragments are joined with blank lines so the model sees clean section breaks. Don't reorder lightly — every reorder costs one cache miss across every active session.

Map a user-toggled enable list onto the mcpServers array the agent receives. Conventions match buildSkillsConfig:

• enabled === undefined → every discovered server enabled (default).
• enabled === [] → no servers (the agent runs MCP-less).
• enabled === [names] → allowlist; servers not in the list are dropped.

disabledTools is the per-server tool deny-list from Settings.disabledMcpTools. For each server that survives the server-level enable filter, the per-tool names are merged into McpServerConfig.disabledTools via union with anything the JSON file already pinned — a tool listed in either source is dropped. Union (not override) keeps JSON-side policy stable: a server file that pins disabledTools: ['dangerous_tool'] can't be re-enabled via the UI by accident.

enabledTools (JSON-side allowlist) takes precedence over the UI-side deny-list when both are set on the same server — the allowlist's "only these" semantics would be meaningless if a UI deny-list could subtract from it again. We don't emit disabledTools when enabledTools is present.

Returns a fresh array — callers can mutate without affecting the underlying discovery list. Per-server config objects are also fresh copies (shallow), so the merged disabledTools doesn't leak back onto the discovery catalog.

Map the user's enabled-plugin list onto the contributions a host merges into the agent.

Conventions match enabledSkills / enabledMcps:

• undefined → every discovered plugin is enabled (default)
• [] → all off
• [names] → allowlist

A plugin that failed to load contributes nothing regardless of the allowlist — ok: false means components were never discovered.

Build a protocol-valid user SessionTurn that closes a batch of resumed pending interactions.

• requests MUST be the same list returned by pendingInteractionsFromTurns for the session, in order.
• responses MUST contain an entry for every request id; throws otherwise (caller bug — flush before all answers collected).

Pure: reads no store. Tested in isolation so the batching invariant doesn't regress without the resumed-flow integration noticing.

Assemble the agent.run model option from a chain.

• Single-entry chain → the bare model id string (what a single-model run passes).
• Multi-entry chain → pinned { provider, model } targets, where provider is the runtime Provider.name resolved via providerNameFor (chain entries carry chat-level ProviderKeys, which need not equal the instance names the agent loop matches on).

Throws only on an empty chain — a programmer error, since chains always carry a primary. Stale or unresolvable entries degrade defensively instead (never throw, never produce an entry the agent would reject):

• Entries whose key has no resolvable name (provider not constructed into the current agent) are dropped.
• If the PRIMARY itself doesn't resolve, or fewer than two entries survive, fall back to the bare primary model string.

contextWindowFor (optional) stamps each target with its model's context window from the host catalog, so the loop re-bases the auto-compact trigger when a fallback advances onto it (the host's explicit window is sized for the PRIMARY otherwise).

Map a user-toggled enable list onto the format createAgent expects.

Conventions:

• enabled === undefined → all discovered skills enabled (default).
• enabled === [] → fully off; the agent will not scan or inject the skills tools.
• enabled === [names] → allowlist; skills not in the list are left out of the catalog.

scan is the resolved scan-path list (passed through verbatim). Pass defaultSkillScanPaths() for the standard project + user paths, or supply a host-specific list.

spawn-end marker. The facts ride on spawn.end (status, elapsed wall-clock time, USD cost summed across the child's whole turn tree, token totals); renderers read them through describeSpawnEnd. Most providers don't populate cost, so it is usually absent: no "$0.00" lies. timeout maps to done, matching the TUI.

text keeps its stored shape for clients that predate spawn.end; see spawnEndText.

Pure factory shared by both hook flavors. Captures persistedDenyAll

• setDisabledMcpTools at the call site so toggle handlers stay referentially stable across renders that don't touch the underlying settings entry — important for useKeyboard to avoid re-binding on every catalog change.

Exported for direct use by non-React consumers (CLI, GUI shells) that want the same write semantics without the hook plumbing.

Flatten a server catalog plus the per-server expanded set into the visible-row list a renderer cycles through.

• catalog — filtered / ordered server list (post-search, post-allow-list).
• expanded — names of servers whose tool list is open. Servers not in this set render as a single server-header row.
• toolsByServer — per-server full tool catalog (from chat/mcp-tools-cache.ts). Missing key → 'tool-empty' placeholder under the expanded server.

Transcript-row text for a persisted cache-break notice. Multi-line, one fact per line, so both hosts can show a short headline and fold or list the rest:

cache break ↑116.9k tokens ~$0.48 messagePrefix: message 16 of 41→43 rewritten likely compaction or history trimming

The footer chip stays terse; the row carries the culprit so a break is diagnosable from the transcript. Only the headline on a TTL / eviction break (nothing was done wrong).

Build the per-run behavior.autoCompact a chat host passes to agent.run.

Loop-native auto-compaction is the only mechanism; the TUI + GUI just translate the user's enable/threshold settings plus the picked model's raw context window (the SDK core has no model catalog) into the config the loop consumes. Returns false when disabled. rawContextWindow: null (unknown model) still enables it but leaves the trigger inert — the loop skips with unknown-window rather than guessing.

Resolve the latest available version of packageName, honoring an on-disk TTL cache so the warm path costs zero network. Never throws — registry failures degrade to { source: 'error', latest: null }.

Designed for boot-path usage: short timeout, swallows errors, opt-outs for CI / restricted shells. Consumers driving the explicit upgrade subcommand should set force: true to ignore env opt-outs.

Whether <packageName>@<version> can actually be DOWNLOADED right now, not merely resolved. Right after a publish the registry serves the new manifest minutes before the tarball reaches the CDN; a package manager that hits that window on an optionalDependencies platform binary silently skips it and leaves a bin with nothing behind it. upgrade asks this before spawning the PM so it can wait instead of breaking the install.

• 'ok' tarball responds 2xx
• 'missing' manifest or tarball 404 (published, not propagated)
• 'unknown' network / registry error; the caller decides

Normalize a model-generated title into the shape we want to persist:

• Collapse internal whitespace + take the first line only (some models emit "Title: foo\n\nReason: …" despite instructions).
• Strip surrounding quotes, a leading Title: / title - preamble, and a user: / assistant: role prefix echoed from the transcript — repeatedly, in any nesting order.
• Reject placeholders and answer-shaped replies (see ANSWER_SHAPED_OPENER) by throwing.
• Strip trailing punctuation (., !, ?) — titles read cleaner without it.
• Truncate to TITLE_MAX_CHARS with a trailing … when over.

Exported as cleanTitle so tests can pin the normalization rules without going through a mock provider.

Drop entries for one or more servers, or wipe the cache when no server is named. Idempotent — entries that aren't present are silently skipped. Returns the resulting cache so callers can refresh any in-memory mirror without re-reading from disk.

Meant for a "rescan server" affordance in the settings UI (clear → trigger a real bootstrap → cache repopulates on the mcp:tools:list hook).

Return the longest prefix of hints whose rendered width fits within budget. Used to degrade hint rows gracefully at narrow terminal widths instead of letting an absolutely-positioned hint row wrap mid-segment (which paints the overflow over surrounding borders and looks like garbled glyphs in a TUI).

Prefix-only (no reordering, no last-hint priority) so the survivors keep their authored order — the user's muscle memory for "leftmost hint = primary action" stays intact as the terminal shrinks.

Per-item anchor ids for auto-scroll. Walks items in render order and, for each event, returns either:

• 'turn-anchor-<turnId>' — the first event of this turn (the scroll target).
• undefined — later event of an already-tagged turn (or a synthetic event with no turnId).

ids[i] is a tuple per item: length 1 for plain events, length N for subagent runs (one entry per inner event). idByTurn is the inverse lookup used by the scroll effect. lastTurnId is the most-recently-rendered turn — the scroll effect special-cases it to snap to bottom rather than scroll the anchor into view (which would stop short of the actual tail).

Exported so the anchor-tagging matrix can be unit-tested without rendering anything.

Build a file-backed McpCredentialStore. All per-server reads / writes funnel through the single mcp-credentials.json file — this keeps concurrent flows for different servers from clobbering each other since each save reads-modifies-writes the full file atomically.

Two flows for the same server name CAN race (last write wins). MCP OAuth flows are user-driven and serial in practice (one login modal at a time), so this is acceptable; a per-server file split + cross-process lock would be required to handle a multi-process scenario.

Create the orchestration main session; returns its id.

Directory-less on purpose. The main is GLOBAL — one per store, orchestrating sessions in many directories — so binding it to whichever cwd happened to be active when the toggle flipped put it in that project's group and hid it from every other project's list. With no cwd it sits in the "Chats" bucket and its own tools run from HOME, which is the only directory that is always the user's and never a project's.

Built-in provider: complete filesystem paths under cwd (or absolute / ~ paths). Given the token src/chat/comp, lists src/chat/ and returns every matching continuation of comp as a candidate list — directories first, alphabetical, /-terminated for directories so typing can continue. The host ghosts the first candidate and rotates through the rest on up/down.

Bare tokens (no / yet) are matched against the cwd listing too, so a directory ghost appears as soon as the first characters of src are typed — but only from the second character on, so 1-letter prose words don't ghost-spam.

Dotfiles are only offered when the typed fragment itself starts with . — the usual completion convention.

The { todowrite, todoread } tools plus the plan lifecycle hooks (the open-steps reminder, closing a run's plans when it ends).

createAgent({ ...composePresets(basic, createPlanTools()), provider })

The slot key currently holding the credential whose stable id is id, or undefined when none of fileKey's slots does (signed out, removed).

Slot keys are positional — promoting an account swaps entries between them — so anything that must keep naming ONE account (a session pinned to it) stores the id and asks here on every use, never the key.

Resolve the credentials file path given the resolved TUI data directory (typically ~/.zidane, i.e. config.paths.dir).

Matches the convention used elsewhere in the TUI (sessions.db, state.json) so a single ZIDANE_STORAGE_DIR override moves the entire data root.

Dedup a merged MCP-server list by name. First entry wins.

Applied at agent build across every source that can contribute a server — mcps.json, Agent Plugins, launch options, extensions — so the earliest source in that order takes precedence.

Drops are REPORTED rather than silent, via onDropped. A plugin shipping a github server loses to a github in mcps.json, and nothing downstream says so: the plugin's settings row still counts the server it shipped, because the row renders what the PACKAGE declares and only this merge knows what survived. That mirrors how the skills side reports the same class of event — resolveSkills emits name-collision-shadowed on the winner rather than annotating the loser.

The reporter is injected rather than calling a logger directly so this stays a pure function of its input, testable without a logging shim. It lives here beside buildMcpServers rather than in the TUI because merge precedence is a config concern, not a rendering one.

Search order for MCP config files — see projectUserPaths.

Both mcps.json (zidane's canonical name) and mcp.json (Cursor / common ecosystem alias) are picked up from every search root. The canonical name wins within the same directory; across files the usual first-found-by-name dedup applies, so mcp.json effectively merges its non-overlapping entries on top of mcps.json.

Order per scope (project beats user):

1. {project}/.agents/mcps.json
2. {project}/.agents/mcp.json
3. {project}/.{prefix}/mcps.json
4. {project}/.{prefix}/mcp.json
5. ~/.agents/mcps.json
6. ~/.agents/mcp.json
7. ~/.{prefix}/mcps.json
8. ~/.{prefix}/mcp.json

Non-existent files are skipped without error.

Resolve the default skill scan paths for a project. First-found wins on collision; earlier entries take precedence.

Search order — see projectUserPaths. Non-existent paths are returned so downstream code can choose whether to create them; discoverSkills itself skips missing dirs without error.

Delete a session's persisted data: the store row, then every on-disk artifact it owns — the session-first tree (<userDir>/sessions/<id>/: blobs, task logs, MCP warnings) plus the two pre-session-first locations migration leaves behind. Blob cleanup is best-effort and never throws; it runs AFTER the row delete so a cleanup failure can't leave a live row pointing at removed blobs.

Does NOT stop a live agent — hosts must retire it first (see ChatHost.deleteSession), or its next save resurrects the row.

Display title for a session — preferred sources, in order:

1. metadata.title if it's a non-empty string (typically set by the session-details modal's "generate title" action), on one line (oneLineTitle): whatever wrote it, a title never wraps.
2. titleFromTurns — the first user message, one-line + clipped.
3. DEFAULT_SESSION_TITLE ('New session').

Total / pure / defensive on non-string metadata values.

Detect available auth for every registered provider.

A method appears in methods for every layer that has a credential:

• kind: 'apikey' from credentials.json (injected into env at TUI launch)
• explicit env var (descriptor's envKey)
• kind: 'oauth' from credentials.json (migrated on first read from a legacy .credentials.json, see readCredentials), one per stored account

The preferred credential lives in the canonical file key and is flagged AuthMethod.active; the others sit in sibling slots and are reported too, keyed by AuthMethod.key, so the UI can offer to promote or remove them. Order within methods is presentational — active first — not a resolution order, because the active flag answers that directly.

Never refreshes tokens or rewrites existing credentials. The one write is the first-read migration of a legacy .credentials.json when credentials.json does not exist yet (see readCredentials).

Walk the candidate paths and load every AGENTS.md that exists.

Project paths anchor at the git root when one exists above cwd, else at cwd itself — same anchor logic as projectUserPaths so the three discovery surfaces (skills, mcps, AGENTS.md) stay in lock-step.

All matching files are loaded (no shadowing within a scope). Empty or whitespace-only files are skipped. Render order matches the search order — broader scopes first, narrower scopes last so the project-specific file lands closest to the conversation.

Tolerant on read failures: an unreadable file is skipped silently (logged under ZIDANE_DEBUG). The loader never throws — bootstrap paths can't afford to crash on a permission glitch.

Defensive dedup: when <git-root> === ~ (the user launched zidane directly from $HOME and $HOME happens to be a git repo) the project + user candidate sets would otherwise overlap. We dedup by absolute path so the same file never lands in the block twice.

Walk the default config paths, parse every file that exists, and return { servers, errors } in source-priority order. Project entries appear before user entries; first occurrence of a name wins (later duplicates dropped).

Parse failures are captured into errors rather than thrown — the picker surfaces them while still showing whatever DID parse. A ZIDANE_DEBUG log line is also emitted for ops visibility.

Load every plugin reachable from the default search roots.

Each immediate child directory of a root is one plugin — the same depth-1 rule the spec applies inside skills/. A child that isn't a directory, or that holds no plugin.json, is silently skipped: dropping a README next to your plugins is not an error.

Dedup is by plugin NAME, not directory name, because the manifest owns identity — two directories called tools/ shipping different plugins are two plugins, and one plugin vendored at two scopes is one plugin.

Discover every skill reachable from the default scan paths. Returns parsed SkillConfigs with name, description, frontmatter, and lenient-load diagnostics. Pure I/O — does not activate or write.

signal is forwarded to discoverSkills so the TUI's directory-watch effect can cancel a long scan when the user switches cwd rapidly.

Errors during parse are surfaced as diagnostics on the returned skill, not thrown — keeps the picker usable even when a single SKILL.md is malformed.

Find the active SYSTEM.md override, if any.

Project paths anchor at the git root when one exists above cwd, else at cwd — the same anchor as skills / mcps / AGENTS.md discovery, so all four surfaces agree on what "this project" means.

Tolerant: an unreadable or empty file is treated as absent (logged under ZIDANE_DEBUG) and the next candidate gets its turn. Never throws — this runs on the session-activation path.

Candidates are filtered by DiscoverSystemMdOptions.scope, mirroring how discoverAgentsMd builds its own list.

Normalize a model-options blob to an enabled-only { id: true } map.

Single source of truth shared by every surface that reads or persists model options — the TUI run path, the GUI engine reader, and the GUI IPC handlers. Tolerant of arbitrary input (persisted JSON metadata may be anything): a non-object → {}, and only entries strictly equal to true survive. This keeps the persisted shape minimal (no { fast: false } noise) and means callers never forward a disabled option to agent.run.

Render the env anchor block. Plain text — XML tags only because models lean on them as structural cues, not because we parse them anywhere.

Kept narrow on purpose: cwd / projectRoot / date / platform are the knobs the model can't infer from the conversation. Anything else (git branch, project name) belongs in CLAUDE.md / project-level prompts where the user opts in.

Cache-stability: outputs are byte-stable per (cwd, projectRoot, date, platform) tuple. Repeated session activations against the same workspace produce the same prefix → provider's prompt cache hits across turns + across sessions in the same host process.

Replays persisted turns as a viewable transcript. Equivalent to replayTurns(turns, runs).events. Mirrors the event shape produced live by the agent hooks so loaded and streaming history render identically, including subagent ancestry when runs is supplied:

• Every turn carries a runId, looked up in runs to get the run's depth. The resulting events carry { depth, childId }, the same shape the live child:* bubble hooks produce.
• spawn-start / spawn-end markers land at each child-run boundary, so the transcript reads the same as a live run did.
• For child runs (depth > 0), the user-role "task" text is suppressed because spawn-start already shows it.

Treat pasted as a callback-URL paste. Validates it's a loopback URL, fires a GET, returns the status.

Pass authUrl (the authorization URL currently on screen) to accept partial pastes — a bare code, a query string, a path — via normalizeRedirectPaste. Without it only a full absolute URL is accepted.

Throws when:

• pasted doesn't parse as a URL (and can't be completed from authUrl).
• The URL host isn't loopback (rejects SSRF).
• The fetch errors out (network, timeout).

Returns success/failure for non-2xx responses; the caller decides whether a 4xx is fatal (state mismatch is a 400 the user can retry from).

Usage for one provider, probed with the credential requests use — or, when that one is not the kind the probe needs (an API key in use, OAuth accounts parked beside it), the first stored one that is. What the footer shows.

null means there is nothing to show: the provider has no usage surface, no credential of the kind its probe needs (file or, for API keys, env), or the environment opted out (see usageChecksOptedOut).

Never rejects. Transport and parse failures land in the snapshot.

Filter candidate fallback entries against a primary pick, preserving picked order: entries whose provider isAvailable rejects, entries equal to the primary, and exact duplicates drop. Shared by the picker's apply path (live-auth availability) and persisted-chain restore (registry availability).

One account per provider: a chain runs each provider as ONE instance bound to one account, so an entry naming another account of a provider already in the chain (the primary's, or an earlier fallback's) drops — it would otherwise run on the wrong account.

Walk parents of cwd looking for a .git entry. Returns the absolute path of the directory containing .git — the CHECKOUT root (a linked worktree's own dir, not its main checkout) — or null when no git repo is found above cwd.

Stops at the filesystem root (/) — no infinite loop on dirname's idempotent root case (dirname('/') returns /).

Create and persist a new session whose history is the parent's turns up to and including turnId. The parent is untouched.

Carries: the protocol-clean turn prefix, the run records those turns reference (so run stats survive and the next run can't re-mint run_1 over an existing reference), persisted-output blobs (copied and re-pointed), projectRoot (a fork belongs to its parent's project, wherever it was forked from), agentId, FORK_INHERITED_METADATA_KEYS, and the parent's environment — marked not-owned: the fork runs in the same worktree / sandbox but deleting it never tears that down. Refused while the parent's environment isn't ready: nothing would provision the fork's copy, and provisioning it would mint an environment nobody owns.

Render a binding spec ("ctrl+return", "backspace", "delete") as a compact display string the user recognizes at a glance. Substitutes arrow / enter / backspace glyphs for their verbose names so the hint row stays narrow; modifier names + plain keys pass through unchanged.

Empty / missing specs return an empty string — callers decide whether to render a placeholder (e.g. '—' for an unbound action in the keybindings panel) or hide the surface entirely (e.g. hint rows that fall back to a different chord when the binding is empty).

Convert a project-root-relative path (as emitted by listProjectFiles) into the form the agent's tools — and the user — will actually find given the current cwd.

Inputs:

• projectRelativePath — forward-slashed, no leading slash. Returned verbatim when it's empty or already absolute (defensive — the absolute-input branch is the de-facto "outside the project" escape; the catalog itself never emits absolute paths).
• projectRoot — absolute path of the discovery anchor.
• cwd — absolute path of process.cwd() at the moment of insertion.

Output is always either an absolute path (only when the input arrived absolute) OR a CWD-relative path. The relative form may include ../ segments when the target sits above cwd within the project, which keeps cross-tree references short and scannable (e.g. ../EDIT_THIS.md instead of /Users/.../zidane/EDIT_THIS.md).

Drive one schema-pinned provider call and return the conforming payload. Throws when the provider returns no structured payload (and rethrows aborts verbatim). The caller owns presentation — nothing is rendered or persisted here.

Pass a zod v4 schema and the return type is inferred from it; pass a plain JSON Schema object and name the type via the generic.

The safelist in effect for a working directory — what every host's gate must read. The project's entries (safelistProjectKey), plus entries saved under older keys for the same place, still honored but never written again:

• the CHECKOUT root — the TUI keyed a linked worktree by its own dir before worktrees resolved to their main checkout;
• the exact cwd — the daemon/GUI keyed by raw cwd before keys were normalized to the project.

Open pull requests for the switcher; null when gh is missing or signed out; { rateLimited } when GitHub refused and nothing is cached.

• no query: three lists fetched apart, so a busy repository never pushes yours or the ones waiting on you out of view: review-requested:@me (your teams included), --author @me, and the most recent others.
• a query: GitHub's own search over every open PR (--search), so a repository with thousands of them is searchable from here.

File entries from run (git status --porcelain=v1 -z --untracked-files=<mode>; null: it failed). Every untracked file first; when that fails (a folder nobody ignored, like a fresh node_modules, overflows the output or the time) again with such folders as one record, which parseGitStatus drops: the tracked changes survive. Shared with sandbox workspaces.

Walk KEYBINDING_DEFS in order and bucket rows into contiguous sections by group. Shared between the standalone KeybindingsModal and the Keybindings tab inside SettingsModal so both surfaces render the same catalog with the same ordering rules.

Pass extensionRows (resolved extension keybindings paired with their definitions) to append an "Extensions" section at the end so extension-contributed shortcuts are discoverable in the same UI.

True when a call matches ANY entry in the project's safelist (or is implicitly safe).

For shell commands, the full command string is parsed into individual commands (handling &&, ||, ;, |, $(…), backticks, subshells). Every command head must be covered by at least one safelist entry for the call to pass. If parsing fails, returns false (prompt the user).

True when a key claims a reserved slot namespace.

Built-in keys are plain identifiers (anthropic, openai-codex), but ProviderDescriptor.key / credentialFileKey are open strings — so the reservation is checked, not assumed.

Effective context size of the most recent assistant turn — drives the footer indicator. Walk from the end of turns and return the cache-aware input-token total of the most recent parent (depth-0) assistant turn. Subagent turns are skipped because their context window is the child's, not the parent's — surfacing a subagent's usage.input as the footer's "context used" after a session ends mid-spawn would be misleading. The next prompt feeds the parent, so the parent's last view is what matters.

Zero-context placeholder turns are also skipped. executeTurn synthesizes an assistant turn with usage: { input: 0, output: 0 } when the provider stream throws / aborts before any usage is reported (see src/loop-turn-stream.ts's catch path) — that turn is purely a shape contract for resume, not a real context-window measurement. Without the skip, an abort mid-stream shadows the prior real turn and the footer reads ctx 0 on the next session load even though earlier turns accumulated meaningful context (and run.cost).

runs is optional. Without it depth is unknown, so every assistant turn qualifies.

Discover every non-ignored file under cwd, plus the directories that contain them (derived from the file paths, kind: 'dir'). Tries git ls-files first; on failure (no git, not a repo, abort) walks the fs with a hand-rolled skip list.

Errors are not thrown — the function always returns an array (possibly empty). Callers wanting failure diagnostics can opt into them via ZIDANE_DEBUG.

Load every session and project it to the compact SessionMeta shape used by the picker. Sorted by recency via the underlying store's list() contract (sqlite store returns by updated_at DESC). /side sessions are left out, like every session list (isSideSession).

Robust to per-row failures: Promise.allSettled so a single corrupt or unreadable row (malformed JSON, partial write, transient I/O error) doesn't take down the entire picker. Failed rows are silently skipped; a stderr line is emitted under ZIDANE_DEBUG for diagnosis.

Whole tree as relative paths (dirs implied, explicit trailing / for empty dirs), bounded. .gitignore is honoured through one git ls-files call (instant, unlike git status --ignored, which walks node_modules and can take tens of seconds on a real repo); pass showIgnored to include ignored entries, flagged so the tree can dim them. .git itself is never listed.

An ignored folder is one node (dist/, ignored), never walked: list it with dir when the user opens it, which walks that folder the same way (its ignored subfolders one node each again), so a node_modules-sized folder costs one readdir per level opened. Past the entry cap the listing is cut and says so (truncated).

Best-effort cache read. Returns {} when the file is missing, when JSON.parse rejects, or when the top-level shape isn't a plain object — a corrupt cache must never crash the host on startup.

Per-entry shape validation is light (presence of an array tools): deeper validation would lock the cache to a single zidane version, which is the opposite of what a long-lived cache wants. Entries that survive the light check feed back through McpToolSchema's unknown inputSchema so downstream readers stay tolerant of upstream churn.

The main checkout a LINKED WORKTREE belongs to, or null when checkoutRoot is not one. Does not walk: checkoutRoot must be a checkout root (what findGitRoot returns).

A linked worktree's .git is a file (gitdir: <main>/.git/worktrees/<name>) and that gitdir holds a commondir file pointing back at the shared <main>/.git. Everything else resolves to null and stays its own project:

• a regular checkout (.git is a directory);
• a submodule (its gitdir has no commondir — a submodule IS a separate repo);
• a worktree of a bare repo or of a --separate-git-dir repo (the common dir isn't a .git inside a working tree, so there is no main checkout to belong to);
• anything unreadable or malformed.

Resolve the top margin (in rows) for an event given the one rendered just before it. Context-aware rules:

• A tool / tool-result event right after another tool / tool-result collapses to a tight list — call→result pairs and back-to-back calls read as one logical block.
• Consecutive task-notification banners stack tight — a burst of background-task completions reads as one log column rather than scattered banners.

NB: parent-level events (depth === 0) following a subagent block (depth > 0) get their normal default margin. The subagent's 🌳 end-marker does not provide enough visual separation to collapse the transition to 0: a 2-cell emoji on the same row as the close marker doesn't create a vertical break, and in hide-subagent-output mode the SubagentBlock box isn't rendered either, so the parent's follow-up markdown would be glued directly against the close line. Subagents should READ like tool calls: open with breathing room, close tight inside, and open a clean gap before the parent's next thought — that's the contract the tool-call → markdown transition uses, mirrored here.

Renderer-agnostic — TUI uses it as Yoga marginTop; a CSS host can use the same number as the row's top margin in em / rem.

Convert a per-hunk approval mask into an EditOutcome[]. true → applied; false → denied with the supplied reason.

Length is Math.max(mask.length, fallbackLength) so callers passing a shorter mask still get a fully-populated array — missing entries default to applied, matching the "no decision => keep" convention.

Test a KeyEvent against a parsed-or-string binding. Accepts either form so callers can pre-parse (hot path) or pass the raw spec for one-off checks.

Modifier semantics: ALL declared modifiers must be pressed AND no extra modifiers may be pressed. So 'o' does NOT match ctrl+o, and 'ctrl+o' does NOT match ctrl+shift+o. This avoids surprises where a binding that should be specific accidentally fires for a superset of key combinations.

Test whether a { tool, input } pair is covered by one safelist entry.

Supported entry shapes:

• "<tool>" — broad match on tool name.
• "<tool>:<token>:*" — match when the primary arg's first token equals <token>.
• "browser_open:<host>" / "browser_navigate:<host>" — match a load of that host (port included).

This function matches a single command against a single entry. For shell commands that chain multiple programs (&&, ||, ;, $(…), etc.), use isOnSafelist which parses the full command and checks every head token independently.

Entries that don't fit either shape are ignored (forward-compat for future pattern syntax — readers shouldn't choke on entries written by a newer version of the TUI).

Merge body-side outcomes (keyed against the approved subset the tool actually ran on, in subset-position order) into approval-side outcomes (1:1 with the model's ORIGINAL edits list, with denied entries for every hunk the user dropped).

Algorithm: walk the approval array; every applied placeholder corresponds to one approved hunk that the body ran. Consume body's outcomes in order against those placeholders. Non-applied approval entries (denied, skipped) stay untouched — they describe gate- level decisions the body never saw.

Pure. Returns a fresh array; never mutates either input.

Edge cases:

• body is empty / shorter than the approved count → remaining approval applied placeholders stay as applied (the body ran happily; absence of a body entry means nothing failed).
• body longer than approved count → trailing body entries are ignored. Shouldn't happen in practice (body sees the rebound subset), but the guard keeps the merge total-pure.

Build a new, UNSAVED session with every creation-time field stamped: projectRoot (git root of cwd), cwd, agentId, title, the model and its fallback chain, the authoring markers, and the environment.

Unsaved on purpose: the TUI's local runtime creates the session when a chat opens but only persists it on the first run, so opening and abandoning /new never leaves an empty row behind. Everyone else wants createSessionInStore.

store may be undefined for an in-memory-only session (ACP without a store): same stamping, no persistence.

Widen what counts as an acceptable paste. The happy path is the full redirect URL out of the browser's address bar, but users on SSH routinely end up holding less than that: some authorization servers render the code on the page instead of redirecting, and copying from a "can't reach this site" error page loses everything but the query.

Accepted forms, given the authorization URL for context:

• http://127.0.0.1:5123/callback?code=x&state=y — passthrough (any absolute URL is returned untouched; the loopback guard in fetchOAuthRedirect still has final say, so a pasted https://evil.test is rejected there, not silently rewritten).
• /callback?code=x&state=y — path + query onto the callback origin.
• ?code=x&state=y / code=x&state=y — query onto the callback URL.
• x — a bare authorization code; state is taken from the authorization URL when it carried one (the loopback server forwards state verbatim and the SDK owns verification, so a missing one is not fatal). Anything with whitespace inside is prose (an error page fragment), not a code — refused with a clearer error than a server 400 would give.

Throws when the input can't be turned into a URL — no authUrl context for a partial paste, or an unusable authorization URL.

Split an editor command line into [executable, ...args].

Whitespace-separated, with single and double quotes honored so an editor living under a path with spaces still works ("/Applications/My App/bin/ed" -w). Quotes group and are stripped; backslash escaping is deliberately NOT implemented, because on Windows backslash is the path separator and treating C:\tools\ed as escapes would corrupt far more command lines than it would rescue.

Returns [] for an empty or whitespace-only spec, so callers can fall back to the platform opener rather than spawning ''.

Parse an <edit-outcomes>…</edit-outcomes> annotation block out of a tool result body. Returns the outcomes keyed by 1-based hunk index, or null when the block is missing / malformed.

Anchored on the explicit tag pair so the parser doesn't false-positive on natural prose that happens to contain #1 applied.

Parse one mcps.json file. Canonical zidane shape is a flat array; the other shapes exist for copy-paste from neighboring tools:

• McpServerConfig[] — flat array (recommended).
• { name: {...} } — name-keyed map.
• { "mcpServers": { name: {...} } } — Claude Desktop / Claude Code / Cursor wrapper. Unwrapped before normalization (otherwise normalizeMcpServers would treat the whole wrapper as a single server).

Per-entry enabled: false (Cursor runtime state) drops the entry — same intent as the source tool. Use the TUI toggle list for "show but disabled".

Tolerant to common copy-paste artifacts: when strict JSON.parse fails, retries after normalizing invisible whitespace that's valid Unicode but not valid JSON whitespace (BOM, NBSP, zero-width spaces, line/paragraph separators) — only OUTSIDE string literals, so user data isn't mutated. If the sanitized version still fails, throws the original error with a targeted hint when NBSPs are present.

Validation flows through normalizeMcpServers so the result matches what createAgent accepts. Throws on truly malformed JSON; the caller decides whether to surface or swallow.

Convenience patches for individual sub-fields. The provider class uses these so a saveTokens call doesn't have to round-trip clientInformation

• discoveryState it never touched.

Scan turns and return every interaction tool call without a matching tool_result, ordered by turn appearance. Works equally for live mid-run inspection and reload-from-disk.

Malformed payloads (input that doesn't match the tool's schema) are skipped silently — the call still lives in the persisted history, but the renderer wouldn't know how to display it. The next agent.run() on the session will see the orphan and synthesize an error tool_result via the loop's normal recovery path.

Re-quote a single argv token for a shell that will re-parse the joined command line — i.e. spawn(..., { shell: true }), which Node uses on Windows so that .cmd / .bat wrappers (how code, cursor and friends ship there) resolve.

Node does NOT re-quote when shell is set: it joins [cmd, ...args] with spaces and hands the string over. Since parseEditorCommand has already STRIPPED the user's quotes, handing tokens back unquoted would split C:\Program Files\ed.exe at the space and try to run C:\Program. This puts the quotes back.

Only tokens that need it are quoted, so a plain code stays code. A literal double quote is doubled, which is how cmd.exe escapes one inside a quoted run.

The test covers cmd.exe METACHARACTERS, not just whitespace: &, |, ^, <, > and friends carry none of the obvious "needs quoting" signals, so a repo cloned into C:\work\a&b would otherwise hand C:\work\a&b\AGENTS.md over bare, and cmd would split it at the & and run the tail as a second command.

% and ! are in the class so such a token is quoted rather than passed bare — but be clear about the limit: quoting does NOT stop cmd.exe expanding %VAR%, nor !VAR! where delayed expansion is on. Double quotes suppress splitting and other syntax, not expansion. That is a property of the shell which no amount of quoting can close; the worst case is a wrong path, not an injected command.

Read credentials from disk.

Returns {} when the file is missing or corrupt (last-ditch tolerance — a hand-edit gone wrong shouldn't lock the user out of re-authing). On first call with no file present, attempts a migration from a legacy .credentials.json in the current directory (the location older bun run auth versions used), when that directory is the home dir or the data dir.

Load + merge the user's keybindings file (when present). Always returns a fully-resolved KeyBindings — defaults fill in for any missing / invalid entries so consumers can treat the result as total.

Failure modes (all tolerated, all fall back to defaults):

• File missing
• File not valid JSON / JSONC (after comment stripping)
• Top-level is not an object
• Individual entries have invalid spec strings

Read the raw on-disk JSON object from keybindings.json after the JSONC stripper. Used by extension-keybinding resolution so the user's overrides for extension-owned ids flow through the same file the built-in actions use.

Returns an empty object on missing / malformed / non-object files — same fault-tolerance contract as readKeybindings.

Both stored credentials for a provider: active is the one every reader resolves, alternate is the stored-but-not-preferred one (if any).

Predates multi-account and only sees the #alt slot; use readProviderCredentials to list every stored account.

Every stored credential of a provider, active first.

Tolerant of any kind in any slot: #alt is meant for the API key and #account:N for OAuth accounts, but a file written by an older build (which parked the OAuth alternate in #alt) must still list everything it holds.

Redeem one banked reset on a provider's credential (Codex only): empties its rate-limit windows now. Spends a reset, so call it only on an explicit user action. The credential's cached snapshot is dropped, so the next fetch shows the new windows and count.

Never rejects: failures come back as code: 'failed' with a short error.

The redirect_uri the authorization server was told to come back to, read out of the authorization URL itself. That's our loopback callback (http://127.0.0.1:<port>/callback) — the UI shows it so an SSH user knows which address to fish out of the browser's URL bar, and normalizeRedirectPaste uses it to rebuild a full callback URL from a partial paste.

Returns null when the URL doesn't parse or carries no usable redirect_uri — callers degrade to "paste the whole URL".

Apply one event to the state map. Pure, immutable — returns a new map with only the affected key reassigned.

State transitions are simple "last write wins"; we don't gate (e.g.) a login:start from overriding authorizing because the loop layer never doubles those up — interactive login is serialized in the TUI.

Force-refresh the on-disk tools cache by opening a transient MCP connection to every server, capturing the mcp:tools:list hook on the way through, and closing the connection immediately. The underlying connectMcpServers runs every server's bootstrap in parallel, so the wall-clock cost collapses to the slowest server.

Two design choices worth noting:

• Shared hook bus. The caller passes the SAME Hookable instance that has the cache subscriber wired (typically agent.hooks after subscribeMcpToolsCache(agent.hooks, …) ran). That way mcp:tools:list fires on the bus the subscriber is listening to and the cache lands on disk without a separate write path.
• Transient, NOT shared with the live agent. The connection opened here is closed immediately. The agent's own MCP connection is untouched, so a refresh never disrupts an in-flight tool call.

The function intentionally swallows per-server failures (they're already surfaced via mcp:bootstrap:end ok: false for any host that wired the listener). The Promise resolves once every server's bootstrap settles, success or otherwise.

Sign a provider out — drops EVERY stored credential.

"Signed out" has to mean the provider resolves nothing afterwards, which is what this guarantees; promoting a survivor instead would silently leave the provider authenticated through another source. Callers that want that behavior use removeStoredCredential on the one slot they mean.

Render one or more AgentsMdFile into a system-prompt block.

Top header tells the model what's coming + that it's user-authored (so it's treated as guidance, not as a system constraint that can't be questioned). Each file becomes a sub-section with its absolute path so the model can cite it back when asking follow-up questions.

Exported separately so callers building custom profiles can inject their own discovery list (e.g. an SDK consumer pulling AGENTS.md from a remote source) without re-implementing the rendering.

Render a session into a string in the requested format.

markdown produces a human-readable transcript: a YAML-free header block with the title and a one-line id, turns, runs summary, a ## Metadata list (id, created, updated, status, turns, runs, tokens, cost), then a ## Conversation block where each turn renders as ### N. role over an italic ISO-date, run run_X, tokens … line, with text, thinking, tool calls, and tool results formatted as appropriate fenced blocks. Useful for sharing a session with a teammate or pasting into an issue tracker.

json returns a 2-space-indented, deterministic dump of the full SessionData blob. Useful for re-importing into the store or for post-hoc analysis tooling.

Wire format between the harness and the model — and, because it is persisted inside the user turn's text block, between a live session and its replay.

Follows <task-notification> exactly: child-tag XML, one block per event, escaped with escapeXml. The model already knows this shape as "the harness telling me something", which is the point — a main that mistook a worker report for a human instruction would act on it as one. eventsFromTurns detects the block on replay and re-synthesizes the structured row instead of painting the raw XML as a user prompt.

Seed contents for a freshly created SYSTEM.md override, built from the built-in doctrine.

Seeding with the real doctrine (rather than an empty file) means creating the override is a behavioral no-op until the user edits it. An empty seed would silently delete every line of doctrine the moment the file appeared, making the agent measurably worse with no visible cause.

currentSystem should be DOCTRINE ONLY — callers pass splitSystemPrompt(doctrineOnlySystem()).static, which excludes both the generated <env> block (rebuilt per turn) and the AGENTS.md block. Baking the latter in would duplicate it, since it is re-appended below the override on every compose.

scope is the active userInstructionsScope; it decides whether the seed's precedence note is true — see projectScopeOverridesLoad.

Resolve user options into a fully-bound runtime config.

NOT pure: besides disk reads, this mutates process.env so the harness providers pick up the chat engine's credential store — it sets ZIDANE_CREDENTIALS_PATH and reconciles stored API keys / OAuth entries into env via applyApiKeyEnv (which can overwrite or delete ambient keys like ANTHROPIC_API_KEY; see its JSDoc for the precedence rationale).

AgentOptions.decisions from settings:

• off (decisionsEnabled) → false (every decision returns unavailable).
• the picked model when its provider builds and its credentials allow it.
• otherwise the first available decision-capable provider (silent fallback, like the compaction model), preferring a provider with a native decisions endpoint over one that only approximates them.
• otherwise the first decision-capable provider that builds, so failures explain the missing credential; undefined when there is none.

Resolve the live spec string for each extension-contributed keybinding. The user's keybindings.json is consulted for an override on the binding's id; absent / invalid entries fall back to the binding's default.

A chord that is reserved or a bare printable character (see isReservedExtensionBinding, isBareCharExtensionBinding) is refused: a user override falls back to the default, and such a default resolves to unbound.

Pass the raw object (from readKeybindingsRaw) — passing KeyBindings here wouldn't help because the typed map only carries built-in KeyAction entries.

Returns one entry per input binding, in source order. Empty spec (binding declared default: '' and the user didn't bind it) is a legitimate "unbound" state — the dispatcher never matches an empty spec, so the action stays accessible via re-binding through keybindings.json.

Resolve the export target for a session id + format. Pure: no fs write happens here, the caller decides whether to existsSync the directory or hand the path to writeSessionExport.

Anchor selection walks upward from cwd looking for a .git entry; the first hit anchors to that repo's root (project). When the walk exits without finding .git, the destination anchors to home: the user's storage data dir.

Resolve the four storage slots according to the precedence above.

Pure aside from one filesystem probe (readdirSync(home/<prefix>), see holdsLegacyStorage). No directories are created here; the relevant write paths (state store, credentials writer, persist dir) handle their own lazy mkdirSync already.

Compute the on-disk layout for a single TUI session. Public so hosts (CLI tools, tests, scripted bootstraps) can ask "where will sessions land?" without going through resolveConfig's full machinery.

Storage-slot resolution (config / data / state / cache) is delegated to resolveStorageDirs. In legacy modes the four slots collapse to a single <storageDir>/<prefix> directory; in XDG mode they fan out into $XDG_CONFIG_HOME/zidane, $XDG_DATA_HOME/zidane, $XDG_STATE_HOME/zidane, $XDG_CACHE_HOME/zidane. See the module doc on ./xdg.ts for the full precedence chain.

Decision logic for project mode (least → most specific):

1. Default: OFF — sessions live in the user-scoped dataDir and get scoped per-project via the SessionData.projectRoot tag.
2. <configDir>/config.json projectDb flag (when present).
3. ZIDANE_PROJECT_DB env var (0 / false / off / no → off, 1 / true / on / yes → on, any other value ignored with a warning).
4. options.projectDb (host call site).

Project mode activates only when the resolution above lands on true AND a git repo is found above cwd. Outside git or with the flag off, sessions + state stay at the user-scoped slots.

Auto-creates the project .{prefix}/ directory when mode resolves to ON (silent — mirrors ensureStateDir), with a .gitignore of * when it creates the directory. User slots are created lazily by the state-store + credentials writers; we don't pre-touch them here so a read-only invocation stays read-only.

Resolve a model's remembered options for a (re)pick: keep only options the model still declares AND that are enabled, dropping any that no longer apply (e.g. switching away from a model that supported fast). Returns undefined when nothing applies so callers can omit the field entirely.

Shared by the TUI pick path and the launch-time resume path so "which options survive a model switch / relaunch" is decided in exactly one place.

Rewrite a multi_edit body header so the totals reflect the model's ORIGINAL edit list (the merged outcomes count) instead of the subset the body actually saw after gate rebinding. Without this, a partially approved call surfaces a misleading applied 2 of 2 edits (subset counts) on the wire even when the original was applied 2 of 3.

Three body-side shapes are handled (matching multi_edit's emit):

1. Edited <path>: applied N edits (R replacements).
2. Edited <path>: applied N of M edits (R replacements).
3. multi_edit error: no edits applied to <path> (M attempted).

The replacements count is preserved verbatim — it's a body-side stat the chat layer can't recompute. When the first line doesn't look like any of the three shapes (e.g. an unrelated error preamble bubbled up), the text is returned unchanged.

Structured stop notice for an abnormal finishReason, or undefined for a normal end.

Normal completions (stop / tool-calls) and user aborts return undefined — and so does a SUCCESSFUL auto-resume, because recovery ends the run on stop. That is what keeps the notice quiet exactly when the ceiling was handled rather than hit. error runs already surface their own error event, so a second notice would double-report.

Run the OAuth login flow for a provider.

Returns the OAuth credentials on success; caller persists them via setProviderCredential(dataDir, descriptor, { kind: 'oauth', ...credentials }). Throws when the descriptor has no oauthProvider configured.

Run the upgrade subcommand. Exit code contract:

• 0 — update succeeded, --check reported no update, or --check reported an update (informational only).
• 1 — update failed (PM exit non-zero, in-place download failed, registry check failed without --force, release not downloadable yet, or the installed version did not change).
• 2 — argv parse error (unknown flag).

Output is a short ledger, one line per package, led by a status mark (src/cli-style.ts): · zidane-tui 7.0.7 → 7.0.8 $ volta install zidane-tui@latest … ✓ zidane-tui 7.0.8 installed Diagnostics go to stderr and say what to do next.

Make one of the provider's stored credentials the preferred one.

Swaps the target into the canonical slot and parks the previous active one (see parkDemoted). Returns which of the three outcomes happened so a caller cannot report a swap that provably did not occur — the write is silent either way, and a void return would look like success to a caller that trusted it instead of refetching.

Store a credential as the provider's preferred one.

The previous active credential is demoted, not destroyed: otherwise authenticating with OAuth would silently delete a working API key (and vice versa), and a second OAuth login would overwrite the first account. An API key moves to alternateCredKey; an OAuth grant moves to the next free account slot. Replacing an API key with an API key is a plain overwrite — there is only ever one — and so is an OAuth login that names its predecessor via replaceKey.

Decide whether a session is ready for one-shot automatic titling.

Returns true iff the conversation has had its first exchange — at least two turns, i.e. the opening user message plus the assistant's reply (this is exactly the "N turns" count the sessions list shows) — AND no explicit title has been set yet. An existing metadata.title (a previous auto-generation, or a manual title from the session-details "generate title" action) is never clobbered.

Pure + total. The runtime layers its own "is one already in flight?" and "is a provider picked?" guards on top of this; the predicate only encodes the content-level rule so it can be pinned in tests without a mock provider — same rationale as the exported cleanTitle.

Starts the worker detached and follows it until it reports. The worker keeps going when this process exits. Never rejects.

A held lock answers skipped / locked without starting anything. A worker that cannot start, or stops without a result, answers lost; for an automatic install that also records the version as a transient failure (in memory when the cache dir can't be written), so it is retried on the backoff, not on every check.

Strip the first <edit-outcomes>…</edit-outcomes> block out of a tool result body, returning the surrounding text. Used by the tool:transform hook to peel a body-emitted annotation before re-appending the merged (approval ∪ body) version — otherwise the result would carry two annotation blocks and parseEditOutcomesFromResult would only see the first.

Anchored on the same \n<edit-outcomes>\n / start-of-string newline shape the parser uses, so prose that incidentally mentions <edit-outcomes> (e.g. a model summarizing its own format) isn't mistakenly stripped. Trims a single leading \n\n separator when present so successive strips don't leave dangling blank lines. Idempotent on inputs that don't contain a properly-anchored block.

Strip // line comments and /* … */ block comments from a JSONC source string. Stays out of string literals so a "foo // bar" value keeps its slashes. Exported for unit-tests; the only runtime caller is readKeybindingsRaw.

Trade-off: this is a tiny state-machine, not a full JSONC parser. It doesn't understand \\ outside strings (irrelevant for JSON) and doesn't track line numbers in error messages. Good enough for a config file — corruption in production gracefully falls back to the defaults via the try/catch in readKeybindingsRaw.

Strip the Tokens: … line from a spawn tool-result. The spawn-end marker displayed right above already shows the same stats; keeping the line in the rendered tool-result body just produces a visible duplicate (and, on reloaded older sessions, an inconsistent duplicate — the persisted line can use the 13 in / 4075 out shape while the freshly synthesized spawn-end uses the cache-aware in 92615 (cache 92602) / 4075 out shape).

Display-only: the persisted tool_result content is untouched, so the LLM still sees the full string in its context window. Anchored to start-of-line and matches both Tokens: 13 in / 4075 out (older) and Tokens: in 13 … (formatTokenUsage) shapes.

Subscribe to mcp:tools:list and persist every successful bootstrap into the on-disk cache. Returns an unsubscribe function — call it during agent teardown so a long-lived host (Settings modal that outlives one agent) doesn't accumulate stale subscribers.

Each write loads the current cache, upserts the named entry, then atomic-writes the full file. The read-modify-write is safe under Node single-threaded event loop semantics — concurrent bootstraps in the same process serialize through the hook bus.

Optional onChange callback fires synchronously after every successful disk write with the entry that was just upserted. Lets a React host trigger a state refresh without polling the disk.

Write failures are swallowed (logged under ZIDANE_DEBUG): the cache is an accelerator, not a correctness boundary. If the disk is full the agent run still works — the settings UI just shows stale data until the next successful write.

Suggest the safelist entries to persist when the user picks "accept and remember" (or "accept for session") for a { tool, input }. Heuristic:

• shell → one shell:<head>:* per DISTINCT command head, parsing the command the SAME way isOnSafelist matches it (&&, ||, ;, |, $(…), subshells, backticks). So cd dir && cat file yields ["shell:cd:*", "shell:cat:*"] — persisting the whole set is what lets the next identical call skip the gate. A single first-token entry would only cover cd, so isOnSafelist's every-head check would fail on cat and re-prompt forever.
• shell with an unparseable / empty command → first-token heuristic, else the bare tool name.
• browser_open / browser_navigate to a non-loopback address → <tool>:<host>: approving one site does not approve the web.
• anything else → bare tool name (broad).

Always returns a non-empty list so the UI has a concrete set to render and persist.

Truncate text to at most max characters, replacing the trailing overflow with …. Edge cases:

• max <= 0 → empty string (no room to render at all).
• max === 1 → just the ellipsis glyph.
• text.length <= max → unchanged.

Trailing-style truncation matches the natural read order of titles: the prefix carries enough signal to identify the surface.

Unwrap a call_tool envelope. null when name is not the dispatcher or the envelope is malformed (missing / non-string name, non-object arguments) — callers then treat the call as a plain call_tool call and let the dispatcher's own schema validation produce the error the model needs to fix its input.

arguments may be omitted for zero-argument tools: it defaults to {}.

Update the trailing 'tool' event matching callId so its edit.outcomes reflects the canonical merged outcomes the chat layer's tool:transform hook just computed. Without this, the live diff badges stay frozen at whatever the gate set (approval-side outcomes) and never reflect body-side failures from multi_edit's best-effort run — only a session reload re-attaches the merged outcomes via eventsFromTurns.

Walks back-to-front because the matching event is overwhelmingly the most recent (we're updating right after the body returned). Returns the same reference when no match is found (or the event already carries the target outcomes), so React skips the re-render.

Drive a prompt-completion popover from React state.

Inputs are pull-style — the caller owns text + cursor (typically mirroring an OpenTUI TextareaRenderable or a <textarea> element) and passes them in each render. Providers are matched by their trigger character; every provider that shares the trigger at the cursor is bound and their suggestions merge into one list.

Asynchronous suggest calls are aborted when the query changes or the popover closes, so providers that hit a backend don't leak.

Bind an "enabled allowlist" setting to a discovered catalog.

keyOf extracts the persisted identity from a catalog entry (skill name, MCP server name, …). Pass a stable, collision-free key — the persisted allowlist is keyed against it forever.

Bind every server in catalogByServer to its own per-tool toggle in a single hook call. Returns a serverName → McpToolToggleSet map.

Use this when a host needs handlers for multiple servers at once (the TUI's MCP settings panel keyboard dispatcher is the canonical example) — calling useMcpToolToggleSet in a for / .map over a dynamic catalog would change the hook-call order whenever a server is added or removed, violating React's rules-of-hooks. This hook calls useMemo exactly once regardless of server count.

Servers absent from catalogByServer get no entry in the result. The persisted deny-list still keeps their entries on disk — they just stay invisible to this consumer until the catalog re-includes them.

Bind a single MCP server's per-tool toggle to Settings.disabledMcpTools[serverName].

catalog is the FULL list of tools the server advertises (i.e. the cached listTools() payload from chat/mcp-tools-cache.ts). The hook needs it both to render enabledSet (every catalog tool not in the persisted deny-list) and to garbage-collect stale deny-list entries on every write.

Whether a USER-scope SYSTEM.md would be loaded under scope.

Mirrors the candidate filter in discoverSystemMd so a host can ask "would writing ~/.{prefix}/SYSTEM.md accomplish anything?" without re-deriving the rule and drifting from it. 'project' excludes the user candidate and 'none' skips discovery altogether, so under either setting creating that file is a silent no-op.

Absolute path of the USER-scope SYSTEM.md — the file the TUI creates when the user asks for an override and none exists yet.

Exported so the host doesn't hardcode the layout and can't drift from what discovery actually reads.

Returns the current update status. The check fires:

• Once per mount (every TUI launch).
• Every recheckMs after that, when set.
• Every time enabled flips from false → true (user re-enabling the setting expects an immediate refresh).

The check is async and deferred by delayMs so it never competes with first paint. Result is null until the first check resolves; flipping enabled to false resets to null so any chip rendered against hasUpdate disappears immediately.

The hook owns its own AbortController so an unmount cancels any in-flight registry request cleanly.

Write credentials atomically (write-then-rename) with mode 0o600.

Atomic on the same filesystem — readers either see the previous file or the new one, never a half-written intermediate. Creates the parent dir if needed (first launch on a fresh machine: ~/.zidane/ may not exist yet).

Reserved suffix marking a provider's SECOND credential slot.

Not usable as (or as the tail of) a descriptor's credential key: foo#alt holds foo's alternate credential, so a provider claiming that name would share storage with it.

Build agent — the default profile. Full read/write/shell access plus subagent spawning. Its tools are those of the basic preset plus glob, grep, web_search and fetch_url.

The system prompt is the cwd-less variant of buildBuildSystem; the TUI overrides it per-session with an env-anchored composition so the prompt carries the current project root + date. SDK consumers calling createAgent({ ...BUILD_AGENT.preset }) directly get the cwd-less prompt and can wrap their own env section.

Default provider registry. Passed verbatim when runTui is invoked without an explicit providers option. Hosts that want to override per-provider metadata can spread this and replace specific entries:

runTui({ providers: { ...BUILTIN_PROVIDERS, anthropic: myOwnAnthropicDescriptor } })

cursor is intentionally NOT registered here: OAuth works, but inference isn't wired (cursor.stream() throws — Cursor speaks a protobuf/HTTP-2 agent protocol, not OpenAI-compat). Shipping it in the picker only lets users select a model that errors every turn. The descriptor stays exported so a host can opt in ({ ...BUILTIN_PROVIDERS, cursor: cursorDescriptor }) once the transport lands — re-add it here at that point.

Built-in theme registry, keyed by theme.id. The TUI looks up the active theme here using Settings.theme; unknown ids fall back to DEFAULT_THEME. Extensions add themes with ctx.registerTheme. The resolver receives them as extraThemes, and built-ins win on an id collision.

Insertion order is the picker cycle order — keep default first so a fresh install (no theme in state.json) sees the default theme before the others.

Tools whose output is exempt from the per-turn toolOutputBudget accounting, for SDK consumers that turn the budget on. The built-in profiles leave it off.

These tools exist to LOAD context into the conversation — their text output IS the value of the call. Counting it against the budget steers the model away from the very tool it needs to make progress (e.g. a 78 KiB tool_search response for a 20-tool Notion MCP server would trigger the "summarize before calling more tools" nudge on the very turn that unlocked those tools, making them effectively unusable).

Note this list is intentionally narrower than DEFAULT_PERSIST_EXCLUDE_TOOLS: read_file is NOT exempt — a 200 KiB file load is exactly the case the budget should steer against. Same for spawn (a sprawling subagent report should still nudge a consolidation pass).

Exported so SDK consumers building custom profiles can extend the list for host-defined context-loading tools.

Tools the chat layer never persists to disk, regardless of output size.

Rationale per entry:

• read_file — our reader is already paginated (offset + limit). Persisting the slice the model asked for and pointing it at the persisted path is circular; if the model wants more, it pages.
• tool_search — short metadata envelope. Never large.
• skills_use / skills_read — the <skill_content> body is intentionally part of the prompt; persisting it defeats the purpose.
• read_chat_turns — previous-chat excerpts are explicitly loaded conversation context; persisting them defeats the purpose.
• present_plan / ask_user — short JSON envelopes (decision + answers). Never large.
• spawn — the subagent's final report IS the value of the call; stubbing it out would defeat the orchestration pattern.
• codemode — a script prints what the model asked for, as a read does, and caps its own output (max_output_tokens: start and end inline, the full text in a file). Persisting it would force a re-read.

Exported so SDK consumers building custom profiles can extend the list (e.g. host-defined screenshot tool whose base64 payload should stay inline). Set behavior.persistExcludeTools to your own list to fully override.

Software-engineering doctrine. Lifted in spirit from claude-code's # Doing tasks (constants/prompts.ts:199-253). Key levers:

• Stick to scope — prevents speculative refactors that double output tokens.
• No narration comments — prevents inflating diffs with // Import the module lines.
• Verify before claiming done — prevents false-positive reports that force a follow-up turn.

Tools that always pass without prompting. Four categories, plus the dev-browser, terminal-read and side-session tools noted inline in the list:

• Pure reads (read_file, list_files, glob, grep) — no side effects on disk or the model's own state.
• Interaction tools (ask_user, present_plan) — the call itself surfaces a TUI picker the user has to answer, so prompting for approval first would mean "approve this prompt before you see the prompt": redundant + breaks the flow. The picker IS the gate.
• Todos (todowrite, todoread) — write to a slot on session.metadata.todos and nothing else. No shell, no disk, no network. The model uses these for checkpointing every few steps; a per-call approval prompt would drown the conversation in interruptions that buy no safety since the tool's surface is read/write on a metadata bag we already trust the agent with.
• Skill activation (skills_use) — mutates a small per-agent Map of active skills and returns the activated skill's bundled instructions (or releases an entry on mode: "deactivate"). Pure state on the agent — no shell, no disk writes, no network. Gating it would also defeat the "model recovers from AgentToolNotAllowedError by calling skills_use({ mode: "deactivate", name })" path: a stuck model would have to ask the user permission to unstick itself on every retry. skills_read and skills_run_script are intentionally NOT on this list — the former touches disk and the latter executes arbitrary scripts, so both keep going through the regular gate.

Users who want to gate any of these must disable safe-mode entirely (or fork this list in their own embedding).

Local OpenAI-compatible LLM (Ollama, vLLM, LM Studio, Lemonade, llama.cpp).

No fixed base URL or model catalogue — both come from the user via customFields. No envKey, so the wizard skips the API-key prompt and treats the customFields-only credential as the auth signal (see applyApiKeyEnv + detectAuth).

Vision / cache / reasoning are off by default in the factory — flip them by passing a custom descriptor that calls local({ capabilities }).

models is a getter, not a static list: there's no fixed catalogue to ship, but once the user has configured a default model (mirrored into LOCAL_LLM_DEFAULT_MODEL by applyApiKeyEnv), we surface it as a single-entry list so the model picker + footer aren't empty. Resolved at access time because the env var is populated at TUI launch, after this module loads. Empty list when unconfigured — the picker hides, the user types a slug at the prompt as before.

Plan agent — read-only exploration mode. Locked down to file reading and codebase search; no shell, no edits, no spawning. The system prompt frames the conversation as planning rather than execution so the model outputs proposals instead of attempting mutations.

In Build's family: a session switching between them keeps Build's agent, a gate enforces Plan's tools and its rules arrive as a note.

How to brief a subagent. Spawning a child agent is the highest-leverage token move in zidane — a 5k-token research dive becomes a 200-token summary in the parent's context. But shallow prompts produce shallow work, so the doctrine is mostly about quality of the briefing.

Lifted from claude-code's ## Writing the prompt tool-prompt (tools/AgentTool/prompt.ts:99-113).

Watches cwd's repository; resolves the stop, or null when cwd is not in one.

On macOS a recursive watch rides the thread's FSEvents stream, which every start and stop rebuilds, and a stop waits for that rebuild: seconds when the system's file events are busy. A process that must not wait (the desktop app's main thread) runs it on a thread of its own.

Host-supplied auto-update settings. The check itself is gated on Settings.checkForUpdates; passing a config wires the React plumbing.

Hosts that want to publish their own consumer-facing package can pass different values without forking anything — the registry / channel / platform-package-prefix are all knobs.

One server's cached entry.

• tools — verbatim copy of the raw tools/list payload (pre any disabledTools / toolFilter filtering). The settings UI ranges over this to render the full server surface; the host applies its own deny-list on top via Settings.disabledMcpTools (see buildMcpServers in mcps-discovery.ts).
• updatedAt — ms-epoch of the bootstrap that populated this entry. Useful for "last seen N hours ago" affordances and for cache eviction policies a host might layer on later.
• transport — informational only; lets the UI distinguish a stdio server's tool list from an http server with the same name in "stale catalog" warnings.

A block of local output a step renders into the chat.

Plain blocks (text only) render as full markdown, both live and on reload — use them for the output the user should read in full (e.g. a final commit message). Blocks with detail render as a collapsed command-detail row instead (dim ▸ label + line-capped body with "… N more lines") — use them for bulky supporting output (diffs, logs, listings) that shouldn't drown the transcript.

Free-form configuration field that a provider needs the user to supply alongside (or instead of) an API key — e.g. a self-hosted base URL, an Azure deployment name, a default model id.

The wizard prompts for each field in order. Submitted values are persisted into the apikey credential (as customFields[key]) and mirrored into process.env[envVar] so the provider's factory can read them via the same env-var convention as envKey.

Descriptors without an envKey use customFields as the sole credential mechanism — the wizard skips its API-key step in that case.

Structured edit data attached to a tool event for edit / multi_edit / write_file. Lets the renderer compute a unified diff without re-parsing the JSON input string.

• edit produces one hunk with replaceAll defaulting to false.
• multi_edit produces one hunk per edits[] step (in order).
• write_file produces a single hunk where oldString is the pre-write file content (empty for a fresh create) and newString is the new content; replaceAll is meaningless here and absent.

Live capture happens in the host's tool:before hook (where the pre-write snapshot can be read off disk before the tool runs). Historical replay from persisted turns can only reconstruct the edit/multi_edit shape — write_file historical events have no pre-write content and render with oldString: '' (= every line is an addition), matching git's "new file" diff convention.