zidane/extensions

Applies a report to a live registry, one extension at a time: changed folders through reloadChangedExtensions (loaded, reloaded or unloaded in place), linked folders it does not hold yet loaded, unlinked ones unloaded, each held entry's enabled set to what the config and allowed say (a reload of that extension), and the report's failures listed as inactive rows (config:<scope>). Never rejects for an extension's fault.

The target for an artifact row (Artifacts panel / rail): its kind's badge kind (commit, pull request, file; artifact for the rest), the row's title and link, and what "Add to prompt" inserts: a commit's SHA, a file's path, the link, else the label.

Human label for a kind (Pull request), falling back to the raw kind string.

The full menu: built-ins then extension items, ordered by group (stable within a group). An extension shortcut that collides with an earlier one is dropped, never the item.

What "Add to prompt" inserts for a target.

Collapse the extension registry's agent-side surface into a single Preset ready to spread into createAgent(). Hooks bucket per-event (every handler fires, copied into fresh arrays), tools shallow-merge (last extension wins on canonical-name collision), mcpServers concat with name-dedup (latest wins — mirrors composePresets), skills concat. Extension instructions don't land here: the agent reads them from the runtime (ctx.instructions).

The built-in actions for a target (host-implemented; see builtinBadgeEffect).

The effect of a built-in action; undefined for an id that isn't one (or doesn't apply).

The built-in key bindings (KEYBINDING_DEFS) as ctx.keymap.list reports them, with the user's keybindings.json applied. What a host passes as CommandHostPort.keybindings.

Installs an extension again from another source, in place: the source must hold an extension with the same name (else name-mismatch, with the names found), the folder is replaced only once the new copy fetched, installed its dependencies and validated (the install's transaction), and .install.json records the new source, which later updates follow. Works on any installed folder, with or without a recorded source.

Clamp a number to the item's [min, max] and snap to step (when set). Used by the input-row commit paths so a user-typed value is coerced into range before it's persisted.

14:05: a local wall-clock time, the same on every surface.

Coerce a raw input string (from a free number / string input row) into a valid persisted value, or undefined when it can't be made valid. Numbers are parsed + clamped; strings are taken verbatim and checked against the pattern; enum / boolean items aren't edited via free input (they use choice / toggle rows) so they return undefined here.

Compile a pattern, or null when its source doesn't parse.

The usable providers as a composer lists them.

Compose extension agent-loop contributions under a host/profile preset and apply extension subagent additions/overrides to the winning spawn tool. With a runtime (registry.runtime), the agents catalog's sub-agent edits apply: registered, added and edited sub-agents join the adds, removed ones become deleting overrides.

The inactive rows of a report's failures: named after the entry's source, carrying the reason.

Reads both config files and their locks: the folders to load in place and the ids to load disabled. Project entries count only when trustProject. Never throws (a broken file reads as no entries).

This process's module for every entrypoint of hostModuleSpecifiers, loaded lazily. Typed as a full record, so a specifier added to the list fails to compile until it is mapped here.

undefined when the registration has no detect. The hook never touches result / isError; a throwing detector emits nothing. Entries default kind to the registration's kind; validateMeta applies to entries of that kind only and drops meta, never the entry.

Build the ctx.artifacts facade over a host-runtime bridge. Read-only; every call re-resolves the scope (session switches swap it). Detached, or a store without artifact support, answers [] — the same honest degradation as ctx.sessions.

Creates a CompletionRunner. A provider that ignores its signal can't hold the answer past timeoutMs.

Builds the layer. Pass the user source first and the project source after: a later source wins per key and for enabled.

An AuthStorePort over <dataDir>/credentials.json.

Creates a bridge that hosts attach their runtime implementation to.

Creates a bridge with no handler attached. submit returns false until a host attaches one.

Creates the coordinator. One per process: scopes are keyed by config file, so every registry of the same user (and project) shares one run.

Creates an empty facet registry.

Makes the default file-backed storage port.

An in-memory settings port.

An in-memory storage port. Every save and delete is announced to every subscriber of the location, so two caches in one process stay in sync (the domain drops echoes of its own writes).

A client port that records each call. Panel, navigate, composer and keymap dispatch calls resolve true; panelState resolves the panels opened so far.

A cached resolver over the registry's providers.

A live ExtensionRegistry over source, narrowed by filter.

The change feed and disposal of one runtime, shared by every view of it.

A dialog port with one client that answers from queued answers.

Creates an empty set of shared watches.

Default scan roots for extension discovery. Mirrors defaultSkillScanPaths / defaultMcpsConfigPaths; the subPath is 'extensions' so each root expands to <scope>/.<convention>/extensions/.

Returns definition unchanged. It anchors type inference for ctx.

Dispose resources owned by an extension registry. Idempotent per registry.

Extension items for a target, in registration order, after validation: ids and labels must be non-empty strings, ids unique per source, at most eight per source. A throwing actions contributes nothing.

A settings port over the host's settings bag (Settings.extensionConfig), which today's Settings UIs write: it is the user layer, and the source of secret strings too. Writes are left to the host, which persists what its Settings UI and action results give it.

The runtime behind registry.runtime (load, unload, reload, settings), or undefined when the registry loaded no extension.

One extension's settings wire with its settings pages, or undefined when it has no definition (failed validation) and no page.

A short name of an install spec: owner/repo with @ref when one is pinned (the folder in the repository left out), an npm package with @version when one is pinned. A spec that does not parse is returned as is.

Materialize the source into destDir (created by the caller, assumed empty). Returns the provenance string plus, for git clones, the exact commit SHA. See fetchInstallSource for transport details and caps.

Read one PR. Path segments are validated to the shape a real repo has (callers pass untrusted strings: artifact meta, matched text), so a crafted owner can't steer the token-bearing request elsewhere. 4 s deadline per request, or signal.

Every reference in text for the providers that scan surface, sorted, without overlaps: the earliest start wins, then the longest, then the earlier provider. Zero-length matches are skipped.

An issue as a reference view: its state icon and color, its number, a hover card.

The PR's canonical URL: the uri its pull_request artifact is stored under.

A PR as a reference view: GitHub's state icon and color, its number, a hover card.

Why GitHub data is stale, in a few words: a pause until a time, or the anonymous limit.

The key an issue or PR number is resolved by: owner/repo#123.

The specifiers a host must map for installed extensions at runtime, for registerExtensionHostModules. UI modules (react, OpenTUI) are the renderer host's own business and not listed.

Tag an inline (host-passed) extension into the same shape disk- loaded ones produce, so host-bundled extensions (e.g. those passed via RunTuiOptions.extensions) flow through buildExtensionRegistry identically to disk-discovered ones. The runtime validates the definition and lists it inactive with what is wrong.

The full fetch → enumerate → deps → validate → copy pipeline. See the module doc for invariants. Throws ExtensionInstallError; a throw means nothing was written to the target roots.

Adapts a zidane/oauth provider flow to an integration method of type custom. connect runs provider.login with the host's flow UI (links, device codes, prompts and choices go through IntegrationFlowIO); the credential's accessToken is provider.getApiKey(grant), the refresh token is kept by the store, and other grant fields ride in credential.extra. refresh runs provider.refreshToken. The account is the grant's email, account or label when it has one.

Whether value is a color hosts accept (#rgb / #rrggbb).

Whether v is a valid ExtensionPanelScope.

Whether value is plain JSON: finite numbers, plain objects with safe keys (see isSafeRecordKey), arrays, strings, booleans and null.

Whether v is a valid PanelSurface.

Whether a stored PR is current: fresh, or in a state that never changes.

Whether a loaded entry carries a module for the runtime (as opposed to a load error).

Whether specifier names a module the renderer provides.

Whether an authored item is well-formed for its declared type — used by ctx.registerConfigItem to drop malformed declarations (wrong / missing default, an enum without options) before they reach the registry. Cheaper than letting a broken item ride to render time.

Whether value is a valid concrete value for item — type match plus the item's constraints (number range, enum membership, string pattern) and the optional author validate. step is intentionally NOT enforced here (it's a UI affordance, not a hard constraint — a persisted value or default that doesn't align to the step is still honored).

The action rows: the counterpart of toWireConfigSchema, which strips them.

List the installable extensions inside a fetched tree. fallbackName seeds the single-extension case when no manifest names it (repo or unscoped package basename).

Every provider's items for cwd, normalised and stamped with the provider id. A provider that throws or hangs contributes one disabled row naming the failure, so the user sees why an expected command is missing.

The folders discoverExtensions would import for the same options: a trusted extension's, never an untrusted project's. What a host compiles ahead of a load (precompileExtension).

Imports one extension folder fresh from disk, as discovery would (version check, manifest, module graph evicted first). Never rejects: a folder with no entry file or a module that fails to import comes back with error. The caller decides whether the folder may load at all (trust, precedence): loadableExtensionDirs answers that.

Runs a panel's load() for a context from across the boundary (known string fields only, bound to cwd). A missing, throwing or hanging panel yields an empty content naming why.

Reads and parses both config files and their locks. Feed [user, project] to createConfigSettingsLayer.

Order items the way badgeMenu does: by group, stable within one, later colliding shortcuts dropped. For hosts that get the built-ins and the extension items separately (the GUI renderer asks main for the latter).

Joins the wire settings of several extensions into the one list the Settings UI reads.

Every specifier of hostModuleSpecifiers that is not mapped yet. Hosts check it after their registration (a test, a debug log).

An effect from extension code, reduced to known, bounded string fields.

A target from across a boundary (the GUI renderer), reduced to its known, bounded fields; null when unusable.

Coerce whatever load() returned into a well-formed PanelContent: unknown item kinds and malformed entries are dropped, strings are trimmed to the caps, and the whole thing is size-bounded. Never throws.

A home layout from a registration or across a boundary, kept only when well-formed.

A load context from across a boundary (the GUI renderer), reduced to its known string fields. Hosts run it before handing the context to load / onAction.

Calls listener each time a settings page of ui is added, replaced or removed: the settings wire changed, read it again. Protocol clients follow the same extensions:ui changes (ExtensionsClient.settings.onChange).

Tab badge as shown next to the label; undefined when nothing to show.

The host runtime a panel's load / onAction (or a badge action) runs in, read-only: the folder's project (projectRootOf(cwd)), plus the session when one is bound. ctx.artifacts.list() answers that session's artifacts ([] unbound), list({ scope: 'project' }) every session's under the project root. Store-wide queries (scope: 'all', find) answer []; record needs a session, so it answers undefined unbound. Everything else reads as detached, as it does for any extension code outside a run.

Whether a panel shows on surface.

Whether a panel registered with scope shows in a context bound to bound (absent scope = 'session').

Summaries of a folder's panels.

The surfaces a panel registered for (absent or empty: ['side']).

A control's value in a view: the picked option id (segmented, select), or fallback when the user picked none or the value is a list.

A multi control's picked options in a view: fallback when the user never touched it.

Classify a raw source string. See parseInstallSource for the grammar.

Parses a key built by githubRefKey. Returns undefined when key does not have the owner/repo#number shape.

git show --shortstat --format= → { additions, deletions, changedFiles } ( 4 files changed, 120 insertions(+), 8 deletions(-)). Any missing clause is 0; an empty stat (empty commit) is undefined.

Partition a registry's loaded + inactive lists into the shape the Settings toggle UIs render. Pure; shared by the TUI's standalone extensions modal and the Settings-modal tab so the rules (and the allowlist-GC key set) stay in one place.

Compiles an extension folder's TypeScript into the cache, as a load would. Files whose entry is current are only checked. A file that does not compile is skipped (the load reports it).

Every action's passive status(), keyed extension:key. A probe that throws, times out or answers no message is left out.

The folder that holds one project's extension storage, after moving what an earlier build left in the project (once per process and project).

Drops the entries not rewritten in maxAgeMs.

A PR's checks line, when it says something (open PRs only).

A PR back from artifact meta, when the meta says enough to draw it (a refresh has filled the title and state); undefined otherwise. Untrusted input: every field is type-checked.

A fetched PR as pull_request artifact meta (merged over what was there): the one stored copy the session badge, the Artifacts row and the hover card all read.

How a PR state reads, GitHub's way. Unknown (not read yet): the plain PR icon, muted.

Where an installed extension came from (its .install.json), or null for one not installed from a source (hand-written, linked, built in).

Read .install.json provenance from an installed extension dir, or null.

The providers a host offers for a registry: the extensions', then the built-in ones (BUILTIN_REFERENCE_PROVIDERS: GitHub pull requests) whose id no extension took. builtins: false leaves those out.

The host's providers (see referenceProviders) as wire data, in order.

Lazy refresh: run the kind's resolve() and return the artifact with the patch applied (updatedAt bumped), or undefined when the kind has no resolver, the resolver declined, or it threw. Callers persist the result through their store / RPC — this never writes.

Maps every zidane entrypoint of hostModuleSpecifiers (zidane, zidane/extensions, zidane/extensions/testing, zidane/providers*, zidane/oauth) to this process's live modules, so an extension installed outside the repo (no node_modules/zidane beside it) can import their runtime values, such as Panel or createTestHost. Lazy, so registering costs nothing until an extension imports one. Every host calls it before its first extension import; idempotent.

Map bare import specifiers to the host's live module objects for every subsequently-imported module (extensions included). No-op outside Bun and for already-registered specifiers. Call BEFORE the first extension import (the TUI does, at startup).

Applies folder changes to a runtime: a held folder that changed is imported fresh and reloaded in place; one whose folder or entry file is gone is unloaded (its ctx.storage.memory cleared); a new folder loads when options.classify allows it. Given a registry, a folder it refused at build time (its import failed, an untrusted project folder) counts as new, and leaves the refused list once it loads or is deleted. Folders are handled one at a time, in the order given (duplicates once). Never rejects for an extension's fault: a module that fails to import is listed failed with the error.

Delete an installed extension's directory. Works on any on-disk extension (hand-authored ones too — no provenance required); the containment guard is the safety boundary. The caller owns follow-up (allowlist cleanup, registry reload).

Row presentation with the guaranteed fallback. A render that throws or returns nothing degrades to label + uri — a stored artifact is never invisible because its kind's extension is gone or buggy.

Resolve the registration for a stored artifact's kind: the active registry wins (an extension may refine a built-in's presentation), then built-ins, then undefined — callers fall back to label + uri.

Runs the submit hooks of the usable providers that declare one, with the same reference collection as the terminal app (resolveCompletionSubmit).

Convenience read against a merged ExtensionRegistry + the user's Settings. Looks up the item schema (extName → key), reads the persisted value out of settings.extensionConfig, and runs it through resolveExtensionConfigValue. Returns undefined only when the (extName, key) pair names no registered item.

Resolve the effective value of a config item from its persisted value. THE single place graceful degradation lives: a persisted that's undefined (never set) OR fails isValidExtensionConfigValue collapses to item.default. Action items hold no value and resolve to undefined — the overloads keep value-item call sites exact.

Normalise raw and bind it to the host's cwd (which wins over any cwd in raw): the context load / onAction receive. scope follows sessionId.

Run one menu item: a built-in resolves locally, an extension item runs its registration's run (8 s deadline). Never throws: failures come back as a notice.

Runs one action. The config patch it returns is sanitized (unknown keys and values failing the schema are dropped) and returned, not written: the app persists it through its settings writer.

Runs itemId on its provider source.

Runs a panel's onAction as loadExtensionPanel runs its load.

A discovered entry as the runtime loads it: its module, or its import error (RuntimeEntry.error).

Wraps a definition as a LoadedExtension entry for the runtime.

Every extension's settings wire of a runtime, merged in load order.

Gate the config patch an action returned before the host persists it. Per-entry, an item is accepted only when it names a registered VALUE item of the declaring extension and passes that item's schema (isValidExtensionConfigValue); everything else lands in rejected for logging. Pure — the host applies accepted through its own settings write path.

The target for a session badge (or one row of its card): GUI sidebar, TUI sessions list.

Several sessions' badges at once (the sidebar rows). One badge per kind, so one registry per session: the one of the project its newest artifact landed in.

Every settings row of the given extensions, with the page and section it is on, for the settings search box. Rows of ui pages with a schema are included, on that page; component-only pages have none. Order: the extensions as given, then page and row order.

Builds the settings sidebar from each extension's wire. An extension without pages (no settings, no settings-page items) is left out. Works for disabled extensions too: their wire comes from the definition.

Keeps every provider's subscribe on, their emits debounced into one onChange.

Keeps a panel's subscribe on, its emits debounced into onChange.

Runs one provider's suggest and keeps the well-formed items, at most MAX_COMPLETION_ITEMS. A throwing provider or a non-array result answers []; insertText falls back to the item id.

Whether a UI change adds, replaces or removes a settings page (reset: every item may have gone).

Project the merged registry's config schema into a wire-safe shape: categories as a flat array, items flattened to a single list carrying their extension + category, with the non-serializable validate callback stripped. Action items are omitted entirely — their run callback only exists in the main process, so a remote renderer (the GUI) has nothing it could do with the row. Pure — factored out so its serialization is unit testable without an Electron / IPC harness.

The providers a composer can render: drops invalid ids / triggers / suggest functions and the reserved triggers, first wins on both id and trigger.

The view for a #N read that found no PR: the issue, or while a rate limit holds a neutral #N that says so (it may be either), or nothing.

The view for a background read: the PR when GitHub answered; when a rate limit stopped it, the newest copy this process holds with the reason, or a muted #N that says it; nothing when the PR can't be read.

An extension's wire with its SettingsPage items appended to its pages (after the schema's pages, by order). Hosts call it where they build an extension's settings wire and hold its UI registry.

Adds an extension's SettingsPage items to its wire, after the schema's pages, by order (default 100; ties keep the given order). Items of other extensions (their id does not start with <extensionId>/) are ignored. Pure.

Thrown by a dialog that got no answer within its timeoutMs.

Thrown by a ctx call made through a disposed owner.

Error thrown by the extension installer. code says which step failed.

Thrown by a dialog when no client can show it.

The error a client call rejects with. type is a declared error name or one of the reserved rpc.* names.

The most sessions one read of badges answers (artifacts.badges).

Context-menu actions on badges, links, files and artifacts.

Built-in branch kind. Detects branches the model created, such as with git switch -c.

The built-in artifact kinds: pull request, branch, commit and file.

Reference providers hosts offer next to the extensions' (an extension's provider wins on id).

Built-in commit kind. Detects commits from git commit runs and shows their change size.

How old an entry may grow without being rewritten before pruneExtensionCompileCache drops it.

How long a provider's suggest, or the submit hooks, may run before the answer is given up.

A context breakdown or context panel section.

Helpers to declare contract tokens.

Empty registry — useful as a zero-value when no extensions are loaded. Frozen (shallow + nested) so a consumer can't accidentally mutate the shared sentinel and poison every other reader.

An MCP port with no servers. Calls reject.

Entry-point filenames probed inside each <name>/ directory, in preference order. Bun loads .ts / .tsx natively; .mjs / .js are accepted so pre-compiled extensions (or vibe-coded JS-only ones) work too. index.js is last because most authors will reach for .ts first.

The API version this runtime supports.

Bound of one facet's compute, in ms.

file has NO automatic detector for plain writes on purpose. Every write_file becoming an artifact is noise — a refactor would produce dozens of rows that are really just the diff and go stale on the next rename. A file is an artifact only when something deliberately says so: the model via record_artifact (a generated report, an export), an extension via ctx.artifacts.record (a build output), or a tool whose whole output is the file (generate_image, generatedImageKind). The kind keeps its rendering and file: URI canonicalization for those paths.

Id of the built-in reference provider for a bare #123: an issue or a pull request.

GitHub's state colors (Primer). Draft stays the theme's gray.

Id of the built-in reference provider for GitHub pull requests.

#12 in a chat whose repo is on GitHub, keyed like a PR (githubRefKey(owner, repo, 12)). No patterns: only the host knows the repo. GitHub's issues endpoint says whether the number is an issue (drawn here) or a PR (read and drawn as github.pull draws it).

PR links (https://github.com/o/r/pull/12, with or without a tail) paint as #12 at once and gain their state when GitHub answers. #12 alone needs the chat's repo, which only the host knows: hosts resolve it through this provider with the key githubRefKey(owner, repo, 12).

Indirection so tests (and hosts with their own credential store) can swap the token source without touching the environment or the gh binary. resolveWithSource is consulted only while resolve is the default.

The zidane entrypoints an installed extension may import at runtime. A host maps every one to its own live module before it imports an extension (registerCoreExtensionHostModules in discover-and-build.ts does it from hostModuleSpecifiers); unmapped, an installed copy or a compiled binary resolves them from the extension's folder and finds nothing.

Every LinkSource.

Opens matching links.

Most items a provider's popup lists.

How many composer.badges items one extension may show in one session, and app.titlebar items in the app.

The most JSON one facet value may take, in bytes of its JSON text.

How many facets one extension may hold.

Longest URL a link handler is offered.

How many sidebar rows one extension may show.

How many items one extension may show in a badge slot (isBadgeSlot); per session for composer.badges.

The client id createScriptedDialogPort and createRecordingUiClientPort report.

A native menu entry.

A dialog port with no client: every dialog rejects with NoUiError, toasts resolve undefined.

An integration flow port for hosts that cannot show a sign-in flow.

A client port for hosts without clients. Never called: the router finds no client first.

Every UI token.

Caps applied before content crosses IPC or reaches a renderer.

Built-in pull_request kind. Detects GitHub PRs and GitLab MRs from gh pr create, glab mr create and *create_pull_request / *create_merge_request tools. Refreshes GitHub PR state.

Inline reference chips (ticket ids, URLs).

Helpers to declare registry tokens.

A renderer for blocks, code languages, tools or artifacts.

Helpers to declare RPC contracts.

A full-screen view or modal.

Every trigger, in a fixed order: what a facet without on runs on.

A Settings page.

Extra data on the sidebar rows of matching sessions.

A filter the user turns on in the sidebar.

A grouping the user can pick in the sidebar.

A row an extension adds to a space, beside its sessions.

A sort order the user can pick in the sidebar.

A small item in a named slot.

A space: a named, query-defined view of sessions in the sidebar.

A color theme.

Bare specifiers kept external in a bundled ui entry: the renderer's shared modules. zidane and zidane/extensions are usually imported for types only (erased); a value import of them stays external and the renderer must map it.

The token names, in a fixed order.

A webview panel or screen.

A button that runs code. status draws a live state next to it.

What an action's run receives.

What an action may return.

A live state drawn next to an action.

What an action's status receives: the extension's own settings, read-only.

Editor of agent profiles and sub-agents.

ctx.agents.

What ctx.app tells about the running app.

Options of applyExtensionsConfigReport.

Options for createArtifactDetectHook.

Passed to a kind's resolve.

ctx.artifacts.

What running an action asks the host to do. Every field is optional; several may combine.

Which badges a registration acts on. Omitted axes match everything; given axes must all match.

One menu item. group places it: copy, prompt, open, then the extension's own.

Badge actions on the wire: which badges they apply to. The menu itself is asked for per target.

A host's resolved menu item: a built-in, or an extension's (source names the registration).

What a badge stands for. Every badge surface builds one so the same menu logic applies everywhere.

An on/off setting.

Options for buildExtensionRegistry.

How buildExtensionRegistry builds the runtime.

Shared members of every catalog domain.

A generic editor over a catalog keyed by id.

A command as CommandsDomain.list reports it.

ctx.commands.

A command.

Runs completion work for a composer: each bounded in time, a newer suggest for the same key aborting the older one.

A reference to a component the extension exports from its ui entry (desktop and web) or its tui entry (terminal). A host without the named component draws the item's data, or its fallback.

A component reference on the wire: the export name and JSON props.

ctx.composer.

One entry's outcome, as hosts log and show it.

What config entries change in a registry build: linked folders and disabled ids.

A stored connection. An integration holds several, one per account; one is the default.

The shared registries and host ports every extension's context draws on. One set per runtime.

ctx.contracts.

Token of an API an extension provides.

ctx.desktop: present only in the desktop app's main process.

The desktop app's main-process handle behind ctx.desktop. Only the desktop host gives one; elsewhere ctx.desktop is undefined.

Options every dialog takes.

Options for discoverAndBuildExtensionRegistry.

Something that can be withdrawn. Calling dispose twice is a no-op.

A choice among fixed values.

What running an action did.

An action row, without its callbacks.

One artifact a detect hook emits; kind defaults to the registering kind.

Scope selector for ctx.artifacts.list.

Renderer-agnostic one-line presentation of an artifact. Core lists (sessions badge, artifacts rail, context panel, GUI panels) call the kind's render per row and fall back to label + uri when the kind is unregistered or render throws.

One fact chip of an artifact row: text, an optional link, and its own look.

What ctx.artifacts resolves queries against: the host's artifacts (its session store, or a client's view of a host's) plus the active session's identity, so scope: 'session' / 'project' can be answered without the extension knowing either id.

Right-click actions an extension adds to matching badges. Registered with ctx.registerBadgeActions.

An icon in both renderers' vocabularies: gui is an icon class (i-ph-git-commit), tui one or two terminal cells (⎇). Either may be omitted; the host then draws none.

Shape returned by partitionExtensionCatalog.

The catalogs extensions register into and transform.

One item of a provider's popup.

A provider as an app's composer lists it: its trigger opens its popup.

What a config ACTION reports back to the host after running. Actions cannot write settings directly — there is deliberately no config.set surface for extensions — so a successful run RETURNS the values it wants persisted and the host writes them through its own validated settings path (sanitizeExtensionConfigActionPatch gates the patch).

Result of an action's passive status probe. state drives the row color (ok accent / off mute / error error); message is the one-line text rendered in the row's value slot.

A boolean config item — rendered as a toggle.

A config category — a labelled grouping the Settings UIs render as a sub-header. Declared via ctx.registerConfigCategory. An item that names no category lands in its extension's implicit category (id = extension name); register a category with that id to give the implicit grouping a friendlier label.

An enum config item — rendered as a cycling choice row. The default must be one of the options values or the item is rejected at registration.

Fields shared by every config-item variant.

A numeric config item — rendered as a free input row, clamped to [min, max] and snapped to step. The default must itself lie within [min, max] or the item is rejected at registration.

A string config item — rendered as a free input row (optionally multiline), validated against pattern.

What is specific to one extension.

Section an extension adds to the context panel. Supply static or computed rows, a load function, or both.

One extension's contributions, in the shapes hosts read.

What ctx.sessions.create() takes.

An extension. Export it as the module's default export, either through defineExtension or as a plain object (no import needed).

What ctx.sessions.events() searches for. Every field narrows.

Handlers an extension put on its own agent-hook bus and host events (when the host gave no agent hooks).

Connects a host to the runtime surfaces extensions see as ctx.runtime, ctx.sessions, ctx.workspace and ctx.artifacts.

What a host attaches to power the runtime surfaces.

An extension as ctx.extensions reports it.

One installable extension found inside a fetched tree.

Where an installed extension came from, from its .install.json: what Settings shows ("Update from <label>").

What .install.json records — enough to replay the install for updates.

Outcome of an install or update.

Argument the TUI dispatcher hands to ExtensionKeybinding.onTrigger. Intentionally tiny — the extension can capture whatever it needs from setup's closure. Extra fields may be added in minor releases; treat unknown ones as forward-compat noise.

Static metadata an extension declares in extension.json or the zidane key of package.json. Discovery reads it before the module runs, so a bad apiVersion or name fails the load early.

The host side of ctx.mcp, shared by every extension of a registry build.

One server ctx.mcp.servers() reports.

What an MCP tool call answered. In-band tool errors resolve with isError: true.

One row of ctx.runtime.models() — a model offered by a provider the user has credentials for. provider.key is the registry key (stable id, e.g. anthropic); provider.name is the display name. model mirrors the host's ModelInfo (id, context window, cost, …).

A contribution tagged with the extension that made it, kept in registration order.

Registry entry: a host-facing PaletteProvider plus its owner and default group.

A side-panel tab an extension registers with ctx.registerPanel.

Registry entry: the definition plus its owning extension.

Filesystem locations given to an extension.

One prompt waiting for an answer, from ctx.sessions.pending().

Connects ctx.submitPrompt to the host's prompt pipeline. Hosts attach their handler after the UI mounts.

A reference's hover card: what the host shows over the badge. JSON-safe, bounded.

One fact of a reference card.

A pattern a reference provider finds in text. Declarative so every host matches the same way, in any process (the GUI renderer has no extension runtime): regex is JavaScript RegExp source, run with the g flag plus flags (i, u, m, s; others are ignored). key builds the key handed to resolve from the match: $0 is the whole match, $1… its groups (default $0). A match whose key comes out empty is skipped.

How a resolved reference paints: a badge in place of the matched text.

What run-settled handlers receive (the run:settled host event, in the shape hosts deliver it).

What createExtensionRuntime returns.

Identity of the extension a transform runs on behalf of. Passed as the second argument to registered transforms.

Options of createExtensionRuntime.

The extension runtime's outputs.

ctx.runtime — reads/controls over the host's active model state.

A discovered (but not yet loaded) extension entry.

The process's declarative-install coordinator.

Options of createExtensionsConfigSync.

The result of one scope's reconcile, handed to every attached target.

A registry a host keeps in line with the config.

What a session shows under its title for one artifact kind: GUI sidebar rows and the TUI sessions list paint the same data. Built by the kind's badge(artifacts) over that session's artifacts of the kind (newest first). JSON-safe: it crosses IPC as-is.

One line of a session badge's card.

Host-level session control behind ctx.sessions: the orchestration verbs and per-session extension state, addressing any session by id, inside a run or not.

What ctx.sessions.read() returns.

A session event (a run ended, or a session waits for an answer), as ctx.sessions.onEvent handlers get it.

One row of the orchestration list(limit) (ExtensionSessionVerbs.list), which ctx.sessions.list falls back to on a host without the query verb.

Which sessions a subscriber hears from. Every field narrows; {} is every session.

ctx.sessions — the orchestration verbs, acting as this extension (docs/ORCHESTRATION.md), plus this extension's state of any session. Every verb rejects without a chat host (a TUI-only window), and when the call is refused (an unknown session).

The orchestration verbs acting as one extension (docs/ORCHESTRATION.md).

The effects declarative install needs from the host.

Rule that activates a skill automatically at the start of a run.

Declares a tool-result metadata namespace owned by an extension and how it appears in the context panel.

ctx.ui — what this window shows. Per window: a daemon or a server has none, and answers false.

What ctx.sessions.wait() returns.

The live (execution, handle) pair behind ctx.workspace. Resolved per call — never cached by the facade — because the pair changes on session switch, cwd change, and registry rebuilds; a captured pair would point at a destroyed container.

Options of FacetRegistry.compute.

A registered facet, as hosts list it.

A ctx.sessions.facets.refresh call, as hosts get it.

The facets every extension registered. Hung on ExtensionRuntimeOutputs.facets.

One generated image.

ctx.generate: model calls outside any session. Uses the user's provider resolution and counts usage. On a host without model access, text and object reject, decide.available is false and decide answers unavailable.

What ctx.generate.image takes.

A pull request as read from GitHub.

A live UI contribution. update patches the item and pushes it to every host. dispose withdraws it.

ctx.hooks.

Host events the runtime cannot see by itself; hosts emit them.

An HTTP request a provider is about to send.

An HTTP response a provider received.

Identifies an installed extension and where to look for extension folders. Used by updateInstalledExtension and removeInstalledExtension.

Options for installExtensionFromSpec.

ctx.instructions: text added to the system prompt.

System prompt text added by extensions (ctx.instructions).

A connect method the extension runs itself (a bespoke OAuth flow, one sending custom headers). connect drives the host's UI through IntegrationFlowIO. An OAuth credential may carry refreshToken: the store keeps it, resolve never hands it out, and refresh gets it back when the credential expires within the refresh skew. integrationMethodFromOAuthProvider adapts a zidane/oauth provider.

What a custom method's connect returns.

What a custom method's connect drives the host's sign-in UI with. The host shows each step the way it shows an OAuth flow's (a link, a code, a question), in the TUI, the desktop app or a browser on another machine.

A registration. update changes the spec in place; Settings redraws.

ctx.integrations.

An integration an extension offers. Settings draws Connect / Disconnect for it.

Options of hooks.intercept.

Every interceptor: [input, result]. The handler returns a new result or undefined.

ctx.keymap.

One command as ctx.keymap.list reports it.

Durable key/value data. Reads are synchronous, from a cache: the host loads user and project before setup and the run's session before each run. The first kv() call for any other scope or session starts loading it, and reads return undefined until the load ends; await ready() before reading when that matters (a session's data after a restart).

One extension folder a config entry links in place (a local source in config.json), scanned ahead of every root. Its scope gates it like a scan root's: a project link loads only in a trusted project.

Opens links the extension understands, before the app's own behavior. Every link the apps open goes through it: transcript links, file and reference chips, panel rows, badge menus, terminal links. Holding Alt opens a link the default way.

A link handler on the wire: which handlers exist and their order. match and open stay in the backend; hosts open a link through the resolver (UiRegistry.openLink, extensions.links.open).

A link to open, as hosts pass it to UiCallbacks.openLink.

A Live value you can read and watch.

Result of attempting to load one extension. Active and disabled entries carry their live contributions; failed ones carry error.

ctx.mcp.

A connected MCP server, as ctx.mcp.list reports it.

An in-memory SettingsPort whose layers can be set from outside.

An in-memory StoragePort with a way to simulate another client's write.

A native menu entry (desktop). It runs a command.

A native menu entry on the wire.

Editor of the model catalog (active providers only).

A model entry.

ctx.models.

A model picker. multi stores a list.

A tool with its name.

How a folder the runtime does not hold may load.

A number setting.

Options of hooks.on.

A group of registrations with one lifetime. The extension's root owner lives until the extension unloads. scope() makes a child that can end earlier (for example "while connected").

A dynamic palette source: items computed on open, drill-down results.

A button an extension adds to a panel footer. Clicking it calls the extension's onAction with id.

A stacked bar chart with its legend (daily tokens by model).

One bar of a bars item.

One series of a bars item: a legend row.

JSON-safe content a panel's load returns. The host paints it with its own components.

One choice of a segmented control.

Host-specific rich view. The TUI resolves renderer against ctx.tui.registerRenderer ids (<extension>/<id>, bare ids are prefixed at registration); the GUI, and any host without the renderer, paints fallback as markdown.

Identifies the badge or card row that opened a panel.

One day of a heatmap. Sparse: days left out are empty.

A week × weekday activity grid ending at end.

How a block sits on the project home before the user arranges it.

Where panels run: the scope's reads, and the bridge extension code reads its host from (absent: detached).

A panel action's or a palette run's failure: the extension's own words.

Per-surface icon: an iconify class for the GUI, a single glyph for the TUI. The GUI ships Phosphor only (i-ph-<name>, -fill for a filled weight); other collections are not registered and paint nothing.

A list of label and value pairs in a panel.

One label and value pair in a key/value item.

The context hosts hand to load / onAction.

A load context as it arrives from across a boundary (the GUI renderer) or from host UI state, before the host binds it: every field optional. normalizePanelLoadContext reduces untrusted input to this shape; resolvePanelLoadContext turns it into the PanelLoadContext load / onAction receive.

A block of Markdown text in a panel.

More items to load after this content: the host shows a Show more button and calls load again with cursor, then appends what comes back (rows to the sections of the same id, new sections after). A new view, search or a change emit loads the first page again.

A button on a panel row. With start, the app opens a new chat for it (never sent); without, it calls the panel's onAction(id, payload).

One line in a panel, same presentation as an artifact row.

What a panel's scope reads from its host.

A search field in the panel's header: the host keeps its text and reloads with it (PanelLoadContext.search).

A titled group of items in a panel.

One big-number tile of a stats item.

A grid of big-number tiles (totals, streaks).

One panel a folder offers, as an app lists it.

A panel on the wire. Its load / onAction / subscribe stay backend-side.

ctx.plugins: Agent Plugins (skills + MCP bundles).

A prompt on its way in, before commands and skills.

Editor of provider descriptors (including inactive ones).

ctx.providers.

A value that changes over time. Stores and selectors implement it.

A UiClientPort that records calls and reports success.

One reference found in a text: [start, end) and the key to resolve.

What a host needs to match a provider's references: JSON-safe.

Resolves reference keys to views, caching the answers.

Options for createReferenceResolver.

Token of a list an extension owns.

How a view narrows its source.

What a registry view reads from: the runtime, the entries it refused, and the change feed.

Options of reloadChangedExtensions.

What reloadChangedExtensions did, by extension id.

A renderer: a component per host, with a markdown fallback.

A renderer on the wire.

What an implementation receives besides its input.

An RPC contract made by Rpc.define. Holds no implementation, so others can import it.

ctx.rpc.

A declared error, returned or thrown by an implementation.

An event delivered to subscribers.

Event side of a client.

One event of an RPC contract. Event data must be an object.

One method of an RPC contract.

A registered implementation.

What run:settled observers receive.

Base data of the shared catalogs. Each falls back to an empty base.

One extension to load.

The loaded state of one extension, for hosts and the registry view.

The agent-hook side of the hooks port.

A discovered or inline extension, carried in the LoadedExtension list until the runtime takes it.

Everything a host plugs into the runtime. Every member is optional.

What an onFire handler gets.

ctx.schedules. Every call rejects while the person has Reminders off (Settings > Sessions > Reminders) and on a host without a chat host. What this extension creates is tagged createdBy: { kind: 'extension', id }.

A full-screen view, or a modal when presentation is 'modal'.

A screen on the wire.

A DialogPort with one client that answers from a script.

One option of select.

A session badge with the kind it was built for and the artifacts behind it.

A session event the host reports: a run ended, or a session waits for the user.

ctx.sessions.facets. Works on every host; a host without sessions never computes them.

A facet: a JSON value the extension computes for every session, which queries read as facet.<extensionId>.<key> (filters, sorts, groupings, templates). The host stores the last value per session and computes it again on each trigger in on. undefined or null clears it; a throw or a timeout (5 s) keeps the last value and counts against the extension's error budget. A value is at most 8 KiB of JSON, and one extension's values on one session 16 KiB together: a value past either keeps the last one, with a warning on the extension's logger.

The fields of a session a query reads, as ctx.sessions.list rows and facet snapshots carry them.

A session's live settings.

One page of ctx.sessions.list.

What ctx.sessions.list takes. Every field is optional.

One row of ctx.sessions.list.

ctx.sessions. Acts as the extension; what it creates is tagged with the extension id. Rejects on hosts without a session runtime, except facets.

What a facet is computed on: the session's fields, its metadata and its turn count. Frozen.

Fields every setting has.

An extension's own group in the settings sidebar.

ctx.settings.

A page in Settings under the extension. Data from a settings-like schema, or a component.

One page of an extension's settings.

A settings page on the wire.

The settings of an extension.

One searchable settings row.

What settingsSidebar returns.

A top-level group an extension declared (SettingsSchema.category).

One extension's entry in the "Extensions" group.

One extension as settingsSidebar and settingsSearchIndex take it.

Subscriptions shared by the clients that asked for them (an extension panel's or palette's live updates): started on the first request for a key, stopped when the last owner releases it or goes away. Without the count, one window closing a panel would stop the updates of another window showing the same one, and a window that closed without releasing would keep its subscription until the registry was rebuilt.

A small label on an extension row.

Extra data on the sidebar rows of the sessions that match where: an icon, a tone, a subtitle, chips, or a component. Only { template } values are read as templates; a plain string is drawn as given. Bindable fields follow the sidebar rule (SpaceItem).

A sidebar decoration on the wire.

A filter the user turns on in the sidebar. toggle keeps the sessions that match query while on; select keeps those of the one option picked; multi keeps those that match any picked option. Bindable fields follow the sidebar rule (SpaceItem).

One choice of a select or multi sidebar filter. Bind the filter's options to change its labels or queries.

A sidebar filter on the wire.

A grouping the user can pick for the sidebar. Bindable fields follow the sidebar rule (SpaceItem).

A sidebar grouping on the wire.

An action in an extension row's menu.

A sidebar row's action on the wire.

A row an extension adds to a space's list beside its sessions: a ticket, a job, a pull request. It lists only in a space that allows items. time sorts it as a session's updatedAt. Bindable fields follow the sidebar rule (SpaceItem).

A sidebar row on the wire, its bindings read and its references resolved: hosts use them as is.

A sort order the user can pick for the sidebar. Bindable fields follow the sidebar rule (SpaceItem).

A sidebar sort on the wire.

ctx.skills.

A small item placed in a slot: a status line, a banner, a composer badge.

A slot item on the wire, its bindings read.

What a session started from a space runs with. Each field left out takes the app's default.

A space on the wire.

ctx.storage.

A typed, reactive value, kept on disk and synced to every window and client.

Options of a typed store.

A text setting. secret values go to the auth store and never show in config files.

A tool call an interceptor can rule on (from tool:gate, which also fires for MCP tools under their mcp_<server>_<tool> name).

A finished tool call (from tool:transform, which also fires for MCP tools).

Editor of the tool catalog, per run.

A tool-result metadata namespace an extension owns.

What a tool.result interceptor returns.

ctx.tools.

TUI-side merged contributions.

One call a RecordingUiClientPort received.

ctx.ui. Dialogs (confirm, prompt, select, form, askUser, presentPlan) reject with NoUiError at once when no client can show them. toast and notify wait for a client instead: up to 20 of them, each for 60 s, delivered in order to the first client that attaches.

One contribution as the hosts see it.

A token naming a kind of UI contribution.

A web page shown in a panel or a screen, sandboxed. It talks to the extension through RPC only.

A webview on the wire. A file source is relative to the extension's folder; the host resolves it.

The full extension-config schema in IPC-safe form.

Everything a Settings UI needs to draw an extension's settings.

An extension as the settings wire names it (WireSettings.extensions).

One page of an extension's settings in the sidebar. kind: 'schema' pages come from the definition's schema and list keys of the wire's own rows; kind: 'ui' pages are SettingsPage items, drawn from their own schema wire or component.

The least client token scope a remote caller needs: the same scopes as every protocol method (chat ⊂ admin). In-process callers, local connections and other extensions are never limited by it.

A value an action reads or writes: what a value setting holds.

The add signature: a token and its item.

What kind of thing a badge stands for.

A field of a UI item that may be a fixed value or a Readable. A bound field re-pushes the item to the hosts when the readable changes.

A cleanup function returned from setup or passed to ctx.onCleanup.

What run receives. A slash invocation carries the full step context (runAgent, emit, interaction…); other sources leave the session-bound members out when no session is active.

How a command was started.

A level and a line, for the host's log.

What happened to one config entry (or lock entry) in a reconcile.

A section of the context breakdown or the context panel.

A context section on the wire.

A scripted answer for one dialog: a value, or a function of the request.

A dialog on the wire, by kind.

The extension API version this runtime loads.

A tool approval's decision.

An exact icon color, #rgb or #rrggbb, for a brand's own palette (a tracker's state colors). Hosts paint it over tone and ignore anything else; keep tone set too, for hosts and themes that don't take colors.

Color hint shared by session badges and text references. Hosts map it to their theme: muted is the quiet default, subtle quieter still, accent the theme accent, the rest the status colors.

Rewrites the agent behavior settings before a run starts. Return a replacement, or nothing to keep it.

How a host applies a changed config value: read live, rebuild the agent, or restart.

Discriminated union of the typed config items an extension can declare. The type tag drives both validation (resolveExtensionConfigValue) and rendering (toggle / choice / input / action row).

Where a config value should be persisted.

Concrete value a config item can hold.

The value-holding config items — everything except action. Functions that produce or validate persisted VALUES take this narrower union; ExtensionConfigItem is the full declarable set.

Result of fetchExtensionSource: the provenance string and, for git clones, the commit SHA.

The host process the extension runs in.

Reason an install, update or removal failed. Matches ExtensionInstallError.code.

Injectable side-effect seams — tests swap these to stay offline; hosts normally omit the whole object. Shared shape with the skills installer.

Where an extension is installed: the project or the user directory.

The shared install-source shape — see src/install/source.ts for the grammar.

Rewrites the MCP server configs before they are connected. Return a replacement list, or nothing to keep it.

An orchestration tool a session can hold: sessions drives sessions, interactions answers their prompts.

Item shape a dynamic provider returns: source is stamped by the host, group defaults to the provider's.

PaletteRunResult as an extension produces it: nested items are ExtensionPaletteItems.

Where a panel shows (ExtensionPanel.scope): 'session' (the default) only beside a session; 'project' only where a folder is open without a session (the new-chat draft screen, project pages); 'both' anywhere.

Where hosts look for references.

A run-settled handler; may be async.

Rewrites the options of a run before it starts. Return replacement options, or nothing to keep them.

Handler registered with ctx.sessions.onEvent.

Where an extension was found.

Rewrites the tool catalog before a run. env.phase tells whether it is the pre-run pass or the run itself, and env.mcpToolNames lists the tools that came from MCP servers. Return a replacement catalog, or nothing to keep it.

ctx.workspace's operations already bound to a session, for a host whose execution lives in another process (the TUI in daemon mode reaches the session's workspace over IPC). Same contract as the facade's methods.

The registry together with its per-extension domain factory, its close (the runtime's dispose calls it first), and forget (the runtime's unload with forget calls it, after the extension's facets went).

What a PR shows: merged / draft / closed, or for an open one its review decision (approved / changes_requested) else open.

Every event hooks.on accepts: each AgentHooks key plus host events.

A host module, eager or lazy. Lazy (() => Promise<module>) exists for self-referencing hosts: zidane/tui maps to ITSELF, which can only be expressed as a deferred dynamic import (the module is still evaluating when it registers).

One of HOST_MODULE_SPECIFIERS.

The value type a Schema accepts: inferred for Standard Schema, unknown for JSON Schema.

The instructions registry together with its per-extension domain factory (createInstructionsRegistry).

One way to connect an integration. For oauth: pkce needs redirectUri (a loopback URL with an explicit port, e.g. http://localhost:51121/callback), device needs deviceUrl (the device authorization endpoint). clientSecret is sent to the token endpoint when set; params are extra authorize-URL parameters (access_type, prompt). custom: see IntegrationCustomMethod.

What IntegrationHandle.update may change.

Handler of interceptor K.

Who put an item in a catalog.

A JSON value.

A plain JSON Schema object. Values validated by it are typed unknown.

Focus areas a keybinding can be limited to. panel:<id> and screen:<id> name an extension's own.

Where a link was clicked.

The state of something another extension provides (a contract, a registry owner, an RPC). Read it where you use it: it changes as the provider starts, stops and reloads.

One upstream tool an MCP server lists, before it is namespaced.

One entry in a panel section: a row, Markdown, key/value pairs, stats, a heatmap, a bar chart, or a custom view.

A side or home panel: an ExtensionPanel (load, subscribe, onAction, controls, focus), plus an optional component.

What a delivered load context is bound to: a session, or just a folder.

Where a panel shows (ExtensionPanel.surfaces): 'side', a tab in the side panel (TUI rail, GUI side panel); 'home', a block on the GUI's project home (the new-chat screen of a folder, and of no folder).

A panel's view state, by control id: the picked option, or the picked options of a multi control.

What a renderer draws: a custom block id, a code-block language, a tool's result, or an artifact kind's detail.

A typed client. Methods reject with RpcCallError on a declared error, validation failure, missing provider or abort.

The implementation of a contract.

Either a Standard Schema (zod, valibot, arktype) or a plain JSON Schema.

When a host computes a facet again: a session was created, a run settled, or its metadata changed.

A session's run state, the same in ctx.sessions.get and list rows: idle (never ran, or between runs), running, blocked (a run waits on the user: a question or an approval), completed (the last run ended well) or error (the last run failed).

One setting.

What a change of the setting needs before it applies.

Where a setting's value is stored.

The value type of one setting.

A chip a decoration adds to a session row: literal text (blank or whitespace-only: no chip), a template (field paths in braces, {{ and }} for a brace; see escapeTemplate), or one chip per value of a facet.

What opening an extension row does. command resolves and gets its argument as a SidebarRowAction's does. panel and screen name this extension's own panel or screen by that id when it has one, else the id as written (<extension>/<id>, or a built-in panel such as todos).

Run state an extension row shows, like a session's.

A plain string drawn as given (blank or whitespace-only: no text), or { template } with field paths in braces: '{facet.git.branch} · {modelId}'.

Folders for storage.path.

Where kv and stores keep their data.

A config item as STORED on the registry / contributions — the authored item plus the resolved category id it belongs to. The owning extension is implied by the namespacing key on ExtensionRegistry.configItems.

Interceptors that run on a synchronous hot path: their handlers must not return a promise.

tool.call verdict. 'ask' sends the call through the approval flow. patch replaces the input, re-validated before execution. result answers the call without running it. block and result end the chain.

A registered transform.

Keys of the settings that hold a value (not actions).

A config item flattened for the wire — carries category + extension, drops validate.

ctx.workspace: exec and files in the session's execution context (sandbox-correct).