@sigrun/shared 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+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.1.0] - 2026-10-21
+### Added
+- First published release of the shared leaf (workspace package of
+  [@sigrun/sigrun](https://github.com/sigrun-ai/sigrun)): theme tokens,
+  conversation/turn shaping, the channel wire types, session-meta,
+  commands, interactions, ambient records, access, settings, views,
+  view-delta, and jobs — the surfaces the webui, TUI, and server share.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @sigrun/shared
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The pure client-shared leaf of [sigrun](https://github.com/sigrun-ai/sigrun):
+theme tokens, turn/conversation shaping, and the channel wire types —
+consumed by the webui, the TUI, and the server. Zero runtime dependencies;
+every subpath is a types+code pair (`@sigrun/shared/themes`, `/conversations`,
+`/turns`, …) exported from `dist`.
+
+Part of the sigrun workspace; published from the repository root as
+`@sigrun/shared` (see the root `CHANGELOG.md` for release history).

package/dist/access.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-resource sharing and content access (core hardening W1 Task 5, spec
+ * §5.9 ruling 6/10: per-resource sharing; groups cut).
+ *
+ * Part of the shared leaf package (`@sigrun/shared`): the server computes
+ * access through `accessOf`, the clients render the `sharing` state — one
+ * source of truth, no drift. PURE module: no imports at all (the
+ * views-purity guard enforces this across `shared/src`).
+ *
+ * The rules, in order (first match wins):
+ *
+ * 1. superuser → write;
+ * 2. ownerless resource → household write (everyone);
+ * 3. user === owner → write;
+ * 4. household sharing with a defined user → the shared level;
+ * 5. people sharing including the user → the shared level;
+ * 6. otherwise none (hidden: 404 on every :id route, absent from lists).
+ *
+ * Anonymous callers (a principal with no user) get nothing from a shared
+ * resource: sharing widens access for identified users only (rule 4/5
+ * require a defined user), while ownerless stays open to everyone by
+ * rule 2.
+ */
+/** What a conversation's owner grants beyond themselves. */
+export type Sharing = {
+    readonly scope: "private";
+} | {
+    readonly scope: "household";
+    readonly level: "read" | "write";
+} | {
+    readonly scope: "people";
+    readonly users: string[];
+    readonly level: "read" | "write";
+};
+/** The resolved access level of a principal to one resource. */
+export type Access = "none" | "read" | "write";
+/** What accessOf needs of the caller (the server's Principal projects here). */
+export interface AccessPrincipal {
+    readonly user?: string;
+    readonly superuser?: boolean;
+}
+/**
+ * Resolve one principal's access to one resource. Rule order per the
+ * module doc; the first matching rule wins.
+ */
+export declare function accessOf(p: AccessPrincipal, r: {
+    readonly owner?: string;
+    readonly sharing?: Sharing;
+}): Access;
+/**
+ * Type guard for the wire value: every scope shape checked strictly
+ * (wrong field types are not a Sharing). An empty `people.users` list is
+ * valid (shares with nobody yet) — validation is about shape, not policy.
+ */
+export declare function isSharing(value: unknown): value is Sharing;

package/dist/access.js

@@ -0,0 +1,72 @@
+/**
+ * Per-resource sharing and content access (core hardening W1 Task 5, spec
+ * §5.9 ruling 6/10: per-resource sharing; groups cut).
+ *
+ * Part of the shared leaf package (`@sigrun/shared`): the server computes
+ * access through `accessOf`, the clients render the `sharing` state — one
+ * source of truth, no drift. PURE module: no imports at all (the
+ * views-purity guard enforces this across `shared/src`).
+ *
+ * The rules, in order (first match wins):
+ *
+ * 1. superuser → write;
+ * 2. ownerless resource → household write (everyone);
+ * 3. user === owner → write;
+ * 4. household sharing with a defined user → the shared level;
+ * 5. people sharing including the user → the shared level;
+ * 6. otherwise none (hidden: 404 on every :id route, absent from lists).
+ *
+ * Anonymous callers (a principal with no user) get nothing from a shared
+ * resource: sharing widens access for identified users only (rule 4/5
+ * require a defined user), while ownerless stays open to everyone by
+ * rule 2.
+ */
+/**
+ * Resolve one principal's access to one resource. Rule order per the
+ * module doc; the first matching rule wins.
+ */
+export function accessOf(p, r) {
+    // 1. The superuser always writes.
+    if (p.superuser === true)
+        return "write";
+    // 2. Ownerless is household-write for everyone.
+    if (r.owner === undefined)
+        return "write";
+    // 3. The owner always writes.
+    if (p.user !== undefined && p.user === r.owner)
+        return "write";
+    // 4./5. Sharing widens identified users only — an anonymous caller
+    // (no user) falls straight through to none.
+    if (p.user !== undefined && r.sharing !== undefined) {
+        if (r.sharing.scope === "household")
+            return r.sharing.level;
+        if (r.sharing.scope === "people" && r.sharing.users.includes(p.user)) {
+            return r.sharing.level;
+        }
+    }
+    // 6. Hidden.
+    return "none";
+}
+/**
+ * Type guard for the wire value: every scope shape checked strictly
+ * (wrong field types are not a Sharing). An empty `people.users` list is
+ * valid (shares with nobody yet) — validation is about shape, not policy.
+ */
+export function isSharing(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    switch (record.scope) {
+        case "private":
+            return true;
+        case "household":
+            return record.level === "read" || record.level === "write";
+        case "people":
+            return (Array.isArray(record.users) &&
+                record.users.every((user) => typeof user === "string") &&
+                (record.level === "read" || record.level === "write"));
+        default:
+            return false;
+    }
+}

package/dist/ambient.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The ambient seam TYPES (spec: docs/approval-ux-seams.md, "Ambient
+ * surfaces"): the channel-neutral record shapes for persistent
+ * read-mostly state — statusline slots and panel widgets — written by
+ * extensions through the host context and rendered by channels
+ * generically.
+ *
+ * The CANONICAL type declarations live here (the shared leaf package);
+ * `src/harness/ambient.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`).
+ *
+ * Lifecycle difference from interactions: an ambient surface is replaced
+ * repeatedly (write = FULL state replacement, never a delta) and never
+ * blocks. One slot key is owned by exactly one extension (allocation,
+ * not silent composition — the pi-zentui chrome-skin lesson).
+ *
+ * Layering mirrors the interaction seam: strict envelope (key, place,
+ * budget, refresh, expires) around a body composed only from the closed
+ * ambient primitives (line, rows, gauge, ledger), with opaque `details`.
+ */
+import type { JsonObject } from "./json.js";
+/** Where a channel places the surface. */
+export type AmbientPlace = "status" | "footer" | "panel";
+/** One widget row (primitive B). */
+export type AmbientRow = {
+    readonly id: string;
+    readonly label: string;
+    /** Channel-schemed glyph state (todo statuses, agent run states). */
+    readonly status?: string;
+    /** Severity ordering/color: 0 = severe .. 2 = quiet. */
+    readonly severity?: 0 | 1 | 2;
+    /** Folded away by default (warden's quiet verdicts). */
+    readonly quiet?: boolean;
+    readonly detail?: string;
+    /** Nesting depth for tree rendering (pi-goal-x task tree). */
+    readonly depth?: number;
+    /** Dependency ids for marker rendering (rpiv-todo blockedBy). */
+    readonly deps?: string[];
+    /** Present-continuous spinner label while the row is active. */
+    readonly spinnerLabel?: string;
+    readonly metrics?: AmbientMetrics;
+};
+/** Numeric metrics with an optional derived-format hint. */
+export type AmbientMetrics = {
+    readonly tokens?: number;
+    readonly cost?: number;
+    readonly current?: number;
+    readonly total?: number;
+    readonly completed?: number;
+    /** Derived display hint for numeric fields ("2.5k", currency) — the
+     * host-reuse lesson from every footer extension. */
+    readonly format?: "compact" | "usd" | "percent";
+};
+/** The `line` primitive: one keyed statusline/footer line, optionally segmented. */
+export type AmbientLine = {
+    readonly text: string;
+    /** Segmented composition for powerline-style slots (pi-powerline,
+     * pi-zentui): sub-segments with placement zones. */
+    readonly segments?: {
+        readonly id: string;
+        readonly text: string;
+        readonly place?: "left" | "middle" | "right";
+    }[];
+};
+/** The `gauge` primitive: live progress with optional check rows. */
+export type AmbientGauge = {
+    readonly label: string;
+    readonly percent?: number;
+    readonly phase?: string;
+    readonly elapsedMs?: number;
+    readonly recentOutput?: string[];
+    /** Check rows (pi-goal-x auditor): row-shaped, same schema as rows[]. */
+    readonly checks?: AmbientRow[];
+};
+/** One ledger entry (primitive D): append-style feed with per-entry amend. */
+export type AmbientLedgerEntry = {
+    readonly id: string;
+    readonly at: number;
+    readonly kind: string;
+    readonly summary: string;
+    readonly detail?: string[];
+};
+/** The ambient body: ONLY these keys, each from the closed primitives. */
+export type AmbientBody = {
+    readonly line?: AmbientLine;
+    readonly rows?: AmbientRow[];
+    readonly gauge?: AmbientGauge;
+    readonly ledger?: AmbientLedgerEntry[];
+};
+/** The strict envelope + closed-primitive body of one ambient surface. */
+export type AmbientRecord = {
+    /** The keyed slot id ("goal", "rpiv-todos", "fabric"). */
+    readonly key: string;
+    /** Which extension owns this key (set by the host context, not the author). */
+    readonly owner: string;
+    readonly place: AmbientPlace;
+    /** Panel row budget / line-slot width guidance (channel advisory). */
+    readonly maxRows?: number;
+    /** Overflow policy for panels (rpiv-todo's drop-completed-first rule). */
+    readonly overflow?: "drop" | "wrap" | "summarize";
+    /** Channel re-render hint between data writes (countdowns, clocks), ms. */
+    readonly refreshMs?: number;
+    /** Auto-clear rule: "never" stays until replaced with an empty body. */
+    readonly expires: "never" | "idle";
+    readonly updatedAt: number;
+    readonly body?: AmbientBody;
+    /** Opaque extension-owned payload; rendered collapsed, never interpreted. */
+    readonly details?: JsonObject;
+};

package/dist/ambient.js

@@ -0,0 +1,23 @@
+/**
+ * The ambient seam TYPES (spec: docs/approval-ux-seams.md, "Ambient
+ * surfaces"): the channel-neutral record shapes for persistent
+ * read-mostly state — statusline slots and panel widgets — written by
+ * extensions through the host context and rendered by channels
+ * generically.
+ *
+ * The CANONICAL type declarations live here (the shared leaf package);
+ * `src/harness/ambient.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`).
+ *
+ * Lifecycle difference from interactions: an ambient surface is replaced
+ * repeatedly (write = FULL state replacement, never a delta) and never
+ * blocks. One slot key is owned by exactly one extension (allocation,
+ * not silent composition — the pi-zentui chrome-skin lesson).
+ *
+ * Layering mirrors the interaction seam: strict envelope (key, place,
+ * budget, refresh, expires) around a body composed only from the closed
+ * ambient primitives (line, rows, gauge, ledger), with opaque `details`.
+ */
+export {};

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 {};