# zidane-ui/adapters

> Browser-safe ChatHost implementations that connect the chat components to an agent.

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

Use `zidane-ui/adapters` to back the chat components with a real run: `createRunHost`, `createWorkerHost` with `exposeRunHost`, `createSseHost` and `createServerHost`. The protocol constants and codecs are exported for custom transports. [Connecting a host](https://zidane.si/docs/ui-adapters.md) sets each one up and lists their limits.

```ts
import { createRunHost } from 'zidane-ui/adapters'

const host = createRunHost({
  async run({ prompt, emit }) {
    emit({ kind: 'markdown', text: 'Looking ', streaming: true })
    emit({ kind: 'markdown', text: `it up: ${prompt}`, streaming: true })
  },
})
await host.send?.({ sessionId: 's1', prompt: 'hello' })
```

## Functions

### `applyLiveEvent`

Function.

One live event folded into a transcript (`now` stamps arrival on tool rows and thinking lanes).
Generic over the event type so the desktop app's `GuiStreamEvent` lanes fold the same way.

```ts
function applyLiveEvent<E extends TimedEvent = ChatEvent>(
  events: readonly E[],
  event: E,
  now?: number,
  markdown?: MarkdownDeltaOptions,
): E[]
```

**Type parameters**

- `E` (`extends TimedEvent`, default `ChatEvent`)

**Parameters**

- `events` (`readonly E[]`): The transcript so far.
- `event` (`E`): The live event to fold in.
- `now?` (`number`): Epoch milliseconds stamped on tool rows and thinking lanes as their arrival time. Defaults to the current time.
- `markdown?` (`MarkdownDeltaOptions`): How streamed markdown merges (`segmentChars`: where a long message splits). The reducer's default when omitted.

**Returns** `E[]`

Source: [ui/src/chat/headless/streams/live-events.ts:90](https://github.com/Tahul/zidane/blob/main/ui/src/chat/headless/streams/live-events.ts#L90)

### `attachmentsFromPreviews`

Function.

`ChatAttachment` previews → zidane's prompt attachments (base64, no data-URL prefix).

```ts
function attachmentsFromPreviews(
  attachments: readonly ChatAttachment[] | undefined,
): { data: string; mediaType: string; name?: string }[]
```

**Parameters**

- `attachments` (`readonly ChatAttachment[] | undefined`): The previews from a [`SendBody`](https://zidane.si/docs/reference/ui-adapters.md#SendBody). Previews without a base64 `data:` URL are dropped.

**Returns** `{ data: string; mediaType: string; name?: string }[]`

Source: [ui/src/adapters/sse-protocol.ts:110](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L110)

### `closeThinkingSegment`

Function.

zidane's live event rule, re-exported for the adapters' public entry. It
lives with the session stream store (`chat/headless/streams/`), which
folds every transcript with it.

```ts
function closeThinkingSegment<E extends TimedEvent>(
  events: E[],
  owner?: string,
  now?: number,
): E[]
```

**Type parameters**

- `E` (`extends TimedEvent`)

**Parameters**

- `events` (`E[]`): The transcript so far.
- `owner?` (`string`): The owner whose segment closes; the tail's when omitted.
- `now?` (`number`): Epoch milliseconds the segment closes at. Defaults to the current time.

**Returns** `E[]`

Source: [ui/src/chat/headless/streams/live-events.ts:53](https://github.com/Tahul/zidane/blob/main/ui/src/chat/headless/streams/live-events.ts#L53)

### `createBrowserAppearanceHost`

Function.

Creates an [`AppearanceHost`](https://zidane.si/docs/reference/ui-appearance-headless.md#AppearanceHost) over the browser's storage: `prefs` and `boot`.

```ts
function createBrowserAppearanceHost(
  options?: BrowserAppearanceHostOptions,
): AppearanceHost
```

**Parameters**

- `options?` (`BrowserAppearanceHostOptions`, default `{}`): The storage, the keys, how to check code theme ids (`codeThemeTypeOf` from `zidane-ui/appearance`).

**Returns** `AppearanceHost`

Source: [ui/src/adapters/browser-appearance-host.ts:40](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/browser-appearance-host.ts#L40)

### `createBrowserKeybindingsHost`

Function.

Creates a [`KeybindingsHost`](https://zidane.si/docs/reference/ui-keybindings-headless.md#KeybindingsHost) over the browser's storage: the overrides and `save`.

```ts
function createBrowserKeybindingsHost(
  options?: BrowserKeybindingsHostOptions,
): KeybindingsHost
```

**Parameters**

- `options?` (`BrowserKeybindingsHostOptions`, default `{}`): The storage and the key.

**Returns** `KeybindingsHost`

Source: [ui/src/adapters/browser-keybindings-host.ts:31](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/browser-keybindings-host.ts#L31)

### `createBrowserWorkspaceHost`

Function.

Creates the web app's [`WorkspaceHost`](https://zidane.si/docs/reference/ui-workspace-headless.md#WorkspaceHost): layouts in browser storage, and the server's extension panels.

```ts
function createBrowserWorkspaceHost(
  options?: BrowserWorkspaceHostOptions,
): WorkspaceHost
```

**Parameters**

- `options?` (`BrowserWorkspaceHostOptions`, default `{}`): The storage, its key, what an unknown scope reads, how other tabs' writes arrive and the server.

**Returns** `WorkspaceHost`

Source: [ui/src/adapters/browser-workspace-host.ts:86](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/browser-workspace-host.ts#L86)

### `createLiveState`

Function.

Creates the stores a `ChatHost` exposes: the session list, per-session transcripts, and pending interactions.

```ts
function createLiveState(options?: LiveStateOptions): LiveState
```

**Parameters**

- `options?` (`LiveStateOptions`, default `{}`): The initial sessions and the transcript open and close hooks.

**Returns** `LiveState`

Source: [ui/src/adapters/live.ts:97](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/live.ts#L97)

### `createRunHost`

Function.

Creates a [`ChatHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatHost) around a run function. Sessions, transcripts, and pending interactions live in memory; the app supplies the agent through `run`.

```ts
function createRunHost(options: RunHostOptions): RunHost
```

**Parameters**

- `options` (`RunHostOptions`): The `run` function and optional initial sessions, transcripts, and models.

**Returns** `RunHost`

Source: [ui/src/adapters/run-host.ts:89](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/run-host.ts#L89)

### `createServerApprovalsHost`

Function.

Creates an [`ApprovalsHost`](https://zidane.si/docs/reference/ui-approvals-headless.md#ApprovalsHost) on a running zidane-server.

```ts
function createServerApprovalsHost(options: ServerApprovalsHostOptions): ApprovalsHost
```

**Parameters**

- `options` (`ServerApprovalsHostOptions`): The shared client, whether the token may answer approvals, and where background errors go.

**Returns** `ApprovalsHost`

Source: [ui/src/adapters/server-approvals-host.ts:41](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-approvals-host.ts#L41)

### `createServerClient`

Function.

The zidane-server client the server adapter speaks through: zidane's own browser client
(`zidane/ipc/browser`), re-exported so an app reaches it from the kit. Share one client
between the chat host and the other areas' hosts on the same server.

```ts
function createServerClient(options: ServerClientOptions): ServerClient
```

**Parameters**

- `options` (`ServerClientOptions`): The server's `url`, the `token`, and optional transport and retry settings.

**Returns** `ServerClient`: The client, connecting.

Source: [dist/ipc/browser.d.ts:245](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L245)

### `createServerComposerHost`

Function.

Creates a [`ComposerHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ComposerHost) over a zidane-server client.

```ts
function createServerComposerHost(
  options: ServerComposerHostOptions,
): ServerComposerHost
```

**Parameters**

- `options` (`ServerComposerHostOptions`): The client to speak through.

**Returns** `ServerComposerHost`

Source: [ui/src/adapters/server-composer-host.ts:194](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-composer-host.ts#L194)

### `createServerExtensionModuleLoader`

Function.

Creates a loader of extension `ui.tsx` modules from zidane-server: each bundle where the folder's
listing says, by its hash, linked against `modules`. A bundle URL the server no longer knows (it
restarted since the listing) is looked up again in a fresh listing, once.

```ts
function createServerExtensionModuleLoader(
  options: ServerExtensionModuleLoaderOptions,
): ServerExtensionModuleLoader
```

**Parameters**

- `options` (`ServerExtensionModuleLoaderOptions`): The server's origin and token, where bundles are, the host modules.

**Returns** `ServerExtensionModuleLoader`

Source: [ui/src/adapters/extension-modules.ts:228](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L228)

### `createServerExtensionsHost`

Function.

Creates an [`ExtensionsHost`](https://zidane.si/docs/reference/ui-extensions-headless.md#ExtensionsHost) over a zidane-server client.

```ts
function createServerExtensionsHost(
  options: ServerExtensionsHostOptions,
): ServerExtensionsHost
```

**Parameters**

- `options` (`ServerExtensionsHostOptions`): The client, the folder, the sign-in step handler, the error sink and where assets are.

**Returns** `ServerExtensionsHost`

Source: [ui/src/adapters/server-extensions-host.ts:413](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L413)

### `createServerFilesHost`

Function.

Creates a [`FilesHost`](https://zidane.si/docs/reference/ui-files-headless.md#FilesHost) on a running zidane-server.

```ts
function createServerFilesHost(options: ServerFilesHostOptions): FilesHost
```

**Parameters**

- `options` (`ServerFilesHostOptions`): The shared client, the folder → session lookup and where editor preferences live.

**Returns** `FilesHost`

Source: [ui/src/adapters/server-files-host.ts:166](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-files-host.ts#L166)

### `createServerGitHost`

Function.

Creates a [`GitHost`](https://zidane.si/docs/reference/ui-git-headless.md#GitHost) over a zidane-server client.

```ts
function createServerGitHost(options: ServerGitHostOptions): GitHost
```

**Parameters**

- `options` (`ServerGitHostOptions`): The client.

**Returns** `GitHost`

Source: [ui/src/adapters/server-git-host.ts:129](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-git-host.ts#L129)

### `createServerHost`

Function.

Creates a [`ChatHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatHost) on a running zidane-server. Pass a shared `client`, or the `url`
and `token` (and client options) to create one.

```ts
function createServerHost(options: ServerHostOptions): ServerHost
```

**Parameters**

- `options` (`ServerHostOptions`): The client, or what to create one with, plus the working directory for new sessions.

**Returns** `ServerHost`

Source: [ui/src/adapters/server-host.ts:152](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-host.ts#L152)

### `createServerMachinesHost`

Function.

Creates a [`MachinesHost`](https://zidane.si/docs/reference/ui-machines-headless.md#MachinesHost) on a running zidane-server.

```ts
function createServerMachinesHost(
  options: ServerMachinesHostOptions,
): ServerMachinesHost
```

**Parameters**

- `options` (`ServerMachinesHostOptions`): The shared client and the server's fallback name.

**Returns** `ServerMachinesHost`

Source: [ui/src/adapters/server-machines-host.ts:89](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-machines-host.ts#L89)

### `createServerOnboardingHost`

Function.

Creates an [`OnboardingHost`](https://zidane.si/docs/reference/ui-onboarding-headless.md#OnboardingHost) on a running zidane-server.

```ts
function createServerOnboardingHost(
  options: ServerOnboardingHostOptions,
): ServerOnboardingHost
```

**Parameters**

- `options` (`ServerOnboardingHostOptions`): The shared client, the run, whether the token may configure the server, the page's look, and where background errors go.

**Returns** `ServerOnboardingHost`

Source: [ui/src/adapters/server-onboarding-host.ts:137](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-onboarding-host.ts#L137)

### `createServerPaletteHost`

Function.

Creates a [`PaletteHost`](https://zidane.si/docs/reference/ui-palette-headless.md#PaletteHost) over a zidane-server client.

```ts
function createServerPaletteHost(options: ServerPaletteHostOptions): ServerPaletteHost
```

**Parameters**

- `options` (`ServerPaletteHostOptions`): The client, recents storage and error sink.

**Returns** `ServerPaletteHost`

Source: [ui/src/adapters/server-palette-host.ts:76](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-palette-host.ts#L76)

### `createServerSessionHost`

Function.

Creates a [`SessionHost`](https://zidane.si/docs/reference/ui-session-headless.md#SessionHost) over a zidane-server client.

```ts
function createServerSessionHost(options: ServerSessionHostOptions): ServerSessionHost
```

**Parameters**

- `options` (`ServerSessionHostOptions`): The client to speak through.

**Returns** `ServerSessionHost`

Source: [ui/src/adapters/server-session-host.ts:75](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-session-host.ts#L75)

### `createServerSettingsHost`

Function.

Creates a [`SettingsHost`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsHost) on a running zidane-server.

```ts
function createServerSettingsHost(
  options: ServerSettingsHostOptions,
): ServerSettingsHost
```

**Parameters**

- `options` (`ServerSettingsHostOptions`): The shared client.

**Returns** `ServerSettingsHost`

Source: [ui/src/adapters/server-settings-host.ts:60](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-settings-host.ts#L60)

### `createServerSidebarHost`

Function.

Creates a [`SidebarHost`](https://zidane.si/docs/reference/ui-chat-headless.md#SidebarHost) over a zidane-server client.

```ts
function createServerSidebarHost(options: ServerSidebarHostOptions): SidebarHost
```

**Parameters**

- `options` (`ServerSidebarHostOptions`): The client to speak through.

**Returns** `SidebarHost`

Source: [ui/src/adapters/server-sidebar-host.ts:31](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-sidebar-host.ts#L31)

### `createServerTerminalHost`

Function.

Creates a [`TerminalHost`](https://zidane.si/docs/reference/ui-terminal-headless.md#TerminalHost) on a running zidane-server.

```ts
function createServerTerminalHost(options: ServerTerminalHostOptions): TerminalHost
```

**Parameters**

- `options` (`ServerTerminalHostOptions`): The shared client.

**Returns** `TerminalHost`

Source: [ui/src/adapters/server-terminal-host.ts:36](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-terminal-host.ts#L36)

### `createServerWebviewSources`

Function.

Creates the webview URL source over zidane-server: a `file` source is minted once per folder
(`POST /zidane/extensions/webview?cwd=&id=`, with the token) into a URL under an unguessable ticket,
served sandboxed with no network: the page talks to its extension only through the RPC bridge.

```ts
function createServerWebviewSources(
  options: ServerWebviewSourcesOptions,
): ServerWebviewSources
```

**Parameters**

- `options` (`ServerWebviewSourcesOptions`): The server's origin and token, the folder.

**Returns** `ServerWebviewSources`

Source: [ui/src/adapters/extension-modules.ts:320](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L320)

### `createSseHost`

Function.

Creates a [`ChatHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatHost) over HTTP and server-sent events, talking to a handler from `createSseHandler`. Actions are POSTs and each watched transcript is one streaming GET that resumes after a drop.

```ts
function createSseHost(options: SseHostOptions): SseHost
```

**Parameters**

- `options` (`SseHostOptions`): The handler's `baseUrl` plus optional `fetch`, `headers`, reconnect delay, and error callback.

**Returns** `SseHost`

Source: [ui/src/adapters/sse-host.ts:42](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-host.ts#L42)

### `createSseParser`

Function.

Creates an incremental `text/event-stream` parser that follows the WHATWG interpretation. Used instead of `EventSource` so requests can carry headers.

```ts
function createSseParser(
  onRecord: (record: SseRecord) => void,
  lastId?: string,
): SseParser
```

**Parameters**

- `onRecord` (`(record: SseRecord) => void`): Called with each dispatched record.
- `lastId?` (`string`, default `''`): The last event ID to start from, for a resumed stream. Defaults to an empty string.

**Returns** `SseParser`

Source: [ui/src/adapters/sse-parser.ts:32](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-parser.ts#L32)

### `createStreamPacer`

Function.

Creates a pacer that feeds `apply` (a run's `emit`, a live state's `apply`).

```ts
function createStreamPacer(
  apply: (event: ChatEvent) => void,
  options?: StreamPacerOptions,
): StreamPacer
```

**Parameters**

- `apply` (`(event: ChatEvent) => void`): Folds one event into the transcript.
- `options?` (`StreamPacerOptions`, default `{}`): [`StreamPacerOptions`](https://zidane.si/docs/reference/ui-adapters.md#StreamPacerOptions).

**Returns** `StreamPacer`

Source: [ui/src/adapters/stream-pacer.ts:45](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/stream-pacer.ts#L45)

### `createWorkerHost`

Function.

Creates a [`ChatHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatHost) in the page whose runs execute in a Web Worker. Sessions, transcripts, and interactions stay in the page; the worker runs the agent through [`exposeRunHost`](https://zidane.si/docs/reference/ui-adapters.md#exposeRunHost).

```ts
function createWorkerHost(
  worker: MessageEndpoint,
  options?: WorkerHostOptions,
): ChatHost & { dispose(): void }
```

**Parameters**

- `worker` (`MessageEndpoint`): The worker, or any object that posts and receives messages like one.
- `options?` (`WorkerHostOptions`, default `{}`): Initial sessions, transcripts, models, and an optional run id generator.

**Returns** `ChatHost & { dispose(): void }`

Source: [ui/src/adapters/worker-host.ts:38](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-host.ts#L38)

### `decodeFromWorker`

Function.

Checks a message the page received from the worker. Returns the [`FromWorker`](https://zidane.si/docs/reference/ui-adapters.md#FromWorker) message, `'version'` when it speaks another protocol version, or `null` when it is not a protocol message.

```ts
function decodeFromWorker(data: unknown): 'version' | FromWorker | null
```

**Parameters**

- `data` (`unknown`): The `data` of a received message.

**Returns** `'version' | FromWorker | null`

Source: [ui/src/adapters/worker-protocol.ts:94](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-protocol.ts#L94)

### `decodeToWorker`

Function.

A protocol message for the worker, or why not: `'version'` (another protocol version), `null` (not ours).

```ts
function decodeToWorker(data: unknown): 'version' | ToWorker | null
```

**Parameters**

- `data` (`unknown`): The `data` of a received message.

**Returns** `'version' | ToWorker | null`

Source: [ui/src/adapters/worker-protocol.ts:84](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-protocol.ts#L84)

### `encodeSseRecord`

Function.

One SSE record on the wire (`data` is single-line JSON, so one `data:` field).

```ts
function encodeSseRecord(id: string | null, record: StreamRecord): string
```

**Parameters**

- `id` (`string | null`): The record id sent as the SSE `id` field. `null` omits it.
- `record` (`StreamRecord`): The record to encode.

**Returns** `string`

Source: [ui/src/adapters/sse-protocol.ts:101](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L101)

### `exposeRunHost`

Function.

Serve `run` to the page over `scope` (default: the worker's global scope).
Returns a function that stops listening.

```ts
function exposeRunHost(run: RunFn, scope?: MessageEndpoint): () => void
```

**Parameters**

- `run` (`RunFn`): The function that runs the agent for each prompt.
- `scope?` (`MessageEndpoint`): The endpoint to listen on and post to. Defaults to the worker's global scope.

**Returns** `() => void`

Source: [ui/src/adapters/worker-host.ts:125](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-host.ts#L125)

### `finishLive`

Function.

A run ended: close the blocks still marked streaming and every thinking lane still open.

```ts
function finishLive<E extends TimedEvent = ChatEvent>(
  events: readonly E[],
  now?: number,
): E[]
```

**Type parameters**

- `E` (`extends TimedEvent`, default `ChatEvent`)

**Parameters**

- `events` (`readonly E[]`): The transcript so far.
- `now?` (`number`): Epoch milliseconds the open lanes close at. Defaults to the current time.

**Returns** `E[]`

Source: [ui/src/chat/headless/streams/live-events.ts:120](https://github.com/Tahul/zidane/blob/main/ui/src/chat/headless/streams/live-events.ts#L120)

### `formatCursor`

Function.

Builds a stream cursor, the `Last-Event-ID` value that names a record.

```ts
function formatCursor(epoch: string, seq: number): string
```

**Parameters**

- `epoch` (`string`): Id of the server process that numbered the records.
- `seq` (`number`): The record's sequence number within the session, from 1.

**Returns** `string`

Source: [ui/src/adapters/sse-protocol.ts:78](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L78)

### `installExtensionHostModules`

Function.

Puts `modules` in the host module map linked bundles read (merged over what is there).

```ts
function installExtensionHostModules(
  modules: ExtensionHostModules,
  target?: object,
): void
```

**Parameters**

- `modules` (`ExtensionHostModules`): Host modules by specifier.
- `target?` (`object`, default `globalThis`): The global object. Default `globalThis`.

Source: [ui/src/adapters/extension-modules.ts:156](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L156)

### `linkExtensionModule`

Function.

Rewrites a bundle's imports of host modules into reads of the host module map, so the code runs
as a module with no imports. A bare import the map has no module for fails, every one named.
Relative and URL imports are left alone (a self-contained bundle has none).

```ts
function linkExtensionModule(
  code: string,
  provided: (specifier: string) => boolean,
): LinkedExtensionModule
```

**Parameters**

- `code` (`string`): One ESM module (zidane's `compileUiEntry` output).
- `provided` (`(specifier: string) => boolean`): Whether the app provides a specifier.

**Returns** `LinkedExtensionModule`: The linked code and the host modules it reads.

Source: [ui/src/adapters/extension-modules.ts:94](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L94)

### `parseCursor`

Function.

Parses a cursor from [`formatCursor`](https://zidane.si/docs/reference/ui-adapters.md#formatCursor). Returns `null` for a missing or malformed cursor.

```ts
function parseCursor(
  cursor: string | null | undefined,
): { epoch: string; seq: number } | null
```

**Parameters**

- `cursor` (`string | null | undefined`): The cursor string, for example a `Last-Event-ID` header value.

**Returns** `{ epoch: string; seq: number } | null`

Source: [ui/src/adapters/sse-protocol.ts:87](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L87)

### `toChatModelProviders`

Function.

Converts the server's model list into the model picker's providers.

```ts
function toChatModelProviders(
  providers: readonly HostModelProvider[],
): ChatModelProvider[]
```

**Parameters**

- `providers` (`readonly HostModelProvider[]`): `models.list`'s providers.

**Returns** `ChatModelProvider[]`

Source: [ui/src/adapters/server-host.ts:124](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-host.ts#L124)

### `toChatSession`

Function.

Converts a zidane server's session row into a [`ChatSession`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatSession). The project root becomes the group, the main session is pinned, and the model id gets its provider prefix.

```ts
function toChatSession(row: SessionRow): ChatSession
```

**Parameters**

- `row` (`SessionRow`): The session row from the server.

**Returns** `ChatSession`

Source: [ui/src/adapters/server-host.ts:84](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-host.ts#L84)

### `toSidebarListSession`

Function.

Converts a zidane server's session row into a [`SidebarListSession`](https://zidane.si/docs/reference/ui-chat-headless.md#SidebarListSession): the chat session plus its folder and space.

```ts
function toSidebarListSession(row: SessionRow): SidebarListSession
```

**Parameters**

- `row` (`SessionRow`): The session row from the server.

**Returns** `SidebarListSession`

Source: [ui/src/adapters/server-host.ts:105](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-host.ts#L105)

## Classes

### `ExtensionModuleLinkError`

Class.

A bundle that imports something the app does not provide.

```ts
class ExtensionModuleLinkError extends Error
```

**Constructor**

```ts
new ExtensionModuleLinkError(specifiers: readonly string[])
```

**Parameters**

- `specifiers` (`readonly string[]`): The specifiers the app has no module for.

**Returns** `ExtensionModuleLinkError`

**Properties**

- `specifiers` (`readonly string[]`, readonly): The specifiers the app has no module for.

Source: [ui/src/adapters/extension-modules.ts:52](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L52)

### `ExtensionModuleLoadError`

Class.

A bundle that could not be loaded: not listed, did not bundle, or the server refused.

```ts
class ExtensionModuleLoadError extends Error
```

**Constructor**

```ts
new ExtensionModuleLoadError(extensionId: string, message: string)
```

**Parameters**

- `extensionId` (`string`): The extension.
- `message` (`string`): What went wrong.

**Returns** `ExtensionModuleLoadError`

**Properties**

- `extensionId` (`string`, readonly): The extension.

Source: [ui/src/adapters/extension-modules.ts:174](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L174)

### `ServerCallError`

Class.

A call the server answered with an error: its JSON-RPC `code` and `data`.

```ts
class ServerCallError extends Error
```

**Constructor**

```ts
new ServerCallError(message: string, code: number, data?: unknown)
```

**Parameters**

- `message` (`string`): The server's message.
- `code` (`number`): The JSON-RPC error code.
- `data?` (`unknown`): The error's data.

**Returns** `ServerCallError`

**Properties**

- `code` (`number`, readonly): The JSON-RPC error code (`IpcErrorCode` names zidane's own).
- `data?` (`unknown`, readonly): The error's data, when it had some (a `Forbidden` refusal's `required` scope).

Source: [dist/ipc/browser.d.ts:178](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L178)

### `ServerConnectionError`

Class.

A call that couldn't be answered: the connection dropped, or the client was refused or closed.

```ts
class ServerConnectionError extends Error
```

**Constructor**

```ts
new ServerConnectionError(message: string, state: ServerClientState)
```

**Parameters**

- `message` (`string`): What happened.
- `state` (`ServerClientState`): The client's state when the call failed.

**Returns** `ServerConnectionError`

**Properties**

- `state` (`ServerClientState`, readonly): The client's state when the call failed: `refused` names why, for good.

Source: [dist/ipc/browser.d.ts:191](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L191)

## Constants

### `EXTENSION_HOST_MODULES_GLOBAL`

Constant.

The global the linked bundles read host modules from.

```ts
const EXTENSION_HOST_MODULES_GLOBAL = '__zidaneExtensionHostModules__'
```

Source: [ui/src/adapters/extension-modules.ts:27](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L27)

### `SERVER_AUTH_CHECK_PATH`

Constant.

The path of a zidane-server's auth check, relative to its WebSocket URL's origin (same as `SERVER_AUTH_PATH`).

```ts
const SERVER_AUTH_CHECK_PATH = "/zidane/auth"
```

Source: [dist/ipc/browser.d.ts:119](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L119)

### `SERVER_MACHINES_HOST_ID`

Constant.

The id the server goes by until its handshake names it (`hello.hostId`).

```ts
const SERVER_MACHINES_HOST_ID = 'server'
```

Source: [ui/src/adapters/server-machines-host.ts:72](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-machines-host.ts#L72)

### `SSE_PROTOCOL_HEADER`

Constant.

Name of the response header that carries the protocol version.

```ts
const SSE_PROTOCOL_HEADER = 'X-Zidane-Chat-Protocol'
```

Source: [ui/src/adapters/sse-protocol.ts:34](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L34)

### `SSE_PROTOCOL_VERSION`

Constant.

Version of the HTTP and server-sent-events protocol between [`createSseHost`](https://zidane.si/docs/reference/ui-adapters.md#createSseHost) and `createSseHandler`.

```ts
const SSE_PROTOCOL_VERSION = 1
```

Source: [ui/src/adapters/sse-protocol.ts:32](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L32)

### `WORKER_PROTOCOL_VERSION`

Constant.

Version of the postMessage protocol between [`createWorkerHost`](https://zidane.si/docs/reference/ui-adapters.md#createWorkerHost) and [`exposeRunHost`](https://zidane.si/docs/reference/ui-adapters.md#exposeRunHost). A side drops messages of another version.

```ts
const WORKER_PROTOCOL_VERSION = 1
```

Source: [ui/src/adapters/worker-protocol.ts:26](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-protocol.ts#L26)

## Interfaces

### `BrowserAppearanceHostOptions`

Interface.

Options of [`createBrowserAppearanceHost`](https://zidane.si/docs/reference/ui-adapters.md#createBrowserAppearanceHost).

```ts
interface BrowserAppearanceHostOptions extends ParseAppearanceOptions
```

**Properties**

- `bootKey?` (`string`): The snapshot key. Default: `zg:appearance:boot:v1`.
- `codeThemeType?` (`(id: string) => 'dark' | 'light' | undefined`, from `ParseAppearanceOptions`): The appearance a code theme id is made for, `undefined` when unknown
  (`codeThemeTypeOf` from `zidane-ui/appearance`). A stored pick of the
  wrong type, or unknown, reads as `'auto'`. Absent: any non-empty id is kept.
- `key?` (`string`): The preferences key. Default: `zg:appearance:v1`.
- `storage?` (`AppearanceStorage`): Where the preferences and the snapshot live. Default: `localStorage` (a page without one keeps nothing).
- `watch?` (`(key: string, onChange: () => void) => () => void`): Calls `onChange` when another tab changed the preferences. Default: the `storage` event.

Source: [ui/src/adapters/browser-appearance-host.ts:18](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/browser-appearance-host.ts#L18)

### `BrowserKeybindingsHostOptions`

Interface.

Options of [`createBrowserKeybindingsHost`](https://zidane.si/docs/reference/ui-adapters.md#createBrowserKeybindingsHost).

```ts
interface BrowserKeybindingsHostOptions
```

**Properties**

- `key?` (`string`): The key. Default: `zg:keybindings:v1`.
- `storage?` (`Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>`): Where the overrides live. Default: `localStorage` (a page without one keeps none).

Source: [ui/src/adapters/browser-keybindings-host.ts:13](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/browser-keybindings-host.ts#L13)

### `BrowserWorkspaceHostOptions`

Interface.

Options for [`createBrowserWorkspaceHost`](https://zidane.si/docs/reference/ui-adapters.md#createBrowserWorkspaceHost).

```ts
interface BrowserWorkspaceHostOptions extends LayoutStoreOptions
```

**Properties**

- `client?` (`ServerClient`): The server whose extension panels it offers. Absent, or a server without `panels.list`: none.
- `initial?` (`(scope: WorkspaceScope) => WorkspaceLayout`, from `LayoutStoreOptions`): What a scope with nothing stored reads. Default: [`EMPTY_WORKSPACE_LAYOUT`](https://zidane.si/docs/reference/ui-workspace-headless.md#EMPTY_WORKSPACE_LAYOUT).
- `key?` (`string`): The storage key. Default: `zidane-ui:workspace:v1`.
- `listenExternal?` (`(onExternalWrite: (key: string | null) => void) => () => void`): Hears another tab's writes. Default: the `storage` event on `window`.
- `storage?` (`LayoutStorage`): Where layouts persist. Default: `localStorage` when there is one, else in memory.

Source: [ui/src/adapters/browser-workspace-host.ts:19](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/browser-workspace-host.ts#L19)

### `ExtensionsClientAnnounce`

Interface.

What the window says about itself (`ui.client.announce`).

```ts
interface ExtensionsClientAnnounce
```

**Properties**

- `active?` (`boolean`): The user just acted in it: it becomes the last active window.
- `viewing?` (`string[]`): Sessions it shows now.

Source: [ui/src/adapters/server-extensions-host.ts:96](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L96)

### `HydrateResponse`

Interface.

Body of `GET /sessions/:id/events`: the transcript so far, plus what a client needs to start streaming.

```ts
interface HydrateResponse
```

**Properties**

- `cursor` (`string`): Pass as `Last-Event-ID` to stream what comes after these events.
- `events` (`ChatEvent[]`): The session's events so far, oldest first.
- `interactions` (`ChatInteraction[]`): Requests from the agent that still wait for an answer.
- `running` (`boolean`): A run is in flight in the session.

Source: [ui/src/adapters/sse-protocol.ts:37](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L37)

### `LinkedExtensionModule`

Interface.

A linked bundle: its code, and the host modules it reads.

```ts
interface LinkedExtensionModule
```

**Properties**

- `code` (`string`): The bundle with its host-module imports rewritten to reads of the shared module map.
- `uses` (`readonly string[]`): The host module specifiers the code reads, each once.

Source: [ui/src/adapters/extension-modules.ts:44](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L44)

### `LiveState`

Interface.

The client half of the live transcript: the stores a `ChatHost` exposes, fed by live events. Shared by every adapter.

```ts
interface LiveState
```

**Properties**

- `allPending` (`Readable<readonly ChatInteraction[]>`): Every session's pending interactions, in arrival order.
- `sessions` (`Writable<readonly ChatSession[]>`): The session list store.
- `addInteraction` (`(sessionId: string, request: InteractionRequest) => void`): Adds a pending request to a session. A request already pending is ignored.
- `apply` (`(sessionId: string, event: ChatEvent, echo?: boolean) => void`): A live event from the agent; `echo` marks the host repeating a prompt (dropped when this client echoed it).
- `echoPrompt` (`(sessionId: string, text: string, attachments?: readonly ChatAttachment[]) => void`): Show the user's prompt at once (with its attachment previews); the host's echo of it is then dropped.
- `hydrate` (`(sessionId: string, events: readonly ChatEvent[], patch?: Partial<TranscriptState>) => void`): Replaces a session's events with a loaded history and marks it hydrated. `patch` sets other transcript state fields, such as `running`.
- `interactionSession` (`(requestId: string) => string | undefined`): The session a pending request belongs to.
- `patchSession` (`(sessionId: string, patch: Partial<ChatSession>) => void`): Merges fields into a session in the list. A session the list does not hold is ignored.
- `pending` (`(sessionId: string) => Writable<readonly ChatInteraction[]>`): The store of a session's pending interactions.
- `readable` (`(sessionId: string, extra?: Pick<Transcript, 'loadEarlier'>) => Transcript`): The `Transcript` a host hands the components, with `onFirstSubscribe` / `onLastUnsubscribe` hooks.
- `resolveInteraction` (`(requestId: string) => void`): Removes a request from the pending interactions of every session.
- `setRunning` (`(sessionId: string, running: boolean, status?: ChatSessionStatus) => void`): A run started or ended; the session's status follows (`status` overrides: `'error'`, `'idle'` after an interrupt).
- `transcript` (`(sessionId: string) => LiveTranscript`): Created on first use; `onOpen` runs then (an adapter starts its stream there).

Source: [ui/src/adapters/live.ts:44](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/live.ts#L44)

### `LiveStateOptions`

Interface.

Options for [`createLiveState`](https://zidane.si/docs/reference/ui-adapters.md#createLiveState).

```ts
interface LiveStateOptions
```

**Properties**

- `evict?` (`boolean`): Forget the transcripts nobody reads: when a session's last subscriber leaves, every window goes but the
  open sessions', the running ones' and the 12 most recently opened. For an adapter that loads a transcript
  again in `onOpen`. Default: `false`.
- `onClose?` (`(sessionId: string) => void`): Called with the session id when the last subscriber of its transcript leaves. An adapter stops the session's stream here.
- `onOpen?` (`(sessionId: string) => void`): Called with the session id when the first subscriber of its transcript arrives. An adapter starts the session's stream here.
- `sessions?` (`readonly ChatSession[]`): The sessions the list starts with. Default: none.

Source: [ui/src/adapters/live.ts:74](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/live.ts#L74)

### `LiveTranscript`

Interface.

One session's live transcript: its state store and the echo bookkeeping.

```ts
interface LiveTranscript
```

**Properties**

- `echoes` (`string[]`): Prompts this client echoed itself, waiting for the host's echo to drop (the store's pending-echo list).
- `state` (`Writable<TranscriptState>`): The session's transcript state, updated as events arrive.

Source: [ui/src/adapters/live.ts:36](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/live.ts#L36)

### `MessageEndpoint`

Interface.

What both ends need of a `Worker` / `DedicatedWorkerGlobalScope` / `MessagePort`.

```ts
interface MessageEndpoint
```

**Properties**

- `addEventListener` (`(type: 'message', listener: (event: MessageEvent) => void) => void`): Registers a listener for messages from the other side.
- `postMessage` (`(message: unknown) => void`): Sends a message to the other side.
- `removeEventListener` (`(type: 'message', listener: (event: MessageEvent) => void) => void`): Removes a listener added with `addEventListener`.

Source: [ui/src/adapters/worker-protocol.ts:58](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-protocol.ts#L58)

### `RunContext`

Interface.

What [`createRunHost`](https://zidane.si/docs/reference/ui-adapters.md#createRunHost) hands to the `run` function for one sent prompt.

```ts
interface RunContext
```

**Properties**

- `attachments` (`readonly ChatAttachment[]`): Files sent with the prompt. Empty when there are none.
- `model?` (`string`): The model the user picked, as `provider/model` or a bare id. Absent when none was picked.
- `prompt` (`string`): The prompt text.
- `sessionId` (`string`): Id of the session the prompt was sent to.
- `signal` (`AbortSignal`): Aborted on interrupt.
- `thinking?` (`'off' | 'minimal' | 'low' | 'medium' | 'high'`): The reasoning effort the user picked. Absent when none was picked.
- `ask` (`(request: InteractionRequest) => Promise<InteractionResponse | null>`): Ask the user; resolves with the answer, or `null` when dismissed or interrupted.
- `emit` (`(event: ChatEvent) => void`): Streams an event into the session's transcript. Markdown and thinking events with `streaming` grow the open block; any other event is a new row.
- `onSteer` (`(listener: (message: string) => void) => void`): Receive messages the user steers into this run. Without a listener, `steer` reports false.

Source: [ui/src/adapters/run-host.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/run-host.ts#L29)

### `RunHost`

Interface.

The [`ChatHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatHost) [`createRunHost`](https://zidane.si/docs/reference/ui-adapters.md#createRunHost) returns, plus what only an in-memory host can do.

```ts
interface RunHost extends ChatHost
```

**Properties**

- `badges?` (`ChatBadgeActions`, from `ChatHost`): The badge menu's extension actions. Absent: the built-in actions only.
- `blockRuns?` (`ChatBlockRuns`, from `ChatHost`): Run here on a reply's shell blocks, and their saved runs. Absent: blocks have no Run button.
- `chips?` (`ChatChipDetails`, from `ChatHost`): What chip hover cards show (a commit, a `#chat`, a skill, a command). Absent: chips have no hover card.
- `interactions?` (`{ all?(): Readable<readonly ChatInteraction[]>; answer(requestId: string, response: InteractionResponse): Promise<void>; cancel?(requestId: string, reason?: string): Promise<void>; pending(sessionId: string): Readable<readonly ChatInteraction[]> }`, from `ChatHost`): Pending questions, plans, and approvals, and the way to answer or dismiss them.
- `models?` (`Readable<readonly ChatModelProvider[]>`, from `ChatHost`): Providers and models for the model picker. Absent: no picker.
- `paths?` (`ChatPaths`, from `ChatHost`): What prose chips name on disk. Absent: a chip opens the path as written.
- `references?` (`ChatReferences`, from `ChatHost`): Extension text references (ticket ids, issue links) in prose. Absent: they stay plain text.
- `searchSync?` (`ChatSearchSync`, from `ChatHost`): The transcript search a session's other windows share. Absent: the search stays in this window.
- `sessions?` (`{ list: Readable<readonly ChatSession[]>; views?: SidebarViewsHost; create?(input?: { title?: string }): Promise<ChatSession>; main?(): Promise<string | null>; onChanged?(listener: (sessionId: string) => void): () => void; onFacets?(listener: (sessionId: string, facets: Readonly<Record<string, unknown>>) => void): () => void; query?(filter: { archive: SessionArchiveFilter; hostId?: string }): Promise<readonly SidebarListSession[]>; remove?(sessionId: string): Promise<void | SessionRemoval>; rename?(sessionId: string, title: string): Promise<void>; search?(query: string, filter?: { archive?: SessionArchiveFilter }): Promise<readonly SessionSearchHit[]>; setArchived?(sessionId: string, archived: boolean): Promise<void>; setFavorite?(sessionId: string, favorite: boolean): Promise<void>; setSpace?(sessionId: string, spaceId: string): Promise<void> }`, from `ChatHost`): Session list and management. Each method left out hides its control (rename, archive, favorite, delete).
- `siteIcons?` (`ChatSiteIcons`, from `ChatHost`): Site icons for link badges. Absent: links show the globe.
- `cancelTool?` (`(sessionId: string, callId: string) => void`, from `ChatHost`): Stop a running tool call (a shell command).
- `interrupt?` (`(sessionId: string) => void`, from `ChatHost`): Stops the run in flight in a session. Absent: no stop button.
- `providerReady?` (`(cwd?: string) => Promise<boolean>`, from `ChatHost`): Whether a model provider can answer a prompt sent from `cwd`. Absent: a send is never refused for want of one.
- `restore` (`(session: { title: string }, events: readonly ChatEvent[]) => ChatSession`): Adds a session with a history, as a new session first in the list (a saved or shared one). Its events show as they are; the agent's own memory of them is the app's concern.
- `send?` (`(input: SendInput) => Promise<void>`, from `ChatHost`): Sends a prompt to a session. Absent: the composer cannot send.
- `shell?` (`(sessionId: string, command: string) => Promise<void>`, from `ChatHost`): Runs a `!` shell command in the session's folder, outside any agent run; its run streams into the
  transcript. Absent: a `!` prompt goes to the model as text.
- `toolOutput?` (`(sessionId: string, callId: string) => Promise<string | null>`, from `ChatHost`): A tool call's full output, when the event carries a preview only.
- `transcript` (`(sessionId: string) => Transcript`, from `ChatHost`): Returns the transcript store for a session.

Source: [ui/src/adapters/run-host.ts:68](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/run-host.ts#L68)

### `RunHostOptions`

Interface.

Options for [`createRunHost`](https://zidane.si/docs/reference/ui-adapters.md#createRunHost).

```ts
interface RunHostOptions
```

**Properties**

- `models?` (`readonly ChatModelProvider[] | Readable<readonly ChatModelProvider[]>`): Providers and models the host offers, fixed or live (a model's details change). Default: none.
- `newId?` (`() => string`): New session ids (default: `crypto.randomUUID()`).
- `run` (`RunFn`): The function that runs the agent for each sent prompt.
- `sessions?` (`readonly ChatSession[]`): Sessions to start with (default: none; the user creates them).
- `transcripts?` (`Record<string, readonly ChatEvent[]>`): Their existing events, per session id.

Source: [ui/src/adapters/run-host.ts:54](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/run-host.ts#L54)

### `SendBody`

Interface.

Body of `POST /sessions/:id/send`.

```ts
interface SendBody
```

**Properties**

- `attachments?` (`readonly ChatAttachment[]`): Previews with a `data:` URL are uploaded; others are dropped.
- `model?` (`string`): The model to run, as `provider/model` or a bare id. Absent: the server's default.
- `prompt` (`string`): The prompt text.
- `thinking?` (`'off' | 'minimal' | 'low' | 'medium' | 'high'`): Reasoning effort for this run.

Source: [ui/src/adapters/sse-protocol.ts:49](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L49)

### `ServerApprovalsHostOptions`

Interface.

Options for [`createServerApprovalsHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerApprovalsHost).

```ts
interface ServerApprovalsHostOptions
```

**Properties**

- `canApprove?` (`boolean`): `false` leaves out `resolve` and `denyAll`, for a token without the `approve` scope.
  Default: `client.can('approvals.resolve')` once the handshake has landed, `true` before it.
- `client` (`ServerClient`): The client to speak through, shared with the chat host (`createServerHost({ client })`) and other areas' hosts.
- `onError?` (`(error: unknown) => void`): Called with errors no caller receives (a failed listing). Default: a console warning.

Source: [ui/src/adapters/server-approvals-host.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-approvals-host.ts#L24)

### `ServerClient`

Interface.

A connection to a zidane-server: typed calls, signals and its state.

```ts
interface ServerClient
```

**Properties**

- `call` (`<M extends keyof IpcMethods>(method: M, params: IpcParams<M>) => Promise<IpcResult<M>>`): Calls a method. Waits while (re)connecting; fails when the connection drops mid-call.
- `can` (`(method: keyof IpcMethods) => boolean`): Whether this connection may call `method`: the host offers it and the token reaches it.
  `true` against a host that predates the list. `false` while not open.
- `close` (`() => void`): Closes the connection and stops reconnecting.
- `hello` (`() => HelloResult | null`): The current connection's hello, `null` while not open.
- `notify` (`<M extends keyof IpcMethods>(method: M, params: IpcParams<M>) => void`): Sends a notification (no answer). Dropped while not open.
- `onOpen` (`(listener: (hello: HelloResult, reconnected: boolean) => void) => () => void`): Called after every handshake, `reconnected` after the first: re-read or resume what the
  page shows. Returns its unsubscribe.
- `onSignal` (`(listener: (signal: HostSignal, meta?: SignalMeta) => void) => () => void`): Called with every signal the host fans out, and its position in its session; returns its unsubscribe.
- `onState` (`(listener: (state: ServerClientState) => void) => () => void`): Called on every state change; returns its unsubscribe.
- `ready` (`Promise<HelloResult>`): Resolves with the first hello; rejects when the client is refused or closed before it.
- `state` (`() => ServerClientState`): The connection's state now.

Source: [dist/ipc/browser.d.ts:201](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L201)

### `ServerClientOptions`

Interface.

Options for [`createServerClient`](https://zidane.si/docs/reference/ui-adapters.md#createServerClient).

```ts
interface ServerClientOptions
```

**Properties**

- `appVersion?` (`string`): Reported in the server's logs and audit (default `'web'`).
- `connectTimeoutMs?` (`number`): How long an attempt may take to open and finish its handshake before it is dropped and retried, in ms (default 10 000).
- `fetch?` (`{ (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | Request | URL, init?: RequestInit): Promise<Response> }`): `fetch`, for the auth check after a failed connect. Default: the global one.
- `heartbeatMs?` (`number`): Ping interval in ms; a ping unanswered by the next one drops the connection (default 20 000; 0: off).
- `onState?` (`(state: ServerClientState) => void`): Called on every state change.
- `reconnect?` (`false | { initialMs?: number; maxMs?: number }`): First reconnect delay and its ceiling, in ms (default 500 doubling to 15 000). `false`: never reconnect.
- `token?` (`string`): A client token (`zidane server token create --scope chat`). Absent: a server without auth.
- `url` (`string`): `ws://` or `wss://` URL of the server.
- `WebSocket?` (`(url: string | URL, protocols?: string | string[]) => WebSocket`): WebSocket constructor. Default: the global one.

Source: [dist/ipc/browser.d.ts:154](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L154)

### `ServerComposerHost`

Interface.

The [`ComposerHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ComposerHost) [`createServerComposerHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerComposerHost) returns.

```ts
interface ServerComposerHost extends ComposerHost
```

**Properties**

- `agents?` (`ComposerAgents`, from `ComposerHost`): The agent profiles the agent picker offers.
- `autocomplete?` (`ComposerAutocomplete`, from `ComposerHost`): Inline ghost text.
- `completions?` (`ComposerCompletions`, from `ComposerHost`): The completion catalogs.
- `context?` (`ComposerContext`, from `ComposerHost`): A session's context gauge, its breakdown and its settled cost.
- `controls?` (`ComposerControls`, from `ComposerHost`): The pickers' writes on a session (model, effort, options, agent) and their cache estimates.
- `drafts?` (`ComposerDrafts`, from `ComposerHost`): The shared per-session draft.
- `folders?` (`ComposerFolders`, from `ComposerHost`): The folder a new session opens in, remembered. Absent: a new session starts without one.
- `models?` (`ComposerModels`, from `ComposerHost`): The model catalogs the pickers list.
- `pickerPrefs?` (`ModelPickerPrefsStore`, from `ComposerHost`): The model picker's per-device preferences. Absent: an in-memory store for the page's life.
- `prefs?` (`ComposerPrefs`, from `ComposerHost`): Where picks are remembered across apps (effort and options per model, the next chat's model).
- `runs?` (`ComposerRuns`, from `ComposerHost`): The current run's counters per session (the run chip, the cost pill).
- `suggestions?` (`ComposerSuggestions`, from `ComposerHost`): Next-prompt suggestions.
- `close` (`() => void`): Stops listening to the client (it leaves the client open).

Source: [ui/src/adapters/server-composer-host.ts:66](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-composer-host.ts#L66)

### `ServerComposerHostOptions`

Interface.

Options for [`createServerComposerHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerComposerHost).

```ts
interface ServerComposerHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host (`createServerHost(…).client`).

Source: [ui/src/adapters/server-composer-host.ts:60](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-composer-host.ts#L60)

### `ServerExtensionAssetsAccess`

Interface.

Where the server serves the extensions' assets (webview pages), and the token they are fetched with.

```ts
interface ServerExtensionAssetsAccess
```

**Properties**

- `fetch?` (`{ (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | Request | URL, init?: RequestInit): Promise<Response> }`): `fetch`. Default: the global one.
- `origin` (`string`): The server's HTTP origin (`https://zidane.example.com`).
- `token?` (`string`): The client token. Absent: a server without auth.

Source: [ui/src/adapters/server-extensions-host.ts:107](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L107)

### `ServerExtensionCommands`

Interface.

The commands, with the keymap mode on top for the session the window shows.

```ts
interface ServerExtensionCommands extends ExtensionCommands
```

**Properties**

- `list` (`Readable<readonly ServerExtensionCommandWire[]>`): Every command, built-ins and extensions'.
- `mode` (`Readable<string | undefined>`): The keymap mode on top (`undefined`: none).
- `run` (`(id: string, opts?: { args?: string; sessionId?: string }) => Promise<boolean>`, from `ExtensionCommands`): Runs one. Whether a command by that id ran.

Source: [ui/src/adapters/server-extensions-host.ts:147](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L147)

### `ServerExtensionCommandWire`

Interface.

A command as this host lists it: the kit's wire, plus where its keybinding fires.

```ts
interface ServerExtensionCommandWire extends ExtensionCommandWire
```

**Properties**

- `bind?` (`readonly string[]`, from `ExtensionCommandWire`): Effective chords.
- `description?` (`string`, from `ExtensionCommandWire`): A line under the title.
- `editable` (`boolean`): Its keybinding also fires while a text field has focus.
- `enabled` (`boolean`): Turned off by its extension.
- `extensionId?` (`string`, from `ExtensionCommandWire`): The registering extension; absent for a built-in.
- `hint` (`boolean`): Shown in key hints.
- `id` (`string`, from `ExtensionCommandWire`): Published id: `<extension>.<id>`, or a built-in's.
- `mode?` (`string`): Its keybinding fires only while this keymap mode is on top.
- `scope` (`string`): Where focus must be for its keybinding: `global`, `composer`, `transcript`, `sidebar`, `modal`, `panel:<id>`, `screen:<id>`.
- `slash?` (`string`, from `ExtensionCommandWire`): The `/` name, without the slash.
- `title` (`string`, from `ExtensionCommandWire`): What a palette shows for it.
- `when` (`'idle' | 'session' | 'always'`): `session`: needs a session; `idle`: also no run in flight.

Source: [ui/src/adapters/server-extensions-host.ts:131](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L131)

### `ServerExtensionDialogs`

Interface.

Dialogs, with the form field check.

```ts
interface ServerExtensionDialogs extends ExtensionDialogs
```

**Properties**

- `current` (`Readable<ExtensionDialog | null>`, from `ExtensionDialogs`): The dialog to show now (the oldest non-toast one), or `null`.
- `toasts` (`Readable<readonly ExtensionDialog[]>`, from `ExtensionDialogs`): The toasts showing now, oldest first.
- `answer` (`(id: string, answer: unknown) => Promise<void>`, from `ExtensionDialogs`): Answers a dialog. The answer per kind: `confirm` a boolean, `prompt` the text, `select`
  `{ ids, action? }`, `form` a value per key, `askUser` a `QuestionResponse`, `presentPlan` a
  `PlanResponse`, `toast` the clicked action id. `undefined` cancels (or dismisses a toast).
- `validate` (`(dialogId: string, key: string, value: unknown) => Promise<string | null>`): Checks one field of a form dialog as the user edits it (`ui.dialog.validate`): the message to
  show under it, or `null` when it is valid (or the dialog is gone).

Source: [ui/src/adapters/server-extensions-host.ts:154](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L154)

### `ServerExtensionModuleLoader`

Interface.

What [`createServerExtensionModuleLoader`](https://zidane.si/docs/reference/ui-adapters.md#createServerExtensionModuleLoader) returns.

```ts
interface ServerExtensionModuleLoader
```

**Properties**

- `load` (`ExtensionModuleLoad`): `AppHostProvider`'s `loadExtensionModule`. A new function after `ServerExtensionModuleLoader.invalidate`.
- `invalidate` (`() => ExtensionModuleLoad`): A fresh `load` (the folder changed, an extension reloaded, the server came back): a module loads again.

Source: [ui/src/adapters/extension-modules.ts:205](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L205)

### `ServerExtensionModuleLoaderOptions`

Interface.

Options for [`createServerExtensionModuleLoader`](https://zidane.si/docs/reference/ui-adapters.md#createServerExtensionModuleLoader).

```ts
interface ServerExtensionModuleLoaderOptions
```

**Properties**

- `bundle` (`ServerExtensionBundleLookup`): Where each bundle is: `ServerExtensionsHost.bundle`.
- `fetch?` (`{ (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | Request | URL, init?: RequestInit): Promise<Response> }`): `fetch`. Default: the global one.
- `importModule?` (`(code: string) => Promise<Readonly<Record<string, unknown>>>`): Evaluates linked code as a module and returns its exports. Default: import from a `blob:` URL.
- `modules` (`ExtensionHostModuleSources`): The host modules the components import, each a namespace or a loader of one.
- `origin` (`string`): The server's HTTP origin (`https://zidane.example.com`).
- `token?` (`string`): The client token. Absent: a server without auth.

Source: [ui/src/adapters/extension-modules.ts:189](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L189)

### `ServerExtensionsHost`

Interface.

The [`ExtensionsHost`](https://zidane.si/docs/reference/ui-extensions-headless.md#ExtensionsHost) [`createServerExtensionsHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerExtensionsHost) returns.

```ts
interface ServerExtensionsHost extends ExtensionsHost
```

**Properties**

- `bundle` (`ServerExtensionBundleLookup`): An extension's `ui` bundle in the folder's current listing (`url` relative to the server's
  origin), why it did not bundle, or `undefined`: it has none. `fresh`: list again first.
- `commands` (`ServerExtensionCommands`): The unified commands.
- `dialogs` (`ServerExtensionDialogs`): `ctx.ui` dialogs and toasts routed to this client. Absent: this client shows none.
- `effects` (`ExtensionUiEffects`): `ctx.ui` panels, navigation, composer edits and notifications routed to this client.
- `integrations` (`ExtensionIntegrations`): Integrations and their connections.
- `invoke` (`<K extends keyof ExtensionCallbacks>(callbackId: K, args: ExtensionCallbacks[K]['args']) => Promise<ExtensionCallbacks[K]['result']>`): Calls an extension callback by id. Absent: nothing invokes (panels don't load, menus stay empty).
- `items` (`ExtensionItemStores`, from `ExtensionsHost`): Every contribution, per token.
- `openLink` (`(request: ExtensionLinkRequest) => Promise<boolean>`): Offers a link the user opened to the extensions' link handlers (`LinkHandler`, higher `priority`
  first). Resolves `true` when one opened it; `false` (or a rejection): open it the app's way. The kit
  skips it while Alt is held (`routeLink`). Absent: links open the app's way.
- `panelChanged` (`(listener: (change: ExtensionPanelChange) => void) => () => void`): A panel would load something new (its `subscribe` emitted, or its handle was updated): reload it where
  visible. `sessionId`: only that session's content changed. Returns the unsubscribe. Absent: panels the kit
  draws reload only after an action or a folder change.
- `ready` (`Promise<void>`): Settles once the first listing of the folder's items, settings, commands and integrations is in.
- `rpc` (`(contract: string, method: string, input?: unknown, opts?: ExtensionRpcOptions) => Promise<unknown>`): Calls an RPC method. Rejects `rpc` with the method's error. Absent: no RPC from the UI.
- `scope` (`Readable<ExtensionAccessScope | null>`): The scope this client's token grants (`null`: not limited, as a local or in-process host). Action
  settings above it show disabled with why. Absent: never limited.
- `settings` (`ExtensionSettings`): The extensions' settings, locked keys and provenance included.
- `storage` (`ExtensionStorage`): The extensions' typed stores.
- `webviews?` (`ExtensionWebviews & ServerWebviewSources`): With `assets`: the webview URLs the server mints.
- `announce` (`(info: ExtensionsClientAnnounce) => Promise<void>`): Tells the server what this window shows (kept and sent again on every reconnect).
- `close` (`() => void`): Stops listening to the client (the client stays open). Pending dialogs close unanswered.
- `folder` (`() => string | null`): The folder shown now.
- `onReset` (`(listener: () => void) => () => void`): The folder's extensions were rebuilt, or the connection came back (maybe to a restarted server):
  their `ui` modules may have changed. Returns the unsubscribe.
- `setFolder` (`(cwd: string | null) => void`): Shows another folder's extensions (`null`: none).

Source: [ui/src/adapters/server-extensions-host.ts:163](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L163)

### `ServerExtensionsHostOptions`

Interface.

Options for [`createServerExtensionsHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerExtensionsHost).

```ts
interface ServerExtensionsHostOptions
```

**Properties**

- `assets?` (`ServerExtensionAssetsAccess`): Where webview pages are minted. Absent: no `webviews` (a `file` source shows nothing).
- `client` (`ServerClient`): The client to speak through, shared with the chat host.
- `cwd?` (`string | null`): The folder whose extensions show. `null`: none until `ServerExtensionsHost.setFolder`.
- `onError?` (`(error: unknown) => void`): Called with errors no caller can receive (a failed listing). Default: a console warning.
- `onFlowStep?` (`ExtensionFlowStepHandler`): Shows one sign-in step. Default: links open in a new tab; questions show as dialogs of this host.

Source: [ui/src/adapters/server-extensions-host.ts:117](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L117)

### `ServerFilesHostOptions`

Interface.

Options for [`createServerFilesHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerFilesHost).

```ts
interface ServerFilesHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host (`createServerHost({ client })`) and other areas' hosts.
- `sessionOf` (`(cwd: string) => string | undefined`): The session whose workspace holds a folder's files (the session open on it); `undefined`: none, nothing to read.
- `storage?` (`EditorPrefsStorage`): Where the editor preferences live (`localStorage`). Absent: no `editorPrefs`, the defaults.

Source: [ui/src/adapters/server-files-host.ts:52](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-files-host.ts#L52)

### `ServerGitHostOptions`

Interface.

Options for [`createServerGitHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerGitHost).

```ts
interface ServerGitHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host.

Source: [ui/src/adapters/server-git-host.ts:44](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-git-host.ts#L44)

### `ServerHost`

Interface.

The [`ChatHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatHost) [`createServerHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerHost) returns, plus the connection.

```ts
interface ServerHost extends ChatHost
```

**Properties**

- `badges?` (`ChatBadgeActions`, from `ChatHost`): The badge menu's extension actions. Absent: the built-in actions only.
- `blockRuns?` (`ChatBlockRuns`, from `ChatHost`): Run here on a reply's shell blocks, and their saved runs. Absent: blocks have no Run button.
- `chips?` (`ChatChipDetails`, from `ChatHost`): What chip hover cards show (a commit, a `#chat`, a skill, a command). Absent: chips have no hover card.
- `client` (`ServerClient`): The client it speaks through (for other areas' hosts on the same connection).
- `connection` (`Readable<ServerClientState>`): The connection's state, for a status line or a sign-in prompt.
- `interactions?` (`{ all?(): Readable<readonly ChatInteraction[]>; answer(requestId: string, response: InteractionResponse): Promise<void>; cancel?(requestId: string, reason?: string): Promise<void>; pending(sessionId: string): Readable<readonly ChatInteraction[]> }`, from `ChatHost`): Pending questions, plans, and approvals, and the way to answer or dismiss them.
- `models?` (`Readable<readonly ChatModelProvider[]>`, from `ChatHost`): Providers and models for the model picker. Absent: no picker.
- `paths?` (`ChatPaths`, from `ChatHost`): What prose chips name on disk. Absent: a chip opens the path as written.
- `ready` (`Promise<void>`): Resolves once the first handshake and session list completed; rejects when the client was refused.
- `references?` (`ChatReferences`, from `ChatHost`): Extension text references (ticket ids, issue links) in prose. Absent: they stay plain text.
- `searchSync?` (`ChatSearchSync`, from `ChatHost`): The transcript search a session's other windows share. Absent: the search stays in this window.
- `sessions?` (`{ list: Readable<readonly ChatSession[]>; views?: SidebarViewsHost; create?(input?: { title?: string }): Promise<ChatSession>; main?(): Promise<string | null>; onChanged?(listener: (sessionId: string) => void): () => void; onFacets?(listener: (sessionId: string, facets: Readonly<Record<string, unknown>>) => void): () => void; query?(filter: { archive: SessionArchiveFilter; hostId?: string }): Promise<readonly SidebarListSession[]>; remove?(sessionId: string): Promise<void | SessionRemoval>; rename?(sessionId: string, title: string): Promise<void>; search?(query: string, filter?: { archive?: SessionArchiveFilter }): Promise<readonly SessionSearchHit[]>; setArchived?(sessionId: string, archived: boolean): Promise<void>; setFavorite?(sessionId: string, favorite: boolean): Promise<void>; setSpace?(sessionId: string, spaceId: string): Promise<void> }`, from `ChatHost`): Session list and management. Each method left out hides its control (rename, archive, favorite, delete).
- `siteIcons?` (`ChatSiteIcons`, from `ChatHost`): Site icons for link badges. Absent: links show the globe.
- `cancelTool?` (`(sessionId: string, callId: string) => void`, from `ChatHost`): Stop a running tool call (a shell command).
- `close` (`() => void`): Closes the connection and stops reconnecting (also closes a client it was given).
- `interrupt?` (`(sessionId: string) => void`, from `ChatHost`): Stops the run in flight in a session. Absent: no stop button.
- `providerReady?` (`(cwd?: string) => Promise<boolean>`, from `ChatHost`): Whether a model provider can answer a prompt sent from `cwd`. Absent: a send is never refused for want of one.
- `refresh` (`() => Promise<void>`): Re-reads the session list.
- `send?` (`(input: SendInput) => Promise<void>`, from `ChatHost`): Sends a prompt to a session. Absent: the composer cannot send.
- `shell?` (`(sessionId: string, command: string) => Promise<void>`, from `ChatHost`): Runs a `!` shell command in the session's folder, outside any agent run; its run streams into the
  transcript. Absent: a `!` prompt goes to the model as text.
- `toolOutput?` (`(sessionId: string, callId: string) => Promise<string | null>`, from `ChatHost`): A tool call's full output, when the event carries a preview only.
- `transcript` (`(sessionId: string) => Transcript`, from `ChatHost`): Returns the transcript store for a session.

Source: [ui/src/adapters/server-host.ts:63](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-host.ts#L63)

### `ServerMachinesHost`

Interface.

The [`MachinesHost`](https://zidane.si/docs/reference/ui-machines-headless.md#MachinesHost) [`createServerMachinesHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerMachinesHost) returns.

```ts
interface ServerMachinesHost extends MachinesHost
```

**Properties**

- `daemon?` (`DaemonControl`, from `MachinesHost`): The local daemon. Absent: no daemon menu.
- `hosts?` (`Readable<HostsState>`, from `MachinesHost`): The hosts the app knows and their connection. Absent: no host list.
- `links?` (`MachineLinks`, from `MachinesHost`): This computer's machine links. Absent: no share or use rows.
- `machines?` (`MachinesDirectory`, from `MachinesHost`): The machines servers hold. Absent: no machine list.
- `permitted?` (`Readable<ReadonlySet<MachinesAction> | null>`, from `MachinesHost`): What the members may do right now; `null` while that is not known (not connected). Absent: everything they offer.
- `presence?` (`MachinesPresence`, from `MachinesHost`): Live per-session presence (attached windows, runs, waiting on you). Absent: no presence on the rows.
- `savedHosts?` (`SavedHosts`, from `MachinesHost`): The saved-server registry with its dates. Absent: the hosts list shows the live statuses alone.
- `sync?` (`HostSync`, from `MachinesHost`): Settings sync to a server and the server's record. Absent: no Sync section, no markers.
- `tokens?` (`ServerTokens`, from `MachinesHost`): A server's client tokens. Absent: no token list.
- `updates?` (`ServerUpdates`, from `MachinesHost`): A server's self-update. Absent: no update section.
- `addHost?` (`(input: { name?: string; token: string; url: string }) => Promise<HostCheckResult>`, from `MachinesHost`): Saves a server after checking it. Absent: no add form.
- `capabilities?` (`(hostId: string, options?: { refresh?: boolean }) => Promise<HostCapabilities>`, from `MachinesHost`): What a host can do (OS, tools on PATH, sandbox, environment kinds, what it allows, disk); `refresh` probes again
  instead of the backend's short cache. Rejects with a [`MachinesError`](https://zidane.si/docs/reference/ui-machines-headless.md#MachinesError) (`read`). Absent: no capabilities.
- `close` (`() => void`): Stops listening to the client (the client stays open).
- `installTool?` (`(hostId: string, name: string) => Promise<ToolInstallResult>`, from `MachinesHost`): Installs a missing tool on a server, as its user, when the server's recipe needs no root (`toolInstall` says
  `run`); answers what it printed and the new capabilities. Rejects with a [`MachinesError`](https://zidane.si/docs/reference/ui-machines-headless.md#MachinesError) (`install`).
  Absent: no Install buttons.
- `pickFolder?` (`() => Promise<string | null>`, from `MachinesHost`): Picks a folder to share (the native dialog). Absent: no Add a folder.
- `refreshHosts?` (`() => Promise<void>`, from `MachinesHost`): Reads the hosts again (after a setting changed).
- `removeHost?` (`(id: string) => Promise<void>`, from `MachinesHost`): Removes a saved server and its token. Rejects with a [`MachinesError`](https://zidane.si/docs/reference/ui-machines-headless.md#MachinesError). Absent: no Remove.
- `renameHost?` (`(id: string, name: string) => Promise<HostCheckResult>`, from `MachinesHost`): Renames a saved server. Absent: no Rename.
- `retry?` (`(hostId: string) => Promise<void>`, from `MachinesHost`): Reconnects to a server now instead of at the next backoff. Absent: no Retry.
- `setHostUrl?` (`(id: string, url: string) => Promise<HostCheckResult>`, from `MachinesHost`): Moves a saved server to a new URL with its saved token, once the same server answers there. Absent: no Change URL.
- `signIn?` (`(hostId: string, target: HostSignInTarget, onDone?: () => void) => SignInFlow`, from `MachinesHost`): Starts a browser sign-in whose tokens stay on `hostId` (the browser opens here); `onDone` runs once the server
  stored them. Absent: no "Sign in there".
- `testHost?` (`(target: { id: string } | { token: string; url: string }) => Promise<HostCheckResult>`, from `MachinesHost`): Tests a saved server, or a URL and token before saving. Absent: no Test.

Source: [ui/src/adapters/server-machines-host.ts:66](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-machines-host.ts#L66)

### `ServerMachinesHostOptions`

Interface.

Options for [`createServerMachinesHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerMachinesHost).

```ts
interface ServerMachinesHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host (`createServerHost({ client })`) and other areas' hosts.
- `name?` (`string`): The server's name before (or without) the one its handshake reports. Default `zidane-server`.
- `url?` (`string`): The server's `ws://` or `wss://` URL as a machine reaches it (a web page's own origin), for join codes.
  Absent: no `machines.invite`.

Source: [ui/src/adapters/server-machines-host.ts:53](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-machines-host.ts#L53)

### `ServerOnboardingHost`

Interface.

The [`OnboardingHost`](https://zidane.si/docs/reference/ui-onboarding-headless.md#OnboardingHost) [`createServerOnboardingHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerOnboardingHost) returns.

```ts
interface ServerOnboardingHost extends OnboardingHost
```

**Properties**

- `appIcons?` (`{ list: Readable<readonly OnboardingAppIcon[]>; note?: string }`, from `OnboardingHost`): App icons for Look, for an app that has several. Absent: Look offers no icon.
- `connectors?` (`{ installed: Readable<readonly string[]>; add(id: string, input?: ConnectorInput): Promise<void>; githubToken?(): Promise<string | null>; signIn?(id: string): SignInFlow }`, from `OnboardingHost`): Connectors. Absent: the step is left out.
- `context` (`Readable<OnboardingSetup | null>`, from `OnboardingHost`): What the wizard starts from. It is `null` while the app still detects.
- `extensions?` (`{ installed: Readable<readonly string[]>; install(name: string, onProgress?: (message: string) => void): Promise<void> }`, from `OnboardingHost`): Native extensions. Absent: the step is left out.
- `imports?` (`{ preview(): Promise<OnboardingImportPreview>; run(selection: OnboardingImportSelection): Promise<void> }`, from `OnboardingHost`): Bring your setup. Absent: the step is left out.
- `providers` (`{ list: Readable<readonly OnboardingProvider[]>; models?(key: string): Promise<readonly OnboardingModelInfo[]>; saveKey?(key: string, input: { fields?: Record<string, string>; value?: string }): Promise<void>; signIn?(key: string): SignInFlow; test?(key: string, model?: string): Promise<ProviderTestResult> }`, from `OnboardingHost`): The providers Connect lists, and how to set them up.
- `skills?` (`{ images?: SkillSourceImages; installed: Readable<readonly string[]>; browse(input: string): Promise<SkillSourceListing>; install(source: string, rels: readonly string[], onProgress?: (message: string) => void): Promise<void> }`, from `OnboardingHost`): Skills. Absent: the step is left out.
- `themes?` (`{ list: Readable<readonly Theme[]>; preview(appearance: OnboardingAppearance | null): void }`, from `OnboardingHost`): Themes for Look. Absent: the step is left out.
- `close` (`() => void`): Stops open sign-ins and listening to the client (the client stays open).
- `commit` (`(result: OnboardingResult) => Promise<void>`, from `OnboardingHost`): Writes what a finished run decided.

Source: [ui/src/adapters/server-onboarding-host.ts:96](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-onboarding-host.ts#L96)

### `ServerOnboardingHostOptions`

Interface.

Options for [`createServerOnboardingHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerOnboardingHost).

```ts
interface ServerOnboardingHostOptions
```

**Properties**

- `appIcons?` (`{ list: Readable<readonly OnboardingAppIcon[]>; note?: string }`): The app icons Look offers, from the page. Absent: Look offers no icon.
- `canConfigure?` (`boolean`): `false` leaves out keys, sign-ins, connectors and extensions, for a token without the `admin` scope.
  Default: `client.can('auth.setApiKey')` once the handshake has landed, `true` before it.
- `client` (`ServerClient`): The client to speak through, shared with the chat host and other areas' hosts.
- `cwd?` (`string`): The folder on the server whose extension providers and catalog count. Absent: the server user's scope.
- `mode?` (`OnboardingMode`, default `'full'`): How much of the wizard runs.
- `oauthCallbackUrl?` (`string`): The server's `SERVER_OAUTH_CALLBACK_PATH` at the origin this page reaches it by: a connector's browser sign-in
  comes back there (a browser can't listen on a loopback port). Absent: no sign-in, a connector signs in on first use.
- `onCommitted?` (`(result: OnboardingResult) => void | Promise<void>`): Called once the settings are written, to apply what the server does not keep: the look, the model pick.
- `onError?` (`(error: unknown) => void`): Called with errors no caller receives (a failed listing). Default: a console warning.
- `surface?` (`OnboardingSurface`, default `'desktop'`): The app the wizard runs in.
- `themes?` (`{ list: Readable<readonly Theme[]>; preview(appearance: OnboardingAppearance | null): void }`): The themes Look offers and the live preview, from the page. Absent: no Look step.

Source: [ui/src/adapters/server-onboarding-host.ts:60](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-onboarding-host.ts#L60)

### `ServerPaletteHost`

Interface.

The [`PaletteHost`](https://zidane.si/docs/reference/ui-palette-headless.md#PaletteHost) [`createServerPaletteHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerPaletteHost) returns.

```ts
interface ServerPaletteHost extends PaletteHost
```

**Properties**

- `extensions?` (`PaletteExtensions`, from `PaletteHost`): Extension-contributed items. Absent: no extensions source.
- `recents?` (`PaletteRecents`, from `PaletteHost`): Persistent recents. Absent: recents last as long as the page.
- `settings?` (`Readable<Partial<Settings>>`, from `PaletteHost`): The settings in effect, read when the palette lists its rows. Absent: no settings rows.
- `close` (`() => void`): Stops listening to the client (the client stays open).
- `listCommands?` (`(query: PaletteCommandQuery) => Promise<readonly PaletteCommand[]>`, from `PaletteHost`): The `/` commands for a folder. Absent: no commands source.
- `listFiles?` (`(query: PaletteFileQuery) => Promise<readonly PaletteFileEntry[]>`, from `PaletteHost`): The project's files (without gitignored ones). Absent: no files source.
- `searchConversations?` (`(query: PaletteConversationQuery) => Promise<readonly PaletteConversationHit[]>`, from `PaletteHost`): Content matches inside conversations, best first; a newer call may cancel an older scan (it then resolves
  with whatever it has, or rejects). Absent: no "In conversations" group.
- `setSettings?` (`(patch: Partial<Settings>) => Promise<void>`, from `PaletteHost`): Applies a settings patch. Absent: settings rows are not offered.

Source: [ui/src/adapters/server-palette-host.ts:34](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-palette-host.ts#L34)

### `ServerPaletteHostOptions`

Interface.

Options for [`createServerPaletteHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerPaletteHost).

```ts
interface ServerPaletteHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host.
- `onError?` (`(error: unknown) => void`): Called with errors no caller can receive (a failed settings read). Default: a console warning.
- `recents?` (`PaletteRecents`): Where recents persist. Default: in memory.

Source: [ui/src/adapters/server-palette-host.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-palette-host.ts#L24)

### `ServerSessionHost`

Interface.

The [`SessionHost`](https://zidane.si/docs/reference/ui-session-headless.md#SessionHost) [`createServerSessionHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerSessionHost) returns.

```ts
interface ServerSessionHost extends SessionHost
```

**Properties**

- `artifacts?` (`SessionArtifacts`, from `SessionHost`): The recorded artifacts. Absent: no Artifacts panel.
- `details?` (`SessionDetailsActions`, from `SessionHost`): The details dialog's actions. Absent: the dialog shows facts only.
- `plans?` (`SessionPlans`, from `SessionHost`): The plans. Absent: no Todos panel.
- `queue?` (`SessionQueue`, from `SessionHost`): The type-ahead queues. Absent: no queue.
- `runningWork?` (`SessionRunningWork`, from `SessionHost`): The cancellable work. Absent: no running work dialog.
- `schedules?` (`SessionSchedules`, from `SessionHost`): Reminders (zidane's schedules). Absent: no Reminders panel, no badge.
- `secrets?` (`SessionSecrets`, from `SessionHost`): The saved secrets of a session's project. Absent: no Secrets panel.
- `side?` (`SessionSideChats`, from `SessionHost`): `/side` chats about a session. Absent: no side chat.
- `turns?` (`SessionTurns`, from `SessionHost`): The stored turns. Absent: no turn details dialog.
- `usage?` (`SessionUsage`, from `SessionHost`): Usage. Absent: no usage card, no usage panel.
- `close` (`() => void`): Stops listening to the client (it leaves the client open).

Source: [ui/src/adapters/server-session-host.ts:65](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-session-host.ts#L65)

### `ServerSessionHostOptions`

Interface.

Options for [`createServerSessionHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerSessionHost).

```ts
interface ServerSessionHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host (`createServerHost(…).client`).
- `saveExport?` (`(file: { content: string; filename: string; format: SessionExportFormat }) => Promise<string>`): Hands an exported transcript to the user (a browser download) and resolves what to show as where it went.
  Absent: no export.

Source: [ui/src/adapters/server-session-host.ts:54](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-session-host.ts#L54)

### `ServerSettingsHost`

Interface.

The [`SettingsHost`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsHost) [`createServerSettingsHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerSettingsHost) returns.

```ts
interface ServerSettingsHost extends SettingsHost
```

**Properties**

- `claudeImport?` (`SettingsClaudeImportHost`, from `SettingsHost`): Importing the Claude Code setup of the host's machine. Absent: no import.
- `document` (`Readable<SettingsDocument>`, from `SettingsHost`): The settings document: `loading` until first read.
- `environments?` (`SettingsEnvironmentsHost`, from `SettingsHost`): Where new sessions run (Settings › Environments).
- `extensions?` (`SettingsExtensionsHost`, from `SettingsHost`): Extensions on disk for a folder (Settings › Extensions).
- `hostCatalog?` (`SettingsHostCatalog`, from `SettingsHost`): The host's own catalogs with its enabled state (a server's Skills, MCP servers, Extensions, Plugins).
- `instructions?` (`SettingsInstructionsHost`, from `SettingsHost`): What a session's agent is loaded with (Settings › Instructions).
- `logs?` (`SettingsLogsHost`, from `SettingsHost`): The host's log funnel (Settings › Logs).
- `mcp?` (`SettingsMcpHost`, from `SettingsHost`): A folder's MCP servers, their sign-ins and tests (Settings › MCP servers). Absent: no servers to show.
- `models?` (`SettingsModelsHost`, from `SettingsHost`): The model rows' decision catalog, tests and last used model (Settings › Agent). Absent: rows without them.
- `paths?` (`SettingsPaths`, from `SettingsHost`): Opening the host's paths in other apps (reveal, open in the editor).
- `performance?` (`SettingsPerformanceHost`, from `SettingsHost`): What the app's processes and threads use, live (Settings › Performance). Absent: an empty page.
- `plugins?` (`SettingsPluginsHost`, from `SettingsHost`): Agent Plugins for a folder (Settings › Plugins).
- `providers?` (`SettingsProvidersHost`, from `SettingsHost`): The providers the host's agents sign in to (Settings › Accounts). Absent: no providers to show.
- `skills?` (`SettingsSkillsHost`, from `SettingsHost`): Skills on disk for a folder (Settings › Skills). Absent: no skills section content.
- `writable?` (`Readable<boolean>`, from `SettingsHost`): Whether `update` may run now (a server token without the admin scope may not). Absent: whenever `update` is there.
- `close` (`() => void`): Stops listening to the client (the client stays open).
- `refresh` (`() => Promise<void>`, from `SettingsHost`): Reads the settings again and tells subscribers. Never rejects: a failure lands in `document` (when nothing was read yet).
- `update?` (`(patch: Partial<Settings>) => Promise<void>`, from `SettingsHost`): Applies a patch: `document` shows it at once, then what the host holds
  after the write. Rejects with a [`SettingsError`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsError) when the write is
  refused, and `document` goes back to what the host holds. Absent: read-only.

Source: [ui/src/adapters/server-settings-host.ts:39](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-settings-host.ts#L39)

### `ServerSettingsHostOptions`

Interface.

Options for [`createServerSettingsHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerSettingsHost).

```ts
interface ServerSettingsHostOptions
```

**Properties**

- `client` (`ServerClient`): The shared client (`createServerClient`).
- `oauthCallbackUrl?` (`string`): The server's `SERVER_OAUTH_CALLBACK_PATH` at the origin this page reaches it by: an MCP server's sign-in
  comes back there (a browser can't listen on a loopback port). Absent: no MCP sign-in.

Source: [ui/src/adapters/server-settings-host.ts:28](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-settings-host.ts#L28)

### `ServerSidebarHostOptions`

Interface.

Options for [`createServerSidebarHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerSidebarHost).

```ts
interface ServerSidebarHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host (`createServerHost(…).client`).

Source: [ui/src/adapters/server-sidebar-host.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-sidebar-host.ts#L21)

### `ServerTerminalHostOptions`

Interface.

Options for [`createServerTerminalHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerTerminalHost).

```ts
interface ServerTerminalHostOptions
```

**Properties**

- `client` (`ServerClient`): The client to speak through, shared with the chat host (`createServerHost({ client })`) and other areas' hosts.

Source: [ui/src/adapters/server-terminal-host.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-terminal-host.ts#L21)

### `ServerWebviewSources`

Interface.

Webview URLs from zidane-server, for `ExtensionWebview`'s `resolveSrc`.

```ts
interface ServerWebviewSources
```

**Properties**

- `clear` (`() => void`): Forgets the minted URLs (the folder changed): the next `resolveSrc` mints again.
- `reset` (`() => void`): Forgets the minted URLs and tells subscribers, so every shown webview mints again (a rebuild, a
  reconnect to a server that may have restarted and dropped its tickets).
- `resolveSrc` (`(webview: { id: string; src: { url: string } | { file: string } }) => string | null`): The URL a webview's iframe loads: a `url` source as given, a `file` source the URL the server
  minted for it (`null` until it answered; subscribers hear when it did).
- `subscribe` (`(listener: () => void) => () => void`): Called when a minted URL arrives. Returns the unsubscribe.

Source: [ui/src/adapters/extension-modules.ts:296](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L296)

### `ServerWebviewSourcesOptions`

Interface.

Options for [`createServerWebviewSources`](https://zidane.si/docs/reference/ui-adapters.md#createServerWebviewSources).

```ts
interface ServerWebviewSourcesOptions
```

**Properties**

- `cwd` (`() => string | null`): The folder whose extensions the webviews belong to (`null`: none).
- `fetch?` (`{ (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | Request | URL, init?: RequestInit): Promise<Response> }`): `fetch`. Default: the global one.
- `onError?` (`(error: unknown) => void`): Called with a mint that failed. Default: a console warning.
- `origin` (`string`): The server's HTTP origin.
- `token?` (`string`): The client token. Absent: a server without auth.

Source: [ui/src/adapters/extension-modules.ts:282](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L282)

### `SseHost`

Interface.

The [`ChatHost`](https://zidane.si/docs/reference/ui-chat-headless.md#ChatHost) [`createSseHost`](https://zidane.si/docs/reference/ui-adapters.md#createSseHost) returns, plus the stream controls.

```ts
interface SseHost extends ChatHost
```

**Properties**

- `badges?` (`ChatBadgeActions`, from `ChatHost`): The badge menu's extension actions. Absent: the built-in actions only.
- `blockRuns?` (`ChatBlockRuns`, from `ChatHost`): Run here on a reply's shell blocks, and their saved runs. Absent: blocks have no Run button.
- `chips?` (`ChatChipDetails`, from `ChatHost`): What chip hover cards show (a commit, a `#chat`, a skill, a command). Absent: chips have no hover card.
- `interactions?` (`{ all?(): Readable<readonly ChatInteraction[]>; answer(requestId: string, response: InteractionResponse): Promise<void>; cancel?(requestId: string, reason?: string): Promise<void>; pending(sessionId: string): Readable<readonly ChatInteraction[]> }`, from `ChatHost`): Pending questions, plans, and approvals, and the way to answer or dismiss them.
- `models?` (`Readable<readonly ChatModelProvider[]>`, from `ChatHost`): Providers and models for the model picker. Absent: no picker.
- `paths?` (`ChatPaths`, from `ChatHost`): What prose chips name on disk. Absent: a chip opens the path as written.
- `references?` (`ChatReferences`, from `ChatHost`): Extension text references (ticket ids, issue links) in prose. Absent: they stay plain text.
- `searchSync?` (`ChatSearchSync`, from `ChatHost`): The transcript search a session's other windows share. Absent: the search stays in this window.
- `sessions?` (`{ list: Readable<readonly ChatSession[]>; views?: SidebarViewsHost; create?(input?: { title?: string }): Promise<ChatSession>; main?(): Promise<string | null>; onChanged?(listener: (sessionId: string) => void): () => void; onFacets?(listener: (sessionId: string, facets: Readonly<Record<string, unknown>>) => void): () => void; query?(filter: { archive: SessionArchiveFilter; hostId?: string }): Promise<readonly SidebarListSession[]>; remove?(sessionId: string): Promise<void | SessionRemoval>; rename?(sessionId: string, title: string): Promise<void>; search?(query: string, filter?: { archive?: SessionArchiveFilter }): Promise<readonly SessionSearchHit[]>; setArchived?(sessionId: string, archived: boolean): Promise<void>; setFavorite?(sessionId: string, favorite: boolean): Promise<void>; setSpace?(sessionId: string, spaceId: string): Promise<void> }`, from `ChatHost`): Session list and management. Each method left out hides its control (rename, archive, favorite, delete).
- `siteIcons?` (`ChatSiteIcons`, from `ChatHost`): Site icons for link badges. Absent: links show the globe.
- `cancelTool?` (`(sessionId: string, callId: string) => void`, from `ChatHost`): Stop a running tool call (a shell command).
- `close` (`() => void`): Close every stream.
- `interrupt?` (`(sessionId: string) => void`, from `ChatHost`): Stops the run in flight in a session. Absent: no stop button.
- `providerReady?` (`(cwd?: string) => Promise<boolean>`, from `ChatHost`): Whether a model provider can answer a prompt sent from `cwd`. Absent: a send is never refused for want of one.
- `refresh` (`() => Promise<void>`): Re-read the session list.
- `send?` (`(input: SendInput) => Promise<void>`, from `ChatHost`): Sends a prompt to a session. Absent: the composer cannot send.
- `shell?` (`(sessionId: string, command: string) => Promise<void>`, from `ChatHost`): Runs a `!` shell command in the session's folder, outside any agent run; its run streams into the
  transcript. Absent: a `!` prompt goes to the model as text.
- `toolOutput?` (`(sessionId: string, callId: string) => Promise<string | null>`, from `ChatHost`): A tool call's full output, when the event carries a preview only.
- `transcript` (`(sessionId: string) => Transcript`, from `ChatHost`): Returns the transcript store for a session.

Source: [ui/src/adapters/sse-host.ts:30](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-host.ts#L30)

### `SseHostOptions`

Interface.

Options for [`createSseHost`](https://zidane.si/docs/reference/ui-adapters.md#createSseHost).

```ts
interface SseHostOptions
```

**Properties**

- `baseUrl` (`string`): Where `createSseHandler` is mounted, e.g. `/api/chat` or `https://agent.example.com/chat`.
- `fetch?` (`{ (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | Request | URL, init?: RequestInit): Promise<Response> }`): The `fetch` function to use. Default: the global `fetch`.
- `headers?` (`HeadersInit | (() => HeadersInit | Promise<HeadersInit>)`): Sent with every request (auth). A function is called per request, so a token can refresh.
- `onError?` (`(error: unknown) => void`): Called with request and stream failures (default: `console.warn`).
- `reconnectMs?` (`number`): First reconnect delay in ms (default 500, doubling to 10 s; a server `retry:` replaces it).

Source: [ui/src/adapters/sse-host.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-host.ts#L16)

### `SseParser`

Interface.

An incremental parser created by [`createSseParser`](https://zidane.si/docs/reference/ui-adapters.md#createSseParser).

```ts
interface SseParser
```

**Properties**

- `lastId` (`() => string`): The last event ID seen so far.
- `push` (`(chunk: string) => void`): Feeds the next chunk of decoded text, split at any point. Calls `onRecord` for each record the chunk completes.
- `retry` (`() => number | undefined`): The `retry:` the server last asked for, in ms.

Source: [ui/src/adapters/sse-parser.ts:17](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-parser.ts#L17)

### `SseRecord`

Interface.

An incremental `text/event-stream` parser (the WHATWG "event stream
interpretation"): feed it decoded text in any chunking, it calls `onRecord`
for each dispatched record. Used instead of `EventSource` so requests can
carry headers (auth) and the client controls reconnects.

```ts
interface SseRecord
```

**Properties**

- `data` (`string`): The record's `data` lines joined with newlines.
- `event` (`string`): `event` field; `'message'` when absent.
- `id` (`string`): The record's `id`, or the last one seen (the spec's "last event ID").

Source: [ui/src/adapters/sse-parser.ts:7](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-parser.ts#L7)

### `StreamPacer`

Interface.

What [`createStreamPacer`](https://zidane.si/docs/reference/ui-adapters.md#createStreamPacer) returns.

```ts
interface StreamPacer
```

**Properties**

- `flush` (`() => void`): Applies everything queued or waiting to reveal, now: the run ended.
- `push` (`(event: ChatEvent) => void`): Queues a live event for the next frame.

Source: [ui/src/adapters/stream-pacer.ts:18](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/stream-pacer.ts#L18)

### `StreamPacerOptions`

Interface.

Options of [`createStreamPacer`](https://zidane.si/docs/reference/ui-adapters.md#createStreamPacer).

```ts
interface StreamPacerOptions
```

**Properties**

- `smooth?` (`boolean`): Reveals streamed reply text at a steady rate. Default: false, each frame applies what arrived.

Source: [ui/src/adapters/stream-pacer.ts:26](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/stream-pacer.ts#L26)

### `WorkerHostOptions`

Interface.

Options for [`createWorkerHost`](https://zidane.si/docs/reference/ui-adapters.md#createWorkerHost): the [`RunHostOptions`](https://zidane.si/docs/reference/ui-adapters.md#RunHostOptions) except `run`, plus `newRunId`.

```ts
interface WorkerHostOptions extends Omit<RunHostOptions, 'run'>
```

**Properties**

- `models?` (`readonly ChatModelProvider[] | Readable<readonly ChatModelProvider[]>`, from `Omit`): Providers and models the host offers, fixed or live (a model's details change). Default: none.
- `newId?` (`() => string`, from `Omit`): New session ids (default: `crypto.randomUUID()`).
- `newRunId?` (`() => string`): Run ids (default: `crypto.randomUUID()`).
- `sessions?` (`readonly ChatSession[]`, from `Omit`): Sessions to start with (default: none; the user creates them).
- `transcripts?` (`Record<string, readonly ChatEvent[]>`, from `Omit`): Their existing events, per session id.

Source: [ui/src/adapters/worker-host.ts:27](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-host.ts#L27)

### `WorkerRunInput`

Interface.

The prompt the page sends to start a run in the worker.

```ts
interface WorkerRunInput
```

**Properties**

- `attachments` (`readonly ChatAttachment[]`): Files sent with the prompt.
- `model?` (`string`): The model the user picked, as `provider/model` or a bare id.
- `prompt` (`string`): The prompt text.
- `sessionId` (`string`): Id of the session the prompt was sent to.
- `thinking?` (`'off' | 'minimal' | 'low' | 'medium' | 'high'`): The reasoning effort the user picked.

Source: [ui/src/adapters/worker-protocol.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-protocol.ts#L29)

## Types

### `AnswerBody`

Type.

Body of `POST /interactions/:requestId/answer`.

```ts
type AnswerBody = unknown
```

Source: [ui/src/adapters/sse-protocol.ts:70](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L70)

### `ExtensionFlowStepHandler`

Type.

Answers one sign-in step of an integration flow: the value for a step that asks (`undefined` cancels).

```ts
type ExtensionFlowStepHandler = (step: FlowStep, reply: (value: string | undefined) => void) => void
```

Source: [ui/src/adapters/server-extensions-host.ts:104](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-extensions-host.ts#L104)

### `ExtensionHostModule`

Type.

A module namespace (`import * as React from 'react'`).

```ts
type ExtensionHostModule = Readonly<Record<string, unknown>>
```

Source: [ui/src/adapters/extension-modules.ts:30](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L30)

### `ExtensionHostModules`

Type.

Host modules by specifier: what the app hands the extensions' components.

```ts
type ExtensionHostModules = Readonly<Record<string, ExtensionHostModule>>
```

Source: [ui/src/adapters/extension-modules.ts:33](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L33)

### `ExtensionHostModuleSources`

Type.

Host modules by specifier, each a namespace or a loader of one (a function resolving the namespace): a
loader runs the first time a bundle imports its specifier, so the app's first load stays small.

```ts
type ExtensionHostModuleSources = Readonly<Record<string, ExtensionHostModule | (() => Promise<ExtensionHostModule>)>>
```

Source: [ui/src/adapters/extension-modules.ts:39](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L39)

### `ExtensionModuleLoad`

Type.

Loads an extension's `ui.tsx` module: its exports by name (`zidane-ui/extensions`' `ExtensionModuleLoader`).

```ts
type ExtensionModuleLoad = (extensionId: string) => Promise<Readonly<Record<string, unknown>>>
```

Source: [ui/src/adapters/extension-modules.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L24)

### `FromWorker`

Type.

A message from the worker to the page: `ready`, a live `event`, an `ask` request, `steerable`, or `done` when the run ends.

```ts
type FromWorker =
  | { type: 'ready'; v: 1 }
  | { event: ChatEvent; runId: string; type: 'event'; v: 1 }
  | { request: InteractionRequest; runId: string; type: 'ask'; v: 1 }
  | { runId: string; type: 'steerable'; v: 1 }
  | { error?: string; runId: string; type: 'done'; v: 1 }
```

Source: [ui/src/adapters/worker-protocol.ts:50](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-protocol.ts#L50)

### `RunFn`

Type.

Runs the agent for one prompt. Called once per sent prompt with a [`RunContext`](https://zidane.si/docs/reference/ui-adapters.md#RunContext). The run ends when the returned promise settles; a rejection shows as an error row.

```ts
type RunFn = (context: RunContext) => void | Promise<void>
```

Source: [ui/src/adapters/run-host.ts:51](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/run-host.ts#L51)

### `ServerClientState`

Type.

Where a [`ServerClient`](https://zidane.si/docs/reference/ui-adapters.md#ServerClient)'s connection is.

```ts
type ServerClientState =
  | { attempt: number; status: 'connecting' }
  | { hello: HelloResult; status: 'open' }
  | { attempt: number; error: string; inMs: number; status: 'retrying' }
  | { message: string; reason: ServerRefusal; status: 'refused' }
  | { status: 'closed' }
```

Source: [dist/ipc/browser.d.ts:131](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L131)

### `ServerExtensionBundle`

Type.

One extension's bundle in the folder's listing: where it is (relative to the server's origin), or why it did not bundle.

```ts
type ServerExtensionBundle =
  | { hash: string; url: string }
  | { errors: readonly string[] }
```

Source: [ui/src/adapters/extension-modules.ts:162](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L162)

### `ServerExtensionBundleLookup`

Type.

Where an extension's bundle is, from the folder's current listing (`ServerExtensionsHost.bundle`);
`fresh`: list again first (the listed URL went stale). `undefined`: it has none.

```ts
type ServerExtensionBundleLookup = (extensionId: string, opts?: { fresh?: boolean }) => Promise<ServerExtensionBundle | undefined>
```

Source: [ui/src/adapters/extension-modules.ts:168](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/extension-modules.ts#L168)

### `ServerHostOptions`

Type.

Options for [`createServerHost`](https://zidane.si/docs/reference/ui-adapters.md#createServerHost): a client to share, or what to create one with.

```ts
type ServerHostOptions = ({ client: ServerClient } | (Omit<ServerClientOptions, 'onState'> & { client?: undefined })) & { cwd?: string; onError?: (error: unknown) => void }
```

Source: [ui/src/adapters/server-host.ts:49](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/server-host.ts#L49)

### `ServerRefusal`

Type.

Why a server refused this client for good: `token` (unknown or revoked), the server's
admission refusals (`origin` not allowed, `insecure-transport`, `untrusted-proxy`, a
`scope` it may not connect with), or a `protocol` the two don't share.

```ts
type ServerRefusal =
  | 'token'
  | 'origin'
  | 'insecure-transport'
  | 'untrusted-proxy'
  | 'scope'
  | 'protocol'
```

Source: [dist/ipc/browser.d.ts:129](https://github.com/Tahul/zidane/blob/main/dist/ipc/browser.d.ts#L129)

### `StreamRecord`

Type.

One record of a session's event stream: a transcript `event`, a `run` state change, an `interaction` raised or resolved, a `session` update, or a `reset` that tells the client to hydrate again.

```ts
type StreamRecord =
  | { data: { echo?: boolean; event: ChatEvent }; type: 'event' }
  | { data: { error?: string; ok?: boolean; running: boolean }; type: 'run' }
  | { data: { request: InteractionRequest }; type: 'interaction' }
  | { data: { requestId: string }; type: 'interaction-resolved' }
  | { data: { session: ChatSession }; type: 'session' }
  | { data: Record<string, never>; type: 'reset' }
```

Source: [ui/src/adapters/sse-protocol.ts:61](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/sse-protocol.ts#L61)

### `ToWorker`

Type.

A message from the page to the worker: `send` starts a run, `interrupt` aborts it, `steer` passes guidance to it, and `answer` returns the user's reply to a request.

```ts
type ToWorker =
  | { input: WorkerRunInput; runId: string; type: 'send'; v: 1 }
  | { runId: string; type: 'interrupt'; v: 1 }
  | { message: string; runId: string; type: 'steer'; v: 1 }
  | { requestId: string; response: InteractionResponse | null; type: 'answer'; v: 1 }
```

Source: [ui/src/adapters/worker-protocol.ts:43](https://github.com/Tahul/zidane/blob/main/ui/src/adapters/worker-protocol.ts#L43)