# zidane/chat/pure

> The Node-free subset of zidane/chat, safe to import from a browser renderer.

Import: `import { … } from 'zidane/chat/pure'`. Source: [src/chat/pure.ts](https://github.com/Tahul/zidane/blob/main/src/chat/pure.ts).

Use this entry point in a browser renderer (an Electron window, a Vite web build) that needs the chat engine's pure logic. It re-exports only modules with no `node:*` imports, React hooks or OpenTUI components: formatters, todo edits, diff builders, color helpers, transcript reducers, the picker cache hints (`cacheHintText`), the settings catalog and their types. Disk access and agent runs stay in the Node build of `zidane/chat`. Its browser build adds the React contexts and hooks to this logic.

It also holds the model of the setup wizard. The terminal app, the desktop app and [`zidane-ui/onboarding`](https://zidane.si/docs/reference/ui-onboarding.md) all run on it. `planOnboarding` returns the steps of a run, and `createOnboardingFlow` and `onboardingReducer` move through them. `TRANSCRIPT_PRESETS`, `CONNECTORS` and `NATIVE_EXTENSIONS` are its catalogs. `onboardingSettingsChange` returns the settings that a run writes, and `needsOnboarding` decides when the wizard opens. `createOnboardingRun` runs a whole wizard without a UI: the reducer, plus the imports and installs that its steps start.

```ts
import { addTodo, ageString, formatCostLabel, planOnboarding, transcriptPresetOf } from 'zidane/chat/pure'

const todos = addTodo(addTodo([], 'Write tests'), 'Update docs')
console.log(todos.map(todo => todo.content))
console.log(ageString(Date.now() - 5 * 60_000), formatCostLabel(0.0421))

// The setup wizard: the steps of a Quick start, and the preset that some settings match.
console.log(planOnboarding({ mode: 'quick', surface: 'desktop', importAvailable: false, installsAvailable: true }))
console.log(transcriptPresetOf({ showThinking: false }))
```

## Functions

### `accentColor`

Function.

Resolve a profile's `accent` token to a concrete hex color via the
caller's color palette. Renderer-agnostic — accepts the four-role
subset of `ThemeColors` that's relevant to accent surfaces, so this
helper composes against either `useColors()` (TUI) or a CSS-variable
lookup (GUI). Omitted / unknown tokens fall back to `accent`.

```ts
function accentColor(
  accent: (string & {}) | AgentAccent | undefined,
  COLOR: { accent: string; brand: string; model: string; warn: string },
): string
```

**Parameters**

- `accent` (`(string & {}) | AgentAccent | undefined`): Accent token from an agent profile. Unknown or missing tokens use `accent`.
- `COLOR` (`{ accent: string; brand: string; model: string; warn: string }`): Palette that supplies the `brand`, `accent`, `warn` and `model` colors.

**Returns** `string`

Source: [src/chat/agent-accent.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/agent-accent.ts#L23)

### `actionIssues`

Function.

The problems of an action.

```ts
function actionIssues(action: unknown): ScheduleIssue[]
```

**Parameters**

- `action` (`unknown`): What the caller sent.

**Returns** `ScheduleIssue[]`

Source: [src/schedules/validate.ts:91](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L91)

### `activePlanSummary`

Function.

The plan worth a glance: the session scope's applying plan, else its most
recent stopped one. `null` when neither exists.

```ts
function activePlanSummary(bag: PlansBag): ActivePlanSummary | null
```

**Parameters**

- `bag` (`PlansBag`): The bag.

**Returns** `ActivePlanSummary | null`

Source: [src/chat/plans.ts:1145](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L1145)

### `activeSnapshotFor`

Function.

The snapshot the footer indicator shows for a provider: the one probed with
the credential requests use — the session's pinned `account` when it has
one, else the provider's active credential — else the first reported.
`null` when none.

```ts
function activeSnapshotFor(
  all: readonly ProviderUsageSnapshot[],
  providerKey: string,
  account?: string | null,
): ProviderUsageSnapshot | null
```

**Parameters**

- `all` (`readonly ProviderUsageSnapshot[]`): Snapshots for every provider and account.
- `providerKey` (`string`): Provider to pick a snapshot for.
- `account?` (`string | null`): Optional account id. Falls back to the active credential, then the first snapshot.

**Returns** `ProviderUsageSnapshot | null`

Source: [src/chat/provider-usage-format.ts:143](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L143)

### `activeSpaceOf`

Function.

The space to show: the remembered one when it still exists, else the first
space in the list (Default unless the user moved it).

```ts
function activeSpaceOf(
  spaces: readonly Space[],
  remembered: string | null | undefined,
): Space
```

**Parameters**

- `spaces` (`readonly Space[]`): The space list.
- `remembered` (`string | null | undefined`): Id of the space shown last.

**Returns** `Space`

Source: [src/chat/spaces.ts:293](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L293)

### `ageStep`

Function.

The relative-age ladder every "how long ago" label climbs: under a minute,
then whole minutes, hours and days, then (from `dateAfterDays`) a date.
Only a `duration` reads with "ago" in a sentence: "Updated 5m ago", but
"Updated now" and "Updated Mar 4".

```ts
function ageStep(at: number, now: number, dateAfterDays?: number): AgeStep
```

**Parameters**

- `at` (`number`): Epoch milliseconds of the event.
- `now` (`number`): Epoch milliseconds of the current time.
- `dateAfterDays?` (`number`, default `Infinity`): Days from which the age is a date. Default: never.

**Returns** `AgeStep`

Source: [src/chat/format.ts:166](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L166)

### `ageString`

Function.

Compact relative-time formatter — "just now / 5m ago / 3h ago / 2d ago".

```ts
function ageString(ts: number, now?: number): string
```

**Parameters**

- `ts` (`number`): Timestamp in epoch milliseconds.
- `now?` (`number`): Current time in epoch milliseconds.

**Returns** `string`

Source: [src/chat/format.ts:185](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L185)

### `ansiLineText`

Function.

The visible text of a line.

```ts
function ansiLineText(spans: readonly AnsiSpan[]): string
```

**Parameters**

- `spans` (`readonly AnsiSpan[]`): The line's spans.

**Returns** `string`

Source: [src/chat/ansi.ts:295](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L295)

### `appendMarkdownDelta`

Function.

Coalesce a markdown delta into `owner`'s open streaming block, or open one.

```ts
function appendMarkdownDelta<E extends StreamEvent = StreamEvent>(
  prev: NoInfer<E>[],
  delta: string,
  owner: string,
  depth: number | undefined,
  turnId: string | undefined,
  options?: MarkdownDeltaOptions,
): E[]
```

**Type parameters**

- `E` (`extends StreamEvent`, default `StreamEvent`)

**Parameters**

- `prev` (`NoInfer<E>[]`): Current transcript events.
- `delta` (`string`): Streamed markdown text.
- `owner` (`string`): `parent` or the subagent's spawn id.
- `depth` (`number | undefined`): Nesting depth, or `undefined` when the source named none.
- `turnId` (`string | undefined`): Turn the delta belongs to.
- `options?` (`MarkdownDeltaOptions`, default `{}`): Split threshold for a growing block.

**Returns** `E[]`

Source: [src/chat/streaming-pure.ts:162](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L162)

### `appendThinkingLines`

Function.

Coalesce a thinking delta into `owner`'s open lane, one row per line.

```ts
function appendThinkingLines<E extends StreamEvent = StreamEvent>(
  prev: NoInfer<E>[],
  delta: string,
  owner: string,
  depth: number | undefined,
  turnId: string | undefined,
  options?: ThinkingDeltaOptions<E>,
): E[]
```

**Type parameters**

- `E` (`extends StreamEvent`, default `StreamEvent`)

**Parameters**

- `prev` (`NoInfer<E>[]`): Current transcript events.
- `delta` (`string`): Streamed thinking text. Each line becomes one row.
- `owner` (`string`): `parent` or the subagent's spawn id.
- `depth` (`number | undefined`): Nesting depth, or `undefined` when the source named none.
- `turnId` (`string | undefined`): Turn the delta belongs to.
- `options?` (`ThinkingDeltaOptions<E>`, default `{}`): Hook for decorating the first row of a new lane.

**Returns** `E[]`

Source: [src/chat/streaming-pure.ts:226](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L226)

### `applyEditPayload`

Function.

Apply the payload's hunks against `priorContent` and return the
resulting file body, with exact string matching only:

- `replaceAll === true`  → `String.replaceAll`
- otherwise              → first-occurrence `String.replace`

Hunks are applied in order — a `multi_edit` later hunk operates on
the output of the earlier ones, just like the actual tool. The tool's
lenient matching (curly quotes, line-number prefixes) is not applied here;
see [`previewEditPayload`](https://zidane.si/docs/reference/chat-pure.md#previewEditPayload).

```ts
function applyEditPayload(payload: EditPayload, priorContent: string): string
```

**Parameters**

- `payload` (`EditPayload`): The edit payload whose hunks are applied.
- `priorContent` (`string`): File content the hunks apply to.

**Returns** `string`

Source: [src/chat/edit-diff.ts:417](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L417)

### `applyingPlan`

Function.

The scope's applying plan, if any.

```ts
function applyingPlan(bag: PlansBag, scope?: string): Plan | undefined
```

**Parameters**

- `bag` (`PlansBag`): The bag.
- `scope?` (`string`, default `SESSION_SCOPE`): [`SESSION_SCOPE`](https://zidane.si/docs/reference/chat-pure.md#SESSION_SCOPE) or a sub-agent run id.

**Returns** `Plan | undefined`

Source: [src/chat/plans.ts:1086](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L1086)

### `applyInsert`

Function.

Replace `[span.start, span.end)` in `text` with `insertText`. Returns the
mutated text and the new cursor position (end of insertion).

```ts
function applyInsert(
  text: string,
  span: { end: number; start: number },
  insertText: string,
): { cursor: number; text: string }
```

**Parameters**

- `text` (`string`): The source text.
- `span` (`{ end: number; start: number }`): Half-open `[start, end)` range to replace.
- `insertText` (`string`): Text inserted in place of the span.

**Returns** `{ cursor: number; text: string }`

Source: [src/chat/completion-core.ts:325](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L325)

### `applyPlanEvent`

Function.

Applies one event to a bag. Pure: the input bag is never mutated. An event
whose id was already applied changes nothing; a refused event returns
`error` and the input bag.

```ts
function applyPlanEvent(bag: PlansBag, event: PlanEvent): ApplyPlanResult
```

**Parameters**

- `bag` (`PlansBag`): The current bag.
- `event` (`PlanEvent`): The change.

**Returns** `ApplyPlanResult`

Source: [src/chat/plans.ts:473](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L473)

### `applySettingsPatch`

Function.

Settings with a change applied. A setting that turns on also turns on the
one that it needs, so Session titles turns on Decisions, and a feature
turns on what it includes, so Browser tab turns on Agent can use the
browser. A setting that turns off also turns off the ones that need it.

```ts
function applySettingsPatch(
  settings: Partial<Settings>,
  patch: Partial<Settings>,
): Partial<Settings>
```

**Parameters**

- `settings` (`Partial<Settings>`): The settings before the change.
- `patch` (`Partial<Settings>`): The settings to change.

**Returns** `Partial<Settings>`

Source: [src/chat/onboarding/flow.ts:150](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L150)

### `authFailureHeadline`

Function.

The card's one-line headline, in plain English (the TUI's words; the GUI
words it through labels with the same shape).

```ts
function authFailureHeadline(auth: AuthFailure, label?: string): string
```

**Parameters**

- `auth` (`AuthFailure`): The failed sign-in.
- `label?` (`string`, default `auth.provider`): The provider as the user knows it (`Anthropic`); defaults to `auth.provider`.

**Returns** `string`

Source: [src/chat/auth-failure.ts:62](https://github.com/Tahul/zidane/blob/main/src/chat/auth-failure.ts#L62)

### `authOffersSignInFallback`

Function.

Whether the card also offers signing in again next to its retry: a retry
that keeps failing on a stuck refresh is fixed by a fresh sign-in.

```ts
function authOffersSignInFallback(auth: AuthFailure): boolean
```

**Parameters**

- `auth` (`AuthFailure`): The failed sign-in.

**Returns** `boolean`

Source: [src/chat/auth-failure.ts:30](https://github.com/Tahul/zidane/blob/main/src/chat/auth-failure.ts#L30)

### `authPrimaryAction`

Function.

The card's main action. A refresh stuck in another process or one that
could not reach the provider is retried first; anything else (expired,
revoked, missing, rejected) needs a new sign-in.

```ts
function authPrimaryAction(auth: AuthFailure): AuthPrimaryAction
```

**Parameters**

- `auth` (`AuthFailure`): The failed sign-in.

**Returns** `AuthPrimaryAction`

Source: [src/chat/auth-failure.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/auth-failure.ts#L20)

### `authProviderKeys`

Function.

The provider key a failure is about, for matching it against the host's
provider list (a descriptor's `key`, or its credentials key).

```ts
function authProviderKeys(auth: AuthFailure): string[]
```

**Parameters**

- `auth` (`AuthFailure`): The failed sign-in.

**Returns** `string[]`

Source: [src/chat/auth-failure.ts:40](https://github.com/Tahul/zidane/blob/main/src/chat/auth-failure.ts#L40)

### `autoTextModelId`

Function.

The automatic text model among one provider's models; `undefined` when
nothing qualifies (the caller then uses the main model).

```ts
function autoTextModelId(
  models: readonly TextModelCandidate[],
  mainModelId: string,
): string | undefined
```

**Parameters**

- `models` (`readonly TextModelCandidate[]`): The provider's models, in catalog order.
- `mainModelId` (`string`): The session's main model id (its vendor narrows an aggregator's list).

**Returns** `string | undefined`

Source: [src/chat/text-model.ts:107](https://github.com/Tahul/zidane/blob/main/src/chat/text-model.ts#L107)

### `bindingAlternatives`

Function.

The chords one binding lists. A binding may name several, any of which
fires the action: `"ctrl+w | cmd+w"` (or, in `keybindings.json`, an array).
A `|` right after a `+` / `-` is the key itself (`ctrl+|`).

```ts
function bindingAlternatives(spec: string | null | undefined): string[]
```

**Parameters**

- `spec` (`string | null | undefined`): Binding spec, possibly listing several chords separated by `|`.

**Returns** `string[]`

Source: [src/chat/keybinding-spec.ts:90](https://github.com/Tahul/zidane/blob/main/src/chat/keybinding-spec.ts#L90)

### `blendHsl`

Function.

Blend two hex colors in HSL space with shortest-path hue interpolation.
`t` ∈ \[0, 1]; `t=0` returns `from`, `t=1` returns `to`.

```ts
function blendHsl(from: string, to: string, t: number): string
```

**Parameters**

- `from` (`string`): Start color as a hex string.
- `to` (`string`): End color as a hex string.
- `t` (`number`): Blend position from 0 to 1.

**Returns** `string`

Source: [src/chat/color-gradient.ts:88](https://github.com/Tahul/zidane/blob/main/src/chat/color-gradient.ts#L88)

### `blockRunCommand`

Function.

The command that runs a block in the session's folder, with no input, for Run here.

```ts
function blockRunCommand(plan: ShellBlockPlan): string
```

**Parameters**

- `plan` (`ShellBlockPlan`): What runs ([`shellBlockPlan`](https://zidane.si/docs/reference/chat-pure.md#shellBlockPlan)).

**Returns** `string`

Source: [src/chat/shell-blocks.ts:129](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L129)

### `blockRunKey`

Function.

The key of a block's run: its reply and its code. An edited or regenerated
reply is a new turn, so its blocks start without a run. Two identical
blocks in one reply share their run.

```ts
function blockRunKey(turnId: string, code: string): string
```

**Parameters**

- `turnId` (`string`): The reply the block is in.
- `code` (`string`): The block's text.

**Returns** `string`

Source: [src/chat/shell-blocks.ts:195](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L195)

### `blockTerminalInput`

Function.

What is typed in a terminal to run a block there, ending with its Enter. The
command keeps the terminal's input, so it can ask for some.

```ts
function blockTerminalInput(plan: ShellBlockPlan): string
```

**Parameters**

- `plan` (`ShellBlockPlan`): What runs ([`shellBlockPlan`](https://zidane.si/docs/reference/chat-pure.md#shellBlockPlan)).

**Returns** `string`

Source: [src/chat/shell-blocks.ts:141](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L141)

### `buildContextBreakdown`

Function.

Shape a [`ContextSnapshot`](https://zidane.si/docs/reference/chat-pure.md#ContextSnapshot) into a render-ready [`ContextBreakdown`](https://zidane.si/docs/reference/chat-pure.md#ContextBreakdown).

Live categories (system prompt, rules, tools, MCP tools/instructions, skills,
searchable-tools catalog, conversation) sum to `snapshot.used` — `conversation`
absorbs the remainder so the bar matches the provider-reported total
(the remainder is floored at 0).
Deferred + autocompact + free-space buckets follow.

When `snapshot.exact` carries provider counts, the matching categories use
them (system, tools) and drop their `estimated` flag; everything else stays
on the heuristic.

```ts
function buildContextBreakdown(snapshot: ContextSnapshot): ContextBreakdown
```

**Parameters**

- `snapshot` (`ContextSnapshot`): Raw inputs captured at prompt-assembly time.

**Returns** `ContextBreakdown`

Source: [src/chat/context-breakdown.ts:330](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L330)

### `buildContextSegments`

Function.

Shape assembled-prompt pieces into a flat, render-ready segment list.

Order is prompt order — base doctrine, then instruction files (broadest
scope first, as `discoverAgentsMd` returns them), then the appended
catalogs. Empty / whitespace-only pieces are dropped so the list never
shows a zero-byte row.

```ts
function buildContextSegments(input: ContextSegmentsInput): ContextSegment[]
```

**Parameters**

- `input` (`ContextSegmentsInput`): The assembled prompt pieces and instruction files.

**Returns** `ContextSegment[]`

Source: [src/chat/context-segments.ts:173](https://github.com/Tahul/zidane/blob/main/src/chat/context-segments.ts#L173)

### `buildContextualDiff`

Function.

Like `buildUnifiedDiff` but operating against the full file content
so the diff carries *real* file line numbers and configurable
surrounding context.

Strategy:

1. Apply the payload to `priorContent` → `newContent`.
2. Run `computeLineDiff` over the whole file.
3. Group non-context ops into hunks, padding each with up to
   `contextLines` of context above and below. Adjacent hunks
   whose context regions touch are merged so we don't emit two
   `@@` headers separated by zero context lines.

The output line numbers in the `@@` header are 1-based and reflect
the change's position in the actual file — what the user expects
when reading a diff alongside their editor.

For `write_file` creating a new file (priorContent === ''), this
falls back to the same `--- /dev/null` convention as
`buildUnifiedDiff`.

```ts
function buildContextualDiff(
  payload: EditPayload,
  priorContent: string,
  contextLines?: number,
): string
```

**Parameters**

- `payload` (`EditPayload`): The edit payload to render.
- `priorContent` (`string`): Full file content before the edit.
- `contextLines?` (`number`, default `3`): Lines of unchanged context kept around each change.

**Returns** `string`

Source: [src/chat/edit-diff.ts:452](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L452)

### `buildLinearRamp`

Function.

Static gradient ramp of length `n` going from `from` (index 0) to
`to` (index n-1) in HSL space. For the cycling A→B→A→B ramp the
throbber uses, see `buildCycleRamp` in `src/tui/crush-throbber.tsx`.

```ts
function buildLinearRamp(from: string, to: string, n: number): string[]
```

**Parameters**

- `from` (`string`): Start color as a hex string.
- `to` (`string`): End color as a hex string.
- `n` (`number`): Number of colors in the ramp. A value of 0 or less returns an empty ramp.

**Returns** `string[]`

Source: [src/chat/color-gradient.ts:115](https://github.com/Tahul/zidane/blob/main/src/chat/color-gradient.ts#L115)

### `buildModelCatalog`

Function.

Build the unified catalog from a list of available providers.

Provider order is preserved (callers typically pass the picker order
— alphabetical, auth-detection order, etc.); model order inside each
provider matches whatever `modelsFor` returns. The current selection
(when set) is bubbled to the top of its provider's section so it
shows first without disturbing relative ordering elsewhere.

`modelsFor` is injected (not imported from `./providers`) so the same
helper works with hosts that supply their own model resolver via
`ResolvedConfig.modelsFor`.

`include` guarantees a pair is listed even when the provider stopped
serving it. Persisted picks outlive catalogs (a provider retires an id, a
user typed one by hand), and an entry that isn't in the list can't be
selected away from, and the picker would keep re-persisting it. Synthesized
entries carry `offCatalog: true` and a stub `ModelInfo`.

```ts
function buildModelCatalog(
  opts: { current?: { modelId: string; providerKey: string } | null; include?: readonly { modelId: string; providerKey: string }[]; modelsFor: (key: string, account?: string) => readonly ModelInfo[]; providers: readonly ProviderAuth[] },
): CatalogEntry[]
```

**Parameters**

- `opts` (`{ current?: { modelId: string; providerKey: string } | null; include?: readonly { modelId: string; providerKey: string }[]; modelsFor: (key: string, account?: string) => readonly ModelInfo[]; providers: readonly ProviderAuth[] }`): Providers to list, a models lookup per provider key, the current pick to float to the top of its section, and extra picks to show even when the provider does not list them.

**Returns** `CatalogEntry[]`

Source: [src/chat/model-catalog.ts:69](https://github.com/Tahul/zidane/blob/main/src/chat/model-catalog.ts#L69)

### `buildOnboardingResult`

Function.

What a finished run writes: the settings change, the provider pick, the
look and the records.

```ts
function buildOnboardingResult(
  state: OnboardingFlowState,
  stored: Partial<Settings>,
  now?: Date,
): OnboardingResult
```

**Parameters**

- `state` (`OnboardingFlowState`): The finished run.
- `stored` (`Partial<Settings>`): The settings slice stored now.
- `now?` (`Date`): When it finished.

**Returns** `OnboardingResult`

Source: [src/chat/onboarding/result.ts:190](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L190)

### `buildPanelCatalog`

Function.

Built-ins first, then extension panels in registry (load) order.

```ts
function buildPanelCatalog(
  extensionPanels: readonly Pick<ExtensionPanelEntry, 'scope' | 'id' | 'icon' | 'label' | 'ownerName' | 'ownerIcon' | 'owner' | 'surfaces'>[],
  options?: PanelCatalogOptions,
): PanelTab[]
```

**Parameters**

- `extensionPanels` (`readonly Pick<ExtensionPanelEntry, 'scope' | 'id' | 'icon' | 'label' | 'ownerName' | 'ownerIcon' | 'owner' | 'surfaces'>[]`): Panels registered by extensions.
- `options?` (`PanelCatalogOptions`, default `{}`): Catalog filters.

**Returns** `PanelTab[]`

Source: [src/chat/panels.ts:123](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L123)

### `buildPlanResumeMessage`

Function.

The message the Resume button sends: the agent continues the plan by
writing its step ids, which reopens it (the gate's resume rule).

```ts
function buildPlanResumeMessage(plan: Plan): string
```

**Parameters**

- `plan` (`Plan`): A stopped plan.

**Returns** `string`

Source: [src/chat/plans.ts:1226](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L1226)

### `buildSessionSearchIndex`

Function.

Builds a [`SessionSearchIndex`](https://zidane.si/docs/reference/chat-pure.md#SessionSearchIndex), skipping turns with no searchable text.

```ts
function buildSessionSearchIndex(turns: readonly SessionTurn[]): SessionSearchIndex
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Session turns to index.

**Returns** `SessionSearchIndex`

Source: [src/chat/history-search.ts:124](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L124)

### `buildSessionSearchIndexAsync`

Function.

Yielding index builder for TUI callers — never monopolizes a frame.

```ts
function buildSessionSearchIndexAsync(
  turns: readonly SessionTurn[],
  options?: { onProgress?: (indexed: number, total: number) => void; signal?: AbortSignal; yieldEvery?: number },
): Promise<SessionSearchIndex>
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Session turns to index.
- `options?` (`{ onProgress?: (indexed: number, total: number) => void; signal?: AbortSignal; yieldEvery?: number }`, default `{}`): Yield interval (default 80 turns), progress callback, and abort signal. Aborting throws.

**Returns** `Promise<SessionSearchIndex>`

Source: [src/chat/history-search.ts:137](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L137)

### `buildStepRetryMessage`

Function.

The message a step's Retry sends (a steer mid-run, a prompt when idle).
Quotes the step so the agent matches it against its own list, and names
the status: retrying a completed step differs from reviving a cancelled one.

```ts
function buildStepRetryMessage(step: Pick<PlanStep, 'id' | 'title' | 'status'>): string
```

**Parameters**

- `step` (`Pick<PlanStep, 'id' | 'title' | 'status'>`): The step to retry.

**Returns** `string`

Source: [src/chat/plans.ts:1239](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L1239)

### `buildUnifiedDiff`

Function.

Builds a unified diff for an edit payload.
Line numbers in each `@@` header are synthetic, since hunks carry only snippets. A `write_file` that creates a file uses `--- /dev/null`. The result ends with a newline.

```ts
function buildUnifiedDiff(payload: EditPayload): string
```

**Parameters**

- `payload` (`EditPayload`): The edit payload to render.

**Returns** `string`

Source: [src/chat/edit-diff.ts:917](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L917)

### `buildVisibleAuthRows`

Function.

Flatten the provider list plus the expanded set into the visible-row list.

- `providers` — filtered / ordered provider list (post-search).
- `expanded`  — keys of providers whose sources are open. Keys for
  providers that are no longer expandable are ignored rather
  than cleaned up, so stale expansion state (a credential
  removed while the modal is open) can't desync the cursor.

```ts
function buildVisibleAuthRows(
  providers: readonly ProviderAuth[],
  expanded: ReadonlySet<string>,
): VisibleAuthRow[]
```

**Parameters**

- `providers` (`readonly ProviderAuth[]`): Filtered and ordered provider list.
- `expanded` (`ReadonlySet<string>`): Keys of providers whose sources are open.

**Returns** `VisibleAuthRow[]`

Source: [src/chat/auth-rows.ts:68](https://github.com/Tahul/zidane/blob/main/src/chat/auth-rows.ts#L68)

### `buildVisibleInstructionRows`

Function.

Filter segments by the active query and resolve each one's expanded state.

Deliberately does NOT auto-expand matches the way the Extensions tab does:
the search corpus includes each segment's full text, so a query typically
matches deep inside a long document — auto-expanding every hit would dump
thousands of lines into the viewport on a keystroke. The user expands the row
they care about.

```ts
function buildVisibleInstructionRows(
  opts: BuildVisibleInstructionRowsOptions,
): VisibleInstructionRow[]
```

**Parameters**

- `opts` (`BuildVisibleInstructionRowsOptions`): Segments, expanded ids, and the active search state.

**Returns** `VisibleInstructionRow[]`

Source: [src/chat/instruction-rows.ts:54](https://github.com/Tahul/zidane/blob/main/src/chat/instruction-rows.ts#L54)

### `cacheBreakChip`

Function.

Build the chip for a cache break.

`costUsd` is OPTIONAL and omitted entirely on a rate miss — never rendered
as `$0.00`. A fabricated zero would read as "this was free", which is the
opposite of what the chip exists to say. When present it is prefixed `~`
because it is an estimate (registry rates × re-billed prefix), and clamped
to `<0.01` rather than rounding a real charge down to nothing.

```ts
function cacheBreakChip(info: CacheBreakInfo & { costUsd?: number }): CacheChipContent
```

**Parameters**

- `info` (`CacheBreakInfo & { costUsd?: number }`): Cache break report, with an optional estimated cost in USD.

**Returns** `CacheChipContent`

Source: [src/chat/footer-chips.ts:57](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L57)

### `cacheHintText`

Function.

The hint for an option: `re-reads ~452k tokens` when picking it would
re-read a long prompt. Nothing for the current option, a switch that keeps
the cache, a cache already expired (it is gone anyway), a short prompt, or
an unknown estimate.

```ts
function cacheHintText(
  impact: CacheImpact | null | undefined,
  current?: boolean,
): string | undefined
```

**Parameters**

- `impact` (`CacheImpact | null | undefined`): The host's estimate for the option (`ChatHost.cacheImpact`), `null` / `undefined` when unknown.
- `current?` (`boolean`, default `false`): The option is the one in force: picking it changes nothing.

**Returns** `string | undefined`

Source: [src/chat/cache-hint.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/cache-hint.ts#L20)

### `calibrationFactor`

Function.

The factor that corrects this project's estimates: the median of
actual / estimated over its recent finished runs, kept within
[`CALIBRATION_MIN`](https://zidane.si/docs/reference/chat-pure.md#CALIBRATION_MIN)..[`CALIBRATION_MAX`](https://zidane.si/docs/reference/chat-pure.md#CALIBRATION_MAX). `null` with too few runs.

```ts
function calibrationFactor(ratios: readonly number[]): number | null
```

**Parameters**

- `ratios` (`readonly number[]`): Actual / estimated working time of finished runs, oldest first.

**Returns** `number | null`

Source: [src/chat/run-estimate.ts:106](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L106)

### `canonicalKeyName`

Function.

A key name as the parser canonicalizes it (`'Enter'` → `'return'`, `'ArrowLeft'` → `'left'`).

```ts
function canonicalKeyName(key: string): string
```

**Parameters**

- `key` (`string`): Key name from a spec or a key event, in any case.

**Returns** `string`

Source: [src/chat/keybinding-spec.ts:78](https://github.com/Tahul/zidane/blob/main/src/chat/keybinding-spec.ts#L78)

### `canSkipOnboardingStep`

Function.

Whether the user can skip the current step. Welcome and Ready have nothing
to skip, and the TUI cannot run without a provider.

```ts
function canSkipOnboardingStep(state: OnboardingFlowState): boolean
```

**Parameters**

- `state` (`OnboardingFlowState`): The run.

**Returns** `boolean`

Source: [src/chat/onboarding/flow.ts:179](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L179)

### `capabilityTags`

Function.

The short tags a host's row shows: the tools found and the cloud kinds available, at most `max`.

```ts
function capabilityTags(
  capabilities: HostCapabilities,
  max?: number,
): { more: number; tags: string[] }
```

**Parameters**

- `capabilities` (`HostCapabilities`): The host's capabilities.
- `max?` (`number`, default `4`): How many tags to return; `more` counts the rest.

**Returns** `{ more: number; tags: string[] }`

Source: [src/chat/capabilities.ts:127](https://github.com/Tahul/zidane/blob/main/src/chat/capabilities.ts#L127)

### `capBlockOutput`

Function.

`output` cut to its last [`BLOCK_RUN_OUTPUT_CAP`](https://zidane.si/docs/reference/chat-pure.md#BLOCK_RUN_OUTPUT_CAP) characters.

```ts
function capBlockOutput(output: string): { output: string; truncated?: true }
```

**Parameters**

- `output` (`string`): What a run wrote.

**Returns** `{ output: string; truncated?: true }`

Source: [src/chat/shell-blocks.ts:245](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L245)

### `capTranscriptEvents`

Function.

Bound a transcript event array for display. Identity below the cap
(no re-render churn on the hot append path); above it, drops the
oldest events down to [`TRANSCRIPT_TRIM_TO_EVENTS`](https://zidane.si/docs/reference/chat-pure.md#TRANSCRIPT_TRIM_TO_EVENTS) — extended to
the next turn boundary — and prepends a cumulative hidden-count
marker. Callers: the stream buffer's drain commit and every
`eventsFromTurns` replay site.

```ts
function capTranscriptEvents(
  events: StreamEvent[],
  max?: number,
  trimTo?: number,
  weigh?: TranscriptWeight,
): StreamEvent[]
```

**Parameters**

- `events` (`StreamEvent[]`): Transcript events in order.
- `max?` (`number`, default `MAX_TRANSCRIPT_EVENTS`): Length above which the transcript is capped.
- `trimTo?` (`number`, default `TRANSCRIPT_TRIM_TO_EVENTS`): Length to trim to. Clamped to 80% of `max`.
- `weigh?` (`TranscriptWeight`): Count rows instead of events (`TranscriptWeight`); the
  raw events then stay under `MAX_WEIGHTED_TRANSCRIPT_EVENTS`.

**Returns** `StreamEvent[]`

Source: [src/chat/streaming-pure.ts:613](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L613)

### `chainAccountConflict`

Function.

Whether `entry` may join a chain led by `chain[0]` (one account per provider; see [`filterChainFallbacks`](https://zidane.si/docs/reference/chat.md#filterChainFallbacks)).

```ts
function chainAccountConflict(
  chain: readonly ModelChainEntry[],
  entry: ModelChainEntry,
): boolean
```

**Parameters**

- `chain` (`readonly ModelChainEntry[]`): The current chain.
- `entry` (`ModelChainEntry`): The pick to test.

**Returns** `boolean`

Source: [src/chat/model-chain.ts:357](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L357)

### `chainEntryKey`

Function.

Identity of a chain entry — provider, account and model, not object identity.

```ts
function chainEntryKey(entry: ModelChainEntry): string
```

**Parameters**

- `entry` (`ModelChainEntry`): The chain entry to key.

**Returns** `string`

Source: [src/chat/model-chain.ts:35](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L35)

### `chainPositionOf`

Function.

1-based chain position of a provider+model(+account) pick, or `null` when not in the chain.

```ts
function chainPositionOf(
  chain: readonly ModelChainEntry[],
  provider: string,
  model: string,
  account?: string,
): number | null
```

**Parameters**

- `chain` (`readonly ModelChainEntry[]`): The current chain.
- `provider` (`string`): Provider key of the pick.
- `model` (`string`): Model id of the pick.
- `account?` (`string`): Optional account of the pick.

**Returns** `number | null`

Source: [src/chat/model-chain.ts:175](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L175)

### `chainsEqual`

Function.

Compares two chains element by element using [`chainEntryKey`](https://zidane.si/docs/reference/chat-pure.md#chainEntryKey).

```ts
function chainsEqual(
  a: readonly ModelChainEntry[],
  b: readonly ModelChainEntry[],
): boolean
```

**Parameters**

- `a` (`readonly ModelChainEntry[]`): First chain.
- `b` (`readonly ModelChainEntry[]`): Second chain.

**Returns** `boolean`

Source: [src/chat/model-chain.ts:185](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L185)

### `chainsEqualKeyed`

Function.

Same entries in the same order.

```ts
function chainsEqualKeyed<T>(
  a: readonly T[],
  b: readonly T[],
  keyOf: (e: T) => string,
): boolean
```

**Type parameters**

- `T`

**Parameters**

- `a` (`readonly T[]`): First list.
- `b` (`readonly T[]`): Second list.
- `keyOf` (`(e: T) => string`): Returns the identity key of an element.

**Returns** `boolean`

Source: [src/chat/model-chain.ts:120](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L120)

### `chatReferenceTokensFromText`

Function.

Extracts the `#token` chat references from text.
A token starts after whitespace or at the start of the text. Trailing punctuation is stripped, tokens are lowercased and duplicates are dropped.

```ts
function chatReferenceTokensFromText(text: string): string[]
```

**Parameters**

- `text` (`string`): The prompt text to scan.

**Returns** `string[]`

Source: [src/chat/completion-chats.ts:288](https://github.com/Tahul/zidane/blob/main/src/chat/completion-chats.ts#L288)

### `chunkMarkdownForRender`

Function.

Split a large markdown document into render-safe chunks at blank-line
boundaries outside code fences, each roughly `targetBytes` long.

Rendering the chunks as SIBLING markdown renderables (with a one-row
gap standing in for the consumed blank line) is visually equivalent to
one renderable, but sidesteps the quadratic lexer cost documented on
[`MARKDOWN_RENDER_CHUNK_TARGET_BYTES`](https://zidane.si/docs/reference/chat-pure.md#MARKDOWN_RENDER_CHUNK_TARGET_BYTES). Chunk boundaries are
prefix-stable: appending text (streaming) can only ever change the
LAST chunk, so keyed-by-index consumers reconcile cheaply.

Returns `[text]` untouched for anything at or under the target.

```ts
function chunkMarkdownForRender(text: string, targetBytes?: number): string[]
```

**Parameters**

- `text` (`string`): Markdown document.
- `targetBytes?` (`number`, default `MARKDOWN_RENDER_CHUNK_TARGET_BYTES`): Approximate chunk size. Counted in string length.

**Returns** `string[]`

Source: [src/chat/markdown-segments.ts:325](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L325)

### `classifyMcpTest`

Function.

Classifies a connection attempt. HTTP servers that required auth or answered
401/403 become `token-rejected` when the config sends its own headers, else
`needs-auth`. Any other error becomes `error`. A clean connection is `ok`.

```ts
function classifyMcpTest(
  config: Pick<McpServerConfig, 'transport' | 'headers'>,
  result: { authRequired: boolean; error?: unknown; tools?: number },
): McpTestResult
```

**Parameters**

- `config` (`Pick<McpServerConfig, 'transport' | 'headers'>`): The server's transport and headers.
- `result` (`{ authRequired: boolean; error?: unknown; tools?: number }`): Whether auth was required, the error if any, and the tool count.

**Returns** `McpTestResult`

Source: [src/chat/mcp-test-outcome.ts:71](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-test-outcome.ts#L71)

### `clipAnsiLine`

Function.

A line cut to `max` visible characters, the last one an ellipsis when it is cut.

```ts
function clipAnsiLine(spans: readonly AnsiSpan[], max: number): AnsiSpan[]
```

**Parameters**

- `spans` (`readonly AnsiSpan[]`): The line's spans.
- `max` (`number`): Visible characters kept.

**Returns** `AnsiSpan[]`

Source: [src/chat/ansi.ts:316](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L316)

### `clockOrDateText`

Function.

"14:05" when `at` falls on `now`'s day, "Oct 12" in the same year, else "Oct 12, 2025".

```ts
function clockOrDateText(at: number, now: number): string
```

**Parameters**

- `at` (`number`): Epoch milliseconds to show.
- `now` (`number`): Epoch milliseconds of today.

**Returns** `string`

Source: [src/chat/machines-view.ts:192](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L192)

### `clockText`

Function.

"14:05", local time, 24-hour.

```ts
function clockText(at: number): string
```

**Parameters**

- `at` (`number`): Epoch milliseconds.

**Returns** `string`

Source: [src/chat/machines-view.ts:181](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L181)

### `closePanel`

Function.

Closes the panel and keeps the active tab.

```ts
function closePanel(state: PanelState): PanelState
```

**Parameters**

- `state` (`PanelState`): The current panel state.

**Returns** `PanelState`

Source: [src/chat/panels.ts:253](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L253)

### `collectReferences`

Function.

Collect every provider's references in one pass. Convenience wrapper —
the TUI textarea component calls this on every keystroke to highlight
in-prompt mentions.

```ts
function collectReferences<TItem>(
  text: string,
  providers: readonly CompletionProvider<TItem>[],
  cursor?: number,
): CompletionReference<TItem>[]
```

**Type parameters**

- `TItem`

**Parameters**

- `text` (`string`): The prompt text to scan.
- `providers` (`readonly CompletionProvider<TItem>[]`): Providers whose `parseReferences` run over the text.
- `cursor?` (`number`, default `text.length`): Cursor offset passed to the providers in their context.

**Returns** `CompletionReference<TItem>[]`

Source: [src/chat/completion-core.ts:366](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L366)

### `commandGist`

Function.

`Ran <gist>` for a shell command: heredoc bodies dropped, setup steps
(`cd`, `export`, `set -e`) skipped, env and wrappers peeled off, program
plus subcommand kept. Further meaningful steps read as `+N`.

```ts
function commandGist(command: string): { gist: string; more: number }
```

**Parameters**

- `command` (`string`): Shell command text, possibly several steps.

**Returns** `{ gist: string; more: number }`

Source: [src/chat/fold-actions.ts:159](https://github.com/Tahul/zidane/blob/main/src/chat/fold-actions.ts#L159)

### `compactingLabel`

Function.

[`compactingParts`](https://zidane.si/docs/reference/chat-pure.md#compactingParts) as one plain string, for a slot that cannot hold
badges: `Compacting... ~12k, 8s`.

```ts
function compactingLabel(
  estTokens: number | null | undefined,
  startedAt: number | null | undefined,
  now?: number,
): string
```

**Parameters**

- `estTokens` (`number | null | undefined`): Token estimate reported by the loop, if any.
- `startedAt` (`number | null | undefined`): Compaction start time in epoch milliseconds, if known.
- `now?` (`number`): Current time in epoch milliseconds. Defaults to `Date.now()`.

**Returns** `string`

Source: [src/chat/footer-chips.ts:213](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L213)

### `compactingParts`

Function.

Footer readout while a compaction summary is being generated: the label,
then `~12k` once the loop reports a token estimate, then `8s` once a second
has passed, one badge each. Same rule on every surface so a minutes-long
compaction of a large transcript reads as progress, not a hang, in the TUI
and the GUI alike.

`now` is injectable so callers driving a 1 Hz tick don't have to re-read
the clock, and so tests are deterministic.

```ts
function compactingParts(
  estTokens: number | null | undefined,
  startedAt: number | null | undefined,
  now?: number,
): { label: string; meta: string[] }
```

**Parameters**

- `estTokens` (`number | null | undefined`): Token estimate reported by the loop, if any.
- `startedAt` (`number | null | undefined`): Compaction start time in epoch milliseconds, if known.
- `now?` (`number`): Current time in epoch milliseconds. Defaults to `Date.now()`.

**Returns** `{ label: string; meta: string[] }`

Source: [src/chat/footer-chips.ts:192](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L192)

### `compactPath`

Function.

Compact an absolute path for display: replace the user's `$HOME`
prefix with `~` (so `/Users/yael/Code/zidane` → `~/Code/zidane`),
and optionally left-truncate with an ellipsis when the result
still exceeds `maxWidth` (so the path's *tail* — the part the user
recognizes — stays visible: `…/zidane` rather than `/Users/yaeluil…`).

`maxWidth` is the maximum *display width* in cells. Omit to skip
truncation. Paths outside `$HOME` are returned verbatim modulo
truncation. The ellipsis (`…`) counts as one cell.

`home` overrides the home directory read from `HOME` / `USERPROFILE`
for tests; production callers leave it undefined.

```ts
function compactPath(path: string, maxWidth?: number, home?: string): string
```

**Parameters**

- `path` (`string`): Absolute path to shorten.
- `maxWidth?` (`number`): Maximum display width in cells. Omit to skip truncation.
- `home?` (`string`): Home directory to abbreviate. Defaults to `HOME`, then `USERPROFILE`, then none (path returned verbatim).

**Returns** `string`

Source: [src/chat/format.ts:324](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L324)

### `compareModelVersion`

Function.

Numeric, segment by segment; a longer version wins a tie on the shared prefix (`5.5` > `5`).

```ts
function compareModelVersion(a: readonly number[], b: readonly number[]): number
```

**Parameters**

- `a` (`readonly number[]`): First version, as parsed by [`parseModelId`](https://zidane.si/docs/reference/chat-pure.md#parseModelId).
- `b` (`readonly number[]`): Second version.

**Returns** `number`

Source: [src/chat/model-lineup.ts:135](https://github.com/Tahul/zidane/blob/main/src/chat/model-lineup.ts#L135)

### `compareValues`

Function.

Orders two present values: numbers, then strings (natural order, case
ignored, then exact), then booleans (`false` first), then anything else
by its JSON text.

```ts
function compareValues(a: unknown, b: unknown): number
```

**Parameters**

- `a` (`unknown`): A value.
- `b` (`unknown`): Another value.

**Returns** `number`: Negative, zero or positive.

Source: [src/chat/session-query/sort.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/sort.ts#L26)

### `compileQuery`

Function.

Compiles a query into a predicate. Relative bounds (`'-7d'`) resolve
against `options.now` each time the predicate runs, so a long-lived
predicate stays current. Throws [`SessionQueryError`](https://zidane.si/docs/reference/chat-pure.md#SessionQueryError) for an invalid query.

```ts
function compileQuery<R extends SessionQueryRow>(
  where: SessionQuery | undefined,
  options?: QueryOptions,
): (row: R) => boolean
```

**Type parameters**

- `R` (`extends SessionQueryRow`)

**Parameters**

- `where` (`SessionQuery | undefined`): The query. `undefined` matches every row.
- `options?` (`QueryOptions`, default `{}`): The clock.

**Returns** `(row: R) => boolean`: A predicate over rows.

Source: [src/chat/session-query/compile.ts:121](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/compile.ts#L121)

### `computeInlineDiff`

Function.

Computes word-level segments for a paired removed and added line.
Both segment lists keep the same order. Tokens that differ have `changed: true`. Very long lines fall back to one fully changed segment.

```ts
function computeInlineDiff(oldLine: string, newLine: string): InlineDiff
```

**Parameters**

- `oldLine` (`string`): The line before the edit.
- `newLine` (`string`): The line after the edit.

**Returns** `InlineDiff`

Source: [src/chat/edit-diff.ts:295](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L295)

### `computeLineDiff`

Function.

Computes a line diff between two strings with an LCS table.
Common leading and trailing lines are trimmed first. When the changed core is too large for the table budget, the result is all removals followed by all additions.

```ts
function computeLineDiff(oldString: string, newString: string): DiffLine[]
```

**Parameters**

- `oldString` (`string`): Text before the edit.
- `newString` (`string`): Text after the edit.

**Returns** `DiffLine[]`

Source: [src/chat/edit-diff.ts:152](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L152)

### `connectorAuthText`

Function.

How a connector signs in, when it is not the usual browser sign-in.

```ts
function connectorAuthText(
  entry: ConnectorEntry,
  ghLogin: boolean,
  words: ConnectorAuthWords,
): string | null
```

**Parameters**

- `entry` (`ConnectorEntry`): The connector.
- `ghLogin` (`boolean`): A `gh` login was found, so a GitHub token can come from it.
- `words` (`ConnectorAuthWords`): The words to use.

**Returns** `string | null`: The words, or `null` for a browser sign-in.

Source: [src/chat/onboarding/words.ts:170](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L170)

### `connectorById`

Function.

A connector by id, or `undefined`.

```ts
function connectorById(id: string): ConnectorEntry | undefined
```

**Parameters**

- `id` (`string`): The connector id.

**Returns** `ConnectorEntry | undefined`

Source: [src/chat/onboarding/connectors.ts:178](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L178)

### `connectorInputError`

Function.

Why zidane cannot add a connector with this input, or `undefined` when it
can. The one reason is a missing token that the connector needs.

```ts
function connectorInputError(
  entry: ConnectorEntry,
  input?: ConnectorInput,
): string | undefined
```

**Parameters**

- `entry` (`ConnectorEntry`): The connector.
- `input?` (`ConnectorInput`, default `{}`): What the user typed.

**Returns** `string | undefined`

Source: [src/chat/onboarding/connectors.ts:189](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L189)

### `connectorInstalled`

Function.

Whether a connector is already installed: a server with its name, its
endpoint, or its command and arguments.

```ts
function connectorInstalled(
  entry: ConnectorEntry,
  servers: readonly InstalledServerRef[],
): boolean
```

**Parameters**

- `entry` (`ConnectorEntry`): The connector.
- `servers` (`readonly InstalledServerRef[]`): The servers already configured.

**Returns** `boolean`

Source: [src/chat/onboarding/connectors.ts:243](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L243)

### `connectorServerConfig`

Function.

The MCP server a connector writes to `mcps.json`.

```ts
function connectorServerConfig(
  entry: ConnectorEntry,
  input?: ConnectorInput,
): McpServerConfig
```

**Parameters**

- `entry` (`ConnectorEntry`): The connector.
- `input?` (`ConnectorInput`, default `{}`): What the user typed: the token, for token sign-in.

**Returns** `McpServerConfig`

**Example**

```ts
import { connectorById, connectorServerConfig } from 'zidane/chat/pure'

connectorServerConfig(connectorById('linear')!)
// { name: 'linear', transport: 'streamable-http', url: 'https://mcp.linear.app/mcp' }
```

Source: [src/chat/onboarding/connectors.ts:209](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L209)

### `connectorsFromImport`

Function.

The connectors that an import brings over: the MCP servers that it copies
and that have the id of a connector. The Connectors step marks them, and the
run does not add them twice.

```ts
function connectorsFromImport(
  preview: OnboardingImportPreviewState,
  selection: OnboardingImportSelection | undefined,
): readonly string[]
```

**Parameters**

- `preview` (`OnboardingImportPreviewState`): What the import brings over.
- `selection` (`OnboardingImportSelection | undefined`): What the user picked to import.

**Returns** `readonly string[]`

**Example**

```ts
import { connectorsFromImport } from 'zidane/chat/pure'

const none = { copy: [], skip: [] }
const preview = { sessions: { project: 0, all: 0 }, mcps: { copy: ['github', 'my-db'], skip: [] }, skills: none, commands: none, agents: none, notes: [] }
const selection = { sessions: false, allProjects: false, mcps: true, skills: false, commands: false, agents: false }
connectorsFromImport({ kind: 'ready', preview }, selection) // ['github']
```

Source: [src/chat/onboarding/run.ts:90](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L90)

### `copyNames`

Function.

The names a copy of `name` tries, in order: itself, `a copy.ts`, `a copy 2.ts`, …
(a folder or a dotfile keeps no extension apart).

```ts
function copyNames(name: string, kind: EntryKind): Generator<string>
```

**Parameters**

- `name` (`string`): The name to copy.
- `kind` (`EntryKind`): A file or a folder: only a file keeps its extension at the end.

**Returns** `Generator<string>`

Source: [src/chat/workspace/entries.ts:131](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L131)

### `countNeighbors`

Function.

Count turns before / after the one identified by `turnId` in the
given list. Returns `null` when the id is missing. Used to label the
turn-details modal with `N before, M after`.

```ts
function countNeighbors(
  turnIds: readonly string[],
  turnId: string,
): { after: number; before: number } | null
```

**Parameters**

- `turnIds` (`readonly string[]`): Turn ids in order.
- `turnId` (`string`): Id of the turn to locate.

**Returns** `{ after: number; before: number } | null`

Source: [src/chat/turn-operations.ts:241](https://github.com/Tahul/zidane/blob/main/src/chat/turn-operations.ts#L241)

### `countOnceCallSites`

Function.

How many calls a script makes, when every call can run once at most: each
`tools.<name>(…)` or `sh(…)` sits outside loops and functions (callbacks,
helpers, methods). `undefined` when one may run more than once, when the
script reaches `tools` or `sh` another way (a reference, a computed name),
or when it makes no call. A call in a branch that does not run makes the
count high, never low, so a percent from it never runs ahead.

```ts
function countOnceCallSites(code: string): number | undefined
```

**Parameters**

- `code` (`string`): The script, as the model wrote it.

**Returns** `number | undefined`

Source: [src/chat/script-progress.ts:851](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L851)

### `createAnsiLines`

Function.

Creates an incremental [`AnsiLines`](https://zidane.si/docs/reference/chat-pure.md#AnsiLines) reader. The style carries across chunks and lines, as in a terminal.

```ts
function createAnsiLines(): AnsiLines
```

**Returns** `AnsiLines`

Source: [src/chat/ansi.ts:166](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L166)

### `createChatsCompletionProvider`

Function.

Creates a completion provider for `#` chat references.
Each chat gets the shortest id prefix, at least 6 characters, that identifies it in the catalog. Suggestions are fuzzy-matched on title, token and project folder.

```ts
function createChatsCompletionProvider(
  opts: { ensureCatalog?: () => Promise<readonly ChatReferenceEntry[]>; getCatalog: () => readonly ChatReferenceEntry[]; getReferenceCatalog?: () => readonly ChatReferenceEntry[]; getScope?: () => ChatReferenceScope; limit?: number },
): CompletionProvider<ChatReferenceData>
```

**Parameters**

- `opts` (`{ ensureCatalog?: () => Promise<readonly ChatReferenceEntry[]>; getCatalog: () => readonly ChatReferenceEntry[]; getReferenceCatalog?: () => readonly ChatReferenceEntry[]; getScope?: () => ChatReferenceScope; limit?: number }`): Catalog getters, an optional async catalog loader, the scope used for labels and a result limit (default 50).

**Returns** `CompletionProvider<ChatReferenceData>`

**Example**

```ts
import { createChatsCompletionProvider } from 'zidane/chat'

const provider = createChatsCompletionProvider({
  getCatalog: () => [
    { id: 'c0ffee00-0000-4000-8000-000000000001', title: 'Fix login', turnCount: 4, userMessageCount: 2, runCount: 2, updatedAt: Date.now() },
  ],
})
```

Source: [src/chat/completion-chats.ts:202](https://github.com/Tahul/zidane/blob/main/src/chat/completion-chats.ts#L202)

### `createCommandsCompletionProvider`

Function.

Build a commands completion provider against a *live* command list. The
getter is re-evaluated per `suggest` so registry toggles / cwd rebuilds
take effect without re-instantiating the provider.

```ts
function createCommandsCompletionProvider(
  opts: { getCommands: () => readonly Command[] },
): CompletionProvider<Command>
```

**Parameters**

- `opts` (`{ getCommands: () => readonly Command[] }`): Options. `getCommands` returns the current command list and is re-read on every suggestion.

**Returns** `CompletionProvider<Command>`

Source: [src/chat/completion-commands.ts:82](https://github.com/Tahul/zidane/blob/main/src/chat/completion-commands.ts#L82)

### `createEntryOps`

Function.

The entry actions over `port`, whose paths are relative to the folder (the
caller's port maps them where they live).

```ts
function createEntryOps(port: EntryPort): EntryOps
```

**Parameters**

- `port` (`EntryPort`): The folder's file operations.

**Returns** `EntryOps`

Source: [src/chat/workspace/entries.ts:181](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L181)

### `createFilesCompletionProvider`

Function.

Build an `@`-prefixed files completion provider against a *live* catalog.

The factory captures a getter so the catalog can be re-scanned (cwd
change, manual refresh) without re-instantiating the provider — the
App keeps one provider for the lifetime of the prompt block and just
mutates the underlying state.

`limit` caps the result list so the popover stays bounded on huge
monorepos. Filtering is substring on `path` + `name`, case-insensitive,
with an fzf-scored basename fuzzy fallback so small typos / omissions
(`lop.ts` → `loop.ts`) still surface results; ranking prefers (in
order): exact name match, name prefix, name substring, path substring,
basename fuzzy match, alphabetical.

```ts
function createFilesCompletionProvider(
  opts: { ensureCatalog?: () => Promise<readonly FileEntry[]>; formatPath?: (entry: FileEntry) => string; getCatalog: () => readonly FileEntry[]; limit?: number },
): CompletionProvider<FileEntry>
```

**Parameters**

- `opts` (`{ ensureCatalog?: () => Promise<readonly FileEntry[]>; formatPath?: (entry: FileEntry) => string; getCatalog: () => readonly FileEntry[]; limit?: number }`): Options: the live file catalog, an optional lazy catalog loader, a result limit and a path rewriter.

**Returns** `CompletionProvider<FileEntry>`

Source: [src/chat/completion-files.ts:172](https://github.com/Tahul/zidane/blob/main/src/chat/completion-files.ts#L172)

### `createHostIndex`

Function.

Creates an empty index of which host holds each id.

```ts
function createHostIndex(noun?: string): HostIndex
```

**Parameters**

- `noun?` (`string`, default `'session'`): What the ids name, used in error messages.

**Returns** `HostIndex`

Source: [src/chat/hosts/host-index.ts:99](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/host-index.ts#L99)

### `createOnboardingFlow`

Function.

A new run at its first step.

```ts
function createOnboardingFlow(
  context: OnboardingPlanContext,
  start: OnboardingStart,
): OnboardingFlowState
```

**Parameters**

- `context` (`OnboardingPlanContext`): The run's mode, surface and what was found so far.
- `start` (`OnboardingStart`): The settings, look and provider in effect now.

**Returns** `OnboardingFlowState`

Source: [src/chat/onboarding/flow.ts:128](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L128)

### `createOnboardingRun`

Function.

Starts a run of the setup wizard.

```ts
function createOnboardingRun(
  host: OnboardingRunHost,
  setup: OnboardingRunSetup,
  options?: OnboardingRunOptions,
): OnboardingRun
```

**Parameters**

- `host` (`OnboardingRunHost`): The work that the app does for the run.
- `setup` (`OnboardingRunSetup`): What the run starts from.
- `options?` (`OnboardingRunOptions`, default `{}`): The step to open at, and the clock.

**Returns** `OnboardingRun`: The run. Call `dispose` when the wizard closes.

**Example**

```ts
import { createOnboardingRun } from 'zidane/chat/pure'

const run = createOnboardingRun(
  { commit: async result => console.log(result.settings) },
  { context: { mode: 'full', surface: 'tui', importAvailable: false, installsAvailable: false }, settings: {} },
)
run.dispatch({ type: 'set-settings', settings: { spaces: true } })
run.dispatch({ type: 'finish' }) // logs { set: { spaces: true }, reset: [] }
```

Source: [src/chat/onboarding/run.ts:227](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L227)

### `createOutputTail`

Function.

Creates an empty [`OutputTail`](https://zidane.si/docs/reference/chat-pure.md#OutputTail).

```ts
function createOutputTail(maxLines: number, lineChars: number): OutputTail
```

**Parameters**

- `maxLines` (`number`): Lines kept.
- `lineChars` (`number`): Characters kept per line.

**Returns** `OutputTail`

Source: [src/chat/output-tail.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/output-tail.ts#L52)

### `createPaletteRanker`

Function.

`rankPaletteItems` for a palette being typed into: it remembers the last
query, and when the next one only adds to it (one more character, one
more word) it searches just what matched before. A longer query never
matches an item the shorter one missed, so the result is the same.

```ts
function createPaletteRanker(): (items: readonly PaletteItem[], query: string, recents?: readonly string[]) => RankedPaletteItem[]
```

**Returns** `(items: readonly PaletteItem[], query: string, recents?: readonly string[]) => RankedPaletteItem[]`

Source: [src/chat/palette.ts:359](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L359)

### `createPresenceMerge`

Function.

Creates an empty presence merge that keeps the last snapshot of each host.

```ts
function createPresenceMerge<Row extends { sessionId: string }>(): PresenceMerge<Row>
```

**Type parameters**

- `Row` (`extends { sessionId: string }`)

**Returns** `PresenceMerge<Row>`

Source: [src/chat/hosts/presence.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/presence.ts#L21)

### `createRunStopMarker`

Function.

The run-stop pass for one surface. It returns its input itself when no run
stopped early, so memoised consumers stay put.

It runs on every stream drain tick, where only the tail changes. Items are
immutable, so both caches key on identity: the failure scan reads each
reply once, and a segment whose items are unchanged hands back its previous
output (without that, a session with one old failed run minted fresh stop
items every tick, so they re-rendered on every streamed token).

```ts
function createRunStopMarker<T extends RunStopItem>(
  adapter: RunStopAdapter<T>,
): (items: readonly T[]) => readonly T[]
```

**Type parameters**

- `T` (`extends RunStopItem`)

**Parameters**

- `adapter` (`RunStopAdapter<T>`): How the surface copies and marks its items.

**Returns** `(items: readonly T[]) => readonly T[]`

Source: [src/chat/run-stops.ts:99](https://github.com/Tahul/zidane/blob/main/src/chat/run-stops.ts#L99)

### `createScriptProgressTracker`

Function.

Creates an empty [`ScriptProgressTracker`](https://zidane.si/docs/reference/chat-pure.md#ScriptProgressTracker).

```ts
function createScriptProgressTracker(): ScriptProgressTracker
```

**Returns** `ScriptProgressTracker`

Source: [src/chat/script-progress.ts:80](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L80)

### `createSkillsCompletionProvider`

Function.

Build a slash-command completion provider against a *live* skills
catalog. The factory captures a getter so the catalog can change across
renders (toggles, reload) without re-instantiating the provider.

Pass `getEnabled` to additionally hide skills the user has toggled off
— when undefined, every catalog entry is offered.

```ts
function createSkillsCompletionProvider(
  opts: { ensureCatalog?: () => Promise<readonly SkillConfig[]>; getCatalog: () => readonly SkillConfig[]; getEnabled?: () => readonly string[] | undefined },
): CompletionProvider<SkillConfig>
```

**Parameters**

- `opts` (`{ ensureCatalog?: () => Promise<readonly SkillConfig[]>; getCatalog: () => readonly SkillConfig[]; getEnabled?: () => readonly string[] | undefined }`): Options: the live skill catalog, an optional enabled-skills filter and an optional lazy catalog loader.

**Returns** `CompletionProvider<SkillConfig>`

Source: [src/chat/completion-skills.ts:121](https://github.com/Tahul/zidane/blob/main/src/chat/completion-skills.ts#L121)

### `cronProblem`

Function.

Schedules: the wire shapes, the checks and the time math that the host,
the TUI and the UI share. The cron math (`./cron`, on `croner`) and the
scheduler (`./scheduler`) are imported by path, so this entry stays free
of them. See docs/SCHEDULES.md.

```ts
function cronProblem(expr: string, tz: string, cron?: CronEngine): string | undefined
```

**Parameters**

- `expr` (`string`): The expression.
- `tz` (`string`): The IANA time zone.
- `cron?` (`CronEngine`): The cron math. Absent: only the five fields are checked.

**Returns** `string | undefined`

Source: [src/schedules/next-fire.ts:78](https://github.com/Tahul/zidane/blob/main/src/schedules/next-fire.ts#L78)

### `currentModelKeys`

Function.

Keys (`provider\0model`) of the current models: per provider and family,
the newest version, one entry per size. `keep` entries (the active model,
fallback chain, off-catalog ids) are always included.

```ts
function currentModelKeys(
  entries: readonly LineupEntry[],
  keep?: readonly LineupEntry[],
): Set<string>
```

**Parameters**

- `entries` (`readonly LineupEntry[]`): Every provider and model id on offer.
- `keep?` (`readonly LineupEntry[]`, default `[]`): Entries to include regardless of age.

**Returns** `Set<string>`

Source: [src/chat/model-lineup.ts:186](https://github.com/Tahul/zidane/blob/main/src/chat/model-lineup.ts#L186)

### `currentModels`

Function.

`entries` in their original order, current models only (see [`currentModelKeys`](https://zidane.si/docs/reference/chat-pure.md#currentModelKeys)).

```ts
function currentModels<T extends LineupEntry>(
  entries: readonly T[],
  keep?: readonly LineupEntry[],
): T[]
```

**Type parameters**

- `T` (`extends LineupEntry`)

**Parameters**

- `entries` (`readonly T[]`): Every provider and model id on offer.
- `keep?` (`readonly LineupEntry[]`, default `[]`): Entries to include regardless of age.

**Returns** `T[]`

Source: [src/chat/model-lineup.ts:225](https://github.com/Tahul/zidane/blob/main/src/chat/model-lineup.ts#L225)

### `currentOnboardingStep`

Function.

The current step.

```ts
function currentOnboardingStep(state: OnboardingFlowState): OnboardingStepId
```

**Parameters**

- `state` (`OnboardingFlowState`): The run.

**Returns** `OnboardingStepId`

Source: [src/chat/onboarding/flow.ts:169](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L169)

### `customModelTargets`

Function.

Every route for a typed model id, one per provider: the provider the query
names first (`xai grok-9`), then `fallbackProviderKey` (the current pick),
then the rest in the given order. Lets a picker offer "use this id via…"
for each signed-in provider instead of guessing one. Empty when the query
names no model id.

```ts
function customModelTargets(
  query: string,
  providers: readonly Pick<ProviderAuth, 'key' | 'label'>[],
  fallbackProviderKey: string | null,
): CustomModelTarget[]
```

**Parameters**

- `query` (`string`): Free text, optionally starting with a provider key or label.
- `providers` (`readonly Pick<ProviderAuth, 'key' | 'label'>[]`): Providers to offer, ranked with the named one first and the fallback second.
- `fallbackProviderKey` (`string | null`): Provider to rank second when the query names none.

**Returns** `CustomModelTarget[]`

Source: [src/chat/model-catalog.ts:256](https://github.com/Tahul/zidane/blob/main/src/chat/model-catalog.ts#L256)

### `cycleTab`

Function.

Cycle to the next / previous tab (wraps). Counts as a user pick.

```ts
function cycleTab(
  state: PanelState,
  catalog: readonly PanelTab[],
  direction: -1 | 1,
): PanelState
```

**Parameters**

- `state` (`PanelState`): The current panel state.
- `catalog` (`readonly PanelTab[]`): Tabs in display order.
- `direction` (`-1 | 1`): `1` for the next tab, `-1` for the previous.

**Returns** `PanelState`

Source: [src/chat/panels.ts:307](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L307)

### `dayOfYear`

Function.

The day of the year (1-366) of `d`: a seed stable within a day.

```ts
function dayOfYear(d: Date): number
```

**Parameters**

- `d` (`Date`): The date.

**Returns** `number`

Source: [src/chat/usage-format.ts:78](https://github.com/Tahul/zidane/blob/main/src/chat/usage-format.ts#L78)

### `daysEndingAt`

Function.

The `count` days ending at `end` (inclusive), oldest first, as local `YYYY-MM-DD`.

```ts
function daysEndingAt(count: number, end?: string): string[]
```

**Parameters**

- `count` (`number`): How many days.
- `end?` (`string`): The last day (local `YYYY-MM-DD`); default today.

**Returns** `string[]`

Source: [src/chat/heatmap-levels.ts:61](https://github.com/Tahul/zidane/blob/main/src/chat/heatmap-levels.ts#L61)

### `decisionsEnabled`

Function.

Whether the agent gets decisions: the user turned them on, or Model
decision approvals (`approvalMode: 'decide'`) need their answers.

```ts
function decisionsEnabled(
  settings: Partial<Pick<Settings, 'decisions' | 'approvalMode'>>,
): boolean
```

**Parameters**

- `settings` (`Partial<Pick<Settings, 'decisions' | 'approvalMode'>>`): Settings that hold the `decisions` switch and the approval mode.

**Returns** `boolean`

Source: [src/chat/settings-defaults.ts:425](https://github.com/Tahul/zidane/blob/main/src/chat/settings-defaults.ts#L425)

### `defaultCatchUp`

Function.

The default `catchUp` of a trigger: a missed reminder still arrives, a missed recurring fire does not.

```ts
function defaultCatchUp(trigger: ScheduleTrigger): ScheduleCatchUp
```

**Parameters**

- `trigger` (`ScheduleTrigger`): The schedule's trigger.

**Returns** `ScheduleCatchUp`

Source: [src/schedules/validate.ts:202](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L202)

### `defaultExtensionSource`

Function.

The default source pinned to a release, `Tahul/zidane#v<version>`: the
native extensions that match the running app's API.

```ts
function defaultExtensionSource(version: string): string
```

**Parameters**

- `version` (`string`): The running zidane version (`ZIDANE_VERSION`), with or without the `v`.

**Returns** `string`

**Example**

```ts
import { defaultExtensionSource } from 'zidane/chat/pure'

defaultExtensionSource('9.0.4') // 'Tahul/zidane#v9.0.4'
```

Source: [src/chat/extension-sources.ts:105](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L105)

### `defaultImportSelection`

Function.

The selection that Bring your setup starts on. It has every piece with
something new to copy. It has the sessions of this project, or of every
project when this project has none.

```ts
function defaultImportSelection(
  preview: OnboardingImportPreview,
): OnboardingImportSelection
```

**Parameters**

- `preview` (`OnboardingImportPreview`): What an import brings over.

**Returns** `OnboardingImportSelection`

**Example**

```ts
import { defaultImportSelection } from 'zidane/chat/pure'

const none = { copy: [], skip: [] }
defaultImportSelection({ sessions: { project: 0, all: 3 }, mcps: { copy: ['github'], skip: [] }, skills: none, commands: none, agents: none, notes: [] })
// { sessions: true, allProjects: true, mcps: true, skills: false, commands: false, agents: false }
```

Source: [src/chat/onboarding/imports.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/imports.ts#L23)

### `defaultSessionAgent`

Function.

The agent a new session in `spaceId` starts on: the space's (spaces on),
else the global one (`Settings.defaultAgent`), else `undefined` (Build). An
id the registry doesn't hold is the caller's to resolve (`resolveAgentId`).

```ts
function defaultSessionAgent(
  settings: SpacesSettings | undefined,
  spaceId: string | undefined,
): string | undefined
```

**Parameters**

- `settings` (`SpacesSettings | undefined`): The settings the helpers read.
- `spaceId` (`string | undefined`): Space the session is created in.

**Returns** `string | undefined`

Source: [src/chat/spaces.ts:421](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L421)

### `defaultSessionKnobs`

Function.

The effort and options a new session in `spaceId` starts with, whatever its
model: each the space's own (spaces on), else the global one
(`Settings.defaultEffort` / `defaultModelOptions`), else absent (the last
used with the model). A pick in the composer wins over these.

```ts
function defaultSessionKnobs(
  settings: SpacesSettings | undefined,
  spaceId: string | undefined,
): SessionKnobs
```

**Parameters**

- `settings` (`SpacesSettings | undefined`): The settings the helpers read.
- `spaceId` (`string | undefined`): Space the session is created in.

**Returns** `SessionKnobs`

Source: [src/chat/spaces.ts:391](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L391)

### `defaultSessionModel`

Function.

The model a new session in `spaceId` starts on: the space's default
(spaces on), else the global one (`Settings.defaultModel`), else
`undefined` (the caller's last used), with the effort and options new
sessions start with ([`defaultSessionKnobs`](https://zidane.si/docs/reference/chat-pure.md#defaultSessionKnobs)). A pick in the composer
wins over this ([`newSessionModel`](https://zidane.si/docs/reference/chat-pure.md#newSessionModel)).

```ts
function defaultSessionModel(
  settings: SpacesSettings | undefined,
  spaceId: string | undefined,
): SpaceModelDefault | undefined
```

**Parameters**

- `settings` (`SpacesSettings | undefined`): The settings the helpers read.
- `spaceId` (`string | undefined`): Space the session is created in.

**Returns** `SpaceModelDefault | undefined`

Source: [src/chat/spaces.ts:408](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L408)

### `defineFeatureGate`

Function.

Creates a [`FeatureGate`](https://zidane.si/docs/reference/chat-pure.md#FeatureGate) from its setting key, kill-switch env var, and CLI flag.

```ts
function defineFeatureGate<K extends string>(
  options: FeatureGateOptions<K>,
): FeatureGate<K>
```

**Type parameters**

- `K` (`extends string`)

**Parameters**

- `options` (`FeatureGateOptions<K>`): Setting key, kill-switch env var, and flag name.

**Returns** `FeatureGate<K>`

**Example**

```ts
import { defineFeatureGate } from 'zidane/chat'

const gate = defineFeatureGate({ setting: 'daemon', killSwitchEnv: 'ZIDANE_NO_DAEMON', flag: '--no-daemon' })
gate.isEnabled({ daemon: true }, {}) // true
gate.isEnabled({ daemon: true }, { ZIDANE_NO_DAEMON: '1' }) // false
```

Source: [src/chat/feature-gate.ts:60](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L60)

### `deleteTurnSafely`

Function.

Delete — remove the turn with `turnId` and any tool blocks left
orphaned by the removal. Returns `null` when `turnId` doesn't exist.

Strategy:

1. Drop the target turn.
2. Scan the remaining turns for `tool_call`s without a matching
   `tool_result` (orphaned by removing the user turn that carried
   the result), and `tool_result`s without a matching `tool_call`
   (orphaned by removing the assistant turn that issued the call).
   Strip both sides.
3. Drop turns whose content is now empty.

This guarantees the resulting history is protocol-clean — a follow-up
`agent.run()` against the modified session can post turns without the
provider rejecting the history.

```ts
function deleteTurnSafely(
  turns: readonly SessionTurn[],
  turnId: string,
): SessionTurn[] | null
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Persisted turns in order.
- `turnId` (`string`): Id of the turn to delete.

**Returns** `SessionTurn[] | null`

Source: [src/chat/turn-operations.ts:101](https://github.com/Tahul/zidane/blob/main/src/chat/turn-operations.ts#L101)

### `describeDuration`

Function.

A duration in words: `90 min` → `1 h 30 min`.

```ts
function describeDuration(ms: number): string
```

**Parameters**

- `ms` (`number`): The duration in milliseconds.

**Returns** `string`

Source: [src/schedules/when.ts:195](https://github.com/Tahul/zidane/blob/main/src/schedules/when.ts#L195)

### `describeSpawnEnd`

Function.

A worker's end from its `spawn-end` marker. Reads `spawn.end`, or parses
the text of a marker recorded before it existed
(`done · 42s · $0.01 · in 3100 / 400 out`), whose facts become badges
verbatim.

```ts
function describeSpawnEnd(event: Pick<StreamEvent, 'text' | 'spawn'>): SpawnEndSummary
```

**Parameters**

- `event` (`Pick<StreamEvent, 'text' | 'spawn'>`): The spawn-end marker.

**Returns** `SpawnEndSummary`

Source: [src/chat/format.ts:93](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L93)

### `describeTime`

Function.

A time for lists: `today 09:00`, `tomorrow 09:00`, else `Mon 3 Nov 09:00`.

```ts
function describeTime(at: number, now: number, options?: DescribeTimeOptions): string
```

**Parameters**

- `at` (`number`): Epoch ms.
- `now` (`number`): Epoch ms.
- `options?` (`DescribeTimeOptions`): `seconds`: write the time to the second (`today 09:00:05`).

**Returns** `string`

Source: [src/schedules/when.ts:175](https://github.com/Tahul/zidane/blob/main/src/schedules/when.ts#L175)

### `describeTrigger`

Function.

A trigger in words, for lists: `once at 09:00 tomorrow`, `every 30 min`,
`cron 0 9 * * 1-5 (Europe/Paris)`.

```ts
function describeTrigger(
  trigger: ScheduleTrigger,
  now: number,
  options?: DescribeTimeOptions,
): string
```

**Parameters**

- `trigger` (`ScheduleTrigger`): The trigger.
- `now` (`number`): Epoch ms, to say "today" and "tomorrow".
- `options?` (`DescribeTimeOptions`): `seconds`: write the time to the second (`09:00:05`).

**Returns** `string`

Source: [src/schedules/when.ts:149](https://github.com/Tahul/zidane/blob/main/src/schedules/when.ts#L149)

### `discardThinking`

Function.

Drop one owner's streamed output for a turn: the reasoning, and the text,
of a provider attempt the loop abandoned (a stalled stream retried, a
connection that dropped mid-answer, or a move to the next model), which the
next attempt replaces and the saved turn never holds. The loop only
abandons an attempt whose turn has no other output, so nothing kept is lost.
Returns the same array when there is nothing to drop.

```ts
function discardThinking<E extends StreamEvent = StreamEvent>(
  events: E[],
  owner: string,
  turnId: string,
): E[]
```

**Type parameters**

- `E` (`extends StreamEvent`, default `StreamEvent`)

**Parameters**

- `events` (`E[]`): Transcript events in order.
- `owner` (`string`): Whose lane: `'parent'` or a subagent id.
- `turnId` (`string`): The turn whose streamed output goes. Rows without a turn id are kept.

**Returns** `E[]`

Source: [src/chat/streaming-pure.ts:277](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L277)

### `displayHostUrl`

Function.

Scheme, host, port and path of a URL (token-looking path segments redacted): what is safe to show or log.

```ts
function displayHostUrl(raw: string): string
```

**Parameters**

- `raw` (`string`): URL as entered. An invalid URL reads as `<invalid URL>`.

**Returns** `string`

Source: [src/chat/hosts/url.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/url.ts#L42)

### `displayNameFor`

Function.

Resolve the display verb for a tool. Native tools use their curated
entry from [`TOOL_DISPLAY`](https://zidane.si/docs/reference/chat-pure.md#TOOL_DISPLAY); everything else gets a sentence-case
version of the raw name (`my_host_tool` → `My host tool`) so an MCP /
host tool still reads cleanly in the transcript without shouting
Title Case at every word.

MCP convention: every tool surfaced by `mcp/connectMcpServers` is
namespaced as `mcp_<server>_<tool>` (see `src/mcp/index.ts`). The
`mcp_` prefix is plumbing — strip it before casing so the label
reads as `Github create issue` instead of `Mcp github create issue`.
The server name leads, which doubles as a free visual grouping
affordance ("everything starting with `Github` came from the github
MCP server").

```ts
function displayNameFor(name: string, input?: Record<string, unknown>): string
```

**Parameters**

- `name` (`string`): Tool name.
- `input?` (`Record<string, unknown>`): The call's input, for tools whose label depends on it.

**Returns** `string`

Source: [src/chat/tool-formatters.ts:595](https://github.com/Tahul/zidane/blob/main/src/chat/tool-formatters.ts#L595)

### `editableTurnText`

Function.

The text an edit of `turn` starts from: its text blocks one paragraph
apart, after rejoining a cited Claude reply's fragments (`mergeReplyText`),
so a cited answer edits as the one text it is and, saved unchanged through
[`replaceTurnTextBlocks`](https://zidane.si/docs/reference/chat-pure.md#replaceTurnTextBlocks), stays exactly as written.

```ts
function editableTurnText(turn: SessionTurn): string
```

**Parameters**

- `turn` (`SessionTurn`): The turn to edit.

**Returns** `string`

Source: [src/chat/turn-operations.ts:217](https://github.com/Tahul/zidane/blob/main/src/chat/turn-operations.ts#L217)

### `effectiveOnboardingMode`

Function.

The mode a run ends in: Quick start turns a full run into a quick one.

```ts
function effectiveOnboardingMode(state: OnboardingFlowState): OnboardingMode
```

**Parameters**

- `state` (`OnboardingFlowState`): The run.

**Returns** `OnboardingMode`

Source: [src/chat/onboarding/result.ts:178](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L178)

### `enabledMcpsWith`

Function.

The list with `name` turned on, or `undefined` when it already is.

```ts
function enabledMcpsWith(
  list: readonly string[] | undefined,
  name: string,
): string[] | undefined
```

**Parameters**

- `list` (`readonly string[] | undefined`): The current `enabledMcps` list, or `undefined` when every server is on.
- `name` (`string`): Server to turn on.

**Returns** `string[] | undefined`

Source: [src/chat/mcp-allowlist.ts:14](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-allowlist.ts#L14)

### `enabledMcpsWithout`

Function.

The list without `name`, or `undefined` when it isn't listed.

```ts
function enabledMcpsWithout(
  list: readonly string[] | undefined,
  name: string,
): string[] | undefined
```

**Parameters**

- `list` (`readonly string[] | undefined`): The current `enabledMcps` list, or `undefined` when every server is on.
- `name` (`string`): Server to turn off.

**Returns** `string[] | undefined`

Source: [src/chat/mcp-allowlist.ts:24](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-allowlist.ts#L24)

### `enforceSettingsInvariants`

Function.

Cross-setting invariants, applied at EVERY write: resets every toggle whose
`requires` setting is off.

Settings are a shared file with three writers (the TUI, the GUI main
process, the daemon) and no lock; a rule enforced in one client is a rule
the others break. So this is the single definition, derived from the
`requires` declarations on the toggle rows themselves — adding a
dependency is one field on one row, and the UI hint and the write-time
guarantee follow from it together.

Pure and idempotent: returns the same object when nothing changes, so React
state and file writers can short-circuit on identity.

```ts
function enforceSettingsInvariants<T extends Partial<Settings>>(
  settings: T,
): WithInvariants<T>
```

**Type parameters**

- `T` (`extends Partial<Settings>`)

**Parameters**

- `settings` (`T`): The settings to check.

**Returns** `WithInvariants<T>`

Source: [src/chat/settings-catalog.ts:319](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L319)

### `engagedKillSwitches`

Function.

The kill-switch env vars engaged in `env`, sorted. The GUI main process
hands this to its renderer (which has no `process.env`) so settings rows
can say why they are inert.

```ts
function engagedKillSwitches(env?: Env): string[]
```

**Parameters**

- `env?` (`Env`): Environment to read. Defaults to `process.env`, or an empty object when there is none.

**Returns** `string[]`

Source: [src/chat/feature-gate.ts:97](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L97)

### `entryName`

Function.

The last segment of `path`.

```ts
function entryName(path: string): string
```

**Parameters**

- `path` (`string`): A path relative to the workspace.

**Returns** `string`

Source: [src/chat/workspace/entries.ts:110](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L110)

### `entryParent`

Function.

The folder holding `path` (`''`: the root).

```ts
function entryParent(path: string): string
```

**Parameters**

- `path` (`string`): A path relative to the workspace.

**Returns** `string`

Source: [src/chat/workspace/entries.ts:100](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L100)

### `entryPath`

Function.

`path` as the rules take it (no trailing `/`), or `null` when it is not a valid entry path.

```ts
function entryPath(path: string, root?: boolean): string | null
```

**Parameters**

- `path` (`string`): A path relative to the folder.
- `root?` (`boolean`, default `false`): Whether `''` (the folder itself) is accepted.

**Returns** `string | null`

Source: [src/chat/workspace/entries.ts:79](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L79)

### `environmentLabel`

Function.

A session's environment as its header shows it: `local@laptop`, `worktree@laptop ⎇ feat`, `⎇ feat`, or the kind.

```ts
function environmentLabel(environment: { branch?: string; kind: string }): string
```

**Parameters**

- `environment` (`{ branch?: string; kind: string }`): The session environment: its kind and optional branch.

**Returns** `string`

Source: [src/chat/machines-view.ts:138](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L138)

### `escapeTemplate`

Function.

`text` as a template that renders to itself: each brace doubled. Use it for
user text inside a template (`` `${escapeTemplate(bot.name)} · {modelId}` ``).

```ts
function escapeTemplate(text: string): string
```

**Parameters**

- `text` (`string`): Literal text.

**Returns** `string`

Source: [src/chat/session-query/template.ts:56](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/template.ts#L56)

### `estimateLevelLabel`

Function.

One level's label, as the decision model reads it.

```ts
function estimateLevelLabel(minutes: number): string
```

**Parameters**

- `minutes` (`number`): The level, in minutes.

**Returns** `string`

Source: [src/chat/run-estimate.ts:41](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L41)

### `estimateReadout`

Function.

What `view` says at `now`.

```ts
function estimateReadout(view: RunEstimateTiming, now: number): EstimateReadout
```

**Parameters**

- `view` (`RunEstimateTiming`): The estimate.
- `now` (`number`): Epoch ms on the host's clock (the window's is close enough).

**Returns** `EstimateReadout`

Source: [src/chat/run-estimate.ts:276](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L276)

### `estimateViewAt`

Function.

When `view` was made: its estimate's time, or its failure's.

```ts
function estimateViewAt(view: RunEstimateView): number
```

**Parameters**

- `view` (`RunEstimateView`): An estimate view.

**Returns** `number`

Source: [src/chat/run-estimate.ts:205](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L205)

### `extensionMark`

Function.

The mark of an extension: `icon.gui` (unless it is the native catalog's
own icon and the catalog has a logo), then `brand`, then the native
catalog's `brand`, then its `icon.gui`, then the first letter or digit of the display name.

```ts
function extensionMark(input: ExtensionMarkInput): ExtensionMark
```

**Parameters**

- `input` (`ExtensionMarkInput`): The extension.

**Returns** `ExtensionMark`: What to draw.

**Example**

```ts
import { extensionMark } from 'zidane/chat/pure'

extensionMark({ id: 'linear' }) // { kind: 'brand', brand: 'linear' }
extensionMark({ id: 'linear', icon: { gui: 'i-ph-ticket' } }) // { kind: 'brand', brand: 'linear' }
extensionMark({ id: 'goal', icon: { gui: 'i-ph-flag' } }) // { kind: 'icon', gui: 'i-ph-flag' }
extensionMark({ id: 'my-tool', name: 'My tool' }) // { kind: 'letter', letter: 'M' }
```

Source: [src/chat/extension-mark.ts:46](https://github.com/Tahul/zidane/blob/main/src/chat/extension-mark.ts#L46)

### `extensionSpace`

Function.

An extension's space as a [`Space`](https://zidane.si/docs/reference/chat-pure.md#Space): read-only, its `newSession`
defaults as the space's own (agent, model, effort).

```ts
function extensionSpace(source: ExtensionSpaceSource, extensionId: string): Space
```

**Parameters**

- `source` (`ExtensionSpaceSource`): The space's wire form.
- `extensionId` (`string`): The extension contributing it.

**Returns** `Space`

Source: [src/chat/spaces.ts:163](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L163)

### `extractEditPayload`

Function.

Extracts an [`EditPayload`](https://zidane.si/docs/reference/chat.md#EditPayload) from a tool call's raw input.
Supports the `edit`, `multi_edit` and `write_file` tools. Returns `undefined` for other tools or when the input is malformed.

```ts
function extractEditPayload(
  name: string,
  input: Record<string, unknown>,
  priorContent?: string,
): EditPayload | undefined
```

**Parameters**

- `name` (`string`): Tool name.
- `input` (`Record<string, unknown>`): Raw tool input, which must carry a non-empty string `path`.
- `priorContent?` (`string`): Previous file content. `write_file` uses it as the old side of its diff.

**Returns** `EditPayload | undefined`

Source: [src/chat/edit-diff.ts:40](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L40)

### `fieldCategory`

Function.

The category a field belongs to.

```ts
function fieldCategory(field: string): SyncCategory | undefined
```

**Parameters**

- `field` (`string`): Field name such as `setting:approvalMode`.

**Returns** `SyncCategory | undefined`

Source: [src/chat/sync/types.ts:91](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L91)

### `filetypeFromPath`

Function.

Maps a file path to a tree-sitter filetype name.
Query strings and fragments are ignored, and the extension match is case-insensitive. Returns `undefined` for unknown or missing extensions.

```ts
function filetypeFromPath(path: string): string | undefined
```

**Parameters**

- `path` (`string`): File path or path-like reference.

**Returns** `string | undefined`

Source: [src/chat/edit-diff.ts:989](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L989)

### `filterLogRecords`

Function.

Retain only records at or above `minLevel`. Preserves order.

```ts
function filterLogRecords(
  records: readonly LogRecord[],
  minLevel: LogLevel,
): readonly LogRecord[]
```

**Parameters**

- `records` (`readonly LogRecord[]`): Records to filter.
- `minLevel` (`LogLevel`): Lowest level to keep.

**Returns** `readonly LogRecord[]`

Source: [src/chat/logs-view.ts:32](https://github.com/Tahul/zidane/blob/main/src/chat/logs-view.ts#L32)

### `filterModelCatalog`

Function.

Filter `catalog` by a user query. Empty / whitespace-only queries
pass every entry through (a copy of `catalog`). Multi-term
queries (space-separated) require EVERY term to appear somewhere in
the entry's search corpus — so `"claude opus"` matches `claude-opus-4`
regardless of how the words are interleaved with provider names.

Match is case-insensitive (the corpus is pre-lowercased; the query
is lowercased once per call).

Generic over the entry shape so the GUI renderer filters its flat IPC
wire rows (which carry the same main-built `searchCorpus`) with this
one implementation.

```ts
function filterModelCatalog<E extends { searchCorpus: string }>(
  catalog: readonly E[],
  query: string,
): E[]
```

**Type parameters**

- `E` (`extends { searchCorpus: string }`)

**Parameters**

- `catalog` (`readonly E[]`): Entries to filter.
- `query` (`string`): Space-separated terms. An entry matches when every term appears in its search corpus.

**Returns** `E[]`

Source: [src/chat/model-catalog.ts:175](https://github.com/Tahul/zidane/blob/main/src/chat/model-catalog.ts#L175)

### `filterRows`

Function.

The rows that match `where`, in input order. `now` is read once for the whole list.

```ts
function filterRows<R extends SessionQueryRow>(
  rows: readonly R[],
  where: SessionQuery | undefined,
  options?: QueryOptions,
): R[]
```

**Type parameters**

- `R` (`extends SessionQueryRow`)

**Parameters**

- `rows` (`readonly R[]`): The rows.
- `where` (`SessionQuery | undefined`): The query. `undefined` keeps every row.
- `options?` (`QueryOptions`, default `{}`): The clock.

**Returns** `R[]`

Source: [src/chat/session-query/compile.ts:142](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/compile.ts#L142)

### `filterSessionSearchCatalog`

Function.

`contentMatches` are keyed by `keyOf(meta)`: the bare id by default, a
(host, id) session key for a list across hosts (twins are two rows).

```ts
function filterSessionSearchCatalog(
  sessions: readonly SessionMeta[],
  query: string,
  contentMatches: ReadonlyMap<string, SessionHistoryMatch>,
  keyOf?: (meta: SessionMeta) => string,
): SessionMeta[]
```

**Parameters**

- `sessions` (`readonly SessionMeta[]`): Sessions to filter.
- `query` (`string`): Search text. A blank query returns all sessions.
- `contentMatches` (`ReadonlyMap<string, SessionHistoryMatch>`): Transcript matches, keyed by `keyOf`.
- `keyOf?` (`(meta: SessionMeta) => string`): Maps a session to its key in `contentMatches`. Defaults to the session id.

**Returns** `SessionMeta[]`: Sessions that match by title, id, or project, or by transcript, best first.

Source: [src/chat/history-search.ts:491](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L491)

### `finalizeStreamingMarkdown`

Function.

Flip any trailing streaming markdown blocks (any owner) to finalized.

```ts
function finalizeStreamingMarkdown(events: StreamEvent[]): StreamEvent[]
```

**Parameters**

- `events` (`StreamEvent[]`): Transcript events in order.

**Returns** `StreamEvent[]`

Source: [src/chat/streaming-pure.ts:287](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L287)

### `finalizeStreamingMarkdownForOwner`

Function.

Flip the trailing streaming markdown block for one specific owner.

```ts
function finalizeStreamingMarkdownForOwner(
  events: StreamEvent[],
  owner: string,
): StreamEvent[]
```

**Parameters**

- `events` (`StreamEvent[]`): Transcript events in order.
- `owner` (`string`): `parent` or the subagent's spawn id.

**Returns** `StreamEvent[]`

Source: [src/chat/streaming-pure.ts:305](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L305)

### `findActiveTrigger`

Function.

Resolve the provider trigger active at `cursor`, or `null` when none fits.

Rules:

- The trigger character must sit at position 0 of the buffer OR be
  preceded by whitespace. This prevents `http://` from triggering the
  `/`-bound skills provider mid-URL.
- The cursor must be at or past the trigger position.
- Nothing between the trigger and the cursor may be whitespace (the
  query is one contiguous token), unless a provider sets
  `allowSpacesInQuery`. A newline always closes the query.
- The query length is bounded — `maxQueryLength` defaults to 64 — so
  a runaway buffer scan can't pin the renderer.

```ts
function findActiveTrigger<TItem>(
  text: string,
  cursor: number,
  providers: readonly CompletionProvider<TItem>[],
  options?: { maxQueryLength?: number },
): ActiveTrigger<TItem> | null
```

**Type parameters**

- `TItem`

**Parameters**

- `text` (`string`): The buffer text.
- `cursor` (`number`): Cursor offset into `text`.
- `providers` (`readonly CompletionProvider<TItem>[]`): Providers whose trigger characters are checked.
- `options?` (`{ maxQueryLength?: number }`, default `{}`): Options. `maxQueryLength` bounds the query scan.

**Returns** `ActiveTrigger<TItem> | null`

Source: [src/chat/completion-core.ts:209](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L209)

### `findSpace`

Function.

One space looked up by id or name (both case-insensitive), the id match first. `undefined` for a blank query.

```ts
function findSpace(spaces: readonly Space[], query: string): Space | undefined
```

**Parameters**

- `spaces` (`readonly Space[]`): The space list.
- `query` (`string`): Space name or id.

**Returns** `Space | undefined`

Source: [src/chat/spaces.ts:481](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L481)

### `fitRunReceiptCells`

Function.

Fit cells to `width` columns for a renderer that draws them two blank
columns apart (the TUI's badge rows): returns the cells that fit whole. A
cut cell is truncated with `…`; anything after it is dropped. Never wraps.
`prefix` is the columns the renderer already spent (glyph + space).

```ts
function fitRunReceiptCells(
  cells: readonly RunReceiptCell[],
  width: number,
  prefix?: number,
): RunReceiptCell[]
```

**Parameters**

- `cells` (`readonly RunReceiptCell[]`): Cells in display order.
- `width` (`number`): Available width in characters.
- `prefix?` (`number`, default `0`): Characters already used before the first cell.

**Returns** `RunReceiptCell[]`

Source: [src/chat/run-receipt.ts:248](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L248)

### `flattenQuery`

Function.

`query` with nested `all` in `all` and `any` in `any` merged into their
parent, and a one-element `all` / `any` replaced by its element. Matches
the same rows.

```ts
function flattenQuery(query: SessionQuery): SessionQuery
```

**Parameters**

- `query` (`SessionQuery`): A query.

**Returns** `SessionQuery`

Source: [src/chat/session-query/view.ts:57](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/view.ts#L57)

### `fmtCost`

Function.

USD cost, dollar-prefixed — 2 decimals, 4 below a cent so tiny spends
stay visible (a haiku worker's $0.0007 must not render as $0.00).

```ts
function fmtCost(cost: number): string
```

**Parameters**

- `cost` (`number`): Cost in USD.

**Returns** `string`

Source: [src/chat/format.ts:148](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L148)

### `fmtTokens`

Function.

Compact token formatter — 12_415 → "12.4k", 1_234_567 → "1.23M".

```ts
function fmtTokens(n: number): string
```

**Parameters**

- `n` (`number`): Token count.

**Returns** `string`

Source: [src/chat/format.ts:22](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L22)

### `foldsInCompactShape`

Function.

Compact density: does this item fold into its exchange's one row?
Thinking, tool traffic, worker lifecycle, a `/` command's details and
everything a worker produced fold; the prompt, the assistant's prose,
errors, notices, the user's own `!` runs and session events stay.

```ts
function foldsInCompactShape(shape: FoldShape): boolean
```

**Parameters**

- `shape` (`FoldShape`): The item's kind, owner and notice.

**Returns** `boolean`

Source: [src/chat/fold-rules.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L39)

### `foldSummary`

Function.

A settled fold's header: its own calls in the shared words (`Read a file,
ran a command +2`), with the workers after them when no `spawn` call
already says so (`, 1 worker`: a script started it). Exchanges without
calls say what they did: `Delegated to a worker`, `Thought`, `Worked`.

```ts
function foldSummary(
  plan: Pick<FoldPlan<unknown>, 'stats' | 'calls'>,
  options?: { overflow?: boolean },
): string
```

**Parameters**

- `plan` (`Pick<FoldPlan<unknown>, 'stats' | 'calls'>`): The fold's plan.
- `options?` (`{ overflow?: boolean }`, default `{}`): Header options.

**Returns** `string`

Source: [src/chat/fold-rules.ts:322](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L322)

### `formatBalance`

Function.

`20.00 / 25.00`, or just the remainder when no total is reported.

```ts
function formatBalance(credits: ProviderUsageCredits): string
```

**Parameters**

- `credits` (`ProviderUsageCredits`): Credit balance to format.

**Returns** `string`

Source: [src/chat/provider-usage-format.ts:249](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L249)

### `formatBytes`

Function.

Byte counts for people: `512 B`, `1.5 KB`, `2.0 MB`.

```ts
function formatBytes(bytes: number): string
```

**Parameters**

- `bytes` (`number`): Size in bytes.

**Returns** `string`

Source: [src/format-bytes.ts:6](https://github.com/Tahul/zidane/blob/main/src/format-bytes.ts#L6)

### `formatCost`

Function.

USD: `formatCostLabel` below $10 (`$0.004`, never `$0.00`), whole dollars below $10k, then $12.3k.

```ts
function formatCost(usd: number): string
```

**Parameters**

- `usd` (`number`): An amount in US dollars.

**Returns** `string`

Source: [src/chat/usage-format.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/usage-format.ts#L23)

### `formatCostLabel`

Function.

Live cost, readable: sub-dollar runs keep a tenth of a cent (so the figure
visibly moves while a cheap run streams), then cents with grouping:
`$0.123`, `$4.56`, `$1,646.17`. `null` for nothing spent, never `$0.00`.

```ts
function formatCostLabel(usd: number): string | null
```

**Parameters**

- `usd` (`number`): Cost in USD.

**Returns** `string | null`

Source: [src/chat/format.ts:62](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L62)

### `formatCostUsd`

Function.

`$0.04`, or four decimals under a cent so a cheap run is not shown as `$0.00`. Same as `fmtCost`.

```ts
function formatCostUsd(cost: number): string
```

**Parameters**

- `cost` (`number`): Cost in USD.

**Returns** `string`

Source: [src/chat/run-receipt.ts:93](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L93)

### `formatCount`

Function.

A count at a glance: `950`, `1.2k`, `12.4k`, `120k`, `4.6M`, `1.2B`. One
decimal (a trailing `.0` dropped) below `wholeFrom` of a unit, whole
numbers from there. A value that rounds up to 1000 of a unit reads in the
next one (`999_999` → `1M`, never `1000k`).

```ts
function formatCount(n: number, wholeFrom?: number): string
```

**Parameters**

- `n` (`number`): The count.
- `wholeFrom?` (`number`, default `100`): Size, in units, from which the decimal is dropped (`10`: `9.5k`, `12k`).

**Returns** `string`

Source: [src/chat/format.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L42)

### `formatCredits`

Function.

Balances are dollars for OpenRouter and opaque units elsewhere.

```ts
function formatCredits(value: number): string
```

**Parameters**

- `value` (`number`): Credit amount. Values of 100 or more show no decimals, others show two.

**Returns** `string`

Source: [src/chat/provider-usage-format.ts:240](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L240)

### `formatDuration`

Function.

Compact human-readable duration formatter shared by background-task
surfaces (the `<task-notification>` summary, the TUI banner, the
`shell_kill` tool result, etc.).

Format ladder:

- `< 1s`   →  `"Nms"`
- `< 10s`  →  `"N.Ns"` (one decimal)
- `< 1m`   →  `"Ns"`   (whole seconds)
- `< 1h`   →  `"NmNs"` / `"Nm"` when the remaining seconds are 0
- `≥ 1h`   →  `"NhNm"` / `"Nh"` when the remaining minutes are 0

Single source of truth so a 60s task renders the same across the
model-facing XML summary and the user-facing banner. Separate
formatters would disagree (XML `"60.0s"`, banner `"1m"`), which is
confusing to a user reading both side by side.

```ts
function formatDuration(ms: number): string
```

**Parameters**

- `ms` (`number`): Duration in milliseconds. Negative values count as 0.

**Returns** `string`

Source: [src/chat/format.ts:246](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L246)

### `formatElapsed`

Function.

Run time as a person reads it: `42s`, `1m 05s`, `2h 03m`.

```ts
function formatElapsed(sec: number): string
```

**Parameters**

- `sec` (`number`): Elapsed time in whole seconds.

**Returns** `string`

Source: [src/chat/format.ts:134](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L134)

### `formatEstimate`

Function.

A remaining time as a chip says it: `~45s`, `~11m`, `~1h 20m`, `~12h`,
and `24h+` past a day (the open-ended last step: no number pretends to know).

```ts
function formatEstimate(ms: number): string
```

**Parameters**

- `ms` (`number`): Time left, in ms.

**Returns** `string`

Source: [src/chat/run-estimate.ts:292](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L292)

### `formatHour`

Function.

0-23 → "9 am" / "2 pm" / "12 pm".

```ts
function formatHour(hour: number): string
```

**Parameters**

- `hour` (`number`): A local hour, 0-23.

**Returns** `string`

Source: [src/chat/usage-format.ts:38](https://github.com/Tahul/zidane/blob/main/src/chat/usage-format.ts#L38)

### `formatLogLine`

Function.

Render a record as a single human-readable line (no trailing newline):
`<ISO timestamp> <LEVEL> <message> <attrs as kv pairs>`. Shared by the
console + file sinks, the TUI logs viewer, and the GUI Logs tab so every
surface presents a byte-identical line.

Lives here rather than in `logger.ts` because that module imports
`node:fs` for its file sink; this one function is pure and is the only part
the renderer needs.

```ts
function formatLogLine(record: LogRecord): string
```

**Parameters**

- `record` (`LogRecord`): Log record to render.

**Returns** `string`

Source: [src/chat/logs-view.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/logs-view.ts#L52)

### `formatModelSetting`

Function.

The settings string for a pick (inverse of [`parseModelSetting`](https://zidane.si/docs/reference/chat-pure.md#parseModelSetting)).

```ts
function formatModelSetting(pick: ModelSettingPick): string
```

**Parameters**

- `pick` (`ModelSettingPick`): Provider, model and optional account.

**Returns** `string`

Source: [src/chat/model-setting.ts:54](https://github.com/Tahul/zidane/blob/main/src/chat/model-setting.ts#L54)

### `formatRunDuration`

Function.

`2m18s` / `48s` / `<1s` / `1h05m`. Compact — this is a receipt, not a profiler.

```ts
function formatRunDuration(ms: number): string
```

**Parameters**

- `ms` (`number`): Duration in milliseconds.

**Returns** `string`

Source: [src/chat/run-receipt.ts:78](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L78)

### `formatRunReceiptCells`

Function.

The receipt's cells, in display order. Renderers show each as a badge, tint
it by `kind`, and truncate to their own width; the CONTENT is fixed here. `modelName` names the model as the surface's picker does.

```ts
function formatRunReceiptCells(r: RunReceipt, modelName?: ModelNamer): RunReceiptCell[]
```

**Parameters**

- `r` (`RunReceipt`): The receipt to format.
- `modelName?` (`ModelNamer`, default `nameFromModelId`): Maps a model id and provider key to a display name.

**Returns** `RunReceiptCell[]`

Source: [src/chat/run-receipt.ts:204](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L204)

### `formatRunReceiptLine`

Function.

The plain-text receipt for slots that cannot hold badges (the event's
`text`, a copy): cells comma-joined, ellipsized to `width` columns. Never
wraps.

```ts
function formatRunReceiptLine(
  r: RunReceipt,
  width?: number,
  modelName?: ModelNamer,
): string
```

**Parameters**

- `r` (`RunReceipt`): The receipt to format.
- `width?` (`number`, default `Number.POSITIVE_INFINITY`): Maximum length. Longer lines end in an ellipsis.
- `modelName?` (`ModelNamer`, default `nameFromModelId`): Maps a model id and provider key to a display name.

**Returns** `string`

Source: [src/chat/run-receipt.ts:276](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L276)

### `formatTaskStatus`

Function.

Status label for a terminated background task — `"exited <code>"`
for natural exits, `"killed"` (with the signal name when known)
for our-issued SIGTERMs.

Pulled out as its own function so the `<task-notification>` XML
summary, the TUI banner header, the `shell_kill` tool result, and
future surfaces all read the same string.

```ts
function formatTaskStatus(
  info: { exitCode: number; signal?: Signals; status: 'exited' | 'killed' },
): string
```

**Parameters**

- `info` (`{ exitCode: number; signal?: Signals; status: 'exited' | 'killed' }`): Task status, exit code, and the signal when it was killed.

**Returns** `string`

Source: [src/chat/format.ts:273](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L273)

### `formatTaskSummary`

Function.

One-line summary of a terminated background task: the model-facing
`<summary>` of the persisted `<task-notification>` XML, which replay
copies into the event's `text`. Three dot-separated segments:

`<command preview · status · duration>`

A wire format, not display copy: renderers build their badges from the
event's structured `task` (`formatTaskStatus`, `formatDuration`).

```ts
function formatTaskSummary(
  info: { command: string; durationMs: number; exitCode: number; signal?: Signals; status: 'exited' | 'killed' },
  maxCommandChars?: number,
): string
```

**Parameters**

- `info` (`{ command: string; durationMs: number; exitCode: number; signal?: Signals; status: 'exited' | 'killed' }`): Command, status, exit code, optional signal, and duration in milliseconds.
- `maxCommandChars?` (`number`, default `80`): Maximum length of the command preview. Defaults to 80.

**Returns** `string`

Source: [src/chat/format.ts:296](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L296)

### `formatTokenCount`

Function.

`1.2k` / `48k` / `1.3M` — token counts are read at a glance, not counted.

```ts
function formatTokenCount(tokens: number): string
```

**Parameters**

- `tokens` (`number`): Token count.

**Returns** `string`

Source: [src/chat/run-receipt.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L65)

### `formatTokens`

Function.

12.3k / 4.6M / 1.2B — one decimal below 100 of a unit, whole above (`formatCount`).

```ts
function formatTokens(n: number): string
```

**Parameters**

- `n` (`number`): A token count.

**Returns** `string`

Source: [src/chat/usage-format.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/usage-format.ts#L12)

### `formatTokensPerSecond`

Function.

`42 tk/s`; one decimal under 10 so a slow model is not shown as `0 tk/s`.

```ts
function formatTokensPerSecond(tps: number): string
```

**Parameters**

- `tps` (`number`): Tokens per second.

**Returns** `string`

Source: [src/chat/run-receipt.ts:161](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L161)

### `formatToolCall`

Function.

Run a tool's curated formatter and return the result, or `null` when
no formatter is registered / the input shape doesn't match. Renderer
decides what to do with `null` — typically: show `↳ <displayName>`
with no target / meta tail.

```ts
function formatToolCall(
  name: string,
  input: Record<string, unknown>,
): ToolFormatLine | null
```

**Parameters**

- `name` (`string`): Tool name.
- `input` (`Record<string, unknown>`): The call's input.

**Returns** `ToolFormatLine | null`

Source: [src/chat/tool-formatters.ts:651](https://github.com/Tahul/zidane/blob/main/src/chat/tool-formatters.ts#L651)

### `formatUsagePercent`

Function.

Percent for display: integers print bare, fractions keep one decimal (so a
status bar never reads `100%` for `99.9`).

```ts
function formatUsagePercent(usedPercent: number): string
```

**Parameters**

- `usedPercent` (`number`): Percent used, from 0 to 100.

**Returns** `string`

Source: [src/chat/provider-usage-format.ts:170](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L170)

### `freeEntryName`

Function.

The first free name for `name` in folder `dir`, compared without case (a
case-insensitive disk sees `A.ts` and `a.ts` as one).

```ts
function freeEntryName(
  port: Pick<EntryPort, 'list'>,
  dir: string,
  name: string,
  kind: EntryKind,
): Promise<string>
```

**Parameters**

- `port` (`Pick<EntryPort, 'list'>`): The folder's port.
- `dir` (`string`): Where the entry goes.
- `name` (`string`): The name it would like.
- `kind` (`EntryKind`): What it is (a file keeps its extension last).

**Returns** `Promise<string>`

Source: [src/chat/workspace/entries.ts:150](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L150)

### `fuzzyMatch`

Function.

Subsequence match of `query` in `text` with the usual bonuses: word
starts and the very beginning score higher, gaps cost, runs of adjacent
hits are rewarded, and the query found whole (as one run) beats the same
letters scattered. Returns null when not every query character appears
in order. Case-insensitive; `query` must already be lower-cased.

```ts
function fuzzyMatch(
  text: string,
  query: string,
): { indices: number[]; score: number } | null
```

**Parameters**

- `text` (`string`): Text to search in.
- `query` (`string`): Lower-cased query to look for.

**Returns** `{ indices: number[]; score: number } | null`

Source: [src/chat/palette.ts:142](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L142)

### `gatherCommandNotes`

Function.

One receipt line per exchange: every `command-note` in an exchange moves
to its end and joins into a single event (`committed 83dfea7, pushed to
origin/main`). Returns `events` itself when there is nothing to merge;
the merged event keeps its identity while its notes do not change, so
memoised rows stay put.

```ts
function gatherCommandNotes<E extends StreamEvent>(events: readonly E[]): readonly E[]
```

**Type parameters**

- `E` (`extends StreamEvent`)

**Parameters**

- `events` (`readonly E[]`): Transcript events in display order.

**Returns** `readonly E[]`

Source: [src/chat/command-notes.ts:74](https://github.com/Tahul/zidane/blob/main/src/chat/command-notes.ts#L74)

### `generateSessionTitle`

Function.

Drive the provider's `stream()` once and return a concise title for
the conversation represented by `turns`. Throws when:

- `turns` contains no text-bearing content (nothing to summarize),
- the provider stream completes with no output text,
- the model answered the transcript instead of labeling it (see
  [`cleanTitle`](https://zidane.si/docs/reference/chat.md#cleanTitle)) — a failed generation the caller retries,
- `signal` is aborted (rethrown verbatim).

Output is trimmed, single-line, with surrounding quotes / trailing
punctuation stripped, and truncated to `TITLE_MAX_CHARS`.

```ts
function generateSessionTitle(options: GenerateSessionTitleOptions): Promise<string>
```

**Parameters**

- `options` (`GenerateSessionTitleOptions`): Provider, model, turns, and optional turn window, abort signal, and word cap.

**Returns** `Promise<string>`

Source: [src/chat/generate-title.ts:155](https://github.com/Tahul/zidane/blob/main/src/chat/generate-title.ts#L155)

### `groupKeysOf`

Function.

The group keys of a value: one for a scalar, one per distinct element for
a list, none for a missing value or an empty list.

```ts
function groupKeysOf(value: unknown): string[]
```

**Parameters**

- `value` (`unknown`): A field value.

**Returns** `string[]`

Source: [src/chat/session-query/group.ts:30](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/group.ts#L30)

### `groupPaletteRows`

Function.

Sections for display. With a query the ranking already interleaves
providers, so groups follow the order of their best row. Without a
query the recents (ids in `recents`, present in `ranked`) form a
leading `Recent` section and the rest keeps provider order.

```ts
function groupPaletteRows(
  ranked: readonly RankedPaletteItem[],
  query: string,
  recents?: readonly string[],
): PaletteGroup[]
```

**Parameters**

- `ranked` (`readonly RankedPaletteItem[]`): Rows from [`rankPaletteItems`](https://zidane.si/docs/reference/chat-pure.md#rankPaletteItems).
- `query` (`string`): The query the rows were ranked for. A non-blank query disables the `Recent` section.
- `recents?` (`readonly string[]`, default `[]`): Most-recent-first item ids.

**Returns** `PaletteGroup[]`

Source: [src/chat/palette.ts:392](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L392)

### `groupRows`

Function.

Groups rows by `groupBy.field`. Rows keep their input order inside each
group, so sort first. Groups are ordered by `groupBy.order`; the group of
rows without a value (key `null`) comes last. Throws
[`SessionQueryError`](https://zidane.si/docs/reference/chat-pure.md#SessionQueryError) for an invalid grouping.

```ts
function groupRows<R extends SessionQueryRow>(
  rows: readonly R[],
  groupBy: SessionGroupBy,
  options?: GroupOptions,
): SessionGroup<R>[]
```

**Type parameters**

- `R` (`extends SessionQueryRow`)

**Parameters**

- `rows` (`readonly R[]`): The rows, already sorted.
- `groupBy` (`SessionGroupBy`): The grouping.
- `options?` (`GroupOptions`, default `{}`): Caller labels and the missing-value label.

**Returns** `SessionGroup<R>[]`

Source: [src/chat/session-query/group.ts:48](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/group.ts#L48)

### `hasAnsi`

Function.

Whether `text` holds anything [`parseAnsi`](https://zidane.si/docs/reference/chat-pure.md#parseAnsi) changes: an escape, a carriage return, a backspace.

```ts
function hasAnsi(text: string): boolean
```

**Parameters**

- `text` (`string`): Terminal output.

**Returns** `boolean`

Source: [src/chat/ansi.ts:63](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L63)

### `hasRunReceipt`

Function.

Anything to show? A run with no record data renders no line at all.

```ts
function hasRunReceipt(r: RunReceipt): boolean
```

**Parameters**

- `r` (`RunReceipt`): The receipt to test.

**Returns** `boolean`

Source: [src/chat/run-receipt.ts:290](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L290)

### `hasTool`

Function.

Whether `name` is on the host's PATH; `undefined` while unknown.

```ts
function hasTool(
  capabilities: HostCapabilities | null | undefined,
  name: string,
): boolean | undefined
```

**Parameters**

- `capabilities` (`HostCapabilities | null | undefined`): The host's capabilities, or nothing while they load.
- `name` (`string`): The tool's name, as in [`HOST_TOOLS`](https://zidane.si/docs/reference/chat-pure.md#HOST_TOOLS).

**Returns** `boolean | undefined`

Source: [src/chat/capabilities.ts:117](https://github.com/Tahul/zidane/blob/main/src/chat/capabilities.ts#L117)

### `heatmapLevel`

Function.

A value's level against [`heatmapThresholds`](https://zidane.si/docs/reference/chat-pure.md#heatmapThresholds).

```ts
function heatmapLevel(
  value: number,
  t: HeatmapThresholds,
  active?: boolean,
): HeatmapLevel
```

**Parameters**

- `value` (`number`): The day's value.
- `t` (`HeatmapThresholds`): The bounds.
- `active?` (`boolean`, default `false`): The day had activity even at a value of 0 (a message without tokens).

**Returns** `HeatmapLevel`

Source: [src/chat/heatmap-levels.ts:40](https://github.com/Tahul/zidane/blob/main/src/chat/heatmap-levels.ts#L40)

### `heatmapThresholds`

Function.

The quartile bounds of the values above 0.

```ts
function heatmapThresholds(values: Iterable<number>): HeatmapThresholds
```

**Parameters**

- `values` (`Iterable<number>`): Every day's value (zeros are ignored).

**Returns** `HeatmapThresholds`

Source: [src/chat/heatmap-levels.ts:25](https://github.com/Tahul/zidane/blob/main/src/chat/heatmap-levels.ts#L25)

### `highlightSegments`

Function.

Splits `text` into highlighted and plain runs along `ranges`.

```ts
function highlightSegments(
  text: string,
  ranges: readonly HighlightRange[],
): HighlightSegment[]
```

**Parameters**

- `text` (`string`): Text to split.
- `ranges` (`readonly HighlightRange[]`): Match ranges in `text`. Overlapping ranges are merged.

**Returns** `HighlightSegment[]`

Source: [src/chat/history-search.ts:545](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L545)

### `humanBytes`

Function.

[`formatBytes`](https://zidane.si/docs/reference/chat-pure.md#formatBytes) with whole kilobytes (`2 KB`), for short notices and attachment labels.

```ts
function humanBytes(bytes: number): string
```

**Parameters**

- `bytes` (`number`): Size in bytes.

**Returns** `string`

Source: [src/format-bytes.ts:19](https://github.com/Tahul/zidane/blob/main/src/format-bytes.ts#L19)

### `importEntries`

Function.

Brings `items` into folder `dir` through `create` (one call per entry, so
no call carries more than one file): each top-level item takes a free name,
what is inside a dropped folder keeps its own. The limits are checked
before anything is written; a failure on the way stops the import and says
what was made.

```ts
function importEntries(
  create: (path: string, kind: EntryKind, options?: EntryCreateOptions) => Promise<EntryResult>,
  dir: string,
  items: readonly EntryImportItem[],
  limits?: EntryImportLimits,
): Promise<EntryImportResult>
```

**Parameters**

- `create` (`(path: string, kind: EntryKind, options?: EntryCreateOptions) => Promise<EntryResult>`): The folder's create (local, or over a connection).
- `dir` (`string`): The folder to import into (`''`: the root).
- `items` (`readonly EntryImportItem[]`): What was dropped.
- `limits?` (`EntryImportLimits`, default `{}`): Size and count limits.

**Returns** `Promise<EntryImportResult>`

Source: [src/chat/workspace/entries.ts:316](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L316)

### `importsSomething`

Function.

Whether a selection brings anything over.

```ts
function importsSomething(selection: OnboardingImportSelection | undefined): boolean
```

**Parameters**

- `selection` (`OnboardingImportSelection | undefined`): The selection, or `undefined` when none was made.

**Returns** `boolean`

Source: [src/chat/onboarding/imports.ts:40](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/imports.ts#L40)

### `indexOfEntry`

Function.

Find a catalog entry's index by its `{providerKey, modelId}` tuple.
Returns `-1` when not present. Useful when re-rendering the picker
(a query just narrowed the list, where did the selection land?).

```ts
function indexOfEntry(
  catalog: readonly CatalogEntry[],
  target: { modelId: string; providerKey: string } | null | undefined,
): number
```

**Parameters**

- `catalog` (`readonly CatalogEntry[]`): Entries to search.
- `target` (`{ modelId: string; providerKey: string } | null | undefined`): Provider and model to find.

**Returns** `number`

Source: [src/chat/model-catalog.ts:194](https://github.com/Tahul/zidane/blob/main/src/chat/model-catalog.ts#L194)

### `indexOfProviderRow`

Function.

Index in `rows` of the header for the given provider key, or `-1`.

Collapse handlers snap the cursor up to the parent BEFORE the row list
shrinks; without that the cursor keeps its flat index and silently lands on
whichever sibling row slid into that slot.

```ts
function indexOfProviderRow(
  rows: readonly VisibleAuthRow[],
  providerKey: string,
): number
```

**Parameters**

- `rows` (`readonly VisibleAuthRow[]`): The visible rows.
- `providerKey` (`string`): Key of the provider to find.

**Returns** `number`

Source: [src/chat/auth-rows.ts:116](https://github.com/Tahul/zidane/blob/main/src/chat/auth-rows.ts#L116)

### `inferPromptRefs`

Function.

File-mention refs recovered from a prompt's text: `@<path>` at the start
or after whitespace, where the path looks like one (has a `/` or a `.`),
trailing punctuation excluded (the files completion's own rule).

Refs are known only to the client that sent the prompt, which typed the
mention through a completion. The persisted turn and the send echo other
windows receive carry the text alone, so without this a prompt's chips
existed in the sender's live transcript only: gone after a reload, never
shown in another window or the TUI. Replay and the echo fill refs from
this when the event has none, so every client paints the same prompt.
Skills and chats mentions are not inferred: their tokens (`/name`,
`#token`) are ordinary text too often to guess without the catalogs.

```ts
function inferPromptRefs(text: string): PromptSegmentRef[]
```

**Parameters**

- `text` (`string`): Prompt text to scan for `@path` mentions.

**Returns** `PromptSegmentRef[]`

Source: [src/chat/prompt-segments.ts:106](https://github.com/Tahul/zidane/blob/main/src/chat/prompt-segments.ts#L106)

### `instructionOriginBadge`

Function.

Short badge for a segment's origin — the "where does this come from" column.
`'file'` is intentionally the only one that reads like a location, since it's
the only origin the user can act on.

```ts
function instructionOriginBadge(segment: ContextSegment): string
```

**Parameters**

- `segment` (`ContextSegment`): Segment whose `origin` is labeled.

**Returns** `string`

Source: [src/chat/instruction-rows.ts:100](https://github.com/Tahul/zidane/blob/main/src/chat/instruction-rows.ts#L100)

### `instructionPreviewLines`

Function.

Split a segment's text into renderable preview lines, clamped to
[`INSTRUCTION_PREVIEW_LINE_CAP`](https://zidane.si/docs/reference/chat-pure.md#INSTRUCTION_PREVIEW_LINE_CAP).

`hidden` is how many lines were dropped off the tail, so the view can render
an honest "+N more lines" marker instead of silently truncating. Tabs are
expanded to two spaces because the terminal text renderable doesn't
interpret `\t`, and `\r` is stripped so CRLF files don't leave artefacts at
every line end.

```ts
function instructionPreviewLines(text: string): { hidden: number; lines: string[] }
```

**Parameters**

- `text` (`string`): Segment text to preview.

**Returns** `{ hidden: number; lines: string[] }`

Source: [src/chat/instruction-rows.ts:79](https://github.com/Tahul/zidane/blob/main/src/chat/instruction-rows.ts#L79)

### `isAllowedBrowserUrl`

Function.

Only http(s) pages (and the blank page) ever load in the dev browser.

```ts
function isAllowedBrowserUrl(url: string): boolean
```

**Parameters**

- `url` (`string`): URL to test.

**Returns** `boolean`

Source: [src/chat/browser/url.ts:41](https://github.com/Tahul/zidane/blob/main/src/chat/browser/url.ts#L41)

### `isCacheNotice`

Function.

Whether a notice is one `showCacheNotices` hides: a prompt-cache break or
expiry, or dropped reasoning (the same prefix churn, seen from the thinking side).

```ts
function isCacheNotice(
  notice: { label: string; severity: 'error' | 'info' | 'warn' } | undefined,
): boolean
```

**Parameters**

- `notice` (`{ label: string; severity: 'error' | 'info' | 'warn' } | undefined`): The event's notice, if any.

**Returns** `boolean`

Source: [src/chat/turn-selection.ts:279](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L279)

### `isEditErrorResult`

Function.

Recognize a tool-result body as carrying NON-success information so the
renderer doesn't suppress it under `showEditDiffs`. Categories:

- `edit` → "Edit error: …"
- `write_file` permission errors wrapped by the loop → "Tool failed: …"
- `multi_edit` → single-line error `multi_edit error: …`, OR
  a result carrying an `<edit-outcomes>…</edit-outcomes>` annotation
  block. The host only appends the annotation when at least one hunk
  was NOT applied, so its mere presence is the signal — the result
  body needs to stay visible next to the diff so the user can read
  denial / skip / failure reasons longer than the per-hunk badge.
- Fully-denied gate emit (`[fully denied] <edit-outcomes>…`) likewise
  stays visible.

Exported for unit-testability of the visibility matrix.

```ts
function isEditErrorResult(text: string): boolean
```

**Parameters**

- `text` (`string`): Text of an edit tool result.

**Returns** `boolean`

Source: [src/chat/turn-selection.ts:60](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L60)

### `isExistingInstall`

Function.

Whether the install existed before the wizard: it has stored settings,
credentials, sessions or a last-used provider.

```ts
function isExistingInstall(signals: OnboardingInstallSignals): boolean
```

**Parameters**

- `signals` (`OnboardingInstallSignals`): What the app read from this machine.

**Returns** `boolean`

Source: [src/chat/onboarding/result.ts:74](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L74)

### `isExpandableProvider`

Function.

A provider earns a chevron only when there is a real choice to reveal.

```ts
function isExpandableProvider(provider: ProviderAuth): boolean
```

**Parameters**

- `provider` (`ProviderAuth`): The provider to test.

**Returns** `boolean`

Source: [src/chat/auth-rows.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/auth-rows.ts#L52)

### `isExtensionSpaceId`

Function.

Whether `spaceId` names an extension space (`<extension>/<id>`).

```ts
function isExtensionSpaceId(spaceId: string | null | undefined): boolean
```

**Parameters**

- `spaceId` (`string | null | undefined`): A space id.

**Returns** `boolean`

Source: [src/chat/spaces.ts:184](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L184)

### `isFenceClose`

Function.

`line` closes the fence opened with `fenceChar` × `fenceLen`: the same
character, at least as many, and nothing but spaces after (an info string
makes it a line of code, as in CommonMark).

```ts
function isFenceClose(line: string, fenceChar: string, fenceLen: number): boolean
```

**Parameters**

- `line` (`string`): One line inside the fence.
- `fenceChar` (`string`): The opener's marker character.
- `fenceLen` (`number`): The opener's marker length.

**Returns** `boolean`

Source: [src/chat/markdown-segments.ts:428](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L428)

### `isKillSwitchEngaged`

Function.

`name` is set to `'1'` in `env`: the kill-switch test, for a row that only knows the variable.

```ts
function isKillSwitchEngaged(name: string, env?: Env): boolean
```

**Parameters**

- `name` (`string`): Kill-switch env var name.
- `env?` (`Env`): Environment to read. Defaults to `process.env`, or an empty object when there is none.

**Returns** `boolean`

Source: [src/chat/feature-gate.ts:124](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L124)

### `isLocalBrowserUrl`

Function.

A loopback address: the dev servers the browser exists for.

```ts
function isLocalBrowserUrl(url: string): boolean
```

**Parameters**

- `url` (`string`): URL to test.

**Returns** `boolean`

Source: [src/chat/browser/url.ts:58](https://github.com/Tahul/zidane/blob/main/src/chat/browser/url.ts#L58)

### `isMainSession`

Function.

Type guard over untrusted metadata.

```ts
function isMainSession(metadata: Readonly<Record<string, unknown>> | undefined): boolean
```

**Parameters**

- `metadata` (`Readonly<Record<string, unknown>> | undefined`): Session metadata to inspect.

**Returns** `boolean`

Source: [src/chat/orchestration.ts:161](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L161)

### `isMethodNotFound`

Function.

The host predates the method (`models.list`, `catalog.*`, …): callers degrade, never fail.

```ts
function isMethodNotFound(err: unknown): boolean
```

**Parameters**

- `err` (`unknown`): Error from a host call.

**Returns** `boolean`

Source: [src/chat/hosts/connection.ts:48](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/connection.ts#L48)

### `isMouseTracking`

Function.

Whether the program asked for mouse reports.

```ts
function isMouseTracking(state: ModeState): boolean
```

**Parameters**

- `state` (`ModeState`): The modes to check.

**Returns** `boolean`

Source: [src/contexts/terminal-modes.ts:117](https://github.com/Tahul/zidane/blob/main/src/contexts/terminal-modes.ts#L117)

### `isolationLabel`

Function.

The isolation a kind gives, named without its machine (the picker names the
place apart): `In the folder` for local kinds, `New worktree` for worktree
kinds, else the kind's own label.

```ts
function isolationLabel(descriptor: { kind: string; label: string }): string
```

**Parameters**

- `descriptor` (`{ kind: string; label: string }`): Environment kind descriptor: its kind and label.

**Returns** `string`

Source: [src/chat/machines-view.ts:112](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L112)

### `isPaletteContext`

Function.

Type guard hosts use before forwarding a payload from an untrusted provider.

```ts
function isPaletteContext(v: unknown): v is PaletteContext
```

**Parameters**

- `v` (`unknown`): Value to test.

**Returns** `v is PaletteContext`

Source: [src/chat/palette.ts:539](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L539)

### `isRelativeTime`

Function.

Whether `value` is a relative time: `'now'`, or a sign, a count and a unit
(`s`, `m`, `h`, `d`, `w`), such as `'-7d'`.

```ts
function isRelativeTime(value: unknown): value is string
```

**Parameters**

- `value` (`unknown`): Any value.

**Returns** `value is string`

Source: [src/chat/session-query/time.ts:18](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/time.ts#L18)

### `isRunEstimated`

Function.

Whether `view` has a timing to count down (not a problem).

```ts
function isRunEstimated(view: RunEstimateView): view is RunEstimateTiming
```

**Parameters**

- `view` (`RunEstimateView`): An estimate view.

**Returns** `view is RunEstimateTiming`

Source: [src/chat/run-estimate.ts:196](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L196)

### `isSecretAnswer`

Function.

Whether `value` is a [`SecretAnswer`](https://zidane.si/docs/reference/chat-pure.md#SecretAnswer): a value or a decline sent by a client.

```ts
function isSecretAnswer(value: unknown): value is SecretAnswer
```

**Parameters**

- `value` (`unknown`): Any value.

**Returns** `value is SecretAnswer`

Source: [src/chat/secrets/protocol.ts:113](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L113)

### `isSecretName`

Function.

Whether `name` is a valid secret name ([`SECRET_NAME_PATTERN`](https://zidane.si/docs/reference/chat-pure.md#SECRET_NAME_PATTERN)).

```ts
function isSecretName(name: unknown): name is string
```

**Parameters**

- `name` (`unknown`): Any value.

**Returns** `name is string`

Source: [src/chat/secrets/protocol.ts:62](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L62)

### `isSecretReference`

Function.

Whether `value` is a [`SecretReference`](https://zidane.si/docs/reference/chat-pure.md#SecretReference).

```ts
function isSecretReference(value: unknown): value is SecretReference
```

**Parameters**

- `value` (`unknown`): Any value.

**Returns** `value is SecretReference`

Source: [src/chat/secrets/protocol.ts:125](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L125)

### `isSecretTtl`

Function.

Whether `value` is a [`SecretTtl`](https://zidane.si/docs/reference/chat-pure.md#SecretTtl).

```ts
function isSecretTtl(value: unknown): value is SecretTtl
```

**Parameters**

- `value` (`unknown`): Any value.

**Returns** `value is SecretTtl`

Source: [src/chat/secrets/protocol.ts:50](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L50)

### `isShellFence`

Function.

Whether a fence of `language` runs.

```ts
function isShellFence(language: string | undefined): boolean
```

**Parameters**

- `language` (`string | undefined`): The fence's language, as written.

**Returns** `boolean`

Source: [src/chat/shell-blocks.ts:54](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L54)

### `isTurnHighlighted`

Function.

Render-time check: should `event` paint with the selection accent?

`true` when the event's own turn is selected, OR when the selected turn
`owns` the event's turn via [`turnSelectionOwnership`](https://zidane.si/docs/reference/chat-pure.md#turnSelectionOwnership) (the call and
its tool-result rows highlight together), OR when the event's turn owns the
selected turn (a result-only turn selected highlights its call). `false` when nothing is
selected or the relationship doesn't apply.

Pure. Renderer-agnostic — the TUI's `<Transcript>` uses it; a GUI's
equivalent walks the same rule.

```ts
function isTurnHighlighted(
  event: Pick<StreamEvent, 'turnId'>,
  selectedTurnId: string | null,
  ownership: ReadonlyMap<string, string>,
): boolean
```

**Parameters**

- `event` (`Pick<StreamEvent, 'turnId'>`): The event being rendered.
- `selectedTurnId` (`string | null`): The selected turn id, or `null` when nothing is selected.
- `ownership` (`ReadonlyMap<string, string>`): Map from an owned turn id to its owner, from [`turnSelectionOwnership`](https://zidane.si/docs/reference/chat-pure.md#turnSelectionOwnership).

**Returns** `boolean`

Source: [src/chat/turn-selection.ts:443](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L443)

### `isUserBashEvent`

Function.

Is this event a user-initiated `!` bash exchange (vs. a model-driven shell call)?

```ts
function isUserBashEvent(event: Pick<StreamEvent, 'tool' | 'callId'>): boolean
```

**Parameters**

- `event` (`Pick<StreamEvent, 'tool' | 'callId'>`): The event to test.

**Returns** `boolean`

Source: [src/chat/turn-selection.ts:93](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L93)

### `isValidMachineName`

Function.

A machine name: one path-safe segment, so `local@<name>` is unambiguous.

```ts
function isValidMachineName(name: string): boolean
```

**Parameters**

- `name` (`string`): Candidate machine name.

**Returns** `boolean`

Source: [src/chat/machine-protocol.ts:309](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L309)

### `isVisible`

Function.

Whether `event` shows in the transcript under the user's toggles, including
`hideSubagentOutput`, `showEditDiffs`, `showThinking` and `showToolResults`.
When subagent output is hidden:

- Child-agent events are filtered down to the `spawn-start` /
  `spawn-end` markers so the user still sees "🌱 working… 🌳 done".
- The parent's `tool-result` for `spawn` is hidden too. Its body
  duplicates `spawn-end`'s stats line *and* the parent's next
  markdown turn; showing it again produces an extra
  `┃ [sub-agent child-1] Completed …` block users just want gone.

Renderer-agnostic — returns plain `boolean` so TUI / GUI consumers
can filter events identically.

```ts
function isVisible(event: StreamEvent, settings: Settings): boolean
```

**Parameters**

- `event` (`StreamEvent`): The event to test.
- `settings` (`Settings`): The user's transcript settings.

**Returns** `boolean`

Source: [src/chat/turn-selection.ts:300](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L300)

### `joinEntry`

Function.

`name` in folder `dir`.

```ts
function joinEntry(dir: string, name: string): string
```

**Parameters**

- `dir` (`string`): The folder (`''`: the root).
- `name` (`string`): The entry's name.

**Returns** `string`

Source: [src/chat/workspace/entries.ts:120](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L120)

### `joinFewNames`

Function.

Up to two names, then a count: "A and B", "A, B and 3 more".

```ts
function joinFewNames(list: readonly string[]): string
```

**Parameters**

- `list` (`readonly string[]`): The names.

**Returns** `string`

Source: [src/chat/onboarding/words.ts:48](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L48)

### `joinNames`

Function.

A list of names as a sentence reads it: "A", "A and B", "A, B and C".

```ts
function joinNames(list: readonly string[]): string
```

**Parameters**

- `list` (`readonly string[]`): The names.

**Returns** `string`

**Example**

```ts
import { joinNames } from 'zidane/chat/pure'

joinNames(['GitHub', 'Linear', 'Sentry']) // 'GitHub, Linear and Sentry'
```

Source: [src/chat/onboarding/words.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L39)

### `lastSeenText`

Function.

"seen 5 min ago" for a machine's `lastSeen`.

```ts
function lastSeenText(lastSeen: number | undefined, now: number): string
```

**Parameters**

- `lastSeen` (`number | undefined`): Epoch milliseconds the machine was last seen, or `undefined` if never.
- `now` (`number`): Epoch milliseconds to measure from.

**Returns** `string`

Source: [src/chat/machines-view.ts:162](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L162)

### `lentServerMachines`

Function.

The machine names of the saved servers a local host uses as machines
(`machines.links.status` `uses`): pickers list those servers once, as
servers, not again as `local@<server>`.

```ts
function lentServerMachines(
  links: { uses: readonly { machineName?: string }[] } | null | undefined,
): Set<string>
```

**Parameters**

- `links` (`{ uses: readonly { machineName?: string }[] } | null | undefined`): The local host's links, or nothing when it can't say.

**Returns** `Set<string>`

Source: [src/chat/machines-view.ts:129](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L129)

### `liveSessionCost`

Function.

Session cost while a turn streams: settled figure plus the running estimate
for the in-flight turn. `estimated` tells the surface to render it dimmed
(the number will move, then snap to the settled value at turn end). `null`
when there is nothing to show — never `$0.00`.

```ts
function liveSessionCost(
  settledUsd: number,
  progress: { estCostUsd?: number } | null | undefined,
): { estimated: boolean; usd: number } | null
```

**Parameters**

- `settledUsd` (`number`): Cost of settled turns in USD.
- `progress` (`{ estCostUsd?: number } | null | undefined`): Streaming progress carrying the running cost estimate for the in-flight turn, if any.

**Returns** `{ estimated: boolean; usd: number } | null`

Source: [src/chat/footer-chips.ts:167](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L167)

### `localTimeZone`

Function.

The IANA time zone of this process (`UTC` when it has none).

```ts
function localTimeZone(): string
```

**Returns** `string`

Source: [src/schedules/when.ts:28](https://github.com/Tahul/zidane/blob/main/src/schedules/when.ts#L28)

### `longDayLabel`

Function.

"Monday, Oct 26" for a `YYYY-MM-DD` day.

```ts
function longDayLabel(day: string): string
```

**Parameters**

- `day` (`string`): A local `YYYY-MM-DD`.

**Returns** `string`

Source: [src/chat/usage-format.ts:99](https://github.com/Tahul/zidane/blob/main/src/chat/usage-format.ts#L99)

### `machineBlockedReason`

Function.

Why a machine kind can't be picked now (its machine is offline), else `undefined`.

```ts
function machineBlockedReason(
  descriptor: { machine?: { name: string; status: 'online' | 'offline' } },
): string | undefined
```

**Parameters**

- `descriptor` (`{ machine?: { name: string; status: 'online' | 'offline' } }`): Environment kind descriptor with its machine and the machine's status.

**Returns** `string | undefined`

Source: [src/chat/machines-view.ts:101](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L101)

### `machineDirListing`

Function.

`machines.listDirs` as a folder listing: the parent stops at the root the folder is in.

```ts
function machineDirListing(
  result: { dirs: string[]; path: string; roots: string[] },
): MachineDirListing
```

**Parameters**

- `result` (`{ dirs: string[]; path: string; roots: string[] }`): Directory names, the listed path and the allowed roots from `machines.listDirs`.

**Returns** `MachineDirListing`

Source: [src/chat/machines-view.ts:69](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L69)

### `machineKind`

Function.

A machine-qualified environment kind: `<base>@<machine name>`.

```ts
function machineKind(base: 'worktree' | 'local', name: string): string
```

**Parameters**

- `base` (`'worktree' | 'local'`): Base environment kind.
- `name` (`string`): Machine name.

**Returns** `string`

Source: [src/chat/machine-protocol.ts:290](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L290)

### `machineSetupCommand`

Function.

The command a machine runs to join a main server with a join string (`formatJoinString`).

```ts
function machineSetupCommand(join: string): string
```

**Parameters**

- `join` (`string`): `<server url>#<join code>`.

**Returns** `string`

Source: [src/chat/machines-view.ts:226](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L226)

### `machineVersionDiffers`

Function.

Whether a machine runs another zidane version than its main server. `false` when either is unknown.

```ts
function machineVersionDiffers(
  version: string | undefined,
  serverVersion: string | undefined,
): boolean
```

**Parameters**

- `version` (`string | undefined`): The machine's version.
- `serverVersion` (`string | undefined`): The main server's version.

**Returns** `boolean`

Source: [src/chat/machines-view.ts:217](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L217)

### `machineWaiting`

Function.

The machine a session's run is paused on, from its notices (`waiting for
laptop…` until `laptop is back.` or `laptop stayed offline … run stopped`),
`null` when none. `online`: machines known to be back since (a
`machine:status` the window saw), which clear the wait at once.

```ts
function machineWaiting(
  events: readonly { notice?: { label?: string }; text?: string }[],
  online?: ReadonlySet<string>,
): string | null
```

**Parameters**

- `events` (`readonly { notice?: { label?: string }; text?: string }[]`): A session's events, oldest first.
- `online?` (`ReadonlySet<string>`): Machine names known to be back online.

**Returns** `string | null`

Source: [src/chat/machines-view.ts:27](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L27)

### `maskScriptSource`

Function.

`code` with the text of strings, comments and regular expressions replaced
by spaces (newlines kept), so a scan sees only code. Template literals keep
their `${…}` expressions.

```ts
function maskScriptSource(code: string): string
```

**Parameters**

- `code` (`string`): The script, as the model wrote it.

**Returns** `string`

Source: [src/chat/script-progress.ts:471](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L471)

### `mayHaveStreamFailure`

Function.

Cheap pre-check before splitting: the text may end in a stop marker.

```ts
function mayHaveStreamFailure(text: string): boolean
```

**Parameters**

- `text` (`string`): Assistant message text.

**Returns** `boolean`

Source: [src/chat/stream-failure.ts:48](https://github.com/Tahul/zidane/blob/main/src/chat/stream-failure.ts#L48)

### `mediaTypeOfPath`

Function.

The media a path names, by its extension; `null` for everything else.

```ts
function mediaTypeOfPath(path: string): MediaType | null
```

**Parameters**

- `path` (`string`): A file path.

**Returns** `MediaType | null`

Source: [src/chat/workspace/media-type.ts:46](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/media-type.ts#L46)

### `mergeOnboardingState`

Function.

Stored records with new ones merged in. A finished run (any record) clears
the in-progress marker.

```ts
function mergeOnboardingState(
  stored: OnboardingState | undefined,
  records: OnboardingState,
): OnboardingState
```

**Parameters**

- `stored` (`OnboardingState | undefined`): The records in the state file now.
- `records` (`OnboardingState`): The records to add, such as `OnboardingResult.records` or an `inProgress` marker.

**Returns** `OnboardingState`

Source: [src/chat/onboarding/result.ts:166](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L166)

### `mergePresenceMaps`

Function.

`base` with every other host's rows laid over it, by session id.

```ts
function mergePresenceMaps<Row extends { sessionId: string }>(
  base: ReadonlyMap<string, Row>,
  others: Iterable<readonly Row[]>,
): ReadonlyMap<string, Row>
```

**Type parameters**

- `Row` (`extends { sessionId: string }`)

**Parameters**

- `base` (`ReadonlyMap<string, Row>`): Presence rows keyed by session id.
- `others` (`Iterable<readonly Row[]>`): Rows from other hosts. They replace `base` rows with the same session id.

**Returns** `ReadonlyMap<string, Row>`

Source: [src/chat/hosts/presence.ts:45](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/presence.ts#L45)

### `mergeReferences`

Function.

Merge reference lists from multiple providers into one ordered list with
earlier-start-wins disambiguation when spans overlap. Ties broken by
insertion order. Spans are sorted ascending so renderers can walk them
sequentially with a cursor through the source string.

```ts
function mergeReferences<TItem>(
  refs: readonly CompletionReference<TItem>[],
): CompletionReference<TItem>[]
```

**Type parameters**

- `TItem`

**Parameters**

- `refs` (`readonly CompletionReference<TItem>[]`): References gathered from one or more providers.

**Returns** `CompletionReference<TItem>[]`

Source: [src/chat/completion-core.ts:342](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L342)

### `mergeSuggestions`

Function.

Flatten several providers' suggestion lists into one, stamping
`providerId` on every item (for provider-aware row styling) and
defaulting `section` to the producing provider's `label` so the popover
can render group headers.

`section` is stamped only when the TRIGGER hosts ≥2 providers (see
`groupCount`), not when ≥2 happen to return items — so a query that
filters a shared trigger (`/`) down to one group still shows that
group's header, while a genuinely single-provider trigger (`@` files)
renders flat (the header would just duplicate the popup's border
title). Items that already carry a value keep it.

```ts
function mergeSuggestions<TItem>(
  groups: readonly { items: readonly CompletionItem<TItem>[]; provider: CompletionProvider<TItem> }[],
  groupCount?: number,
): CompletionItem<TItem>[]
```

**Type parameters**

- `TItem`

**Parameters**

- `groups` (`readonly { items: readonly CompletionItem<TItem>[]; provider: CompletionProvider<TItem> }[]`): Provider and item pairs, in display order.
- `groupCount?` (`number`, default `groups.length`): Number of groups used to decide whether items are sectioned. Sections are added only when it is above 1.

**Returns** `CompletionItem<TItem>[]`

Source: [src/chat/completion-core.ts:301](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L301)

### `mergeTargetIndex`

Function.

Index of the event `owner`'s next delta may coalesce into, or `-1` when the
owner has no open lane at the tail.

Walks backwards over events owned by OTHER subagents — concurrent siblings
whose rows carry no ordering relation to this owner's output, and which a
per-owner drain interleaves at \~60Hz — and stops at the first event that is
either this owner's or a real ordering boundary (parent output, user
prompts, banners). The caller decides whether the event found is mergeable
for its kind. A tail-only check splits every concurrent child's message
into fragments braided with its siblings'.

```ts
function mergeTargetIndex(events: readonly StreamEvent[], owner: string): number
```

**Parameters**

- `events` (`readonly StreamEvent[]`): Transcript events in order.
- `owner` (`string`): `parent` or the subagent's spawn id.

**Returns** `number`

Source: [src/chat/streaming-pure.ts:46](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L46)

### `messagePreview`

Function.

A message as a person skims it: its words, markdown syntax and code
blocks dropped, whitespace folded. For the compact stacks of earlier
messages.

```ts
function messagePreview(text: string): string
```

**Parameters**

- `text` (`string`): Message text, usually markdown.

**Returns** `string`

Source: [src/chat/fold-actions.ts:473](https://github.com/Tahul/zidane/blob/main/src/chat/fold-actions.ts#L473)

### `messageSelectionOwnership`

Function.

Ownership for "one selection stop per message": result-only turns fold
into their assistant turn (`turnSelectionOwnership`), and turns that only
did work (thinking, tool calls, worker markers) fold into the answer that
follows them in the same exchange. "Read three files, then answered" is
one stop, so ↑ moves one visible message at a time. An exchange that ends
in work alone stops on its first work turn. Same rule as the GUI's
`computeSelectStops`.

```ts
function messageSelectionOwnership(events: readonly StreamEvent[]): Map<string, string>
```

**Parameters**

- `events` (`readonly StreamEvent[]`): Transcript events in order.

**Returns** `Map<string, string>`

Source: [src/chat/turn-selection.ts:467](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L467)

### `migratedOnboardingRecords`

Function.

The records an install that predates the wizard gets, so it never opens on its own.

```ts
function migratedOnboardingRecords(
  surface: OnboardingSurface,
  now?: Date,
): OnboardingState
```

**Parameters**

- `surface` (`OnboardingSurface`): The app that noticed.
- `now?` (`Date`): When.

**Returns** `OnboardingState`

Source: [src/chat/onboarding/result.ts:154](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L154)

### `modelConcern`

Function.

Why the decision model handed a call to the user, for the approval card.

```ts
function modelConcern(approval: ModelApproval): string
```

**Parameters**

- `approval` (`ModelApproval`): The model's verdict on the escalated call.

**Returns** `string`

Source: [src/chat/model-approval.ts:63](https://github.com/Tahul/zidane/blob/main/src/chat/model-approval.ts#L63)

### `modelDisplayName`

Function.

Builds the picker name for a model: the catalog name when given, else the id made readable, with a vendor prefix split off and the provider's own brand word removed.

```ts
function modelDisplayName(input: ModelNameInput): ModelDisplayName
```

**Parameters**

- `input` (`ModelNameInput`): Provider key, model id and optional catalog name.

**Returns** `ModelDisplayName`

Source: [src/chat/model-name.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/model-name.ts#L65)

### `modelPickKey`

Function.

Identity of a model pick on any shape: the same model on two accounts of a
provider is two picks. The one key every picker and chain edit compares by.

```ts
function modelPickKey(provider: string, model: string, account?: string): string
```

**Parameters**

- `provider` (`string`): Provider key.
- `model` (`string`): Model id.
- `account?` (`string`): Optional account. Omitted accounts produce a two-part key.

**Returns** `string`

Source: [src/chat/model-chain.ts:47](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L47)

### `modePrefix`

Function.

Sequences that put a fresh terminal in `state`'s modes.

```ts
function modePrefix(state: ModeState): string
```

**Parameters**

- `state` (`ModeState`): The modes to restore.

**Returns** `string`

Source: [src/contexts/terminal-modes.ts:90](https://github.com/Tahul/zidane/blob/main/src/contexts/terminal-modes.ts#L90)

### `modePrefixLength`

Function.

Length of the mode sequences `text` starts with: at least the
[`modePrefix`](https://zidane.si/docs/reference/chat-pure.md#modePrefix) put in front of a snapshot. Output that itself starts
with mode sequences counts too, so this errs towards less output, never more.

```ts
function modePrefixLength(text: string): number
```

**Parameters**

- `text` (`string`): A replay that may start with a mode prefix.

**Returns** `number`

Source: [src/contexts/terminal-modes.ts:108](https://github.com/Tahul/zidane/blob/main/src/contexts/terminal-modes.ts#L108)

### `mostConstrainedWindow`

Function.

The window closest to its ceiling, which is the one that will bite first and
the only one a single-line indicator has room for. `null` when the snapshot
carries no windows.

```ts
function mostConstrainedWindow(
  snapshot: ProviderUsageSnapshot,
): ProviderUsageWindow | null
```

**Parameters**

- `snapshot` (`ProviderUsageSnapshot`): The snapshot to inspect.

**Returns** `ProviderUsageWindow | null`

Source: [src/chat/provider-usage-format.ts:155](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L155)

### `moveTab`

Function.

Move one visible tab `delta` slots within the visible strip (keyboard
reorder), clamped at the ends. Hidden pinned ids keep their slots.

```ts
function moveTab(
  pinned: readonly string[],
  visible: readonly string[],
  id: string,
  delta: number,
): readonly string[]
```

**Parameters**

- `pinned` (`readonly string[]`): The host's pinned tab ids in order.
- `visible` (`readonly string[]`): Ids of the tabs currently shown, in display order.
- `id` (`string`): Id of the tab to move.
- `delta` (`number`): Positions to move by. Negative moves earlier. Clamped to the visible range.

**Returns** `readonly string[]`

Source: [src/chat/panels.ts:211](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L211)

### `nativeExtensionByName`

Function.

A native extension by name, or `undefined`.

```ts
function nativeExtensionByName(name: string): NativeExtensionEntry | undefined
```

**Parameters**

- `name` (`string`): The extension name.

**Returns** `NativeExtensionEntry | undefined`

Source: [src/chat/onboarding/native-extensions.ts:99](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/native-extensions.ts#L99)

### `nativeExtensionEntry`

Function.

The listing row of a native extension, from the catalog shipped in the app.

```ts
function nativeExtensionEntry(
  entry: NativeExtensionEntry,
  source: string,
): ExtensionSourceEntry
```

**Parameters**

- `entry` (`NativeExtensionEntry`): The catalog entry.
- `source` (`string`): The spec that installs from the repository (`defaultExtensionSource`).

**Returns** `ExtensionSourceEntry`

Source: [src/chat/extension-sources.ts:115](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L115)

### `nativeExtensionListing`

Function.

The native extensions as a listing of the default source pinned to
`version`, built from the catalog shipped in the app (`NATIVE_EXTENSIONS`):
what an app shows when the repository cannot be read. No network.

```ts
function nativeExtensionListing(version: string): ExtensionSourceListing
```

**Parameters**

- `version` (`string`): The running zidane version.

**Returns** `ExtensionSourceListing`: A listing with `builtin: true` and no error.

Source: [src/chat/extension-sources.ts:136](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L136)

### `nativeExtensionNeedText`

Function.

What a native extension needs, in words: "gh (optional)", "the Linear connector".

```ts
function nativeExtensionNeedText(
  need: NativeExtensionNeed,
  words?: NativeExtensionNeedWords,
): string
```

**Parameters**

- `need` (`NativeExtensionNeed`): The need.
- `words?` (`NativeExtensionNeedWords`, default `ONBOARDING_WORDS`): The words to use. Defaults to [`ONBOARDING_WORDS`](https://zidane.si/docs/reference/chat-pure.md#ONBOARDING_WORDS).

**Returns** `string`

Source: [src/chat/onboarding/words.ts:137](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L137)

### `nativeExtensionSource`

Function.

The install source of a native extension, pinned to a release tag:
`Tahul/zidane#v<version>:extensions/<name>`, the grammar
`installExtensionFromSpec` takes.

```ts
function nativeExtensionSource(entry: NativeExtensionEntry, version: string): string
```

**Parameters**

- `entry` (`NativeExtensionEntry`): The extension.
- `version` (`string`): The running zidane version (`ZIDANE_VERSION`), without the `v`.

**Returns** `string`

**Example**

```ts
import { nativeExtensionByName, nativeExtensionSource } from 'zidane/chat/pure'

nativeExtensionSource(nativeExtensionByName('goal')!, '8.1.0')
// 'Tahul/zidane#v8.1.0:extensions/goal'
```

Source: [src/chat/onboarding/native-extensions.ts:118](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/native-extensions.ts#L118)

### `needsOnboarding`

Function.

What an app does at launch about the wizard (`docs/ONBOARDING.md`, When it opens).

```ts
function needsOnboarding(input: OnboardingGateInput): OnboardingGate
```

**Parameters**

- `input` (`OnboardingGateInput`): The records, the machine's signals and the app.

**Returns** `OnboardingGate`

**Example**

```ts
import { needsOnboarding } from 'zidane/chat/pure'

const signals = { storedSettings: false, credentials: false, sessions: false, lastProvider: false, surfaceFirstRun: true }
needsOnboarding({ state: undefined, signals, surface: 'tui' }) // { kind: 'run', mode: 'full' }
```

Source: [src/chat/onboarding/result.ts:102](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L102)

### `nestedCallShown`

Function.

Whether a script's nested call shows in the transcript: a call that runs a
subagent (its worker attaches to it), a plan or a question, or any call
with `codemodeShowCalls` on. Every surface (the host's live rows, `isVisible`,
the kit's rows) applies this one rule.

```ts
function nestedCallShown(
  call: { runsNestedAgent?: boolean; tool?: string },
  codemodeShowCalls: boolean,
): boolean
```

**Parameters**

- `call` (`{ runsNestedAgent?: boolean; tool?: string }`): The nested call.
- `codemodeShowCalls` (`boolean`): The user's `codemodeShowCalls` setting.

**Returns** `boolean`

Source: [src/chat/nested-call-events.ts:44](https://github.com/Tahul/zidane/blob/main/src/chat/nested-call-events.ts#L44)

### `nestedRecordEvents`

Function.

A persisted record as the events the live run emitted for it.

```ts
function nestedRecordEvents(
  records: readonly NestedToolCallRecord[],
  parentToolCallId: string,
  tag?: NestedEventTag,
): StreamEvent[]
```

**Parameters**

- `records` (`readonly NestedToolCallRecord[]`): Nested calls stored on the calling tool's result.
- `parentToolCallId` (`string`): Id of the calling tool.
- `tag?` (`NestedEventTag`): Turn, subagent and depth to stamp on the events.

**Returns** `StreamEvent[]`

Source: [src/chat/nested-call-events.ts:126](https://github.com/Tahul/zidane/blob/main/src/chat/nested-call-events.ts#L126)

### `nestedResultEvent`

Function.

The `tool-result` row for a nested call as it ends; the output is cut to a preview.

```ts
function nestedResultEvent(
  result: { callId: string; durationMs?: number; isError: boolean; name: string; output: string; parentToolCallId: string; runsNestedAgent?: boolean },
  tag?: NestedEventTag,
): StreamEvent
```

**Parameters**

- `result` (`{ callId: string; durationMs?: number; isError: boolean; name: string; output: string; parentToolCallId: string; runsNestedAgent?: boolean }`): The nested call's result.
- `tag?` (`NestedEventTag`): Turn, subagent and depth to stamp on the event.

**Returns** `StreamEvent`

Source: [src/chat/nested-call-events.ts:105](https://github.com/Tahul/zidane/blob/main/src/chat/nested-call-events.ts#L105)

### `nestedToolEvent`

Function.

The `tool` row for a nested call as it starts.

```ts
function nestedToolEvent(
  call: { callId: string; input: Record<string, unknown>; name: string; parentToolCallId: string; runsNestedAgent?: boolean; startedAt?: number },
  tag?: NestedEventTag,
): StreamEvent
```

**Parameters**

- `call` (`{ callId: string; input: Record<string, unknown>; name: string; parentToolCallId: string; runsNestedAgent?: boolean; startedAt?: number }`): The nested call.
- `tag?` (`NestedEventTag`): Turn, subagent and depth to stamp on the event.

**Returns** `StreamEvent`

Source: [src/chat/nested-call-events.ts:78](https://github.com/Tahul/zidane/blob/main/src/chat/nested-call-events.ts#L78)

### `newSessionModel`

Function.

The model a new session starts on: an explicit pick wins, else the space's
default. `fallbacks` is set only when the result IS the space default (a
different pick must not inherit the space's chain); `undefined` fallbacks
leave the caller's usual seeding (`lastModelChain`) in place.

```ts
function newSessionModel(
  pick: { account?: string; modelId?: string; providerKey?: string },
  spaceDefault: SpaceModelDefault | undefined,
): SpaceModelDefault | undefined
```

**Parameters**

- `pick` (`{ account?: string; modelId?: string; providerKey?: string }`): The model picked in the composer, if any.
- `spaceDefault` (`SpaceModelDefault | undefined`): The space's default model, if any.

**Returns** `SpaceModelDefault | undefined`

Source: [src/chat/spaces.ts:434](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L434)

### `newSpaceId`

Function.

A fresh, unused space id (`space-<n>`).

```ts
function newSpaceId(spaces: readonly Space[]): string
```

**Parameters**

- `spaces` (`readonly Space[]`): The space list.

**Returns** `string`

Source: [src/chat/spaces.ts:467](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L467)

### `nextFireAfter`

Function.

Schedules: the wire shapes, the checks and the time math that the host,
the TUI and the UI share. The cron math (`./cron`, on `croner`) and the
scheduler (`./scheduler`) are imported by path, so this entry stays free
of them. See docs/SCHEDULES.md.

```ts
function nextFireAfter(
  trigger: ScheduleTrigger,
  after: number,
  cron?: CronEngine,
): number | null
```

**Parameters**

- `trigger` (`ScheduleTrigger`): A valid trigger (`validateScheduleInput` checked it).
- `after` (`number`): Epoch ms.
- `cron?` (`CronEngine`): The cron math. Absent: a cron trigger answers `null`.

**Returns** `number | null`

Source: [src/schedules/next-fire.ts:33](https://github.com/Tahul/zidane/blob/main/src/schedules/next-fire.ts#L33)

### `nextLogLevel`

Function.

Next min-level in [`LOG_LEVEL_CYCLE`](https://zidane.si/docs/reference/chat-pure.md#LOG_LEVEL_CYCLE), wrapping around.

```ts
function nextLogLevel(level: LogLevel): LogLevel
```

**Parameters**

- `level` (`LogLevel`): Current minimum level.

**Returns** `LogLevel`

Source: [src/chat/logs-view.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/logs-view.ts#L21)

### `normalizeBrowserUrl`

Function.

Normalize address-bar input to a loadable URL, or `null` when it is not one.

```ts
function normalizeBrowserUrl(input: string): string | null
```

**Parameters**

- `input` (`string`): Text typed in the address bar. A bare port means a local dev server.

**Returns** `string | null`

Source: [src/chat/browser/url.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/browser/url.ts#L17)

### `normalizeMarkdownCodeFences`

Function.

Lift indented fenced code blocks to column 0 while preserving the code
body's relative indentation.

OpenTUI's markdown renderNode hook only receives top-level code tokens.
A common assistant shape is:

- Run this:
  ```bash
  command
  ```

Marked parses that as code inside a list token, so the TUI loses the
code-panel wrapper and copy affordance. Normalizing just the fence's list
indentation keeps the prose readable while routing the snippet through
the same top-level renderer as ordinary fences.

```ts
function normalizeMarkdownCodeFences(text: string): string
```

**Parameters**

- `text` (`string`): Markdown that may hold indented fenced code blocks.

**Returns** `string`

Source: [src/chat/markdown-segments.ts:238](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L238)

### `normalizePaletteItems`

Function.

Coerce whatever a provider returned into well-formed items: entries
without an id or title are dropped, strings are capped, unknown kinds
fall back to `action`, and `source` is stamped with the provider id.
Never throws.

```ts
function normalizePaletteItems(
  input: unknown,
  source: string,
  defaultGroup: string,
): PaletteItem[]
```

**Parameters**

- `input` (`unknown`): Value a provider returned.
- `source` (`string`): Provider id stamped on each item.
- `defaultGroup` (`string`): Group for items that name none.

**Returns** `PaletteItem[]`

Source: [src/chat/palette.ts:445](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L445)

### `normalizePaletteRunResult`

Function.

Same guard for a `run` result: anything malformed becomes `undefined` (nothing to do).

```ts
function normalizePaletteRunResult(
  input: unknown,
  source: string,
  defaultGroup: string,
): PaletteRunResult
```

**Parameters**

- `input` (`unknown`): Value a provider's `run` returned.
- `source` (`string`): Provider id stamped on nested items.
- `defaultGroup` (`string`): Group for nested items that name none.

**Returns** `PaletteRunResult`

Source: [src/chat/palette.ts:499](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L499)

### `normalizeSpaces`

Function.

The stored list made safe to use: malformed entries and duplicate ids
dropped, and the Default space always present (first when it was missing).
Order is kept: it is the switcher order.

```ts
function normalizeSpaces(list: unknown): Space[]
```

**Parameters**

- `list` (`unknown`): Stored value, usually parsed from settings.

**Returns** `Space[]`

Source: [src/chat/spaces.ts:195](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L195)

### `noteLabel`

Function.

A `/` command's details line: its label, capitalised, or "Details".

```ts
function noteLabel(label: string | undefined): string
```

**Parameters**

- `label` (`string | undefined`): The command's notice label, if any.

**Returns** `string`

Source: [src/chat/fold-rules.ts:155](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L155)

### `oauthAccountLabel`

Function.

Trimmed user-given account name, or [`DEFAULT_OAUTH_ACCOUNT_LABEL`](https://zidane.si/docs/reference/chat-pure.md#DEFAULT_OAUTH_ACCOUNT_LABEL).

```ts
function oauthAccountLabel(credential: { label?: unknown }): string
```

**Parameters**

- `credential` (`{ label?: unknown }`): An OAuth credential entry that may carry a `label`.

**Returns** `string`

Source: [src/chat/cred-keys.ts:150](https://github.com/Tahul/zidane/blob/main/src/chat/cred-keys.ts#L150)

### `offlineSinceText`

Function.

"offline since 14:05" (a date when not today) for an offline machine's `lastSeen`; "offline" when never seen.

```ts
function offlineSinceText(lastSeen: number | undefined, now: number): string
```

**Parameters**

- `lastSeen` (`number | undefined`): Epoch milliseconds the machine was last seen.
- `now` (`number`): Epoch milliseconds of today.

**Returns** `string`

Source: [src/chat/machines-view.ts:207](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L207)

### `onboardingFeatureCopy`

Function.

The label and description of a feature, from the settings catalog.

```ts
function onboardingFeatureCopy(key: BooleanSettingKey): OnboardingFeatureCopy
```

**Parameters**

- `key` (`BooleanSettingKey`): The setting the feature flips.

**Returns** `OnboardingFeatureCopy`

Source: [src/chat/onboarding/features.ts:193](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/features.ts#L193)

### `onboardingFeatures`

Function.

The features that a run offers: the ones of its app. An `extras` run offers
only the ones that no other app offers, because the other app set the
shared ones.

```ts
function onboardingFeatures(
  surface: OnboardingSurface,
  mode: OnboardingMode,
): OnboardingFeature[]
```

**Parameters**

- `surface` (`OnboardingSurface`): The app that runs the wizard.
- `mode` (`OnboardingMode`): The run's mode.

**Returns** `OnboardingFeature[]`

Source: [src/chat/onboarding/features.ts:172](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/features.ts#L172)

### `onboardingImportParts`

Function.

The parts of an import that the user picked, in words, in the order of the step.

```ts
function onboardingImportParts(
  selection: OnboardingImportSelection | undefined,
  words?: OnboardingImportWords,
): string[]
```

**Parameters**

- `selection` (`OnboardingImportSelection | undefined`): The picks. Absent: nothing to import.
- `words?` (`OnboardingImportWords`, default `ONBOARDING_WORDS`): The words to use. Defaults to [`ONBOARDING_WORDS`](https://zidane.si/docs/reference/chat-pure.md#ONBOARDING_WORDS).

**Returns** `string[]`

Source: [src/chat/onboarding/recap.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/recap.ts#L21)

### `onboardingProgress`

Function.

How far a run is.

```ts
function onboardingProgress(state: OnboardingFlowState): OnboardingProgress
```

**Parameters**

- `state` (`OnboardingFlowState`): The run.

**Returns** `OnboardingProgress`

Source: [src/chat/onboarding/flow.ts:307](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L307)

### `onboardingRecord`

Function.

A record for a run that just ended.

```ts
function onboardingRecord(
  surface: OnboardingSurface,
  now?: Date,
  migrated?: boolean,
): OnboardingRecord
```

**Parameters**

- `surface` (`OnboardingSurface`): The app it ran in.
- `now?` (`Date`): When it ended.
- `migrated?` (`boolean`, default `false`): Written for an install that predates the wizard.

**Returns** `OnboardingRecord`

Source: [src/chat/onboarding/result.ts:123](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L123)

### `onboardingRecords`

Function.

The records that a finished run writes. A full, quick or repeated run writes
the shared record and the record of this app. An extras run writes only the
record of this app. Connect alone writes none.

```ts
function onboardingRecords(
  mode: OnboardingMode,
  surface: OnboardingSurface,
  now?: Date,
): OnboardingState
```

**Parameters**

- `mode` (`OnboardingMode`): The mode the run ended in.
- `surface` (`OnboardingSurface`): The app it ran in.
- `now?` (`Date`): When it ended.

**Returns** `OnboardingState`

Source: [src/chat/onboarding/result.ts:136](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L136)

### `onboardingReducer`

Function.

The next state of a run.

```ts
function onboardingReducer(
  state: OnboardingFlowState,
  action: OnboardingAction,
): OnboardingFlowState
```

**Parameters**

- `state` (`OnboardingFlowState`): The run now.
- `action` (`OnboardingAction`): What happened.

**Returns** `OnboardingFlowState`

**Example**

```ts
import { createOnboardingFlow, currentOnboardingStep, DEFAULT_SETTINGS, onboardingReducer } from 'zidane/chat/pure'

let flow = createOnboardingFlow(
  { mode: 'full', surface: 'tui', importAvailable: false, installsAvailable: true },
  { settings: DEFAULT_SETTINGS },
)
flow = onboardingReducer(flow, { type: 'next' })
currentOnboardingStep(flow) // 'connect'
```

Source: [src/chat/onboarding/flow.ts:252](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L252)

### `onboardingSettingsChange`

Function.

The settings that a run writes. Only the keys that the run changed count. A
value that equals the default is not stored, so it keeps following the
default. If the key is stored, the run resets it instead of pinning it. A
setting that is off only because the one it needs is off is not written:
it comes back as it was when that one turns on again.

```ts
function onboardingSettingsChange(
  draft: Partial<Settings>,
  initial: Partial<Settings>,
  stored: Partial<Settings>,
): OnboardingSettingsChange
```

**Parameters**

- `draft` (`Partial<Settings>`): The settings the run ends with.
- `initial` (`Partial<Settings>`): The settings the run started with.
- `stored` (`Partial<Settings>`): The settings slice stored now (explicit choices only, without defaults).

**Returns** `OnboardingSettingsChange`

**Example**

```ts
import { DEFAULT_SETTINGS, onboardingSettingsChange } from 'zidane/chat/pure'

onboardingSettingsChange({ ...DEFAULT_SETTINGS, spaces: true }, DEFAULT_SETTINGS, {})
// { set: { spaces: true }, reset: [] }
```

Source: [src/chat/onboarding/result.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L52)

### `onboardingStep`

Function.

The display data of a step.

```ts
function onboardingStep(id: OnboardingStepId): OnboardingStepMeta
```

**Parameters**

- `id` (`OnboardingStepId`): The step.

**Returns** `OnboardingStepMeta`

Source: [src/chat/onboarding/steps.ts:41](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/steps.ts#L41)

### `onboardingSwitchedFeatures`

Function.

The features that a run switched on and off. Only the ones it changed:
the defaults are not news.

```ts
function onboardingSwitchedFeatures(
  state: OnboardingFlowState,
): OnboardingSwitchedFeatures
```

**Parameters**

- `state` (`OnboardingFlowState`): The run.

**Returns** `OnboardingSwitchedFeatures`

Source: [src/chat/onboarding/recap.ts:48](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/recap.ts#L48)

### `oneLineTitle`

Function.

`text` on one line: line breaks, tabs and runs of spaces become one space.

```ts
function oneLineTitle(text: string): string
```

**Parameters**

- `text` (`string`): Title text. Whitespace runs collapse to one space.

**Returns** `string`

Source: [src/chat/session-title-text.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/session-title-text.ts#L17)

### `openForAttention`

Function.

The agent is blocked on the user (a plan to approve, a question to
answer): show the tab regardless of earlier picks. Costs at most a tab
switch, and nothing in that tab decides implicitly. Not a user pick, so
it does not lock out later proactive opens.

```ts
function openForAttention(state: PanelState, id: string): PanelState
```

**Parameters**

- `state` (`PanelState`): The current panel state.
- `id` (`string`): Id of the tab that needs attention.

**Returns** `PanelState`

Source: [src/chat/panels.ts:280](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L280)

### `openProactive`

Function.

Agent / extension asked to show a tab. Honoured only until the user has
picked a tab themselves (a badge that flipped must never steal the tab);
otherwise the request is dropped and the state returned unchanged.

```ts
function openProactive(state: PanelState, id: string): PanelState
```

**Parameters**

- `state` (`PanelState`): The current panel state.
- `id` (`string`): Id of the tab to show.

**Returns** `PanelState`

Source: [src/chat/panels.ts:265](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L265)

### `orchestratedBy`

Function.

The main session id a worker reports to, or `null` for an ordinary session.

```ts
function orchestratedBy(
  metadata: Readonly<Record<string, unknown>> | undefined,
): string | null
```

**Parameters**

- `metadata` (`Readonly<Record<string, unknown>> | undefined`): Session metadata to inspect.

**Returns** `string | null`

Source: [src/chat/orchestration.ts:170](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L170)

### `orderByMachine`

Function.

Environment kinds in picker order: this host's own first, then each
machine's together (`local@` before `worktree@`), machines by name.

```ts
function orderByMachine<T extends { kind: string; machine?: { name: string } }>(
  descriptors: readonly T[],
): T[]
```

**Type parameters**

- `T` (`extends { kind: string; machine?: { name: string } }`)

**Parameters**

- `descriptors` (`readonly T[]`): Environment kind descriptors.

**Returns** `T[]`

Source: [src/chat/machines-view.ts:85](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L85)

### `otherDelivery`

Function.

The delivery that is not `delivery`: what Alt+Enter does while a run works.

```ts
function otherDelivery(delivery: MessageDelivery): MessageDelivery
```

**Parameters**

- `delivery` (`MessageDelivery`): What Enter does: the "Messages during a run" setting.

**Returns** `MessageDelivery`: The other delivery.

Source: [src/chat/message-delivery.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/message-delivery.ts#L13)

### `ownerOf`

Function.

Returns the owner of an event: its `childId`, or `parent`.

```ts
function ownerOf(event: StreamEvent): string
```

**Parameters**

- `event` (`StreamEvent`): The event to inspect.

**Returns** `string`

Source: [src/chat/streaming-pure.ts:22](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L22)

### `paginate`

Function.

One page of `rows`. Pass the page's `cursor` back for the next one. A
cursor resumes at the first row that sorts after the row it ended on,
comparing sort keys then id, so rows that moved, appeared or went away
in between never shift the page. Throws [`SessionQueryError`](https://zidane.si/docs/reference/chat-pure.md#SessionQueryError) for a
bad limit, a bad cursor, or a cursor made for another sort, filter or scope.

```ts
function paginate<R extends SessionQueryRow>(
  rows: readonly R[],
  options: PageOptions,
): SessionPage<R>
```

**Type parameters**

- `R` (`extends SessionQueryRow`)

**Parameters**

- `rows` (`readonly R[]`): The rows, filtered and sorted by `withIdTiebreak(options.sort)`.
- `options` (`PageOptions`): Page size, cursor, and what the cursor is signed with.

**Returns** `SessionPage<R>`

Source: [src/chat/session-query/paginate.ts:107](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/paginate.ts#L107)

### `parentProviderKey`

Function.

Provider key a row "belongs to" — its own for a provider header, the parent's
for a source row.

```ts
function parentProviderKey(row: VisibleAuthRow): string
```

**Parameters**

- `row` (`VisibleAuthRow`): A visible row.

**Returns** `string`

Source: [src/chat/auth-rows.ts:102](https://github.com/Tahul/zidane/blob/main/src/chat/auth-rows.ts#L102)

### `parseAnsi`

Function.

`text` as lines of styled spans. A text without a closing newline still
yields its last line; an empty text yields one empty line.

```ts
function parseAnsi(text: string): AnsiSpan[][]
```

**Parameters**

- `text` (`string`): Terminal output.

**Returns** `AnsiSpan[][]`

Source: [src/chat/ansi.ts:283](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L283)

### `parseBindingSpec`

Function.

The spec's first valid chord (callers that pre-parse one binding). Use
[`parseBindingSpecs`](https://zidane.si/docs/reference/chat-pure.md#parseBindingSpecs) to honour every alternative.

```ts
function parseBindingSpec(spec: string | null | undefined): ParsedBinding | null
```

**Parameters**

- `spec` (`string | null | undefined`): Binding spec, possibly listing several chords separated by `|`.

**Returns** `ParsedBinding | null`

Source: [src/chat/keybinding-spec.ts:111](https://github.com/Tahul/zidane/blob/main/src/chat/keybinding-spec.ts#L111)

### `parseBindingSpecs`

Function.

Every chord of `spec` that parses (see [`bindingAlternatives`](https://zidane.si/docs/reference/chat-pure.md#bindingAlternatives)).

```ts
function parseBindingSpecs(spec: string | null | undefined): ParsedBinding[]
```

**Parameters**

- `spec` (`string | null | undefined`): Binding spec, possibly listing several chords separated by `|`.

**Returns** `ParsedBinding[]`

Source: [src/chat/keybinding-spec.ts:101](https://github.com/Tahul/zidane/blob/main/src/chat/keybinding-spec.ts#L101)

### `parseCommandInvocation`

Function.

Parse a prompt as a command invocation, but only when the command token is
the LEADING token of the whole prompt and names a known command. This is
what keeps mid-prompt `/skill` mentions routed to the skills provider:
`"summarize /research"` is not a command, `"/research foo"` is.

`known` is matched case-insensitively; entries may be bare names or
`{ name, aliases }` records — an alias hit canonicalizes to the entry's
`name` (registered casing), so dispatch-by-name downstream just works.

```ts
function parseCommandInvocation(
  prompt: string,
  known: readonly (string | Pick<Command, 'name' | 'aliases'>)[],
): CommandInvocation | null
```

**Parameters**

- `prompt` (`string`): The raw user prompt.
- `known` (`readonly (string | Pick<Command, 'name' | 'aliases'>)[]`): Known command names, or `{ name, aliases }` records, matched case-insensitively.

**Returns** `CommandInvocation | null`

Source: [src/chat/commands.ts:514](https://github.com/Tahul/zidane/blob/main/src/chat/commands.ts#L514)

### `parseCustomModelQuery`

Function.

Read a query that matched nothing as "use this model id anyway".

A bare id is meaningless without a provider, so the first term is checked
against every provider's key and label (case-insensitive): `xai grok-9` and
`Anthropic claude-next` name their provider explicitly, anything else is
attributed to `fallbackProviderKey` (the picker's current pick). Returns
`null` when nothing usable is left, including when the whole query is just a
provider name.

```ts
function parseCustomModelQuery(
  query: string,
  providers: readonly Pick<ProviderAuth, 'key' | 'label'>[],
  fallbackProviderKey: string | null,
): CustomModelTarget | null
```

**Parameters**

- `query` (`string`): Free text, optionally starting with a provider key or label.
- `providers` (`readonly Pick<ProviderAuth, 'key' | 'label'>[]`): Known providers to match a prefix against.
- `fallbackProviderKey` (`string | null`): Provider used when the query names none.

**Returns** `CustomModelTarget | null`

Source: [src/chat/model-catalog.ts:219](https://github.com/Tahul/zidane/blob/main/src/chat/model-catalog.ts#L219)

### `parseFenceOpen`

Function.

The fence `line` opens, or `null`: three or more backticks or tildes, and a
backtick fence's info string holds no backtick. Every markdown scanner that
must agree on where code blocks are (here, and the desktop app's chunker)
reads fences through this and [`isFenceClose`](https://zidane.si/docs/reference/chat-pure.md#isFenceClose).

```ts
function parseFenceOpen(line: string): FenceOpen | null
```

**Parameters**

- `line` (`string`): One line of markdown.

**Returns** `FenceOpen | null`

Source: [src/chat/markdown-segments.ts:402](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L402)

### `parseFieldPath`

Function.

Reads a field path apart, or `undefined` when it names no field and no
well-formed facet.

```ts
function parseFieldPath(path: unknown): ParsedFieldPath | undefined
```

**Parameters**

- `path` (`unknown`): A row field (`updatedAt`) or a facet path (`facet.git.branch`).

**Returns** `ParsedFieldPath | undefined`

Source: [src/chat/session-query/fields.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L65)

### `parseKeyValueLines`

Function.

Parse one key/value pair PER LINE. Line-based (not whitespace-split)
because values legitimately contain spaces — `Authorization: Bearer
abc123` is the canonical headers case, and env values like
`GREETING=hello world` are equally valid. The first separator found
(the separator that appears first in the line) splits.
The rest of the line is the value, trimmed. Blank lines skipped.

```ts
function parseKeyValueLines(
  raw: string,
  opts: { label: string; separators: readonly string[] },
): { ok: true; pairs: Record<string, string> } | { error: string; ok: false }
```

**Parameters**

- `raw` (`string`): Field text, one pair per line.
- `opts` (`{ label: string; separators: readonly string[] }`): A `label` for error messages and the separators to split on.

**Returns** `{ ok: true; pairs: Record<string, string> } | { error: string; ok: false }`

Source: [src/chat/mcp-form.ts:177](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L177)

### `parseMachineKind`

Function.

`{ base, name }` of a machine-qualified kind, `null` for any other.

```ts
function parseMachineKind(
  kind: string,
): { base: 'worktree' | 'local'; name: string } | null
```

**Parameters**

- `kind` (`string`): Environment kind, such as `local@laptop`.

**Returns** `{ base: 'worktree' | 'local'; name: string } | null`

Source: [src/chat/machine-protocol.ts:299](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L299)

### `parseModelId`

Function.

Splits a model id into vendor, family, version, size, snapshot and routing variant. Parsing is lowercase and never throws.

```ts
function parseModelId(id: string): ModelIdParts
```

**Parameters**

- `id` (`string`): Model id, for example `anthropic/claude-sonnet-4-5:thinking`.

**Returns** `ModelIdParts`

Source: [src/chat/model-lineup.ts:54](https://github.com/Tahul/zidane/blob/main/src/chat/model-lineup.ts#L54)

### `parseModelSetting`

Function.

Parse a model setting; `undefined` for unset or malformed.

```ts
function parseModelSetting(raw: string | undefined): ModelSettingPick | undefined
```

**Parameters**

- `raw` (`string | undefined`): Setting text such as `provider/model` or `provider@account/model`. Returns `undefined` when empty or malformed.

**Returns** `ModelSettingPick | undefined`

**Example**

```ts
import { parseModelSetting } from 'zidane/chat/pure'

parseModelSetting('anthropic@work/claude-sonnet-4-5')
// { providerKey: 'anthropic', modelId: 'claude-sonnet-4-5', account: 'work' }
```

Source: [src/chat/model-setting.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/model-setting.ts#L31)

### `parseRemoteHostUrl`

Function.

Validate and normalize a host URL (no trailing slash); throws [`RemoteHostError`](https://zidane.si/docs/reference/chat-pure.md#RemoteHostError).

```ts
function parseRemoteHostUrl(raw: string): string
```

**Parameters**

- `raw` (`string`): URL as entered.

**Returns** `string`

Source: [src/chat/hosts/url.ts:70](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/url.ts#L70)

### `parseRepoInput`

Function.

Reads a git or forge URL (or `owner/repo`) as what `git clone` would clone; `null` when it is not one.

```ts
function parseRepoInput(raw: string): RepoSpec | null
```

**Parameters**

- `raw` (`string`): What was pasted.

**Returns** `RepoSpec | null`

Source: [src/chat/git/repo-url.ts:59](https://github.com/Tahul/zidane/blob/main/src/chat/git/repo-url.ts#L59)

### `parseSessionKey`

Function.

The pair `key` names (a bare id: This computer's).

```ts
function parseSessionKey(key: string): SessionKeyParts
```

**Parameters**

- `key` (`string`): Key built by [`sessionKey`](https://zidane.si/docs/reference/chat-pure.md#sessionKey).

**Returns** `SessionKeyParts`

Source: [src/chat/hosts/session-key.ts:56](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/session-key.ts#L56)

### `parseWhen`

Function.

Reads the time phrase at the start of `text`. `null` when the text does
not start with one of the forms above.

```ts
function parseWhen(text: string, now: number, tz?: string): ParsedWhen | null
```

**Parameters**

- `text` (`string`): What the person typed after the command name.
- `now` (`number`): Epoch ms.
- `tz?` (`string`): The time zone for cron triggers. Default: this process's.

**Returns** `ParsedWhen | null`

Source: [src/schedules/when.ts:114](https://github.com/Tahul/zidane/blob/main/src/schedules/when.ts#L114)

### `patchInlineGhost`

Function.

Optimistically transform the current ghost across a buffer edit so it
stays visible while the debounced provider re-query is in flight —
without this, every keystroke inside a completable token blinks the
ghost (hide → 120 ms → reshow).

Two edits are reconcilable (everything else returns null and waits for
the authoritative result):

- typing FORWARD along the suggestion (`bi` → `bin` with ghost
  `n/`): candidates are filtered to those starting with the typed
  chars and trimmed;
- deleting BACKWARD within the token (`bin` → `bi` with ghost `/`):
  the deleted chars are re-prepended to every candidate. Guarded to
  non-whitespace so crossing a token boundary drops the ghost.

The patched ghost is provisional — the provider's answer replaces it
(and may add candidates the patch couldn't know about).

```ts
function patchInlineGhost(
  prev: InlineGhost | null,
  text: string,
  cursor: number,
): InlineGhost | null
```

**Parameters**

- `prev` (`InlineGhost | null`): Current ghost, or `null` when none is shown.
- `text` (`string`): New buffer text.
- `cursor` (`number`): New caret offset.

**Returns** `InlineGhost | null`: The patched ghost, or `null` when the edit cannot be reconciled.

Source: [src/chat/inline-ghost.ts:44](https://github.com/Tahul/zidane/blob/main/src/chat/inline-ghost.ts#L44)

### `percentileMs`

Function.

The duration below which the answer puts probability `p` (`0..1`), from
the per-level probabilities. `null` when they don't add up to anything.

```ts
function percentileMs(probabilities: readonly number[], p: number): number | null
```

**Parameters**

- `probabilities` (`readonly number[]`): Probability per level, indexed like the levels.
- `p` (`number`): The percentile.

**Returns** `number | null`

Source: [src/chat/run-estimate.ts:73](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L73)

### `pickChainPrimary`

Function.

Moves `entry` to position 0, adding it when absent.

```ts
function pickChainPrimary(
  chain: readonly ModelChainEntry[],
  entry: ModelChainEntry,
): ModelChainEntry[]
```

**Parameters**

- `chain` (`readonly ModelChainEntry[]`): The current chain.
- `entry` (`ModelChainEntry`): The pick to make primary.

**Returns** `ModelChainEntry[]`

Source: [src/chat/model-chain.ts:163](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L163)

### `pickPrimaryKeyed`

Function.

Make `entry` the primary (position 0), keeping the rest in order. Inserts
when absent, promotes when present; no-op when it already leads.

This is `↵` in the picker. It exists because toggling APPENDS: with a chain
of `[current]`, toggling a new model gives `[current, new]`, so the pick
would become a fallback and the active model would not change. "Highlight and ↵"
means "use this one", so that gesture promotes; building a fallback list is
the secondary gesture (`⇥`) and keeps toggle semantics.

```ts
function pickPrimaryKeyed<T>(
  chain: readonly T[],
  entry: T,
  keyOf: (e: T) => string,
): T[]
```

**Type parameters**

- `T`

**Parameters**

- `chain` (`readonly T[]`): The current list.
- `entry` (`T`): The element to move to the front, or add there.
- `keyOf` (`(e: T) => string`): Returns the identity key of an element.

**Returns** `T[]`

Source: [src/chat/model-chain.ts:96](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L96)

### `pickTab`

Function.

The user clicked a tab (or a keybinding cycled to it). Always honoured, always opens.

```ts
function pickTab(state: PanelState, id: string): PanelState
```

**Parameters**

- `state` (`PanelState`): The current panel state.
- `id` (`string`): Id of the chosen tab.

**Returns** `PanelState`

Source: [src/chat/panels.ts:235](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L235)

### `pinTab`

Function.

Add a tab to the host's pinned strip (idempotent, keeps order).

```ts
function pinTab(pinned: readonly string[], id: string): readonly string[]
```

**Parameters**

- `pinned` (`readonly string[]`): The host's pinned tab ids in order.
- `id` (`string`): Id of the tab to pin.

**Returns** `readonly string[]`

Source: [src/chat/panels.ts:179](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L179)

### `planAttachment`

Function.

Decide how a file is attached. Images go by type (or extension); PDFs by
type, extension or their `%PDF-` signature; anything else is text when its
first bytes read as text, sent as `text/plain` unless its type already
names text (a `.ts` file the browser types `video/mp2t` is text).

```ts
function planAttachment(file: AttachmentCandidate): AttachmentPlan
```

**Parameters**

- `file` (`AttachmentCandidate`): The file's name, reported type, size and first bytes.

**Returns** `AttachmentPlan`

Source: [src/chat/attachment-rules.ts:107](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L107)

### `planFold`

Function.

The steps of one exchange in order, and its counts. Consecutive thoughts
are one step; each worker is one step holding its lane's items, merged
with the `spawn` call that started it (the call's line opens onto the
worker's progress). A worker's state is its own structured end: failed
only when it errored (core `describeSpawnEnd`), stopped reads done.

```ts
function planFold<T>(units: readonly FoldUnit<T>[]): FoldPlan<T>
```

**Type parameters**

- `T`

**Parameters**

- `units` (`readonly FoldUnit<T>[]`): The exchange's folded items, oldest first.

**Returns** `FoldPlan<T>`

Source: [src/chat/fold-rules.ts:177](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L177)

### `planOnboarding`

Function.

The steps that a run shows, in order. It starts from the steps of the mode.
It leaves out Bring your setup when zidane found no other agent, and
Connectors, Skills and Extensions when installs do not run on this computer. It
also leaves out the steps that the host excludes. A `connect` run always
has Connect.

```ts
function planOnboarding(ctx: OnboardingPlanContext): OnboardingStepId[]
```

**Parameters**

- `ctx` (`OnboardingPlanContext`): The run's mode, surface and what was found.

**Returns** `OnboardingStepId[]`

**Example**

```ts
import { planOnboarding } from 'zidane/chat/pure'

planOnboarding({ mode: 'quick', surface: 'tui', importAvailable: false, installsAvailable: true })
// ['welcome', 'connect', 'ready']
```

Source: [src/chat/onboarding/steps.ts:61](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/steps.ts#L61)

### `planProgress`

Function.

Counts a plan's steps.

```ts
function planProgress(plan: Pick<Plan, 'steps'>): PlanProgress
```

**Parameters**

- `plan` (`Pick<Plan, 'steps'>`): The plan.

**Returns** `PlanProgress`

Source: [src/chat/plans.ts:1063](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L1063)

### `planProgressLabel`

Function.

Position label for compact surfaces: the active step's position, else
the completed count (`"3/7"`). `null` for a plan with no steps.

```ts
function planProgressLabel(progress: PlanProgress): string | null
```

**Parameters**

- `progress` (`PlanProgress`): The plan's progress.

**Returns** `string | null`

Source: [src/chat/plans.ts:1160](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L1160)

### `positionKeyed`

Function.

1-based position of `key` in the chain, or `null` when absent.

```ts
function positionKeyed<T>(
  chain: readonly T[],
  key: string,
  keyOf: (e: T) => string,
): number | null
```

**Type parameters**

- `T`

**Parameters**

- `chain` (`readonly T[]`): The list to search.
- `key` (`string`): Identity key to find.
- `keyOf` (`(e: T) => string`): Returns the identity key of an element.

**Returns** `number | null`

Source: [src/chat/model-chain.ts:108](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L108)

### `previewEditPayload`

Function.

Previews an edit payload the way the edit tool would apply it.
Hunks are resolved with the tool's lenient matcher, so recoverable `old_string` mismatches still render. The result reports a resolution for each hunk.

```ts
function previewEditPayload(
  payload: EditPayload,
  priorContent: string,
  contextLines?: number,
): PreviewResult
```

**Parameters**

- `payload` (`EditPayload`): The edit payload to preview.
- `priorContent` (`string`): Full file content before the edit.
- `contextLines?` (`number`, default `3`): Lines of unchanged context kept around each change.

**Returns** `PreviewResult`

Source: [src/chat/edit-diff.ts:734](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L734)

### `previewLine`

Function.

Single-line preview of a multi-line string, capped at `max` chars and
ellipsis-terminated when truncated.

Whitespace runs (newlines, tabs, multiple spaces) collapse into one
space so the rendered output stays on a single visual row no matter
how the input was shaped. Used by every transcript "preview" surface
(spawn-start task, `tool: shell (background): <command>`,
`<task-notification>` summary line, etc.) — without the whitespace
collapse, a 60-char `slice` on a string with an inline `\n\n` paints
the second paragraph below the first, producing the visible
"preview text spills onto multiple lines" bug (and, downstream,
misaligned spawn markers when the wrapped lines collide with
other events).

Reserves one slot for the `…` so the displayed width is exactly
`max` when truncation kicks in.

```ts
function previewLine(s: string, max: number): string
```

**Parameters**

- `s` (`string`): Text to preview.
- `max` (`number`): Maximum length in characters, ellipsis included.

**Returns** `string`

Source: [src/chat/format.ts:220](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L220)

### `projectNameOf`

Function.

The folder name of a row's project: the last segment of `projectRoot`, or of
`cwd` without one (`/` and `\\` both separate). `undefined` when neither is set.

```ts
function projectNameOf(
  row: { readonly cwd?: string; readonly projectRoot?: string | null },
): string | undefined
```

**Parameters**

- `row` (`{ readonly cwd?: string; readonly projectRoot?: string | null }`): The row's `projectRoot` and `cwd`.

**Returns** `string | undefined`

Source: [src/chat/session-query/fields.ts:89](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L89)

### `promptSegmentLines`

Function.

The segments cut into the lines the user typed. A flex-wrap row cannot
break on a newline inside one of its items, so each line renders as its
own row; an empty array is a blank line.

```ts
function promptSegmentLines(segments: readonly PromptSegment[]): PromptSegment[][]
```

**Parameters**

- `segments` (`readonly PromptSegment[]`): Segments from [`splitPromptSegments`](https://zidane.si/docs/reference/chat-pure.md#splitPromptSegments).

**Returns** `PromptSegment[][]`

Source: [src/chat/prompt-segments.ts:125](https://github.com/Tahul/zidane/blob/main/src/chat/prompt-segments.ts#L125)

### `promptTurnRefs`

Function.

Reduce persisted turns to the prompt refs the retag needs, dropping
non-prompt turns (assistant, tool results, loop-injected) entirely.

Shared by the in-process path and the daemon broadcast so both select the
same turns as "prompts" — a divergence here would make a prompt selectable
on one surface and not the other.

```ts
function promptTurnRefs(turns: readonly SessionTurn[]): PromptTurnRef[]
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Persisted turns, in order.

**Returns** `PromptTurnRef[]`

Source: [src/chat/turn-selection.ts:167](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L167)

### `providerBrand`

Function.

The setup wizard's model: React-free and Node-free, re-exported by
`zidane/chat/pure` and `zidane/chat`. `docs/ONBOARDING.md` describes it.

```ts
function providerBrand(key: string): string | undefined
```

**Parameters**

- `key` (`string`): The provider key.

**Returns** `string | undefined`

Source: [src/chat/onboarding/brands.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/brands.ts#L52)

### `pushPaletteRecent`

Function.

Most-recent-first list of ids, deduplicated and capped.

```ts
function pushPaletteRecent(recents: readonly string[], id: string): string[]
```

**Parameters**

- `recents` (`readonly string[]`): Current most-recent-first ids.
- `id` (`string`): Id to move to the front.

**Returns** `string[]`

Source: [src/chat/palette.ts:416](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L416)

### `querySessions`

Function.

Filters `rows` by `where`, sorts them by `sort`, then cuts one page.
Paged results (a `limit` or a `cursor`) break ties by id, so the order is
total and a cursor resumes at one place. Throws [`SessionQueryError`](https://zidane.si/docs/reference/chat-pure.md#SessionQueryError)
for an invalid input.

```ts
function querySessions<R extends SessionQueryRow>(
  rows: readonly R[],
  input?: SessionQueryInput,
  options?: QueryOptions,
): SessionPage<R>
```

**Type parameters**

- `R` (`extends SessionQueryRow`)

**Parameters**

- `rows` (`readonly R[]`): Every candidate row.
- `input?` (`SessionQueryInput`, default `{}`): Filter, sort, page and scope.
- `options?` (`QueryOptions`, default `{}`): The clock for relative times.

**Returns** `SessionPage<R>`

Source: [src/chat/session-query/query.ts:35](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/query.ts#L35)

### `rankPaletteItems`

Function.

Rank every item against `query`. Terms are AND-ed: `tog sid` needs both
`tog` and `sid` somewhere in the text, each with its letters in order. A
title that holds every term as one run gets a large bonus;
description, keywords and group are fallbacks. On an empty query recents
come first (most recent on top), then the catalog in provider order.
Returns at most 200 rows.

```ts
function rankPaletteItems(
  items: readonly PaletteItem[],
  query: string,
  recents?: readonly string[],
): RankedPaletteItem[]
```

**Parameters**

- `items` (`readonly PaletteItem[]`): Items to rank.
- `query` (`string`): Space-separated search terms.
- `recents?` (`readonly string[]`, default `[]`): Most-recent-first item ids, shown first on an empty query.

**Returns** `RankedPaletteItem[]`

**Example**

```ts
import { rankPaletteItems } from 'zidane/chat/pure'

const ranked = rankPaletteItems(
  [{ id: 'builtin:openSettings', title: 'Open settings', group: 'App', source: 'builtin' }],
  'set',
)
ranked[0]?.item.id // 'builtin:openSettings'
```

Source: [src/chat/palette.ts:339](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L339)

### `readBlockRuns`

Function.

The saved runs of a session, by key. What does not read as a run is left out.

```ts
function readBlockRuns(
  metadata: Readonly<Record<string, unknown>> | undefined,
): Record<string, BlockRun>
```

**Parameters**

- `metadata` (`Readonly<Record<string, unknown>> | undefined`): The session's metadata.

**Returns** `Record<string, BlockRun>`

Source: [src/chat/shell-blocks.ts:212](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L212)

### `readField`

Function.

The value of a field path in `row` (see [`readParsedField`](https://zidane.si/docs/reference/chat-pure.md#readParsedField)), or
`undefined` for a path that names nothing.

```ts
function readField(row: SessionQueryRow, path: string): unknown
```

**Parameters**

- `row` (`SessionQueryRow`): The row.
- `path` (`string`): A row field or a facet path.

**Returns** `unknown`

Source: [src/chat/session-query/fields.ts:146](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L146)

### `readParsedField`

Function.

The value of a parsed field path in `row`. Missing and `null` both read
`undefined`; a missing boolean field reads `false`; `environment.kind`
reads `'local'` without an environment.

```ts
function readParsedField(row: SessionQueryRow, field: ParsedFieldPath): unknown
```

**Parameters**

- `row` (`SessionQueryRow`): The row.
- `field` (`ParsedFieldPath`): A path from [`parseFieldPath`](https://zidane.si/docs/reference/chat-pure.md#parseFieldPath).

**Returns** `unknown`

Source: [src/chat/session-query/fields.ts:122](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L122)

### `readSessionAccount`

Function.

The account a session's primary model runs on, when one is pinned.

```ts
function readSessionAccount(
  metadata: Readonly<Record<string, unknown>> | undefined,
): string | undefined
```

**Parameters**

- `metadata` (`Readonly<Record<string, unknown>> | undefined`): Session metadata to read the pinned account from.

**Returns** `string | undefined`

Source: [src/chat/model-chain-metadata.ts:36](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain-metadata.ts#L36)

### `readSessionFacets`

Function.

A session's stored facet values: `{}` when it has none or the stored value
is not a record.

```ts
function readSessionFacets(
  metadata: Readonly<Record<string, unknown>> | undefined,
): Record<string, JsonValue>
```

**Parameters**

- `metadata` (`Readonly<Record<string, unknown>> | undefined`): Session metadata.

**Returns** `Record<string, JsonValue>`

Source: [src/session/facets.ts:48](https://github.com/Tahul/zidane/blob/main/src/session/facets.ts#L48)

### `readSessionSpaceId`

Function.

The raw space id stamped on a session's metadata, if any.

```ts
function readSessionSpaceId(
  metadata: Readonly<Record<string, unknown>> | undefined,
): string | undefined
```

**Parameters**

- `metadata` (`Readonly<Record<string, unknown>> | undefined`): Session metadata.

**Returns** `string | undefined`

Source: [src/chat/spaces.ts:215](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L215)

### `recentSessionsContent`

Function.

The recent sessions block's content.

```ts
function recentSessionsContent(
  rows: readonly RecentSessionRow[],
  options: { now: number; project: boolean },
): PanelContent
```

**Parameters**

- `rows` (`readonly RecentSessionRow[]`): The sessions, newest first.
- `options` (`{ now: number; project: boolean }`): Options.

**Returns** `PanelContent`

Source: [src/chat/home-blocks.ts:307](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L307)

### `recentSessionsHomeBlock`

Function.

The recent sessions block.

```ts
function recentSessionsHomeBlock(deps: RecentSessionsBlockDeps): ExtensionPanelEntry
```

**Parameters**

- `deps` (`RecentSessionsBlockDeps`): Where its sessions come from.

**Returns** `ExtensionPanelEntry`

Source: [src/chat/home-blocks.ts:336](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L336)

### `reconcileEvents`

Function.

`next`, with every event structurally equal to one of `prev` replaced by
that object (matched one to one, so an event repeated twice keeps two
objects). Hands back `prev` itself when the result is positionally
identical, so a store keyed on the array sees no change at all.

```ts
function reconcileEvents<E extends ReconcilableEvent>(
  prev: readonly E[],
  next: readonly E[],
): E[]
```

**Type parameters**

- `E` (`extends ReconcilableEvent`)

**Parameters**

- `prev` (`readonly E[]`): Events on show now.
- `next` (`readonly E[]`): The replacement transcript.

**Returns** `E[]`

Source: [src/chat/transcript-reconcile.ts:40](https://github.com/Tahul/zidane/blob/main/src/chat/transcript-reconcile.ts#L40)

### `rememberableChain`

Function.

What of a model pick a window remembers as its default (`lastModelChain`:
the next new session's model, the next launch's). One rule for the TUI and
the GUI. A session on a server runs with the server's credentials, so its
pickers list the server's providers: a pick there is remembered only when
this computer can run its primary too (a provider only the server has
would leave the next local session without a usable model), and the
fallbacks this computer can't run are dropped. A pick on This computer is
remembered as made. `null`: nothing to remember.

```ts
function rememberableChain<T>(
  chain: readonly T[],
  providerOf: (entry: T) => string,
  scope: { canRunHere: (providerKey: string) => boolean; onServer: boolean },
): T[] | null
```

**Type parameters**

- `T`

**Parameters**

- `chain` (`readonly T[]`): Ordered picks, primary first.
- `providerOf` (`(entry: T) => string`): Returns the provider key of a pick.
- `scope` (`{ canRunHere: (providerKey: string) => boolean; onServer: boolean }`): Whether the session runs on a server, and whether this computer can run a given provider.

**Returns** `T[] | null`

Source: [src/chat/model-chain.ts:375](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L375)

### `renderTemplate`

Function.

The template with each placeholder replaced by the row's value: text as
is, numbers and booleans as written, lists joined with `', '`, anything
else (and missing values) empty. Runs of spaces collapse; the result is
trimmed.

```ts
function renderTemplate(template: string, row: SessionQueryRow): string
```

**Parameters**

- `template` (`string`): A template that passed [`validateTemplate`](https://zidane.si/docs/reference/chat-pure.md#validateTemplate).
- `row` (`SessionQueryRow`): The row.

**Returns** `string`

Source: [src/chat/session-query/template.ts:79](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/template.ts#L79)

### `reorderKeyed`

Function.

Move the entry with `key` by one priority slot; boundary or missing = identity.

```ts
function reorderKeyed<T>(
  chain: readonly T[],
  key: string,
  delta: -1 | 1,
  keyOf: (e: T) => string,
): readonly T[]
```

**Type parameters**

- `T`

**Parameters**

- `chain` (`readonly T[]`): The current list.
- `key` (`string`): Identity key of the element to move.
- `delta` (`-1 | 1`): `-1` moves it earlier, `1` moves it later.
- `keyOf` (`(e: T) => string`): Returns the identity key of an element.

**Returns** `readonly T[]`

Source: [src/chat/model-chain.ts:132](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L132)

### `reorderTabs`

Function.

Apply a user reorder of the VISIBLE strip to the pinned list. `pinned` can
hold ids the catalog no longer shows (an extension disabled for this cwd);
they keep their slots, and the visible ids fill the remaining slots in the
new order, so re-enabling the extension brings its tab back where it was.
Ids in `visible` that aren't pinned are ignored. Returns `pinned` itself
when nothing moved.

```ts
function reorderTabs(
  pinned: readonly string[],
  visible: readonly string[],
): readonly string[]
```

**Parameters**

- `pinned` (`readonly string[]`): The host's pinned tab ids in order.
- `visible` (`readonly string[]`): Ids of the tabs currently shown, in their new order.

**Returns** `readonly string[]`

Source: [src/chat/panels.ts:194](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L194)

### `replaceTurnTextBlocks`

Function.

Replace a turn's text with `newText`, keeping every non-text block (tool
calls, tool results, thinking, images) where it was. All text blocks
collapse into one, placed where the first text block was; an empty or
whitespace-only `newText` removes the text and keeps the rest.

Returns `null` when the turn is missing or has no text to edit, so callers
can report it. Untouched turns keep their identity (a store can rewrite
only the edited row).

```ts
function replaceTurnTextBlocks(
  turns: readonly SessionTurn[],
  turnId: string,
  newText: string,
): SessionTurn[] | null
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Persisted turns in order.
- `turnId` (`string`): Id of the turn to edit.
- `newText` (`string`): Replacement text.

**Returns** `SessionTurn[] | null`

Source: [src/chat/turn-operations.ts:163](https://github.com/Tahul/zidane/blob/main/src/chat/turn-operations.ts#L163)

### `requirementMet`

Function.

Whether a toggle's `requires` setting is on. `decisions` is also on while
approvals use Model decision (`decisionsEnabled`).

```ts
function requirementMet(settings: Partial<Settings>, key: BooleanSettingKey): boolean
```

**Parameters**

- `settings` (`Partial<Settings>`): The settings to check.
- `key` (`BooleanSettingKey`): The required setting.

**Returns** `boolean`

Source: [src/chat/settings-catalog.ts:337](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L337)

### `resetLabel`

Function.

Time to reset, worded like a provider error's (`resets in 1 h 45 min`,
see `formatResetDelay`), so the panel and a rate-limit line agree.
`null` when the provider reported no reset, `resetting` once it is due.

```ts
function resetLabel(resetsAt: number | null, now?: number): string | null
```

**Parameters**

- `resetsAt` (`number | null`): Epoch milliseconds of the reset, or `null` when unknown.
- `now?` (`number`): Epoch milliseconds to measure from.

**Returns** `string | null`

Source: [src/chat/provider-usage-format.ts:208](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L208)

### `resolveActiveTab`

Function.

Resolve the tab to render: the active one when it still exists, else the
first tab, else `null` (empty catalog). Keeps state stable when an
extension is disabled and its tab vanishes.

```ts
function resolveActiveTab(
  state: PanelState,
  catalog: readonly PanelTab[],
): PanelTab | null
```

**Parameters**

- `state` (`PanelState`): The current panel state.
- `catalog` (`readonly PanelTab[]`): Tabs in display order.

**Returns** `PanelTab | null`

Source: [src/chat/panels.ts:294](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L294)

### `resolveSessionSpace`

Function.

The space a session is shown in: its stamped id when that space exists,
else Default (unstamped, Default itself, or a deleted space).

```ts
function resolveSessionSpace(
  spaceId: string | undefined,
  spaces: readonly Space[],
): string
```

**Parameters**

- `spaceId` (`string | undefined`): Id stamped on the session, if any.
- `spaces` (`readonly Space[]`): The space list.

**Returns** `string`

Source: [src/chat/spaces.ts:227](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L227)

### `resolveTime`

Function.

A bound as epoch ms: a number as is, a relative time from `now`, an ISO
date parsed (UTC without a zone). `undefined` for anything else.

```ts
function resolveTime(bound: QueryBound, now: number): number | undefined
```

**Parameters**

- `bound` (`QueryBound`): The bound.
- `now` (`number`): The current time, epoch ms.

**Returns** `number | undefined`

Source: [src/chat/session-query/time.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/time.ts#L29)

### `retagUserPromptEvents`

Function.

Retro-tag live `user-prompt` events with the id of their persisted turn.

Live prompt echoes are appended to the stream BEFORE `agent.run()` mints
and persists the user turn, so they carry no `turnId` — which makes them
invisible to select-turn navigation, hover, and click (all keyed on
`turnId`), while the SAME prompt becomes selectable after a session reload
(replay tags every event). Hosts call this when the seeded turns land
(e.g. the `session:turns` hook, which fires right after the prompt turn
persists, before the first model turn).

Matching rule, per prompt-bearing turn: the NEWEST `user-prompt` event
that has no `turnId` yet and whose text equals one of the turn's text
blocks — or the turn's `display` echo when the caller supplies one
(run-minted prompt turns never carry `display` themselves; the TUI's
command `runAgent` path injects the origin display onto a copy after the
sub-run resolves, since the echo event's text is the short display line,
not the full prompt). A prompt turn qualifies with at least one non-blank
text block, OR — the attachment-only submit — with media blocks
(document/image/audio/video) and no tool plumbing; the latter matches the
newest untagged blank-text event that carries attachment chips. Tool-
result-only user turns contribute nothing, and loop-injected turns
(`SessionTurn.injected`) are not prompts, so neither is ever matched.

Pure — returns the SAME array instance when nothing matched, so hosts
can cheaply skip a re-render.

```ts
function retagUserPromptEvents(
  events: readonly StreamEvent[],
  appendedTurns: readonly SessionTurn[],
): readonly StreamEvent[]
```

**Parameters**

- `events` (`readonly StreamEvent[]`): Current transcript events.
- `appendedTurns` (`readonly SessionTurn[]`): Turns just persisted, in order.

**Returns** `readonly StreamEvent[]`

Source: [src/chat/turn-selection.ts:150](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L150)

### `retagUserPromptEventsFromRefs`

Function.

Attach persisted turn ids to the live `user-prompt` events they correspond
to, so a just-sent prompt becomes selectable (hover, click, edit, delete)
without waiting for a session reload.

Matching is newest-first and one-to-one: identical prompt text sent twice
must bind to two different turns, so each ref consumes exactly one untagged
event.

```ts
function retagUserPromptEventsFromRefs(
  events: readonly StreamEvent[],
  refs: readonly PromptTurnRef[],
): readonly StreamEvent[]
```

**Parameters**

- `events` (`readonly StreamEvent[]`): Current transcript events.
- `refs` (`readonly PromptTurnRef[]`): Prompt turn refs from [`promptTurnRefs`](https://zidane.si/docs/reference/chat-pure.md#promptTurnRefs).

**Returns** `readonly StreamEvent[]`

Source: [src/chat/turn-selection.ts:217](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L217)

### `retryLabel`

Function.

Provider-retry label — `retrying 2/5`, or `retrying 2/5 (child-3)` when the
stalled stream belongs to a subagent rather than the parent.

Naming the source matters: with subagents in flight, an unattributed
"retrying" leaves the user unable to tell whether their own turn is stuck or
a delegated worker is.

```ts
function retryLabel(info: { attempt: number; max: number; source: string }): string
```

**Parameters**

- `info` (`{ attempt: number; max: number; source: string }`): Retry attempt, attempt limit, and the source of the stalled stream (`'parent'` or a subagent id).

**Returns** `string`

Source: [src/chat/footer-chips.ts:119](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L119)

### `runEstimateView`

Function.

A run record's estimate as a [`RunEstimateView`](https://zidane.si/docs/reference/chat-pure.md#RunEstimateView): its timing when it
has one, else its lasting failure; `undefined` for neither (never asked,
or a failure the next attempt may not hit).

```ts
function runEstimateView(
  run: Pick<SessionRun, 'id' | 'startedAt' | 'depth' | 'label' | 'parentCallId' | 'estimate' | 'estimateFailure' | 'userWait'>,
): RunEstimateView | undefined
```

**Parameters**

- `run` (`Pick<SessionRun, 'id' | 'startedAt' | 'depth' | 'label' | 'parentCallId' | 'estimate' | 'estimateFailure' | 'userWait'>`): The run record.

**Returns** `RunEstimateView | undefined`

Source: [src/chat/run-estimate.ts:216](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L216)

### `runFoldStatus`

Function.

The live work row's status: a retry wins, then a wait that has lasted
[`RUN_WAITING_DELAY_MS`](https://zidane.si/docs/reference/chat-pure.md#RUN_WAITING_DELAY_MS), else working.

```ts
function runFoldStatus(
  input: { retry: RunRetry | null; waitedMs: number | null },
): RunFoldStatus
```

**Parameters**

- `input` (`{ retry: RunRetry | null; waitedMs: number | null }`): What the surface knows.

**Returns** `RunFoldStatus`

Source: [src/chat/run-activity.ts:128](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L128)

### `runningEstimateViews`

Function.

The estimates of a session's runs in progress, the session's own first:
what a session row carries.

```ts
function runningEstimateViews(runs: readonly SessionRun[]): RunEstimateView[]
```

**Parameters**

- `runs` (`readonly SessionRun[]`): The session's run records.

**Returns** `RunEstimateView[]`

Source: [src/chat/run-estimate.ts:247](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L247)

### `runReceiptFromRun`

Function.

Build the receipt for a run record. `now` stands in for `endedAt` when the
record is not finalized yet (`run:end` is broadcast a beat before it is).

```ts
function runReceiptFromRun(
  run: SessionRun,
  now?: number,
  previous?: SessionRun,
): RunReceipt
```

**Parameters**

- `run` (`SessionRun`): The run record.
- `now?` (`number`): Epoch milliseconds used as the end time of a run still in progress.
- `previous?` (`SessionRun`): The session's top-level run before this one, to tell an agent switch.

**Returns** `RunReceipt`

Source: [src/chat/run-receipt.ts:103](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L103)

### `runRetryingLabel`

Function.

The header text while a provider call is retried: `Retrying 2/3`, naming
the subagent when it is not the session's own stream. Both apps show these words.

```ts
function runRetryingLabel(retry: RunRetry): string
```

**Parameters**

- `retry` (`RunRetry`): The retry in flight.

**Returns** `string`

Source: [src/chat/run-activity.ts:145](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L145)

### `runStatusCells`

Function.

The live run readout as cells, one badge each: `1m 15s` `↓1.2k` `41 tok/s`.
Time runs from the run's start, the count covers the whole run (settled
turns plus the one streaming), and the rate is the honest windowed figure
from `stepStreamRate` (`null` until it has one). `↓~` marks a count that is
still the character heuristic. A tool-only stretch shows just the time.
Same model as `formatRunReceiptCells`, the receipt the run ends with.

`detail` drops the least useful cell first when space runs out:
`'full'` → `'count'` (no rate) → `'time'`.

```ts
function runStatusCells(
  run: { elapsedSec: number; estimated: boolean; outputTokens: number; rate: number | null },
  detail?: 'full' | 'count' | 'time',
): RunStatusCell[]
```

**Parameters**

- `run` (`{ elapsedSec: number; estimated: boolean; outputTokens: number; rate: number | null }`): Elapsed seconds, output token count, whether the count is estimated, and the stream rate in tokens per second (`null` when unknown).
- `detail?` (`'full' | 'count' | 'time'`, default `'full'`): How much of the readout to keep. Defaults to `'full'`.

**Returns** `RunStatusCell[]`

Source: [src/chat/footer-chips.ts:146](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L146)

### `runStatusKey`

Function.

The status a surface times, as a key: one per retry attempt and one per
wait, `null` while nothing is timed. A surface restarts its clock when
the key changes.

```ts
function runStatusKey(status: LiveRunStatus): string | null
```

**Parameters**

- `status` (`LiveRunStatus`): The live run's status.

**Returns** `string | null`

Source: [src/chat/run-activity.ts:107](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L107)

### `runTailActivity`

Function.

Classify the tail of a live transcript. Only meaningful while a run is in
flight: an idle transcript reads as `waiting` too.

Reasoning that is only whitespace counts as nothing (transcripts hide it),
and a tool call counts as running until its result arrives, back to the
run's prompt.

```ts
function runTailActivity(events: readonly StreamEvent[]): RunTailActivity
```

**Parameters**

- `events` (`readonly StreamEvent[]`): Transcript events, oldest first.

**Returns** `RunTailActivity`

Source: [src/chat/run-activity.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L39)

### `sameAuthTarget`

Function.

The same sign-in: the failure is fixed once this one signs in again, so
every earlier card for it can say so.

```ts
function sameAuthTarget(a: AuthFailure, b: AuthFailure): boolean
```

**Parameters**

- `a` (`AuthFailure`): One failure.
- `b` (`AuthFailure`): The other.

**Returns** `boolean`

Source: [src/chat/auth-failure.ts:51](https://github.com/Tahul/zidane/blob/main/src/chat/auth-failure.ts#L51)

### `scanModes`

Function.

The mode state after `text`, which starts at stream offset `base`. Returns `state` itself when nothing changed.

```ts
function scanModes(state: ModeState, text: string, base: number): ModeState
```

**Parameters**

- `state` (`ModeState`): The modes before `text`.
- `text` (`string`): Program output to scan.
- `base` (`number`): Stream offset of `text`'s first character, recorded in `altAt`.

**Returns** `ModeState`

Source: [src/contexts/terminal-modes.ts:46](https://github.com/Tahul/zidane/blob/main/src/contexts/terminal-modes.ts#L46)

### `scheduleLabel`

Function.

A schedule's name for lists and the transcript: its own, else the start of its prompt, else its handler.

```ts
function scheduleLabel(schedule: Pick<Schedule, 'name' | 'action'>): string
```

**Parameters**

- `schedule` (`Pick<Schedule, 'name' | 'action'>`): The schedule's name and action.

**Returns** `string`

Source: [src/schedules/validate.ts:211](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L211)

### `scheduleTargetSession`

Function.

The session that a schedule's prompt goes to, or `undefined` (a `newSession` or an extension action).

```ts
function scheduleTargetSession(action: ScheduleAction): string | undefined
```

**Parameters**

- `action` (`ScheduleAction`): The schedule's action.

**Returns** `string | undefined`

Source: [src/schedules/validate.ts:225](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L225)

### `scoreToMs`

Function.

A score (a level index, possibly between levels) as a duration: the marks
are on a log scale, so a score between two levels is interpolated on it.

```ts
function scoreToMs(score: number): number
```

**Parameters**

- `score` (`number`): Probability-weighted level index, `0` to `levels - 1`.

**Returns** `number`

Source: [src/chat/run-estimate.ts:56](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L56)

### `scriptErrorOf`

Function.

The error a failed script threw and the line it names, out of its result
(`Script error: …` then the `12 | source` excerpt the sandbox writes).

```ts
function scriptErrorOf(result: string): { line: number; message: string } | undefined
```

**Parameters**

- `result` (`string`): The script's result text.

**Returns** `{ line: number; message: string } | undefined`

Source: [src/chat/script-progress.ts:454](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L454)

### `scriptLoops`

Function.

The loops of a script, by the lines they span, outer ones first (by start, then the longest): bodies of
`for`, `while` and `do`, and callbacks of array methods (`.map`, `.forEach`, `.filter`, …).
A helper function is not a loop.

```ts
function scriptLoops(code: string): ScriptLoop[]
```

**Parameters**

- `code` (`string`): The script, as the model wrote it.

**Returns** `ScriptLoop[]`

Source: [src/chat/script-progress.ts:818](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L818)

### `scriptProgressByCall`

Function.

The latest `tool-progress` state of each script, by call id (`childId` + NUL + `callId`).

```ts
function scriptProgressByCall(
  events: readonly Pick<StreamEvent, 'kind' | 'childId' | 'callId' | 'scriptProgress'>[],
): ReadonlyMap<string, ScriptProgress>
```

**Parameters**

- `events` (`readonly Pick<StreamEvent, 'kind' | 'childId' | 'callId' | 'scriptProgress'>[]`): The transcript's events.

**Returns** `ReadonlyMap<string, ScriptProgress>`

Source: [src/chat/script-progress.ts:222](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L222)

### `scriptProgressFromRecords`

Function.

The final progress of a script from its saved call records, or `undefined`
when none carries a line (the script ran without live progress).

```ts
function scriptProgressFromRecords(
  records: readonly NestedToolCallRecord[],
  ok?: boolean,
): ScriptProgress | undefined
```

**Parameters**

- `records` (`readonly NestedToolCallRecord[]`): The calls saved on the script's result.
- `ok?` (`boolean`): The script's own result was no error.

**Returns** `ScriptProgress | undefined`

Source: [src/chat/script-progress.ts:184](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L184)

### `scriptProgressKey`

Function.

Key of a script in [`scriptProgressByCall`](https://zidane.si/docs/reference/chat-pure.md#scriptProgressByCall).

```ts
function scriptProgressKey(callId: string, childId?: string): string
```

**Parameters**

- `callId` (`string`): The script's call id.
- `childId?` (`string`): The subagent that ran it, if any.

**Returns** `string`

Source: [src/chat/script-progress.ts:237](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L237)

### `scriptProgressView`

Function.

The view of a script: its lines with their states, the counts, and the
percent when it is exact (see [`countOnceCallSites`](https://zidane.si/docs/reference/chat-pure.md#countOnceCallSites)).

```ts
function scriptProgressView(
  code: string,
  progress: ScriptProgress | undefined,
  finished: boolean,
  ok?: boolean,
  result?: string | null,
): ScriptProgressView
```

**Parameters**

- `code` (`string`): The script, as the model wrote it.
- `progress` (`ScriptProgress | undefined`): Its progress, when it streamed any.
- `finished` (`boolean`): The script ended (`ok` tells how).
- `ok?` (`boolean`, default `true`): It ended without error.
- `result?` (`string | null`): Its result text: a failed script's names the line it threw at.

**Returns** `ScriptProgressView`

Source: [src/chat/script-progress.ts:353](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L353)

### `searchableTurnText`

Function.

Search-specific serializer. Unlike `turnAsText`, it never serializes media,
document attachments, encrypted reasoning, or base64-looking payloads.

```ts
function searchableTurnText(turn: SessionTurn): string
```

**Parameters**

- `turn` (`SessionTurn`): Turn to serialize.

**Returns** `string`

Source: [src/chat/history-search.ts:674](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L674)

### `searchHighlightRanges`

Function.

Finds the ranges of `text` that match `query`: the whole phrase, else each term, else fuzzy term matches.

```ts
function searchHighlightRanges(text: string, query: string): HighlightRange[]
```

**Parameters**

- `text` (`string`): Text to search.
- `query` (`string`): Search text.

**Returns** `HighlightRange[]`

Source: [src/chat/history-search.ts:522](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L522)

### `searchSessionHistory`

Function.

Searches `turns` and aggregates the matches into one [`SessionHistoryMatch`](https://zidane.si/docs/reference/chat-pure.md#SessionHistoryMatch).

```ts
function searchSessionHistory(
  turns: readonly SessionTurn[],
  query: string,
  maxExcerpts?: number,
): SessionHistoryMatch | null
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Session turns to search.
- `query` (`string`): Search text.
- `maxExcerpts?` (`number`, default `3`): Maximum excerpts kept in total. Defaults to 3.

**Returns** `SessionHistoryMatch | null`: The aggregate match, or `null` when no turn matches.

Source: [src/chat/history-search.ts:280](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L280)

### `searchSessionHistoryIndex`

Function.

Searches a prebuilt index and aggregates the matches into one [`SessionHistoryMatch`](https://zidane.si/docs/reference/chat-pure.md#SessionHistoryMatch).

```ts
function searchSessionHistoryIndex(
  index: SessionSearchIndex,
  query: string,
  maxExcerpts?: number,
): SessionHistoryMatch | null
```

**Parameters**

- `index` (`SessionSearchIndex`): Index to search.
- `query` (`string`): Search text.
- `maxExcerpts?` (`number`, default `3`): Maximum excerpts kept in total. Defaults to 3.

**Returns** `SessionHistoryMatch | null`: The aggregate match, or `null` when no turn matches.

Source: [src/chat/history-search.ts:292](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L292)

### `searchSessionHistoryIndexAsync`

Function.

Like [`searchSessionHistoryIndex`](https://zidane.si/docs/reference/chat-pure.md#searchSessionHistoryIndex), but yields to the event loop while it searches.

```ts
function searchSessionHistoryIndexAsync(
  index: SessionSearchIndex,
  query: string,
  maxExcerpts?: number,
  onProgress?: (searched: number, total: number) => void,
  signal?: AbortSignal,
): Promise<SessionHistoryMatch | null>
```

**Parameters**

- `index` (`SessionSearchIndex`): Index to search.
- `query` (`string`): Search text.
- `maxExcerpts?` (`number`, default `3`): Maximum excerpts kept in total. Defaults to 3.
- `onProgress?` (`(searched: number, total: number) => void`): Called with the number of turns searched and the total.
- `signal?` (`AbortSignal`): Aborts the search. Aborting throws.

**Returns** `Promise<SessionHistoryMatch | null>`: The aggregate match, or `null` when no turn matches.

Source: [src/chat/history-search.ts:306](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L306)

### `searchSessionIndex`

Function.

Searches an index and returns the best matching turns.

```ts
function searchSessionIndex(
  index: SessionSearchIndex,
  query: string,
  limit?: number,
): SearchTurnMatch[]
```

**Parameters**

- `index` (`SessionSearchIndex`): Index to search.
- `query` (`string`): Search text.
- `limit?` (`number`, default `10`): Maximum number of matches. Defaults to 10.

**Returns** `SearchTurnMatch[]`: Matches sorted by score, then newest first. Empty for a blank query or a non-positive `limit`.

Source: [src/chat/history-search.ts:167](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L167)

### `searchSessionIndexAsync`

Function.

Yielding matcher for very large indexes; progress is checked per chunk.

```ts
function searchSessionIndexAsync(
  index: SessionSearchIndex,
  query: string,
  options?: { limit?: number; onProgress?: (searched: number, total: number) => void; signal?: AbortSignal; yieldEvery?: number },
): Promise<SearchTurnMatch[]>
```

**Parameters**

- `index` (`SessionSearchIndex`): Index to search.
- `query` (`string`): Search text.
- `options?` (`{ limit?: number; onProgress?: (searched: number, total: number) => void; signal?: AbortSignal; yieldEvery?: number }`, default `{}`): Match limit (default 10), yield interval (default 250 turns), progress callback, and abort signal. Aborting throws.

**Returns** `Promise<SearchTurnMatch[]>`

Source: [src/chat/history-search.ts:204](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L204)

### `searchSessionTurns`

Function.

Searches `turns` and returns every match as a [`SearchSessionResult`](https://zidane.si/docs/reference/chat-pure.md#SearchSessionResult).

```ts
function searchSessionTurns(
  turns: readonly SessionTurn[],
  query: string,
  maxExcerpts?: number,
): SearchSessionResult[]
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Session turns to search.
- `query` (`string`): Search text.
- `maxExcerpts?` (`number`, default `3`): Maximum excerpts kept per match. Defaults to 3.

**Returns** `SearchSessionResult[]`

Source: [src/chat/history-search.ts:259](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L259)

### `searchTurns`

Function.

Builds a throwaway index over `turns` and searches it.

```ts
function searchTurns(
  turns: readonly SessionTurn[],
  query: string,
  limit?: number,
): SearchTurnMatch[]
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Session turns to search.
- `query` (`string`): Search text.
- `limit?` (`number`, default `10`): Maximum number of matches. Defaults to 10.

**Returns** `SearchTurnMatch[]`

**Example**

```ts
import type { SessionTurn } from 'zidane'
import { searchTurns } from 'zidane/chat'

declare const turns: SessionTurn[]
const matches = searchTurns(turns, 'migration plan', 5)
console.log(matches[0]?.score)
```

Source: [src/chat/history-search.ts:248](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L248)

### `selectableSources`

Function.

Stored credentials, i.e. the ones a user can actually choose between.

`env` is excluded: it is observed rather than stored, and is usually just the
mirror `applyApiKeyEnv` wrote from the stored API key, so counting it would
advertise a choice that does not exist.

```ts
function selectableSources(provider: ProviderAuth): AuthMethod[]
```

**Parameters**

- `provider` (`ProviderAuth`): The provider whose auth methods are filtered.

**Returns** `AuthMethod[]`

Source: [src/chat/auth-rows.ts:43](https://github.com/Tahul/zidane/blob/main/src/chat/auth-rows.ts#L43)

### `selectableTurnIds`

Function.

Deduplicated, in-order list of **parent-conversation** turn ids that appear
in a rendered transcript — the navigation index for the TUI's select-turn
mode. Three classes of turns are deliberately skipped:

- **Subagent turns** (`childId` set). Nested execution detail; the
  user's mental model of a "message" is the conversational exchange,
  not each spawn turn. Also filtered out by `isVisible` under
  `hideSubagentOutput: true` — selecting them would highlight nothing.
- **Result-only turns** — see [`turnSelectionOwnership`](https://zidane.si/docs/reference/chat-pure.md#turnSelectionOwnership). These get
  coalesced into the assistant turn that emitted their tool_calls.
- **Settings-hidden turns** (when `settings` is supplied). A turn whose
  every event fails [`isVisible`](https://zidane.si/docs/reference/chat-pure.md#isVisible) would render no rows — landing
  the cursor there hides it from the user entirely. The check is opt-
  in so SDK callers without a Settings object get the
  "everything visible" behavior.

Synthetic events (separator, spawn-start, spawn-end) have no `turnId` and
are skipped naturally.

```ts
function selectableTurnIds(
  events: readonly StreamEvent[],
  settings?: Settings,
  visible?: (event: StreamEvent) => boolean,
  opts?: { byMessage?: boolean },
): string[]
```

**Parameters**

- `events` (`readonly StreamEvent[]`): Transcript events in order.
- `settings?` (`Settings`): When set, turns with no visible event are skipped.
- `visible?` (`(event: StreamEvent) => boolean`): Overrides [`isVisible`](https://zidane.si/docs/reference/chat-pure.md#isVisible) for the settings check.
- `opts?` (`{ byMessage?: boolean }`): `byMessage` makes one stop per visible message.

**Returns** `string[]`

Source: [src/chat/turn-selection.ts:548](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L548)

### `sessionDirLabel`

Function.

The directory name a session lives in — the same basename label the sidebar
groups by. `undefined` for a directory-less session (the main) or no cwd.

```ts
function sessionDirLabel(cwd: string | undefined): string | undefined
```

**Parameters**

- `cwd` (`string | undefined`): The session's working directory.

**Returns** `string | undefined`

Source: [src/chat/orchestration.ts:653](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L653)

### `sessionEventExcerpt`

Function.

The dimmed second line: the last thing the session said, collapsed to one
paragraph and capped. Renderers may clamp further (line-clamp in the GUI,
width in the TUI); this is the upper bound and the shared ellipsis rule.

```ts
function sessionEventExcerpt(event: SessionEvent, max?: number): string
```

**Parameters**

- `event` (`SessionEvent`): The event to excerpt.
- `max?` (`number`, default `240`): Maximum length in characters, counting the ellipsis.

**Returns** `string`

Source: [src/chat/orchestration.ts:706](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L706)

### `sessionEventLabel`

Function.

The short label a transcript row shows: `api-refactor finished`. Status
words are chosen to read as a verb phrase after the title.

```ts
function sessionEventLabel(event: SessionEvent): string
```

**Parameters**

- `event` (`SessionEvent`): The event to label.

**Returns** `string`

Source: [src/chat/orchestration.ts:608](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L608)

### `sessionEventMeta`

Function.

The header's metadata cells, in display order, omitting anything unknown.
Renderers join them with their own separator; the CONTENT is fixed here so
both surfaces show the same receipt for the same run.

The session id is deliberately NOT a cell: it is the least legible datum and
exists only to disambiguate. Renderers append `shortSessionId` LAST and
dimmer than the rest.

```ts
function sessionEventMeta(event: SessionEvent): string[]
```

**Parameters**

- `event` (`SessionEvent`): The event to summarize.

**Returns** `string[]`

Source: [src/chat/orchestration.ts:680](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L680)

### `sessionKey`

Function.

The key of `sessionId` on `hostKey` (`null` / absent / [`LOCAL_HOST_KEY`](https://zidane.si/docs/reference/chat-pure.md#LOCAL_HOST_KEY): a local session).

```ts
function sessionKey(hostKey: string | null | undefined, sessionId: string): string
```

**Parameters**

- `hostKey` (`string | null | undefined`): Key of the host. `null`, absent or the local host key mean This computer.
- `sessionId` (`string`): Session id on that host.

**Returns** `string`

Source: [src/chat/hosts/session-key.ts:43](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/session-key.ts#L43)

### `sessionSpaceFilter`

Function.

The predicate a sessions list filters by, or `null` (no filtering) while
the feature is off. Rows with `isMain` (the orchestration main) belong to
every space and are always kept.

```ts
function sessionSpaceFilter<T extends { isMain?: boolean; spaceId?: string }>(
  settings: SpacesSettings | undefined,
  activeSpaceId: string,
): ((row: T) => boolean) | null
```

**Type parameters**

- `T` (`extends { isMain?: boolean; spaceId?: string }`)

**Parameters**

- `settings` (`SpacesSettings | undefined`): The settings the helpers read.
- `activeSpaceId` (`string`): Id of the space being shown.

**Returns** `((row: T) => boolean) | null`

Source: [src/chat/spaces.ts:305](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L305)

### `settingField`

Function.

Builds the sync field name for a setting.

```ts
function settingField(key: string): string
```

**Parameters**

- `key` (`string`): Setting key.

**Returns** `string`

Source: [src/chat/sync/types.ts:82](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L82)

### `settingKeywords`

Function.

A row's search keywords (`SETTINGS_KEYWORDS`), empty when it has none.

```ts
function settingKeywords(key: string): readonly string[]
```

**Parameters**

- `key` (`string`): Settings key of the row.

**Returns** `readonly string[]`

Source: [src/chat/settings-catalog.ts:199](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L199)

### `settingOfField`

Function.

The setting a field names, if it is one.

```ts
function settingOfField(field: string): string | undefined
```

**Parameters**

- `field` (`string`): Field name such as `setting:approvalMode`.

**Returns** `string | undefined`

Source: [src/chat/sync/types.ts:114](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L114)

### `shellBlockPlan`

Function.

What runs for a block, or `null` when nothing does (another language, no
command, too long). A block with `$ ` lines runs those lines only, without
the prompt, and the lines a trailing \`\` continues them onto: the other
lines are output.

```ts
function shellBlockPlan(
  code: string,
  language: string | undefined,
): ShellBlockPlan | null
```

**Parameters**

- `code` (`string`): The block's text.
- `language` (`string | undefined`): The fence's language.

**Returns** `ShellBlockPlan | null`

Source: [src/chat/shell-blocks.ts:88](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L88)

### `shortAge`

Function.

"now" / "5m" / "3h" / "2d" / "6w": the sidebar's age words.

```ts
function shortAge(ms: number): string
```

**Parameters**

- `ms` (`number`): Elapsed milliseconds.

**Returns** `string`

Source: [src/chat/home-blocks.ts:286](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L286)

### `shortDayLabel`

Function.

"Jun 12" for a `YYYY-MM-DD` day.

```ts
function shortDayLabel(day: string): string
```

**Parameters**

- `day` (`string`): A local `YYYY-MM-DD`.

**Returns** `string`

Source: [src/chat/usage-format.ts:89](https://github.com/Tahul/zidane/blob/main/src/chat/usage-format.ts#L89)

### `shortestGap`

Function.

Schedules: the wire shapes, the checks and the time math that the host,
the TUI and the UI share. The cron math (`./cron`, on `croner`) and the
scheduler (`./scheduler`) are imported by path, so this entry stays free
of them. See docs/SCHEDULES.md.

```ts
function shortestGap(
  trigger: ScheduleTrigger,
  from: number,
  cron?: CronEngine,
  samples?: number,
): number
```

**Parameters**

- `trigger` (`ScheduleTrigger`): A valid trigger.
- `from` (`number`): Epoch ms to start from.
- `cron?` (`CronEngine`): The cron math.
- `samples?` (`number`, default `24`): Fires to compare. A cron like `0,1 9 * * *` packs two fires a minute apart once a day, so look at more than two.

**Returns** `number`

Source: [src/schedules/next-fire.ts:58](https://github.com/Tahul/zidane/blob/main/src/schedules/next-fire.ts#L58)

### `shortId`

Function.

Six-char short form of a session id for headers and lists.

```ts
function shortId(id: string): string
```

**Parameters**

- `id` (`string`): Session id, usually a UUID.

**Returns** `string`

Source: [src/chat/format.ts:195](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L195)

### `shortSessionId`

Function.

Short, stable id fragment for the header — enough to disambiguate, not to read.

```ts
function shortSessionId(id: string): string
```

**Parameters**

- `id` (`string`): Full session id.

**Returns** `string`

Source: [src/chat/orchestration.ts:665](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L665)

### `showsAccount`

Function.

Whether a snapshot should show its account name: only when another snapshot
in the same list belongs to the same provider. One account is the provider.

```ts
function showsAccount(
  snapshot: ProviderUsageSnapshot,
  all: readonly ProviderUsageSnapshot[],
): boolean
```

**Parameters**

- `snapshot` (`ProviderUsageSnapshot`): The snapshot to label.
- `all` (`readonly ProviderUsageSnapshot[]`): Every snapshot on screen.

**Returns** `boolean`

Source: [src/chat/provider-usage-format.ts:129](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L129)

### `sideSessionParent`

Function.

The parent a side session answers about, or `null` for any other session.

```ts
function sideSessionParent(
  metadata: Readonly<Record<string, unknown>> | undefined,
): string | null
```

**Parameters**

- `metadata` (`Readonly<Record<string, unknown>> | undefined`): Session metadata to inspect.

**Returns** `string | null`

Source: [src/chat/orchestration.ts:186](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L186)

### `sliceEnd`

Function.

End of a slice of at most `size` chars from `from`, never between the halves of a surrogate pair.

```ts
function sliceEnd(text: string, from: number, size: number): number
```

**Parameters**

- `text` (`string`): The text being sliced.
- `from` (`number`): Index the slice starts at.
- `size` (`number`): Most characters the slice may hold (at least one is taken).

**Returns** `number`

Source: [src/chat/terminal/output-history.ts:34](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/output-history.ts#L34)

### `smoothCharsForTick`

Function.

Number of characters to drain on the next smooth-mode tick + the
fractional remainder to carry into the next tick.

Combining the CPS curve with a fractional accumulator means the
effective draining rate matches the target CPS exactly. Rounding up
on every tick (`Math.ceil(cps * dt)`) would give 4 chars/tick at
200 CPS / 16ms (= 250 CPS effective), a 25 % speed-up, and visible
step transitions (4 → 5 → 7 → 8 → 10 as backlog grew) that read as
the typewriter cadence jumping.

```ts
function smoothCharsForTick(
  backlog: number,
  carry: number,
  dtMs: number,
): { carry: number; take: number }
```

**Parameters**

- `backlog` (`number`): Chars waiting to reveal.
- `carry` (`number`): The fraction the previous tick left over.
- `dtMs` (`number`): Milliseconds since the previous tick.

**Returns** `{ carry: number; take: number }`

Source: [src/chat/streaming-pure.ts:802](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L802)

### `smoothCpsForBacklog`

Function.

Target chars-per-second for the next smooth-mode tick given the
current bucket backlog. Two linear segments (base→burst over the
first 400 chars, burst→max over the rest of the ramp) so the function
is continuous everywhere and plateaus (rather than cliffs) once backlog
passes [`SMOOTH_MAX_BACKLOG_CHARS`](https://zidane.si/docs/reference/chat-pure.md#SMOOTH_MAX_BACKLOG_CHARS).

```ts
function smoothCpsForBacklog(backlog: number): number
```

**Parameters**

- `backlog` (`number`): Chars waiting to reveal.

**Returns** `number`

Source: [src/chat/streaming-pure.ts:773](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L773)

### `sortRows`

Function.

A sorted copy of `rows`. Stable: rows equal on every key keep their
input order. Rows without a value for a key sort after those with one,
whatever the direction. Throws [`SessionQueryError`](https://zidane.si/docs/reference/chat-pure.md#SessionQueryError) for an invalid sort.

```ts
function sortRows<R extends SessionQueryRow>(
  rows: readonly R[],
  sort: readonly SessionSort[] | undefined,
): R[]
```

**Type parameters**

- `R` (`extends SessionQueryRow`)

**Parameters**

- `rows` (`readonly R[]`): The rows.
- `sort` (`readonly SessionSort[] | undefined`): The keys, most significant first. `undefined` or `[]` keeps the input order.

**Returns** `R[]`

Source: [src/chat/session-query/sort.ts:115](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/sort.ts#L115)

### `spaceIdForNewSession`

Function.

The space id to stamp on a session created while `activeSpaceId` is shown,
or `undefined` (feature off, or Default) — pass it to [`spaceMetadata`](https://zidane.si/docs/reference/chat-pure.md#spaceMetadata).

```ts
function spaceIdForNewSession(
  settings: SpacesSettings | undefined,
  activeSpaceId: string | null | undefined,
): string | undefined
```

**Parameters**

- `settings` (`SpacesSettings | undefined`): The settings the helpers read.
- `activeSpaceId` (`string | null | undefined`): Id of the space being shown.

**Returns** `string | undefined`

Source: [src/chat/spaces.ts:455](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L455)

### `spaceMetadata`

Function.

The metadata entries stamping a session into `spaceId`: none for Default
(an absent id IS Default), so creating in Default writes nothing new.

```ts
function spaceMetadata(spaceId: string | undefined): Record<string, string>
```

**Parameters**

- `spaceId` (`string | undefined`): Space to stamp into.

**Returns** `Record<string, string>`

Source: [src/chat/spaces.ts:322](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L322)

### `spaceModelDefault`

Function.

The default model a new session in `spaceId` starts on, or `undefined`
(feature off, unknown space, or no default set) — the caller then falls
back to its usual last-used model.

```ts
function spaceModelDefault(
  settings: SpacesSettings | undefined,
  spaceId: string | undefined,
): SpaceModelDefault | undefined
```

**Parameters**

- `settings` (`SpacesSettings | undefined`): The settings the helpers read.
- `spaceId` (`string | undefined`): Space the session is created in.

**Returns** `SpaceModelDefault | undefined`

Source: [src/chat/spaces.ts:350](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L350)

### `spaceOfSwitchItem`

Function.

The space a [`spaceSwitchItems`](https://zidane.si/docs/reference/chat-pure.md#spaceSwitchItems) entry switches to; `undefined` for any other id.

```ts
function spaceOfSwitchItem(itemId: string): string | undefined
```

**Parameters**

- `itemId` (`string`): Palette item id.

**Returns** `string | undefined`

Source: [src/chat/spaces.ts:518](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L518)

### `spacesEnabled`

Function.

Feature on? Off by default.

```ts
function spacesEnabled(settings: SpacesSettings | undefined): boolean
```

**Parameters**

- `settings` (`SpacesSettings | undefined`): The settings the helpers read.

**Returns** `boolean`

Source: [src/chat/spaces.ts:282](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L282)

### `spaceSwitchItems`

Function.

The command palette's "Switch to space" entries: one per space but the
shown one. The GUI and the TUI list these same entries, and each runs them
through its own switch ([`spaceOfSwitchItem`](https://zidane.si/docs/reference/chat-pure.md#spaceOfSwitchItem)).

```ts
function spaceSwitchItems(
  spaces: readonly Space[],
  activeSpaceId: string,
  source: string,
): PaletteItem[]
```

**Parameters**

- `spaces` (`readonly Space[]`): The space list.
- `activeSpaceId` (`string`): Id of the space being shown.
- `source` (`string`): Id of the palette provider listing them.

**Returns** `PaletteItem[]`

Source: [src/chat/spaces.ts:500](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L500)

### `spawnLane`

Function.

The worker `childId`'s rows belong under: its outermost ancestor that is
itself one of the `present` workers (the ones owning rows in this view).
A view that already re-based its owner's rows (a worker opened in a fold)
leaves that owner out of `present`, so the owner's direct children become
the lanes there. `childId` itself when no ancestor is present.

```ts
function spawnLane(
  childId: string,
  parents: ReadonlyMap<string, string>,
  present: ReadonlySet<string>,
): string
```

**Parameters**

- `childId` (`string`): The subagent to place.
- `parents` (`ReadonlyMap<string, string>`): Child-to-parent map from [`spawnParents`](https://zidane.si/docs/reference/chat-pure.md#spawnParents).
- `present` (`ReadonlySet<string>`): Ids of subagents that have rows.

**Returns** `string`

Source: [src/chat/spawn-tree.ts:50](https://github.com/Tahul/zidane/blob/main/src/chat/spawn-tree.ts#L50)

### `spawnLaneResolver`

Function.

Lane resolver over one view's rows: precomputes the parent map and the
present-worker set, then maps a row's `childId` to its lane.

```ts
function spawnLaneResolver(rows: readonly SpawnTreeRow[]): (childId: string) => string
```

**Parameters**

- `rows` (`readonly SpawnTreeRow[]`): Transcript rows.

**Returns** `(childId: string) => string`

Source: [src/chat/spawn-tree.ts:66](https://github.com/Tahul/zidane/blob/main/src/chat/spawn-tree.ts#L66)

### `spawnParents`

Function.

Worker id → the worker that spawned it, from nested spawn markers.

```ts
function spawnParents(rows: Iterable<SpawnTreeRow>): Map<string, string>
```

**Parameters**

- `rows` (`Iterable<SpawnTreeRow>`): Transcript rows.

**Returns** `Map<string, string>`

Source: [src/chat/spawn-tree.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/spawn-tree.ts#L29)

### `spawnStartParts`

Function.

A worker's start from its `spawn-start` marker: the task preview, and the
`child-N` it resumes, if any (a badge). Reads `spawn.resumes`, or parses the
`resumes child-2 · <task>` text of a marker recorded before it existed.

```ts
function spawnStartParts(
  event: Pick<StreamEvent, 'text' | 'spawn'>,
): { resumes?: string; task: string }
```

**Parameters**

- `event` (`Pick<StreamEvent, 'text' | 'spawn'>`): The spawn-start marker.

**Returns** `{ resumes?: string; task: string }`

Source: [src/chat/format.ts:122](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L122)

### `splitCommandLine`

Function.

Split a command line into tokens, honoring single/double quotes so
`npx -y my-server --root "/path with spaces"` round-trips. No escape
processing beyond quote grouping — this is a form field, not a shell.

```ts
function splitCommandLine(line: string): string[]
```

**Parameters**

- `line` (`string`): Command line text.

**Returns** `string[]`

Source: [src/chat/mcp-form.ts:158](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L158)

### `splitLines`

Function.

Split a string into lines preserving empty lines but dropping the
implicit trailing `""` produced by a final `\n`. Exported only for
its tests — callers should use `computeLineDiff`.

```ts
function splitLines(s: string): string[]
```

**Parameters**

- `s` (`string`): The text to split.

**Returns** `string[]`

Source: [src/chat/edit-diff.ts:248](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L248)

### `splitMarkdownCodeBlocks`

Function.

Split markdown text into alternating prose / fenced-code segments.

Recognizes both ` ``` ` and `~~~` fences, with arbitrary length ≥ 3,
matching CommonMark's "fence indicator must be at least as long to
close" rule. Info-strings (the bit after the opening fence) are kept
as the `lang` hint; any trailing whitespace is trimmed. Closing
fences are detected on a line of their own (whitespace tolerated).

Unclosed fences fall back to emitting the would-be-code body as a
trailing prose segment so no content is dropped — finalized markdown
isn't expected to ship one, but the fallback keeps the renderer
truthful when the model produces malformed output.

Exported for unit tests.

```ts
function splitMarkdownCodeBlocks(text: string): MarkdownSegment[]
```

**Parameters**

- `text` (`string`): Markdown, possibly mid-stream with an unclosed fence.

**Returns** `MarkdownSegment[]`

**Example**

```ts
import { splitMarkdownCodeBlocks } from 'zidane/chat/pure'

const segments = splitMarkdownCodeBlocks('Run:\n~~~bash\nls\n~~~')
segments.map(s => s.kind) // ['prose', 'code']
```

Source: [src/chat/markdown-segments.ts:64](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L64)

### `splitPromptSegments`

Function.

Split a prompt buffer into word-sized atomic segments suitable for a
flex-row + flex-wrap renderer (TUI) or a `display: inline` flow with
inline-block chips (GUI). Each chip becomes one segment (atomic —
never broken across rows); each plain run is split into "word +
trailing space" units so wraps land at clean word boundaries.

Robust to:

- Overlapping refs — sorted by start; later refs that overlap are
  dropped via the first-wins rule.
- Out-of-bounds refs — dropped entirely when `end > text.length` or
  `start >= text.length`. Partial clipping would silently truncate
  a chip's label; the caller is in a better position to surface the
  mismatch (typically a stale `refs` array referencing a previous text).
- Whitespace-only plain runs — emitted as their own plain segment
  so chip-adjacent-to-chip cases keep the original spacing.

Word splitter rationale: `\S+\s*` keeps trailing whitespace attached
to its preceding word so wrap boundaries land between words (cleanly).
A leading-whitespace-only segment is captured by `\s+` so we don't
drop it entirely when the plain run starts with a space.

```ts
function splitPromptSegments(
  text: string,
  refs: readonly PromptSegmentRef[],
): PromptSegment[]
```

**Parameters**

- `text` (`string`): The prompt text.
- `refs` (`readonly PromptSegmentRef[]`): Chip spans inside `text`. Overlapping or out-of-range spans are dropped.

**Returns** `PromptSegment[]`

Source: [src/chat/prompt-segments.ts:62](https://github.com/Tahul/zidane/blob/main/src/chat/prompt-segments.ts#L62)

### `splitStreamFailure`

Function.

Split a reply into what the model wrote and the stop marker at its end, if any.

```ts
function splitStreamFailure(
  text: string,
): { failure: StreamFailure | null; text: string }
```

**Parameters**

- `text` (`string`): Assistant message text that may end in a failure marker.

**Returns** `{ failure: StreamFailure | null; text: string }`

Source: [src/chat/stream-failure.ts:28](https://github.com/Tahul/zidane/blob/main/src/chat/stream-failure.ts#L28)

### `stepStreamRate`

Function.

Folds one output token reading into the rate state. Returns a new state, or
the same one for an out-of-order or duplicate sample.

```ts
function stepStreamRate(state: RateState, sample: RateSample): RateState
```

**Parameters**

- `state` (`RateState`): The current rate state.
- `sample` (`RateSample`): The newest output token reading.

**Returns** `RateState`

Source: [src/chat/stream-rate.ts:60](https://github.com/Tahul/zidane/blob/main/src/chat/stream-rate.ts#L60)

### `streamRateValue`

Function.

Whole tokens per second for display, or `null` when there is no honest reading.

```ts
function streamRateValue(state: RateState): number | null
```

**Parameters**

- `state` (`RateState`): The current rate state.

**Returns** `number | null`

Source: [src/chat/stream-rate.ts:100](https://github.com/Tahul/zidane/blob/main/src/chat/stream-rate.ts#L100)

### `stripAnsi`

Function.

`text` without its escapes, as a terminal would show it.

```ts
function stripAnsi(text: string): string
```

**Parameters**

- `text` (`string`): Terminal output.

**Returns** `string`

Source: [src/chat/ansi.ts:304](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L304)

### `summarizeEditPayload`

Function.

Build a per-hunk digest used by the compact diff view.

Strategy:

- When `priorContent` is present and the payload describes a real
  file transformation, compute the contextual diff once, then walk
  the LCS ops splitting at runs of `add` / `remove` to anchor each
  summary entry to the **real** file line. This guarantees the
  summary's `L<n>` matches what the user sees in their editor.
- Otherwise, fall back to per-hunk LCS over the (oldString,
  newString) snippet pair. Line numbers are absent because the
  snippet has no file position.

```ts
function summarizeEditPayload(payload: EditPayload): EditSummary
```

**Parameters**

- `payload` (`EditPayload`): The edit payload to summarize.

**Returns** `EditSummary`

Source: [src/chat/edit-diff.ts:577](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L577)

### `summarizeOutcomes`

Function.

Aggregate counts for the transcript's summary badges (`3 applied`,
`1 denied`, `1 skipped`). Exported so renderers don't reimplement the
tally. Pure / O(n).

```ts
function summarizeOutcomes(
  outcomes: readonly EditOutcome[] | undefined,
): { applied: number; denied: number; failed: number; pending: number; skipped: number; total: number }
```

**Parameters**

- `outcomes` (`readonly EditOutcome[] | undefined`): Per-hunk outcomes.

**Returns** `{ applied: number; denied: number; failed: number; pending: number; skipped: number; total: number }`

Source: [src/chat/edit-approval.ts:386](https://github.com/Tahul/zidane/blob/main/src/chat/edit-approval.ts#L386)

### `summarizeTools`

Function.

"Ran a command, read a file +2" for a run of calls. Adjacent identical
phrases merge, so three reads in a row say "read a file" once.
`overflow: false` leaves the +N off, for a header that counts its calls
another way.

```ts
function summarizeTools(
  tools: readonly { displayName: string; name: string }[],
  options?: { overflow?: boolean },
): string
```

**Parameters**

- `tools` (`readonly { displayName: string; name: string }[]`): Tool calls in run order.
- `options?` (`{ overflow?: boolean }`, default `{}`): Set `overflow` to `false` to leave the `+N` count off. Defaults to showing it.

**Returns** `string`

Source: [src/chat/fold-actions.ts:446](https://github.com/Tahul/zidane/blob/main/src/chat/fold-actions.ts#L446)

### `syncAgo`

Function.

When a server last received a push, as the sync status line says it: `12s ago`, `5 min ago`, then a date.

```ts
function syncAgo(at: number | undefined, now?: number): string
```

**Parameters**

- `at` (`number | undefined`): Time of the last push in epoch ms. `undefined` reads as `never`.
- `now?` (`number`): Current time in epoch ms. Default: `Date.now()`.

**Returns** `string`

Source: [src/chat/sync/types.ts:70](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L70)

### `syncMarkerOf`

Function.

The marker a server's settings UI shows next to a setting, if any.

```ts
function syncMarkerOf(
  status: SyncStatus | null | undefined,
  field: string,
): { device: string; kind: 'synced' | 'override' } | null
```

**Parameters**

- `status` (`SyncStatus | null | undefined`): The server's sync status, if loaded.
- `field` (`string`): Field name such as `setting:approvalMode`.

**Returns** `{ device: string; kind: 'synced' | 'override' } | null`

Source: [src/chat/sync/types.ts:196](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L196)

### `takeChars`

Function.

Slice `n` chars off the front of `buf` without splitting a UTF-16
surrogate pair. Most LLM text is ASCII and never trips this; the guard
matters for emoji / extended planes where halving the pair would emit
an isolated half-character.

```ts
function takeChars(buf: string, n: number): { rest: string; taken: string }
```

**Parameters**

- `buf` (`string`): The text to cut.
- `n` (`number`): How many code units to take; `n <= 0` takes nothing.

**Returns** `{ rest: string; taken: string }`

Source: [src/chat/streaming-pure.ts:835](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L835)

### `templateFields`

Function.

The field paths a template reads, in order, once each.

```ts
function templateFields(template: string): string[]
```

**Parameters**

- `template` (`string`): The template.

**Returns** `string[]`

Source: [src/chat/session-query/template.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/template.ts#L19)

### `thoughtLabel`

Function.

A thought's line: "Thinking" while it streams, "Thought" once settled.

```ts
function thoughtLabel(live: boolean): string
```

**Parameters**

- `live` (`boolean`): Whether the thought is still streaming.

**Returns** `string`

Source: [src/chat/fold-rules.ts:164](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L164)

### `tidyPromptText`

Function.

Collapses runs of three or more newlines to one blank line, trims trailing whitespace and remaps the chip spans.

```ts
function tidyPromptText(
  text: string,
  refs: readonly PromptSegmentRef[],
): { refs: PromptSegmentRef[]; text: string }
```

**Parameters**

- `text` (`string`): Stored prompt text.
- `refs` (`readonly PromptSegmentRef[]`): Chip spans over `text`.

**Returns** `{ refs: PromptSegmentRef[]; text: string }`

Source: [src/chat/prompt-text.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/prompt-text.ts#L16)

### `titleFromText`

Function.

A title from typed text (a first message): one line, clipped with `…`. Null when it holds nothing.

```ts
function titleFromText(text: string): string | null
```

**Parameters**

- `text` (`string`): Message text to derive a title from.

**Returns** `string | null`

Source: [src/chat/session-title-text.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/session-title-text.ts#L26)

### `toggleApplies`

Function.

Whether a toggle does anything under the other settings: `showToolAttachments`
only in compact density, the only one with a "Working" row. Renderers leave
the row out while it does not.

```ts
function toggleApplies(
  key: BooleanSettingKey,
  settings: Pick<Settings, 'transcriptDensity'>,
): boolean
```

**Parameters**

- `key` (`BooleanSettingKey`): The toggle's setting.
- `settings` (`Pick<Settings, 'transcriptDensity'>`): The settings to check.

**Returns** `boolean`

Source: [src/chat/settings-catalog.ts:361](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L361)

### `toggleChainEntry`

Function.

Adds `entry` to the end of the chain, or removes it when already present.

```ts
function toggleChainEntry(
  chain: readonly ModelChainEntry[],
  entry: ModelChainEntry,
): ModelChainEntry[]
```

**Parameters**

- `chain` (`readonly ModelChainEntry[]`): The current chain.
- `entry` (`ModelChainEntry`): The pick to toggle.

**Returns** `ModelChainEntry[]`

Source: [src/chat/model-chain.ts:153](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L153)

### `toggleHeldOn`

Function.

Why a toggle is on whatever its own value says: `decisions` while
approvals use Model decision, which needs its answers. Renderers show the
row on and inert with this note. `undefined` when the row's value applies.

```ts
function toggleHeldOn(
  key: BooleanSettingKey,
  settings: Pick<Settings, 'approvalMode'>,
): string | undefined
```

**Parameters**

- `key` (`BooleanSettingKey`): The toggle's setting.
- `settings` (`Pick<Settings, 'approvalMode'>`): The settings to check.

**Returns** `string | undefined`

Source: [src/chat/settings-catalog.ts:349](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L349)

### `toggleKeyed`

Function.

Toggle `entry`: absent → appended, present → removed. Pure.

```ts
function toggleKeyed<T>(chain: readonly T[], entry: T, keyOf: (e: T) => string): T[]
```

**Type parameters**

- `T`

**Parameters**

- `chain` (`readonly T[]`): The current list.
- `entry` (`T`): The element to add, or to remove when its key is already present.
- `keyOf` (`(e: T) => string`): Returns the identity key of an element.

**Returns** `T[]`

Source: [src/chat/model-chain.ts:74](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L74)

### `togglePanel`

Function.

Opens the panel when closed and closes it when open.

```ts
function togglePanel(state: PanelState): PanelState
```

**Parameters**

- `state` (`PanelState`): The current panel state.

**Returns** `PanelState`

Source: [src/chat/panels.ts:244](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L244)

### `tokenComparison`

Function.

`seed` selects the comparison deterministically (day-of-year keeps it
stable within a day but rotating across days). `null` when the total is
too small for the multiple to land (< 2× the work).

```ts
function tokenComparison(totalTokens: number, seed: number): string | null
```

**Parameters**

- `totalTokens` (`number`): The tokens processed.
- `seed` (`number`): Picks the comparison (the day of the year).

**Returns** `string | null`

Source: [src/chat/usage-format.ts:62](https://github.com/Tahul/zidane/blob/main/src/chat/usage-format.ts#L62)

### `tokenize`

Function.

Tokenize on word / non-word boundaries. Each run of `\w+` is one
token; each run of `\W+` (whitespace, punctuation) is another. This
gives the right granularity for renames (`oldName` → `newName`) and
for symbol swaps (`+ → -`) without exploding into per-char segments.

Exported only for its tests.

```ts
function tokenize(s: string): string[]
```

**Parameters**

- `s` (`string`): The text to tokenize.

**Returns** `string[]`

Source: [src/chat/edit-diff.ts:373](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L373)

### `toMachineName`

Function.

A machine name from a free-form one (a server's display name): the valid characters kept, the rest dashed.

```ts
function toMachineName(raw: string): string
```

**Parameters**

- `raw` (`string`): Free-form name, such as a server's display name.

**Returns** `string`

Source: [src/chat/machine-protocol.ts:279](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L279)

### `toolInputCode`

Function.

The source code a tool call runs, for renderers that show it highlighted
instead of the raw JSON input: Codemode's script as JavaScript, a `shell`
/ `bash` command as bash (the command alone: the label carries the
description, the rest is plumbing). `null` for
every other tool and for calls without the code field. `language` is a
fence-style name both highlighters accept (Shiki in the GUI, OpenTUI's
tree-sitter in the TUI).

```ts
function toolInputCode(
  name: string,
  input: Record<string, unknown> | undefined,
): { code: string; language: string } | null
```

**Parameters**

- `name` (`string`): Tool name.
- `input` (`Record<string, unknown> | undefined`): The call's input.

**Returns** `{ code: string; language: string } | null`

Source: [src/chat/tool-formatters.ts:621](https://github.com/Tahul/zidane/blob/main/src/chat/tool-formatters.ts#L621)

### `toolInstall`

Function.

How to install `name` on the host `capabilities` describe: without root
when it can (bun's script, ripgrep's release into \~/.local/bin, Homebrew),
else a root command to copy, else the tool's page. `undefined` for a tool
that is not in [`HOST_TOOLS`](https://zidane.si/docs/reference/chat-pure.md#HOST_TOOLS).

```ts
function toolInstall(
  name: string,
  capabilities: Pick<HostCapabilities, 'os' | 'installers'>,
): ToolInstall | undefined
```

**Parameters**

- `name` (`string`): The tool's name, as in [`HOST_TOOLS`](https://zidane.si/docs/reference/chat-pure.md#HOST_TOOLS).
- `capabilities` (`Pick<HostCapabilities, 'os' | 'installers'>`): The host's OS, architecture and package managers.

**Returns** `ToolInstall | undefined`

Source: [src/chat/capabilities.ts:91](https://github.com/Tahul/zidane/blob/main/src/chat/capabilities.ts#L91)

### `toolOverview`

Function.

The overview line for one tool call.

```ts
function toolOverview(tool: ToolOverviewInput): ToolOverview
```

**Parameters**

- `tool` (`ToolOverviewInput`): Tool call with its name, input, target, result, and edit payload.

**Returns** `ToolOverview`

Source: [src/chat/fold-actions.ts:295](https://github.com/Tahul/zidane/blob/main/src/chat/fold-actions.ts#L295)

### `toolPhrase`

Function.

Returns the lowercase verb phrase for a tool in a batch summary, such as `read a file`.

```ts
function toolPhrase(name: string, displayName: string): string
```

**Parameters**

- `name` (`string`): Tool name.
- `displayName` (`string`): Name shown to the user, used for tools without a known phrase.

**Returns** `string`

Source: [src/chat/fold-actions.ts:426](https://github.com/Tahul/zidane/blob/main/src/chat/fold-actions.ts#L426)

### `transcriptPreset`

Function.

A preset by id.

```ts
function transcriptPreset(id: TranscriptPresetId): TranscriptPreset
```

**Parameters**

- `id` (`TranscriptPresetId`): The preset.

**Returns** `TranscriptPreset`

Source: [src/chat/onboarding/presets.ts:96](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L96)

### `transcriptPresetNotice`

Function.

The line that the palette shows once a preset applies.

```ts
function transcriptPresetNotice(id: TranscriptPresetId): string
```

**Parameters**

- `id` (`TranscriptPresetId`): The preset that applied.

**Returns** `string`

Source: [src/chat/onboarding/presets.ts:193](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L193)

### `transcriptPresetOf`

Function.

The preset a set of settings matches, or `custom` when it matches none.
Keys left out take their default value.

```ts
function transcriptPresetOf(settings: Partial<Settings>): 'custom' | TranscriptPresetId
```

**Parameters**

- `settings` (`Partial<Settings>`): Settings to read, such as the stored ones or a draft.

**Returns** `'custom' | TranscriptPresetId`

**Example**

```ts
import { transcriptPresetOf } from 'zidane/chat/pure'

transcriptPresetOf({}) // 'balanced'
transcriptPresetOf({ showThinking: false }) // 'custom'
```

Source: [src/chat/onboarding/presets.ts:113](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L113)

### `transcriptPresetOfPaletteItem`

Function.

The preset that a row of [`transcriptPresetPalettePicker`](https://zidane.si/docs/reference/chat-pure.md#transcriptPresetPalettePicker) applies.

```ts
function transcriptPresetOfPaletteItem(itemId: string): TranscriptPresetId | undefined
```

**Parameters**

- `itemId` (`string`): The id of the palette row that ran.

**Returns** `TranscriptPresetId | undefined`: The preset, or `undefined` for any other row.

**Example**

```ts
import { transcriptPresetOfPaletteItem } from 'zidane/chat/pure'

transcriptPresetOfPaletteItem('setting:conversation-preset:detailed') // 'detailed'
```

Source: [src/chat/onboarding/presets.ts:181](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L181)

### `transcriptPresetPaletteItem`

Function.

The palette entry for the conversation preset. It names the preset in
effect, and running it opens the presets ([`transcriptPresetPalettePicker`](https://zidane.si/docs/reference/chat-pure.md#transcriptPresetPalettePicker)).

```ts
function transcriptPresetPaletteItem(
  settings: Partial<Settings>,
  source: string,
): PaletteItem
```

**Parameters**

- `settings` (`Partial<Settings>`): The settings in effect.
- `source` (`string`): The id of the palette provider that owns the entry.

**Returns** `PaletteItem`

Source: [src/chat/onboarding/presets.ts:132](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L132)

### `transcriptPresetPalettePicker`

Function.

The list that the palette entry opens: the three presets, the one in effect checked.

```ts
function transcriptPresetPalettePicker(
  settings: Partial<Settings>,
  source: string,
): { items: readonly PaletteItem[]; kind: 'items'; placeholder?: string; title?: string }
```

**Parameters**

- `settings` (`Partial<Settings>`): The settings in effect.
- `source` (`string`): The id of the palette provider that owns the rows.

**Returns** `{ items: readonly PaletteItem[]; kind: 'items'; placeholder?: string; title?: string }`

Source: [src/chat/onboarding/presets.ts:152](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L152)

### `triggerIssues`

Function.

The problems of a trigger.

```ts
function triggerIssues(
  trigger: unknown,
  now: number,
  minIntervalMs?: number,
  cron?: CronEngine,
): ScheduleIssue[]
```

**Parameters**

- `trigger` (`unknown`): What the caller sent.
- `now` (`number`): Epoch ms. An `at` more than a minute before it is refused.
- `minIntervalMs?` (`number`, default `MIN_INTERVAL_MS`): The shortest interval that a recurring trigger can have.
- `cron?` (`CronEngine`): The cron math (the host's `cronEngine`). Absent: a cron trigger's shape only.

**Returns** `ScheduleIssue[]`

Source: [src/schedules/validate.ts:50](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L50)

### `truncateTitle`

Function.

Ellipsize a title to `max` characters; titles are user text and can be a paragraph.

```ts
function truncateTitle(title: string, max?: number): string
```

**Parameters**

- `title` (`string`): Title text. Whitespace runs collapse to one space.
- `max?` (`number`, default `48`): Maximum length in characters, counting the ellipsis.

**Returns** `string`

Source: [src/chat/orchestration.ts:763](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L763)

### `truncateTurnsAt`

Function.

Cut the history at `turnId` (a fork, a rewind, an edited prompt), then
strip any `tool_call` blocks left without a matching `tool_result` in
the slice.

Semantics:

- `inclusive` keeps the selected turn ("branch from HERE": the
  selected message is the latest one); exclusive ends the history just
  before it, so an edited prompt can be sent again in its place.
- If the last kept turn is an assistant turn with unresolved
  `tool_call` blocks (their `tool_result`s live in turns AFTER the
  slice), strip those calls. Otherwise the next provider call would
  post an assistant turn with no matching tool results.
- Drop turns that become empty (all blocks stripped). The result may
  be empty.

Returns `null` when `turnId` doesn't exist in `turns` — caller should
surface a "turn not found" error rather than silently no-op.

```ts
function truncateTurnsAt(
  turns: readonly SessionTurn[],
  turnId: string,
  options?: { inclusive?: boolean },
): SessionTurn[] | null
```

**Parameters**

- `turns` (`readonly SessionTurn[]`): Persisted turns in order.
- `turnId` (`string`): Id of the turn to cut at.
- `options?` (`{ inclusive?: boolean }`, default `{}`): Where the cut falls.

**Returns** `SessionTurn[] | null`

Source: [src/chat/turn-operations.ts:41](https://github.com/Tahul/zidane/blob/main/src/chat/turn-operations.ts#L41)

### `turnAsText`

Function.

Serialize a turn's content to a clean text representation suited for
the clipboard. Joins text + thinking blocks verbatim; tool calls and
tool results get bracketed labels so the user can paste a readable
record of what happened without losing structure.

Empty turns return `''`.

```ts
function turnAsText(turn: SessionTurn): string
```

**Parameters**

- `turn` (`SessionTurn`): The turn to serialize.

**Returns** `string`

Source: [src/chat/turn-operations.ts:190](https://github.com/Tahul/zidane/blob/main/src/chat/turn-operations.ts#L190)

### `turnContextSize`

Function.

Effective context size for a single turn.

`usage.input` is misleading on its own when prompt caching is active: providers
(Anthropic, OpenRouter→Anthropic, Gemini) report `input` as the *new uncached*
tokens only — the cached prefix shows up in `cacheRead`, and newly-cached
tokens in `cacheCreation`. The model still saw all three buckets, so the real
context-window utilization is their sum.

Non-caching providers leave `cacheRead`/`cacheCreation` undefined, so this
collapses to plain `input` for them.

```ts
function turnContextSize(usage: TurnUsage | undefined): number
```

**Parameters**

- `usage` (`TurnUsage | undefined`): Token usage of the turn, if recorded.

**Returns** `number`

Source: [src/chat/streaming-pure.ts:335](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L335)

### `turnSelectionOwnership`

Function.

Build the `resultTurnId → owningAssistantTurnId` map used by the select-
turn mode to coalesce a tool-call's surrounding turns into ONE navigation
stop.

Protocol shape: every `tool_call` block in an assistant turn is closed by
a matching `tool_result` block in the *next* user turn (the agent loop's
history validator depends on this). When the next user turn's only events
are `tool-result`s — i.e. it's pure plumbing for the prior assistant
turn — we map it back to that assistant turn here. The select-turn nav
index ([`selectableTurnIds`](https://zidane.si/docs/reference/chat-pure.md#selectableTurnIds)) skips owned turns, and the renderer's
highlight gate ([`isTurnHighlighted`](https://zidane.si/docs/reference/chat-pure.md#isTurnHighlighted)) extends the selection accent
from the assistant turn to the events of any turn it owns. Net effect:

- Navigation never lands the cursor on a result-only turn whose own
  events may be hidden by `showToolResults: false` — the cursor
  wouldn't be visible.
- Selecting an assistant turn highlights the call AND its result as
  one unit, matching the user's mental model of "one message".

Owner-lookup is conservative: result-only turns with no matching prior
assistant turn (orphaned — usually because the parent was deleted)
stay selectable so the user can act on them via the turn-details modal.

Subagent (`childId` set) events are ignored — they live in a separate
conversation tree.

```ts
function turnSelectionOwnership(events: readonly StreamEvent[]): Map<string, string>
```

**Parameters**

- `events` (`readonly StreamEvent[]`): Transcript events in order.

**Returns** `Map<string, string>`

Source: [src/chat/turn-selection.ts:372](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L372)

### `tutorialOnServer`

Function.

The words of a tutorial on a server's settings page: the lines that name
this computer name the server instead.

```ts
function tutorialOnServer(topic: TutorialTopic, host: string): TutorialWords
```

**Parameters**

- `topic` (`TutorialTopic`): The tutorial.
- `host` (`string`): The server's name.

**Returns** `TutorialWords`

Source: [src/chat/onboarding/tutorials.ts:156](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tutorials.ts#L156)

### `uniqueChatIdsFromReferences`

Function.

Returns the unique ids of the chats referenced in a reference list.
References from other providers are ignored. Order of first appearance is kept.

```ts
function uniqueChatIdsFromReferences(
  references: readonly CompletionReference<unknown>[],
): string[]
```

**Parameters**

- `references` (`readonly CompletionReference<unknown>[]`): References collected from a prompt.

**Returns** `string[]`

Source: [src/chat/completion-chats.ts:266](https://github.com/Tahul/zidane/blob/main/src/chat/completion-chats.ts#L266)

### `uniqueFilesFromReferences`

Function.

Walk a reference list and return the deduplicated set of files in
first-mention order — input to "attach these files to the prompt"
downstream logic.

```ts
function uniqueFilesFromReferences(
  references: readonly CompletionReference<unknown>[],
): FileEntry[]
```

**Parameters**

- `references` (`readonly CompletionReference<unknown>[]`): References collected from a prompt.

**Returns** `FileEntry[]`

Source: [src/chat/completion-files.ts:303](https://github.com/Tahul/zidane/blob/main/src/chat/completion-files.ts#L303)

### `uniqueSkillNamesFromReferences`

Function.

Walk a parsed prompt for skill references and return the deduplicated
list of skill names — input to `agent.activateSkill(name)` calls on
submit.

```ts
function uniqueSkillNamesFromReferences(
  references: readonly CompletionReference<unknown>[],
): string[]
```

**Parameters**

- `references` (`readonly CompletionReference<unknown>[]`): References collected from a prompt.

**Returns** `string[]`

Source: [src/chat/completion-skills.ts:202](https://github.com/Tahul/zidane/blob/main/src/chat/completion-skills.ts#L202)

### `updatedLabel`

Function.

`updated 12s ago` / `updated 3m ago` for the newest snapshot in a list, so a
refresh that returns identical numbers is still visibly a refresh. `null`
when the list is empty.

```ts
function updatedLabel(
  snapshots: readonly ProviderUsageSnapshot[],
  now?: number,
): string | null
```

**Parameters**

- `snapshots` (`readonly ProviderUsageSnapshot[]`): Snapshots to age.
- `now?` (`number`): Epoch milliseconds to measure from.

**Returns** `string | null`

Source: [src/chat/provider-usage-format.ts:223](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L223)

### `upsertToolProgress`

Function.

`events` with `event`, a `tool-progress` state, in place of the one it
replaces (same call, same subagent), or appended. Other events are appended.
A script keeps one progress event, however long it runs.

```ts
function upsertToolProgress<E extends Pick<StreamEvent, 'kind' | 'childId' | 'callId'>>(
  events: readonly E[],
  event: E,
): E[]
```

**Type parameters**

- `E` (`extends Pick<StreamEvent, 'kind' | 'childId' | 'callId'>`)

**Parameters**

- `events` (`readonly E[]`): The transcript so far.
- `event` (`E`): The live event.

**Returns** `E[]`

Source: [src/chat/script-progress.ts:205](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L205)

### `usageBlockContent`

Function.

The usage block's content for a summary: pure, so every host paints the same block.

```ts
function usageBlockContent(
  summary: UsageSummary,
  view: Readonly<Record<string, string | readonly string[]>> | undefined,
  options: { modelName?: (modelId: string) => string; now: Date; project: boolean },
): PanelContent
```

**Parameters**

- `summary` (`UsageSummary`): The summary of the view's range.
- `view` (`Readonly<Record<string, string | readonly string[]>> | undefined`): The panel's view state.
- `options` (`{ modelName?: (modelId: string) => string; now: Date; project: boolean }`): Options.

**Returns** `PanelContent`

Source: [src/chat/home-blocks.ts:82](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L82)

### `usageBlockView`

Function.

The usage block's view: its tab and range, from the control values (unknown ones fall back).

```ts
function usageBlockView(
  view: Readonly<Record<string, string | readonly string[]>> | undefined,
): { range: UsageRange; tab: UsageTab }
```

**Parameters**

- `view` (`Readonly<Record<string, string | readonly string[]>> | undefined`): The panel's view state.

**Returns** `{ range: UsageRange; tab: UsageTab }`

Source: [src/chat/home-blocks.ts:66](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L66)

### `usageHomeBlock`

Function.

The usage block.

```ts
function usageHomeBlock(deps: UsageBlockDeps): ExtensionPanelEntry
```

**Parameters**

- `deps` (`UsageBlockDeps`): Where its numbers come from.

**Returns** `ExtensionPanelEntry`

Source: [src/chat/home-blocks.ts:225](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L225)

### `usageTone`

Function.

Maps a usage percent to a [`UsageTone`](https://zidane.si/docs/reference/chat-pure.md#UsageTone).

```ts
function usageTone(usedPercent: number): UsageTone
```

**Parameters**

- `usedPercent` (`number`): Percent used, from 0 to 100.

**Returns** `UsageTone`

Source: [src/chat/provider-usage-format.ts:192](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L192)

### `validateGroupBy`

Function.

Every problem in a grouping: { field, labels?, order? }.

```ts
function validateGroupBy(value: unknown, path?: string): SessionQueryIssue[]
```

**Parameters**

- `value` (`unknown`): The grouping.
- `path?` (`string`, default `'groupBy'`): The name the issue paths start with. Default `'groupBy'`.

**Returns** `SessionQueryIssue[]`

Source: [src/chat/session-query/validate.ts:244](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L244)

### `validateMcpForm`

Function.

Validate + normalize the raw field values into a config entry.
Returns the first problem in row order so the dialog can surface it.

```ts
function validateMcpForm(
  values: McpFormValues,
): { ok: true; result: McpFormResult } | { error: string; ok: false }
```

**Parameters**

- `values` (`McpFormValues`): Raw form field values.

**Returns** `{ ok: true; result: McpFormResult } | { error: string; ok: false }`

Source: [src/chat/mcp-form.ts:71](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L71)

### `validateQuery`

Function.

Every problem in a query. Empty when `value` is a valid [`SessionQuery`](https://zidane.si/docs/reference/chat-pure.md#SessionQuery).

```ts
function validateQuery(value: unknown, path?: string): SessionQueryIssue[]
```

**Parameters**

- `value` (`unknown`): The query, as an extension or a client gave it.
- `path?` (`string`, default `'where'`): The name the issue paths start with. Default `'where'`.

**Returns** `SessionQueryIssue[]`

Source: [src/chat/session-query/validate.ts:160](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L160)

### `validateScheduleInput`

Function.

Checks a `schedules.create` input. Throws a [`ScheduleInputError`](https://zidane.si/docs/reference/chat-pure.md#ScheduleInputError) that names every problem.

```ts
function validateScheduleInput(
  input: unknown,
  now: number,
  minIntervalMs?: number,
  cron?: CronEngine,
): ScheduleInput
```

**Parameters**

- `input` (`unknown`): What the caller sent.
- `now` (`number`): Epoch ms.
- `minIntervalMs?` (`number`, default `MIN_INTERVAL_MS`): The shortest interval allowed for this caller.
- `cron?` (`CronEngine`): The cron math (the host's `cronEngine`). Absent: a cron trigger's shape only.

**Returns** `ScheduleInput`

Source: [src/schedules/validate.ts:152](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L152)

### `validateSchedulePatch`

Function.

Checks a `schedules.update` patch. Throws a [`ScheduleInputError`](https://zidane.si/docs/reference/chat-pure.md#ScheduleInputError) that names every problem.

```ts
function validateSchedulePatch(
  patch: unknown,
  now: number,
  minIntervalMs?: number,
  cron?: CronEngine,
): SchedulePatch
```

**Parameters**

- `patch` (`unknown`): What the caller sent.
- `now` (`number`): Epoch ms.
- `minIntervalMs?` (`number`, default `MIN_INTERVAL_MS`): The shortest interval allowed for this caller.
- `cron?` (`CronEngine`): The cron math (the host's `cronEngine`). Absent: a cron trigger's shape only.

**Returns** `SchedulePatch`

Source: [src/schedules/validate.ts:176](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L176)

### `validateSort`

Function.

Every problem in a sort: a list of { field, dir? }.

```ts
function validateSort(value: unknown, path?: string): SessionQueryIssue[]
```

**Parameters**

- `value` (`unknown`): The sort.
- `path?` (`string`, default `'sort'`): The name the issue paths start with. Default `'sort'`.

**Returns** `SessionQueryIssue[]`

Source: [src/chat/session-query/validate.ts:213](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L213)

### `validateTemplate`

Function.

Every problem in a template: too long, a lone brace, or a placeholder
that names no field.

```ts
function validateTemplate(value: unknown, path?: string): SessionQueryIssue[]
```

**Parameters**

- `value` (`unknown`): The template.
- `path?` (`string`, default `'template'`): The name the issue paths start with. Default `'template'`.

**Returns** `SessionQueryIssue[]`

Source: [src/chat/session-query/template.ts:35](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/template.ts#L35)

### `viewQuery`

Function.

The query a sidebar view stands for, to save it as a space: the space's
membership (see [`SessionViewSpace`](https://zidane.si/docs/reference/chat-pure.md#SessionViewSpace)), then the project, agent,
archive, activity and extension filters, all holding, flattened. Returns
the problems instead when the result is not a valid query (too deep, too
many nodes or values).

```ts
function viewQuery(input: ViewQueryInput): ViewQueryResult
```

**Parameters**

- `input` (`ViewQueryInput`): The space, the view and the known space ids.

**Returns** `ViewQueryResult`

Source: [src/chat/session-query/view.ts:97](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/view.ts#L97)

### `waitedMs`

Function.

Time spent waiting on the user up to `now`, in ms.

```ts
function waitedMs(wait: RunUserWait | undefined, now: number): number
```

**Parameters**

- `wait` (`RunUserWait | undefined`): The run's waits so far, and since when it waits now; absent: it never waited.
- `now` (`number`): The time to count up to, epoch ms.

**Returns** `number`

Source: [src/chat/run-estimate.ts:122](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L122)

### `withBlockRun`

Function.

The saved runs with `run` in, without runs whose reply is gone, at most
[`BLOCK_RUNS_MAX`](https://zidane.si/docs/reference/chat-pure.md#BLOCK_RUNS_MAX) (the latest kept).

```ts
function withBlockRun(
  runs: Readonly<Record<string, BlockRun>>,
  run: BlockRun,
  turnIds: ReadonlySet<string>,
): Record<string, BlockRun>
```

**Parameters**

- `runs` (`Readonly<Record<string, BlockRun>>`): The saved runs.
- `run` (`BlockRun`): The run to keep (it replaces the block's last one).
- `turnIds` (`ReadonlySet<string>`): The session's turns: a run whose reply is not among them is dropped.

**Returns** `Record<string, BlockRun>`

Source: [src/chat/shell-blocks.ts:232](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L232)

### `withIdTiebreak`

Function.

`sort` with a last `{ field: 'id', dir: 'asc' }` key, unless it already ends
on `id`: a total order, so a page cut by [`paginate`](https://zidane.si/docs/reference/chat-pure.md#paginate) resumes at one place.

```ts
function withIdTiebreak(sort: readonly SessionSort[] | undefined): SessionSort[]
```

**Parameters**

- `sort` (`readonly SessionSort[] | undefined`): The sort keys, most significant first.

**Returns** `SessionSort[]`

Source: [src/chat/session-query/sort.ts:85](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/sort.ts#L85)

### `workedMs`

Function.

Working time of a run up to `now`: its time since start, less its waits on the user.

```ts
function workedMs(startedAt: number, wait: RunUserWait | undefined, now: number): number
```

**Parameters**

- `startedAt` (`number`): When the run started, epoch ms.
- `wait` (`RunUserWait | undefined`): Its waits on the user, as [`waitedMs`](https://zidane.si/docs/reference/chat-pure.md#waitedMs) reads them.
- `now` (`number`): The time to count up to, epoch ms.

**Returns** `number`

Source: [src/chat/run-estimate.ts:135](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L135)

## Classes

### `AmbiguousHostIdError`

Class.

Several hosts list the id (two hosts can hold the same session id: a
server sharing this machine's data dir, a copied store) and the lookup
did not say which: refused, never guessed.

```ts
class AmbiguousHostIdError extends Error
```

**Constructor**

```ts
new AmbiguousHostIdError(id: string, hostKeys: readonly string[], noun?: string)
```

Creates the error.

**Parameters**

- `id` (`string`): Id that several hosts list.
- `hostKeys` (`readonly string[]`): Keys of the hosts that list it.
- `noun?` (`string`, default `'session'`): What the id names, used in the message.

**Returns** `AmbiguousHostIdError`

**Properties**

- `code` (`'ambiguous-host-id'`, readonly, default `'ambiguous-host-id'`): Machine-readable error code.
- `hostKeys` (`readonly string[]`, readonly): Keys of the hosts that list it.
- `id` (`string`, readonly): Id that several hosts list.

Source: [src/chat/hosts/host-index.ts:51](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/host-index.ts#L51)

### `BrowserOpError`

Class.

Error thrown when a browser operation fails. `code` says why.

```ts
class BrowserOpError extends Error
```

**Constructor**

```ts
new BrowserOpError(code: BrowserErrorCode, message: string)
```

Creates a browser operation error.

**Parameters**

- `code` (`BrowserErrorCode`): Reason for the failure.
- `message` (`string`): Human-readable description.

**Returns** `BrowserOpError`

**Properties**

- `code` (`BrowserErrorCode`, readonly): Reason for the failure.

Source: [src/chat/browser/protocol.ts:195](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L195)

### `HostIdentityError`

Class.

A saved host's URL answered with another host id (reinstalled, or the
name now points elsewhere). The connection is closed before anything is
read from it, and nothing is recorded under the saved id.

```ts
class HostIdentityError extends Error
```

**Constructor**

```ts
new HostIdentityError(url: string, answeredBy?: string)
```

Creates the error.

**Parameters**

- `url` (`string`): URL of the saved host.
- `answeredBy?` (`string`): Id of the host that answered instead, when it reported one.

**Returns** `HostIdentityError`

**Properties**

- `answeredBy?` (`string`, readonly): Id of the host that answered instead, when it reported one.
- `url` (`string`, readonly): URL of the saved host.

Source: [src/chat/hosts/connection.ts:28](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/connection.ts#L28)

### `HostRegistryError`

Class.

A refused `add` / `rename`; `code` says why.

```ts
class HostRegistryError extends Error
```

**Constructor**

```ts
new HostRegistryError(code: HostErrorCode, message: string)
```

Creates the error.

**Parameters**

- `code` (`HostErrorCode`): Reason the host was refused.
- `message` (`string`): Human-readable description.

**Returns** `HostRegistryError`

**Properties**

- `code` (`HostErrorCode`, readonly): Reason the host was refused.

Source: [src/chat/hosts/types.ts:64](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/types.ts#L64)

### `HostRemovedError`

Class.

The id lived on a host that was removed from this window.

```ts
class HostRemovedError extends Error
```

**Constructor**

```ts
new HostRemovedError(hostKey: string, hostName: string)
```

Creates the error.

**Parameters**

- `hostKey` (`string`): Key of the removed host.
- `hostName` (`string`): Display name of the removed host.

**Returns** `HostRemovedError`

**Properties**

- `code` (`'host-removed'`, readonly, default `'host-removed'`): Machine-readable error code.
- `hostKey` (`string`, readonly): Key of the removed host.
- `hostName` (`string`, readonly): Display name of the removed host.

Source: [src/chat/hosts/host-index.ts:32](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/host-index.ts#L32)

### `OutputHistory`

Class.

One terminal's output by stream offset, capped, replayable into a fresh terminal with its modes.

```ts
class OutputHistory
```

**Constructor**

```ts
new OutputHistory(maxChars: number, options?: OutputHistoryOptions)
```

**Parameters**

- `maxChars` (`number`): Evict the oldest chunks once more characters than this are kept (the newest chunk always stays).
- `options?` (`OutputHistoryOptions`, default `{}`): Further caps.

**Returns** `OutputHistory`

**Properties**

- `end` (`number`, default `0`): Stream offset after the last chunk.
- `modes` (`ModeState`, readonly): Modes in force after everything pushed (an unfinished trailing sequence not yet applied).
- `size` (`number`, readonly): Characters kept.
- `start` (`number`, readonly): Stream offset of the oldest character kept.

**Methods**

#### `push()`

```ts
push(data: string): void
```

Append output at the current end, then evict past the caps.

**Parameters**

- `data` (`string`): The next output, continuing at `OutputHistory.end`.

#### `replay()`

```ts
replay(lines: number, upTo?: number, maxChars?: number): string
```

What rebuilds the terminal's state up to stream offset `upTo`, keeping
about the last `lines` lines and at most `maxChars` characters of
output: the modes in force at the cut, then the output from there.

**Parameters**

- `lines` (`number`): About how many trailing lines to keep (`Infinity` for all).
- `upTo?` (`number`): Stream offset to replay up to, clamped to `OutputHistory.end`.
- `maxChars?` (`number`, default `Infinity`): Most characters of output to replay.

**Returns** `string`

#### `reset()`

```ts
reset(end: number, data: string): void
```

Start over with `data`, which ends at stream offset `end` (a re-attach).

**Parameters**

- `end` (`number`): Stream offset right after `data`.
- `data` (`string`): The output to start from.

#### `text()`

```ts
text(from?: number, to?: number): string
```

Text kept between stream offsets `from` and `to`.

**Parameters**

- `from?` (`number`): Start offset, clamped to `OutputHistory.start`.
- `to?` (`number`): End offset, clamped to `OutputHistory.end`.

**Returns** `string`

Source: [src/chat/terminal/output-history.ts:74](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/output-history.ts#L74)

### `RemoteHostError`

Class.

Error thrown for a host URL a client refuses.

```ts
class RemoteHostError extends Error
```

**Constructor**

```ts
new RemoteHostError(message: string)
```

Creates the error.

**Parameters**

- `message` (`string`): Human-readable description.

**Returns** `RemoteHostError`

Source: [src/chat/hosts/url.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/url.ts#L13)

### `ScheduleInputError`

Class.

A schedule input that failed the checks. `issues` names every problem.

```ts
class ScheduleInputError extends Error
```

**Constructor**

```ts
new ScheduleInputError(issues: readonly ScheduleIssue[])
```

**Parameters**

- `issues` (`readonly ScheduleIssue[]`): Every problem found.

**Returns** `ScheduleInputError`

**Properties**

- `issues` (`readonly ScheduleIssue[]`, readonly): Every problem found.

Source: [src/schedules/validate.ts:21](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L21)

### `SessionQueryError`

Class.

Thrown by the query functions for an invalid query, sort, grouping, page or cursor.

```ts
class SessionQueryError extends Error
```

**Constructor**

```ts
new SessionQueryError(issues: readonly SessionQueryIssue[])
```

**Parameters**

- `issues` (`readonly SessionQueryIssue[]`): The problems found; the message joins them.

**Returns** `SessionQueryError`

**Properties**

- `issues` (`readonly SessionQueryIssue[]`, readonly): The problems found; the message joins them.

Source: [src/chat/session-query/types.ts:232](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L232)

### `TerminalError`

Class.

Error thrown by terminal operations. `code` says why.

```ts
class TerminalError extends Error
```

**Constructor**

```ts
new TerminalError(
  code: 'limit' | 'failed' | 'unavailable' | 'not_found' | 'not_running',
  message: string,
)
```

Creates a terminal error.

**Parameters**

- `code` (`'limit' | 'failed' | 'unavailable' | 'not_found' | 'not_running'`): Reason for the failure.
- `message` (`string`): Human-readable description.

**Returns** `TerminalError`

**Properties**

- `code` (`'limit' | 'failed' | 'unavailable' | 'not_found' | 'not_running'`, readonly): Reason for the failure.

Source: [src/chat/terminal/protocol.ts:199](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L199)

### `UnknownHostIdError`

Class.

No host told this client about the id: nothing to route it to.

```ts
class UnknownHostIdError extends Error
```

**Constructor**

```ts
new UnknownHostIdError(id: string, noun?: string)
```

Creates the error.

**Parameters**

- `id` (`string`): Id that no host reported.
- `noun?` (`string`, default `'session'`): What the id names, used in the message.

**Returns** `UnknownHostIdError`

**Properties**

- `code` (`'unknown-host-id'`, readonly, default `'unknown-host-id'`): Machine-readable error code.
- `id` (`string`, readonly): Id that no host reported.

Source: [src/chat/hosts/host-index.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/host-index.ts#L17)

## Constants

### `AGENT_MAX_PER_SESSION`

Constant.

The most enabled schedules the agent can have on one session.

```ts
const AGENT_MAX_PER_SESSION = 10
```

Source: [src/schedules/types.ts:173](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L173)

### `AGENT_MIN_INTERVAL_MS`

Constant.

The shortest interval for a recurring schedule that the agent makes.

```ts
const AGENT_MIN_INTERVAL_MS: number
```

Source: [src/schedules/types.ts:171](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L171)

### `AGENT_RECURRING_TTL_MS`

Constant.

How long a recurring schedule that the agent made lives, unless you pin it.

```ts
const AGENT_RECURRING_TTL_MS: number
```

Source: [src/schedules/types.ts:175](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L175)

### `API_KEY_ACCOUNT_LABEL`

Constant.

Name of a provider's API-key credential when listed next to its OAuth accounts.

```ts
const API_KEY_ACCOUNT_LABEL = 'API key'
```

Source: [src/chat/cred-keys.ts:143](https://github.com/Tahul/zidane/blob/main/src/chat/cred-keys.ts#L143)

### `APPROVAL_MODE_OPTIONS`

Constant.

The `approvalMode` options, with what each one does: the one list every settings UI shows.

```ts
const APPROVAL_MODE_OPTIONS: readonly { description: string; label: string; value: ApprovalMode }[]
```

Source: [src/chat/settings-catalog.ts:388](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L388)

### `APPROVAL_MODE_TRADEOFFS`

Constant.

What each approval mode gives you and guards against.

```ts
const APPROVAL_MODE_TRADEOFFS: Readonly<Record<ApprovalMode, OnboardingTradeoff>>
```

Source: [src/chat/onboarding/tradeoffs.ts:11](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tradeoffs.ts#L11)

### `ARTIFACTS_PANEL_ID`

Constant.

Id of the artifacts panel.

```ts
const ARTIFACTS_PANEL_ID = 'artifacts'
```

Source: [src/chat/panels.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L21)

### `ATTACHMENT_SNIFF_BYTES`

Constant.

How much of a file's start [`planAttachment`](https://zidane.si/docs/reference/chat-pure.md#planAttachment) reads to tell text from binary.

```ts
const ATTACHMENT_SNIFF_BYTES = 8192
```

Source: [src/chat/attachment-rules.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L23)

### `BASH_CALL_ID_PREFIX`

Constant.

`callId` prefix minted by the TUI's `!` bash mode (see `runBashMode`
in `src/tui/commands/run-bash-mode.ts`). The prefix is the durable signal — it survives
persistence and replay — that a `shell` tool exchange was USER-initiated,
so renderers can keep it visible even when the tool-display settings
hide model-driven plumbing: the user typed the command and expects to
see it and what it printed.

```ts
const BASH_CALL_ID_PREFIX = 'bash_'
```

Source: [src/chat/turn-selection.ts:86](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L86)

### `BLOCK_RUN_OUTPUT_CAP`

Constant.

Output kept of a run (the end of it), in characters.

```ts
const BLOCK_RUN_OUTPUT_CAP: number
```

Source: [src/chat/shell-blocks.ts:36](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L36)

### `BLOCK_RUN_TIMEOUT_MS`

Constant.

How long a Run here may take.

```ts
const BLOCK_RUN_TIMEOUT_MS: number
```

Source: [src/chat/shell-blocks.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L39)

### `BLOCK_RUNS_MAX`

Constant.

Runs kept per session; the oldest go first.

```ts
const BLOCK_RUNS_MAX = 50
```

Source: [src/chat/shell-blocks.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L42)

### `BLOCK_RUNS_METADATA_KEY`

Constant.

Session metadata key of the saved runs.

```ts
const BLOCK_RUNS_METADATA_KEY = 'blockRuns'
```

Source: [src/chat/shell-blocks.ts:45](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L45)

### `BROWSER_ACTION_TIMEOUT_MS`

Constant.

Default for an action's own wait (element to become actionable, text to appear). A request can raise it up to [`BROWSER_MAX_WAIT_MS`](https://zidane.si/docs/reference/chat-pure.md#BROWSER_MAX_WAIT_MS).

```ts
const BROWSER_ACTION_TIMEOUT_MS = 5_000
```

Source: [src/chat/browser/protocol.ts:208](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L208)

### `BROWSER_EVALUATE_MAX_BYTES`

Constant.

Largest serialized `evaluate` result in bytes.

```ts
const BROWSER_EVALUATE_MAX_BYTES: number
```

Source: [src/chat/browser/protocol.ts:218](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L218)

### `BROWSER_MAX_WAIT_MS`

Constant.

Longest wait in ms an operation may request.

```ts
const BROWSER_MAX_WAIT_MS = 30_000
```

Source: [src/chat/browser/protocol.ts:212](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L212)

### `BROWSER_OPEN_MOUNT_MS`

Constant.

How long the host waits for a page to mount and register before `open` gives up.

```ts
const BROWSER_OPEN_MOUNT_MS = 15_000
```

Source: [src/chat/browser/protocol.ts:214](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L214)

### `BROWSER_OPS`

Constant.

Every browser operation name.

```ts
const BROWSER_OPS: readonly ['open', 'navigate', 'snapshot', 'screenshot', 'click', 'type', 'press', 'scroll', 'wait_for', 'evaluate', 'console']
```

Source: [src/chat/browser/protocol.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L52)

### `BROWSER_OUTLINE_MAX_ELEMENTS`

Constant.

Most elements listed in a snapshot outline.

```ts
const BROWSER_OUTLINE_MAX_ELEMENTS = 250
```

Source: [src/chat/browser/protocol.ts:220](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L220)

### `BROWSER_PANEL_ID`

Constant.

Id of the browser panel.

```ts
const BROWSER_PANEL_ID = 'browser'
```

Source: [src/chat/panels.ts:27](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L27)

### `BROWSER_REQUEST_SLACK_MS`

Constant.

Transport budget on top of the action's own wait.

```ts
const BROWSER_REQUEST_SLACK_MS = 5_000
```

Source: [src/chat/browser/protocol.ts:216](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L216)

### `BROWSER_TEXT_MAX_CHARS`

Constant.

Most page text characters in a snapshot.

```ts
const BROWSER_TEXT_MAX_CHARS = 8_000
```

Source: [src/chat/browser/protocol.ts:222](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L222)

### `BROWSER_WAIT_TIMEOUT_MS`

Constant.

Default wait in ms for `wait_for`.

```ts
const BROWSER_WAIT_TIMEOUT_MS = 10_000
```

Source: [src/chat/browser/protocol.ts:210](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L210)

### `BUILTIN_PANEL_TABS`

Constant.

Built-in panel tabs in display order.

```ts
const BUILTIN_PANEL_TABS: readonly BuiltinPanelTab[]
```

Source: [src/chat/panels.ts:84](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L84)

### `CACHE_HINT_MIN_TOKENS`

Constant.

Below this many re-read tokens a switch is cheap: short sessions show no hint.

```ts
const CACHE_HINT_MIN_TOKENS = 20_000
```

Source: [src/chat/cache-hint.ts:9](https://github.com/Tahul/zidane/blob/main/src/chat/cache-hint.ts#L9)

### `CACHE_NOTICE_LABEL`

Constant.

`notice.label` the host stamps on prompt-cache break/expiry rows (`host/notices/index.ts`).

```ts
const CACHE_NOTICE_LABEL = 'cache'
```

Source: [src/chat/turn-selection.ts:268](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L268)

### `CALIBRATION_MAX`

Constant.

Largest calibration factor: estimates are at most tripled.

```ts
const CALIBRATION_MAX = 3
```

Source: [src/chat/run-estimate.ts:97](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L97)

### `CALIBRATION_MAX_SAMPLES`

Constant.

Most recent finished runs calibration reads, per project.

```ts
const CALIBRATION_MAX_SAMPLES = 50
```

Source: [src/chat/run-estimate.ts:93](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L93)

### `CALIBRATION_MIN`

Constant.

Smallest calibration factor: estimates are at most halved.

```ts
const CALIBRATION_MIN = 0.5
```

Source: [src/chat/run-estimate.ts:95](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L95)

### `CALIBRATION_MIN_SAMPLES`

Constant.

Fewest finished runs before calibration applies.

```ts
const CALIBRATION_MIN_SAMPLES = 5
```

Source: [src/chat/run-estimate.ts:91](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L91)

### `CHATS_TRIGGER`

Constant.

Trigger character that starts a chat reference.

```ts
const CHATS_TRIGGER = '#'
```

Source: [src/chat/completion-chats.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/completion-chats.ts#L20)

### `CLOSED_PLAN_STATES`

Constant.

States a plan never leaves. `stopped` is not one: Resume reopens it.

```ts
const CLOSED_PLAN_STATES: readonly PlanState[]
```

Source: [src/chat/plans.ts:66](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L66)

### `COMMANDS_TRIGGER`

Constant.

Trigger character — shared with skills.

```ts
const COMMANDS_TRIGGER = '/'
```

Source: [src/chat/completion-commands.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/completion-commands.ts#L16)

### `CONNECTOR_CATEGORIES`

Constant.

The step's sections, in display order.

```ts
const CONNECTOR_CATEGORIES: readonly ConnectorCategoryMeta[]
```

Source: [src/chat/onboarding/connectors.ts:164](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L164)

### `CONNECTORS`

Constant.

Every connector, in display order within each category.

```ts
const CONNECTORS: readonly ConnectorEntry[]
```

Source: [src/chat/onboarding/connectors.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L15)

### `CONTINUE_PROMPT`

Constant.

What the "continue" action sends after a run that had done work.

```ts
const CONTINUE_PROMPT = 'Continue from where you stopped.'
```

Source: [src/continue-prompt.ts:2](https://github.com/Tahul/zidane/blob/main/src/continue-prompt.ts#L2)

### `DAEMON_HEALTH_GLYPH`

Constant.

Glyph drawn for the daemon health dot.

```ts
const DAEMON_HEALTH_GLYPH = '●'
```

Source: [src/chat/daemon-health.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/daemon-health.ts#L31)

### `DAEMON_HEALTH_STYLE`

Constant.

Tone and label to use for each [`DaemonHealth`](https://zidane.si/docs/reference/chat-pure.md#DaemonHealth) state.

```ts
const DAEMON_HEALTH_STYLE: Readonly<Record<DaemonHealth, DaemonHealthStyle>>
```

Source: [src/chat/daemon-health.ts:34](https://github.com/Tahul/zidane/blob/main/src/chat/daemon-health.ts#L34)

### `daemonGate`

Constant.

The shared daemon runtime. `ZIDANE_NO_DAEMON=1` is set by
`zidane --no-daemon`.

```ts
const daemonGate: FeatureGate<'useDaemon'>
```

Source: [src/chat/feature-gate.ts:75](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L75)

### `DEFAULT_EXTENSION_SOURCE`

Constant.

The default source of extensions: the zidane repository, whose `extensions/` folder holds the native extensions.

```ts
const DEFAULT_EXTENSION_SOURCE = NATIVE_EXTENSIONS_REPO
```

Source: [src/chat/extension-sources.ts:88](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L88)

### `DEFAULT_EXTENSION_SOURCE_UNREACHABLE`

Constant.

What a listing of the default source says when it cannot be read.

```ts
const DEFAULT_EXTENSION_SOURCE_UNREACHABLE = ...
```

Source: [src/chat/extension-sources.ts:91](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L91)

### `DEFAULT_MODEL_PICK`

Constant.

The model a chat runs on when nothing picks one (no session pick, no descriptor default).

```ts
const DEFAULT_MODEL_PICK: { readonly modelId: 'claude-opus-5-5'; readonly providerKey: 'anthropic' }
```

Source: [src/chat/anthropic-models.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/anthropic-models.ts#L19)

### `DEFAULT_OAUTH_ACCOUNT_LABEL`

Constant.

Name shown for an OAuth account that was never given one.

Also what a first OAuth login is stored under, so a second account has
something to be told apart from. Pre-multi-account files hold unnamed
grants; [`oauthAccountLabel`](https://zidane.si/docs/reference/chat-pure.md#oauthAccountLabel) makes them read the same.

```ts
const DEFAULT_OAUTH_ACCOUNT_LABEL = 'Default'
```

Source: [src/chat/cred-keys.ts:140](https://github.com/Tahul/zidane/blob/main/src/chat/cred-keys.ts#L140)

### `DEFAULT_SECRET_TTL`

Constant.

The TTL a picker selects when the question suggests none.

```ts
const DEFAULT_SECRET_TTL: SecretTtl
```

Source: [src/chat/secrets/protocol.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L19)

### `DEFAULT_SETTINGS`

Constant.

Default value of every setting.

```ts
const DEFAULT_SETTINGS: Settings
```

Source: [src/chat/settings-defaults.ts:8](https://github.com/Tahul/zidane/blob/main/src/chat/settings-defaults.ts#L8)

### `DEFAULT_SPACE_ID`

Constant.

Id of the Default space.

```ts
const DEFAULT_SPACE_ID = 'default'
```

Source: [src/chat/spaces.ts:91](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L91)

### `DEFAULT_SPACE_NAME`

Constant.

Name of the Default space.

```ts
const DEFAULT_SPACE_NAME = 'Default'
```

Source: [src/chat/spaces.ts:93](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L93)

### `DIFFS_PANEL_ID`

Constant.

Id of the diffs panel.

```ts
const DIFFS_PANEL_ID = 'diffs'
```

Source: [src/chat/panels.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L23)

### `DURABILITY_OPTIONS`

Constant.

The `durability` options, with what each one does.

```ts
const DURABILITY_OPTIONS: readonly { description: string; label: string; value: DurabilityMode }[]
```

Source: [src/chat/settings-catalog.ts:401](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L401)

### `EDIT_TOOL_NAMES`

Constant.

Tools whose `tool-result` event is suppressed when `showEditDiffs` is on.

```ts
const EDIT_TOOL_NAMES: ReadonlySet<string>
```

Source: [src/chat/turn-selection.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L17)

### `EMPTY_MODES`

Constant.

The modes of a fresh terminal: nothing set or reset yet.

```ts
const EMPTY_MODES: ModeState
```

Source: [src/contexts/terminal-modes.ts:30](https://github.com/Tahul/zidane/blob/main/src/contexts/terminal-modes.ts#L30)

### `EMPTY_RATE`

Constant.

Initial rate state, before any sample.

```ts
const EMPTY_RATE: RateState
```

Source: [src/chat/stream-rate.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/stream-rate.ts#L42)

### `ENTRY_IMPORT_MAX_BYTES`

Constant.

Most bytes one import brings in, all files together.

```ts
const ENTRY_IMPORT_MAX_BYTES: number
```

Source: [src/chat/workspace/entries.ts:63](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L63)

### `ENTRY_IMPORT_MAX_ENTRIES`

Constant.

Most entries one import brings in.

```ts
const ENTRY_IMPORT_MAX_ENTRIES = 5000
```

Source: [src/chat/workspace/entries.ts:67](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L67)

### `ENTRY_IMPORT_MAX_FILE_BYTES`

Constant.

Most bytes of one imported file (one call over a connection).

```ts
const ENTRY_IMPORT_MAX_FILE_BYTES: number
```

Source: [src/chat/workspace/entries.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L65)

### `ESTIMATE_LEVEL_MINUTES`

Constant.

The score levels, in minutes, lowest first, in 10 steps (the most a score
question may have, `MAX_SCORE_LEVELS`): 1 minute to 24 hours, each about
2.5 times the last, then "more than 24 hours" for runs that go on for
days. That last step stands at 48 hours for the math (an answer between
two marks reads as the time between them); it shows as `24h+`.

```ts
const ESTIMATE_LEVEL_MINUTES: readonly number[]
```

Source: [src/chat/run-estimate.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L26)

### `ESTIMATE_OPEN_ENDED_MINUTES`

Constant.

Past this, a run is in the open-ended last step: "more than 24 hours".

```ts
const ESTIMATE_OPEN_ENDED_MINUTES = 1440
```

Source: [src/chat/run-estimate.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L17)

### `ESTIMATE_OVER_FALLBACK`

Constant.

Without level probabilities, the over point is the estimate times this.

```ts
const ESTIMATE_OVER_FALLBACK = 1.5
```

Source: [src/chat/run-estimate.ts:32](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L32)

### `ESTIMATE_OVER_PERCENTILE`

Constant.

Percentile of the answer's distribution past which a run counts as over its estimate.

```ts
const ESTIMATE_OVER_PERCENTILE = 0.8
```

Source: [src/chat/run-estimate.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L29)

### `EXCLUDED_NATIVE_EXTENSIONS`

Constant.

Folders of `extensions/` left out of the wizard on purpose, with the reason.
Every folder is either listed above or here.

```ts
const EXCLUDED_NATIVE_EXTENSIONS: Readonly<Record<string, string>>
```

Source: [src/chat/onboarding/native-extensions.ts:71](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/native-extensions.ts#L71)

### `FACET_EXTENSION_ID`

Constant.

An extension id, as facet paths name it. A copy of `EXTENSION_ID_PATTERN`
(`src/extensions/runtime/validate-definition.ts`), kept here so this module
stays a pure leaf; a test keeps the two equal.

```ts
const FACET_EXTENSION_ID: RegExp
```

Source: [src/chat/session-query/fields.ts:46](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L46)

### `FACET_KEY`

Constant.

A facet key: a letter or `_`, then up to 63 letters, digits, `_` or `-`. No dots.

```ts
const FACET_KEY: RegExp
```

Source: [src/chat/session-query/fields.ts:49](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L49)

### `FEATURE_GATES`

Constant.

Every gate, so a client can report which kill switches are engaged.

```ts
const FEATURE_GATES: readonly FeatureGate<string>[]
```

Source: [src/chat/feature-gate.ts:88](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L88)

### `FILES_PANEL_ID`

Constant.

Id of the files panel.

```ts
const FILES_PANEL_ID = 'files'
```

Source: [src/chat/panels.ts:25](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L25)

### `FILES_TRIGGER`

Constant.

Trigger character — `@` is the conventional file-mention prefix in chat UIs.

```ts
const FILES_TRIGGER = '@'
```

Source: [src/chat/completion-files.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/completion-files.ts#L23)

### `FIRE_HISTORY`

Constant.

Fires kept per schedule.

```ts
const FIRE_HISTORY = 50
```

Source: [src/schedules/types.ts:177](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L177)

### `HOME_BLOCKS_OWNER`

Constant.

Owner of the built-in blocks.

```ts
const HOME_BLOCKS_OWNER = 'zidane'
```

Source: [src/chat/home-blocks.ts:22](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L22)

### `HOST_TOOLS`

Constant.

The tools probed, in the order the UIs list them. `versionArgs`: what prints the version, when not `--version`.

```ts
const HOST_TOOLS: readonly { icon: string; label: string; name: string; versionArgs?: readonly string[]; why: string }[]
```

Source: [src/chat/capabilities.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/capabilities.ts#L42)

### `INBOX_PANEL_ID`

Constant.

Id of the inbox panel.

```ts
const INBOX_PANEL_ID = 'inbox'
```

Source: [src/chat/panels.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L17)

### `INITIAL_PANEL_STATE`

Constant.

Panel state at startup: closed, no active tab, no user picks.

```ts
const INITIAL_PANEL_STATE: PanelState
```

Source: [src/chat/panels.ts:171](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L171)

### `INSTRUCTION_PREVIEW_LINE_CAP`

Constant.

Upper bound on preview lines rendered for one expanded segment. Same idea as
the Logs tab's `LOGS_RENDER_CAP`: the scrollbox can hold arbitrary height, but pasting a
runaway 64KB instruction file into the layout pass is a waste of a frame.
File-backed segments have `$EDITOR` as the escape hatch for the remainder.

```ts
const INSTRUCTION_PREVIEW_LINE_CAP = 400
```

Source: [src/chat/instruction-rows.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/instruction-rows.ts#L21)

### `LASTING_ESTIMATE_FAILURES`

Constant.

Failure reasons the next attempt would hit again: the request or the
setup is wrong. A timeout, a rate limit or a network error is retried at
the next trigger instead, and shows nothing.

```ts
const LASTING_ESTIMATE_FAILURES: ReadonlySet<string>
```

Source: [src/chat/run-estimate.ts:189](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L189)

### `LOCAL_HOST_KEY`

Constant.

This computer's key in every host directory (the in-process host, the embedded one, or the daemon).

```ts
const LOCAL_HOST_KEY = 'local'
```

Source: [src/chat/hosts/connection.ts:9](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/connection.ts#L9)

### `LOCAL_HOST_NAME`

Constant.

This computer's label in lists and pickers.

```ts
const LOCAL_HOST_NAME = 'This computer'
```

Source: [src/chat/hosts/connection.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/connection.ts#L12)

### `LOCAL_SERVER_BRANDS`

Constant.

The logo of each local model server the wizard looks for.

```ts
const LOCAL_SERVER_BRANDS: Readonly<Record<OnboardingLocalServer['kind'], string>>
```

Source: [src/chat/onboarding/brands.ts:35](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/brands.ts#L35)

### `LOCAL_SERVER_NAMES`

Constant.

The name of each local model server that the wizard finds.

```ts
const LOCAL_SERVER_NAMES: Readonly<Record<OnboardingLocalServer['kind'], string>>
```

Source: [src/chat/onboarding/words.ts:22](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L22)

### `LOG_LEVEL_CYCLE`

Constant.

The cycle order the `l` key walks through — coarsest last so it wraps back to "everything".

```ts
const LOG_LEVEL_CYCLE: readonly LogLevel[]
```

Source: [src/chat/logs-view.ts:14](https://github.com/Tahul/zidane/blob/main/src/chat/logs-view.ts#L14)

### `MACHINE_LINK_STATE_TEXT`

Constant.

Display text for each [`MachineLinkState`](https://zidane.si/docs/reference/chat-pure.md#MachineLinkState).

```ts
const MACHINE_LINK_STATE_TEXT: Record<MachineLinkState, string>
```

Source: [src/chat/machines-view.ts:145](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L145)

### `MACHINE_NOTICE_LABEL`

Constant.

The `label` of the notices a host emits about a session's machine.

```ts
const MACHINE_NOTICE_LABEL = 'machine'
```

Source: [src/chat/machines-view.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L12)

### `MARKDOWN_RENDER_CHUNK_TARGET_BYTES`

Constant.

Default per-chunk target for [`chunkMarkdownForRender`](https://zidane.si/docs/reference/chat-pure.md#chunkMarkdownForRender). Chosen from
measurement: marked's lexer (which OpenTUI's `<markdown>` runs
internally) is O(n²) over paragraph-heavy input — \~500ms at 64KiB,
\~2s at 128KiB, \~6s at 256KiB on an M-series laptop — while staying
comfortably in the linear zone below \~32KiB (≤ \~200ms). Chunking a
large document into ≤24KiB pieces keeps the total render linear in
document size with a small constant.

```ts
const MARKDOWN_RENDER_CHUNK_TARGET_BYTES = 24_576
```

Source: [src/chat/markdown-segments.ts:291](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L291)

### `MAX_CURSOR_LENGTH`

Constant.

The longest cursor [`paginate`](https://zidane.si/docs/reference/chat-pure.md#paginate) accepts. Bounds every cursor it makes: up to 9 keys of at most [`MAX_SORT_TEXT`](https://zidane.si/docs/reference/chat-pure.md#MAX_SORT_TEXT) characters.

```ts
const MAX_CURSOR_LENGTH = 32_768
```

Source: [src/chat/session-query/paginate.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/paginate.ts#L15)

### `MAX_FILE_ATTACHMENT_BYTES`

Constant.

Cap on a PDF's or a text file's bytes.

```ts
const MAX_FILE_ATTACHMENT_BYTES: number
```

Source: [src/chat/attachment-rules.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L20)

### `MAX_IMAGE_ATTACHMENT_BYTES`

Constant.

Cap on an image's bytes. Base64 inflates \~33%, so this keeps the encoded
payload under Anthropic's 5 MB image ceiling while covering essentially
every screenshot. A composer scales a bigger image down to fit.

```ts
const MAX_IMAGE_ATTACHMENT_BYTES: number
```

Source: [src/chat/attachment-rules.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L17)

### `MAX_NAME_CHARS`

Constant.

Longest name.

```ts
const MAX_NAME_CHARS = 120
```

Source: [src/schedules/types.ts:181](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L181)

### `MAX_PAGE_SIZE`

Constant.

The largest page [`paginate`](https://zidane.si/docs/reference/chat-pure.md#paginate) hands out.

```ts
const MAX_PAGE_SIZE = 1000
```

Source: [src/chat/session-query/paginate.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/paginate.ts#L12)

### `MAX_PLAUSIBLE_RATE`

Constant.

Faster than any served model today (the fastest wafer-scale ones run \~3k): a reading above is a glitch.

```ts
const MAX_PLAUSIBLE_RATE = 6000
```

Source: [src/chat/stream-rate.ts:49](https://github.com/Tahul/zidane/blob/main/src/chat/stream-rate.ts#L49)

### `MAX_PROMPT_CHARS`

Constant.

Longest prompt text.

```ts
const MAX_PROMPT_CHARS: number
```

Source: [src/schedules/types.ts:179](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L179)

### `MAX_QUERY_DEPTH`

Constant.

How deep `all` / `any` / `not` may nest.

```ts
const MAX_QUERY_DEPTH = 16
```

Source: [src/chat/session-query/validate.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L13)

### `MAX_QUERY_LIST`

Constant.

How many values one `in` / `nin` may list.

```ts
const MAX_QUERY_LIST = 256
```

Source: [src/chat/session-query/validate.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L17)

### `MAX_QUERY_NODES`

Constant.

How many nodes (conditions and combinators) one query may hold.

```ts
const MAX_QUERY_NODES = 512
```

Source: [src/chat/session-query/validate.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L15)

### `MAX_QUERY_STRING`

Constant.

How long a string value may be.

```ts
const MAX_QUERY_STRING = 1024
```

Source: [src/chat/session-query/validate.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L21)

### `MAX_QUERY_VALUES`

Constant.

How many `in` / `nin` values one query may list in total.

```ts
const MAX_QUERY_VALUES = 1024
```

Source: [src/chat/session-query/validate.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L19)

### `MAX_SCHEDULES`

Constant.

Most schedules one host stores.

```ts
const MAX_SCHEDULES = 500
```

Source: [src/schedules/types.ts:183](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L183)

### `MAX_SESSION_FACETS_BYTES`

Constant.

The most JSON one session's facet values may take together, in bytes of their JSON text.

```ts
const MAX_SESSION_FACETS_BYTES: number
```

Source: [src/session/facets.ts:22](https://github.com/Tahul/zidane/blob/main/src/session/facets.ts#L22)

### `MAX_SORT_KEYS`

Constant.

How many keys a sort may have.

```ts
const MAX_SORT_KEYS = 8
```

Source: [src/chat/session-query/validate.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/validate.ts#L23)

### `MAX_SORT_TEXT`

Constant.

How many characters of a text value sort (and travel in a cursor).

```ts
const MAX_SORT_TEXT = 256
```

Source: [src/chat/session-query/sort.ts:63](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/sort.ts#L63)

### `MAX_TEMPLATE_LENGTH`

Constant.

How long a template may be.

```ts
const MAX_TEMPLATE_LENGTH = 500
```

Source: [src/chat/session-query/template.ts:10](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/template.ts#L10)

### `MAX_TRANSCRIPT_EVENTS`

Constant.

Display-layer transcript bounds. Each rendered event holds live React
fibers + OpenTUI renderables + native text buffers even when scrolled
off-screen — measured at roughly 0.13 MB RSS per markdown-heavy event —
so an uncapped multi-thousand-event session (a normal working day with
tool calls) climbs into the hundreds of MB and eventually OOM/thrash.

The cap bounds ONLY what is materialized on screen: session turns on
disk are complete, and switching sessions / re-activating replays the
most recent window again. Trimming happens at TURN boundaries so a
turn's rows are never orphaned, and re-caps fold into one cumulative
marker rather than stacking markers.

```ts
const MAX_TRANSCRIPT_EVENTS = 1_500
```

Source: [src/chat/streaming-pure.ts:356](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L356)

### `MCP_KEY_REFUSED_HINT`

Constant.

What to do about a refused key, under the "Key refused" headline.

```ts
const MCP_KEY_REFUSED_HINT = 'Check the headers in mcps.json.'
```

Source: [src/chat/mcp-test-outcome.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-test-outcome.ts#L31)

### `MCP_OAUTH_NOTE`

Constant.

Shown with the MCP category: OAuth tokens stay where they were made.

```ts
const MCP_OAUTH_NOTE: 'MCP sign-ins stay on this computer. Sign in again on the server.'
```

Source: [src/chat/sync/types.ts:62](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L62)

### `MCP_STATUS_LABEL`

Constant.

The status words both apps show for a server, so the desktop app's badge
and the TUI's read the same. `idle` says nothing.

```ts
const MCP_STATUS_LABEL: Readonly<Record<Exclude<McpAuthStatus['kind'], 'idle'>, string>>
```

Source: [src/chat/mcp-auth-state.ts:75](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-auth-state.ts#L75)

### `MCP_TRANSPORTS`

Constant.

Every [`McpTransport`](https://zidane.si/docs/reference/chat-pure.md#McpTransport) in the order a form lists them.

```ts
const MCP_TRANSPORTS: readonly McpTransport[]
```

Source: [src/chat/mcp-form.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L20)

### `MEDIA_BY_EXTENSION`

Constant.

The media types by lowercase file extension.

```ts
const MEDIA_BY_EXTENSION: Readonly<Record<string, MediaType>>
```

Source: [src/chat/workspace/media-type.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/media-type.ts#L17)

### `MESSAGE_DELIVERY_OPTIONS`

Constant.

The `messageDelivery` options, with what each one does: the one list that settings and the setup wizard show.

```ts
const MESSAGE_DELIVERY_OPTIONS: readonly { description: string; label: string; value: MessageDelivery }[]
```

Source: [src/chat/settings-catalog.ts:395](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L395)

### `MESSAGE_DELIVERY_TRADEOFFS`

Constant.

What each "Messages during a run" choice of Conversation gives you and guards against.

```ts
const MESSAGE_DELIVERY_TRADEOFFS: Readonly<Record<MessageDelivery, OnboardingTradeoff>>
```

Source: [src/chat/onboarding/tradeoffs.ts:27](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tradeoffs.ts#L27)

### `METHOD_NOT_FOUND`

Constant.

JSON-RPC "method not found": the host predates an additive method.

```ts
const METHOD_NOT_FOUND: number
```

Source: [src/chat/hosts/connection.ts:41](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/connection.ts#L41)

### `MIN_INTERVAL_MS`

Constant.

The shortest interval for `every`, and between two cron times, for a schedule that a person or an extension makes.

```ts
const MIN_INTERVAL_MS = 60_000
```

Source: [src/schedules/types.ts:169](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L169)

### `nameFromModelId`

Constant.

The name from the id alone, for a surface without the provider catalogs.

```ts
const nameFromModelId: ModelNamer
```

Source: [src/chat/run-receipt.ts:195](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L195)

### `NATIVE_EXTENSION_GROUPS`

Constant.

The step's sections, in display order.

```ts
const NATIVE_EXTENSION_GROUPS: readonly NativeExtensionGroupMeta[]
```

Source: [src/chat/onboarding/native-extensions.ts:87](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/native-extensions.ts#L87)

### `NATIVE_EXTENSIONS`

Constant.

Every native extension, in display order within each group.

```ts
const NATIVE_EXTENSIONS: readonly NativeExtensionEntry[]
```

Source: [src/chat/onboarding/native-extensions.ts:14](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/native-extensions.ts#L14)

### `NATIVE_EXTENSIONS_REPO`

Constant.

The GitHub repository native extensions install from.

```ts
const NATIVE_EXTENSIONS_REPO = 'Tahul/zidane'
```

Source: [src/chat/onboarding/native-extensions.ts:11](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/native-extensions.ts#L11)

### `NOTICE_GLYPH`

Constant.

Leading glyph per severity. `info` is deliberately quiet: a plain `i`, single-width in every terminal.

```ts
const NOTICE_GLYPH: Readonly<Record<NoticeSeverity, string>>
```

Source: [src/chat/notice-format.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/notice-format.ts#L15)

### `ONBOARDING_AGENT_BRANDS`

Constant.

The logo of each agent whose setup the wizard reads. Pi has none.

```ts
const ONBOARDING_AGENT_BRANDS: Readonly<Record<OnboardingAgentId, string | undefined>>
```

Source: [src/chat/onboarding/brands.ts:28](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/brands.ts#L28)

### `ONBOARDING_AGENT_NAMES`

Constant.

The name of each agent whose setup the wizard reads.

```ts
const ONBOARDING_AGENT_NAMES: Readonly<Record<OnboardingAgentId, string>>
```

Source: [src/chat/onboarding/words.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L15)

### `ONBOARDING_FEATURE_GROUPS`

Constant.

The step's sections, in display order.

```ts
const ONBOARDING_FEATURE_GROUPS: readonly OnboardingFeatureGroupMeta[]
```

Source: [src/chat/onboarding/features.ts:157](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/features.ts#L157)

### `ONBOARDING_FEATURES`

Constant.

Every feature the step can offer, in display order.

```ts
const ONBOARDING_FEATURES: readonly OnboardingFeature[]
```

Source: [src/chat/onboarding/features.ts:18](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/features.ts#L18)

### `ONBOARDING_PREVIEW_ATTACHMENTS`

Constant.

The files attached to the preview prompt: a chart of the traffic and the
team's notes. The events carry their names. An app that draws them supplies
the bytes, matched by name.

```ts
const ONBOARDING_PREVIEW_ATTACHMENTS: readonly { mediaType: string; name: string; size: number }[]
```

Source: [src/chat/onboarding/preview.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/preview.ts#L31)

### `ONBOARDING_PREVIEW_EVENTS`

Constant.

The preview conversation, as the transcript renders it.

```ts
const ONBOARDING_PREVIEW_EVENTS: readonly StreamEvent[]
```

Source: [src/chat/onboarding/preview.ts:37](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/preview.ts#L37)

### `ONBOARDING_SETTING_KEYS`

Constant.

Every setting the wizard can change.

```ts
const ONBOARDING_SETTING_KEYS: readonly keyof Settings[]
```

Source: [src/chat/onboarding/flow.ts:48](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L48)

### `ONBOARDING_STEP_SETTINGS`

Constant.

The settings each step edits. Skipping a step puts them back.

```ts
const ONBOARDING_STEP_SETTINGS: Partial<Record<OnboardingStepId, readonly keyof Settings[]>>
```

Source: [src/chat/onboarding/flow.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L39)

### `ONBOARDING_STEPS`

Constant.

Every step in flow order, with what it writes and its copy.

```ts
const ONBOARDING_STEPS: readonly OnboardingStepMeta[]
```

Source: [src/chat/onboarding/steps.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/steps.ts#L16)

### `ONBOARDING_VERSION`

Constant.

Version of the wizard, stored in each record it writes. A record from an
older version still counts as done: existing users open new steps from
Settings or the palette, never on their own.

```ts
const ONBOARDING_VERSION = 1
```

Source: [src/chat/onboarding/steps.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/steps.ts#L13)

### `ONBOARDING_WORDS`

Constant.

The sentences that both apps say word for word, in English.

```ts
const ONBOARDING_WORDS: { agentName: (agent: OnboardingAgentId) => string; background: string; browseFailed: (message: string) => string; browsing: (source: string) => string; changeLater: string; credentialsAt: (path: string) => string; custom: string; detecting: string; effort: string; effortHint: string; found: string; foundAgent: (agent: OnboardingAgentId) => string; foundEnvKey: (envKey: string) => string; foundGithub: (login: string | undefined, source: string) => string; foundLocalServer: (server: OnboardingLocalServer) => string; foundSaved: (provider: string) => string; foundSignedIn: (provider: string) => string; fromRepo: (repo: string) => string; fullSetup: string; importAgents: string; importAllProjects: string; importCommands: string; importMcps: string; importNames: (list: readonly string[]) => string; importSessions: string; importSessionsDetail: (project: number, all: number) => string; importSkills: string; importSkipped: (count: number) => string; listingTruncated: string; localFound: (server: OnboardingLocalServer) => string; model: string; moreProviders: string; needsAccount: (account: string) => string; needsCommand: (name: string, optional: boolean) => string; needsConnector: (connector: string) => string; needsDecisions: string; noSkills: string; noSkillsHint: string; packHint: string; prevents: string; preview: string; quickStart: string; readInPlaceDetail: string; recapNone: string; recapProvider: (provider: string, model?: string) => string; recapSwitched: (on: readonly string[], off: readonly string[]) => string; recommendedSources: string; sandboxed: string; skillCount: (count: number) => string; sourcePlaceholder: string; spendCap: string; spendCapDetail: string; testing: string; tutorialOnServer: (topic: TutorialTopic, host: string) => TutorialWords; tutorials: Readonly<Record<TutorialTopic, TutorialWords>>; unlocks: string }
```

Source: [src/chat/onboarding/words.ts:53](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L53)

### `ORCHESTRATED_BY_KEY`

Constant.

`session.metadata.orchestratedBy` — the creating orchestrator session's id, on a worker.

```ts
const ORCHESTRATED_BY_KEY = 'orchestratedBy'
```

Source: [src/chat/orchestration.ts:32](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L32)

### `PALETTE_LIMITS`

Constant.

Caps applied by [`normalizePaletteItems`](https://zidane.si/docs/reference/chat-pure.md#normalizePaletteItems): item count, text length and keyword count.

```ts
const PALETTE_LIMITS: { readonly items: 500; readonly keywords: 16; readonly textChars: 500 }
```

Source: [src/chat/palette.ts:425](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L425)

### `PALETTE_RECENT_GROUP`

Constant.

Group name the hosts use for the most-recently-used rows shown on an empty query.

```ts
const PALETTE_RECENT_GROUP = 'Recent'
```

Source: [src/chat/palette.ts:110](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L110)

### `PALETTE_RECENTS_MAX`

Constant.

Maximum number of recent item ids kept.

```ts
const PALETTE_RECENTS_MAX = 12
```

Source: [src/chat/palette.ts:112](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L112)

### `PALETTE_RESULT_MAX`

Constant.

Ranked rows returned for a query; the host virtualises anyway, this bounds the work.

```ts
const PALETTE_RESULT_MAX = 200
```

Source: [src/chat/palette.ts:114](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L114)

### `PROVIDER_BRANDS`

Constant.

The logo of each built-in provider, by provider key.

```ts
const PROVIDER_BRANDS: Readonly<Record<string, string>>
```

Source: [src/chat/onboarding/brands.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/brands.ts#L12)

### `QUEUE_PANEL_ID`

Constant.

Id of the queue panel: messages sent during a run, waiting for it to end (the desktop app only).

```ts
const QUEUE_PANEL_ID = 'queue'
```

Source: [src/chat/panels.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L19)

### `RECENT_SESSIONS_BLOCK_ID`

Constant.

The recent sessions block's panel id.

```ts
const RECENT_SESSIONS_BLOCK_ID = 'zidane/recent-sessions'
```

Source: [src/chat/home-blocks.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L26)

### `REMINDERS_PANEL_ID`

Constant.

Reminders: prompts set to reach the session at a set time (only while `Settings.schedules` is on).

```ts
const REMINDERS_PANEL_ID = 'reminders'
```

Source: [src/chat/panels.ts:35](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L35)

### `remoteHostsGate`

Constant.

Remote hosts (zidane-server). The setting ("Remote hosts")
gates the saved servers: the Hosts settings, the per-host session groups
and picking a host for a new session. Connecting through an explicit `--host` /
`ZIDANE_HOST_URL` is its own opt-in, but `ZIDANE_NO_REMOTE=1` still wins
over it (`src/tui/host-target.ts`). `ZIDANE_NO_REMOTE=1` is set by
`zidane --no-remote`.

```ts
const remoteHostsGate: FeatureGate<'remoteHosts'>
```

Source: [src/chat/feature-gate.ts:85](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L85)

### `RUN_RECEIPT_GLYPH`

Constant.

The glyph that leads the line on every surface.

```ts
const RUN_RECEIPT_GLYPH = '≡'
```

Source: [src/chat/run-receipt.ts:236](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L236)

### `RUN_RECEIPT_SWITCH_GLYPH`

Constant.

Leads the agent when the run switched to it from the previous run's.

```ts
const RUN_RECEIPT_SWITCH_GLYPH = '⇄'
```

Source: [src/chat/run-receipt.ts:58](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L58)

### `RUN_RECEIPT_TURN_GLYPH`

Constant.

Leads the turn count: one cycle = one model round trip.

```ts
const RUN_RECEIPT_TURN_GLYPH = '↻'
```

Source: [src/chat/run-receipt.ts:55](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L55)

### `RUN_STATUS_TIME_MS`

Constant.

From when a status shows how long it has lasted. Shorter waits are
routine (a model's first token often takes a few seconds), so they show
no clock.

```ts
const RUN_STATUS_TIME_MS = 5000
```

Source: [src/chat/run-activity.ts:118](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L118)

### `RUN_WAITING_DELAY_MS`

Constant.

How long the tail must read `waiting` before a surface says so, so the
gap between a tool call and the next turn never flashes it. The TUI and
the desktop app use the same value.

```ts
const RUN_WAITING_DELAY_MS = 1500
```

Source: [src/chat/run-activity.ts:24](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L24)

### `RUN_WAITING_LABEL`

Constant.

The header text while the run waits on the model. Both apps show these words.

```ts
const RUN_WAITING_LABEL = 'Waiting for the model'
```

Source: [src/chat/run-activity.ts:137](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L137)

### `SCHEDULE_METADATA_KEY`

Constant.

Metadata key on a session that a schedule created, and on the queued prompt of a fire.

```ts
const SCHEDULE_METADATA_KEY = 'scheduleId'
```

Source: [src/schedules/types.ts:185](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L185)

### `SCHEDULE_ORIGIN_SOURCE`

Constant.

`TextOrigin.source` of a fire's prompt.

```ts
const SCHEDULE_ORIGIN_SOURCE = 'schedule'
```

Source: [src/schedules/types.ts:187](https://github.com/Tahul/zidane/blob/main/src/schedules/types.ts#L187)

### `SCRIPT_OUTPUT_LINE_CHARS`

Constant.

Characters kept per output line.

```ts
const SCRIPT_OUTPUT_LINE_CHARS = 240
```

Source: [src/chat/script-progress.ts:61](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L61)

### `SCRIPT_OUTPUT_TAIL_LINES`

Constant.

Output lines a progress state keeps.

```ts
const SCRIPT_OUTPUT_TAIL_LINES = 8
```

Source: [src/chat/script-progress.ts:59](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L59)

### `SECRET_NAME_PATTERN`

Constant.

A secret name: an env-var style identifier, also the file name in the store.

```ts
const SECRET_NAME_PATTERN: RegExp
```

Source: [src/chat/secrets/protocol.ts:55](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L55)

### `SECRET_TTLS`

Constant.

Every [`SecretTtl`](https://zidane.si/docs/reference/chat-pure.md#SecretTtl), in the order a picker shows them.

```ts
const SECRET_TTLS: readonly SecretTtl[]
```

Source: [src/chat/secrets/protocol.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L16)

### `SECRETS_PANEL_ID`

Constant.

The saved secrets of the session's project (only while `Settings.secrets` is on).

```ts
const SECRETS_PANEL_ID = 'secrets'
```

Source: [src/chat/panels.ts:33](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L33)

### `SENDABLE_IMAGE_TYPES`

Constant.

Image types every provider takes as they are.

```ts
const SENDABLE_IMAGE_TYPES: ReadonlySet<string>
```

Source: [src/chat/attachment-rules.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L26)

### `SESSION_ACCOUNT_METADATA_KEY`

Constant.

Session metadata key of the pinned account (next to `providerKey` / `modelId`).

```ts
const SESSION_ACCOUNT_METADATA_KEY = 'account'
```

Source: [src/chat/model-chain-metadata.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain-metadata.ts#L29)

### `SESSION_EVENT_STATUS_STYLE`

Constant.

Status → how it reads. `needs-attention` is deliberately the loudest: it is
the one status where the human, not the main, has to act.

```ts
const SESSION_EVENT_STATUS_STYLE: Readonly<Record<SessionEventStatus, SessionEventStatusStyle>>
```

Source: [src/chat/orchestration.ts:640](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L640)

### `SESSION_FACETS_METADATA_KEY`

Constant.

The metadata key holding a session's facet values. Namespaced: the flat session metadata also holds keys like `cwd` and `archived`.

```ts
const SESSION_FACETS_METADATA_KEY = 'zidane.facets'
```

Source: [src/session/facets.ts:16](https://github.com/Tahul/zidane/blob/main/src/session/facets.ts#L16)

### `SESSION_FIELDS`

Constant.

Every row field a query can read, with its type.

```ts
const SESSION_FIELDS: Readonly<Record<SessionFieldName, SessionFieldType>>
```

Source: [src/chat/session-query/fields.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L12)

### `SESSION_KEY_SEPARATOR`

Constant.

Character that separates the host key from the session id in a session key (U+001F).

```ts
const SESSION_KEY_SEPARATOR = '\u001F'
```

Source: [src/chat/hosts/session-key.ts:27](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/session-key.ts#L27)

### `SESSION_ROLE_KEY`

Constant.

`session.metadata.role` — present and `'main'` on the one orchestrating session.

```ts
const SESSION_ROLE_KEY = 'role'
```

Source: [src/chat/orchestration.ts:30](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L30)

### `SESSION_SCOPE`

Constant.

The scope of top-level runs. A sub-agent run's scope is its run id.

```ts
const SESSION_SCOPE = 'session'
```

Source: [src/chat/plans.ts:41](https://github.com/Tahul/zidane/blob/main/src/chat/plans.ts#L41)

### `SETTING_TRADEOFFS`

Constant.

What the safety settings of Autonomy and Bring your setup give you and guard against.

```ts
const SETTING_TRADEOFFS: Readonly<Partial<Record<keyof Settings, OnboardingTradeoff>>>
```

Source: [src/chat/onboarding/tradeoffs.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tradeoffs.ts#L39)

### `SETTINGS_CHOICES`

Constant.

Every option-valued setting the settings UI lists, in display order.

```ts
const SETTINGS_CHOICES: readonly SettingsChoice[]
```

Source: [src/chat/settings-catalog.ts:408](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L408)

### `SETTINGS_TOGGLES`

Constant.

Every boolean setting the settings UI lists, in display order.

```ts
const SETTINGS_TOGGLES: readonly SettingsToggle[]
```

Source: [src/chat/settings-catalog.ts:212](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L212)

### `SETUP_PALETTE_ITEM`

Constant.

"Run setup", the palette entry both apps list to open the wizard again.

```ts
const SETUP_PALETTE_ITEM: SetupPaletteItem
```

Source: [src/chat/onboarding/steps.ts:98](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/steps.ts#L98)

### `SHELL_BLOCK_MAX_CHARS`

Constant.

Longest block that runs, in characters.

```ts
const SHELL_BLOCK_MAX_CHARS: number
```

Source: [src/chat/shell-blocks.ts:33](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L33)

### `SHELL_FENCE_LANGUAGES`

Constant.

Fence languages that run.

```ts
const SHELL_FENCE_LANGUAGES: ReadonlySet<string>
```

Source: [src/chat/shell-blocks.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L17)

### `SIDE_PANEL_ID`

Constant.

A `/side` chat about the session (the desktop app only).

```ts
const SIDE_PANEL_ID = 'side'
```

Source: [src/chat/panels.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L31)

### `SKILLS_TRIGGER`

Constant.

Trigger character — slash-commands convention.

```ts
const SKILLS_TRIGGER = '/'
```

Source: [src/chat/completion-skills.ts:24](https://github.com/Tahul/zidane/blob/main/src/chat/completion-skills.ts#L24)

### `SMOOTH_BASE_CPS`

Constant.

Smooth reveal rate (chars a second) while almost nothing waits.

```ts
const SMOOTH_BASE_CPS = 200
```

Source: [src/chat/streaming-pure.ts:756](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L756)

### `SMOOTH_MAX_BACKLOG_CHARS`

Constant.

Backlog (chars) at and past which the smooth reveal runs at [`SMOOTH_MAX_CPS`](https://zidane.si/docs/reference/chat-pure.md#SMOOTH_MAX_CPS).

```ts
const SMOOTH_MAX_BACKLOG_CHARS = 4000
```

Source: [src/chat/streaming-pure.ts:762](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L762)

### `SMOOTH_MAX_CPS`

Constant.

Smooth reveal rate (chars a second) once the backlog reaches [`SMOOTH_MAX_BACKLOG_CHARS`](https://zidane.si/docs/reference/chat-pure.md#SMOOTH_MAX_BACKLOG_CHARS).

```ts
const SMOOTH_MAX_CPS = 4000
```

Source: [src/chat/streaming-pure.ts:760](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L760)

### `SPACE_METADATA_KEY`

Constant.

Session metadata key holding the space id.

```ts
const SPACE_METADATA_KEY = 'spaceId'
```

Source: [src/chat/spaces.ts:95](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L95)

### `STREAMING_MARKDOWN_SEGMENT_CHARS`

Constant.

Default segment bound for a growing streaming markdown event. Coalescing
copies the ENTIRE accumulated string into fresh state on every drain tick,
so one long streamed message costs O(L²) aggregate — past this threshold
the event is split and the copy re-bounded. The split reuses
[`chunkMarkdownForRender`](https://zidane.si/docs/reference/chat-pure.md#chunkMarkdownForRender) (blank-line boundaries outside fences,
unsafe-continuation guard), so the finalized segments are byte-identical
to the chunks the renderer would have produced inside a single event, and
the one-row markdown/markdown margin stands in for the consumed blank line
exactly like the renderer's inter-chunk gap. When no safe boundary exists
(one giant fence/list) the event keeps growing until one arrives.

```ts
const STREAMING_MARKDOWN_SEGMENT_CHARS: number
```

Source: [src/chat/streaming-pure.ts:85](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L85)

### `SYNC_CATEGORIES`

Constant.

In the order the UIs list them.

```ts
const SYNC_CATEGORIES: readonly SyncCategory[]
```

Source: [src/chat/sync/types.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L20)

### `SYNC_CATEGORY_INFO`

Constant.

What each category is called and carries, for both UIs.

```ts
const SYNC_CATEGORY_INFO: Readonly<Record<SyncCategory, { description: string; label: string }>>
```

Source: [src/chat/sync/types.ts:38](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L38)

### `SYNC_MODE_LABEL`

Constant.

Display label for each sync mode.

```ts
const SYNC_MODE_LABEL: Readonly<Record<SyncMode, string>>
```

Source: [src/chat/sync/types.ts:55](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L55)

### `SYNC_MODES`

Constant.

Every sync mode, in the order the UIs list them.

```ts
const SYNC_MODES: readonly SyncMode[]
```

Source: [src/chat/sync/types.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L52)

### `SYSTEM_MD_FIELD`

Constant.

Sync field name of the user-scope SYSTEM.md file.

```ts
const SYSTEM_MD_FIELD = 'system-md'
```

Source: [src/chat/sync/types.ts:84](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L84)

### `TERMINAL_HISTORY_MAX_CHARS`

Constant.

History kept per terminal for new views (characters).

```ts
const TERMINAL_HISTORY_MAX_CHARS: number
```

Source: [src/chat/terminal/protocol.ts:177](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L177)

### `TERMINAL_MAX_PER_SCOPE`

Constant.

Terminals a session, a project or a draft may have open at once (user terminals).

```ts
const TERMINAL_MAX_PER_SCOPE = 12
```

Source: [src/chat/terminal/protocol.ts:191](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L191)

### `TERMINAL_MAX_PER_SESSION`

Constant, deprecated.

**Deprecated.** Use [`TERMINAL_MAX_PER_SCOPE`](https://zidane.si/docs/reference/chat-pure.md#TERMINAL_MAX_PER_SCOPE).

Terminals a session, a project or a draft may have open at once.

```ts
const TERMINAL_MAX_PER_SESSION = TERMINAL_MAX_PER_SCOPE
```

Source: [src/chat/terminal/protocol.ts:196](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L196)

### `TERMINAL_OUTPUT_WINDOW`

Constant.

Characters a client may be behind before the host stops sending to it.

```ts
const TERMINAL_OUTPUT_WINDOW: number
```

Source: [src/chat/terminal/protocol.ts:175](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L175)

### `TERMINAL_PANEL_ID`

Constant.

Id of the terminal panel.

```ts
const TERMINAL_PANEL_ID = 'terminal'
```

Source: [src/chat/panels.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L29)

### `TERMINAL_READ_MAX_CHARS`

Constant.

Most the agent gets from one read (characters).

```ts
const TERMINAL_READ_MAX_CHARS: number
```

Source: [src/chat/terminal/protocol.ts:189](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L189)

### `TERMINAL_TEXT_MAX_LINES`

Constant.

Plain-text lines kept per terminal for the agent.

```ts
const TERMINAL_TEXT_MAX_LINES = 5000
```

Source: [src/chat/terminal/protocol.ts:187](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L187)

### `TERMINAL_VIEW_MAX_LINES`

Constant.

Lines a desktop view can show (its scrollback, plus a screen of up to
1000 rows): what it asks `terminal.attach` for (`maxLines`) and what it
keeps of the output it drew.

```ts
const TERMINAL_VIEW_MAX_LINES: number
```

Source: [src/chat/terminal/protocol.ts:185](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L185)

### `TERMINAL_VIEW_SCROLLBACK`

Constant.

Scrollback lines a desktop terminal view keeps (each mounted view holds its own).

```ts
const TERMINAL_VIEW_SCROLLBACK = 5_000
```

Source: [src/chat/terminal/protocol.ts:179](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L179)

### `TODO_STATUS_GLYPHS`

Constant.

Glyph shown for each todo status.

```ts
const TODO_STATUS_GLYPHS: Readonly<Record<TodoStatus, string>>
```

Source: [src/chat/todo-glyphs.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/todo-glyphs.ts#L17)

### `TOOL_DISPLAY`

Constant.

Display metadata for the built-in tools, keyed by tool name.

```ts
const TOOL_DISPLAY: Readonly<Record<string, ToolDisplayMeta>>
```

Source: [src/chat/tool-formatters.ts:89](https://github.com/Tahul/zidane/blob/main/src/chat/tool-formatters.ts#L89)

### `TRANSCRIPT_PRESET_KEYS`

Constant.

Every setting a conversation preset sets, in the order the fine-tuning lists them.

```ts
const TRANSCRIPT_PRESET_KEYS: readonly TranscriptPresetKey[]
```

Source: [src/chat/onboarding/presets.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L13)

### `TRANSCRIPT_PRESET_PALETTE_ID`

Constant.

The id of the palette entry for the conversation preset. Both apps use it.

```ts
const TRANSCRIPT_PRESET_PALETTE_ID = 'setting:conversation-preset'
```

Source: [src/chat/onboarding/presets.ts:120](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L120)

### `TRANSCRIPT_PRESETS`

Constant.

The three presets, from the quietest to the most complete. Built by a pure call, so a bundle that never reads them drops them and the settings they read.

```ts
const TRANSCRIPT_PRESETS: readonly TranscriptPreset[]
```

Source: [src/chat/onboarding/presets.ts:36](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/presets.ts#L36)

### `TRANSCRIPT_TRIM_TO_EVENTS`

Constant.

Post-trim size — the hysteresis gap keeps re-trims O(rare), not per-append.

```ts
const TRANSCRIPT_TRIM_TO_EVENTS = 1_200
```

Source: [src/chat/streaming-pure.ts:358](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L358)

### `TUTORIAL_TOPICS`

Constant.

Every tutorial, in the order the docs list them.

```ts
const TUTORIAL_TOPICS: readonly TutorialTopic[]
```

Source: [src/chat/onboarding/tutorials.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tutorials.ts#L39)

### `TUTORIALS`

Constant.

The words of each tutorial.

```ts
const TUTORIALS: Readonly<Record<TutorialTopic, TutorialWords>>
```

Source: [src/chat/onboarding/tutorials.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tutorials.ts#L42)

### `USAGE_BLOCK_ID`

Constant.

The usage block's panel id.

```ts
const USAGE_BLOCK_ID = 'zidane/usage'
```

Source: [src/chat/home-blocks.ts:24](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L24)

### `WORKER_REPORT_FRAGMENT`

Constant.

System-prompt fragment appended to every WORKER's agent. A worker's last
message becomes the main's `summary`, so it must be a report, not a sign-off
— the main should be able to act on it without reading the transcript.

```ts
const WORKER_REPORT_FRAGMENT = ...
```

Source: [src/chat/orchestration.ts:773](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L773)

## Interfaces

### `ActiveTrigger`

Interface.

Identified active trigger span. Returned by `findActiveTrigger` so
callers can show the popover, query the provider, and on commit replace
the span with the selected item's `insertText`.

```ts
interface ActiveTrigger<TItem = unknown>
```

**Type parameters**

- `TItem` (default `unknown`)

**Properties**

- `provider` (`CompletionProvider<TItem>`): The provider bound to the active trigger character.
- `query` (`string`): Substring after the trigger, up to the cursor. Empty if cursor sits right after the trigger.
- `span` (`{ end: number; start: number }`): `[start, end)` — span covered by the trigger + query in the source.

Source: [src/chat/completion-core.ts:177](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L177)

### `AnsiLines`

Interface.

Reads terminal output in chunks, as lines of styled spans.

```ts
interface AnsiLines
```

**Properties**

- `partial` (`() => AnsiSpan[]`): The line being written, not ended yet.
- `push` (`(chunk: string) => AnsiSpan[][]`): Feeds a chunk; returns the lines it completed, without their newlines.

Source: [src/chat/ansi.ts:43](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L43)

### `AnsiSpan`

Interface.

Text in one style. `style` is absent for plain text.

```ts
interface AnsiSpan
```

**Properties**

- `style?` (`AnsiStyle`): Its style, absent for plain text.
- `text` (`string`): The text, without escapes.

Source: [src/chat/ansi.ts:35](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L35)

### `AnsiStyle`

Interface.

How a span of text is drawn. Absent fields are the default.

```ts
interface AnsiStyle
```

**Properties**

- `bg?` (`AnsiColor`): Background color.
- `bold?` (`true`): Bold (SGR 1).
- `dim?` (`true`): Faint (SGR 2).
- `fg?` (`AnsiColor`): Text color.
- `inverse?` (`true`): Foreground and background swapped.
- `italic?` (`true`): Italic (SGR 3).
- `underline?` (`true`): Underlined (SGR 4).

Source: [src/chat/ansi.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L17)

### `AttachmentCandidate`

Interface.

A file a composer was handed, as [`planAttachment`](https://zidane.si/docs/reference/chat-pure.md#planAttachment) needs it.

```ts
interface AttachmentCandidate
```

**Properties**

- `head` (`string`): The file's first [`ATTACHMENT_SNIFF_BYTES`](https://zidane.si/docs/reference/chat-pure.md#ATTACHMENT_SNIFF_BYTES) bytes decoded as UTF-8, invalid bytes as U+FFFD.
- `mediaType` (`string`): The type the browser or the OS reported. Often empty.
- `name` (`string`): The file's name. Its extension stands in for a missing type.
- `size` (`number`): Size in bytes.

Source: [src/chat/attachment-rules.ts:49](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L49)

### `AuthMethod`

Interface.

One credential source detected for a provider.

```ts
interface AuthMethod
```

**Properties**

- `active?` (`boolean`): True for the credential every reader actually resolves.

  Exactly one STORED credential is active: the one in the canonical file key
  (see `alternateCredKey`). A provider can hold an API key and any number of
  OAuth accounts, so the list alone does not say which one wins. `env` is
  never marked active — it is an observable signal, not a stored credential
  the user can promote.

  Optional so hosts that build `ProviderAuth` themselves (this type is public
  via `zidane/chat`) keep compiling; absent reads as "not active".
  [`detectAuth`](https://zidane.si/docs/reference/chat.md#detectAuth) always sets it.
- `detail` (`string`): Human-readable detail: the env var name, the credentials file, or an
  OAuth grant's expiry. The OAuth account name is in `label`, not here.
- `email?` (`string`): Email of a stored OAuth account, when known (see `backfillAccountEmails`).
- `id?` (`string`): Stable id of a STORED credential (`ProviderCredential.id`): unlike
  `key`, it does not move when another account is promoted. What a
  session pinned to this account stores. Absent for `env`, and for an entry
  written before ids until its next write.
- `integration?` (`{ account: string; id: string }`): Set for a connection of the provider's integration
  (`ProviderDescriptor.integration`): sign it in, out or make it the
  default through the integration, not the provider's credential slots
  (such a method has no `key`). `id` is its account.
- `key?` (`string`): Credentials-file key of a STORED credential — the identity to hand to
  `setPreferredCredential({ key })` / `removeStoredCredential`. Several OAuth
  accounts share `source: 'oauth'`, so `source` alone does not select one.
  Absent for `env`.
- `label?` (`string`): Account name — always set for stored OAuth credentials: the user-given one,
  or `DEFAULT_OAUTH_ACCOUNT_LABEL` when the grant was never named.
- `source` (`'oauth' | 'apikey' | 'env'`): Where the credential comes from: an environment variable, a stored OAuth grant, or a stored API key.

Source: [src/chat/auth.ts:18](https://github.com/Tahul/zidane/blob/main/src/chat/auth.ts#L18)

### `BlockRun`

Interface.

The last run of a block, as the session keeps it.

```ts
interface BlockRun
```

**Properties**

- `durationMs` (`number`): How long it ran.
- `exitCode` (`number | null`): `null` when it was stopped or could not start.
- `finishedAt` (`number`): When it ended, epoch milliseconds.
- `key` (`string`): [`blockRunKey`](https://zidane.si/docs/reference/chat-pure.md#blockRunKey) of the block.
- `output` (`string`): What it wrote, stdout and stderr in arrival order, raw (ANSI codes kept): the last [`BLOCK_RUN_OUTPUT_CAP`](https://zidane.si/docs/reference/chat-pure.md#BLOCK_RUN_OUTPUT_CAP) characters.
- `stopped?` (`'cancelled' | 'timeout'`): Why it ended early.
- `truncated?` (`true`): Output was cut at its start.
- `turnId` (`string`): The reply the block is in: a run whose reply is gone is dropped.

Source: [src/chat/shell-blocks.ts:158](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L158)

### `BlockRunRequest`

Interface.

What a window asks the host to run.

```ts
interface BlockRunRequest
```

**Properties**

- `code` (`string`): The block's text.
- `language` (`string`): The fence's language.
- `turnId` (`string`): The reply the block is in.

Source: [src/chat/shell-blocks.ts:148](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L148)

### `BrowserChange`

Interface.

What changed on the page because of an action; the agent reads this instead of re-snapshotting every step.

```ts
interface BrowserChange
```

**Properties**

- `dialog?` (`{ handled: 'accepted' | 'dismissed'; message: string; type: string }`): A JavaScript dialog the page opened, and what was done with it.
- `errors?` (`string[]`): Console errors and failed requests since the action started.
- `refsStale?` (`boolean`): The page navigated or changed a lot: refs from the last snapshot may be gone.
- `target?` (`string`): The element acted on, by its accessible name (or tag when it has none).
- `title?` (`string`): Page title after the action.
- `url?` (`string`): Page URL after the action.

Source: [src/chat/browser/protocol.ts:79](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L79)

### `BrowserConsoleEntry`

Interface.

One console message or failed request.

```ts
interface BrowserConsoleEntry
```

**Properties**

- `level` (`'error' | 'info' | 'debug' | 'warning' | 'log'`): Severity of the message.
- `seq` (`number`): Sequence number, increasing per entry.
- `text` (`string`): Message text.
- `url?` (`string`): Set for failed network requests.

Source: [src/chat/browser/protocol.ts:95](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L95)

### `BrowserOpInputs`

Interface.

Input of each browser operation, keyed by operation name.

```ts
interface BrowserOpInputs
```

**Properties**

- `click` (`BrowserTarget & { timeoutMs?: number }`): Clicks a target, waiting until it is actionable.
- `console` (`{ level?: 'error' | 'all' | 'warning'; since?: number }`): Reads console messages, optionally only newer than `since` and filtered by `level`.
- `evaluate` (`{ expression: string }`): Runs a JavaScript expression in the page.
- `navigate` (`{ action?: 'reload' | 'back' | 'forward'; timeoutMs?: number; url?: string; waitUntil?: BrowserWaitUntil }`): Goes to a URL, or back, forward or reload.
- `open` (`{ show?: boolean; url?: string }`): Opens the browser, optionally at a URL, and optionally shows its tab.
- `press` (`{ key: string; modifiers?: ('Alt' | 'Control' | 'Meta' | 'Shift')[] }`): Presses a key with optional modifiers.
- `screenshot` (`{ ref?: string }`): Captures the viewport, or one element named by `ref`.
- `scroll` (`BrowserTarget & { dx?: number; dy?: number }`): Scrolls the page or a target by `dx` and `dy` CSS pixels.
- `snapshot` (`Record<string, never>`): Reads the page. Takes no input.
- `type` (`BrowserTarget & { clear?: boolean; submit?: boolean; text: string; timeoutMs?: number }`): Types text into a target, optionally clearing it first or submitting after.
- `wait_for` (`{ selector?: string; text?: string; timeoutMs?: number; urlIncludes?: string }`): Waits for text, a selector or a URL fragment to appear.

Source: [src/chat/browser/protocol.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L23)

### `BrowserOpResults`

Interface.

Result of each browser operation, keyed by operation name.

```ts
interface BrowserOpResults
```

**Properties**

- `click` (`BrowserChange`): What the click changed.
- `console` (`{ entries: BrowserConsoleEntry[]; next: number }`): Console entries and the cursor to pass as `since` next time.
- `evaluate` (`{ value: unknown }`): The value the expression produced.
- `navigate` (`BrowserStatus`): Status after navigating.
- `open` (`BrowserStatus`): Status after opening.
- `press` (`BrowserChange`): What the key press changed.
- `screenshot` (`BrowserScreenshot`): The captured image.
- `scroll` (`BrowserChange & { scrollX?: number; scrollY?: number }`): What scrolling changed, with the resulting scroll offsets.
- `snapshot` (`BrowserSnapshot`): The page snapshot.
- `type` (`BrowserChange`): What typing changed.
- `wait_for` (`BrowserStatus`): Status once the wait condition held.

Source: [src/chat/browser/protocol.ts:135](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L135)

### `BrowserRequest`

Interface.

A browser operation sent from the agent to the process that owns the page.

```ts
interface BrowserRequest<O extends BrowserOp = BrowserOp>
```

**Type parameters**

- `O` (`extends BrowserOp`, default `BrowserOp`)

**Properties**

- `input` (`BrowserOpInputs[O]`): Input for the operation.
- `op` (`O`): Operation to run.
- `requestId` (`string`): Id that pairs the response with this request.
- `sessionId` (`string`): Session the operation belongs to.
- `timeoutMs` (`number`): Total time in ms the caller waits for the response.

Source: [src/chat/browser/protocol.ts:176](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L176)

### `BrowserScreenshot`

Interface.

A captured image of the viewport or of one element.

```ts
interface BrowserScreenshot
```

**Properties**

- `data` (`string`): Base64 JPEG.
- `height` (`number`): Image height in pixels.
- `mediaType` (`'image/jpeg'`): MIME type of `data`.
- `scale` (`number`): Image pixels per CSS pixel: divide image coordinates by this to click.
- `width` (`number`): Image width in pixels.

Source: [src/chat/browser/protocol.ts:121](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L121)

### `BrowserSnapshot`

Interface.

A readable view of the page: status, element outline and visible text.

```ts
interface BrowserSnapshot
```

**Properties**

- `errors` (`string[]`): Recent console errors and failed requests.
- `outline` (`string`): One line per interactive or landmark element, `[ref=eN]` on the ones you can act on.
- `status` (`BrowserStatus`): Where the page is.
- `text` (`string`): Visible page text, capped at [`BROWSER_TEXT_MAX_CHARS`](https://zidane.si/docs/reference/chat-pure.md#BROWSER_TEXT_MAX_CHARS) characters.
- `truncated` (`number`): Elements left out because of the cap.

Source: [src/chat/browser/protocol.ts:107](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L107)

### `BrowserStatus`

Interface.

Where the page is: its URL, title and loading state.

```ts
interface BrowserStatus
```

**Properties**

- `loading` (`boolean`): Whether the page is still loading.
- `title` (`string`): Current page title.
- `url` (`string`): Current page URL.
- `viewport?` (`{ height: number; width: number }`): Viewport size in CSS pixels, when known.

Source: [src/chat/browser/protocol.ts:67](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L67)

### `BrowserTarget`

Interface.

A target on the page: a snapshot ref (preferred), a CSS selector / `text=` / `role=` locator, or a point.

```ts
interface BrowserTarget
```

**Properties**

- `ref?` (`string`): Ref from the latest snapshot, such as `e12`.
- `selector?` (`string`): CSS selector, or a `text=` or `role=` locator.
- `x?` (`number`): Viewport x coordinate in CSS pixels. Used with `y`.
- `y?` (`number`): Viewport y coordinate in CSS pixels. Used with `x`.

Source: [src/chat/browser/protocol.ts:8](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L8)

### `BuildVisibleInstructionRowsOptions`

Interface.

Options for [`buildVisibleInstructionRows`](https://zidane.si/docs/reference/chat-pure.md#buildVisibleInstructionRows).

```ts
interface BuildVisibleInstructionRowsOptions
```

**Properties**

- `expanded` (`ReadonlySet<string>`): Segment ids the user has expanded.
- `matchSegment` (`(segment: ContextSegment) => boolean`): Whether a segment matches the query. Ignored when `queryActive` is false.
- `queryActive` (`boolean`): True when a search query is active.
- `segments` (`readonly ContextSegment[]`): Segments to list, in display order.

Source: [src/chat/instruction-rows.ts:32](https://github.com/Tahul/zidane/blob/main/src/chat/instruction-rows.ts#L32)

### `BuiltinPanelTab`

Interface.

A tab for a panel the host renders itself.

```ts
interface BuiltinPanelTab
```

**Properties**

- `builtin` (`true`): Discriminant that marks a built-in tab.
- `icon` (`PanelIcon`): Icon for each renderer.
- `id` (`BuiltinPanelId`): Built-in panel id.
- `label` (`string`): Tab label.

Source: [src/chat/panels.ts:51](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L51)

### `CacheChipContent`

Interface.

Content of the prompt-cache chip. Built by [`cacheBreakChip`](https://zidane.si/docs/reference/chat-pure.md#cacheBreakChip).

```ts
interface CacheChipContent
```

**Properties**

- `glyph` (`string`): Leading glyph. Kept out of `label` so a surface can style it separately.
- `label` (`string`): Chip text after the glyph: `cache break in system: +41.6k tok, ~$0.48`. Plain, because the TUI shows it in a hint slot.
- `tone` (`CacheChipTone`): Severity: `warn` for an avoidable break, `dim` for an ordinary expiry.

Source: [src/chat/footer-chips.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L29)

### `CatalogEntry`

Interface.

A model entry as displayed in the cross-provider picker.

```ts
interface CatalogEntry
```

**Properties**

- `account?` (`Pick<ProviderAccount, 'id' | 'active' | 'label'>`): The stored account of the provider this row runs on, when the provider
  has several (`ProviderAuth.accounts`): one row per account, so the same
  model on "Work" and "Personal" are two picks. Absent: the provider's
  only account.
- `model` (`ModelInfo`): Metadata of the model. An off-catalog entry carries only `id` and a `contextWindow` of `0`.
- `offCatalog?` (`boolean`): The provider does not (or no longer) list this model: the entry was
  synthesized from an `include` pair, so `model` is a stub carrying the id
  and nothing else. Renderers should say so rather than print stub
  metadata as if it were real.
- `providerKey` (`string`): Key of the provider that serves the model.
- `providerLabel` (`string`): Display name of the provider.
- `searchCorpus` (`string`): Pre-computed lowercase corpus for substring search across the
  provider key, label, account label, model id, and display name. Built once at
  catalog-assembly time so filtering on every keystroke is
  O(catalogSize × queryLength), not O(catalogSize × fieldCount ×
  lowercase-overhead × queryLength).

Source: [src/chat/model-catalog.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/model-catalog.ts#L17)

### `CatalogItemProvenance`

Interface.

What Settings shows about one catalog item.

```ts
interface CatalogItemProvenance
```

**Properties**

- `changedBy` (`readonly string[]`, readonly): Extensions that added, edited or removed the item, in replay order, without duplicates.
- `id` (`string`, readonly): The item id (for models, `<providerId>/<modelId>`).
- `origin` (`ItemOrigin`, readonly): Who put the item in the catalog.
- `removed` (`boolean`, readonly): A transform removed the item: turning `removedBy` off brings it back.
- `removedBy?` (`string`, readonly): The extension whose transform removed it.
- `replaced?` (`ItemOrigin`, readonly): The origin of an item this one replaced at registration (same id).
- `source` (`string`, readonly): A label for `origin`: `Built in`, `Config`, `MCP server x`, `Extension x`.

Source: [src/chat/agents-catalog.ts:176](https://github.com/Tahul/zidane/blob/main/src/chat/agents-catalog.ts#L176)

### `ChatReferenceData`

Interface.

Provider payload for a chat reference.

```ts
interface ChatReferenceData
```

**Properties**

- `entry` (`ChatReferenceEntry`): The referenced chat.
- `token` (`string`): The `#token` text that identifies the chat, without the `#`.

Source: [src/chat/completion-chats.ts:49](https://github.com/Tahul/zidane/blob/main/src/chat/completion-chats.ts#L49)

### `ChatReferenceEntry`

Interface.

A chat that can be referenced from a prompt.

```ts
interface ChatReferenceEntry
```

**Properties**

- `artifactCount?` (`number`): Optional (store-dependent); shown as a hint when > 0.
- `id` (`string`): Chat id.
- `projectRoot?` (`string`): Project directory the chat belongs to.
- `runCount` (`number`): Number of agent runs in the chat.
- `title` (`string`): Chat title.
- `turnCount` (`number`): Number of turns in the chat.
- `updatedAt` (`number`): Last update time in ms since epoch.
- `userMessageCount` (`number`): Number of user messages in the chat.

Source: [src/chat/completion-chats.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/completion-chats.ts#L29)

### `Command`

Interface.

An extension-contributed `/` command. Provide EITHER `run` (one step) or `steps`.

```ts
interface Command
```

**Properties**

- `aliases?` (`readonly string[]`): Alternate invocation names (same constraints as `name`). `/alias`
  dispatches to this command; the popover shows the canonical name and
  lists aliases in the description. Aliases participate in the same
  first-registration-wins dedupe as names.
- `completeArgs?` (`(argsPrefix: string) => readonly CommandArgSuggestion[] | Promise<readonly CommandArgSuggestion[] | undefined> | undefined`): Argument completion — called while the user types `/<name> <prefix>▌`
  with everything after the command name (may itself contain spaces).
  Return suggestions to show in the `/` popover; return `[]`/`undefined`
  for none. Sync or async.
- `description` (`string`): One-line summary shown in the completion popover.
- `group?` (`string`): Grouping key for completion — the registry stamps the source
  extension's name here, so typing `/<extension>` in the popover lists
  every command that extension contributes. Not an invocation name:
  `parseCommandInvocation` ignores it.
- `name` (`string`): Invoked as `/<name>`. Lowercase, no whitespace.
- `run?` (`CommandStepFn`): Single-step sugar.
- `steps?` (`readonly CommandStep[]`): Explicit ordered pipeline. Takes precedence over `run` when both are set.

Source: [src/chat/commands.ts:330](https://github.com/Tahul/zidane/blob/main/src/chat/commands.ts#L330)

### `CommandArgSuggestion`

Interface.

One argument suggestion returned by `Command.completeArgs`.

```ts
interface CommandArgSuggestion
```

**Properties**

- `description?` (`string`): Optional secondary text shown next to the label.
- `label?` (`string`): Display label. Defaults to `value`.
- `value` (`string`): Text inserted after `/<name> ` on accept.

Source: [src/chat/commands.ts:320](https://github.com/Tahul/zidane/blob/main/src/chat/commands.ts#L320)

### `CommandInvocation`

Interface.

Parsed `/<name> [args]` invocation.

```ts
interface CommandInvocation
```

**Properties**

- `args` (`string`): Text after the name, trimmed.
- `argv` (`string[]`): `args` split on whitespace.
- `invokedAs` (`string`): The token the user actually typed (lowercased, no slash) — `name`
  when the canonical name was used, the alias otherwise. Lets commands
  keep per-alias behavior (e.g. bare `/fix-comments` defaulting to
  comments mode in the `/fix` command).
- `name` (`string`): Canonical command name, in its registered casing.

Source: [src/chat/commands.ts:485](https://github.com/Tahul/zidane/blob/main/src/chat/commands.ts#L485)

### `CompletionContext`

Interface.

Read-only view of the active prompt buffer + cursor passed to provider
callbacks. Kept minimal so providers stay portable across renderers.

```ts
interface CompletionContext
```

**Properties**

- `cursor` (`number`): UTF-16 code unit offset of the cursor (0-based).
- `text` (`string`): Full prompt text.

Source: [src/chat/completion-core.ts:165](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L165)

### `CompletionItem`

Interface.

A discoverable, selectable thing — one row in the autocomplete popover.
`TItem` is provider-specific; consumers can inspect `data` when they
need the originating payload (e.g. the full `SkillConfig` for tooltips).

```ts
interface CompletionItem<TItem = unknown>
```

**Type parameters**

- `TItem` (default `unknown`)

**Properties**

- `data` (`TItem`): Original provider-specific payload.
- `description?` (`string`): Optional one-line secondary string ("In-depth research with citations").
- `id` (`string`): Stable identifier within the provider. Used as React key + selection equality.
- `insertText` (`string`): Text that replaces the active span (trigger + query) on commit. Usually
  `${trigger}${label}` with a trailing space so the cursor lands ready
  for the next token.
- `label` (`string`): User-visible primary string ("research").
- `providerId?` (`string`): Id of the producing provider — stamped by [`mergeSuggestions`](https://zidane.si/docs/reference/chat-pure.md#mergeSuggestions) so
  renderers can apply provider-specific styling (e.g. chip-colored
  titles) in a multi-provider popover. Items constructed outside the
  merge path may leave it unset.
- `section?` (`string`): Optional section header for popovers that host several providers on one
  trigger (e.g. `/` → Commands + Skills). When set, the renderer groups
  items under this label; when absent, items render flat. The engine
  defaults it to the producing provider's `label` in [`mergeSuggestions`](https://zidane.si/docs/reference/chat-pure.md#mergeSuggestions).

Source: [src/chat/completion-core.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L29)

### `CompletionProvider`

Interface.

Provider contract. Implementations decide their own ranking, fuzzy-match
rules, async loading behavior, and reference grammar.

```ts
interface CompletionProvider<TItem = unknown>
```

**Type parameters**

- `TItem` (default `unknown`)

**Properties**

- `allowSpacesInQuery?` (`boolean`): Keep the trigger active across spaces (single line only — a newline
  still closes it). Default false: a space ends the query token, which is
  right for file/skill/chat mentions. The commands provider opts in so
  `/deploy stag▌` can complete ARGUMENTS: its query becomes
  `deploy stag` and it decides internally what to suggest. When the
  query contains whitespace, only opted-in providers are consulted.
- `id` (`string`): Stable id used for tagging references + React keys.
- `label` (`string`): Human-readable name. Used as the section header when several providers share a trigger.
- `parseReferences` (`(text: string, ctx: CompletionContext) => CompletionReference<TItem>[]`): Find every reference to this provider's items in `text`. Pure: must not
  mutate ctx. The TUI calls this on every keystroke for highlighting, so
  keep it cheap (linear scan, no I/O).
- `suggest` (`(query: string, ctx: CompletionContext, signal: AbortSignal) => CompletionItem<TItem>[] | Promise<CompletionItem<TItem>[]>`): Returns items for the active `query` (the text between the trigger and
  the cursor, excluding the trigger itself). Synchronous return is the
  common case; promises let providers paginate or hit a backend.

  `signal` is aborted when the query changes or the popover closes —
  use it to cancel in-flight network calls.
- `trigger` (`string`): Single character that activates this provider. The engine considers a
  trigger "active" when it appears at the start of the buffer or
  immediately after whitespace, and is not closed by whitespace before
  the cursor (so a trigger plus query is a contiguous token).
- `onSubmit?` (`(submission: CompletionSubmitContext<TItem>, signal: AbortSignal) => void | Promise<void>`): Optional submit-time side effect hook. Runs after references are resolved.
- `resolveReferences?` (`(references: readonly CompletionReference<TItem>[], ctx: CompletionSubmitContext<TItem>, signal: AbortSignal) => CompletionReference<TItem>[] | Promise<CompletionReference<TItem>[]>`): Optional submit-time resolver. Unlike `parseReferences`, this may do async
  work and enrich references before the host turns them into attachments,
  activated skills, or other side effects.

  Declared with method syntax (not a property arrow) on purpose: it makes the
  `TItem`-typed params bivariant, so a heterogeneous `CompletionProvider`
  collection (skills + files + extensions) stays assignable to
  `CompletionProvider<unknown>[]`.

Source: [src/chat/completion-core.ts:94](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L94)

### `CompletionReference`

Interface.

A reference to a provider item inside arbitrary prompt text. Producers:
`provider.parseReferences(text)`. Consumers: the TUI for highlighting,
the run flow for "activate every referenced skill before agent.run()".

Spans are half-open `[start, end)` UTF-16 code unit offsets (string
indices) into the source string. Overlapping spans from the same or different providers are
caller-resolved — the helpers below ship a "first wins" merger.

```ts
interface CompletionReference<TItem = unknown>
```

**Type parameters**

- `TItem` (default `unknown`)

**Properties**

- `data` (`TItem`): Provider-specific payload for the referenced item.
- `end` (`number`): Exclusive end offset of the span.
- `itemId` (`string`): Id of the referenced provider item.
- `metadata?` (`Record<string, unknown>`): Optional provider-specific extras.
- `providerId` (`string`): Id of the provider that produced the reference.
- `start` (`number`): Inclusive start offset of the span.

Source: [src/chat/completion-core.ts:69](https://github.com/Tahul/zidane/blob/main/src/chat/completion-core.ts#L69)

### `ConnectorAuthWords`

Interface.

The words that [`connectorAuthText`](https://zidane.si/docs/reference/chat-pure.md#connectorAuthText) uses. Each app writes them its own way.

```ts
interface ConnectorAuthWords
```

**Properties**

- `noAccount` (`string`): The connector needs no account.
- `tokenOptionalAuth` (`string`): A token is optional.
- `tokenOrGhLogin` (`string`): It takes a token, or the user's `gh` login.
- `tokenSignIn` (`string`): It needs a token.

Source: [src/chat/onboarding/words.ts:151](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L151)

### `ConnectorCategoryMeta`

Interface.

A section of the Connectors step.

```ts
interface ConnectorCategoryMeta
```

**Properties**

- `id` (`ConnectorCategory`): The section.
- `label` (`string`): Its heading.

Source: [src/chat/onboarding/connectors.ts:156](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L156)

### `ConnectorEntry`

Interface.

A service the Connectors step adds as an MCP server.

```ts
interface ConnectorEntry
```

**Properties**

- `auth` (`ConnectorAuth`): How it signs in.
- `brand?` (`string`): Its logo, as a Simple Icons slug (`linear`). Absent: the app shows a letter.
- `category` (`ConnectorCategory`): Section it is listed under.
- `description` (`string`): One line on what the agent can do with it.
- `docsUrl` (`string`): The vendor's documentation of the server.
- `id` (`string`): Stable id, also the server name written to `mcps.json`.
- `label` (`string`): Display name.
- `transport` (`ConnectorTransport`): How it reaches the server.

Source: [src/chat/onboarding/types.ts:385](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L385)

### `ConnectorInput`

Interface.

What the user typed for a connector.

```ts
interface ConnectorInput
```

**Properties**

- `token?` (`string`): The token, without the header prefix, for token sign-in.

Source: [src/chat/onboarding/types.ts:405](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L405)

### `ConnectorTokenAuth`

Interface.

Token sign-in of a connector: what to ask for and where it goes.

```ts
interface ConnectorTokenAuth
```

**Properties**

- `createUrl` (`string`): Page where the user creates a token.
- `header` (`string`): Header the token is sent in.
- `kind` (`'token'`): The sign-in kind.
- `optional?` (`boolean`): The server also answers without a token, with lower limits.
- `placeholder?` (`string`): Input placeholder.
- `prefix?` (`string`): Text before the token in the header value (`Bearer `).
- `reuse?` (`'github'`): A token zidane already knows can fill it: `github` reuses the `gh` login.

Source: [src/chat/onboarding/types.ts:358](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L358)

### `ContextBreakdown`

Interface.

The shaped, render-ready breakdown.

```ts
interface ContextBreakdown
```

**Properties**

- `activeSkills?` (`string[]`): Names of currently-active skills. Informational — an activated skill's body
  lands in the conversation (tool-results), so its tokens are already counted
  under Conversation; this just surfaces "which skills are loaded". Empty/absent
  when none are active.
- `categories` (`ContextCategory[]`): Live categories (sum to `used`) followed by deferred + free-space buckets.
- `effectiveWindow` (`number`): Effective window (raw - output reserve), the bar's denominator.
- `extensionSections?` (`readonly ContextExtensionSection[]`): Extension-owned context panel sections.
- `fraction` (`number`): `used / effectiveWindow`, clamped to \[0, 1].
- `hasEstimates` (`boolean`): True when ANY live category is estimated (drives the panel's footnote).
- `modelId` (`string`): Model id the snapshot was built for.
- `usage?` (`ContextUsageSplit`): Exact last-turn usage split (cache read / write / fresh input / output),
  when the host supplied it. Always exact — rendered as an informational
  section below the categories. Absent when no usage is available yet.
- `used` (`number`): Real last-turn context size (provider-reported `input + cacheRead +
  cacheCreation`) — the SAME number the footer/orb shows. The non-deferred
  categories sum to this, unless the static categories alone exceed it.

Source: [src/chat/context-breakdown.ts:135](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L135)

### `ContextBreakdownContributionContext`

Interface.

Data exposed to extension context-breakdown contributors.

```ts
interface ContextBreakdownContributionContext
```

**Properties**

- `turns` (`readonly SessionTurn[]`): The session turns the breakdown is computed from.

Source: [src/chat/context-breakdown.ts:84](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L84)

### `ContextBreakdownOptions`

Interface.

Host-supplied options for `agent.getContextBreakdown`.

```ts
interface ContextBreakdownOptions
```

**Properties**

- `autocompactBuffer?` (`number`): Tokens reserved for output (autocompact buffer). Defaults to 0.
- `compactThreshold?` (`number`): Auto-compact threshold as a fraction of the window (0–1), when enabled.
  When set, the "Autocompact buffer" bucket represents the ENTIRE tail from
  the threshold to the end of the window (`(1 − threshold) × window`) rather
  than just the reserved-output tokens — so the bar/row show exactly where
  compaction fires. When omitted, `autocompactBuffer` is used as-is.
- `effectiveWindow?` (`number`): Effective context window (`rawWindow - outputReserve`) for the active
  model, resolved by the host via the chat model registry. Drives free-space
  - fraction. When omitted, defaults to `used` (no headroom shown).
- `model?` (`string`): Active model id — used for the exact `countTokens` call + the header label.
  Only consulted on the PRE-RUN path (no snapshot yet); once a run has fired,
  the snapshot's own model wins. When omitted, the provider default is used.
- `signal?` (`AbortSignal`): Abort signal forwarded to the provider's `countTokens`.

Source: [src/chat/context-breakdown.ts:170](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L170)

### `ContextCategory`

Interface.

One category row in the breakdown.

```ts
interface ContextCategory
```

**Properties**

- `deferred?` (`boolean`): True for buckets that are NOT counted against the live window total
  (deferred tools, free space, autocompact buffer) — the UI renders these
  dimmed / below a divider, mirroring Claude Code's layout.
- `estimated` (`boolean`): True when `tokens` came from the heuristic rather than an exact count.
- `id` (`ContextCategoryId`): Stable category id.
- `items?` (`ContextItem[]`): Optional expandable child rows (per MCP tool, per rules file, ...).
- `label` (`string`): Display label (e.g. "Tool definitions").
- `tokens` (`number`): Token count for the category.

Source: [src/chat/context-breakdown.ts:115](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L115)

### `ContextExactCounts`

Interface.

Exact per-segment counts from a provider's `countTokens`, when available.
Each field is the count of the cumulative payload up to and including that
segment, so categories are derived by differencing (see
[`buildContextBreakdown`](https://zidane.si/docs/reference/chat-pure.md#buildContextBreakdown)). Any subset may be present; missing fields
fall back to the heuristic for that category.

```ts
interface ContextExactCounts
```

**Properties**

- `full?` (`number`): Tokens for the full payload (system + tools + messages) = the real total.
- `system?` (`number`): Tokens for system prompt alone.
- `systemAndTools?` (`number`): Tokens for system + tools (so tools = systemAndTools - system).

Source: [src/chat/context-breakdown.ts:212](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L212)

### `ContextExtensionRow`

Interface.

One display row contributed by an extension to the context panel.

```ts
interface ContextExtensionRow
```

**Properties**

- `label` (`string`): Row label.
- `value` (`string`): Row value text.

Source: [src/chat/context-breakdown.ts:64](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L64)

### `ContextExtensionSection`

Interface.

Extension-owned context panel section. Core treats rows as opaque display data.

```ts
interface ContextExtensionSection
```

**Properties**

- `accentColor?` (`string`): Optional section-title foreground color. UIs fall back to their theme accent.
- `id` (`string`): Stable section id.
- `label` (`string`): Section title.
- `rows` (`readonly ContextExtensionRow[]`): Rows shown in the section.

Source: [src/chat/context-breakdown.ts:72](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L72)

### `ContextItem`

Interface.

One expandable child row under a category (e.g. a single MCP tool / rules file).

```ts
interface ContextItem
```

**Properties**

- `description?` (`string`): Tool description (tool items only) — what a UI shows on hover.
- `estimated` (`boolean`): True when `tokens` came from the heuristic rather than an exact count.
- `group?` (`string`): Owning group when the category flattens several (MCP server name).
- `id` (`string`): Stable-ish key for rendering (tool name, file path).
- `label` (`string`): Display label.
- `tokens` (`number`): Token count for this item.

Source: [src/chat/context-breakdown.ts:99](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L99)

### `ContextMcpGroup`

Interface.

Tools grouped by MCP server, for the expandable per-server rows.

```ts
interface ContextMcpGroup
```

**Properties**

- `server` (`string`): MCP server name.
- `tools` (`{ description?: string; json: string; name: string }[]`): Wire tool specs for this server (their JSON size is measured).

Source: [src/chat/context-breakdown.ts:198](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L198)

### `ContextSegment`

Interface.

One chunk of text present in the session's default context.

```ts
interface ContextSegment
```

**Properties**

- `detail?` (`string`): Short right-hand qualifier — the instruction scope for files, the server
  list for MCP, a count for the skills catalog. Absent when there's nothing
  useful to add beyond the origin badge.
- `id` (`string`): Stable key for rendering (`'system'`, `'rules:<path>'`, `'skills'`, ...).
- `label` (`string`): Display label (e.g. "System prompt", or the file's basename).
- `origin` (`ContextSegmentOrigin`): Where the text comes from: built into zidane, a file, generated at run time or an MCP server.
- `path?` (`string`): Absolute path of the file backing this segment. Present only for
  `origin: 'file'` — a host uses it as the "open in $EDITOR" target.
- `text` (`string`): The text itself, as it sits in the prompt. Empty segments are dropped.
- `tokens` (`number`): Heuristic token size (\~4 bytes/token). Always an estimate: exact
  per-segment counts aren't separable from the single system-prompt string
  the provider counts, which is why [`ContextSegment`](https://zidane.si/docs/reference/chat-pure.md#ContextSegment) carries no
  `estimated` flag — every value here is one.

Source: [src/chat/context-segments.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/context-segments.ts#L31)

### `ContextSegmentFile`

Interface.

A host-discovered instruction file. Structurally compatible with
`AgentsMdFile` from `./agents-md` (whose `source` field is the SCOPE, not
the text — `contents` is the text), so callers can pass those straight in.

```ts
interface ContextSegmentFile
```

**Properties**

- `contents` (`string`): Text of the file.
- `path` (`string`): Path of the instruction file.
- `source?` (`string`): Instruction scope — `'project'` / `'user'`, surfaced as the row detail.

Source: [src/chat/context-segments.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/context-segments.ts#L65)

### `ContextSegmentsInput`

Interface.

The assembled-prompt pieces [`buildContextSegments`](https://zidane.si/docs/reference/chat-pure.md#buildContextSegments) shapes. Mirrors the
subset of the agent's `ContextAssembly` that carries text, plus host-side
instruction files (which the assembly only knows as paths).

```ts
interface ContextSegmentsInput
```

**Properties**

- `baseSystem?` (`string`): Host-composed base system BEFORE the agent appended its catalogs. The
  rules block is a substring of this; the "System prompt" segment is the
  remainder. Falls back to `system` when absent, which over-attributes the
  appended catalogs into the base row rather than losing them.
- `mcpInstructions?` (`string`): Rendered MCP instructions block.
- `rulesBlock?` (`string`): Rendered instruction block (a substring of `baseSystem`). Subtracted from
  the base so its text isn't reported twice — once as doctrine and once as
  per-file rows.
- `rulesFiles?` (`readonly ContextSegmentFile[]`): The files behind `rulesBlock`, each with its own text.
- `skillsCatalog?` (`string`): Rendered skills catalog (the per-skill blurbs, not skill bodies).
- `subagentDefs?` (`string`): Lazy-tool `<searchable_tools>` catalog text. Key name is historical — it
  holds no subagent definitions.
- `system?` (`string`): Full rendered system prompt as sent. Used as the `baseSystem` fallback.
- `systemPath?` (`string`): Absolute path of a `SYSTEM.md` override backing the base prompt. When set,
  the "System prompt" segment reports `origin: 'file'` and becomes openable
  — the doctrine is the user's file, not compiled-in text.

Source: [src/chat/context-segments.ts:79](https://github.com/Tahul/zidane/blob/main/src/chat/context-segments.ts#L79)

### `ContextSnapshot`

Interface.

Raw inputs captured at agent prompt-assembly time. Everything here is what
actually went on (or was withheld from) the wire for the last run.

```ts
interface ContextSnapshot
```

**Properties**

- `activeSkills?` (`string[]`): Names of currently-active skills (passed straight through).
- `autocompactBuffer` (`number`): Tokens reserved for output (autocompact buffer).
- `baseSystem?` (`string`): Host-composed base system BEFORE the agent appended skills / searchable /
  MCP-instructions catalogs. Includes the rules block. `buildContextBreakdown`
  does not read it (it sizes `system` and subtracts the attributed
  sections); `buildContextSegments` takes it as input.
- `deferredMcpGroups` (`ContextMcpGroup[]`): Deferred (undisclosed) MCP tools grouped by server.
- `deferredToolsJson` (`string[]`): Lazy tool entries NOT currently disclosed (deferred), as JSON strings.
- `effectiveWindow` (`number`): Effective window (raw - output reserve).
- `exact?` (`ContextExactCounts`): Exact per-segment counts from the provider, when available.
- `extensionSections?` (`readonly ContextExtensionSection[]`): Extension-owned context panel sections.
- `mcpGroups` (`ContextMcpGroup[]`): MCP tools grouped by server (disclosed ones).
- `mcpInstructions?` (`string`): Rendered MCP instructions block, if any.
- `modelId` (`string`): Id of the model the run used.
- `rulesBlock?` (`string`): Rendered AGENTS.md/CLAUDE.md rules block (a substring of `baseSystem`).
- `rulesFiles?` (`{ path: string; source: string }[]`): Source files behind the rules block, for per-file rows.
- `skillsCatalog?` (`string`): Rendered skills catalog text, if any.
- `subagentDefs?` (`string`): Lazy-tool `<searchable_tools>` catalog text, if any (key name is historical).
- `system` (`string`): Full rendered system prompt (marker-stripped, as sent).
- `toolItems?` (`{ description?: string; json: string; name: string }[]`): Per-tool detail for `toolsJson`, same order, when the host has it —
  lets the breakdown list native tools like it lists MCP tools. Optional so
  SDK callers assembling a snapshot by hand are unaffected.
- `toolsJson` (`string[]`): Wire tool specs currently disclosed to the model, as JSON strings.
- `usage?` (`ContextUsageSplit`): Exact last-turn usage split, when available (passed straight through).
- `used` (`number`): Real last-turn total (input + cacheRead + cacheCreation).

Source: [src/chat/context-breakdown.ts:225](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L225)

### `ContextUsageSplit`

Interface.

Exact last-turn token usage split (provider-reported — always exact). Drives
the cache breakdown shown below the categories. `cacheRead + cacheCreation +
input` equals the live context total (`used`).

```ts
interface ContextUsageSplit
```

**Properties**

- `cacheCreation` (`number`): Tokens written to the cache this turn.
- `cacheRead` (`number`): Tokens served from the prompt cache (the cached prefix).
- `input` (`number`): Fresh, uncached input tokens this turn.
- `output` (`number`): Assistant output tokens (not part of the input window; informational).

Source: [src/chat/context-breakdown.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L52)

### `CronEngine`

Interface.

The cron math the host plugs in (`cronEngine` in `./cron`).

```ts
interface CronEngine
```

**Properties**

- `next` (`(expr: string, tz: string, after: number) => number | null`): The first time strictly after `after` (epoch ms), or `null`.
- `problem` (`(expr: string, tz: string) => string | undefined`): Why the expression or the time zone is not valid, or `undefined`.
- `runs` (`(expr: string, tz: string, count: number, from: number) => number[]`): The next `count` times from `from` (epoch ms).

Source: [src/schedules/next-fire.ts:15](https://github.com/Tahul/zidane/blob/main/src/schedules/next-fire.ts#L15)

### `CustomModelTarget`

Interface.

A provider and model id a free-text query resolves to.

```ts
interface CustomModelTarget
```

**Properties**

- `modelId` (`string`): Model id taken from the query, without any provider prefix.
- `named?` (`boolean`): The query named this provider (`xai grok-9`).
- `providerKey` (`string`): Provider the model id would run on.
- `providerLabel` (`string`): Display name of the provider.

Source: [src/chat/model-catalog.ts:234](https://github.com/Tahul/zidane/blob/main/src/chat/model-catalog.ts#L234)

### `DaemonHealthStyle`

Interface.

How the daemon health dot is styled.

```ts
interface DaemonHealthStyle
```

**Properties**

- `label` (`string`): Tooltip / accessibility text. The dot itself carries no words.
- `tone` (`DaemonHealthTone`): Theme tone of the dot.

Source: [src/chat/daemon-health.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/daemon-health.ts#L23)

### `DescribeTimeOptions`

Interface.

How [`describeTime`](https://zidane.si/docs/reference/chat-pure.md#describeTime) writes a time.

```ts
interface DescribeTimeOptions
```

**Properties**

- `seconds?` (`boolean`): Write the seconds too: `09:00:05`. Default: minutes only.

Source: [src/schedules/when.ts:161](https://github.com/Tahul/zidane/blob/main/src/schedules/when.ts#L161)

### `DiffLine`

Interface.

One line of a line diff.

```ts
interface DiffLine
```

**Properties**

- `op` (`DiffOp`): Whether the line is unchanged, added or removed.
- `text` (`string`): Line content without a diff prefix.

Source: [src/chat/edit-diff.ts:138](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L138)

### `EditHunkSummary`

Interface.

Digest of one changed region, used by the compact diff view.

```ts
interface EditHunkSummary
```

**Properties**

- `added` (`number`): Number of lines added in this hunk.
- `firstNew?` (`string`): First added line preview (trimmed, may be empty for pure deletions).
- `firstOld?` (`string`): First removed line preview (trimmed, may be empty for pure additions).
- `line?` (`number`): 1-based line number in the new file where the change starts; undefined when unknown (no priorContent).
- `removed` (`number`): Number of lines removed in this hunk.

Source: [src/chat/edit-diff.ts:539](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L539)

### `EditSummary`

Interface.

Digest of an edit payload for the compact diff view.

```ts
interface EditSummary
```

**Properties**

- `hunks` (`EditHunkSummary[]`): Per-hunk digests, in order.
- `totalAdded` (`number`): Total number of added lines.
- `totalRemoved` (`number`): Total number of removed lines.

Source: [src/chat/edit-diff.ts:553](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L553)

### `EntryCreateOptions`

Interface.

Options of `EntryOps.create`.

```ts
interface EntryCreateOptions
```

**Properties**

- `content?` (`Uint8Array<ArrayBufferLike>`): A new file's bytes. Default: empty.
- `freeName?` (`boolean`): Take the next free name (`a copy.ts`) when the name is taken, instead of refusing.

Source: [src/chat/workspace/entries.ts:43](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L43)

### `EntryImportLimits`

Interface.

Limits of [`importEntries`](https://zidane.si/docs/reference/chat-pure.md#importEntries).

```ts
interface EntryImportLimits
```

**Properties**

- `maxBytes?` (`number`): All files together. Default [`ENTRY_IMPORT_MAX_BYTES`](https://zidane.si/docs/reference/chat-pure.md#ENTRY_IMPORT_MAX_BYTES).
- `maxEntries?` (`number`): Entries (files and folders). Default [`ENTRY_IMPORT_MAX_ENTRIES`](https://zidane.si/docs/reference/chat-pure.md#ENTRY_IMPORT_MAX_ENTRIES).
- `maxFileBytes?` (`number`): One file. Default [`ENTRY_IMPORT_MAX_FILE_BYTES`](https://zidane.si/docs/reference/chat-pure.md#ENTRY_IMPORT_MAX_FILE_BYTES).

Source: [src/chat/workspace/entries.ts:295](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L295)

### `EntryOps`

Interface.

The entry actions on one folder. Paths are relative to it; `''` is the folder itself.

```ts
interface EntryOps
```

**Properties**

- `copy` (`(from: string, toDir: string) => Promise<EntryResult>`): Copies `from` into folder `toDir` under its name, or the next free one.
- `create` (`(path: string, kind: EntryKind, options?: EntryCreateOptions) => Promise<EntryResult>`): Creates a file or a folder at `path`, making the folders on the way.
- `move` (`(from: string, to: string) => Promise<EntryResult>`): Moves (or renames) `from` to `to`, making the folders on the way.
- `remove` (`(path: string) => Promise<EntryResult>`): Removes `path` (a folder whole). Where it goes (the trash, or nowhere) is the port's.

Source: [src/chat/workspace/entries.ts:51](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L51)

### `EstimateReadout`

Interface.

What an estimate says at a moment.

```ts
interface EstimateReadout
```

**Properties**

- `remainingMs` (`number`): Working time left, in ms; `0` once the estimate is spent.
- `state` (`'live' | 'paused' | 'due' | 'over'`): - `live`: counting down.
  - `due`: the estimate is spent, the run is not over yet (between its total and its over point).
  - `paused`: the run waits on the user; the count holds.
  - `over`: past its over point.

Source: [src/chat/run-estimate.ts:258](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L258)

### `ExtensionMarkInput`

Interface.

What [`extensionMark`](https://zidane.si/docs/reference/chat-pure.md#extensionMark) reads.

```ts
interface ExtensionMarkInput
```

**Properties**

- `brand?` (`string`): A logo a source listing gives it (a Simple Icons slug), read before the native catalog's.
- `icon?` (`{ gui?: string; tui?: string }`): Its own icon (the definition's or the manifest's `icon`).
- `id` (`string`): The extension's id (its folder name).
- `name?` (`string`): Its display name. Absent: the native catalog's label, else the id.
- `nativeName?` (`string`): The native catalog entry to read (`NATIVE_EXTENSIONS[].name`). Absent: the id.

Source: [src/chat/extension-mark.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/extension-mark.ts#L16)

### `ExtensionPanelTab`

Interface.

A tab for a panel an extension registered.

```ts
interface ExtensionPanelTab
```

**Properties**

- `builtin` (`false`): Discriminant that marks an extension tab.
- `icon?` (`PanelIcon`): Icon for each renderer, when the extension set one.
- `id` (`string`): Panel id.
- `label` (`string`): Tab label.
- `owner` (`string`): Name of the extension that registered the panel.
- `ownerIcon?` (`PanelIcon`): The extension's own icon: without `icon`, apps draw the extension's mark (`extensionMark`).
- `ownerName?` (`string`): The extension's display name.

Source: [src/chat/panels.ts:63](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L63)

### `ExtensionSourceEntry`

Interface.

An extension a source holds, read from its `package.json` (`zidane` field) or `extension.json`. Nothing of it ran.

```ts
interface ExtensionSourceEntry
```

**Properties**

- `apiVersion?` (`number`): The extension API version its manifest declares.
- `brand?` (`string`): Its logo from the native catalog (a Simple Icons slug), for the native extensions only.
- `description?` (`string`): What it does.
- `displayName` (`string`): Its display name (`displayName` or `label`), else the name.
- `icon?` (`{ gui?: string; tui?: string }`): Its icon (the manifest's `icon`).
- `install?` (`{ extension?: string; source: string }`): What installs it: `installExtensionFromSpec({ source, extension })`
  (`catalog.install` with `spec: source`). Absent for a local folder,
  which the installer does not take.
- `name` (`string`): Its name: the folder it installs as (the manifest's `name`, else the folder or package name).
- `path` (`string`): Its folder in the source, relative to the repository or package root (`.` for the root).
- `version?` (`string`): Its version (`package.json` `version`).

Source: [src/chat/extension-sources.ts:46](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L46)

### `ExtensionSourceInfo`

Interface.

Where a listing comes from.

```ts
interface ExtensionSourceInfo
```

**Properties**

- `kind` (`ExtensionSourceKind`): Its kind.
- `label` (`string`): A short name: `Tahul/zidane`, `Tahul/zidane@v9.0.4`, `@scope/pkg`, the folder.
- `owner?` (`string`): GitHub owner.
- `package?` (`string`): npm package name.
- `path?` (`string`): The folder on the host (`local`).
- `ref?` (`string`): The branch or tag listed (GitHub: the default branch when none was given), or the npm version listed.
- `repo?` (`string`): GitHub repository.
- `url?` (`string`): A page to open: the repository, the folder on GitHub, the package on npmjs.com.

Source: [src/chat/extension-sources.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L15)

### `ExtensionSourceListing`

Interface.

The extensions of one source, as `listExtensionSource` lists them.

```ts
interface ExtensionSourceListing
```

**Properties**

- `builtin?` (`boolean`): The rows come from the catalog shipped in the app (`nativeExtensionListing`), not from the source.
- `error?` (`{ code: ExtensionSourceErrorCode; message: string }`): Why the source could not be read.
- `extensions` (`ExtensionSourceEntry[]`): The extensions found. Empty with `error` when the source could not be read, except the default source, which lists the native catalog then (`builtin`).
- `input` (`string`): What was asked for, trimmed.
- `source` (`ExtensionSourceInfo`): Where the extensions come from.
- `truncated?` (`boolean`): The listing stopped early: GitHub cut the file tree, or the source holds more than the cap.

Source: [src/chat/extension-sources.ts:72](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L72)

### `ExtensionSpaceSource`

Interface.

A space an extension contributes, as its wire form carries it (`SpaceWire`
in `zidane/extensions`): the fields [`extensionSpace`](https://zidane.si/docs/reference/chat-pure.md#extensionSpace) reads.

```ts
interface ExtensionSpaceSource
```

**Properties**

- `groupBy?` (`SessionGroupBy`): Its grouping.
- `id` (`string`): `<extension>/<id>`.
- `name` (`string`): Display name.
- `newSession?` (`{ agentId?: string; effort?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive'; modelId?: string; providerKey?: string }`): What a session started from it runs with.
- `query` (`SessionQuery`): The sessions it lists.
- `sortBy?` (`readonly SessionSort[]`): Its sort.

Source: [src/chat/spaces.ts:75](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L75)

### `FeatureGate`

Interface.

A feature gate created by [`defineFeatureGate`](https://zidane.si/docs/reference/chat-pure.md#defineFeatureGate).

```ts
interface FeatureGate<K extends string>
```

**Type parameters**

- `K` (`extends string`)

**Properties**

- `flag` (`string`, readonly): CLI flag that sets the kill-switch env var for the launch.
- `isEnabled` (`(settings: Partial<Record<K, unknown>>, env?: Env) => boolean`): Setting is `true` and the kill switch is not engaged.
- `isKilled` (`(env?: Env) => boolean`): The kill-switch env var is set to `'1'`.
- `killSwitchEnv` (`string`, readonly): Env var that disables the feature when set to `'1'`.
- `setting` (`K`, readonly): Settings key holding the opt-in.

Source: [src/chat/feature-gate.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L29)

### `FeatureGateOptions`

Interface.

Options for [`defineFeatureGate`](https://zidane.si/docs/reference/chat-pure.md#defineFeatureGate).

```ts
interface FeatureGateOptions<K extends string>
```

**Type parameters**

- `K` (`extends string`)

**Properties**

- `flag` (`string`): The `zidane` flag that sets `killSwitchEnv` for the launch (`--no-…`).
- `killSwitchEnv` (`string`): Env var that disables the feature when set to `'1'`, whatever the setting says.
- `setting` (`K`): Settings key holding the opt-in. Only a literal `true` enables.

Source: [src/chat/feature-gate.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/feature-gate.ts#L19)

### `FenceOpen`

Interface.

A fenced code block's opening line: its indent, marker character and marker length.

```ts
interface FenceOpen
```

**Properties**

- `char` (`string`): The marker character: a backtick or `~`.
- `indent` (`number`): Spaces before the marker.
- `length` (`number`): How many marker characters open the fence; a closer needs at least as many.

Source: [src/chat/markdown-segments.ts:385](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L385)

### `FoldPlan`

Interface.

[`planFold`](https://zidane.si/docs/reference/chat-pure.md#planFold)'s result.

```ts
interface FoldPlan<T>
```

**Type parameters**

- `T`

**Properties**

- `calls` (`{ displayName: string; name: string }[]`): The exchange's own top-level calls, in order, for [`foldSummary`](https://zidane.si/docs/reference/chat-pure.md#foldSummary).
- `stats` (`FoldStats`): The counts the header reads.
- `steps` (`FoldStep<T>[]`): The opened fold's lines, in order.

Source: [src/chat/fold-rules.ts:137](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L137)

### `FoldShape`

Interface.

What decides whether an item folds: its kind and owner, and two facts only its surface knows.

```ts
interface FoldShape
```

**Properties**

- `childId?` (`string`): The worker session that produced it; absent on the main session.
- `depth?` (`number`): Worker nesting depth; `0` or absent on the main session.
- `earlierMarker?` (`boolean`): The transcript's "N earlier events" marker: its top, not part of an exchange.
- `kind` (`string`): The item's kind (`thinking`, `tool`, `info`, …).
- `notice?` (`unknown`): Set when the item is a notice: an `info` notice stays out of the fold.
- `userBash?` (`boolean`): The user's own `!` run: they ran it to see it.

Source: [src/chat/fold-rules.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L16)

### `FoldStats`

Interface.

What the header reads. Worker-owned calls and thoughts count under the worker, not here.

```ts
interface FoldStats
```

**Properties**

- `durationMs?` (`number`): Known time of the own calls and thoughts; absent when nothing carries timing.
- `failed` (`number`): Own calls that failed.
- `pending` (`number`): Own calls (nested ones included) with no result yet.
- `thoughts` (`number`): The exchange's own thinking items.
- `tools` (`number`): The exchange's own calls (a script's nested calls ride their script's).
- `workers` (`number`): Distinct workers; one a worker started counts under its spawner.

Source: [src/chat/fold-rules.ts:121](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L121)

### `FoldStep`

Interface.

One line of an opened fold: a tool call, consecutive thoughts, a worker, or a command's note.

```ts
interface FoldStep<T>
```

**Type parameters**

- `T`

**Properties**

- `at` (`number`): How many steps came before it when it started: a stable index for ids.
- `call?` (`T`): A tool step's call, or the `spawn` call that started a worker.
- `callId?` (`string`): A tool step's call id.
- `items` (`T[]`): Tool: the call and its results. Thought: its thinking items. Worker: every item of its lane. Note: the note.
- `kind` (`'tool' | 'worker' | 'thought' | 'note'`): What the line shows: a tool call, consecutive thoughts, a worker, or a command's note.
- `lane?` (`string`): A worker's lane (its `childId`, or the worker that started it).
- `live?` (`boolean`): A thought still streaming.
- `parentId?` (`string`): The call that made this one (a codemode script's `tools.*`).
- `state` (`FoldStepState`): Its progress; a worker's is its own end, not its call's result.
- `task?` (`string`): A worker no call started: the task its marker carries.
- `waitingFor?` (`{ active: number; max: number }`): A `waiting` spawn call: the worker slots taken and the limit.

Source: [src/chat/fold-rules.ts:95](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L95)

### `GenerateSessionTitleOptions`

Interface.

Options for [`generateSessionTitle`](https://zidane.si/docs/reference/chat-pure.md#generateSessionTitle).

```ts
interface GenerateSessionTitleOptions
```

**Properties**

- `maxTurns?` (`number`): Cap on how many TRAILING turns to feed the model. Defaults to 10.
  The session's opening user turn is always included on top when the
  window cuts it off (see `renderTitleTranscript`).
- `maxWords?` (`number`): Cap the title at this many words (asked for in the prompt, enforced
  after). Unset asks for 3-7 word labels.
- `model` (`string`): Model id used for the call.
- `provider` (`Provider`): Provider whose `stream()` produces the title.
- `signal?` (`AbortSignal`): Optional cancellation signal — forwarded to the provider's stream.
- `turns` (`readonly SessionTurn[]`): Conversation history to summarize. Empty → the returned promise rejects.

Source: [src/chat/generate-title.ts:119](https://github.com/Tahul/zidane/blob/main/src/chat/generate-title.ts#L119)

### `GroupOptions`

Interface.

Options of [`groupRows`](https://zidane.si/docs/reference/chat-pure.md#groupRows).

```ts
interface GroupOptions
```

**Properties**

- `labels?` (`Readonly<Record<string, string>>`): Labels by group key the caller knows (agent names, project names). The grouping's own `labels` win.
- `missingLabel?` (`string`): Label of the group of rows without a value. Default `'None'`.

Source: [src/chat/session-query/group.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/group.ts#L13)

### `HeatmapThresholds`

Interface.

The three quartile bounds a value is placed against.

```ts
interface HeatmapThresholds
```

**Properties**

- `q1` (`number`): Upper bound of level 1 (the first quartile).
- `q2` (`number`): Upper bound of level 2 (the median).
- `q3` (`number`): Upper bound of level 3 (the third quartile).

Source: [src/chat/heatmap-levels.ts:11](https://github.com/Tahul/zidane/blob/main/src/chat/heatmap-levels.ts#L11)

### `HighlightRange`

Interface.

Half-open character range `[start, end)` of a match inside a text.

```ts
interface HighlightRange
```

**Properties**

- `end` (`number`): Offset just past the last matched character.
- `start` (`number`): Offset of the first matched character.

Source: [src/chat/history-search.ts:5](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L5)

### `HighlightSegment`

Interface.

A run of text that is either all highlighted or not, from [`highlightSegments`](https://zidane.si/docs/reference/chat-pure.md#highlightSegments).

```ts
interface HighlightSegment
```

**Properties**

- `highlighted` (`boolean`): Whether the run is part of a match.
- `text` (`string`): The run's text.

Source: [src/chat/history-search.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L13)

### `HostCapabilities`

Interface.

A host's probed capabilities, as `host.capabilities` returns them.

```ts
interface HostCapabilities
```

**Properties**

- `allows` (`{ asMachine: boolean; clone: boolean; createFolders: boolean; remoteInstalls: boolean; sync: boolean }`): What it lets clients do (the hello flags).
- `environments` (`{ available: boolean; kind: string; label: string; reason?: string }[]`): Environment kinds a new session can pick there.
- `installers?` (`{ apt: boolean; brew: boolean }`): Package managers on PATH, for [`toolInstall`](https://zidane.si/docs/reference/chat-pure.md#toolInstall). Absent from a server that predates them.
- `os` (`{ arch: string; platform: string; release: string }`): The host's OS: `process.platform`, CPU architecture and kernel release.
- `partial?` (`boolean`): Built from the hello alone: the server predates the probe.
- `probedAt` (`number`): When it was probed, in epoch milliseconds.
- `sandbox` (`{ backend?: string; ok: boolean; reason?: string }`): The OS sandbox local sessions run under.
- `tools` (`HostTool[]`): Every tool in [`HOST_TOOLS`](https://zidane.si/docs/reference/chat-pure.md#HOST_TOOLS), found or not.
- `workspace` (`{ freeBytes?: number; roots: string[] }`): The workspace roots, with the free space of the first one when it could be read.

Source: [src/chat/capabilities.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/capabilities.ts#L20)

### `HostEntry`

Interface.

One saved host. Tokens are not here: see `hostCredentialKey`.

```ts
interface HostEntry
```

**Properties**

- `addedAt` (`number`): Epoch ms.
- `hostKind?` (`'server'`): Kind of host. Only `server` is saved.
- `id` (`string`): The server's `hostId` (`ipc.hello`): `add` verifies the host before saving it.
- `lastConnectedAt?` (`number`): Epoch ms of the last successful `add` / `test`.
- `name` (`string`): Display name: the one given at `add` or `rename`, else the server's.
- `serverName?` (`string`): The server's own name (`hostName`) at the last successful connect.
- `serverVersion?` (`string`): The server's zidane version at the last successful connect.
- `url` (`string`): `wss://…`, or `ws://` to loopback.

Source: [src/chat/hosts/types.ts:8](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/types.ts#L8)

### `HostIdentity`

Interface.

The identity a host reports (`hostRefOf(hello)`).

```ts
interface HostIdentity
```

**Properties**

- `id` (`string`): Stable host id.
- `kind` (`'server' | 'daemon' | 'in-process'`): How the host runs: in this process, as a local daemon, or as a remote server.
- `name` (`string`): Host display name.

Source: [src/chat/hosts/types.ts:43](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/types.ts#L43)

### `HostIndex`

Interface.

Keyed by (host, id): the same id may live on several hosts. A lookup that
names its host (`hostKey`) gets exactly that pair; one that doesn't
resolves only when one host has the id.

```ts
interface HostIndex
```

**Properties**

- `dropHost` (`(hostKey: string, hostName: string) => string[]`): The host was removed: its pairs are marked so (lookups say so); returns their ids.
- `forget` (`(id: string, hostKey?: string) => void`): The id is gone from `hostKey` (deleted there), or from every host.
- `hostOf` (`(id: string, hostKey?: string) => string | undefined`): With `hostKey`: it, when `id` is known live there. Without: the one live host of `id` (`undefined` when none, or several).
- `hostsOf` (`(id: string) => string[]`): Every live host of `id`.
- `idsOf` (`(hostKey: string) => string[]`): Ids noted on `hostKey`.
- `note` (`(id: string, hostKey: string) => void`): `id` lives on `hostKey` (clears that pair's removed-host mark).
- `removedHostOf` (`(id: string, hostKey?: string) => { key: string; name: string } | undefined`): The removed host `id` lived on (with `hostKey`: that one), if any.
- `require` (`(id: string, hostKey?: string) => string`): The live host of `id` (with `hostKey`: that pair). Throws
  [`HostRemovedError`](https://zidane.si/docs/reference/chat-pure.md#HostRemovedError), [`UnknownHostIdError`](https://zidane.si/docs/reference/chat-pure.md#UnknownHostIdError), or without
  `hostKey` [`AmbiguousHostIdError`](https://zidane.si/docs/reference/chat-pure.md#AmbiguousHostIdError) when several hosts have it.

Source: [src/chat/hosts/host-index.ts:71](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/host-index.ts#L71)

### `HostTool`

Interface.

A tool looked up on the host's PATH.

```ts
interface HostTool
```

**Properties**

- `found` (`boolean`): It is on PATH and executable.
- `name` (`string`): The executable's name, for example `gh`.
- `version?` (`string`): First line of `<tool> --version`, when it answered.

Source: [src/chat/capabilities.ts:10](https://github.com/Tahul/zidane/blob/main/src/chat/capabilities.ts#L10)

### `HunkResolution`

Interface.

How the edit tool would resolve one hunk.

```ts
interface HunkResolution
```

**Properties**

- `ambiguous?` (`boolean`): True when the resolver found >1 match without `replace_all`.
- `occurrences?` (`number`): Match count in the running content for the hunk.
- `resolved` (`boolean`): True when the tool body would find this hunk's `old_string` AND apply
  it without ambiguity. False when `resolveOldString` returned null OR
  the match was ambiguous (multiple occurrences and `replace_all` off).
- `via?` (`'exact' | 'quotes' | 'desanitize' | 'quotes+desanitize' | 'line-numbers' | 'quotes+line-numbers'`): Path the resolver took — `'exact'` when no recovery was needed.

Source: [src/chat/edit-diff.ts:689](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L689)

### `IndexedSearchTurn`

Interface.

A turn with its searchable text, prepared once for repeated queries.

```ts
interface IndexedSearchTurn
```

**Properties**

- `lowerText` (`string`): Pre-normalized once, reused for every query.
- `text` (`string`): Attachment/base64-free text shown in search results.
- `turn` (`SessionTurn`): The original turn.

Source: [src/chat/history-search.ts:88](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L88)

### `InlineDiff`

Interface.

Word-level segments for the old and new side of a paired line.

```ts
interface InlineDiff
```

**Properties**

- `newSegments` (`InlineSegment[]`): Segments of the new line.
- `oldSegments` (`InlineSegment[]`): Segments of the old line.

Source: [src/chat/edit-diff.ts:281](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L281)

### `InlineGhost`

Interface.

Inline autocomplete suggestion shown as ghost text after the caret, with the buffer state it was computed for.

```ts
interface InlineGhost
```

**Properties**

- `cursor` (`number`): Caret offset in `text` the ghost was computed for.
- `index` (`number`): Index into `suffixes` of the candidate currently shown.
- `suffixes` (`readonly string[]`): Candidate completions, each the text to insert at the caret.
- `text` (`string`): Buffer text the ghost was computed for.

Source: [src/chat/inline-ghost.ts:10](https://github.com/Tahul/zidane/blob/main/src/chat/inline-ghost.ts#L10)

### `InlineSegment`

Interface.

A run of text in an inline diff.

```ts
interface InlineSegment
```

**Properties**

- `changed` (`boolean`): True when this run differs between the old and new line.
- `text` (`string`): The run's text.

Source: [src/chat/edit-diff.ts:273](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L273)

### `InstalledServerRef`

Interface.

The fields of an installed MCP server a connector is matched on.

```ts
interface InstalledServerRef
```

**Properties**

- `args?` (`readonly string[]`): Command arguments, for a stdio server.
- `command?` (`string`): Command, for a stdio server.
- `name` (`string`): Server name.
- `url?` (`string`): Endpoint, for an HTTP server.

Source: [src/chat/onboarding/connectors.ts:223](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/connectors.ts#L223)

### `LineupEntry`

Interface.

A provider and model id pair considered for the lineup.

```ts
interface LineupEntry
```

**Properties**

- `modelId` (`string`): Model id.
- `providerKey` (`string`): Provider key.

Source: [src/chat/model-lineup.ts:169](https://github.com/Tahul/zidane/blob/main/src/chat/model-lineup.ts#L169)

### `LiveRunStatus`

Interface.

What a transcript passes its live work row so the row can name the run's
status: the provider retry in flight, and whether nothing live is on
screen ([`runTailActivity`](https://zidane.si/docs/reference/chat-pure.md#runTailActivity) reads `waiting`).

```ts
interface LiveRunStatus
```

**Properties**

- `retry` (`RunRetry | null`): The provider retry in flight, if any.
- `waiting` (`boolean`): Nothing live is on screen: the run waits on the model.

Source: [src/chat/run-activity.ts:93](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L93)

### `MachineDirListing`

Interface.

A folder listing a folder picker renders (the shape of `fs.listDirs`).

```ts
interface MachineDirListing
```

**Properties**

- `entries` (`{ isGitRepo: boolean; name: string; path: string }[]`): Folders under `path`. `isGitRepo` is always `false` here.
- `parent` (`string | null`): Parent folder, or `null` when `path` is a root.
- `path` (`string`): The folder being listed.
- `roots` (`string[]`): Folders the picker may start from.

Source: [src/chat/machines-view.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/machines-view.ts#L42)

### `MachineInfo`

Interface.

A machine as clients see it (`machines.list`, `environments.list`).

```ts
interface MachineInfo
```

**Properties**

- `capabilities?` (`Partial<MachineCapabilities>`): What it registered with (absent: never connected since this host recorded it).
- `id` (`string`): Stable machine id.
- `lastSeen?` (`number`): Time of the last connection, in epoch milliseconds.
- `name` (`string`): Machine name, valid per [`isValidMachineName`](https://zidane.si/docs/reference/chat-pure.md#isValidMachineName).
- `roots` (`MachineRoot[]`): Directories the machine allows commands and file access in.
- `status` (`'online' | 'offline'`): Whether the machine is connected to the host now.
- `version?` (`string`): Version the machine reported when it registered.

Source: [src/chat/machine-protocol.ts:200](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L200)

### `MachineLinksStatus`

Interface.

Status of every machine link of a local host.

```ts
interface MachineLinksStatus
```

**Properties**

- `shares` (`MachineShareStatus[]`): This computer shared with saved servers.
- `uses` (`MachineUseStatus[]`): Saved servers used as machines.

Source: [src/chat/machine-protocol.ts:262](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L262)

### `MachineRoot`

Interface.

A directory a machine exposes to its host.

```ts
interface MachineRoot
```

**Properties**

- `label?` (`string`): Display name for the root.
- `path` (`string`): Absolute path of the root on the machine.

Source: [src/chat/machine-protocol.ts:14](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L14)

### `MachineShareStatus`

Interface.

State of this computer's share to one saved server, where it acts as a machine.

```ts
interface MachineShareStatus
```

**Properties**

- `detail?` (`string`): Why it is not connected. Never a token.
- `hostId` (`string`): The saved server's host id.
- `name` (`string`): This computer's name there (`local@<name>`).
- `roots` (`string[]`): Paths shared with the server.
- `state` (`MachineLinkState`): Connection state of the link.

Source: [src/chat/machine-protocol.ts:236](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L236)

### `MachineStatusChange`

Interface.

`machine:status` payload.

```ts
interface MachineStatusChange
```

**Properties**

- `machineId` (`string`): Id of the machine whose status changed.
- `name` (`string`): Name of the machine.
- `status` (`'online' | 'offline'`): New connection status.

Source: [src/chat/machine-protocol.ts:218](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L218)

### `MachineUseStatus`

Interface.

State of one saved server used as a machine by this host.

```ts
interface MachineUseStatus
```

**Properties**

- `detail?` (`string`): Why the link is not connected. Never a token.
- `hostId` (`string`): The saved server's host id.
- `machineName?` (`string`): The server's machine name on this host, once attached.
- `state` (`MachineLinkState`): Connection state of the link.

Source: [src/chat/machine-protocol.ts:250](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L250)

### `MarkdownDeltaOptions`

Interface.

Options for [`appendMarkdownDelta`](https://zidane.si/docs/reference/chat-pure.md#appendMarkdownDelta).

```ts
interface MarkdownDeltaOptions
```

**Properties**

- `segmentChars?` (`number`): Split threshold for a growing block (default
  [`STREAMING_MARKDOWN_SEGMENT_CHARS`](https://zidane.si/docs/reference/chat-pure.md#STREAMING_MARKDOWN_SEGMENT_CHARS)). `Infinity` keeps one event per
  streamed message — for a host whose reloaded transcript shows messages
  whole and whose renderer chunks long text itself.

Source: [src/chat/streaming-pure.ts:123](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L123)

### `MarkdownSegment`

Interface.

One block returned by [`splitMarkdownCodeBlocks`](https://zidane.si/docs/reference/chat-pure.md#splitMarkdownCodeBlocks). Prose segments
carry their original markdown (including blank lines that bracketed
the fence) so the surrounding paragraph spacing stays faithful to the
original input. Code segments carry the raw body — fence markers and
info-string stripped — so a "copy code" action lands what the user
actually sees, byte-for-byte.

```ts
interface MarkdownSegment
```

**Properties**

- `content` (`string`): Prose markdown, or the raw code body without fence markers.
- `kind` (`'code' | 'prose'`): Whether the segment is markdown prose or a fenced code body.
- `lang?` (`string`): Info-string (e.g. `ts`, `python`). Empty when the fence had none.
- `open?` (`boolean`): Meant for a code segment whose closing fence hasn't arrived yet.
  [`splitMarkdownCodeBlocks`](https://zidane.si/docs/reference/chat-pure.md#splitMarkdownCodeBlocks) never sets it: it returns an unclosed
  fence as prose instead.

Source: [src/chat/markdown-segments.ts:24](https://github.com/Tahul/zidane/blob/main/src/chat/markdown-segments.ts#L24)

### `McpFormResult`

Interface.

A validated form: the config entry to write and where to write it.

```ts
interface McpFormResult
```

**Properties**

- `clientSecret?` (`string`): Client secret from the Advanced OAuth section. Deliberately NOT in
  `entry`: hosts keep it in the MCP credential store, out of `mcps.json`.
- `entry` (`McpServerConfig`): Normalized server config.
- `scope` (`InstallScopeChoice`): Where the entry should be written.

Source: [src/chat/mcp-form.ts:53](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L53)

### `McpFormValues`

Interface.

Raw field values of the add-MCP-server form.

```ts
interface McpFormValues
```

**Properties**

- `commandLine` (`string`): stdio: full command line (first token = command, rest = args).
- `env` (`string`): One `KEY=VALUE` per line — stdio only. Values may contain spaces.
- `headers` (`string`): One `Name: value` (or `Name=value`) per line — http/sse only.
- `name` (`string`): Server name. Letters, digits, dots, hyphens and underscores.
- `oauthCallbackPort?` (`string`): Raw field text; validated to an unprivileged port.
- `oauthClientId?` (`string`): Advanced OAuth (http/sse only): a pre-registered client for auth
  servers without dynamic client registration. Optional so forms that
  don't render the section keep compiling.
- `oauthClientSecret?` (`string`): Secret of the pre-registered client, when it has one.
- `oauthScope?` (`string`): Space- or comma-separated OAuth scopes to request.
- `scope` (`InstallScopeChoice`): Whether to write the entry to the user or the project config.
- `transport` (`McpTransport`): Transport the server uses.
- `url` (`string`): http/sse: server URL.

Source: [src/chat/mcp-form.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L23)

### `McpTestResult`

Interface.

Classified result of one MCP connection test.

```ts
interface McpTestResult
```

**Properties**

- `kind` (`McpTestOutcomeKind`): How the server answered.
- `message?` (`string`): User-facing explanation for non-`ok` kinds.
- `tools?` (`number`): Number of tools listed. Set for `ok`.

Source: [src/chat/mcp-test-outcome.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-test-outcome.ts#L21)

### `MediaType`

Interface.

A media file's kind and MIME type.

```ts
interface MediaType
```

**Properties**

- `kind` (`MediaKind`): How it plays.
- `mime` (`string`): Its MIME type.

Source: [src/chat/workspace/media-type.ts:9](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/media-type.ts#L9)

### `ModelChainEntry`

Interface.

One provider+model pair in a fallback chain.

```ts
interface ModelChainEntry
```

**Properties**

- `account?` (`string`): The stored account of `provider` this entry runs on (a credential's
  stable id, see `chat/credentials`). Absent = the provider's active
  account (a chain persisted without accounts reads this way).
- `model` (`string`): Model id of the pick.
- `provider` (`string`): Provider key of the pick.

Source: [src/chat/model-chain.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/model-chain.ts#L17)

### `ModelDisplayName`

Interface.

Display name of a model, with its vendor when the name carried one.

```ts
interface ModelDisplayName
```

**Properties**

- `name` (`string`): Name to show.
- `vendor?` (`string`): The model's maker, when the name carried it (aggregators: "Anthropic").

Source: [src/chat/model-name.ts:25](https://github.com/Tahul/zidane/blob/main/src/chat/model-name.ts#L25)

### `ModelIdParts`

Interface.

Parsed shape of a model id. Exported for tests and for pickers that want to show a family label.

```ts
interface ModelIdParts
```

**Properties**

- `family` (`string`): The words of the id, lowercased and joined with `-`.
- `size` (`string`): Size tokens joined with `-` (`27b`, `235b-a22b`); '' when absent.
- `snapshot` (`string`): Dated / numbered snapshot (`20251001`, `2024-05-13` → `20240513`, `0731`); '' for the plain alias.
- `variant` (`string`): Routing variant after `:` (`batch`, `free`); '' when absent.
- `vendor` (`string`): `vendor/` prefix on aggregator ids (`anthropic` in `anthropic/claude-opus-5`), lowercased; '' when absent.
- `version` (`number[]`): Numeric version segments in order; empty when the id carries none.

Source: [src/chat/model-lineup.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/model-lineup.ts#L19)

### `ModelNameInput`

Interface.

Input of [`modelDisplayName`](https://zidane.si/docs/reference/chat-pure.md#modelDisplayName).

```ts
interface ModelNameInput
```

**Properties**

- `modelId` (`string`): Model id as the provider names it.
- `modelName?` (`string | null`): The catalog's display name, when known.
- `providerKey?` (`string | null`): Provider key. Inferred as `anthropic` for ids starting with `claude` when absent.

Source: [src/chat/model-name.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/model-name.ts#L15)

### `ModelSettingPick`

Interface.

Model choices stored as one settings string (`compactionModel`, a space's
default in the GUI rows): `"providerKey/modelId"`, or
`"providerKey@account/modelId"` for a pinned account (a credential's stable
id). Split on the FIRST slash — model ids may contain slashes, provider
keys and credential ids never do. Node-free: shared by the hosts and the
GUI renderer (`zidane/chat/pure`).

```ts
interface ModelSettingPick
```

**Properties**

- `account?` (`string`): The stored account of the provider (credential id); absent = its active account.
- `modelId` (`string`): Model id.
- `providerKey` (`string`): Provider key.

Source: [src/chat/model-setting.ts:10](https://github.com/Tahul/zidane/blob/main/src/chat/model-setting.ts#L10)

### `ModeState`

Interface.

The terminal modes a program's output has left set, as [`scanModes`](https://zidane.si/docs/reference/chat-pure.md#scanModes) follows them.

```ts
interface ModeState
```

**Properties**

- `altAt` (`number | null`, readonly): Stream offset of the sequence that entered the alternate screen, while it is active.
- `keypad` (`boolean | null`, readonly): Application keypad (`ESC =`), when it was set or reset.
- `modes` (`ReadonlyMap<number, boolean>`, readonly): DEC private modes last set (true) or reset (false).

Source: [src/contexts/terminal-modes.ts:20](https://github.com/Tahul/zidane/blob/main/src/contexts/terminal-modes.ts#L20)

### `NativeExtensionCommandNeed`

Interface.

A program a native extension runs, looked up on PATH.

```ts
interface NativeExtensionCommandNeed
```

**Properties**

- `kind` (`'command'`): The need kind.
- `name` (`string`): The program.
- `optional?` (`boolean`): The extension works without it, with less.
- `why` (`string`): What it is used for.

Source: [src/chat/onboarding/types.ts:418](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L418)

### `NativeExtensionEntry`

Interface.

An extension of the zidane repository's `extensions/` folder, installable in one click.

```ts
interface NativeExtensionEntry
```

**Properties**

- `brand?` (`string`): Its logo, as a Simple Icons slug (`git`). Absent: the app shows its own mark or a letter.
- `description` (`string`): One line on what it adds.
- `group` (`NativeExtensionGroup`): Section it is listed under.
- `icon?` (`{ gui?: string; tui?: string }`): Its icon, as its definition declares it (`gui`: an icon class such as `'i-ph-target'`). Drawn where it has no logo.
- `label` (`string`): Display name.
- `name` (`string`): Folder name in `extensions/`, also the extension's name.
- `needs` (`readonly NativeExtensionNeed[]`): What it needs to work.
- `provider?` (`string`): The provider key it registers, for the provider extensions listed under Connect.

Source: [src/chat/onboarding/types.ts:444](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L444)

### `NativeExtensionGroupMeta`

Interface.

A section of the Extensions step.

```ts
interface NativeExtensionGroupMeta
```

**Properties**

- `id` (`NativeExtensionGroup`): The section.
- `label` (`string`): Its heading.

Source: [src/chat/onboarding/native-extensions.ts:79](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/native-extensions.ts#L79)

### `NestedEventTag`

Interface.

Where nested events sit in the transcript; copied onto each event when set.

```ts
interface NestedEventTag
```

**Properties**

- `childId?` (`string`): Subagent that made the call; absent for the top-level agent.
- `depth?` (`number`): Nesting depth: 0 for the top-level agent, 1 and up for subagents.
- `turnId?` (`string`): Turn of the calling tool.

Source: [src/chat/nested-call-events.ts:49](https://github.com/Tahul/zidane/blob/main/src/chat/nested-call-events.ts#L49)

### `OnboardingAppearance`

Interface.

The look of the desktop app, as a portable value. It has the mode (light,
dark or the system's) and a theme for each mode. It also has an accent that
replaces the accent of the theme, and the app icon.

```ts
interface OnboardingAppearance
```

**Properties**

- `accent` (`string | null`): `#rrggbb` replacing the theme's accent, or `null` for the theme's own.
- `darkTheme` (`string`): Theme id used in dark mode.
- `icon?` (`string`): Id of the app icon, for an app that offers several (the desktop app). Absent: the app keeps its icon.
- `lightTheme` (`string`): Theme id used in light mode.
- `mode` (`'system' | 'light' | 'dark'`): Light, dark, or the system's.

Source: [src/chat/onboarding/types.ts:506](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L506)

### `OnboardingCustomField`

Interface.

A setting a provider needs besides its key (a base URL, a cloud project), as the Connect step asks for it.

```ts
interface OnboardingCustomField
```

**Properties**

- `hint?` (`string`): Helper text under the label.
- `key` (`string`): Storage key inside the stored credential.
- `label` (`string`): Field label.
- `placeholder?` (`string`): Input placeholder.
- `required?` (`boolean`): An empty value is refused.

Source: [src/chat/onboarding/types.ts:89](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L89)

### `OnboardingDetection`

Interface.

What the wizard found on this machine before its first step.

```ts
interface OnboardingDetection
```

**Properties**

- `agents` (`readonly OnboardingAgentId[]`): Other agents whose configuration exists here.
- `github?` (`OnboardingGithubIdentity`): The GitHub account in use. Absent when none is set up.
- `localServers` (`readonly OnboardingLocalServer[]`): Local model servers that answered.
- `providers` (`readonly OnboardingProvider[]`): Every provider the Connect step offers, with its status.
- `signals` (`OnboardingInstallSignals`): Signs of an install that predates the wizard.

Source: [src/chat/onboarding/types.ts:167](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L167)

### `OnboardingDraft`

Interface.

Everything a run has picked so far. Settings stay in one map, so they diff against what is stored.

```ts
interface OnboardingDraft
```

**Properties**

- `appearance?` (`OnboardingAppearance`): The desktop app's look.
- `connectors` (`readonly string[]`): Connector ids picked.
- `extensions` (`readonly string[]`): Native extension names picked.
- `imports?` (`OnboardingImportSelection`): Bring your setup's selection.
- `path` (`'custom' | 'quick'`): The Welcome choice.
- `provider?` (`OnboardingProviderPick`): Connect's pick. Credentials are saved when signing in, not at the end.
- `settings` (`Partial<Settings>`): Every setting the run edits: theme, transcript, autonomy, features.
- `skills` (`readonly SkillPick[]`): Skills picked, from any source.

Source: [src/chat/onboarding/types.ts:520](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L520)

### `OnboardingFeature`

Interface.

A toggle the Features step offers. Its label and description are the setting's own (`SETTINGS_TOGGLES`).

```ts
interface OnboardingFeature
```

**Properties**

- `badges?` (`readonly OnboardingFeatureBadge[]`): Marks shown next to the label.
- `example` (`string`): One sentence that shows the feature at work, starting with "For example,".
  Text between backticks is code: a path, a command or an address.
- `group` (`OnboardingFeatureGroup`): Section it is listed under.
- `includes?` (`readonly BooleanSettingKey[]`): Settings that turn on with this feature, such as Agent can use the browser
  with Browser tab. The step shows no switch for them. Settings does.
  Turning the feature off leaves them as they are.
- `key` (`BooleanSettingKey`): The setting it flips.
- `prevents` (`string`): What it guards against. A sentence that applies when it is off says so ("Off, …").
- `surfaces` (`readonly OnboardingSurface[]`): The apps that offer it.
- `unlocks` (`string`): What turning it on gives you, in one or two sentences.

Source: [src/chat/onboarding/types.ts:308](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L308)

### `OnboardingFeatureCopy`

Interface.

A feature's label and description: the setting's own.

```ts
interface OnboardingFeatureCopy
```

**Properties**

- `description` (`string`): One line on what it does.
- `label` (`string`): Row label.

Source: [src/chat/onboarding/features.ts:181](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/features.ts#L181)

### `OnboardingFeatureGroupMeta`

Interface.

A section of the Features step.

```ts
interface OnboardingFeatureGroupMeta
```

**Properties**

- `id` (`OnboardingFeatureGroup`): The section.
- `label` (`string`): Its heading.

Source: [src/chat/onboarding/features.ts:149](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/features.ts#L149)

### `OnboardingFlowState`

Interface.

Where a run is.

```ts
interface OnboardingFlowState
```

**Properties**

- `context` (`OnboardingPlanContext`): What decides the steps. `mode` is the mode the run opened in.
- `done` (`boolean`): The last step was passed: the run is finished.
- `draft` (`OnboardingDraft`): Everything picked so far.
- `index` (`number`): Index of the current step in `steps`.
- `initial` (`OnboardingDraft`): The draft the run started from: what Skip goes back to, and what the result diffs against.
- `steps` (`readonly OnboardingStepId[]`): The steps of this run, in order.
- `tasks` (`readonly OnboardingTask[]`): Imports and installs the steps started.

Source: [src/chat/onboarding/flow.ts:56](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L56)

### `OnboardingGateInput`

Interface.

What [`needsOnboarding`](https://zidane.si/docs/reference/chat-pure.md#needsOnboarding) reads.

```ts
interface OnboardingGateInput
```

**Properties**

- `disabled?` (`boolean`): The wizard is turned off: `ZIDANE_NO_ONBOARDING=1`, an embedder's `onboarding: false`, a headless run.
- `signals` (`OnboardingInstallSignals`): What the app read from this machine.
- `state` (`OnboardingState | undefined`): The records in the state file.
- `surface` (`OnboardingSurface`): The app asking.

Source: [src/chat/onboarding/result.ts:79](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/result.ts#L79)

### `OnboardingGithubIdentity`

Interface.

The GitHub account the `gh` CLI or a token in the environment uses.

```ts
interface OnboardingGithubIdentity
```

**Properties**

- `login?` (`string`): GitHub login, when known.
- `source` (`string`): Where the token comes from (`gh CLI`, `GH_TOKEN`, `GITHUB_TOKEN`).

Source: [src/chat/onboarding/types.ts:159](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L159)

### `OnboardingImportCategory`

Interface.

What an import brings over and what it skips, for one piece.

```ts
interface OnboardingImportCategory
```

**Properties**

- `copy` (`readonly string[]`): Names that it copies.
- `skip` (`readonly string[]`): Names that it skips, because zidane already has them.

Source: [src/chat/onboarding/types.ts:226](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L226)

### `OnboardingImportPreview`

Interface.

What Bring your setup shows before anything is imported.

```ts
interface OnboardingImportPreview
```

**Properties**

- `agents` (`OnboardingImportCategory`): Subagents.
- `commands` (`OnboardingImportCategory`): Slash commands.
- `mcps` (`OnboardingImportCategory`): MCP servers.
- `notes` (`readonly string[]`): What is deliberately not imported, spelled out for the step.
- `sessions` (`OnboardingImportSessionCounts`): Claude Code transcripts.
- `skills` (`OnboardingImportCategory`): Skills.

Source: [src/chat/onboarding/types.ts:242](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L242)

### `OnboardingImportSelection`

Interface.

What to import from Claude Code. Each piece is skipped when false.

```ts
interface OnboardingImportSelection
```

**Properties**

- `agents` (`boolean`): Subagents, copied into zidane's agents folder.
- `allProjects` (`boolean`): Take sessions from every Claude Code project, not only the current one.
- `commands` (`boolean`): Slash commands, copied into zidane's commands folder.
- `mcps` (`boolean`): MCP servers, copied into zidane's own `mcps.json`.
- `sessions` (`boolean`): Conversations, converted into zidane sessions.
- `skills` (`boolean`): Skills, copied into zidane's skills folder.

Source: [src/chat/onboarding/types.ts:210](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L210)

### `OnboardingImportSessionCounts`

Interface.

The transcript counts Bring your setup shows.

```ts
interface OnboardingImportSessionCounts
```

**Properties**

- `all` (`number`): Transcripts of every project.
- `project` (`number`): Transcripts of the current project.

Source: [src/chat/onboarding/types.ts:234](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L234)

### `OnboardingInstallSignals`

Interface.

What tells an install that existed before the wizard from a fresh one.

```ts
interface OnboardingInstallSignals
```

**Properties**

- `credentials` (`boolean`): Credentials are stored for at least one provider.
- `lastProvider` (`boolean`): A provider was used before (`lastProvider`).
- `sessions` (`boolean`): The session store holds at least one session.
- `storedSettings` (`boolean`): The state file holds settings someone chose.
- `surfaceFirstRun` (`boolean`): This app has never run on this machine (the desktop app: its appearance store is empty).

Source: [src/chat/onboarding/types.ts:145](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L145)

### `OnboardingLocalServer`

Interface.

A local OpenAI-compatible model server answering on its default port.

```ts
interface OnboardingLocalServer
```

**Properties**

- `kind` (`'vllm' | 'ollama' | 'lm-studio'`): Which server answered.
- `url` (`string`): Its base URL, as the Local LLM provider takes it.

Source: [src/chat/onboarding/types.ts:137](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L137)

### `OnboardingPlanContext`

Interface.

What decides which steps a run shows.

```ts
interface OnboardingPlanContext
```

**Properties**

- `exclude?` (`readonly OnboardingStepId[]`): Steps that this host leaves out, such as one whose data it cannot provide.
- `importAvailable` (`boolean`): Another agent's configuration was found on this machine: Bring your setup shows.
- `installsAvailable` (`boolean`): Connectors and extensions install on this machine. False for a client of a remote host.
- `mode` (`OnboardingMode`): How much of the wizard runs.
- `surface` (`OnboardingSurface`): The app that runs it.

Source: [src/chat/onboarding/types.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L65)

### `OnboardingProgress`

Interface.

How far a run is: the current step's position and the number of steps.

```ts
interface OnboardingProgress
```

**Properties**

- `count` (`number`): Number of steps in the run.
- `index` (`number`): Zero-based position of the current step.

Source: [src/chat/onboarding/flow.ts:295](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L295)

### `OnboardingProvider`

Interface.

A provider as the Connect step lists it: what it is, how it signs in, and whether it is ready.

```ts
interface OnboardingProvider
```

**Properties**

- `apiKey` (`boolean`): It takes an API key. False for providers configured by fields only (a local server).
- `apiKeyPlaceholder?` (`string`): Placeholder of the API key field.
- `brand?` (`string`): Its logo, as a Simple Icons slug (`anthropic`). Absent: the app shows a letter.
- `customFields` (`readonly OnboardingCustomField[]`): Fields asked before the key.
- `description?` (`string`): One line on what it serves and how it signs in.
- `envKey?` (`string`): The environment variable the key was found in, for a `source` of `env`.
- `featured` (`boolean`): Shown first, before the "More" list.
- `key` (`string`): Registry key (`anthropic`, `openai`, an extension's key).
- `label` (`string`): Display name.
- `oauth` (`boolean`): It can sign in through a browser (a subscription or an account).
- `oauthHint?` (`string`): What the browser sign-in uses instead of a key (`Claude Pro or Max plan`).
- `ready` (`boolean`): A credential is ready: stored, signed in or found in the environment.
- `signInLabel?` (`string`): The account its browser sign-in uses, as a button names it (`Claude`).
- `source?` (`OnboardingCredentialSource`): Where the ready credential came from. Absent while not ready.
- `viaExtension?` (`string`): The native extension that adds this provider, when it is not installed yet.

Source: [src/chat/onboarding/types.ts:103](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L103)

### `OnboardingProviderPick`

Interface.

The provider, model and effort picked in Connect.

```ts
interface OnboardingProviderPick
```

**Properties**

- `effort?` (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive'`): Reasoning effort, for a model that has one.
- `key` (`string`): Provider key.
- `model?` (`string`): Model id. Absent: the provider's default.

Source: [src/chat/onboarding/types.ts:492](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L492)

### `OnboardingReadable`

Interface.

A value that a UI reads and watches. It has the shape of `Readable` in `zidane-ui`.

```ts
interface OnboardingReadable<T>
```

**Type parameters**

- `T`

**Properties**

- `get` (`() => T`): Returns the current value.
- `subscribe` (`(onChange: () => void) => () => void`): Calls `onChange` after the value changes. Returns a function that stops the calls.

Source: [src/chat/onboarding/run.ts:38](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L38)

### `OnboardingRecord`

Interface.

The record of one finished run.

```ts
interface OnboardingRecord
```

**Properties**

- `completedAt` (`string`): When it finished, as an ISO 8601 timestamp.
- `migrated?` (`true`): Written for an install that predates the wizard: nothing was shown.
- `surface` (`OnboardingSurface`): The app it ran in.
- `version` (`number`): Version of the wizard that ran (`ONBOARDING_VERSION`).

Source: [src/chat/onboarding/types.ts:548](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L548)

### `OnboardingResult`

Interface.

What a finished run writes. Installs and imports ran during their steps, and this is the rest.

```ts
interface OnboardingResult
```

**Properties**

- `appearance?` (`OnboardingAppearance`): The desktop app's look.
- `mode` (`OnboardingMode`): The mode it ran in.
- `provider?` (`OnboardingProviderPick`): The provider, model and effort to start on.
- `records` (`OnboardingState`): Records to write, merged into the stored ones.
- `settings` (`OnboardingSettingsChange`): Settings to set and to reset.
- `surface` (`OnboardingSurface`): The app it ran in.

Source: [src/chat/onboarding/types.ts:598](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L598)

### `OnboardingRun`

Interface.

A run and the work that it starts.

```ts
interface OnboardingRun
```

**Properties**

- `connectorInput` (`(id: string) => ConnectorInput`): Returns what the user typed for a connector.
- `dispatch` (`(action: OnboardingAction) => void`): Applies an action. Picking an extension that works through a connector
  also picks the connector, unless it is installed, imported or picked.
  Passing a step starts what the user picked there. Passing the last step
  saves the result.
- `dispose` (`() => void`): Ends the run. A run that never saved puts the previewed look back.
- `importPreview` (`OnboardingReadable<OnboardingImportPreviewState>`): What an import from Claude Code brings over.
- `phase` (`OnboardingReadable<OnboardingPhase>`): Where the run is in its life.
- `retry` (`(taskId: string) => void`): Runs a failed task again.
- `setConnectorInput` (`(id: string, input: ConnectorInput) => void`): Keeps what the user typed for a connector, such as a token. A token is a secret, so it stays out of the draft.
- `state` (`OnboardingReadable<OnboardingFlowState>`): The steps, the picks and the background tasks.

Source: [src/chat/onboarding/run.ts:155](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L155)

### `OnboardingRunHost`

Interface.

The work that a run asks the app to do. If a member is left out, that work does not run.

```ts
interface OnboardingRunHost
```

**Properties**

- `commit` (`(result: OnboardingResult) => Promise<void>`): Writes what a finished run decided.
- `connectors?` (`{ add: (id: string, input?: ConnectorInput) => Promise<void>; installed: () => readonly string[]; signInLater?: boolean }`): Connectors.
- `extensions?` (`{ install: (name: string, onProgress?: (line: string) => void) => Promise<void>; installed: () => readonly string[] }`): Native extensions.
- `imports?` (`{ preview: () => Promise<OnboardingImportPreview>; run: (selection: OnboardingImportSelection) => Promise<void> }`): The import from Claude Code. Leave it out when there is no Claude Code setup.
- `previewLook?` (`(appearance: OnboardingAppearance | null) => void`): Shows a look of the desktop app live. `null` puts the current look back.
- `skills?` (`{ install: (source: string, rels: readonly string[], onProgress?: (line: string) => void) => Promise<void>; installed: () => readonly string[] }`): Skills.

Source: [src/chat/onboarding/run.ts:97](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L97)

### `OnboardingRunOptions`

Interface.

Options of [`createOnboardingRun`](https://zidane.si/docs/reference/chat-pure.md#createOnboardingRun).

```ts
interface OnboardingRunOptions
```

**Properties**

- `now?` (`() => Date`): The clock of the records. It defaults to the current time.
- `start?` (`OnboardingStepId`): Opens the run at this step instead of its first one, when the run has it.

Source: [src/chat/onboarding/run.ts:147](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L147)

### `OnboardingRunSetup`

Interface.

What a run starts from.

```ts
interface OnboardingRunSetup
```

**Properties**

- `appearance?` (`OnboardingAppearance`): The look of the desktop app now.
- `context` (`OnboardingPlanContext`): The mode, the app, and what was found.
- `provider?` (`OnboardingProviderPick`): The provider, model and effort in use now, for a re-run.
- `settings` (`Partial<Settings>`): The stored settings: explicit choices only, without the defaults.

Source: [src/chat/onboarding/run.ts:135](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L135)

### `OnboardingRunStart`

Interface.

A run that started and has not finished.

```ts
interface OnboardingRunStart
```

**Properties**

- `startedAt` (`string`): When it started, as an ISO 8601 timestamp.
- `surface` (`OnboardingSurface`): The app it started in.

Source: [src/chat/onboarding/types.ts:560](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L560)

### `OnboardingSettingsChange`

Interface.

What a run does to the stored settings: keys it sets, and keys it returns to their default.

```ts
interface OnboardingSettingsChange
```

**Properties**

- `reset` (`readonly keyof Settings[]`): Keys to remove from the stored settings, so they follow the default again.
- `set` (`Partial<Settings>`): Keys to store, with their values.

Source: [src/chat/onboarding/types.ts:540](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L540)

### `OnboardingStart`

Interface.

The draft a run starts from.

```ts
interface OnboardingStart
```

**Properties**

- `appearance?` (`OnboardingAppearance`): The desktop app's current look, for the desktop app.
- `provider?` (`OnboardingProviderPick`): The provider in use now, for a re-run.
- `settings` (`Settings`): The settings in effect now: the stored ones over the defaults.

Source: [src/chat/onboarding/flow.ts:108](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L108)

### `OnboardingState`

Interface.

The wizard's records in the state file: `shared` for the steps both apps
read, and one per app for that app's own steps.

```ts
interface OnboardingState
```

**Properties**

- `desktop?` (`OnboardingRecord`): The desktop app's own steps ran.
- `inProgress?` (`OnboardingRunStart`): A run started and did not finish. The next launch resumes it, even when
  Connect already stored credentials. The records of a finished run clear it.
- `shared?` (`OnboardingRecord`): The shared steps ran (or the install predates the wizard).
- `tui?` (`OnboardingRecord`): The terminal app's own steps ran.

Source: [src/chat/onboarding/types.ts:571](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L571)

### `OnboardingStepMeta`

Interface.

Display data of one step. Renderers style the copy. They never rewrite it.

```ts
interface OnboardingStepMeta
```

**Properties**

- `id` (`OnboardingStepId`): The step.
- `label` (`string`): Short name, for the progress rail and the recap.
- `lede` (`string`): One sentence under the title.
- `scope` (`OnboardingStepScope`): What the step writes.
- `title` (`string`): The step's question or heading.

Source: [src/chat/onboarding/types.ts:51](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L51)

### `OnboardingSwitchedFeatures`

Interface.

The features a run switched, by their Settings label.

```ts
interface OnboardingSwitchedFeatures
```

**Properties**

- `off` (`string[]`): The ones it turned off.
- `on` (`string[]`): The ones it turned on.

Source: [src/chat/onboarding/recap.ts:35](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/recap.ts#L35)

### `OnboardingTask`

Interface.

An import or install that the wizard started. Ready lists them.

```ts
interface OnboardingTask
```

**Properties**

- `id` (`string`): `<kind>:<name>`, unique in a run.
- `kind` (`OnboardingTaskKind`): What it does.
- `label` (`string`): What it is about (`Linear`, `git-flow`, `Claude Code`).
- `message?` (`string`): The last progress line, or the error.
- `status` (`OnboardingTaskStatus`): Where it is.

Source: [src/chat/onboarding/types.ts:474](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L474)

### `OnboardingTradeoff`

Interface.

What a choice gives you and what it guards against, as the wizard shows them side by side.

```ts
interface OnboardingTradeoff
```

**Properties**

- `prevents` (`string`): What it guards against. A sentence that applies when it is off says so.
- `unlocks` (`string`): What the choice gives you.

Source: [src/chat/onboarding/types.ts:335](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L335)

### `OutputHistoryOptions`

Interface.

Optional caps for an [`OutputHistory`](https://zidane.si/docs/reference/chat-pure.md#OutputHistory).

```ts
interface OutputHistoryOptions
```

**Properties**

- `maxLines?` (`number`): Also evict once more than this many lines are kept, except while the
  program is on the alternate screen (a replay needs all of it).

Source: [src/chat/terminal/output-history.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/output-history.ts#L65)

### `OutputLine`

Interface.

One line of output.

```ts
interface OutputLine
```

**Properties**

- `id` (`number`): The line's number in the whole output, from 0: the same while the line
  shows (a command's line keeps its id as it is written, then ended), so a
  view can key on it and animate only what is new.
- `line?` (`number`): Script line of the call that wrote it (codemode).
- `spans?` (`AnsiSpan[]`): The same text in styled spans, when it had colors or styles (ANSI codes).
- `stream` (`OutputStream`): Where it came from.
- `text` (`string`): The line's visible text, without its newline, cut to the tail's width.

Source: [src/chat/output-tail.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/output-tail.ts#L19)

### `OutputTail`

Interface.

The last lines of an output.

```ts
interface OutputTail
```

**Properties**

- `chunk` (`(stream: OutputStream, text: string, line?: number) => void`): A chunk of a command's output, which can end mid-line.
- `item` (`(stream: OutputStream, text: string, line?: number) => void`): A whole item: each of its lines.
- `lines` (`() => OutputLine[]`): The last lines, oldest first; a command's line still being written comes last.

Source: [src/chat/output-tail.ts:37](https://github.com/Tahul/zidane/blob/main/src/chat/output-tail.ts#L37)

### `PageOptions`

Interface.

Options of [`paginate`](https://zidane.si/docs/reference/chat-pure.md#paginate).

```ts
interface PageOptions
```

**Properties**

- `cursor?` (`string`): The cursor of the previous page. Absent: the first page.
- `limit` (`number`): Rows per page, 1 to [`MAX_PAGE_SIZE`](https://zidane.si/docs/reference/chat-pure.md#MAX_PAGE_SIZE).
- `scope?` (`unknown`): Anything else that chose the rows (such as `archived`), as JSON. Only signs the cursor.
- `sort?` (`readonly SessionSort[]`): The sort the rows are in, without the id tiebreak: the rows must be
  sorted by [`withIdTiebreak`](https://zidane.si/docs/reference/chat-pure.md#withIdTiebreak) of it ([`querySessions`](https://zidane.si/docs/reference/chat-pure.md#querySessions) does).
- `where?` (`SessionQuery`): The filter the rows passed. Only signs the cursor: one made under another filter is refused.

Source: [src/chat/session-query/paginate.ts:18](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/paginate.ts#L18)

### `PaletteContext`

Interface.

JSON-safe snapshot of the host handed to providers. Never holds functions.

```ts
interface PaletteContext
```

**Properties**

- `busy?` (`boolean`): A run is in flight on the active session.
- `cwd?` (`string`): Working directory of the active session.
- `host` (`PaletteHost`): Which app is asking.
- `sessionId?` (`string`): Id of the active session.

Source: [src/chat/palette.ts:58](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L58)

### `PaletteGroup`

Interface.

A titled section of ranked palette rows.

```ts
interface PaletteGroup
```

**Properties**

- `rows` (`readonly RankedPaletteItem[]`): Rows in the section, in display order.
- `title` (`string`): Section header.

Source: [src/chat/palette.ts:375](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L375)

### `PaletteItem`

Interface.

An entry in the command palette.

```ts
interface PaletteItem
```

**Properties**

- `checked?` (`boolean`): For `toggle` items.
- `description?` (`string`): Secondary text shown beside the title.
- `disabled?` (`string`): Reason the item cannot run right now; it stays listed, muted.
- `group` (`string`): Section header. Hosts order groups by first appearance after `Recent`.
- `icon?` (`PanelIcon`): Icon for each renderer.
- `id` (`string`): Stable, unique across providers: `builtin:openSettings`, `slash:compact`, `<extension>/<id>`.
- `keybinding?` (`string`): Resolved chord spec (`ctrl+shift+k`); the host formats it for display.
- `keywords?` (`readonly string[]`): Extra search terms not shown in the row.
- `kind?` (`PaletteItemKind`): How the item behaves. Treated as `action` when omitted.
- `searchOnly?` (`boolean`): Only appears once the query matches it: bulk catalogs (every file in
  the project) stay out of the empty-query listing but are one keystroke
  away.
- `source` (`string`): Provider that owns `run` for this item. Stamped by the aggregator.
- `title` (`string`): Text shown in the row.

Source: [src/chat/palette.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L26)

### `PaletteProvider`

Interface.

Source of palette items and the handler that runs them.

```ts
interface PaletteProvider
```

**Properties**

- `id` (`string`): Provider id, stamped on its items as `source`.
- `items` (`(ctx: PaletteContext) => readonly PaletteItem[] | Promise<readonly PaletteItem[]>`): Items for the current context. Called on open, on `subscribe` emits, and on explicit refresh.
- `run` (`(itemId: string, ctx: PaletteContext) => PaletteRunResult | Promise<PaletteRunResult>`): Runs the item with the given id. May return a follow-up result.
- `subscribe?` (`(emit: () => void) => () => void`): Live updates while the palette is open, same contract as panels.

Source: [src/chat/palette.ts:84](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L84)

### `PanelCatalogOptions`

Interface.

Options for [`buildPanelCatalog`](https://zidane.si/docs/reference/chat-pure.md#buildPanelCatalog).

```ts
interface PanelCatalogOptions
```

**Properties**

- `omitBuiltins?` (`readonly BuiltinPanelId[]`): Built-in ids the host does not render (the TUI keeps only the artifacts tab).
- `showArtifacts?` (`boolean`): Hide the artifacts tab (the user's `artifacts: false` setting).
- `showReminders?` (`boolean`): Show the reminders tab (`Settings.schedules` on). Absent or false: hidden.
- `showSecrets?` (`boolean`): Show the secrets tab (`Settings.secrets` on). Absent or false: hidden.
- `unbound?` (`boolean`): No session is bound (only a folder is open): keep just the extension
  panels that opted in (`scope: 'project' | 'both'`). Bound (the
  default), `scope: 'project'` panels are dropped. Built-ins are not
  filtered here; hosts drop session-only ones via `omitBuiltins`.

Source: [src/chat/panels.ts:99](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L99)

### `PanelState`

Interface.

Open state of the side panel.

```ts
interface PanelState
```

**Properties**

- `activeId` (`string | null`): Active tab id; `null` when nothing has been chosen yet (hosts pick the first tab).
- `open` (`boolean`): Whether the side panel is open.
- `proactiveAt` (`number`): `userPicks` value at the last proactive open that was honoured.
- `userPicks` (`number`): Monotonic counter bumped on every user pick; gates proactive opens.

Source: [src/chat/panels.ts:159](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L159)

### `ParsedBinding`

Interface.

Parsed shape of a `"ctrl+shift+o"` spec.

```ts
interface ParsedBinding
```

**Properties**

- `alt` (`boolean`): Whether `alt` (or `option`) is held.
- `ctrl` (`boolean`): Whether `ctrl` is held.
- `meta` (`boolean`): Whether `meta` (`cmd`, `super`, or `win`) is held.
- `name` (`string`): The key name (e.g. `'o'`, `'tab'`, `'escape'`). Always lowercase.
- `shift` (`boolean`): Whether `shift` is held.

Source: [src/chat/keybinding-spec.ts:9](https://github.com/Tahul/zidane/blob/main/src/chat/keybinding-spec.ts#L9)

### `ParsedWhen`

Interface.

A parsed time phrase: the trigger, and the text after the phrase (the prompt).

```ts
interface ParsedWhen
```

**Properties**

- `rest` (`string`): The text after the phrase: the prompt.
- `trigger` (`ScheduleTrigger`): The trigger the phrase names.

Source: [src/schedules/when.ts:18](https://github.com/Tahul/zidane/blob/main/src/schedules/when.ts#L18)

### `PresenceMerge`

Interface.

Presence across hosts. Each host (This computer, every connected server)
answers presence for its own sessions only; a sessions list reads one
snapshot. The last snapshot of each host is kept and the union handed out
on every change. A host that goes away takes its entries with it.
Node-free, shared by the TUI and the GUI main process.

```ts
interface PresenceMerge<Row extends { sessionId: string }>
```

**Type parameters**

- `Row` (`extends { sessionId: string }`)

**Properties**

- `forget` (`(hostKey: string) => boolean`): Drop a host's entries (offline, removed); `true` when it had any.
- `hosts` (`() => string[]`): The hosts with a snapshot (to notice the ones that went away).
- `merged` (`() => Row[]`): Every host's last snapshot, one after the other (an id two hosts hold is a row per host).
- `set` (`(hostKey: string, rows: readonly Row[]) => Row[]`): Replace one host's snapshot; returns the merged one.

Source: [src/chat/hosts/presence.ts:9](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/presence.ts#L9)

### `PreviewResult`

Interface.

Result of [`previewEditPayload`](https://zidane.si/docs/reference/chat-pure.md#previewEditPayload).

```ts
interface PreviewResult
```

**Properties**

- `diffText` (`string`): Full unified diff of the (resolvable) hunks against `priorContent`.
- `perHunkDiff` (`string[]`): Per-hunk isolated diff text rendered against the cumulative content
  after applying all earlier resolved hunks. Useful for the modal's
  focused-hunk view so hunk #N's preview reflects the state hunks
  1..N-1 will leave the file in (same as the tool's order).
- `resolution` (`HunkResolution[]`): 1:1 with `payload.hunks`.
- `resolvedPayload` (`EditPayload`): Resolved hunks with `oldString` rewritten to the haystack's actual
  bytes and `newString` re-styled to preserve curly-quote typography
  / line-prefix conventions. Pass this to `buildContextualDiff` to
  paint the unified diff.

Source: [src/chat/edit-diff.ts:705](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L705)

### `PromptSegmentRef`

Interface.

Highlight span — half-open `[start, end)` over the source string.

Offsets are JS string indices (UTF-16 code units) — the same convention used
everywhere else in the chat layer (`text[i]`, `m.index`, `String.slice`).
Surrogate pairs that straddle a span boundary would render malformed, but
realistic prompts in this surface (terminal text + ASCII triggers) keep that
risk theoretical; callers feeding emoji-heavy content should normalize to
codepoint walks upstream.

```ts
interface PromptSegmentRef
```

**Properties**

- `end` (`number`): Offset just past the last character of the span.
- `providerId` (`string`): Provider id tagging this span (`'skills'`, `'files'`, …). Free-form.
- `start` (`number`): Offset of the first character of the span.

Source: [src/chat/prompt-segments.ts:18](https://github.com/Tahul/zidane/blob/main/src/chat/prompt-segments.ts#L18)

### `PromptTurnRef`

Interface.

The minimum a prompt turn must carry to be matched against its live echo.

Exists because the daemon has to send this over a wire: a full `SessionTurn`
carries every content block, including base64 image and document payloads,
which would be megabytes per prompt to ship for the sake of attaching an id.

```ts
interface PromptTurnRef
```

**Properties**

- `attachmentOnly` (`boolean`): Whether the turn has attachments and no prompt text.
- `id` (`string`): Id of the user turn.
- `texts` (`readonly string[]`): Text blocks plus the `display` override, if any.

Source: [src/chat/turn-selection.ts:196](https://github.com/Tahul/zidane/blob/main/src/chat/turn-selection.ts#L196)

### `ProviderAccount`

Interface.

One stored credential of a provider that a session can run on (see `ProviderAuth.accounts`).

```ts
interface ProviderAccount
```

**Properties**

- `active` (`boolean`): The provider's active credential (what an unpinned session runs on).
- `id` (`string`): The credential's stable id: what a session pins (`metadata.account`).
- `kind` (`'oauth' | 'apikey'`): Whether the account is an OAuth grant or an API key.
- `label` (`string`): Display name: the OAuth account's label, or `API key`.

Source: [src/chat/auth.ts:71](https://github.com/Tahul/zidane/blob/main/src/chat/auth.ts#L71)

### `ProviderAuth`

Interface.

Authentication state of one provider, as listed by [`detectAuth`](https://zidane.si/docs/reference/chat.md#detectAuth).

```ts
interface ProviderAuth
```

**Properties**

- `accounts?` (`ProviderAccount[]`): The stored credentials a session can be pinned to, active first — set
  only when there is a choice: the provider's factory takes an account
  (`ProviderDescriptor.accounts`) and at least two are stored. Absent:
  one account (or none), so pickers show the provider as before.
- `available` (`boolean`): True when at least one credential source is present.
- `envKey?` (`string`): Env var this provider reads, when it declares one.

  Carried separately from `methods` because the settings list shows the
  env slot even when it holds nothing. `methods` only ever lists sources that
  are actually present, since `available` is derived from it.
- `key` (`string`): Provider key.
- `label` (`string`): Display name of the provider.
- `methods` (`AuthMethod[]`): Credential sources currently present, stored credentials first.

Source: [src/chat/auth.ts:83](https://github.com/Tahul/zidane/blob/main/src/chat/auth.ts#L83)

### `ProviderResetCredit`

Interface.

One banked reset.

```ts
interface ProviderResetCredit
```

**Properties**

- `expiresAt` (`number | null`): Epoch ms it expires, or `null` when it never does.
- `grantedAt` (`number | null`): Epoch ms it was granted, or `null` when unknown.
- `id` (`string`): The provider's id: redeem this one with it.
- `title` (`string | null`): The provider's name for it (`Full reset (Weekly + 5 hr)`), or `null`.

Source: [src/chat/provider-usage-format.ts:47](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L47)

### `ProviderResetOutcome`

Interface.

What redeeming a banked reset did. `reset`: the windows were emptied;
`nothing_to_reset`: no window had usage, so nothing was spent; `no_credit`:
no reset left; `already_redeemed`: this request was already applied;
`failed`: the request failed (`error` says why), possibly before reaching
the provider.

```ts
interface ProviderResetOutcome
```

**Properties**

- `code` (`'failed' | 'reset' | 'nothing_to_reset' | 'no_credit' | 'already_redeemed'`): What happened (see above).
- `error` (`string | null`): Short failure reason when `code` is `failed`.
- `windowsReset` (`number`): Windows the reset emptied (`0` unless `code` is `reset`).

Source: [src/chat/provider-usage-format.ts:65](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L65)

### `ProviderUsageCredits`

Interface.

Remaining credits for pay-as-you-go style providers.

```ts
interface ProviderUsageCredits
```

**Properties**

- `remaining` (`number`): Credits left.
- `total` (`number | null`): Credits granted in total, or `null` when the provider reports no total.

Source: [src/chat/provider-usage-format.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L31)

### `ProviderUsageResets`

Interface.

Banked rate-limit resets an account holds (Codex): one redeemed empties its windows now.

```ts
interface ProviderUsageResets
```

**Properties**

- `available` (`number`): Resets left to redeem.
- `credits?` (`readonly ProviderResetCredit[]`): Each reset held, soonest to expire first. Absent when the list could not be read (the count still stands).

Source: [src/chat/provider-usage-format.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L39)

### `ProviderUsageSnapshot`

Interface.

Usage of one credential of a provider, as probed at one moment.

```ts
interface ProviderUsageSnapshot
```

**Properties**

- `account` (`string | null`): Account name for OAuth-backed snapshots (`Default`, `work`, …); `null` for
  API-key probes. Surfaces show it only when the provider has more than one
  snapshot, so a single-account provider stays quiet.
- `activeCredential` (`boolean`): True when this credential is the one requests use (the canonical slot).
- `credentialId?` (`string`): Stable id of that credential (`ProviderCredential.id`): unlike
  `credentialKey` it does not move when another account is promoted,
  so a session pinned to an account finds its snapshot by it. Absent for
  an env-only key or an entry written before ids.
- `credentialKey` (`string`): Credentials-file key of the credential this snapshot was probed with. A
  provider holding several OAuth accounts yields one snapshot per account;
  this is what tells them apart (and the stable list key).
- `credits` (`ProviderUsageCredits | null`): Credit balance, or `null` when the provider reports none.
- `error` (`string | null`): Short failure reason when `status` is not `ok`.
- `fetchedAt` (`number`): Epoch milliseconds when the snapshot was taken.
- `label` (`string`): Display label for the provider.
- `note?` (`string`): A short hint shown under the windows (GitHub's "anonymous: run `gh auth login`").
- `plan` (`string | null`): Plan name when the provider reports one.
- `providerKey` (`string`): Registry key (`anthropic`, `openai`, …).
- `resets?` (`ProviderUsageResets`): Banked resets, when the provider reports them (Codex). Redeem one with `redeemProviderReset`.
- `status` (`ProviderUsageStatus`): Outcome of the probe.
- `windows` (`readonly ProviderUsageWindow[]`): Rate-limit windows with their usage.

Source: [src/chat/provider-usage-format.ts:78](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L78)

### `ProviderUsageWindow`

Interface.

One rate-limit window on a subscription (e.g. "5h", "weekly").

```ts
interface ProviderUsageWindow
```

**Properties**

- `id` (`string`): Stable id from the provider, used as a React / list key.
- `label` (`string`): Human label as the provider names it.
- `resetsAt` (`number | null`): Epoch ms when the window resets, or `null` when the provider omits it.
- `usedPercent` (`number`): 0..100, may be fractional.

Source: [src/chat/provider-usage-format.ts:19](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L19)

### `QueryOptions`

Interface.

Options of the query functions.

```ts
interface QueryOptions
```

**Properties**

- `now?` (`number | (() => number)`): The current time (epoch ms), or a clock, for relative bounds. Default `Date.now`.

Source: [src/chat/session-query/compile.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/compile.ts#L13)

### `RankedPaletteItem`

Interface.

A palette item with its match score.

```ts
interface RankedPaletteItem
```

**Properties**

- `item` (`PaletteItem`): The matched item.
- `score` (`number`): Match score. Higher ranks first.
- `titleMatches` (`readonly number[]`): Indices into `item.title` to highlight. Empty when the match came from elsewhere.

Source: [src/chat/palette.ts:100](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L100)

### `RateSample`

Interface.

One `stream:progress` reading of a turn, as [`stepStreamRate`](https://zidane.si/docs/reference/chat-pure.md#stepStreamRate) takes it.

```ts
interface RateSample
```

**Properties**

- `elapsedMs` (`number`): ms since the turn's request; only differences are used.
- `estimated` (`boolean`): Whether `outputTokens` is an estimate rather than a provider-reported count.
- `outputTokens` (`number`): Output tokens counted so far in the turn.
- `turnId` (`string`): Turn the sample belongs to.

Source: [src/chat/stream-rate.ts:18](https://github.com/Tahul/zidane/blob/main/src/chat/stream-rate.ts#L18)

### `RateState`

Interface.

Sliding-window state of the output rate of a streaming turn.

```ts
interface RateState
```

**Properties**

- `estimated` (`boolean | null`): Whether the samples are estimates, or `null` before the first sample.
- `rate` (`number | null`): Smoothed tokens/second, `null` until the window has enough span.
- `samples` (`readonly { n: number; t: number }[]`): Samples inside the window, oldest first; the first is the baseline.
- `turnId` (`string | null`): Turn being measured, or `null` before the first sample.

Source: [src/chat/stream-rate.ts:30](https://github.com/Tahul/zidane/blob/main/src/chat/stream-rate.ts#L30)

### `RecentSessionRow`

Interface.

One session the recent block lists.

```ts
interface RecentSessionRow
```

**Properties**

- `commits?` (`number`): Commits its runs made.
- `cwd?` (`string`): The folder it ran in (shown on the home of no project).
- `id` (`string`): The session id, as the host opens it.
- `running?` (`boolean`): A run is in progress.
- `title` (`string`): Its title.
- `updatedAt` (`number`): Epoch ms of its last update.

Source: [src/chat/home-blocks.ts:252](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L252)

### `RecentSessionsBlockDeps`

Interface.

What the recent sessions block reads from its host.

```ts
interface RecentSessionsBlockDeps
```

**Properties**

- `list` (`(projectRoot: string | undefined, limit: number) => Promise<readonly RecentSessionRow[]>`): The newest sessions, newest first: one project's, or every one (`projectRoot` absent).
- `now?` (`() => number`): The clock. Default: `Date.now()`.
- `projectRootOf` (`(cwd: string) => string`): The project a folder belongs to.
- `subscribe?` (`(emit: () => void) => () => void`): Calls `emit` when the list may have changed. Returns the unsubscribe.

Source: [src/chat/home-blocks.ts:268](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L268)

### `ReconcilableEvent`

Interface.

What reconciling reads off an event: a `StreamEvent`, or a client's wire copy of one.

```ts
interface ReconcilableEvent
```

**Properties**

- `callId?` (`string`): Tool call the event belongs to.
- `childId?` (`string`): Subagent that produced the event.
- `kind` (`string`): Event kind (`tool`, `text`, …).
- `synthetic?` (`boolean`): A display-only prompt marker the user never typed; compared along with `text`.
- `text?` (`unknown`): Row text; a string's length is part of the match key.
- `turnId?` (`string`): Turn the event belongs to.

Source: [src/chat/transcript-reconcile.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/transcript-reconcile.ts#L16)

### `RepoSpec`

Interface.

What a pasted "repository" is: the URL git should clone, the folder name
it lands in, and a short label for the UI. Pure, shared by main (the
clone) and the renderer (the live preview under the field).

Accepted: `owner/repo` (GitHub shorthand), `github.com/owner/repo`,
`https://host/owner/repo(.git)`, a GitHub web URL deep in the tree
(`/tree/<branch>/…`, `/blob/…`, `/pull/…`: the branch is kept when it is
in the URL), `git@host:owner/repo.git`, `ssh://…`, `git://…`, `file://…`.

```ts
interface RepoSpec
```

**Properties**

- `branch?` (`string`): Branch named in a web URL (`/tree/<branch>`), cloned with `--branch`.
- `cloneUrl` (`string`): What `git clone` receives.
- `label` (`string`): `owner/repo` on a known forge, else host + path.
- `name` (`string`): Default folder name: the repo's last path segment without `.git`.
- `treePath?` (`string`): Everything after `/tree/` when it has more than one segment. Branch
  names can contain `/`, so the clone matches it against the remote's
  branches; `branch` (the first segment) is the fallback.

Source: [src/chat/git/repo-url.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/git/repo-url.ts#L12)

### `RunEstimateProblem`

Interface.

A run that could not be estimated for a reason that will not go away by
itself (`LASTING_ESTIMATE_FAILURES`): a window says so, so a setup problem
(a rejected request, a missing key) does not look like nothing happening.

```ts
interface RunEstimateProblem extends RunEstimateRef
```

**Properties**

- `callId?` (`string`, from `RunEstimateRef`): The `spawn` call that started a subagent's run.
- `depth` (`number`, from `RunEstimateRef`): Subagent depth: 0 for the session's own run.
- `label?` (`string`, from `RunEstimateRef`): A subagent's label (`child-3`), as its spawn row names it.
- `problem` (`RunEstimateFailure`): Why: the decision's failure reason and detail (`SessionRun.estimateFailure`).
- `runId` (`string`, from `RunEstimateRef`): The run.
- `startedAt` (`number`, from `RunEstimateRef`): When the run started, epoch ms on the host's clock.

Source: [src/chat/run-estimate.ts:172](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L172)

### `RunEstimateTiming`

Interface.

An estimated run: enough to count down without the run record.

```ts
interface RunEstimateTiming extends RunEstimateRef
```

**Properties**

- `at` (`number`): When the estimate was made, epoch ms.
- `callId?` (`string`, from `RunEstimateRef`): The `spawn` call that started a subagent's run.
- `depth` (`number`, from `RunEstimateRef`): Subagent depth: 0 for the session's own run.
- `highMs` (`number`): Working time past which the run is over its estimate, in ms.
- `label?` (`string`, from `RunEstimateRef`): A subagent's label (`child-3`), as its spawn row names it.
- `runId` (`string`, from `RunEstimateRef`): The run.
- `startedAt` (`number`, from `RunEstimateRef`): When the run started, epoch ms on the host's clock.
- `totalMs` (`number`): Expected working time of the whole run, in ms.
- `waitingSince?` (`number`): Start of the wait going on now, epoch ms.
- `waitMs` (`number`): Finished waits on the user, in ms.

Source: [src/chat/run-estimate.ts:154](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L154)

### `RunReceipt`

Interface.

What a finished run cost and how long it took, as shown on its receipt row.

```ts
interface RunReceipt
```

**Properties**

- `agent?` (`string`): The agent profile the run ran as.
- `agentSwitched?` (`boolean`): The previous run ran as another agent: the user switched before this run.
- `costUsd?` (`number`): Total cost in USD.
- `durationMs?` (`number`): Wall-clock duration in milliseconds.
- `modelId?` (`string`): Model that produced the LAST turn — the one the answer came from.
- `otherModels?` (`number`): Distinct models beyond the last one (a fallback chain that engaged).
- `providerKey?` (`string`): The provider that served that turn, so its name reads as the model picker's.
- `tokensIn?` (`number`): Input tokens, cached tokens included.
- `tokensOut?` (`number`): Output tokens.
- `tokensPerSecond?` (`number`): Output tokens per second of GENERATION — output over (stream duration −
  time to first token), summed across the run's turns. Excludes the wait
  for the first byte and everything outside the provider stream (tool
  execution, approvals), so it measures the model, not the run.
- `turns?` (`number`): Number of turns.

Source: [src/chat/run-receipt.ts:24](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L24)

### `RunReceiptCell`

Interface.

One cell of a formatted receipt line.

```ts
interface RunReceiptCell
```

**Properties**

- `kind` (`RunReceiptCellKind`): What the cell shows.
- `segments?` (`readonly RunReceiptSegment[]`): Optional tinted sub-parts, space-joined; `text` is their plain join. A
  renderer without per-segment color just paints `text`.
- `text` (`string`): Plain rendering — what `formatRunReceiptLine` and width fitting use.

Source: [src/chat/run-receipt.ts:179](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L179)

### `RunReceiptSegment`

Interface.

One part of a `tokens` cell, so renderers can color input and output differently.

```ts
interface RunReceiptSegment
```

**Properties**

- `kind` (`RunReceiptSegmentKind`): Whether the segment is input or output tokens.
- `text` (`string`): Segment text.

Source: [src/chat/run-receipt.ts:171](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L171)

### `RunRetry`

Interface.

A provider retry in flight: the attempt, out of how many, and whose stream (`parent` or absent for the session's own, else a subagent id).

```ts
interface RunRetry
```

**Properties**

- `attempt` (`number`): The attempt in flight, counting from 1.
- `max` (`number`): How many attempts the run allows.
- `source?` (`string`): Whose stream is retried: `parent` (or absent) for the session's own, else a subagent id.

Source: [src/chat/run-activity.ts:68](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L68)

### `RunStatusCell`

Interface.

One value of the live run readout, so a renderer can tint and badge it by meaning.

```ts
interface RunStatusCell
```

**Properties**

- `kind` (`'tokens' | 'elapsed' | 'rate'`): What the cell shows: the run's elapsed time, its output tokens, or the stream rate.
- `text` (`string`): Display text: `1m 15s`, `↓1.2k` (`↓~1.2k` while estimated), `41 tok/s`.

Source: [src/chat/footer-chips.ts:125](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L125)

### `RunStop`

Interface.

How a run ended early and how to pick it back up.

```ts
interface RunStop
```

**Properties**

- `cause` (`'error' | 'aborted'`): `aborted` when the user stopped the run, `error` when it failed.
- `prompt?` (`string`): The prompt to resend, set only with `resume: 'retry'`.
- `resume` (`'retry' | 'continue'`): `continue` when the run had done work, `retry` (resend `prompt`) when not.

Source: [src/chat/run-stops.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/run-stops.ts#L16)

### `RunStopAdapter`

Interface.

How one surface copies and marks its items.

```ts
interface RunStopAdapter<T extends RunStopItem>
```

**Type parameters**

- `T` (`extends RunStopItem`)

**Properties**

- `isMarked` (`(item: T) => boolean`): The item already speaks for a stop (an earlier pass's output fed back in).
- `mark` (`(error: T, text: string, stop: RunStop) => T`): The run's own error, now speaking for the stop with `text`.
- `mint` (`(reply: T, text: string, stop: RunStop) => T`): The stop line a marker becomes when no run error closes the exchange.
- `withText` (`(reply: T, text: string) => T`): The reply with its marker split off.

Source: [src/chat/run-stops.ts:46](https://github.com/Tahul/zidane/blob/main/src/chat/run-stops.ts#L46)

### `RunStopItem`

Interface.

What the classifier reads off an item: stream events and the GUI's rows both carry it.

```ts
interface RunStopItem
```

**Properties**

- `callId?` (`string`): The call an error belongs to: not the run's own error.
- `childId?` (`string`): The worker session that produced it; absent on the main session.
- `depth?` (`number`): Worker nesting depth; `0` or absent on the main session.
- `kind` (`string`): The item's kind (`markdown`, `error`, `user-prompt`, `tool`, …).
- `notice?` (`{ label?: string }`): Set when the item is a notice; `label` names its source (`run`, `repeat guard`, …).
- `streaming?` (`boolean`): A reply still streaming: its marker, if any, is not final yet.
- `text?` (`string`): Its text: a reply's markdown, an error's message, a prompt.
- `tool?` (`string`): The tool an error belongs to: not the run's own error.

Source: [src/chat/run-stops.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/run-stops.ts#L26)

### `ScheduleIssue`

Interface.

One problem in a schedule input.

```ts
interface ScheduleIssue
```

**Properties**

- `message` (`string`): What is wrong with it.
- `path` (`string`): The field, as a dotted path (`trigger.expr`).

Source: [src/schedules/validate.ts:13](https://github.com/Tahul/zidane/blob/main/src/schedules/validate.ts#L13)

### `ScriptLineProgress`

Interface.

A script line that made calls.

```ts
interface ScriptLineProgress
```

**Properties**

- `calls` (`number`): Calls made from this line so far, its `sleep`s included.
- `line` (`number`): 1-based line in the script as the model wrote it.
- `status` (`ScriptCallStatus`): State of the latest call made from this line.
- `until?` (`number`): While it waits (`waiting`): when the wait ends, epoch milliseconds.

Source: [src/chat/script-progress.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L26)

### `ScriptLoop`

Interface.

A loop of a script, by its lines.

```ts
interface ScriptLoop
```

**Properties**

- `end` (`number`): 1-based line its body ends on.
- `kind` (`ScriptLoopKind`): A `for` / `while` / `do`, or an array method's callback.
- `start` (`number`): 1-based line its keyword (`for`, `while`, `do`) or its callback starts on.

Source: [src/chat/script-progress.ts:802](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L802)

### `ScriptOptions`

Interface.

What a script's `// @options` line sets.

```ts
interface ScriptOptions
```

**Properties**

- `maxOutputTokens?` (`number`): `max_output_tokens`: the budget for what the script returns.
- `other` (`{ key: string; value: string }[]`): Fields the view does not know, as written.
- `raw?` (`string`): The JSON as written, when it does not read as an object.
- `timeoutMs?` (`number`): `timeout_ms`: the script's deadline, tool calls included.

Source: [src/chat/script-progress.ts:308](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L308)

### `ScriptProgress`

Interface.

A script's progress as a `tool-progress` event carries it.

```ts
interface ScriptProgress
```

**Properties**

- `at?` (`number`): The line of the latest call or wait to start: where the script is (in a loop, which round's lines are behind it).
- `done` (`number`): Calls that ended, failed ones included.
- `ended?` (`'error' | 'ok'`): How the script ended, once it did: its last line shows done when it ended without error.
- `failed` (`number`): Calls that failed.
- `lines` (`ScriptLineProgress[]`): Lines that made calls, by line.
- `output` (`OutputLine[]`): The last lines of output, oldest first. A command's line still being written comes last.
- `running` (`number`): Calls still running.

Source: [src/chat/script-progress.ts:41](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L41)

### `ScriptProgressTracker`

Interface.

Builds a script's [`ScriptProgress`](https://zidane.si/docs/reference/chat-pure.md#ScriptProgress) from its calls and output, in the order they happen.

```ts
interface ScriptProgressTracker
```

**Properties**

- `end` (`(ok: boolean) => void`): The script itself ended.
- `finish` (`(callId: string, ok: boolean) => void`): A call ended.
- `output` (`(stream: 'output' | 'console' | 'stdout' | 'stderr', text: string, line?: number) => void`): The script printed, or a command wrote, `text`.
- `snapshot` (`() => ScriptProgress`): The state now.
- `start` (`(callId: string, line: number | undefined) => void`): A call started. Calls without a line are ignored.
- `wait` (`(line: number, ms: number) => void`): A `sleep` on `line` started (`ms` > 0) or ended (0). It counts on its line, not among the calls.

Source: [src/chat/script-progress.ts:64](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L64)

### `ScriptProgressView`

Interface.

What the GUI and the TUI draw for a script.

```ts
interface ScriptProgressView
```

**Properties**

- `active?` (`number`): The line to keep in view: the first running one, else where the script is.
- `done` (`number`): Calls that ended, failed ones included.
- `error?` (`{ line: number; message: string }`): The error the script itself threw, at the line it names (its result's excerpt).
- `failed` (`number`): Calls that failed.
- `lines` (`ScriptViewLine[]`): The script's lines, the `// @options` line and blank edges left out.
- `loops` (`ScriptViewLoop[]`): The script's loops with their rounds, outer ones first; empty without progress.
- `options?` (`ScriptOptions`): The `// @options` line's settings, read (left out of `lines`).
- `output` (`OutputLine[]`): The last lines the script printed or its shell calls wrote, oldest first.
- `percent?` (`number`): 0 to 100, only with `total`.
- `running` (`number`): Calls still running.
- `total?` (`number`): Calls the script makes in all, when each can run once at most.
- `tracked` (`boolean`): Whether live progress exists for this script (the lines carry states).

Source: [src/chat/script-progress.ts:280](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L280)

### `ScriptViewLine`

Interface.

One line of a script as the view draws it.

```ts
interface ScriptViewLine
```

**Properties**

- `calls` (`number`): Calls this line made, its `sleep`s included.
- `label` (`number`): The number to show: counted from the first line of code, the `// @options` line left out.
- `number` (`number`): 1-based line in the script as the model wrote it: the line the progress and errors name.
- `state` (`ScriptLineState`): How it draws: see [`ScriptLineState`](https://zidane.si/docs/reference/chat-pure.md#ScriptLineState).
- `text` (`string`): The line's source, without its newline.
- `until?` (`number`): While it waits: when the wait ends, epoch milliseconds.

Source: [src/chat/script-progress.ts:254](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L254)

### `ScriptViewLoop`

Interface.

A loop of the script as the view draws it.

```ts
interface ScriptViewLoop extends ScriptLoop
```

**Properties**

- `active` (`boolean`): The script is inside it now.
- `depth` (`number`): How many loops it sits in (0: none), for its bracket's place.
- `end` (`number`, from `ScriptLoop`): 1-based line its body ends on.
- `kind` (`ScriptLoopKind`, from `ScriptLoop`): A `for` / `while` / `do`, or an array method's callback.
- `rounds` (`number`): Rounds it went through so far (the most rounds a line of its own ran), 0 when none of its lines made a call.
- `start` (`number`, from `ScriptLoop`): 1-based line its keyword (`for`, `while`, `do`) or its callback starts on.

Source: [src/chat/script-progress.ts:270](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L270)

### `SearchExcerpt`

Interface.

A clipped line of a turn around a match.

```ts
interface SearchExcerpt
```

**Properties**

- `highlighted` (`HighlightRange[]`): Match ranges, relative to `text`.
- `text` (`string`): The clipped line text.

Source: [src/chat/history-search.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L21)

### `SearchSessionResult`

Interface.

A matching turn flattened for a session search list, as returned by [`searchSessionTurns`](https://zidane.si/docs/reference/chat-pure.md#searchSessionTurns).

```ts
interface SearchSessionResult
```

**Properties**

- `excerpts` (`SearchExcerpt[]`): Clipped lines around the matches.
- `highlighted` (`HighlightRange[]`): Match ranges, relative to `text`.
- `id` (`string`): Id of the matching turn.
- `matchKind` (`'exact-phrase' | 'exact-terms' | 'fuzzy'`): How the query matched: the whole phrase, every term, or approximately.
- `score` (`number`): Rank of the match. Higher is better.
- `text` (`string`): Searchable text of the turn.
- `turn` (`SessionTurn`): The matching turn.

Source: [src/chat/history-search.ts:52](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L52)

### `ServerUpdateStatus`

Interface.

Where a server's self-update stands, as `server.update.*` reports it.

```ts
interface ServerUpdateStatus
```

**Properties**

- `current` (`string`): The version running now.
- `enabled` (`boolean`): The setting, as the window or the config set it.
- `error?` (`string`): What went wrong, in the `error` state.
- `lastCheckAt?` (`number`): When it last checked for a release, in epoch milliseconds.
- `latest?` (`string`): The newest release seen.
- `reason?` (`string`): Why not, when it can't.
- `rolledBackFrom?` (`string`): The release the last update rolled back from; it is skipped until a newer one is published.
- `state` (`UpdateState`): What the updater is doing.
- `supported` (`boolean`): This install can update itself (a release binary in a writable folder).
- `updatedFrom?` (`string`): The last update: from which version, or the version rolled back from.
- `waitingFor?` (`('work' | 'terminals')[]`): In the `waiting` state: what the install waits for. `work`: runs,
  commands and background tasks; `terminals`: open terminals with a
  command running. `Install now` stops waiting for both.
- `waitingSince?` (`number`): In the `waiting` state: since when, in epoch milliseconds.

Source: [src/chat/server-update.ts:10](https://github.com/Tahul/zidane/blob/main/src/chat/server-update.ts#L10)

### `SessionCondition`

Interface.

One test on one field. Every operator given must hold. An array value
(a facet holding a list) matches `eq` / `in` / `contains` when one of
its elements does. A missing value equals `null`; a missing boolean field
reads `false`.

```ts
interface SessionCondition
```

**Properties**

- `contains?` (`string`): Contains this text, ignoring case.
- `eq?` (`QueryValue`): Equals this value (strings compare exactly).
- `exists?` (`boolean`): `true`: has a value (not missing, not `null`). `false`: has none. Boolean fields always have one.
- `field` (`SessionFieldPath`): The field or facet tested.
- `gt?` (`QueryBound`): Greater than this number or time. Rows without a number never match.
- `gte?` (`QueryBound`): Greater than or equal to this number or time.
- `in?` (`readonly QueryValue[]`): Equals one of these values. An empty list matches no row.
- `lt?` (`QueryBound`): Less than this number or time.
- `lte?` (`QueryBound`): Less than or equal to this number or time.
- `ne?` (`QueryValue`): Does not equal this value. A missing value matches unless the value is `null`.
- `nin?` (`readonly QueryValue[]`): Equals none of these values. An empty list matches every row.

Source: [src/chat/session-query/types.ts:66](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L66)

### `SessionEvent`

Interface.

A report from a worker session to the orchestrating main session.

```ts
interface SessionEvent
```

**Properties**

- `artifacts?` (`RunArtifacts`): What the run touched — the receipts a decision needs.
- `at` (`number`): Wall-clock at the event.
- `costUsd?` (`number`): Run cost in USD when the provider reported one. Omitted, never `0`.
- `cwd?` (`string`): Worker cwd — lets the main reason about which project reported.
- `detail?` (`string`): For `needs-attention`: WHAT is being asked — the approval's tool, the
  plan's title, the question's prompt. The main can often answer from this
  alone instead of reading the worker's transcript.
- `durationMs?` (`number`): Wall-clock of the run that produced this event, when it has ended.
- `error?` (`string`): For `error`: the failure text, separate from `summary` so the UI can style it.
- `finishReason?` (`'length' | 'content-filter' | 'pause'`): Abnormal terminal state beyond `status`: the run ended because the model
  hit a ceiling (`length`), spun on empty pauses (`pause`), or was refused
  (`content-filter`). Omitted for a normal `stop`.
- `goal?` (`string`): The prompt that started the run — "what was asked". Paired with
  `summary` ("what it said") this is what turns telemetry into a decision:
  a 692-token essay is fine if that was the goal, and noise if it wasn't.
- `link?` (`string`): Deep link that opens the worker in the desktop app (`sessionLink`), for the receiver to paste.
- `request?` (`SessionEventRequest`): For `needs-attention`: the pending request itself, so the receiver can
  answer it (the `interactions` tool's `answer`) without another call.
- `seq?` (`number`): Monotonic per-main sequence. Lets a consumer dedup or detect a gap when
  the same event can arrive twice (live signal, then replay) or a window
  reattaches.
- `sessionId` (`string`): The worker the event is about. Click target in both clients.
- `status` (`SessionEventStatus`): What happened in the worker.
- `summary` (`string`): One-line human summary; also what the model reads.
- `summaryTruncated?` (`boolean`): `summary` is the last message cut at `SESSION_SUMMARY_MAX` characters; `sessions read` with `full: true` has all of it.
- `title` (`string`): Worker title at event time — titles change, the event should not.
- `tokens?` (`number`): Input + output tokens across the run's assistant turns. Omitted, never `0`.
- `turns?` (`number`): Turns the run produced. Omitted, never `0`.
- `worker?` (`boolean`): Created by the session receiving the event (vs. a session started elsewhere).

Source: [src/chat/orchestration.ts:67](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L67)

### `SessionEventStatusStyle`

Interface.

Glyph, tone and verb used to render one [`SessionEventStatus`](https://zidane.si/docs/reference/chat-pure.md#SessionEventStatus).

```ts
interface SessionEventStatusStyle
```

**Properties**

- `glyph` (`string`): Glyph for the icon column.
- `tone` (`SessionEventTone`): Theme tone for the row.
- `verb` (`string`): Verb phrase after the title: "finished", "needs your input", …

Source: [src/chat/orchestration.ts:627](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L627)

### `SessionGroup`

Interface.

One group of [`groupRows`](https://zidane.si/docs/reference/chat-pure.md#groupRows).

```ts
interface SessionGroup<R>
```

**Type parameters**

- `R`

**Properties**

- `key` (`string | null`): The group's value as a string (`'true'`, `'42'`, `'idle'`), or `null` for rows without a value.
- `label` (`string`): What to show for it.
- `rows` (`R[]`): Its rows, in input order.

Source: [src/chat/session-query/types.ts:206](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L206)

### `SessionGroupBy`

Interface.

Groups rows by the value of a field or facet. Each distinct value is one
group; a row whose value is a list is in one group per element. Rows
without a value go to a last group with key `null`.

```ts
interface SessionGroupBy
```

**Properties**

- `field` (`SessionFieldPath`): The field or facet grouped on.
- `labels?` (`Readonly<Record<string, string>>`): Labels by group key. Win over the labels the caller supplies. Default label: the key.
- `order?` (`SessionGroupOrder`): Default `'asc'`. The group without a value is always last.

Source: [src/chat/session-query/types.ts:132](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L132)

### `SessionHistoryMatch`

Interface.

Aggregated row-level match used by the conversations list.

```ts
interface SessionHistoryMatch
```

**Properties**

- `excerpts` (`SessionSearchExcerpt[]`): Excerpts from the best matches, capped by the caller.
- `matchedTurnIds` (`string[]`): Ids of every matching turn, best first.
- `score` (`number`): Score of the best matching turn.

Source: [src/chat/history-search.ts:78](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L78)

### `SessionKeyParts`

Interface.

The pair a session key names.

```ts
interface SessionKeyParts
```

**Properties**

- `hostKey` (`string`): Always explicit: [`LOCAL_HOST_KEY`](https://zidane.si/docs/reference/chat-pure.md#LOCAL_HOST_KEY) for This computer.
- `sessionId` (`string`): Session id on that host.

Source: [src/chat/hosts/session-key.ts:30](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/session-key.ts#L30)

### `SessionKnobs`

Interface.

The effort and options a new session starts with, as configured.

```ts
interface SessionKnobs
```

**Properties**

- `effort?` (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive'`): Reasoning effort; absent = the last used with the session's model.
- `modelOptions?` (`Record<string, boolean>`): Model options (`fast`…), on or off, applied where the model offers them; absent = the last used with the model.

Source: [src/chat/spaces.ts:375](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L375)

### `SessionPage`

Interface.

One page of [`paginate`](https://zidane.si/docs/reference/chat-pure.md#paginate).

```ts
interface SessionPage<R>
```

**Type parameters**

- `R`

**Properties**

- `cursor?` (`string`): Pass it back for the next page. Absent on the last page.
- `rows` (`R[]`): The page's rows.

Source: [src/chat/session-query/types.ts:216](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L216)

### `SessionQueryAll`

Interface.

Every sub-query holds. An empty list matches every row.

```ts
interface SessionQueryAll
```

**Properties**

- `all` (`readonly SessionQuery[]`): The sub-queries.

Source: [src/chat/session-query/types.ts:92](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L92)

### `SessionQueryAny`

Interface.

At least one sub-query holds. An empty list matches no row.

```ts
interface SessionQueryAny
```

**Properties**

- `any` (`readonly SessionQuery[]`): The sub-queries.

Source: [src/chat/session-query/types.ts:98](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L98)

### `SessionQueryEnvironment`

Interface.

The environment part of a row.

```ts
interface SessionQueryEnvironment
```

**Properties**

- `branch?` (`string`, readonly): Git branch the environment works on.
- `kind?` (`string`, readonly): Environment kind, such as `worktree@laptop`.
- `state?` (`string`, readonly): Provisioning state.

Source: [src/chat/session-query/types.ts:142](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L142)

### `SessionQueryInput`

Interface.

What [`querySessions`](https://zidane.si/docs/reference/chat-pure.md#querySessions) takes.

```ts
interface SessionQueryInput
```

**Properties**

- `cursor?` (`string`): The previous page's cursor.
- `limit?` (`number`): Rows per page. Absent: every row (up to [`MAX_PAGE_SIZE`](https://zidane.si/docs/reference/chat-pure.md#MAX_PAGE_SIZE) when a cursor is given).
- `scope?` (`unknown`): Anything else that chose `rows` (such as `archived`), as JSON: a cursor only resumes under the same scope.
- `sort?` (`readonly SessionSort[]`): Sort keys, most significant first. Absent: input order (by id once paged).
- `where?` (`SessionQuery`): Rows must match it. Absent: every row.

Source: [src/chat/session-query/query.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/query.ts#L12)

### `SessionQueryIssue`

Interface.

One problem `validateQuery` and its siblings found.

```ts
interface SessionQueryIssue
```

**Properties**

- `message` (`string`): What is wrong.
- `path` (`string`): Where, as a path into the value (`where.all[1].gte`).

Source: [src/chat/session-query/types.ts:224](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L224)

### `SessionQueryNot`

Interface.

The sub-query does not hold.

```ts
interface SessionQueryNot
```

**Properties**

- `not` (`SessionQuery`): The sub-query.

Source: [src/chat/session-query/types.ts:104](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L104)

### `SessionQueryRow`

Interface.

A session row the query reads. The protocol's `SessionRow` and the
extension API's `SessionListRow` both fit. Facet values sit under
`facets`, keyed `<extensionId>.<key>`.

```ts
interface SessionQueryRow
```

**Properties**

- `account?` (`string`, readonly): Pinned provider account.
- `agentId?` (`string`, readonly): Agent profile id.
- `archived?` (`boolean`, readonly): Archived.
- `createdAt?` (`number`, readonly): Creation time, epoch ms.
- `cwd?` (`string`, readonly): Working directory.
- `effort?` (`string`, readonly): Thinking effort.
- `environment?` (`SessionQueryEnvironment | null`, readonly): Environment summary; absent for a local session.
- `facets?` (`Readonly<Record<string, unknown>>`, readonly): Facet values, keyed `<extensionId>.<key>`.
- `favorite?` (`boolean`, readonly): Marked favorite.
- `hostId?` (`string`, readonly): Host serving the row.
- `id` (`string`, readonly): Session id.
- `isMain?` (`boolean`, readonly): The orchestration main session.
- `modelId?` (`string`, readonly): Model id.
- `projectRoot?` (`string | null`, readonly): Project root, or `null` for none.
- `providerKey?` (`string`, readonly): Provider key.
- `repoKey?` (`string`, readonly): Repository key (`github.com/owner/repo`).
- `runStartedAt?` (`number`, readonly): When the run in progress began, epoch ms.
- `scheduleId?` (`string`, readonly): The schedule that created the session (a reminder's "new session" fire).
- `spaceId?` (`string`, readonly): Space id, when not the default.
- `status?` (`string`, readonly): Run state.
- `title?` (`string`, readonly): Title.
- `updatedAt?` (`number`, readonly): Last change, epoch ms.
- `wakes?` (`readonly string[]`, readonly): The orchestrator sessions its current run wakes when it ends.

Source: [src/chat/session-query/types.ts:156](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L156)

### `SessionSearchExcerpt`

Interface.

An excerpt tagged with the turn it came from.

```ts
interface SessionSearchExcerpt extends SearchExcerpt
```

**Properties**

- `highlighted` (`HighlightRange[]`, from `SearchExcerpt`): Match ranges, relative to `text`.
- `role` (`'system' | 'user' | 'assistant' | 'command'`): Role of that turn.
- `text` (`string`, from `SearchExcerpt`): The clipped line text.
- `turnId` (`string`): Id of the turn the excerpt came from.

Source: [src/chat/history-search.ts:70](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L70)

### `SessionSearchIndex`

Interface.

Prebuilt index over a session's turns. Build one with [`buildSessionSearchIndex`](https://zidane.si/docs/reference/chat-pure.md#buildSessionSearchIndex) and reuse it across queries.

```ts
interface SessionSearchIndex
```

**Properties**

- `turns` (`IndexedSearchTurn[]`): Turns that have searchable text, in session order.

Source: [src/chat/history-search.ts:100](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L100)

### `SessionSort`

Interface.

One sort key. Rows without a value sort last in both directions. Only text,
numbers and booleans sort: a facet holding a list or an object sorts as
missing, and text sorts on its first 256 characters.

```ts
interface SessionSort
```

**Properties**

- `dir?` (`'asc' | 'desc'`): Default `'asc'`.
- `field` (`SessionFieldPath`): The field or facet sorted on.

Source: [src/chat/session-query/types.ts:117](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L117)

### `SessionView`

Interface.

The filters of a sidebar view. Each one left out keeps every session.

```ts
interface SessionView
```

**Properties**

- `agent?` (`string | null`): Only sessions on this agent profile.
- `archive?` (`'active' | 'all' | 'archived'`): `active`: leave archived sessions out; `archived`: only those; `all`: both.
- `filters?` (`readonly SessionQuery[]`): The queries of the extension filters the user turned on, each one holding.
- `project?` (`string | null`): Only sessions of this project, by folder name (`projectName`, exact).
- `updatedSince?` (`QueryBound`): Only sessions updated at or after this bound (`'-7d'`, epoch ms).

Source: [src/chat/session-query/view.ts:22](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/view.ts#L22)

### `SessionViewSpace`

Interface.

The space a view is on.

```ts
interface SessionViewSpace
```

**Properties**

- `id` (`string`): Space id: `default`, a user space's id, or `<extension>/<id>`.
- `query?` (`SessionQuery`): The space's own query, when it has one: the sessions it lists besides those tagged with it.

Source: [src/chat/session-query/view.ts:14](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/view.ts#L14)

### `SettingsChoice`

Interface.

String-valued settings that pick between a known set of options. The
`SettingsModal` renders these as one row showing the active label, where
`enter` cycles to the next option (wrapping back to the first). Same
shape any GUI settings panel can consume — render the options array as a
dropdown or segmented control.

Keep `options` in stable display order; cycling depends on it.

```ts
interface SettingsChoice<K extends keyof Settings = keyof Settings>
```

**Type parameters**

- `K` (`extends keyof Settings`, default `keyof Settings`)

**Properties**

- `category` (`SettingsCategory`): Tab the row belongs to.
- `description` (`string`): One-line explanation of the setting.
- `key` (`K`): Setting the row writes.
- `label` (`string`): Row label.
- `options` (`readonly { label: string; value: Settings[K] }[]`): Selectable values with their labels, in cycling order.

Source: [src/chat/settings-catalog.ts:374](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L374)

### `SettingsToggle`

Interface.

Static description of every togglable setting, in display order. The TUI's
`SettingsModal` and the GUI settings panel build their row list
from this so labels/descriptions stay in one place.

```ts
interface SettingsToggle
```

**Properties**

- `category` (`SettingsCategory`): Tab the row belongs to.
- `description` (`string`): One-line explanation of the setting.
- `desktopOnly?` (`true`): The setting drives something only the desktop app shows (its browser,
  its terminals). The TUI still lets you change it, and says so.
- `key` (`BooleanSettingKey`): Setting the row flips.
- `killSwitchEnv?` (`string`): Env var of the feature gate's kill switch (`FEATURE_GATES`). While it is
  `'1'` the feature is off whatever the setting says, so renderers grey the
  row out and name the variable.
- `label` (`string`): Row label.
- `requires?` (`BooleanSettingKey`): Another boolean setting this one is meaningless without. Renderers grey
  the row out and say so while the requirement is off; the write layer
  (`enforceSettingsInvariants`) guarantees the value can never be `true`
  while the requirement is `false`, whichever client or file wrote it.

Source: [src/chat/settings-catalog.ts:99](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L99)

### `SetupPaletteItem`

Interface.

The command palette's entry for the wizard.

```ts
interface SetupPaletteItem
```

**Properties**

- `description` (`string`): Text beside the title.
- `id` (`string`): Palette item id, the same in both apps.
- `keywords` (`readonly string[]`): Extra search terms.
- `title` (`string`): Row title.

Source: [src/chat/onboarding/steps.ts:86](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/steps.ts#L86)

### `ShellBlockPlan`

Interface.

What runs for a block.

```ts
interface ShellBlockPlan
```

**Properties**

- `oneLine` (`boolean`): One command line: run as it is, no temporary script.
- `script` (`string`): The script: the block, or its `$ ` lines without the prompt.
- `shell` (`BlockShell`): The shell it runs in: the fence's (`zsh`, `sh`), else `bash`.

Source: [src/chat/shell-blocks.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L23)

### `Space`

Interface.

A named group of sessions with optional defaults for new ones.

```ts
interface Space
```

**Properties**

- `account?` (`string`): The stored account of `providerKey` the default runs on (credential id); absent = its active account.
- `agentId?` (`string`): Agent new sessions in this space start on (`AgentProfile.id`); absent = the global default (`Settings.defaultAgent`).
- `effort?` (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive'`): Effort new sessions in this space start with, whatever their model; absent = Settings' (`defaultEffort`).
- `extensionId?` (`string`): The extension contributing the space (id `<extension>/<id>`). In the
  stored list, an entry with an extension space's id only places it in
  the switcher and may hide it; its base comes from the extension.
- `fallbacks?` (`{ modelId: string; providerKey: string }[]`): Fallback chain seeded with the default model (`provider`/`model` pairs).
- `groupBy?` (`SessionGroupBy`): How the space groups its sessions until the user picks a grouping.
- `hidden?` (`boolean`): Left out of the switcher; its sessions stay in it.
- `icon?` (`SpaceIcon`): Icon shown in the switcher.
- `id` (`string`): Stable id. [`DEFAULT_SPACE_ID`](https://zidane.si/docs/reference/chat-pure.md#DEFAULT_SPACE_ID) for the Default space.
- `modelId?` (`string`): Default model id for new sessions. Used together with `providerKey`.
- `modelOptions?` (`Record<string, boolean>`): Model options (`fast`…) new sessions in this space start with, where their model offers them; absent = Settings' (`defaultModelOptions`).
- `name` (`string`): Display name.
- `providerKey?` (`string`): Default provider for new sessions in this space; set together with `modelId`.
- `query?` (`SessionQuery`): A query space (an extension's, or a view the user saved): the sessions
  it lists besides those stamped with its id. Absent: only those.
- `readonly?` (`boolean`): Its name, query and defaults are the extension's: the user can't edit them (extension spaces).
- `sortBy?` (`SessionSort[]`): How the space sorts its sessions until the user picks a sort.

Source: [src/chat/spaces.ts:29](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L29)

### `SpaceModelDefault`

Interface.

The model a new session in a space starts on.

```ts
interface SpaceModelDefault
```

**Properties**

- `account?` (`string`): Stored account of the provider to run on. Absent means its active account.
- `effort?` (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive'`): Effort a new session on this model starts with; absent = the last used for the model.
- `fallbacks?` (`{ modelId: string; providerKey: string }[]`): Fallback targets after the primary.
- `modelId` (`string`): Model id.
- `modelOptions?` (`Record<string, boolean>`): Model options (`fast`…) it starts with; absent = the last used for the model.
- `providerKey` (`string`): Provider key.

Source: [src/chat/spaces.ts:327](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L327)

### `SpacesSettings`

Interface.

The parts of the settings the helpers read.

```ts
interface SpacesSettings
```

**Properties**

- `defaultAgent?` (`string`): Global default agent profile id.
- `defaultEffort?` (`string`): Global default reasoning effort.
- `defaultModel?` (`string`): Global default model, as `provider/model`.
- `defaultModelOptions?` (`unknown`): Global default model options.
- `extensionSpaces?` (`readonly Space[]`): The spaces extensions contribute ([`extensionSpace`](https://zidane.si/docs/reference/chat-pure.md#extensionSpace)). Not a
  setting: hosts and windows pass them in, so a session created in one
  starts on its defaults and is stamped with its id.
- `spaceList?` (`unknown`): Stored list of spaces, validated by [`normalizeSpaces`](https://zidane.si/docs/reference/chat-pure.md#normalizeSpaces).
- `spaces?` (`boolean`): Whether the Spaces feature is on.

Source: [src/chat/spaces.ts:232](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L232)

### `SpawnEndSummary`

Interface.

A worker's end, ready to render: the sentence head, and the facts to show as badges.

```ts
interface SpawnEndSummary
```

**Properties**

- `failed` (`boolean`): The worker errored.
- `head` (`string`): `Finished in 42s`, `Failed after 1m 5s`, `Stopped after 9s`.
- `meta` (`string[]`): What it cost and used, one badge each: `$0.01`, `↑3.10k ↓400`.

Source: [src/chat/format.ts:76](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L76)

### `SpawnTreeRow`

Interface.

What the helpers read off a transcript row / event.
The slice of a transcript row needed to build the spawn tree.

```ts
interface SpawnTreeRow
```

**Properties**

- `childId?` (`string`): Subagent the row belongs to.
- `kind` (`string`): Row kind. Only `spawn-start` and `spawn-end` rows contribute parents.
- `spawn?` (`{ parentChildId?: string }`): Spawn details. `parentChildId` names the spawning subagent.

Source: [src/chat/spawn-tree.ts:15](https://github.com/Tahul/zidane/blob/main/src/chat/spawn-tree.ts#L15)

### `StoredSessionFacets`

Interface.

A session's facets as its metadata holds them.

```ts
interface StoredSessionFacets
```

**Properties**

- `computed` (`string[]`): Facet ids that answered at least once.
- `values` (`Record<string, JsonValue>`): Values by `<extensionId>.<key>`.

Source: [src/session/facets.ts:31](https://github.com/Tahul/zidane/blob/main/src/session/facets.ts#L31)

### `StreamFailure`

Interface.

A stop marker split off an assistant reply by [`splitStreamFailure`](https://zidane.si/docs/reference/chat-pure.md#splitStreamFailure).

```ts
interface StreamFailure
```

**Properties**

- `aborted` (`boolean`): The user stopped the run; not a failure of the provider.
- `message` (`string`): The provider message, `''` when there is none (always for an abort).
- `midOutput` (`boolean`): Text had streamed before the stream ended.

Source: [src/chat/stream-failure.ts:11](https://github.com/Tahul/zidane/blob/main/src/chat/stream-failure.ts#L11)

### `SyncClaimResult`

Interface.

`sync.claim`: claimed, or another device is the source (`status.source`).

```ts
interface SyncClaimResult
```

**Properties**

- `claimed` (`boolean`): `true` when this device is now the source.
- `status` (`SyncStatus`): The server's sync status after the claim attempt.

Source: [src/chat/sync/types.ts:183](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L183)

### `SyncPushResult`

Interface.

`sync.push`: what happened to each field of the snapshot.

```ts
interface SyncPushResult
```

**Properties**

- `applied` (`string[]`): Fields written on the server.
- `skipped` (`{ field: string; reason: string }[]`): Fields left alone, each with the reason.
- `unchanged` (`string[]`): Fields that already matched the snapshot.
- `warnings` (`{ field: string; message: string }[]`): Fields applied with a caveat, each with the message.

Source: [src/chat/sync/types.ts:171](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L171)

### `SyncSource`

Interface.

The device a server takes its sync from.

```ts
interface SyncSource
```

**Properties**

- `claimedAt` (`number`): Time the device claimed the server in epoch ms.
- `deviceId` (`string`): Stable id of the source device.
- `deviceName` (`string`): Display name of the source device.
- `tokenId?` (`string`): The token that claimed it (a zidane-server's token id).

Source: [src/chat/sync/types.ts:143](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L143)

### `SyncStatus`

Interface.

`sync.status`: the server's record, no values.

```ts
interface SyncStatus
```

**Properties**

- `categories` (`SyncCategory[]`): Categories the source sends.
- `fields` (`Record<string, { category: SyncCategory; syncedAt: number }>`): Fields the source set: field → when.
- `keys` (`string[]`): Providers whose API key the source opted in.
- `lastPushAt?` (`number`): Time of the last push in epoch ms.
- `overrides` (`Record<string, { at: number }>`): Fields edited on the server since: sync leaves them alone until `sync.reset`.
- `source` (`SyncSource | null`): The device the server syncs from, or `null` when unclaimed.

Source: [src/chat/sync/types.ts:155](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L155)

### `TerminalAdoptResult`

Interface.

What `terminal.adopt` moved into the session (ids), and what it could not.

```ts
interface TerminalAdoptResult
```

**Properties**

- `adopted` (`string[]`): Ids of the terminals moved into the session.
- `skipped` (`string[]`): Over the per-scope cap: left in the project.

Source: [src/chat/terminal/protocol.ts:145](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L145)

### `TerminalAttachResult`

Interface.

What a client needs to start showing a terminal: its history, and where live output resumes.

```ts
interface TerminalAttachResult
```

**Properties**

- `data` (`string`): Output history to show first.
- `offset` (`number`): Character offset where live output resumes.
- `terminal` (`TerminalInfo`): The terminal that was attached.

Source: [src/chat/terminal/protocol.ts:153](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L153)

### `TerminalInfo`

Interface.

Description of one terminal, as the host reports it to clients.

```ts
interface TerminalInfo
```

**Properties**

- `cols` (`number`): Width in character cells.
- `createdAt` (`number`): Creation time in epoch ms.
- `cwd` (`string`): Working directory the terminal started in.
- `environment` (`string`): Environment kind it runs in (`local`, `worktree`, `docker`, `e2b`, …).
- `error?` (`string`): Failure message, when `status` is `error`.
- `exitCode?` (`number`): Exit code, once the process has exited.
- `hiddenFromAgent` (`boolean`): The agent's terminal tools skip it.
- `id` (`string`): Terminal id.
- `label` (`string`): Stable name ("Terminal 2", or the agent's command).
- `lastActivityAt` (`number`): Time of the last output or input in epoch ms.
- `owner` (`TerminalOwner`): Who started the terminal.
- `program?` (`string`): The program in the foreground, for terminals on this machine.
- `rows` (`number`): Height in character cells.
- `scope?` (`TerminalProjectScope`): Set on project / draft terminals (`sessionId` is `''`).
- `sessionId` (`string`): The session it belongs to; `''` for a project / draft terminal (see `scope`).
- `sizeSeq` (`number`): Bumped on every size change: signals and attach replies reach a view by
  different routes, so it keeps the newest size, not the last to arrive.
- `status` (`TerminalStatus`): Connection and process state.
- `target` (`TerminalTarget`): Where the terminal runs.
- `taskId?` (`string`): The background task it runs (agent terminals).
- `title?` (`string`): Title the program set (OSC 0/2), if any.

Source: [src/chat/terminal/protocol.ts:39](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L39)

### `TerminalOpenInput`

Interface.

Opens a terminal in a session.

```ts
interface TerminalOpenInput
```

**Properties**

- `cols` (`number`): Initial width in character cells.
- `rows` (`number`): Initial height in character cells.
- `sessionId` (`string`): Session to open the terminal in.
- `target?` (`TerminalTarget`, default `'session'`): Where to run it.

Source: [src/chat/terminal/protocol.ts:98](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L98)

### `TerminalProjectOpenInput`

Interface.

Opens a project / draft terminal: a shell on the host's machine in `cwd`.

```ts
interface TerminalProjectOpenInput
```

**Properties**

- `cols` (`number`): Initial width in character cells.
- `cwd` (`string`): Folder of the project. The shell starts here.
- `draftId?` (`string`): New-chat draft to tie the terminal to. Absent: the terminal belongs to the project.
- `rows` (`number`): Initial height in character cells.

Source: [src/chat/terminal/protocol.ts:110](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L110)

### `TerminalProjectScope`

Interface.

A terminal not bound to a session: a plain shell on the host's machine, in
a project's folder (docs/PROJECT-SCOPE-AUDIT.md). `draftId` ties it to a
new-chat draft until `terminal.adopt` hands it to the session created from
that draft (or `terminal.releaseDraft` gives it back to the project).
Agents never see unbound terminals.

```ts
interface TerminalProjectScope
```

**Properties**

- `draftId?` (`string`): New-chat draft the terminal is tied to. Absent: the terminal belongs to the project.
- `root` (`string`): Project root (`projectRootOf`, computed by the host).

Source: [src/chat/terminal/protocol.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L31)

### `TerminalProjectState`

Interface.

The terminals of a project or of one draft, and whether this host can run them.

```ts
interface TerminalProjectState
```

**Properties**

- `available` (`boolean`): False when this host cannot run terminals.
- `reason?` (`string`): Why not, when `available` is false.
- `root` (`string`): The resolved project root (what `terminal:project-changed` names).
- `terminals` (`TerminalInfo[]`): Terminals of the project or draft.

Source: [src/chat/terminal/protocol.ts:133](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L133)

### `TerminalProjectStateInput`

Interface.

The terminals of a project (`draftId` absent) or of one draft. `cwd` is any
folder of the project; the host resolves its root.

```ts
interface TerminalProjectStateInput
```

**Properties**

- `cwd` (`string`): Any folder of the project.
- `draftId?` (`string`): Draft to list the terminals of. Absent: the project's terminals.

Source: [src/chat/terminal/protocol.ts:125](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L125)

### `TerminalReadResult`

Interface.

The agent's view: plain text lines, with a cursor for the next read.

```ts
interface TerminalReadResult
```

**Properties**

- `next` (`number`): Pass as `since` to get only newer lines.
- `terminal` (`TerminalInfo`): The terminal that was read.
- `text` (`string`): Plain-text output.
- `truncated` (`number`): Lines dropped from the front because of the size cap.

Source: [src/chat/terminal/protocol.ts:163](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L163)

### `TerminalSessionState`

Interface.

The terminals of one session and whether this host can run them.

```ts
interface TerminalSessionState
```

**Properties**

- `available` (`boolean`): False when this host can't run terminals (the GUI without the daemon).
- `environment` (`{ kind: string; remote: boolean }`): Kind of the session's environment, and whether it runs somewhere else.
- `reason?` (`string`): Why not, when `available` is false.
- `terminals` (`TerminalInfo[]`): Terminals of the session.

Source: [src/chat/terminal/protocol.ts:86](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L86)

### `TextModelCandidate`

Interface.

One model of the session's provider, as the automatic pick reads it (a `ModelInfo` fits).

```ts
interface TextModelCandidate
```

**Properties**

- `cost?` (`{ input: number }`): Input price; the cheapest candidate wins, and one without a price loses.
- `id` (`string`): Model id.
- `input?` (`readonly ('text' | 'image')[]`): Input modalities; a model without `text` is skipped.
- `tier?` (`ModelTier`): Catalog tier; guessed from the id when absent.

Source: [src/chat/text-model.ts:77](https://github.com/Tahul/zidane/blob/main/src/chat/text-model.ts#L77)

### `TextModelOptions`

Interface.

Inputs of `textModelChain` / `resolveTextModel`.

```ts
interface TextModelOptions
```

**Properties**

- `main` (`{ account?: string; modelId: string; providerKey: string }`): The session's main model (or the default model, outside a session).
- `modelsOf` (`(providerKey: string) => readonly TextModelCandidate[]`): The models of a provider (`modelsForDescriptor`).
- `setting` (`string | undefined`): `Settings.textModel`: `''` / unset = automatic.

Source: [src/chat/text-model.ts:140](https://github.com/Tahul/zidane/blob/main/src/chat/text-model.ts#L140)

### `TextModelPick`

Interface.

A text model to run on.

```ts
interface TextModelPick
```

**Properties**

- `account?` (`string`): The provider's stored account; absent = its active one.
- `modelId` (`string`): Model id on that provider.
- `providerKey` (`string`): Provider to run on.
- `source` (`TextModelSource`): Whether the pick came from `Settings.textModel`, the automatic choice or the main model.

Source: [src/chat/text-model.ts:128](https://github.com/Tahul/zidane/blob/main/src/chat/text-model.ts#L128)

### `ThinkingDeltaOptions`

Interface.

Options for [`appendThinkingLines`](https://zidane.si/docs/reference/chat-pure.md#appendThinkingLines).

```ts
interface ThinkingDeltaOptions<E>
```

**Type parameters**

- `E`

**Properties**

- `onLaneOpen?` (`(row: E) => E`): Decorate the first row of a newly opened thinking lane (e.g. stamp its start time).

Source: [src/chat/streaming-pure.ts:134](https://github.com/Tahul/zidane/blob/main/src/chat/streaming-pure.ts#L134)

### `ToolDisplayMeta`

Interface.

How one tool is labeled and summarized in the transcript.

```ts
interface ToolDisplayMeta
```

**Properties**

- `displayName` (`string | ((input: Record<string, unknown> | undefined) => string)`): Sentence-case display verb (e.g. `Read`, `Shell`, `Edit`). When the
  label depends on an input field (e.g. `skills_use`'s
  `mode: 'activate' | 'deactivate'` → `Enable` / `Disable`), supply
  a function instead and read the field defensively. The function
  form is called whenever [`displayNameFor`](https://zidane.si/docs/reference/chat-pure.md#displayNameFor) has the call's
  input in scope; callers without input fall back to the function's
  `input: undefined` branch, which should return a stable default.
- `format` (`(input: Record<string, unknown>) => ToolFormatLine | null`): Pull a [`ToolFormatLine`](https://zidane.si/docs/reference/chat-pure.md#ToolFormatLine) out of the raw model input. Returns
  `null` when the shape isn't what the tool expects (typed defensively
  — we never want a malformed call to crash the transcript).

Source: [src/chat/tool-formatters.ts:55](https://github.com/Tahul/zidane/blob/main/src/chat/tool-formatters.ts#L55)

### `ToolFormatLine`

Interface.

The pieces of a one-line tool call summary.

```ts
interface ToolFormatLine
```

**Properties**

- `detail?` (`string`): Optional SECOND line — the payload behind the action (a prompt sent to
  another session). Renderers paint it dimmed under the header and clamp
  it (two lines in the GUI, one terminal row in the TUI); it is never
  squeezed into the header line, which stays single-line.
- `meta?` (`readonly string[]`): Secondary annotations shown after the target, each as its own
  segment. Use for line ranges (`L10-25`), limits, flags,
  or any short suffix that adds context without bloating the line.
- `sessionId?` (`string`): The session this call targets, when the tool addresses one. `target`
  carries the short id as a fallback; a renderer with the session list in
  scope shows the session's TITLE instead.
- `target?` (`string`): Primary target — typically a path, command, pattern, or
  task description. Renderer paints this in the model accent color
  so the eye lands on it first.

Source: [src/chat/tool-formatters.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/tool-formatters.ts#L26)

### `ToolOverview`

Interface.

One-line description of a tool call, built by [`toolOverview`](https://zidane.si/docs/reference/chat-pure.md#toolOverview).

```ts
interface ToolOverview
```

**Properties**

- `added?` (`number`): Lines added, for edits.
- `hint?` (`string`): Quiet context after the label: a file's directory, `+2` chained commands.
- `label` (`string`): What the call did, such as `Ran bun test`.
- `removed?` (`number`): Lines removed, for edits.
- `title?` (`string`): The full payload (the whole command, the full path).

Source: [src/chat/fold-actions.ts:193](https://github.com/Tahul/zidane/blob/main/src/chat/fold-actions.ts#L193)

### `ToolOverviewInput`

Interface.

What a tool call is, independent of how a surface stores it.

```ts
interface ToolOverviewInput
```

**Properties**

- `displayName` (`string`): Name shown to the user for the tool.
- `edit?` (`EditPayload`): Edit payload, when the call changed a file.
- `input?` (`Record<string, unknown>`): The call's input arguments.
- `name` (`string`): Tool name, such as `shell` or `read_file`.
- `ok?` (`boolean | null`): `null` while running.
- `result?` (`string | null`): The call's result text, once it has one.
- `target?` (`string`): The formatted target (`tool-formatters`), when there is one.

Source: [src/chat/fold-actions.ts:175](https://github.com/Tahul/zidane/blob/main/src/chat/fold-actions.ts#L175)

### `TranscriptPreset`

Interface.

One conversation preset.

```ts
interface TranscriptPreset
```

**Properties**

- `description` (`string`): One line on what it shows.
- `id` (`TranscriptPresetId`): The preset.
- `label` (`string`): Display name.
- `settings` (`TranscriptPresetSettings`): The value it gives every transcript setting.

Source: [src/chat/onboarding/types.ts:286](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L286)

### `TutorialStep`

Interface.

One step of a tutorial.

```ts
interface TutorialStep
```

**Properties**

- `detail` (`string`): One or two sentences more.
- `title` (`string`): What happens, in a few words.

Source: [src/chat/onboarding/tutorials.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tutorials.ts#L23)

### `TutorialWords`

Interface.

The words of a tutorial: its title and its three steps, in order.

```ts
interface TutorialWords
```

**Properties**

- `steps` (`readonly [TutorialStep, TutorialStep, TutorialStep]`): The steps. A scene plays them in turn, one third of its cycle each.
- `title` (`string`): The title, such as "How skills work".

Source: [src/chat/onboarding/tutorials.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tutorials.ts#L31)

### `UsageBlockDeps`

Interface.

What the usage block reads from its host.

```ts
interface UsageBlockDeps
```

**Properties**

- `modelName?` (`(modelId: string) => string`): A model id's display name. Default: `modelDisplayName`.
- `now?` (`() => Date`): The clock. Default: `new Date()`.
- `projectRootOf` (`(cwd: string) => string`): The project a folder belongs to.
- `subscribe?` (`(emit: () => void) => () => void`): Calls `emit` when the numbers may have changed (a run ended). Returns the unsubscribe.
- `summary` (`(range: UsageRange, projectRoot: string | undefined) => Promise<UsageSummary>`): The summary of `range`: one project's, or every session's (`projectRoot` absent).

Source: [src/chat/home-blocks.ts:33](https://github.com/Tahul/zidane/blob/main/src/chat/home-blocks.ts#L33)

### `ViewQueryInput`

Interface.

What [`viewQuery`](https://zidane.si/docs/reference/chat-pure.md#viewQuery) takes.

```ts
interface ViewQueryInput
```

**Properties**

- `knownSpaceIds` (`readonly string[]`): The id of every space that exists (user and extension spaces; `default` may be in it).
- `space?` (`SessionViewSpace | null`): The space the view is on. `null` or absent while spaces are off: the view spans every session.
- `view` (`SessionView`): The view's filters.

Source: [src/chat/session-query/view.ts:36](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/view.ts#L36)

### `VisibleInstructionRow`

Interface.

One selectable row: a context segment, plus its resolved open state.

```ts
interface VisibleInstructionRow
```

**Properties**

- `expanded` (`boolean`): Whether the row is open.
- `segment` (`ContextSegment`): Context segment shown in the row.

Source: [src/chat/instruction-rows.ts:24](https://github.com/Tahul/zidane/blob/main/src/chat/instruction-rows.ts#L24)

## Types

### `AgentAccent`

Type.

Theme color token used to accent the active profile in the UI (footer
badge, picker highlight). Resolved against `ThemeColors` via
`useColors()`; falls back to `accent` when omitted.

```ts
type AgentAccent = 'brand' | 'accent' | 'warn' | 'model'
```

Source: [src/chat/agent-accent.ts:11](https://github.com/Tahul/zidane/blob/main/src/chat/agent-accent.ts#L11)

### `AgeStep`

Type.

A step of the relative-age ladder: under a minute, a whole duration, or old enough to show as a date.

```ts
type AgeStep =
  | { kind: 'now' }
  | { kind: 'duration'; unit: 'm' | 'h' | 'd'; value: number }
  | { kind: 'date' }
```

Source: [src/chat/format.ts:154](https://github.com/Tahul/zidane/blob/main/src/chat/format.ts#L154)

### `AnsiColor`

Type.

A color: one of the 256 palette entries (0 to 15 are the theme's), or `#rrggbb`.

```ts
type AnsiColor = number | `#${string}`
```

Source: [src/chat/ansi.ts:14](https://github.com/Tahul/zidane/blob/main/src/chat/ansi.ts#L14)

### `AttachmentPlan`

Type.

What to do with a file: attach its bytes as they are, typed `mediaType`;
decode and re-encode an image first (a format providers don't take, or
over [`MAX_IMAGE_ATTACHMENT_BYTES`](https://zidane.si/docs/reference/chat-pure.md#MAX_IMAGE_ATTACHMENT_BYTES)); or refuse it.

```ts
type AttachmentPlan =
  | { kind: 'image' | 'pdf' | 'text'; mediaType: string }
  | { kind: 'convert-image'; mediaType: string }
  | ({ kind: 'refuse' } & AttachmentRefusal)
```

Source: [src/chat/attachment-rules.ts:75](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L75)

### `AttachmentRefusal`

Type.

Why a file is not attached.

```ts
type AttachmentRefusal =
  | { reason: 'empty' }
  | { limit: number; reason: 'too-large'; size: number }
  | { reason: 'export-pdf' }
  | { reason: 'unreadable-image' }
  | { reason: 'unsupported' }
```

Source: [src/chat/attachment-rules.ts:61](https://github.com/Tahul/zidane/blob/main/src/chat/attachment-rules.ts#L61)

### `AuthPrimaryAction`

Type.

What the card's main button does: sign in again, or retry when signing in would not help (yet).

```ts
type AuthPrimaryAction = 'sign-in' | 'retry'
```

Source: [src/chat/auth-failure.ts:11](https://github.com/Tahul/zidane/blob/main/src/chat/auth-failure.ts#L11)

### `BlockShell`

Type.

The shell a block runs in, from its fence.

```ts
type BlockShell = 'bash' | 'zsh' | 'sh'
```

Source: [src/chat/shell-blocks.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/shell-blocks.ts#L20)

### `BooleanSettingKey`

Type.

Keys of `Settings` whose value type is exactly `boolean`. Used to type
the toggle table so `SETTINGS_TOGGLES.key` only ever points to a
boolean-valued setting — string- and array-valued settings (theme,
enabledSkills, …) live in `SETTINGS_CHOICES` or actions.

`-?` strips optionality from the mapped output so `Settings[K]` doesn't
silently broaden into `T | undefined` and short-circuit the `extends
boolean` check via `undefined`.

```ts
type BooleanSettingKey = { [K in keyof Settings]-?: Settings[K] extends boolean ? K : never }[keyof Settings]
```

Source: [src/chat/settings-catalog.ts:53](https://github.com/Tahul/zidane/blob/main/src/chat/settings-catalog.ts#L53)

### `BrowserErrorCode`

Type.

Machine-readable reason a browser operation failed.

```ts
type BrowserErrorCode =
  | 'no_browser'
  | 'no_page'
  | 'stale_ref'
  | 'not_found'
  | 'not_actionable'
  | 'invalid_url'
  | 'invalid_input'
  | 'timeout'
  | 'interrupted'
  | 'cancelled'
  | 'too_large'
  | 'failed'
```

Source: [src/chat/browser/protocol.ts:161](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L161)

### `BrowserOp`

Type.

Name of a browser operation.

```ts
type BrowserOp = keyof BrowserOpInputs
```

Source: [src/chat/browser/protocol.ts:49](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L49)

### `BrowserResponse`

Type.

Answer to a [`BrowserRequest`](https://zidane.si/docs/reference/chat-pure.md#BrowserRequest): the result, or an error code and message.

```ts
type BrowserResponse<O extends BrowserOp = BrowserOp> = 
  | { ok: true; result: BrowserOpResults[O] }
  | { error: { code: BrowserErrorCode; message: string }; ok: false }
```

**Type parameters**

- `O` (`extends BrowserOp`, default `BrowserOp`)

Source: [src/chat/browser/protocol.ts:190](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L190)

### `BrowserWaitUntil`

Type.

Page load milestone a navigation waits for. `none` returns without waiting.

```ts
type BrowserWaitUntil = 'load' | 'domcontentloaded' | 'none'
```

Source: [src/chat/browser/protocol.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/browser/protocol.ts#L20)

### `BuiltinPanelId`

Type.

Built-in tabs the hosts render with their own components.

```ts
type BuiltinPanelId =
  | typeof INBOX_PANEL_ID
  | typeof QUEUE_PANEL_ID
  | typeof ARTIFACTS_PANEL_ID
  | typeof DIFFS_PANEL_ID
  | typeof FILES_PANEL_ID
  | typeof BROWSER_PANEL_ID
  | typeof TERMINAL_PANEL_ID
  | typeof SIDE_PANEL_ID
  | typeof SECRETS_PANEL_ID
  | typeof REMINDERS_PANEL_ID
```

Source: [src/chat/panels.ts:38](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L38)

### `CacheChipTone`

Type.

`warn` = a real cache break (a named dimension changed, so it was
avoidable); `dim` = ordinary TTL expiry, which is not anyone's fault and
should not shout.

```ts
type CacheChipTone = 'warn' | 'dim'
```

Source: [src/chat/footer-chips.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/footer-chips.ts#L26)

### `CatalogKind`

Type.

The catalogs Settings can ask about.

```ts
type CatalogKind =
  | 'tools'
  | 'agents'
  | 'subagents'
  | 'models'
  | 'providers'
  | 'mcp'
  | 'skills'
```

Source: [src/chat/agents-catalog.ts:173](https://github.com/Tahul/zidane/blob/main/src/chat/agents-catalog.ts#L173)

### `ChatReferenceScope`

Type.

Whether chat suggestions cover the current project or every project.

```ts
type ChatReferenceScope = 'project' | 'all'
```

Source: [src/chat/completion-chats.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/completion-chats.ts#L26)

### `ConnectorAuth`

Type.

How a connector signs in.

- `oauth`: in the browser, through the server's OAuth (the server registers zidane as a client).
- `token`: a token sent in a header ([`ConnectorTokenAuth`](https://zidane.si/docs/reference/chat-pure.md#ConnectorTokenAuth)).
- `none`: no account.

```ts
type ConnectorAuth = { kind: 'oauth' } | ConnectorTokenAuth | { kind: 'none' }
```

Source: [src/chat/onboarding/types.ts:382](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L382)

### `ConnectorCategory`

Type.

Section a connector is listed under.

```ts
type ConnectorCategory =
  | 'code'
  | 'work'
  | 'cloud'
  | 'observability'
  | 'docs'
  | 'browser'
```

Source: [src/chat/onboarding/types.ts:347](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L347)

### `ConnectorTransport`

Type.

How a connector reaches its server: an HTTP endpoint, or a command the
agent starts and talks to over stdio.

```ts
type ConnectorTransport =
  | { kind: 'http'; url: string }
  | { args: readonly string[]; command: string; kind: 'stdio' }
```

Source: [src/chat/onboarding/types.ts:353](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L353)

### `ContextBreakdownContributor`

Type.

Extension hook for adding opaque rows to the context panel.

```ts
type ContextBreakdownContributor = (ctx: ContextBreakdownContributionContext) => ContextExtensionSection | readonly ContextExtensionSection[] | null | undefined | Promise<ContextExtensionSection | readonly ContextExtensionSection[] | null | undefined>
```

Source: [src/chat/context-breakdown.ts:90](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L90)

### `ContextCategoryId`

Type.

Stable identifiers for each breakdown category. Drives swatch color +
ordering in both UIs. `*Deferred` buckets are tools/MCP that exist but are
NOT currently on the wire (lazy disclosure); `autocompactBuffer` is the
reserved output headroom; `freeSpace` is the remaining window.

```ts
type ContextCategoryId =
  | 'systemPrompt'
  | 'rules'
  | 'tools'
  | 'mcpTools'
  | 'mcpInstructions'
  | 'skills'
  | 'subagentDefs'
  | 'conversation'
  | 'mcpToolsDeferred'
  | 'toolsDeferred'
  | 'autocompactBuffer'
  | 'freeSpace'
```

Source: [src/chat/context-breakdown.ts:33](https://github.com/Tahul/zidane/blob/main/src/chat/context-breakdown.ts#L33)

### `ContextSegmentOrigin`

Type.

Where a segment's text came from. Only `'file'` segments carry a `path`.

```ts
type ContextSegmentOrigin = 'built-in' | 'file' | 'generated' | 'mcp'
```

Source: [src/chat/context-segments.ts:28](https://github.com/Tahul/zidane/blob/main/src/chat/context-segments.ts#L28)

### `DaemonHealth`

Type.

Daemon connection health — the one model behind the status dot in both
clients' footers.

Three states, because "connected: boolean" cannot express the one users
actually want to see: a daemon that is being spawned or reconnected is not
DOWN, and painting it red for the seconds that takes teaches people to
ignore red. So:

- `connected`    — handshake done, signals live.            green (accent)
- `connecting`   — spawning / reconnecting / first attempt. amber (warn)
- `disconnected` — reachable daemon absent, last attempt failed. red (error)

Tones are theme SLOTS, not colors, so the dot recolors with the palette on
both surfaces. Node-free; re-exported from `zidane/chat/pure`.

```ts
type DaemonHealth = 'connected' | 'connecting' | 'disconnected'
```

Source: [src/chat/daemon-health.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/daemon-health.ts#L17)

### `DaemonHealthTone`

Type.

Theme tone used to color the daemon health dot.

```ts
type DaemonHealthTone = 'accent' | 'warn' | 'error'
```

Source: [src/chat/daemon-health.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/daemon-health.ts#L20)

### `DiffOp`

Type.

Role of a line in a diff: unchanged context, an addition or a removal.

```ts
type DiffOp = 'context' | 'add' | 'remove'
```

Source: [src/chat/edit-diff.ts:135](https://github.com/Tahul/zidane/blob/main/src/chat/edit-diff.ts#L135)

### `EntryImportItem`

Type.

One thing dropped from outside: a file (read when its turn comes) or a folder.

```ts
type EntryImportItem =
  | { name: string; read: () => Promise<Uint8Array>; size: number }
  | { children: EntryImportItem[]; name: string }
```

Source: [src/chat/workspace/entries.ts:285](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L285)

### `EntryImportResult`

Type.

What an import did: the top-level paths it made, and why it stopped when it did.

```ts
type EntryImportResult =
  | { ok: true; paths: string[] }
  | { message: string; ok: false; paths: string[]; reason: EntryRefusal }
```

Source: [src/chat/workspace/entries.ts:290](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L290)

### `EntryRefusal`

Type.

Why an entry action was refused.

```ts
type EntryRefusal = 'exists' | 'missing' | 'invalid' | 'denied' | 'too-large'
```

Source: [src/chat/workspace/entries.ts:25](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L25)

### `EntryResult`

Type.

What an entry action did: the path it ended at, or why it was refused.

```ts
type EntryResult =
  | { ok: true; path: string }
  | { message: string; ok: false; reason: EntryRefusal }
```

Source: [src/chat/workspace/entries.ts:38](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/entries.ts#L38)

### `ExtensionMark`

Type.

What an app draws for an extension: an icon class, a Simple Icons slug, or a letter.

```ts
type ExtensionMark =
  | { gui: string; kind: 'icon' }
  | { brand: string; kind: 'brand' }
  | { kind: 'letter'; letter: string }
```

Source: [src/chat/extension-mark.ts:10](https://github.com/Tahul/zidane/blob/main/src/chat/extension-mark.ts#L10)

### `ExtensionSourceErrorCode`

Type.

Why a listing is empty or partial.

- `not-found`: no such repository, branch, folder or package.
- `private`: the source exists but needs access (or GitHub hid it: a private repository answers 404 without a token).
- `rate-limit`: GitHub refused more calls without a token.
- `network`: the connection failed, or the server answered an error.
- `invalid`: the text is not a source this can list.

```ts
type ExtensionSourceErrorCode =
  | 'not-found'
  | 'private'
  | 'rate-limit'
  | 'network'
  | 'invalid'
```

Source: [src/chat/extension-sources.ts:43](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L43)

### `ExtensionSourceKind`

Type.

The kind of a source: a GitHub repository (or a folder in one), an npm package, another link, a folder on the host.

```ts
type ExtensionSourceKind = 'github' | 'npm' | 'url' | 'local'
```

Source: [src/chat/extension-sources.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/extension-sources.ts#L12)

### `FacetPath`

Type.

A facet an extension computes for each session: `facet.<extensionId>.<key>`,
optionally followed by `.<property>` steps into an object value (a number
step indexes an array).

```ts
type FacetPath = `facet.${string}`
```

Source: [src/chat/session-query/types.ts:55](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L55)

### `FoldStepState`

Type.

A step's progress: `waiting` is a `spawn` call every worker slot is taken for.

```ts
type FoldStepState = 'waiting' | 'running' | 'ok' | 'err'
```

Source: [src/chat/fold-rules.ts:64](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L64)

### `FoldUnit`

Type.

One folded item, as the planner reads it. `item` is the surface's own object, handed back in the steps.

```ts
type FoldUnit<T> = { childId?: string; depth?: number; item: T; spawn?: StreamEvent['spawn'] } & ({ kind: 'thought'; live?: boolean; ms?: number } | { callId?: string; displayName: string; kind: 'call'; ms?: number; name: string; parentId?: string; state: FoldStepState; task?: string; waitingFor?: { active: number; max: number } } | { callId: string; failed: boolean; kind: 'result' } | { kind: 'spawn-start' | 'spawn-end'; text: string } | { kind: 'note' } | { kind: 'other' })
```

**Type parameters**

- `T`

Source: [src/chat/fold-rules.ts:67](https://github.com/Tahul/zidane/blob/main/src/chat/fold-rules.ts#L67)

### `HeatmapLevel`

Type.

0 = no activity … 4 = the top quartile of active days.

```ts
type HeatmapLevel = 0 | 1 | 2 | 3 | 4
```

Source: [src/chat/heatmap-levels.ts:8](https://github.com/Tahul/zidane/blob/main/src/chat/heatmap-levels.ts#L8)

### `HostConnectionStatus`

Type.

`auth-refused`: the server turned the token down (401/403); `identity`: a
different server answers at a saved host's URL. Neither retries until
something changes. `version-mismatch`: the server speaks another protocol
version (the error says which side to upgrade); re-checked every few
minutes, so an upgrade heals it.

```ts
type HostConnectionStatus =
  | 'connecting'
  | 'connected'
  | 'reconnecting'
  | 'offline'
  | 'auth-refused'
  | 'identity'
  | 'version-mismatch'
```

Source: [src/chat/hosts/connection.ts:21](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/connection.ts#L21)

### `HostErrorCode`

Type.

Why a host could not be added or tested:

- `invalid-url`: not `wss://`, or `ws://` off loopback; nothing was dialed.
- `invalid-token`: empty.
- `invalid-name`: an empty name.
- `auth`: the server refused the token (401) or the connection (403).
- `unreachable`: nothing answered (refused, DNS, timeout, closed).
- `tls`: the TLS handshake failed (certificate).
- `protocol`: something answered but not a zidane-server this client can
  talk to (protocol version, no host identity, not a server).
- `identity`: a different host answers at the saved URL.
- `unknown-host`: no saved host has this id.

```ts
type HostErrorCode =
  | 'invalid-url'
  | 'invalid-token'
  | 'invalid-name'
  | 'auth'
  | 'unreachable'
  | 'tls'
  | 'protocol'
  | 'identity'
  | 'unknown-host'
```

Source: [src/chat/hosts/types.ts:40](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/types.ts#L40)

### `HostProbeResult`

Type.

Answer of a host probe: the host's identity and latency, or an error code and message.

```ts
type HostProbeResult =
  | { hostRef: HostIdentity; latencyMs: number; ok: true; serverVersion?: string }
  | { error: HostErrorCode; message: string; ok: false }
```

Source: [src/chat/hosts/types.ts:53](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/types.ts#L53)

### `HostTestResult`

Type.

`test(id)`: the probe's answer, checked against the saved entry.

```ts
type HostTestResult = HostProbeResult
```

Source: [src/chat/hosts/types.ts:58](https://github.com/Tahul/zidane/blob/main/src/chat/hosts/types.ts#L58)

### `InstallScopeChoice`

Type.

Where a written MCP entry lands.

```ts
type InstallScopeChoice = 'user' | 'project'
```

Source: [src/chat/mcp-form.ts:14](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L14)

### `MachineLinkState`

Type.

What a local host's machine links are doing (`machines.links.status`,
`machine:links`): this computer shared with a saved server (it is the
machine), and saved servers used as machines (`local@<server>`, the
reverse direction over this host's own client connection).

```ts
type MachineLinkState =
  | 'connecting'
  | 'connected'
  | 'reconnecting'
  | 'offline'
  | 'auth-refused'
  | 'identity'
  | 'version-mismatch'
  | 'refused'
```

Source: [src/chat/machine-protocol.ts:233](https://github.com/Tahul/zidane/blob/main/src/chat/machine-protocol.ts#L233)

### `McpAuthStatus`

Type.

Per-server MCP OAuth status tracking, decoupled from the renderer.

The TUI keeps a `Record<serverName, McpAuthStatus>` so it can render a
"needs-auth" / "authorizing" / "error" badge in the MCP picker. The
status map is driven entirely by hooks fired from the agent's MCP
bootstrap + the interactive `loginMcpServer` flow — the reducer below
is pure, makes no FS or network calls, and is shared between the live
TUI store and the test harness.

Status lifecycle:

needs-auth | authorizing | authed ──mcp:connect──▶ authed
(bootstrap succeeded with stored tokens; a server
that was never OAuth-tracked stays idle)
needs-auth (reason 'refused') ──mcp:connect──▶ idle
bootstrap-error | key-refused ──mcp:connect──▶ idle

idle ──mcp:auth:required──▶ needs-auth
(bootstrap saw no/invalid tokens)

idle ──401/403, no key of its own──▶ needs-auth (reason 'refused')
idle ──401/403 on its own header key──▶ key-refused
(see `classifyMcpTest`)

needs-auth ──login()──▶ authorizing ──mcp:auth:url──▶ authorizing(url)
──mcp:auth:success──▶ authed
──mcp:auth:error──▶ error

any         ──logout──▶ idle

Multiple servers progress through the lifecycle independently; the map
is keyed by `McpServerConfig.name`.

```ts
type McpAuthStatus =
  | { kind: 'idle' }
  | { kind: 'needs-auth'; reason: McpNeedsAuthReason }
  | { kind: 'authorizing'; url?: string }
  | { kind: 'authed' }
  | { error: string; kind: 'error' }
  | { error: string; kind: 'bootstrap-error' }
  | { error: string; kind: 'key-refused' }
```

Source: [src/chat/mcp-auth-state.ts:36](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-auth-state.ts#L36)

### `McpTestOutcomeKind`

Type.

Classification of an MCP connection attempt.

```ts
type McpTestOutcomeKind = 'ok' | 'needs-auth' | 'token-rejected' | 'error'
```

Source: [src/chat/mcp-test-outcome.ts:18](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-test-outcome.ts#L18)

### `McpTransport`

Type.

Transport an MCP server is reached over.

```ts
type McpTransport = 'stdio' | 'streamable-http' | 'sse'
```

Source: [src/chat/mcp-form.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/mcp-form.ts#L17)

### `MediaKind`

Type.

What a media file is played as.

```ts
type MediaKind = 'image' | 'video' | 'audio' | 'pdf'
```

Source: [src/chat/workspace/media-type.ts:6](https://github.com/Tahul/zidane/blob/main/src/chat/workspace/media-type.ts#L6)

### `ModelNamer`

Type.

How a surface names a model: the model picker's name for it (`Opus 4.5`).

```ts
type ModelNamer = (modelId: string, providerKey?: string) => string
```

Source: [src/chat/run-receipt.ts:192](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L192)

### `NativeExtensionGroup`

Type.

Section a native extension is listed under.

```ts
type NativeExtensionGroup = 'workflows' | 'integrations' | 'composer' | 'providers'
```

Source: [src/chat/onboarding/types.ts:415](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L415)

### `NativeExtensionNeed`

Type.

Something a native extension needs to work, shown on its card.

- `command`: a program on PATH ([`NativeExtensionCommandNeed`](https://zidane.si/docs/reference/chat-pure.md#NativeExtensionCommandNeed)).
- `connector`: a connector it works through. The step offers to add it.
- `decisions`: the decision model, used when available.
- `account`: an account with a service, set up after the install.

```ts
type NativeExtensionNeed =
  | NativeExtensionCommandNeed
  | { id: string; kind: 'connector' }
  | { kind: 'decisions' }
  | { kind: 'account'; label: string }
```

Source: [src/chat/onboarding/types.ts:437](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L437)

### `NativeExtensionNeedWords`

Type.

The words that [`nativeExtensionNeedText`](https://zidane.si/docs/reference/chat-pure.md#nativeExtensionNeedText) uses.

```ts
type NativeExtensionNeedWords = Pick<OnboardingWords, 'needsCommand' | 'needsConnector' | 'needsDecisions' | 'needsAccount'>
```

Source: [src/chat/onboarding/words.ts:129](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L129)

### `NoticeSeverity`

Type.

Severity of a transcript notice.

```ts
type NoticeSeverity = NonNullable<StreamEvent['notice']>['severity']
```

Source: [src/chat/notice-format.ts:12](https://github.com/Tahul/zidane/blob/main/src/chat/notice-format.ts#L12)

### `OnboardingAction`

Type.

What can happen in a run.

- `next` / `back`: move one step. `next` on the last step finishes the run.
- `goto`: jump to a step of the run, such as from Ready's recap.
- `skip`: put the current step's picks back, then move on.
- `finish`: end the run now, keeping what was picked (Skip setup).
- `choose-path`: Welcome's choice. Quick start cuts the run down to Connect, Bring your setup and Ready.
- `set-context`: the detection finished. The steps are planned again and the current one kept.
- `set-settings`: change settings. Turning a setting on also turns on what it needs and, for a feature, what it includes. Turning one off turns off what needs it.
- `apply-preset`: set every transcript setting to a preset's values.
- `set-provider`, `set-imports`, `set-appearance`: Connect's, Bring your setup's and Look's picks.
- `toggle-connector`, `toggle-extension`: pick or unpick a connector or a native extension.
- `toggle-skills`: pick or unpick skills, one or a whole listing at once.
- `task`: add or update a background task, matched by id.

```ts
type OnboardingAction =
  | { type: 'next' }
  | { type: 'back' }
  | { step: OnboardingStepId; type: 'goto' }
  | { type: 'skip' }
  | { type: 'finish' }
  | { path: OnboardingDraft['path']; type: 'choose-path' }
  | { context: Partial<OnboardingPlanContext>; type: 'set-context' }
  | { settings: Partial<Settings>; type: 'set-settings' }
  | { preset: TranscriptPresetId; type: 'apply-preset' }
  | { provider: OnboardingProviderPick | undefined; type: 'set-provider' }
  | { imports: OnboardingImportSelection | undefined; type: 'set-imports' }
  | { appearance: OnboardingAppearance | undefined; type: 'set-appearance' }
  | { id: string; on: boolean; type: 'toggle-connector' }
  | { name: string; on: boolean; type: 'toggle-extension' }
  | { on: boolean; picks: readonly SkillPick[]; type: 'toggle-skills' }
  | { task: OnboardingTask; type: 'task' }
```

Source: [src/chat/onboarding/flow.ts:89](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/flow.ts#L89)

### `OnboardingAgentId`

Type.

Another coding agent whose configuration the wizard can import or read.

```ts
type OnboardingAgentId = 'claude-code' | 'codex' | 'pi'
```

Source: [src/chat/onboarding/types.ts:83](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L83)

### `OnboardingCredentialSource`

Type.

How a provider's credential was found.

```ts
type OnboardingCredentialSource = 'env' | 'apikey' | 'oauth' | 'configured'
```

Source: [src/chat/onboarding/types.ts:86](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L86)

### `OnboardingFeatureBadge`

Type.

A mark on a feature: still experimental, or billed by the provider on each use.

```ts
type OnboardingFeatureBadge = 'experimental' | 'billed'
```

Source: [src/chat/onboarding/types.ts:305](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L305)

### `OnboardingFeatureGroup`

Type.

Section a feature is listed under.

```ts
type OnboardingFeatureGroup = 'work' | 'background' | 'desktop' | 'trust'
```

Source: [src/chat/onboarding/types.ts:302](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L302)

### `OnboardingGate`

Type.

What an app does at launch about the wizard.

- `run`: show it, in `mode`.
- `migrate`: the install predates the wizard. Write its record and show nothing.
- `none`: nothing to do.

```ts
type OnboardingGate =
  | { kind: 'run'; mode: OnboardingMode }
  | { kind: 'migrate' }
  | { kind: 'none' }
```

Source: [src/chat/onboarding/types.ts:592](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L592)

### `OnboardingImportPreviewState`

Type.

What an import from Claude Code brings over.

- `none`: the run offers no import, because there is no Claude Code setup or no import.
- `loading`: the host is reading it.
- `ready`: the preview.
- `failed`: the host failed to read it.

```ts
type OnboardingImportPreviewState =
  | { kind: 'none' }
  | { kind: 'loading' }
  | { kind: 'ready'; preview: OnboardingImportPreview }
  | { kind: 'failed'; message: string }
```

Source: [src/chat/onboarding/run.ts:67](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L67)

### `OnboardingImportWords`

Type.

The words that [`onboardingImportParts`](https://zidane.si/docs/reference/chat-pure.md#onboardingImportParts) uses.

```ts
type OnboardingImportWords = Pick<OnboardingWords, 'importSessions' | 'importMcps' | 'importSkills' | 'importCommands' | 'importAgents'>
```

Source: [src/chat/onboarding/recap.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/recap.ts#L13)

### `OnboardingMode`

Type.

How much of the wizard runs.

- `full`: every step that applies, for a fresh install.
- `quick`: Welcome, Connect, Bring your setup (when another agent is found) and Ready.
- `extras`: the steps that belong to this app only, after the shared steps ran in the other app.
- `connect`: Connect alone, opened from the desktop app's sign-in prompts.
- `rerun`: every step but Welcome, prefilled with the current values, opened from Settings or the palette.

```ts
type OnboardingMode = 'full' | 'quick' | 'extras' | 'connect' | 'rerun'
```

Source: [src/chat/onboarding/types.ts:42](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L42)

### `OnboardingPhase`

Type.

Where a run is in its life.

- `running`: the user is going through the steps.
- `saving`: the last step was passed, and the host is writing the result.
- `saved`: the result is written. The app closes the wizard.
- `failed`: writing failed. The run is back on its step, and moving on again tries again.

```ts
type OnboardingPhase =
  | { kind: 'running' }
  | { kind: 'saving' }
  | { kind: 'saved'; result: OnboardingResult }
  | { kind: 'failed'; message: string }
```

Source: [src/chat/onboarding/run.ts:53](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/run.ts#L53)

### `OnboardingSignInState`

Type.

Where a browser sign-in is, for a provider or a connector. Renderers show
the link, the device code or the question. `done` and `error` end it.

- `starting`: the flow is starting.
- `url`: the sign-in page to open. Pasting the redirect URL or the code also finishes it.
- `device`: a device flow. The user enters `userCode` on the page at `url`.
- `prompt`: the provider asks a question, such as a code to paste, or a pick among `options`.
- `progress`: a status line while it finishes.
- `done`: signed in, as `account` when the provider names it.
- `error`: it failed, with the reason.

```ts
type OnboardingSignInState =
  | { kind: 'starting' }
  | { kind: 'url'; url: string }
  | { expiresInSeconds?: number; kind: 'device'; url: string; userCode: string }
  | { kind: 'prompt'; message: string; options?: readonly string[]; placeholder?: string }
  | { kind: 'progress'; message: string }
  | { account?: string; kind: 'done' }
  | { kind: 'error'; message: string }
```

Source: [src/chat/onboarding/types.ts:196](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L196)

### `OnboardingStepId`

Type.

A step of the setup wizard, in flow order.

```ts
type OnboardingStepId =
  | 'welcome'
  | 'connect'
  | 'import'
  | 'connectors'
  | 'skills'
  | 'extensions'
  | 'look'
  | 'conversation'
  | 'autonomy'
  | 'features'
  | 'ready'
```

Source: [src/chat/onboarding/types.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L17)

### `OnboardingStepScope`

Type.

What a step writes: files both apps read (`shared`), state of the app that
runs it (`surface`), or nothing (`none`).

```ts
type OnboardingStepScope = 'shared' | 'surface' | 'none'
```

Source: [src/chat/onboarding/types.ts:48](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L48)

### `OnboardingSurface`

Type.

The app that runs the wizard.

```ts
type OnboardingSurface = 'tui' | 'desktop'
```

Source: [src/chat/onboarding/types.ts:31](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L31)

### `OnboardingTaskKind`

Type.

What a background task does.

```ts
type OnboardingTaskKind = 'import' | 'connector' | 'skill' | 'extension'
```

Source: [src/chat/onboarding/types.ts:468](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L468)

### `OnboardingTaskStatus`

Type.

Where a background task is. `needs-sign-in`: added, but the browser sign-in did not finish.

```ts
type OnboardingTaskStatus = 'queued' | 'running' | 'done' | 'failed' | 'needs-sign-in'
```

Source: [src/chat/onboarding/types.ts:471](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L471)

### `OnboardingWords`

Type.

The shape of [`ONBOARDING_WORDS`](https://zidane.si/docs/reference/chat-pure.md#ONBOARDING_WORDS).

```ts
type OnboardingWords = typeof ONBOARDING_WORDS
```

Source: [src/chat/onboarding/words.ts:126](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/words.ts#L126)

### `OutputStream`

Type.

Where an output line came from: a printed item (`output`, `console`) or a command's `stdout` / `stderr`.

```ts
type OutputStream = 'output' | 'console' | 'stdout' | 'stderr'
```

Source: [src/chat/output-tail.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/output-tail.ts#L16)

### `PaletteHost`

Type.

Which app renders the palette.

```ts
type PaletteHost = 'gui' | 'tui'
```

Source: [src/chat/palette.ts:20](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L20)

### `PaletteItemKind`

Type.

`toggle` shows a checked state; `picker` opens a nested list on run.

```ts
type PaletteItemKind = 'action' | 'toggle' | 'picker'
```

Source: [src/chat/palette.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L23)

### `PaletteRunResult`

Type.

What a provider's `run` may hand back. `items` opens a nested picker
(branches, environments); the host keeps a stack so Backspace on an
empty query goes back one level. `prompt` sends text to the chat,
`insert` puts it in the composer (a `/` command that takes arguments).

```ts
type PaletteRunResult =
  | void
  | undefined
  | { items: readonly PaletteItem[]; kind: 'items'; placeholder?: string; title?: string }
  | { kind: 'prompt'; text: string }
  | { kind: 'insert'; text: string }
  | { kind: 'notify'; text: string; tone?: 'info' | 'warn' | 'error' }
```

Source: [src/chat/palette.ts:75](https://github.com/Tahul/zidane/blob/main/src/chat/palette.ts#L75)

### `PanelTab`

Type.

A built-in or extension panel tab.

```ts
type PanelTab = BuiltinPanelTab | ExtensionPanelTab
```

Source: [src/chat/panels.ts:81](https://github.com/Tahul/zidane/blob/main/src/chat/panels.ts#L81)

### `ParsedFieldPath`

Type.

A field path read apart.

```ts
type ParsedFieldPath =
  | { kind: 'field'; name: SessionFieldName; type: SessionFieldType }
  | { extension: string; facet: string; key: string; kind: 'facet'; steps: readonly string[] }
```

Source: [src/chat/session-query/fields.ts:54](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L54)

### `PromptSegment`

Type.

One atomic unit emitted by [`splitPromptSegments`](https://zidane.si/docs/reference/chat-pure.md#splitPromptSegments). Plain segments
are word-sized so wraps land cleanly between words; chip segments
carry the source `providerId` (`'skills'`, `'files'`, …) so renderers
can pick per-kind colors without re-walking the ref list.

```ts
type PromptSegment =
  | { kind: 'plain'; text: string }
  | { kind: 'chip'; providerId: string; text: string }
```

Source: [src/chat/prompt-segments.ts:33](https://github.com/Tahul/zidane/blob/main/src/chat/prompt-segments.ts#L33)

### `ProviderUsageStatus`

Type.

Outcome of a usage probe: `ok`, `unauthorized` when the credential is missing or rejected, or `unavailable` on any other failure.

```ts
type ProviderUsageStatus = 'ok' | 'unauthorized' | 'unavailable'
```

Source: [src/chat/provider-usage-format.ts:75](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L75)

### `QueryBound`

Type.

A bound of `gt` / `gte` / `lt` / `lte`: a number (epoch ms on time
fields), a relative time (`'now'`, `'-7d'`, `'+12h'`; units `s m h d w`),
or an ISO date (`'2026-01-31'`, `'2026-01-31T09:00:00Z'`; a date without a
zone is UTC). Strings are accepted on time fields and facets.

```ts
type QueryBound = number | string
```

Source: [src/chat/session-query/types.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L16)

### `QueryValue`

Type.

A value a condition compares against. `null` stands for "no value".

```ts
type QueryValue = string | number | boolean | null
```

Source: [src/chat/session-query/types.ts:8](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L8)

### `RunEstimateView`

Type.

A run's estimate as hosts send it to windows (`run:estimate`, a session
row's `runEstimates`): its timing, or the lasting problem that keeps it
from having one.

```ts
type RunEstimateView = RunEstimateTiming | RunEstimateProblem
```

Source: [src/chat/run-estimate.ts:182](https://github.com/Tahul/zidane/blob/main/src/chat/run-estimate.ts#L182)

### `RunFoldStatus`

Type.

What the live work row's header says while a run is in flight:

- `retrying`: a provider call is being retried.
- `waiting`: nothing has moved on screen for [`RUN_WAITING_DELAY_MS`](https://zidane.si/docs/reference/chat-pure.md#RUN_WAITING_DELAY_MS); the run waits on the model.
- `working`: anything else. The surface names the work its usual way.

```ts
type RunFoldStatus =
  | { kind: 'retrying'; retry: RunRetry }
  | { kind: 'waiting' }
  | { kind: 'working' }
```

Source: [src/chat/run-activity.ts:83](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L83)

### `RunReceiptCellKind`

Type.

What a cell IS, so renderers can tint by meaning rather than by position.

```ts
type RunReceiptCellKind =
  | 'agent'
  | 'model'
  | 'duration'
  | 'turns'
  | 'cost'
  | 'tokens'
  | 'speed'
```

Source: [src/chat/run-receipt.ts:166](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L166)

### `RunReceiptSegmentKind`

Type.

Sub-parts of a cell that want their own tint — the two token arrows.

```ts
type RunReceiptSegmentKind = 'tokens-in' | 'tokens-out'
```

Source: [src/chat/run-receipt.ts:168](https://github.com/Tahul/zidane/blob/main/src/chat/run-receipt.ts#L168)

### `RunTailActivity`

Type.

What the transcript's tail shows during a run:

- `streaming`: a reply is streaming in.
- `thinking`: reasoning text is streaming in.
- `tool`: a tool call (a subagent, a question to the user, a command) is running.
- `waiting`: nothing live is on screen; the run is waiting on the model.

```ts
type RunTailActivity = 'streaming' | 'thinking' | 'tool' | 'waiting'
```

Source: [src/chat/run-activity.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/run-activity.ts#L17)

### `ScriptCallStatus`

Type.

How the latest call of a script line stands: `waiting` is a `sleep(ms)` in progress.

```ts
type ScriptCallStatus = 'running' | 'waiting' | 'ok' | 'error'
```

Source: [src/chat/script-progress.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L23)

### `ScriptLineState`

Type.

How a script line draws: `idle` (not reached yet), `passed` (the script went
past it, or it makes no call), `running`, `waiting` (a `sleep`), `done` or
`failed` (its latest call), `previous` (in a loop that went round again: it
ran in an earlier round, not yet in this one).

```ts
type ScriptLineState =
  | 'idle'
  | 'passed'
  | 'running'
  | 'waiting'
  | 'done'
  | 'failed'
  | 'previous'
```

Source: [src/chat/script-progress.ts:251](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L251)

### `ScriptLoopKind`

Type.

What a loop of the script is: a `for` / `while` / `do`, or the callback of an array method (`.map`, `.forEach`).

```ts
type ScriptLoopKind = 'loop' | 'callback'
```

Source: [src/chat/script-progress.ts:596](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L596)

### `ScriptOutputLine`

Type.

One line of what a script printed or its shell calls wrote.

```ts
type ScriptOutputLine = OutputLine
```

Source: [src/chat/script-progress.ts:38](https://github.com/Tahul/zidane/blob/main/src/chat/script-progress.ts#L38)

### `SearchTurnResult`

Type.

Alias of `SearchTurnMatch`.

```ts
type SearchTurnResult = SearchTurnMatch
```

Source: [src/chat/history-search.ts:47](https://github.com/Tahul/zidane/blob/main/src/chat/history-search.ts#L47)

### `SecretAnswer`

Type.

What a client sends for a `secret` question: the typed value and the TTL
the person picked, or a decline. Never persisted: the host swaps it for a
[`SecretReference`](https://zidane.si/docs/reference/chat-pure.md#SecretReference) first.

```ts
type SecretAnswer =
  | { kind: 'secret-value'; ttl: SecretTtl; value: string }
  | { kind: 'secret-declined' }
```

Source: [src/chat/secrets/protocol.ts:83](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L83)

### `SecretReference`

Type.

What the model reads for a `secret` question. Holds no value.

```ts
type SecretReference =
  | { expiresAt: string | null; path: string; reused?: true; secret: string }
  | { declined: true; reason?: string; secret: string }
```

Source: [src/chat/secrets/protocol.ts:88](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L88)

### `SecretTtl`

Type.

How long a secret stays in the store. `never` keeps it until the user revokes it.

```ts
type SecretTtl = '1h' | '24h' | '7d' | 'never'
```

Source: [src/chat/secrets/protocol.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/secrets/protocol.ts#L13)

### `SessionEventStatus`

Type.

What happened in a worker. `needs-attention` is a worker blocked on an
approval or interaction that no window has answered — the main can steer,
but a human still has to decide.

```ts
type SessionEventStatus = 'done' | 'error' | 'cancelled' | 'needs-attention'
```

Source: [src/chat/orchestration.ts:64](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L64)

### `SessionEventTone`

Type.

Semantic tone a renderer maps onto its theme.

```ts
type SessionEventTone = 'accent' | 'error' | 'dim' | 'warn'
```

Source: [src/chat/orchestration.ts:624](https://github.com/Tahul/zidane/blob/main/src/chat/orchestration.ts#L624)

### `SessionFieldName`

Type.

A session row field a query can read. `environment.kind` is `'local'` for a
session without an environment. `projectName` is computed: the folder name
(last path segment) of `projectRoot`, or of `cwd` without one.

```ts
type SessionFieldName =
  | 'id'
  | 'title'
  | 'projectRoot'
  | 'projectName'
  | 'cwd'
  | 'agentId'
  | 'status'
  | 'createdAt'
  | 'updatedAt'
  | 'runStartedAt'
  | 'archived'
  | 'favorite'
  | 'isMain'
  | 'spaceId'
  | 'scheduleId'
  | 'providerKey'
  | 'modelId'
  | 'account'
  | 'effort'
  | 'hostId'
  | 'repoKey'
  | 'environment.kind'
  | 'environment.state'
  | 'environment.branch'
  | 'wakes'
```

Source: [src/chat/session-query/types.ts:23](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L23)

### `SessionFieldPath`

Type.

What a condition, a sort or a grouping reads: a row field or a facet.

```ts
type SessionFieldPath = SessionFieldName | FacetPath
```

Source: [src/chat/session-query/types.ts:58](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L58)

### `SessionFieldType`

Type.

How a field compares: text, number, time (epoch ms) or boolean.

```ts
type SessionFieldType = 'string' | 'number' | 'time' | 'boolean'
```

Source: [src/chat/session-query/fields.ts:9](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/fields.ts#L9)

### `SessionGroupOrder`

Type.

Group order: by label ascending or descending, or these group keys first (the rest by label after them).

```ts
type SessionGroupOrder = 'asc' | 'desc' | readonly string[]
```

Source: [src/chat/session-query/types.ts:125](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L125)

### `SessionQuery`

Type.

A filter over session rows: a condition, or `all` / `any` / `not` of more queries.

```ts
type SessionQuery =
  | SessionCondition
  | SessionQueryAll
  | SessionQueryAny
  | SessionQueryNot
```

Source: [src/chat/session-query/types.ts:110](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/types.ts#L110)

### `SpaceIcon`

Type.

A space's icon: one emoji, or a small image data-URL (the GUI's directory icon shape).

```ts
type SpaceIcon = { kind: 'emoji'; value: string } | { kind: 'image'; value: string }
```

Source: [src/chat/spaces.ts:26](https://github.com/Tahul/zidane/blob/main/src/chat/spaces.ts#L26)

### `SyncCategory`

Type.

Settings sync, this computer → a server (one-way, opt-in): the shapes both
sides share. Node-free, re-exported from `zidane/chat/pure` for the GUI
renderer.

A server keeps one sync record (`<dataDir>/sync.json`): the device that
syncs to it (one source per server), the categories that device sends,
the fields it set ("synced from <device>") and the fields edited on the
server since (overrides, which sync leaves alone until reset). The client
keeps, per saved server, a mode, the categories, the API keys it opted in
and the categories still to push (`hosts-sync.json`).

Fields are named `<kind>:<name>`: `setting:approvalMode`, `safelist:/srv/app`,
`system-md`, `skill:deploy`, `mcp:github`, `extension:greeter`,
`environment:e2b`, `key:anthropic`.

```ts
type SyncCategory =
  | 'settings'
  | 'safelists'
  | 'files'
  | 'mcps'
  | 'extensions'
  | 'environments'
  | 'keys'
```

Source: [src/chat/sync/types.ts:17](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L17)

### `SyncMode`

Type.

Off (default), Import once (a snapshot now), or Keep in sync (changes pushed as they happen).

```ts
type SyncMode = 'off' | 'once' | 'keep'
```

Source: [src/chat/sync/types.ts:49](https://github.com/Tahul/zidane/blob/main/src/chat/sync/types.ts#L49)

### `TerminalOwner`

Type.

Who started it: the user, or the agent (a background `shell` task).

```ts
type TerminalOwner = 'user' | 'agent'
```

Source: [src/chat/terminal/protocol.ts:13](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L13)

### `TerminalStatus`

Type.

`paused`: not connected right now (the sandbox paused, or the host
restarted) but it can be found again; opening it reconnects.

```ts
type TerminalStatus = 'starting' | 'running' | 'paused' | 'exited' | 'error'
```

Source: [src/chat/terminal/protocol.ts:22](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L22)

### `TerminalTarget`

Type.

Where it runs: the session's environment, or this machine in the project.

```ts
type TerminalTarget = 'session' | 'local'
```

Source: [src/chat/terminal/protocol.ts:16](https://github.com/Tahul/zidane/blob/main/src/chat/terminal/protocol.ts#L16)

### `TextModelSource`

Type.

Where a resolved text model came from.

```ts
type TextModelSource = 'setting' | 'auto' | 'main'
```

Source: [src/chat/text-model.ts:125](https://github.com/Tahul/zidane/blob/main/src/chat/text-model.ts#L125)

### `ToolInstall`

Type.

How a missing tool gets on a host. `run`: a command the host may run itself,
as its own user, no root (`host.installTool`). `copy`: a command that needs
root, for the person to run there. `link`: the tool's install page.

```ts
type ToolInstall =
  | { command: string; kind: 'run' }
  | { command: string; kind: 'copy' }
  | { kind: 'link'; url: string }
```

Source: [src/chat/capabilities.ts:60](https://github.com/Tahul/zidane/blob/main/src/chat/capabilities.ts#L60)

### `TranscriptPresetId`

Type.

A conversation preset.

```ts
type TranscriptPresetId = 'focused' | 'balanced' | 'detailed'
```

Source: [src/chat/onboarding/types.ts:262](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L262)

### `TranscriptPresetKey`

Type.

The settings a conversation preset sets: how much of the agent's work the transcript shows, and how plain its rows are.

```ts
type TranscriptPresetKey =
  | 'transcriptDensity'
  | 'showRowIcons'
  | 'showThinking'
  | 'thinkingAutoExpand'
  | 'toolCallDisplay'
  | 'showToolResults'
  | 'groupToolCalls'
  | 'showEditDiffs'
  | 'editDiffDisplay'
  | 'showRunReceipt'
  | 'showToolAttachments'
  | 'hideSubagentOutput'
  | 'showCacheNotices'
  | 'showFullShellOutput'
  | 'showCompactionSummary'
```

Source: [src/chat/onboarding/types.ts:265](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L265)

### `TranscriptPresetSettings`

Type.

The values of every [`TranscriptPresetKey`](https://zidane.si/docs/reference/chat-pure.md#TranscriptPresetKey).

```ts
type TranscriptPresetSettings = Pick<Settings, TranscriptPresetKey>
```

Source: [src/chat/onboarding/types.ts:283](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/types.ts#L283)

### `TutorialTopic`

Type.

What a tutorial explains.

```ts
type TutorialTopic =
  | 'connectors'
  | 'skills'
  | 'mcp'
  | 'instructions'
  | 'extensions'
  | 'environments'
  | 'files'
  | 'accounts'
  | 'hosts'
  | 'secrets'
```

Source: [src/chat/onboarding/tutorials.ts:10](https://github.com/Tahul/zidane/blob/main/src/chat/onboarding/tutorials.ts#L10)

### `UpdateState`

Type.

`ready`: auto-update is off and *Check now* downloaded and verified `latest`;
`server.update.install` installs it.

```ts
type UpdateState =
  | 'idle'
  | 'checking'
  | 'downloading'
  | 'ready'
  | 'waiting'
  | 'installing'
  | 'error'
```

Source: [src/chat/server-update.ts:7](https://github.com/Tahul/zidane/blob/main/src/chat/server-update.ts#L7)

### `UsageTone`

Type.

Severity tone for a usage percent. `error` ≥ 85, `warn` ≥ 60, else `ok`.
Surfaces map tones to their own palette.

```ts
type UsageTone = 'ok' | 'warn' | 'error'
```

Source: [src/chat/provider-usage-format.ts:185](https://github.com/Tahul/zidane/blob/main/src/chat/provider-usage-format.ts#L185)

### `ViewQueryResult`

Type.

What [`viewQuery`](https://zidane.si/docs/reference/chat-pure.md#viewQuery) returns: the query, or the problems that made it invalid.

```ts
type ViewQueryResult =
  | { issues?: undefined; query: SessionQuery }
  | { issues: SessionQueryIssue[]; query?: undefined }
```

Source: [src/chat/session-query/view.ts:46](https://github.com/Tahul/zidane/blob/main/src/chat/session-query/view.ts#L46)

### `VisibleAuthRow`

Type.

One row in the flattened Authentication list. Two kinds:

- `'provider'` — provider header with label, configured badge, and (when
  expandable) the chevron. Always present.
- `'source'`   — one credential source belonging to the provider above.
  Present only while that provider is expanded.

```ts
type VisibleAuthRow =
  | { expandable: boolean; kind: 'provider'; provider: ProviderAuth }
  | { kind: 'source'; method: AuthMethod; providerKey: string }
```

Source: [src/chat/auth-rows.ts:30](https://github.com/Tahul/zidane/blob/main/src/chat/auth-rows.ts#L30)

## Re-exports

These names are documented on the entry point that owns them.

- [zidane/extensions](https://zidane.si/docs/reference/extensions.md): [`ARTIFACT_BADGES_MAX`](https://zidane.si/docs/reference/extensions.md#ARTIFACT_BADGES_MAX), [`artifactBadgeTarget`](https://zidane.si/docs/reference/extensions.md#artifactBadgeTarget), [`BadgeAction`](https://zidane.si/docs/reference/extensions.md#BadgeActionSpec), [`BadgeActionEffect`](https://zidane.si/docs/reference/extensions.md#BadgeActionEffect), [`BadgeMenuItem`](https://zidane.si/docs/reference/extensions.md#BadgeMenuItem), [`badgePromptText`](https://zidane.si/docs/reference/extensions.md#badgePromptText), [`BadgeTarget`](https://zidane.si/docs/reference/extensions.md#BadgeTarget), [`BadgeTargetKind`](https://zidane.si/docs/reference/extensions.md#BadgeTargetKind), [`builtinBadgeActions`](https://zidane.si/docs/reference/extensions.md#builtinBadgeActions), [`builtinBadgeEffect`](https://zidane.si/docs/reference/extensions.md#builtinBadgeEffect), [`ExtensionArtifactRowFact`](https://zidane.si/docs/reference/extensions.md#ExtensionArtifactRowFact), [`ExtensionBadgeColor`](https://zidane.si/docs/reference/extensions.md#ExtensionBadgeColor), [`ExtensionBadgeIcon`](https://zidane.si/docs/reference/extensions.md#ExtensionBadgeIcon), [`ExtensionBadgeTone`](https://zidane.si/docs/reference/extensions.md#ExtensionBadgeTone), [`ExtensionInstallOrigin`](https://zidane.si/docs/reference/extensions.md#ExtensionInstallOrigin), [`ExtensionPaletteProviderEntry`](https://zidane.si/docs/reference/extensions.md#ExtensionPaletteProviderEntry), [`ExtensionPanel`](https://zidane.si/docs/reference/extensions.md#ExtensionPanel), [`ExtensionPanelEntry`](https://zidane.si/docs/reference/extensions.md#ExtensionPanelEntry), [`ExtensionPanelScope`](https://zidane.si/docs/reference/extensions.md#ExtensionPanelScope), [`ExtensionReferenceCard`](https://zidane.si/docs/reference/extensions.md#ExtensionReferenceCard), [`ExtensionReferenceCardFact`](https://zidane.si/docs/reference/extensions.md#ExtensionReferenceCardFact), [`ExtensionReferenceSurface`](https://zidane.si/docs/reference/extensions.md#ExtensionReferenceSurface), [`ExtensionReferenceView`](https://zidane.si/docs/reference/extensions.md#ExtensionReferenceView), [`ExtensionSessionBadge`](https://zidane.si/docs/reference/extensions.md#ExtensionSessionBadge), [`ExtensionSessionBadgeCardRow`](https://zidane.si/docs/reference/extensions.md#ExtensionSessionBadgeCardRow), [`ExtensionSettingsSearchEntry`](https://zidane.si/docs/reference/extensions.md#SettingsSearchEntry), [`findReferences`](https://zidane.si/docs/reference/extensions.md#findReferences), [`GITHUB_ISSUE_PROVIDER_ID`](https://zidane.si/docs/reference/extensions.md#GITHUB_ISSUE_PROVIDER_ID), [`GITHUB_PULL_PROVIDER_ID`](https://zidane.si/docs/reference/extensions.md#GITHUB_PULL_PROVIDER_ID), [`githubPullUrl`](https://zidane.si/docs/reference/extensions.md#githubPullUrl), [`githubRefKey`](https://zidane.si/docs/reference/extensions.md#githubRefKey), [`isBadgeColor`](https://zidane.si/docs/reference/extensions.md#isBadgeColor), [`isExtensionPanelScope`](https://zidane.si/docs/reference/extensions.md#isExtensionPanelScope), [`isPanelSurface`](https://zidane.si/docs/reference/extensions.md#isPanelSurface), [`mergeBadgeMenu`](https://zidane.si/docs/reference/extensions.md#mergeBadgeMenu), [`normalizePanelContent`](https://zidane.si/docs/reference/extensions.md#normalizePanelContent), [`normalizePanelHomeLayout`](https://zidane.si/docs/reference/extensions.md#normalizePanelHomeLayout), [`normalizePanelLoadContext`](https://zidane.si/docs/reference/extensions.md#normalizePanelLoadContext), [`PANEL_CONTENT_LIMITS`](https://zidane.si/docs/reference/extensions.md#PANEL_CONTENT_LIMITS), [`PanelAction`](https://zidane.si/docs/reference/extensions.md#PanelAction), [`panelBadgeText`](https://zidane.si/docs/reference/extensions.md#panelBadgeText), [`PanelBarsItem`](https://zidane.si/docs/reference/extensions.md#PanelBarsItem), [`PanelBarsPoint`](https://zidane.si/docs/reference/extensions.md#PanelBarsPoint), [`PanelBarsSeries`](https://zidane.si/docs/reference/extensions.md#PanelBarsSeries), [`PanelContent`](https://zidane.si/docs/reference/extensions.md#PanelContent), [`PanelControl`](https://zidane.si/docs/reference/extensions.md#PanelControl), [`PanelControlOption`](https://zidane.si/docs/reference/extensions.md#PanelControlOption), [`PanelCustomItem`](https://zidane.si/docs/reference/extensions.md#PanelCustomItem), [`PanelFocus`](https://zidane.si/docs/reference/extensions.md#PanelFocus), [`PanelHeatmapDay`](https://zidane.si/docs/reference/extensions.md#PanelHeatmapDay), [`PanelHeatmapItem`](https://zidane.si/docs/reference/extensions.md#PanelHeatmapItem), [`PanelHomeLayout`](https://zidane.si/docs/reference/extensions.md#PanelHomeLayout), [`PanelIcon`](https://zidane.si/docs/reference/extensions.md#PanelIcon), [`PanelItem`](https://zidane.si/docs/reference/extensions.md#PanelContentItem), [`PanelKeyValueItem`](https://zidane.si/docs/reference/extensions.md#PanelKeyValueItem), [`PanelKeyValueRow`](https://zidane.si/docs/reference/extensions.md#PanelKeyValueRow), [`PanelLoadContext`](https://zidane.si/docs/reference/extensions.md#PanelLoadContext), [`PanelLoadContextInput`](https://zidane.si/docs/reference/extensions.md#PanelLoadContextInput), [`PanelLoadScope`](https://zidane.si/docs/reference/extensions.md#PanelLoadScope), [`PanelMarkdownItem`](https://zidane.si/docs/reference/extensions.md#PanelMarkdownItem), [`PanelMore`](https://zidane.si/docs/reference/extensions.md#PanelMore), [`panelOnSurface`](https://zidane.si/docs/reference/extensions.md#panelOnSurface), [`PanelRowAction`](https://zidane.si/docs/reference/extensions.md#PanelRowAction), [`PanelRowItem`](https://zidane.si/docs/reference/extensions.md#PanelRowItem), [`PanelSearch`](https://zidane.si/docs/reference/extensions.md#PanelSearch), [`PanelSection`](https://zidane.si/docs/reference/extensions.md#PanelSection), [`panelShowsIn`](https://zidane.si/docs/reference/extensions.md#panelShowsIn), [`PanelStartSession`](https://zidane.si/docs/reference/extensions.md#PanelStartSession), [`PanelStat`](https://zidane.si/docs/reference/extensions.md#PanelStat), [`PanelStatsItem`](https://zidane.si/docs/reference/extensions.md#PanelStatsItem), [`PanelSurface`](https://zidane.si/docs/reference/extensions.md#PanelSurface), [`panelSurfaces`](https://zidane.si/docs/reference/extensions.md#panelSurfaces), [`PanelView`](https://zidane.si/docs/reference/extensions.md#PanelView), [`panelViewValue`](https://zidane.si/docs/reference/extensions.md#panelViewValue), [`panelViewValues`](https://zidane.si/docs/reference/extensions.md#panelViewValues), [`ReferenceMatch`](https://zidane.si/docs/reference/extensions.md#ReferenceMatch), [`ReferenceProviderWire`](https://zidane.si/docs/reference/extensions.md#ReferenceProviderWire), [`resolvePanelLoadContext`](https://zidane.si/docs/reference/extensions.md#resolvePanelLoadContext), [`SessionBadgeEntry`](https://zidane.si/docs/reference/extensions.md#SessionBadgeEntry), [`sessionBadgeTarget`](https://zidane.si/docs/reference/extensions.md#sessionBadgeTarget), [`settingsSearchIndex`](https://zidane.si/docs/reference/extensions.md#settingsSearchIndex), [`settingsSidebar`](https://zidane.si/docs/reference/extensions.md#settingsSidebar), [`SettingsSidebar`](https://zidane.si/docs/reference/extensions.md#SettingsSidebar), [`SettingsSidebarCategory`](https://zidane.si/docs/reference/extensions.md#SettingsSidebarCategory), [`SettingsSidebarEntry`](https://zidane.si/docs/reference/extensions.md#SettingsSidebarEntry), [`SettingsSidebarExtension`](https://zidane.si/docs/reference/extensions.md#SettingsSidebarExtension)
- [zidane/errors](https://zidane.si/docs/reference/errors.md): [`AuthFailure`](https://zidane.si/docs/reference/errors.md#AuthFailure), [`AuthFailureKind`](https://zidane.si/docs/reference/errors.md#AuthFailureKind)
- [zidane/contexts](https://zidane.si/docs/reference/contexts.md): [`EntryKind`](https://zidane.si/docs/reference/contexts.md#EntryKind), [`EntryPort`](https://zidane.si/docs/reference/contexts.md#EntryPort)
- [zidane/skills](https://zidane.si/docs/reference/skills.md): [`githubAvatarUrl`](https://zidane.si/docs/reference/skills.md#githubAvatarUrl), [`githubPreviewImageUrl`](https://zidane.si/docs/reference/skills.md#githubPreviewImageUrl), [`groupSkillPicks`](https://zidane.si/docs/reference/skills.md#groupSkillPicks), [`RECOMMENDED_SKILL_SOURCES`](https://zidane.si/docs/reference/skills.md#RECOMMENDED_SKILL_SOURCES), [`RecommendedSkillSource`](https://zidane.si/docs/reference/skills.md#RecommendedSkillSource), [`sanitizeSkillName`](https://zidane.si/docs/reference/skills.md#sanitizeSkillName), [`SKILL_CANDIDATE_MAX_DEPTH`](https://zidane.si/docs/reference/skills.md#SKILL_CANDIDATE_MAX_DEPTH), [`skillCandidatesFromPaths`](https://zidane.si/docs/reference/skills.md#skillCandidatesFromPaths), [`skillCategory`](https://zidane.si/docs/reference/skills.md#skillCategory), [`SkillInstallTarget`](https://zidane.si/docs/reference/skills.md#SkillInstallTarget), [`SkillPathCandidate`](https://zidane.si/docs/reference/skills.md#SkillPathCandidate), [`SkillPick`](https://zidane.si/docs/reference/skills.md#SkillPick), [`SkillPickGroup`](https://zidane.si/docs/reference/skills.md#SkillPickGroup), [`skillPickKey`](https://zidane.si/docs/reference/skills.md#skillPickKey), [`skillPickOf`](https://zidane.si/docs/reference/skills.md#skillPickOf), [`SkillSourceInfo`](https://zidane.si/docs/reference/skills.md#SkillSourceInfo), [`SkillSourceListing`](https://zidane.si/docs/reference/skills.md#SkillSourceListing), [`SkillSourceSkill`](https://zidane.si/docs/reference/skills.md#SkillSourceSkill), [`skillTokenWeights`](https://zidane.si/docs/reference/skills.md#skillTokenWeights), [`SkillTokenWeights`](https://zidane.si/docs/reference/skills.md#SkillTokenWeights)
- [zidane](https://zidane.si/docs/reference/index.md): [`LogLevel`](https://zidane.si/docs/reference/index.md#LogLevel), [`LogRecord`](https://zidane.si/docs/reference/index.md#LogRecord), [`Schedule`](https://zidane.si/docs/reference/index.md#Schedule), [`ScheduleAction`](https://zidane.si/docs/reference/index.md#ScheduleAction), [`ScheduleCatchUp`](https://zidane.si/docs/reference/index.md#ScheduleCatchUp), [`ScheduleCreator`](https://zidane.si/docs/reference/index.md#ScheduleCreator), [`ScheduleFire`](https://zidane.si/docs/reference/index.md#ScheduleFire), [`ScheduleFireOutcome`](https://zidane.si/docs/reference/index.md#ScheduleFireOutcome), [`ScheduleInput`](https://zidane.si/docs/reference/index.md#ScheduleInput), [`ScheduleListFilter`](https://zidane.si/docs/reference/index.md#ScheduleListFilter), [`ScheduleNewSession`](https://zidane.si/docs/reference/index.md#ScheduleNewSession), [`SchedulePatch`](https://zidane.si/docs/reference/index.md#SchedulePatch), [`ScheduleTrigger`](https://zidane.si/docs/reference/index.md#ScheduleTrigger)