@sigrun/shared 0.1.0 → 0.1.2

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

package/dist/session-meta.d.ts

@@ -25,9 +25,10 @@ export type { Sharing } from "./access.js";
  * `invalid_field`.
  *
  * Server-owned fields (`autoName`, `autoNameAttempts`,
- * `lastActivityAt`) are written by host code only (activity.ts, the A2
- * auto-namer); they are NOT patch surface — the strict validator keeps
- * rejecting them as `invalid_field`.
+ * `lastActivityAt`, `jobId`, `deliver`) are written by host code only
+ * (activity.ts, the A2 auto-namer, fire.ts's job stamp); they are NOT
+ * patch surface — the strict validator keeps rejecting them as
+ * `invalid_field`.
  */
 /** The per-conversation session metadata (spec §5). */
 export type SessionMeta = {
@@ -69,6 +70,21 @@ export type SessionMeta = {
      * patchable — the strict validator rejects the key as `invalid_field`.
      */
     lastActivityAt?: string;
+    /**
+     * Server-owned job stamp (gateway C7, spec §8.0): the id of the job
+     * whose fire created this conversation (`fire.ts` writes it inside the
+     * creating commit). Never patchable — the strict validator rejects
+     * the key as `invalid_field`.
+     */
+    jobId?: string;
+    /**
+     * Server-owned job delivery targets (gateway C7, spec §8.0): the job
+     * action's `deliver` array, stamped onto the run conversation by
+     * `fire.ts` in the creating commit — the gateway's runSettled delivery
+     * reads it to route the answer to chats. Never patchable — the
+     * strict validator rejects the key as `invalid_field`.
+     */
+    deliver?: string[];
     /**
      * The §5.9 per-resource sharing state; absent = private (owner and
      * superuser only). Patchable by the OWNER or a superuser (403

package/dist/settings.d.ts

@@ -195,6 +195,13 @@ export interface ServerSettings {
     readonly metrics?: {
         readonly public?: boolean;
     };
+    /**
+     * The development flag (spec §14.2/§14.4): `SIGRUN_DEV` (strict
+     * true/false — the spec's `SIGRUN_DEV=1` form reads as true) over this
+     * key, default `false`. Surfaces on `GET /v1/meta` (`dev`); gates the
+     * U1 blocks gallery, U3's development error bodies, and U4.
+     */
+    readonly dev?: boolean;
     /**
      * The backup target — exactly one of the two shapes (mirroring the
      * env rule: `SIGRUN_BACKUP_PATH` XOR `SIGRUN_BACKUP_S3_BUCKET`), plus

package/dist/turns.d.ts

@@ -78,10 +78,27 @@ export type Turn<E extends TurnEntry> = {
     readonly tools: readonly ToolCall[];
     readonly text: string;
     readonly lastEntryId: number;
+    /** The turn's blocks in OCCURRENCE order — the chronological
+     * view interleaves thinking / tool calls / text exactly as they
+     * happened, instead of folding everything under the final text
+     * (the grouped view's shape). Text blocks CONSECUTIVE in the
+     * stream merge into one segment (multi-block answers read as one). */
+    readonly timeline: readonly TimelineEvent[];
 } | {
     readonly kind: "other";
     readonly entry: E;
 };
+/** One chronological segment of an assistant turn. */
+export type TimelineEvent = {
+    readonly kind: "thinking";
+    readonly text: string;
+} | {
+    readonly kind: "tool";
+    readonly tool: ToolCall;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+};
 export declare function groupTurns<E extends TurnEntry>(entries: readonly E[]): Turn<E>[];
 export declare function toolPreview(name: string, args: unknown): string;
 /**

package/dist/turns.js

@@ -52,6 +52,22 @@ export function groupTurns(entries) {
     const flush = () => {
         if (pending === null)
             return;
+        // Merge consecutive text segments for the timeline (a multi-block
+        // answer reads as one run of prose, not N chopped paragraphs).
+        const timeline = [];
+        for (const event of pending.timeline) {
+            const last = timeline[timeline.length - 1];
+            if (event.kind === "text" &&
+                last !== undefined &&
+                last.kind === "text") {
+                timeline[timeline.length - 1] = {
+                    kind: "text",
+                    text: `${last.text}\n\n${event.text}`,
+                };
+                continue;
+            }
+            timeline.push(event);
+        }
         turns.push({
             kind: "assistant",
             entries: pending.entries,
@@ -59,29 +75,44 @@ export function groupTurns(entries) {
             tools: pending.tools,
             text: pending.texts.join("\n\n"),
             lastEntryId: pending.entries[pending.entries.length - 1].id,
+            timeline,
         });
         pending = null;
     };
     for (const entry of entries) {
         if (entry.kind === "pi.assistant" || entry.kind === "pi.tool-result") {
-            pending ??= { entries: [], thinking: [], tools: [], texts: [] };
+            pending ??= {
+                entries: [],
+                thinking: [],
+                tools: [],
+                texts: [],
+                timeline: [],
+            };
             pending.entries.push(entry);
             if (entry.kind === "pi.assistant") {
                 for (const message of entry.model ?? []) {
                     for (const block of blocks(message)) {
                         if (block.type === "text" && block.text !== undefined) {
                             pending.texts.push(block.text);
+                            pending.timeline.push({ kind: "text", text: block.text });
                         }
-                        else if (block.type === "thinking" && block.thinking !== undefined) {
+                        else if (block.type === "thinking" &&
+                            block.thinking !== undefined) {
                             pending.thinking.push(block.thinking);
+                            pending.timeline.push({
+                                kind: "thinking",
+                                text: block.thinking,
+                            });
                         }
                         else if (block.type === "toolCall") {
-                            pending.tools.push({
+                            const call = {
                                 callId: block.id ?? "",
                                 name: block.name ?? "",
                                 preview: toolPreview(block.name ?? "", block.arguments),
                                 isError: false,
-                            });
+                            };
+                            pending.tools.push(call);
+                            pending.timeline.push({ kind: "tool", tool: call });
                         }
                     }
                 }

package/dist/views.d.ts

@@ -388,6 +388,8 @@ export type WorkerStatus = {
 };
 /** The `GET /v1/meta` payload (spec §5; the health block is Task 9e). */
 export interface MetaResponse {
+    /** The sigrun server's own version (the package manifest). */
+    readonly version: string;
     readonly harnessVersion: string;
     readonly schemaVersion: string;
     readonly extensions: readonly {
@@ -400,6 +402,14 @@ export interface MetaResponse {
          * worker's first run.
          */
         readonly workers?: readonly WorkerStatus[];
+        /**
+         * The declared surfaces (UI-blocks U3 Task 5): the flattened
+         * view + panel rows the channels register their rail/panel
+         * entries from. Absent when the extension declared none. The
+         * meta response carries the DECLARATION (id/title/icon/
+         * placement); access filtering is render-time (§6.5).
+         */
+        readonly surfaces?: readonly ExtensionSurfaceInfo[];
     }[];
     /**
      * §5 health: pure aggregation over boot-retained §3 producers (spec
@@ -422,8 +432,15 @@ export interface MetaResponse {
         readonly memory: HealthStatus;
         /** Any contributor's §3 producer degraded → "degraded"; empty → "ok". */
         readonly providers: HealthStatus;
+        /**
+         * The gateway engine's health (gateway C2): present ONLY when an
+         * engine loaded (a no-engine deploy reports NO gateway health —
+         * degenerate "ok" by absence, never a synthesized field); the
+         * wrapped engine health (a throwing `health()` reads "degraded";
+         * a rejected `start` latches degraded until restart).
+         */
+        readonly gateway?: HealthStatus;
     };
-    /**
     /**
      * The auth block (core hardening W1 Task 6, spec §5.7): the effective
      * authenticator list (`ctx.methods` — loopback-derived or explicit) and
@@ -448,6 +465,13 @@ export interface MetaResponse {
         readonly backup: boolean;
         readonly channels: readonly string[];
     };
+    /**
+     * The development flag (spec §14.2/§14.4): `server.dev` / `SIGRUN_DEV`,
+     * default `false`. Gates the U1 blocks gallery, U3's development
+     * error bodies (validation errors in `surface_failed` responses) and
+     * U4 — a boot constant, like the rest of meta.
+     */
+    readonly dev: boolean;
     /**
      * The seam inventory (docs/approval-ux-seams.md): per extension, the
      * interaction kinds / ambient surface keys its factory declared.
@@ -573,6 +597,23 @@ export interface ExtensionInfo {
     readonly workers: readonly WorkerStatus[];
     /** The declared HTTP routes, one `{method, path, auth}` each (W5 Task 2). */
     routes?: readonly ExtensionRouteInfo[];
+    /** The declared surfaces, one `{id, title, icon, placement}` each (U3 Task 1); absent when none. */
+    surfaces?: readonly ExtensionSurfaceInfo[];
+    /**
+     * The channel ids this extension contributes (gateway C1, spec §7):
+     * present only on rows of extensions whose factory result carried
+     * `channels`; unique across every loaded extension (a collision
+     * quarantines the later loader). Absent when the extension declared
+     * none.
+     */
+    readonly channels?: readonly string[];
+    /**
+     * The inert marker (gateway C2): `"no gateway"` on rows of
+     * extensions that contributed `channels` while NO gateway engine
+     * loaded — their adapters are inert (nothing drives them; one boot
+     * warning says so). Absent everywhere else.
+     */
+    readonly inert?: "no gateway";
     /**
      * Built-in extensions (Task 2, pi parity): `true` marks a core-shipped
      * built-in (codemode / MCP / tool search); ABSENT on configured
@@ -591,6 +632,26 @@ export interface ExtensionRouteInfo {
     readonly path: string;
     readonly auth: string;
 }
+/**
+ * One `GET /v1/extensions` surface row (UI-blocks U3 Task 1, spec
+ * §7.1): the extension-declared views and panels — what the channels'
+ * rail (views) and right panel (panels) register from. One row per
+ * declared surface, in declaration order (views before panels).
+ */
+export interface ExtensionSurfaceInfo {
+    readonly id: string;
+    readonly title: string;
+    readonly icon: string;
+    /** The declared placement; `settings` sections (§13.3) are not in this workstream. */
+    readonly placement: "view" | "panel";
+    /** The declared refresh cadence (spec §7.1); channels refetch data on
+     *  this interval while the surface is visible. Absent → no cadence. */
+    readonly refreshMs?: number;
+    /** §7.3 shared-data flag: a sharedData surface's `since` fetches may
+     *  answer with `ops` and NO `data` — channels fall back to a full
+     *  fetch (ops folding is U1). Absent → per-instance data. */
+    readonly sharedData?: boolean;
+}
 /** The `GET /v1/extensions` payload (spec §7.7). */
 export interface ExtensionsResponse {
     readonly extensions: readonly ExtensionInfo[];
@@ -614,7 +675,11 @@ export type { SessionMeta, SessionMetaPatch } from "./session-meta.js";
  * The `GET /v1/auth/whoami` payload (core hardening W1 Task 3, spec
  * §5.8): the resolved principal, verbatim. `user` is absent only under
  * the naive empty-method path with no `X-Sigrun-User` header;
- * `service` marks the env service token.
+ * `service` marks the env service token. `method` mirrors the extension
+ * contract's `Principal.method` (gateway C4b added `"host"` — an
+ * in-process host-built principal; no HTTP route ever resolves one, but
+ * the two unions stay aligned so the whoami build from a principal can
+ * never drift from the wire type).
  */
 export interface WhoamiResponse {
     readonly user?: string;
@@ -622,7 +687,7 @@ export interface WhoamiResponse {
     readonly email?: string;
     readonly admin: boolean;
     readonly service: boolean;
-    readonly method: "none" | "token" | "proxy";
+    readonly method: "none" | "token" | "proxy" | "host";
 }
 /**
  * The `GET /v1/onboarding` payload (core hardening W1 Task 4, spec
@@ -646,12 +711,19 @@ export interface OnboardingState {
  * One directory user on the wire (Task 4): the full record — emails are
  * admin-visible material and the routes that serve this type are
  * admin-gated. `createdAt` is epoch ms.
+ *
+ * `admin` is the STORED flag (the users-admin UI toggles it); the proxy
+ * group grant rides separately as `groupAdmin` (gateway C8): effective
+ * admin is `admin || groupAdmin === true`, and the last-admin guard
+ * counts `admin` alone.
  */
 export interface UserWire {
     readonly user: string;
     readonly name?: string;
     readonly email?: string;
     readonly admin: boolean;
+    /** The persisted proxy-group grant — present only under `adminGroups`. */
+    readonly groupAdmin?: boolean;
     readonly createdAt: number;
     readonly source: "proxy" | "invite" | "cli";
 }
@@ -739,4 +811,12 @@ export type HostEventWire = {
     /** W4 Task 4 (§8.4): the changed job's summary, WITHOUT `access` — the events stream computes `accessOf` per principal and adds it before delivery (a hidden job's event is withheld entirely). */
     readonly type: "job.changed";
     readonly job: Omit<JobWire, "access">;
+} | {
+    /** UI-blocks U3 Task 4 (spec §7.3): one surface instance changed. `k` is the hashed instance key (sha256(slug + "\0" + id + "\0" + key) hex) — the event NEVER carries params or data (render/data are principal-specific; the watcher refetches as itself). Delivered only to streams in the watcher registry whose stored access is not `"none"`. */
+    readonly type: "surface.changed";
+    readonly slug: string;
+    readonly id: string;
+    readonly k: string;
+    readonly rev: number;
+    readonly treeRev: number;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sigrun/shared",
-	"version": "0.1.0",
-	"description": "sigrun shared leaf package — theme tokens, turn/conversation shaping, and the channel wire types (pure leaf, zero dependencies)",
+	"version": "0.1.2",
+	"description": "sigrun shared leaf package \u2014 theme tokens, turn/conversation shaping, and the channel wire types (pure leaf, zero dependencies)",
 	"type": "module",
 	"exports": {
 		"./themes": {
@@ -44,6 +44,10 @@
 			"types": "./dist/views.d.ts",
 			"default": "./dist/views.js"
 		},
+		"./live": {
+			"types": "./dist/live.d.ts",
+			"default": "./dist/live.js"
+		},
 		"./view-delta": {
 			"types": "./dist/view-delta.d.ts",
 			"default": "./dist/view-delta.js"
@@ -51,6 +55,10 @@
 		"./jobs": {
 			"types": "./dist/jobs.d.ts",
 			"default": "./dist/jobs.js"
+		},
+		"./blocks": {
+			"types": "./dist/blocks/index.d.ts",
+			"default": "./dist/blocks/index.js"
 		}
 	},
 	"scripts": {