@sigrun/shared 0.0.0-stage → 0.1.1

package/dist/commands.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The slash-command WIRE types (Task 7, pi parity) — the client-facing
+ * half of `src/server/commands.ts` (which owns the catalog runtime).
+ *
+ * This module is part of the shared leaf package (`@sigrun/shared`): the
+ * tui and webui import these shapes from here, never from server source
+ * (the load-bearing decoupling — the tui is a pure client of the wire).
+ *
+ * PURE module: no imports at all (the views-purity guard enforces this
+ * across `shared/src`).
+ *
+ * Registry header (from the server module — the catalog itself lives
+ * there): a THIN registry of command METADATA — name, description, args
+ * hint, and the §5 endpoint each command drives. Deliberately NO
+ * server-side `execute` indirection: the composer owns the client calls,
+ * the registry only tells it what exists and where it goes. Scope
+ * (controller rulings): ONLY commands mapping to EXISTING endpoints.
+ * `/login`/`/logout` are core-spec §6.4 exclusions (credentials never
+ * cross the API); `/skill:name` and prompt templates are Task 2c's
+ * `kind: "expand"` entries (no endpoint — the server expands the text
+ * at admission). `/model` and `/thinking` ARE included: both map
+ * cleanly onto `POST .../configure`'s existing
+ * `{model?, thinking?}` body (each sends exactly one of the two fields).
+ */
+/** The HTTP method + literal route path a command drives. */
+export interface SlashCommandEndpoint {
+    readonly method: "GET" | "POST" | "PATCH";
+    /**
+     * The REGISTERED route path (Fastify `:param` form, e.g.
+     * `/v1/conversations/:id/fork`) — the composer substitutes the active
+     * conversation id; `server-commands.test.ts` asserts every entry
+     * resolves against the live route table.
+     */
+    readonly path: string;
+}
+/** One slash command's catalog entry. */
+export interface SlashCommand {
+    /** The bare name (no leading slash) — the `Map` key. */
+    readonly name: string;
+    readonly description: string;
+    /** Argument shape shown in the menu/usage errors; absent = no args. */
+    readonly argsHint?: string;
+    /**
+     * The contributing extension's slug (W5 Task 3); ABSENT on core
+     * commands. An extension entry's `endpoint` is its invoke route
+     * (`POST /v1/conversations/:id/commands/<name>`) — the client POSTs
+     * there with `{args}` and renders a returned `notice`.
+     */
+    readonly extension?: string;
+    /**
+     * How the composer satisfies the command. ABSENT means `"endpoint"`
+     * (every pre-existing entry — the composer calls `endpoint`);
+     * `"expand"` (Task 2c) means the client inserts `/name ` into the
+     * composer and the SERVER expands the submitted text at admission
+     * (`/skill:name` and prompt templates) — no endpoint exists and none
+     * is needed.
+     */
+    readonly kind?: "endpoint" | "expand";
+    /** The endpoint an `endpoint`-kind entry drives; absent when `kind === "expand"`. */
+    readonly endpoint?: SlashCommandEndpoint;
+}
+/** The `GET /v1/commands` response (spec §5 response conventions). */
+export interface CommandsResponse {
+    readonly commands: readonly SlashCommand[];
+}
+/**
+ * The `POST /v1/conversations/:id/commands/:name` response (W5 Task 3,
+ * extension commands): the command's optional human-facing notice —
+ * the client renders it as a transient banner (webui) / status-bar
+ * flash (tui). An empty body means the command returned nothing to
+ * say.
+ */
+export interface CommandRunResponse {
+    readonly notice?: string;
+}

package/dist/commands.js

@@ -0,0 +1,25 @@
+/**
+ * The slash-command WIRE types (Task 7, pi parity) — the client-facing
+ * half of `src/server/commands.ts` (which owns the catalog runtime).
+ *
+ * This module is part of the shared leaf package (`@sigrun/shared`): the
+ * tui and webui import these shapes from here, never from server source
+ * (the load-bearing decoupling — the tui is a pure client of the wire).
+ *
+ * PURE module: no imports at all (the views-purity guard enforces this
+ * across `shared/src`).
+ *
+ * Registry header (from the server module — the catalog itself lives
+ * there): a THIN registry of command METADATA — name, description, args
+ * hint, and the §5 endpoint each command drives. Deliberately NO
+ * server-side `execute` indirection: the composer owns the client calls,
+ * the registry only tells it what exists and where it goes. Scope
+ * (controller rulings): ONLY commands mapping to EXISTING endpoints.
+ * `/login`/`/logout` are core-spec §6.4 exclusions (credentials never
+ * cross the API); `/skill:name` and prompt templates are Task 2c's
+ * `kind: "expand"` entries (no endpoint — the server expands the text
+ * at admission). `/model` and `/thinking` ARE included: both map
+ * cleanly onto `POST .../configure`'s existing
+ * `{model?, thinking?}` body (each sends exactly one of the two fields).
+ */
+export {};

package/dist/conversations.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The conversation list tree (Task B1, UI refresh): sidebar shaping —
+ * fork nesting, recency ordering, pinned grouping and age rendering.
+ *
+ * PURE module: no imports at all (test/views-purity.test.ts enforces
+ * this). `ListRow` is structural — both clients' wire row types fit —
+ * and the only fields read are the ones the list endpoint ships.
+ */
+export interface ListRow {
+    readonly id: number;
+    readonly name?: string;
+    readonly lastActivityAt?: string;
+    readonly parent?: {
+        readonly id: number;
+    };
+    readonly archived: boolean;
+    readonly pinned: boolean;
+}
+export interface TreeNode<R extends ListRow> {
+    readonly row: R;
+    readonly children: readonly TreeNode<R>[];
+    /** Max epoch ms over the whole subtree; 0 when nothing was ever used. */
+    readonly newestActivity: number;
+}
+export type AgeGroup = "Pinned" | "Today" | "Yesterday" | "Earlier";
+export declare function buildConversationTree<R extends ListRow>(rows: readonly R[], options: {
+    includeArchived: boolean;
+}): TreeNode<R>[];
+export declare function ageGroup(node: TreeNode<ListRow>, now: Date): AgeGroup;
+export declare function formatAge(iso: string | undefined, now: Date): string;
+export declare function displayName(row: ListRow): string;

package/dist/conversations.js

@@ -0,0 +1,94 @@
+/**
+ * The conversation list tree (Task B1, UI refresh): sidebar shaping —
+ * fork nesting, recency ordering, pinned grouping and age rendering.
+ *
+ * PURE module: no imports at all (test/views-purity.test.ts enforces
+ * this). `ListRow` is structural — both clients' wire row types fit —
+ * and the only fields read are the ones the list endpoint ships.
+ */
+/** Sort: newest first, ties by id descending. */
+function byRecency(a, b) {
+    return b.newestActivity - a.newestActivity || b.row.id - a.row.id;
+}
+/** Epoch ms of a row's activity stamp; 0 when absent or unparsable. */
+function epoch(iso) {
+    if (iso === undefined)
+        return 0;
+    const parsed = Date.parse(iso);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+export function buildConversationTree(rows, options) {
+    const nodes = new Map();
+    for (const row of rows) {
+        // `parent` is fork lineage — an ancestor by construction (set once,
+        // at fork time), so the resulting forest is acyclic.
+        if (options.includeArchived || !row.archived) {
+            nodes.set(row.id, { row, children: [] });
+        }
+    }
+    const roots = [];
+    for (const node of nodes.values()) {
+        const parent = node.row.parent;
+        const parentNode = parent === undefined ? undefined : nodes.get(parent.id);
+        if (parentNode === undefined || parentNode === node) {
+            roots.push(node);
+        }
+        else {
+            parentNode.children.push(node);
+        }
+    }
+    const toNode = (node) => {
+        const children = node.children.map(toNode).sort(byRecency);
+        const own = epoch(node.row.lastActivityAt);
+        const newestActivity = children.reduce((max, child) => Math.max(max, child.newestActivity), own);
+        return { row: node.row, children, newestActivity };
+    };
+    return roots
+        .map(toNode)
+        .sort((a, b) => Number(b.row.pinned) - Number(a.row.pinned) || byRecency(a, b));
+}
+/** Local-calendar-day distance between two instants. */
+function dayDistance(then, now) {
+    const midnight = (value) => {
+        const date = new Date(value);
+        return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+    };
+    // `round` absorbs DST's 23/25-hour days around the midnight anchor.
+    return Math.round((midnight(now) - midnight(then)) / 86_400_000);
+}
+export function ageGroup(node, now) {
+    if (node.row.pinned)
+        return "Pinned";
+    const days = dayDistance(node.newestActivity, now);
+    if (days <= 0)
+        return "Today";
+    if (days === 1)
+        return "Yesterday";
+    return "Earlier";
+}
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+export function formatAge(iso, now) {
+    if (iso === undefined)
+        return "";
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return "";
+    const age = now.getTime() - at;
+    if (age < MINUTE)
+        return "now";
+    if (age < HOUR)
+        return `${Math.floor(age / MINUTE)}m`;
+    if (age < DAY)
+        return `${Math.floor(age / HOUR)}h`;
+    if (age < 7 * DAY)
+        return `${Math.floor(age / DAY)}d`;
+    return new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric" }).format(at);
+}
+export function displayName(row) {
+    const flattened = row.name?.replace(/[\r\n]+/g, " ").trim();
+    return flattened === undefined || flattened.length === 0
+        ? "New conversation"
+        : flattened;
+}

package/dist/interactions.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The interaction seam TYPES (spec: docs/approval-ux-seams.md): the
+ * channel-neutral record shapes for "this conversation is waiting on a
+ * human decision", written by extensions through the host context and
+ * answered by channels through one generic route.
+ *
+ * The CANONICAL type declarations live here (the shared leaf package);
+ * `src/harness/interactions.ts` imports them (type-only) for the doc
+ * definitions and validation runtime. The records ride the §5 wire
+ * AS-IS (envelope + body + details — never projected), so these shapes
+ * are the channel contract too (see `@sigrun/shared/views`).
+ *
+ * Layering (strict envelope / closed primitives / opaque details):
+ *
+ * - envelope: kind, callId, status, timestamps, answer — load-bearing for
+ *   joining tool slots and lifecycle arbitration. Strictly validated.
+ * - body: composed ONLY from the closed primitives (text, options,
+ *   fields, diff). Structurally validated; unknown body keys quarantine.
+ * - details: opaque extension-owned JSON. Never interpreted.
+ */
+import type { JsonObject } from "./json.js";
+/** Lifecycle of one interaction record (spec statuses). */
+export type InteractionStatus = "pending" | "answered" | "skipped" | "expired" | "cancelled";
+/** One choice in the `options` primitive. */
+export type InteractionOption = {
+    readonly id: string;
+    readonly label: string;
+    /** Second line under the label (pi-advisor presets, rpiv options). */
+    readonly description?: string;
+    /** Channel-schemed color/severity hint: "danger" | "warn" | "ok" | "neutral". */
+    readonly tone?: "danger" | "warn" | "ok" | "neutral";
+    /** Pre-selected by the extension's recommendation (pi-interview conviction). */
+    readonly recommended?: boolean;
+};
+/** One light-form field in the `fields` primitive. */
+export type InteractionField = {
+    readonly name: string;
+    readonly type: "string" | "number" | "boolean" | "secret";
+    readonly label?: string;
+    readonly required?: boolean;
+};
+/** The `diff` primitive: before/after content, optionally path-scoped. */
+export type InteractionDiff = {
+    readonly before: string;
+    readonly after: string;
+    readonly path?: string;
+    readonly lang?: string;
+};
+/**
+ * The interaction body: ONLY these four keys, each built only from the
+ * closed primitives. Everything else belongs in `details`.
+ */
+export type InteractionBody = {
+    /** Prose prompt body (markdown). */
+    readonly text?: string;
+    readonly options?: InteractionOption[];
+    readonly fields?: InteractionField[];
+    readonly diff?: InteractionDiff;
+};
+/** What an answer may carry: chosen ids, form values, and/or free text. */
+export type InteractionAnswer = {
+    readonly ids?: string[];
+    readonly values?: Readonly<Record<string, string | number | boolean>>;
+    readonly text?: string;
+};
+/** The strict envelope + closed-primitive body of one interaction. */
+export type InteractionRecord = {
+    /** Extension-declared kind id (e.g. "gating.confirm", "questions.form"). */
+    readonly kind: string;
+    /** Stable join key to the pi.live tool slot (`ToolCall.id`). */
+    readonly callId: string;
+    readonly status: InteractionStatus;
+    /** Epoch ms when seeded. */
+    readonly createdAt: number;
+    /** Epoch ms after which channels may show it as expired. */
+    readonly expiresAt?: number;
+    /** Epoch ms when a terminal status landed. */
+    readonly settledAt?: number;
+    readonly answer?: InteractionAnswer;
+    /** Who answered: "human" via the route, or the extension itself. */
+    readonly answeredBy?: "human" | "extension";
+    /**
+     * The answering principal's directory username (spec §5.9): stamped by
+     * the answer route from `request.principal.user` — host-assigned, never
+     * model-asserted. Absent on the naive single-operator path (no user).
+     */
+    readonly answeredByUser?: string;
+    readonly body?: InteractionBody;
+    /** Opaque extension-owned payload; rendered collapsed, never interpreted. */
+    readonly details?: JsonObject;
+};

package/dist/interactions.js

@@ -0,0 +1,21 @@
+/**
+ * The interaction seam TYPES (spec: docs/approval-ux-seams.md): the
+ * channel-neutral record shapes for "this conversation is waiting on a
+ * human decision", written by extensions through the host context and
+ * answered by channels through one generic route.
+ *
+ * The CANONICAL type declarations live here (the shared leaf package);
+ * `src/harness/interactions.ts` imports them (type-only) for the doc
+ * definitions and validation runtime. The records ride the §5 wire
+ * AS-IS (envelope + body + details — never projected), so these shapes
+ * are the channel contract too (see `@sigrun/shared/views`).
+ *
+ * Layering (strict envelope / closed primitives / opaque details):
+ *
+ * - envelope: kind, callId, status, timestamps, answer — load-bearing for
+ *   joining tool slots and lifecycle arbitration. Strictly validated.
+ * - body: composed ONLY from the closed primitives (text, options,
+ *   fields, diff). Structurally validated; unknown body keys quarantine.
+ * - details: opaque extension-owned JSON. Never interpreted.
+ */
+export {};

package/dist/jobs.d.ts

@@ -0,0 +1,109 @@
+/**
+ * §8.2 job wire types — THE jobs channel contract.
+ *
+ * Part of the shared leaf package (`@sigrun/shared`): the server owns
+ * the runtime half (src/jobs/* — validation, schedule math) and both
+ * clients (webui, tui) import these types directly. Like every wire
+ * module, imports are TYPE-ONLY from sibling shared modules (the
+ * views-purity guard enforces this), so the module erases at compile
+ * time and contributes no runtime.
+ *
+ * The shapes follow spec §8.2's schedule/action grammar verbatim:
+ * a schedule is exactly one of a 5-field `cron` (with an optional IANA
+ * `timezone`, defaulting to the server timezone), an `every` interval
+ * (`^\\d+(s|m|h|d)$`, minimum 60 s), or a one-shot ISO 8601 `at`; an
+ * action is a `prompt` (optionally pinning the model/thinking of a NEW
+ * conversation, or targeting a fixed conversation id) or a `task`
+ * (a registered extension task name plus optional JSON input).
+ */
+import type { Sharing } from "./access.js";
+import type { JsonValue } from "./json.js";
+export type { JsonValue };
+/** When a job fires: a cron (5-field, TZ-aware), an interval, or one instant. */
+export type JobSchedule = {
+    cron: string;
+    timezone?: string;
+} | {
+    every: string;
+} | {
+    at: string;
+};
+/** What a job does when it fires (spec §8.2). */
+export type JobAction = {
+    kind: "prompt";
+    prompt: string;
+    model?: string;
+    thinking?: string;
+    conversation: "new" | number;
+    runSharing?: Sharing;
+    /**
+     * Gateway delivery targets (spec §8.0 C7): 1–8 strings, each
+     * 1–256 chars, valid ONLY with `conversation: "new"` — a
+     * conversation bound to a chat already delivers there. Core
+     * validates SHAPE only; the target grammar belongs to the
+     * gateway. `fire.ts` stamps it onto the run conversation's
+     * SessionMeta so the gateway's runSettled delivery reads it.
+     */
+    deliver?: string[];
+} | {
+    kind: "task";
+    task: string;
+    input?: JsonValue;
+};
+/** A job's declared shape — what every source (api/file/extension) supplies. */
+export type JobSpec = {
+    name: string;
+    schedule: JobSchedule;
+    action: JobAction;
+    overlap?: "skip" | "queue";
+    catchUp?: "once" | "none";
+    enabled?: boolean;
+    owner?: string;
+    sharing?: Sharing;
+};
+/** One job as `GET /v1/jobs` serves it (the list row and the detail). */
+export type JobWire = {
+    id: string;
+    name: string;
+    source: "api" | "file" | "extension";
+    owner?: string;
+    sharing?: Sharing;
+    schedule: JobSchedule;
+    action: JobAction;
+    enabled: boolean;
+    state: "waiting" | "firing" | "disabled" | "blocked";
+    reason?: string;
+    version: number;
+    nextRun?: string;
+    lastRun?: JobRunWire;
+    lastError?: string;
+    access: "read" | "write";
+};
+/** One fire of a job, as the job's `lastRun` copy serves it. */
+export type JobRunWire = {
+    jobId: string;
+    version: number;
+    fireAt: string;
+    manual: boolean;
+    conversationId?: number;
+    taskId?: number;
+    outcome: "running" | "succeeded" | "failed" | "skipped";
+    startedAt: string;
+    settledAt?: string;
+    error?: string;
+};
+/**
+ * One immutable revision of a job (`sigrun.job.revision`, keyed
+ * `<jobId>:<version>`): the spec exactly as it stood at that version.
+ */
+export type JobRevisionWire = {
+    jobId: string;
+    version: number;
+    source: "api" | "file" | "extension";
+    spec: JobSpec;
+    owner?: string;
+    sharing?: Sharing;
+    enabled: boolean;
+    changedAt: string;
+    changedBy: string;
+};

package/dist/jobs.js

@@ -0,0 +1,19 @@
+/**
+ * §8.2 job wire types — THE jobs channel contract.
+ *
+ * Part of the shared leaf package (`@sigrun/shared`): the server owns
+ * the runtime half (src/jobs/* — validation, schedule math) and both
+ * clients (webui, tui) import these types directly. Like every wire
+ * module, imports are TYPE-ONLY from sibling shared modules (the
+ * views-purity guard enforces this), so the module erases at compile
+ * time and contributes no runtime.
+ *
+ * The shapes follow spec §8.2's schedule/action grammar verbatim:
+ * a schedule is exactly one of a 5-field `cron` (with an optional IANA
+ * `timezone`, defaulting to the server timezone), an `every` interval
+ * (`^\\d+(s|m|h|d)$`, minimum 60 s), or a one-shot ISO 8601 `at`; an
+ * action is a `prompt` (optionally pinning the model/thinking of a NEW
+ * conversation, or targeting a fixed conversation id) or a `task`
+ * (a registered extension task name plus optional JSON input).
+ */
+export {};

package/dist/json.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The JSON value mirrors (the shared leaf's local declarations of
+ * chord/pi-durable's `JsonValue`/`JsonObject`).
+ *
+ * Declared LOCALLY — never imported — so every shared module stays
+ * import-free at runtime (the shared-package invariant: the webui
+ * compiles DOM-only against these files, and a dependency import would
+ * drag a module only one client can resolve). The shapes mirror
+ * `@earendil-works/chord`'s `JsonValue` exactly (structural identity —
+ * the server-side doc definitions accept records built from these types
+ * wherever pi-durable's own `JsonObject` is required).
+ */
+/** A strict-JSON value: primitives, arrays, or a JSON object. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** JSON object used as the root of every durable document. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};

package/dist/json.js

@@ -0,0 +1,13 @@
+/**
+ * The JSON value mirrors (the shared leaf's local declarations of
+ * chord/pi-durable's `JsonValue`/`JsonObject`).
+ *
+ * Declared LOCALLY — never imported — so every shared module stays
+ * import-free at runtime (the shared-package invariant: the webui
+ * compiles DOM-only against these files, and a dependency import would
+ * drag a module only one client can resolve). The shapes mirror
+ * `@earendil-works/chord`'s `JsonValue` exactly (structural identity —
+ * the server-side doc definitions accept records built from these types
+ * wherever pi-durable's own `JsonObject` is required).
+ */
+export {};

package/dist/live.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The `docs["pi.live"]` LiveState narrowing (gateway plan 1, Task 1).
+ *
+ * `pi.live` is the harness's live-run document — `run` while a generation
+ * is in flight, `generation.message` (the committed throttled partial of
+ * the response), `tools` (live tool slots), `compactions`, and
+ * `compactionFailure` (shape per pi-durable dist/harness/live.d.ts).
+ * `ConversationViewBase` types `docs` values as `JsonObject`: named
+ * LiveDocs are narrowed by their consumers, and this module is that
+ * narrowing for `pi.live` — shared by the webui, the tui and the gateway
+ * engine so every reader narrows the doc identically.
+ *
+ * Purity: a shared wire module — `import type` sibling-only (the purity
+ * guard in test/views-purity.test.ts); the runtime functions below are
+ * dependency-free so both clients (DOM-only webui, NodeNext tui) and the
+ * server read the same doc the same way.
+ */
+import type { ConversationViewBase } from "./views.js";
+/** One live tool slot of `docs["pi.live"]` (the LiveState tools list). */
+export interface LiveToolSlotWire {
+    readonly callId: string;
+    readonly name: string;
+    readonly status: string;
+    readonly output?: string;
+}
+/**
+ * The `docs["pi.live"]` LiveState doc, narrowed to what the channels read:
+ * `run` (present exactly while busy — the steer field derives from it
+ * server-side), `generation.message` (the committed throttled partial of
+ * the in-flight response), `tools` (live tool slots), `compactions` (live
+ * compaction tasks), `compactionFailure` (the newest failure — a
+ * completed compaction clears it; nothing-to-compact or a fault leaves
+ * it).
+ */
+export interface LiveDocWire {
+    readonly run?: unknown;
+    readonly generation?: {
+        readonly message?: unknown;
+    };
+    readonly tools?: readonly LiveToolSlotWire[];
+    readonly compactions?: readonly unknown[];
+    readonly compactionFailure?: {
+        readonly error?: unknown;
+    };
+}
+/**
+ * The view's `pi.live` doc, or undefined when absent (idle and never-run
+ * conversations carry no doc). A cast, not a validation: the shape is
+ * pinned by the harness writer and the fail-soft reads below absorb
+ * drift.
+ */
+export declare function liveDoc(view: ConversationViewBase): LiveDocWire | undefined;
+/** The live tool slots of the view's `pi.live` doc (empty when absent). */
+export declare function liveToolSlots(view: ConversationViewBase): readonly LiveToolSlotWire[];
+/**
+ * The in-flight generation's committed partial message, or undefined when
+ * idle (or the doc shape is unexpected — fail soft to absent; upstream
+ * drift surfaces in the schema fixture first).
+ */
+export declare function liveGenerationPartial(view: ConversationViewBase): object | undefined;
+/**
+ * The in-flight generation's visible text: the partial's text blocks
+ * (`{type: "text"}`) joined with `""` — thinking and tool-call blocks
+ * contribute nothing. `""` when idle or the content is not an array; a
+ * string `content` returns as-is.
+ */
+export declare function liveGenerationText(view: ConversationViewBase): string;
+/** How many compaction tasks are live right now (0 = none). */
+export declare function liveCompactions(view: ConversationViewBase): number;
+/** The newest compaction failure's error text, when one is surfaced. */
+export declare function liveCompactionFailure(view: ConversationViewBase): string | undefined;

package/dist/live.js

@@ -0,0 +1,82 @@
+/**
+ * The `docs["pi.live"]` LiveState narrowing (gateway plan 1, Task 1).
+ *
+ * `pi.live` is the harness's live-run document — `run` while a generation
+ * is in flight, `generation.message` (the committed throttled partial of
+ * the response), `tools` (live tool slots), `compactions`, and
+ * `compactionFailure` (shape per pi-durable dist/harness/live.d.ts).
+ * `ConversationViewBase` types `docs` values as `JsonObject`: named
+ * LiveDocs are narrowed by their consumers, and this module is that
+ * narrowing for `pi.live` — shared by the webui, the tui and the gateway
+ * engine so every reader narrows the doc identically.
+ *
+ * Purity: a shared wire module — `import type` sibling-only (the purity
+ * guard in test/views-purity.test.ts); the runtime functions below are
+ * dependency-free so both clients (DOM-only webui, NodeNext tui) and the
+ * server read the same doc the same way.
+ */
+/**
+ * The view's `pi.live` doc, or undefined when absent (idle and never-run
+ * conversations carry no doc). A cast, not a validation: the shape is
+ * pinned by the harness writer and the fail-soft reads below absorb
+ * drift.
+ */
+export function liveDoc(view) {
+    // SAFETY: `docs` values are `JsonObject` by wire contract; `pi.live` is
+    // the harness's own LiveState document. The cast narrows the wire type,
+    // it does not validate — every reader below is fail-soft against drift.
+    return view.docs["pi.live"];
+}
+/** The live tool slots of the view's `pi.live` doc (empty when absent). */
+export function liveToolSlots(view) {
+    return liveDoc(view)?.tools ?? [];
+}
+/**
+ * The in-flight generation's committed partial message, or undefined when
+ * idle (or the doc shape is unexpected — fail soft to absent; upstream
+ * drift surfaces in the schema fixture first).
+ */
+export function liveGenerationPartial(view) {
+    const message = liveDoc(view)?.generation?.message;
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    return message;
+}
+/**
+ * The in-flight generation's visible text: the partial's text blocks
+ * (`{type: "text"}`) joined with `""` — thinking and tool-call blocks
+ * contribute nothing. `""` when idle or the content is not an array; a
+ * string `content` returns as-is.
+ */
+export function liveGenerationText(view) {
+    const partial = liveGenerationPartial(view);
+    if (partial === undefined)
+        return "";
+    const content = partial.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    let text = "";
+    for (const block of content) {
+        if (typeof block !== "object" || block === null)
+            continue;
+        const typed = block;
+        if (typed.type !== "text" || typeof typed.text !== "string")
+            continue;
+        text += typed.text;
+    }
+    return text;
+}
+/** How many compaction tasks are live right now (0 = none). */
+export function liveCompactions(view) {
+    return liveDoc(view)?.compactions?.length ?? 0;
+}
+/** The newest compaction failure's error text, when one is surfaced. */
+export function liveCompactionFailure(view) {
+    const failure = liveDoc(view)?.compactionFailure;
+    if (typeof failure !== "object" || failure === null)
+        return undefined;
+    const error = failure.error;
+    return typeof error === "string" && error !== "" ? error : undefined;
+}