@sigrun/tui 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -5,7 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.5.0] - 2026-11-02
+
+Version-companion release for sigrun 0.5.0 (no tui changes).
+## [0.4.2] - 2026-10-31
+
+### Fixed
+- The published tarball carries `dist/` again (`prepublishOnly` builds
+  before `npm publish` — releases 0.2.0–0.4.1 shipped without it, so
+  the `sigrun-tui` bin did not exist for installing users).
 
 ## [0.4.1] - 2026-10-31
 
@@ -49,3 +57,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   alt-screen UI with mouse support, per-keymap standard/vim/emacs
   keymaps, themes from the shared tokens, turn-grouped transcript,
   composer, help overlay, and OSC 52 clipboard.
+

package/dist/actions.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The TUI action layer (Task C3, UI refresh): a channel-neutral union of
+ * everything the keymaps, pickers, mouse regions, and slash commands can
+ * ask the shell to do. {@link TuiApp} implements {@link ActionHost} and
+ * owns the focus state the focus/move/open actions drive.
+ *
+ * Focus targets: `composer` (the pi-tui Editor), `list` (the sidebar's
+ * conversation tree), `transcript` (the pane's focusable turns). The
+ * keymap decides WHICH action a key means per focus; the app decides
+ * what the action DOES per focus.
+ */
+/** The three focusable regions. `surface` (Task 4, UI-blocks U2) is a
+ *  block surface pane (lanes/calendar/collection) — the blocks.* keys
+ *  route ONLY while it has focus. While a surface is focused the
+ *  transcript/list nav keys (y/f/e//?) are inert (the keymaps pass
+ *  them); Task 6's surface host decides any surface-side meaning for
+ *  them. */
+export type Focus = "composer" | "list" | "transcript" | "surface";
+/** Every dispatchable intent. */
+export type Action = {
+    readonly type: "focus";
+    readonly target: Focus;
+} | {
+    readonly type: "focus-cycle";
+    readonly direction: 1 | -1;
+} | {
+    readonly type: "move";
+    readonly delta: number;
+} | {
+    readonly type: "page";
+    readonly direction: 1 | -1;
+    readonly half: boolean;
+} | {
+    readonly type: "edge";
+    readonly to: "top" | "bottom";
+} | {
+    readonly type: "prompt-jump";
+    readonly delta: 1 | -1;
+} | {
+    readonly type: "toggle-fold";
+} | {
+    readonly type: "open";
+} | {
+    readonly type: "copy";
+} | {
+    readonly type: "fork-here";
+} | {
+    readonly type: "edit-here";
+} | {
+    readonly type: "edit-in-vim";
+} | {
+    readonly type: "picker";
+    readonly kind: "conversation" | "model" | "command";
+} | {
+    readonly type: "new-conversation";
+} | {
+    readonly type: "cycle-thinking";
+} | {
+    readonly type: "search";
+    readonly direction: "forward" | "backward";
+} | {
+    readonly type: "search-next";
+    readonly reverse: boolean;
+} | {
+    readonly type: "answer-interaction";
+} | {
+    readonly type: "cancel-run";
+} | {
+    readonly type: "redraw";
+} | {
+    readonly type: "quit";
+} | {
+    readonly type: "help";
+} | {
+    readonly type: "command-line";
+} | {
+    readonly type: "run-command";
+    readonly line: string;
+}
+/** Pick up the item under the cursor (m / M-m). */
+ | {
+    readonly type: "blocks.pickUp";
+}
+/** Drop the picked-up item at its placement (Enter). */
+ | {
+    readonly type: "blocks.drop";
+}
+/** Cancel the pick-up (Esc). */
+ | {
+    readonly type: "blocks.cancelMove";
+}
+/** Toggle the selection of the item under the cursor (Space). */
+ | {
+    readonly type: "blocks.select";
+}
+/** Open the action menu (`.` — bulk actions, "Move to…"). */
+ | {
+    readonly type: "blocks.actionMenu";
+}
+/** Toggle the checkable field of the item under the cursor (x). */
+ | {
+    readonly type: "blocks.check";
+}
+/** Previous calendar range ([). */
+ | {
+    readonly type: "blocks.rangePrev";
+}
+/** Next calendar range (]). */
+ | {
+    readonly type: "blocks.rangeNext";
+}
+/** Return the calendar range to today (t). */
+ | {
+    readonly type: "blocks.today";
+};
+/** The dispatch surface {@link TuiApp} implements. */
+export interface ActionHost {
+    dispatch(action: Action): Promise<void>;
+}

package/dist/actions.js

@@ -0,0 +1,12 @@
+/**
+ * The TUI action layer (Task C3, UI refresh): a channel-neutral union of
+ * everything the keymaps, pickers, mouse regions, and slash commands can
+ * ask the shell to do. {@link TuiApp} implements {@link ActionHost} and
+ * owns the focus state the focus/move/open actions drive.
+ *
+ * Focus targets: `composer` (the pi-tui Editor), `list` (the sidebar's
+ * conversation tree), `transcript` (the pane's focusable turns). The
+ * keymap decides WHICH action a key means per focus; the app decides
+ * what the action DOES per focus.
+ */
+export {};

package/dist/api.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The TUI's typed §5 HTTP client (Task 4).
+ *
+ * Wire shapes are the channel contract — imported from the
+ * `@sigrun/shared` package (`views`, plus `SessionMeta`/`SlashCommand`
+ * siblings), the single source of truth shared with the server and the
+ * webui (build-and-webui Task 1: the tui is a pure client of the wire,
+ * never a relative importer of server source).
+ *
+ * Identity seam (Task 2): the configured `user` rides EVERY request as the
+ * `X-Sigrun-User` header; absent/empty user omits it entirely — the
+ * server's naive mode. The bearer token (Task 7) rides every request as
+ * `authorization: Bearer <token>` when configured.
+ *
+ * Fail-loud: a non-2xx rejects with a {@link SigrunApiError} carrying the
+ * status and the server's parsed error body (`{error: ...}`), never a
+ * silent `undefined` the UI could misrender as empty state.
+ */
+import type { CommandRunResponse, CommandsResponse } from "@sigrun/shared/commands";
+import type { JobsResponse, JobRunResponse } from "@sigrun/shared/views";
+import type { JobRevisionWire, JobRunWire } from "@sigrun/shared/jobs";
+import type { SessionMeta, SessionMetaPatch } from "@sigrun/shared/session-meta";
+import type { AbortResponse, AmbientList, CompactResponse, ConfigureResponse, ConversationCreateResponse, ConversationForkResponse, ConversationList, ConversationViewWire, InteractionAnswered, InteractionList, InteractionWire, MetaResponse, ModelsResponse, SettingsResponse, SettingsSectionsResponse, SubmissionResponse, WhoamiResponse } from "@sigrun/shared/views";
+export type { AbortResponse, AmbientList, AmbientWire, CompactResponse, ConfigureResponse, ConversationCreateResponse, ConversationForkResponse, ConversationList, ConversationSummary, ConversationViewWire, InteractionAnswered, InteractionList, InteractionWire, MetaResponse, ModelEntry, ModelsResponse, SettingsResponse, SettingsSectionsResponse, SettingsSectionEntry, SettingsSectionIndexEntry, SubmissionResponse, WhoamiResponse, } from "@sigrun/shared/views";
+export type { CommandRunResponse, CommandsResponse, SlashCommand } from "@sigrun/shared/commands";
+export type { JobSpec, JobSchedule, JobAction, JobWire, JobRunWire, JobRevisionWire, } from "@sigrun/shared/jobs";
+export type { JobsResponse, JobRunResponse } from "@sigrun/shared/views";
+export type { ExtensionsResponse, ExtensionInfo, ExtensionSurfaceInfo } from "@sigrun/shared/views";
+export type { SessionMeta, SessionMetaPatch } from "@sigrun/shared/session-meta";
+/**
+ * One answer to a pending interaction (the ONE generic route's body).
+ * U6 Task 2 (ruling 20): `{values}` ONLY — every field's value under
+ * its name; the legacy `{ids, text}` shapes are a 400 server-side.
+ */
+export interface InteractionAnswerInput {
+    readonly values: Readonly<Record<string, import("@sigrun/shared/blocks").JsonValue>>;
+}
+/** `GET /v1/jobs/:id/runs`: the job's runs, newest first. */
+export interface JobRunsResponse {
+    readonly runs: readonly JobRunWire[];
+}
+/** `GET /v1/jobs/:id/revisions`: the job's revisions, newest first. */
+export interface JobRevisionsResponse {
+    readonly revisions: readonly JobRevisionWire[];
+}
+/** The `whenBusy` admission modes the server accepts (spec §7 item 3). */
+export type WhenBusyMode = "steer" | "followUp" | "reject";
+/** A non-2xx response: status + the server's parsed error body. */
+export declare class SigrunApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(method: string, path: string, status: number, body: unknown);
+}
+/**
+ * The user-facing name of an auth failure (Task 5): a 401
+ * {@link SigrunApiError} maps to {@link AUTH_FAILURE_MESSAGE} — the one
+ * string that tells the operator WHAT is wrong and WHERE to fix it (the
+ * token is missing, expired, or revoked; a new one is minted in the
+ * webui's Settings → API tokens section). Anything else (a different
+ * status, a non-api error) maps to `undefined`: the caller keeps its
+ * generic error path. Shared by the startup exit (`tuiStartupMessage`),
+ * the pane's error lines (`describeCommandError`), and the SSE
+ * reconnect policy (a 401 never retries — a credential cannot recover
+ * by reconnecting).
+ */
+export declare const AUTH_FAILURE_MESSAGE = "authentication failed (401): SIGRUN_TOKEN is missing, expired, or revoked \u2014 create one in Settings \u2192 API tokens";
+/** @see {@link AUTH_FAILURE_MESSAGE} */
+export declare function authFailureMessage(error: unknown): string | undefined;
+/** The fetch surface the client needs (the real thing or a test stub). */
+export type FetchLike = (input: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface SigrunClientOptions {
+    /**
+     * The server's origin (e.g. `http://127.0.0.1:PORT`) — the TUI is a
+     * remote client, so unlike the webui there is no same-origin default.
+     */
+    readonly baseUrl: string;
+    /**
+     * The `X-Sigrun-User` identity (Task 2). Absent/empty/whitespace → the
+     * header is omitted entirely (the server's naive mode).
+     */
+    readonly user?: string;
+    /**
+     * A bearer token (Task 7): rides EVERY request as
+     * `authorization: Bearer <token>`. Absent/empty/whitespace → omitted.
+     * The launcher threads `SIGRUN_TOKEN` here — the env beats tui.json.
+     */
+    readonly token?: string;
+    /** Injected for tests; defaults to the ambient `fetch`. */
+    readonly fetch?: FetchLike;
+}
+/** The typed §5 client. See {@link SigrunClientOptions} for the seams. */
+import type { ExtensionsResponse } from "@sigrun/shared/views";
+export declare class SigrunClient {
+    #private;
+    /** The server's origin (the settings view's surface transports). */
+    get baseUrl(): string;
+    /** The auth token (the surface transports' bearer). */
+    get token(): string | undefined;
+    /** The `X-Sigrun-User` identity (the surface transports' header). */
+    get user(): string | undefined;
+    /**
+     * The client's fetch (the settings view's surface transports — a
+     * test-injected fetch must carry the section loads too). The
+     * parameter/return types widen to the ambient `fetch` signature;
+     * the declared {@link FetchLike} is the consumed subset.
+     */
+    get fetch(): typeof globalThis.fetch;
+    constructor(options: SigrunClientOptions);
+    /** `GET /v1/conversations` — all durable conversations (Task 3). */
+    listConversations(): Promise<ConversationList>;
+    /** `GET /v1/conversations/:id` — the full wire view (one frame). */
+    getConversation(id: number): Promise<ConversationViewWire>;
+    /** `POST /v1/conversations` — the new id plus its first view frame. */
+    createConversation(): Promise<ConversationCreateResponse>;
+    /** `POST /v1/conversations/:id/fork` (absent `at` = the newest entry). */
+    forkConversation(id: number, at?: number): Promise<ConversationForkResponse>;
+    /**
+     * `POST /v1/conversations/:id/submissions` — plain text input; 202 at
+     * ADMISSION (§7.1) with the record as it stands. The TUI is
+     * fire-and-forget: the reply arrives as view revisions on the stream,
+     * not from this response.
+     */
+    submit(id: number, text: string, whenBusy?: WhenBusyMode): Promise<SubmissionResponse>;
+    /** `POST /v1/conversations/:id/abort`. */
+    abort(id: number): Promise<AbortResponse>;
+    /**
+     * `POST /v1/conversations/:id/compact` — admits a manual compaction;
+     * the summary entry arrives later as a view revision on the stream.
+     */
+    compact(id: number, instructions?: string): Promise<CompactResponse>;
+    /** `GET /v1/conversations/:id/meta`. */
+    getMeta(id: number): Promise<SessionMeta>;
+    /** `PATCH /v1/conversations/:id/meta` — merges; resolves to the new meta. */
+    patchMeta(id: number, patch: SessionMetaPatch): Promise<SessionMeta>;
+    /** `GET /v1/conversations/:id/interactions` — pending interactions. */
+    listInteractions(id: number): Promise<InteractionList>;
+    /** `GET .../interactions/:callId` — one record in ANY status (the
+     *  settle-refetch path: an answer that lands on an already-settled
+     *  record (404 not_pending) refetches here and renders it read-only). */
+    getInteraction(id: number, callId: string): Promise<InteractionWire>;
+    /** `POST .../interactions/:callId/answer` — the ONE generic answer route. */
+    answerInteraction(id: number, callId: string, answer: InteractionAnswerInput): Promise<InteractionAnswered>;
+    /** `GET /v1/conversations/:id/ambient`. */
+    getAmbient(id: number): Promise<AmbientList>;
+    /** `GET /v1/commands` — the slash-command catalog (a boot constant). */
+    getCommands(): Promise<CommandsResponse>;
+    /** `GET /v1/extensions` — the loaded-extension inventory (U3 Task 5:
+     *  the sidebar's Views group + panels read the declared surfaces). */
+    listExtensions(): Promise<ExtensionsResponse>;
+    /**
+     * `POST /v1/conversations/:id/commands/:name` — invoke an extension
+     * slash command (W5 Task 3): the server runs the winning declaration
+     * and resolves with its optional `{notice}`.
+     */
+    runCommand(id: number, name: string, args?: string): Promise<CommandRunResponse>;
+    /** `GET /v1/settings` — the effective settings (absent file = `{}`). */
+    getSettings(): Promise<SettingsResponse>;
+    /**
+     * `GET /v1/settings/sections` (UI-blocks U4 Task 4): the settings
+     * panel's nav list + search index in one payload.
+     */
+    listSettingsSections(): Promise<SettingsSectionsResponse>;
+    /** `GET /v1/auth/whoami` — the resolved principal (the settings
+     *  callout's admin gate). */
+    whoami(): Promise<WhoamiResponse>;
+    /** `GET /v1/meta` — the boot facts (the settings callout's
+     *  `supervised` read). */
+    getBootMeta(): Promise<MetaResponse>;
+    /**
+     * `POST /v1/admin/restart` (admin; U4 Task 2, spec §13.3): resolves
+     * once the server answered 202 (the restart begins after the reply);
+     * rejects on 403/409 (the restart never began).
+     */
+    requestRestart(): Promise<void>;
+    /**
+     * `GET /readyz` readiness probe (U4 Task 2): `true` only on a 200.
+     * The restart-recovery poll rides this; a connection-level failure
+     * (the process mid-restart) resolves `false`, never throws.
+     */
+    checkReady(): Promise<boolean>;
+    /** `GET /v1/models` — the chat-model catalog (the model picker's items). */
+    listModels(): Promise<ModelsResponse>;
+    /**
+     * `POST /v1/conversations/:id/configure` — change the model and/or
+     * thinking level (T9c-i). At least one field is required (the server
+     * rejects an empty change as `invalid_body`).
+     */
+    configure(id: number, body: {
+        readonly model?: string;
+        readonly thinking?: string;
+    }): Promise<ConfigureResponse>;
+    /** `GET /v1/jobs` — the caller-visible jobs (`/jobs`, W4 Task 5). */
+    listJobs(): Promise<JobsResponse>;
+    /** `POST /v1/jobs/:id/run` — fire a job now (write access). */
+    runJob(id: string): Promise<JobRunResponse>;
+    /** `GET /v1/jobs/:id/runs` — the job's runs, newest first. */
+    listJobRuns(id: string, limit?: number): Promise<JobRunsResponse>;
+    /** `GET /v1/jobs/:id/revisions` — the job's revisions, newest first. */
+    listJobRevisions(id: string): Promise<JobRevisionsResponse>;
+}

package/dist/api.js

@@ -0,0 +1,282 @@
+/**
+ * The TUI's typed §5 HTTP client (Task 4).
+ *
+ * Wire shapes are the channel contract — imported from the
+ * `@sigrun/shared` package (`views`, plus `SessionMeta`/`SlashCommand`
+ * siblings), the single source of truth shared with the server and the
+ * webui (build-and-webui Task 1: the tui is a pure client of the wire,
+ * never a relative importer of server source).
+ *
+ * Identity seam (Task 2): the configured `user` rides EVERY request as the
+ * `X-Sigrun-User` header; absent/empty user omits it entirely — the
+ * server's naive mode. The bearer token (Task 7) rides every request as
+ * `authorization: Bearer <token>` when configured.
+ *
+ * Fail-loud: a non-2xx rejects with a {@link SigrunApiError} carrying the
+ * status and the server's parsed error body (`{error: ...}`), never a
+ * silent `undefined` the UI could misrender as empty state.
+ */
+/** A non-2xx response: status + the server's parsed error body. */
+export class SigrunApiError extends Error {
+    status;
+    body;
+    constructor(method, path, status, body) {
+        super(`sigrun api: ${method} ${path} failed with status ${status}`);
+        this.name = "SigrunApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * The user-facing name of an auth failure (Task 5): a 401
+ * {@link SigrunApiError} maps to {@link AUTH_FAILURE_MESSAGE} — the one
+ * string that tells the operator WHAT is wrong and WHERE to fix it (the
+ * token is missing, expired, or revoked; a new one is minted in the
+ * webui's Settings → API tokens section). Anything else (a different
+ * status, a non-api error) maps to `undefined`: the caller keeps its
+ * generic error path. Shared by the startup exit (`tuiStartupMessage`),
+ * the pane's error lines (`describeCommandError`), and the SSE
+ * reconnect policy (a 401 never retries — a credential cannot recover
+ * by reconnecting).
+ */
+export const AUTH_FAILURE_MESSAGE = "authentication failed (401): SIGRUN_TOKEN is missing, expired, or revoked — create one in Settings → API tokens";
+/** @see {@link AUTH_FAILURE_MESSAGE} */
+export function authFailureMessage(error) {
+    if (error instanceof SigrunApiError && error.status === 401) {
+        return AUTH_FAILURE_MESSAGE;
+    }
+    return undefined;
+}
+export class SigrunClient {
+    #baseUrl;
+    #fetch;
+    #headers;
+    #token;
+    #user;
+    /** The server's origin (the settings view's surface transports). */
+    get baseUrl() {
+        return this.#baseUrl;
+    }
+    /** The auth token (the surface transports' bearer). */
+    get token() {
+        return this.#token;
+    }
+    /** The `X-Sigrun-User` identity (the surface transports' header). */
+    get user() {
+        return this.#user;
+    }
+    /**
+     * The client's fetch (the settings view's surface transports — a
+     * test-injected fetch must carry the section loads too). The
+     * parameter/return types widen to the ambient `fetch` signature;
+     * the declared {@link FetchLike} is the consumed subset.
+     */
+    get fetch() {
+        return this.#fetch;
+    }
+    constructor(options) {
+        // A trailing slash would double every route's leading one
+        // (`--server http://host/` → `//v1/...`) — normalize once.
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#fetch =
+            options.fetch ??
+                ((input, init) => globalThis.fetch(input, init));
+        const user = options.user?.trim();
+        const token = options.token?.trim();
+        this.#token = token === "" ? undefined : token;
+        this.#user = user === "" ? undefined : user;
+        this.#headers = {
+            accept: "application/json",
+            ...(user === undefined || user === "" ? {} : { "x-sigrun-user": user }),
+            ...(token === undefined || token === ""
+                ? {}
+                : { authorization: `Bearer ${token}` }),
+        };
+    }
+    async #get(path) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method: "GET",
+            headers: this.#headers,
+        });
+        if (!response.ok) {
+            throw new SigrunApiError("GET", path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    }
+    async #send(method, path, body) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method,
+            headers: { ...this.#headers, "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new SigrunApiError(method, path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    }
+    /** `GET /v1/conversations` — all durable conversations (Task 3). */
+    listConversations() {
+        return this.#get("/v1/conversations");
+    }
+    /** `GET /v1/conversations/:id` — the full wire view (one frame). */
+    getConversation(id) {
+        return this.#get(`/v1/conversations/${id}`);
+    }
+    /** `POST /v1/conversations` — the new id plus its first view frame. */
+    createConversation() {
+        return this.#send("POST", "/v1/conversations", {});
+    }
+    /** `POST /v1/conversations/:id/fork` (absent `at` = the newest entry). */
+    forkConversation(id, at) {
+        return this.#send("POST", `/v1/conversations/${id}/fork`, {
+            ...(at === undefined ? {} : { at }),
+        });
+    }
+    /**
+     * `POST /v1/conversations/:id/submissions` — plain text input; 202 at
+     * ADMISSION (§7.1) with the record as it stands. The TUI is
+     * fire-and-forget: the reply arrives as view revisions on the stream,
+     * not from this response.
+     */
+    submit(id, text, whenBusy) {
+        return this.#send("POST", `/v1/conversations/${id}/submissions`, {
+            input: [{ type: "text", text }],
+            ...(whenBusy === undefined ? {} : { whenBusy }),
+        });
+    }
+    /** `POST /v1/conversations/:id/abort`. */
+    abort(id) {
+        return this.#send("POST", `/v1/conversations/${id}/abort`, {});
+    }
+    /**
+     * `POST /v1/conversations/:id/compact` — admits a manual compaction;
+     * the summary entry arrives later as a view revision on the stream.
+     */
+    compact(id, instructions) {
+        return this.#send("POST", `/v1/conversations/${id}/compact`, {
+            ...(instructions === undefined || instructions === ""
+                ? {}
+                : { instructions }),
+        });
+    }
+    /** `GET /v1/conversations/:id/meta`. */
+    getMeta(id) {
+        return this.#get(`/v1/conversations/${id}/meta`);
+    }
+    /** `PATCH /v1/conversations/:id/meta` — merges; resolves to the new meta. */
+    patchMeta(id, patch) {
+        return this.#send("PATCH", `/v1/conversations/${id}/meta`, patch);
+    }
+    /** `GET /v1/conversations/:id/interactions` — pending interactions. */
+    listInteractions(id) {
+        return this.#get(`/v1/conversations/${id}/interactions`);
+    }
+    /** `GET .../interactions/:callId` — one record in ANY status (the
+     *  settle-refetch path: an answer that lands on an already-settled
+     *  record (404 not_pending) refetches here and renders it read-only). */
+    getInteraction(id, callId) {
+        return this.#get(`/v1/conversations/${id}/interactions/${encodeURIComponent(callId)}`);
+    }
+    /** `POST .../interactions/:callId/answer` — the ONE generic answer route. */
+    answerInteraction(id, callId, answer) {
+        return this.#send("POST", `/v1/conversations/${id}/interactions/${encodeURIComponent(callId)}/answer`, answer);
+    }
+    /** `GET /v1/conversations/:id/ambient`. */
+    getAmbient(id) {
+        return this.#get(`/v1/conversations/${id}/ambient`);
+    }
+    /** `GET /v1/commands` — the slash-command catalog (a boot constant). */
+    getCommands() {
+        return this.#get("/v1/commands");
+    }
+    /** `GET /v1/extensions` — the loaded-extension inventory (U3 Task 5:
+     *  the sidebar's Views group + panels read the declared surfaces). */
+    listExtensions() {
+        return this.#get("/v1/extensions");
+    }
+    /**
+     * `POST /v1/conversations/:id/commands/:name` — invoke an extension
+     * slash command (W5 Task 3): the server runs the winning declaration
+     * and resolves with its optional `{notice}`.
+     */
+    runCommand(id, name, args) {
+        return this.#send("POST", `/v1/conversations/${id}/commands/${encodeURIComponent(name)}`, {
+            args: args ?? "",
+        });
+    }
+    /** `GET /v1/settings` — the effective settings (absent file = `{}`). */
+    getSettings() {
+        return this.#get("/v1/settings");
+    }
+    /**
+     * `GET /v1/settings/sections` (UI-blocks U4 Task 4): the settings
+     * panel's nav list + search index in one payload.
+     */
+    listSettingsSections() {
+        return this.#get("/v1/settings/sections");
+    }
+    /** `GET /v1/auth/whoami` — the resolved principal (the settings
+     *  callout's admin gate). */
+    whoami() {
+        return this.#get("/v1/auth/whoami");
+    }
+    /** `GET /v1/meta` — the boot facts (the settings callout's
+     *  `supervised` read). */
+    getBootMeta() {
+        return this.#get("/v1/meta");
+    }
+    /**
+     * `POST /v1/admin/restart` (admin; U4 Task 2, spec §13.3): resolves
+     * once the server answered 202 (the restart begins after the reply);
+     * rejects on 403/409 (the restart never began).
+     */
+    async requestRestart() {
+        await this.#send("POST", "/v1/admin/restart", {});
+    }
+    /**
+     * `GET /readyz` readiness probe (U4 Task 2): `true` only on a 200.
+     * The restart-recovery poll rides this; a connection-level failure
+     * (the process mid-restart) resolves `false`, never throws.
+     */
+    async checkReady() {
+        try {
+            const response = await this.#fetch(`${this.#baseUrl}/readyz`, {
+                method: "GET",
+                headers: this.#headers,
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** `GET /v1/models` — the chat-model catalog (the model picker's items). */
+    listModels() {
+        return this.#get("/v1/models");
+    }
+    /**
+     * `POST /v1/conversations/:id/configure` — change the model and/or
+     * thinking level (T9c-i). At least one field is required (the server
+     * rejects an empty change as `invalid_body`).
+     */
+    configure(id, body) {
+        return this.#send("POST", `/v1/conversations/${id}/configure`, body);
+    }
+    /** `GET /v1/jobs` — the caller-visible jobs (`/jobs`, W4 Task 5). */
+    listJobs() {
+        return this.#get("/v1/jobs");
+    }
+    /** `POST /v1/jobs/:id/run` — fire a job now (write access). */
+    runJob(id) {
+        return this.#send("POST", `/v1/jobs/${encodeURIComponent(id)}/run`, {});
+    }
+    /** `GET /v1/jobs/:id/runs` — the job's runs, newest first. */
+    listJobRuns(id, limit) {
+        return this.#get(`/v1/jobs/${encodeURIComponent(id)}/runs` +
+            (limit === undefined ? "" : `?limit=${limit}`));
+    }
+    /** `GET /v1/jobs/:id/revisions` — the job's revisions, newest first. */
+    listJobRevisions(id) {
+        return this.#get(`/v1/jobs/${encodeURIComponent(id)}/revisions`);
+    }
+}