@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/server/session-meta.js

@@ -0,0 +1,247 @@
+/**
+ * The session-meta document (spec §5): conversation-scoped sidebar state.
+ *
+ * SPLIT (build-and-webui Task 1): the WIRE types (`SessionMeta`,
+ * `SessionMetaPatch`, `SessionMetaPatchError`) live in the
+ * `@sigrun/shared` package (`shared/src/session-meta.ts` — the canonical
+ * declarations both clients import); this module owns the document and
+ * patch RUNTIME and re-exports the types for server-side importers.
+ *
+ * One latest-only singleton doc per conversation (kind
+ * `"sigrun.session-meta"`): pin/tag/archive flags, the composer draft
+ * (survives reloads — `draft.attachments` are workspace-relative paths from
+ * the uploads endpoint), the session source, the user-facing session name
+ * (T5d), and the multi-user `owner` seam (spec §5: "exists in schema from
+ * day 1; the flow does not" — written by the auth hook at create/fork/
+ * import and read by the listing route; still no interactive flow in v1).
+ *
+ * Docs are standalone tokens: `defineDoc` needs no registry install (a
+ * gated extension's policy doc is the reference pattern). Reads serve `DEFAULT_SESSION_META` when the doc was
+ * never written; only a PATCH materializes it — a read that wrote would
+ * churn a doc revision on every sidebar poll, and defaults are free.
+ *
+ * PATCH semantics (spec §5: "PATCH is a MERGE; explicit `null` CLEARS a
+ * field"): each top-level key shallow-sets; `tagged` REPLACES wholesale
+ * (arrays never merge element-wise); `draft` sub-merges its own fields;
+ * `null` resets the field to its default value — `owner: null` removes the
+ * key entirely. The merge runs as a read-modify-write inside ONE
+ * `Conversation.commit` callback, so concurrent patches cannot lose each
+ * other's fields (the mutation line serializes commits).
+ *
+ * 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`.
+ */
+import { defineDoc } from "@earendil-works/pi-durable";
+import { isSharing } from "@sigrun/shared/access";
+/** What a never-written doc — and every explicit `null` clear — means. */
+export const DEFAULT_SESSION_META = {
+    pinned: false,
+    tagged: [],
+    archived: false,
+    draft: { text: "", attachments: [] },
+    source: "user",
+};
+/** The per-conversation session-meta document (latest-only singleton). */
+export const SessionMetaDoc = defineDoc({
+    kind: "sigrun.session-meta",
+    version: 1,
+    scope: "conversation",
+    history: "latest",
+    fork: "current",
+    // Defensive copy (the alias-free-ownership pattern): the tracker takes
+    // alias-free ownership of the root, so the shared DEFAULT constant must
+    // never become a tracked value.
+    initial: () => ({
+        ...DEFAULT_SESSION_META,
+        tagged: [...DEFAULT_SESSION_META.tagged],
+        draft: {
+            ...DEFAULT_SESSION_META.draft,
+            attachments: [...DEFAULT_SESSION_META.draft.attachments],
+        },
+    }),
+});
+/**
+ * Validate a PATCH body strictly (mirroring the configure endpoint):
+ * non-object/array/empty → `invalid_body`; an unknown top-level key →
+ * `invalid_field` naming the key; an unknown `draft` sub-key →
+ * `invalid_field` naming `draft.<key>`; wrong value types → `invalid_body`.
+ * `null` is valid everywhere (it is the clear operator, not a type error).
+ *
+ * Server-only keys (spec §5.9): a patch carrying `owner` or `source` is a
+ * 400 `invalid_field` EVEN when the value would once have been valid —
+ * `owner` moves via the auth hook alone, and `source` is server-owned.
+ * `sharing` is validated via `isSharing` (a malformed shape names the
+ * field).
+ */
+export function validateSessionMetaPatch(body) {
+    if (body === undefined ||
+        body === null ||
+        typeof body !== "object" ||
+        Array.isArray(body)) {
+        return { error: "invalid_body" };
+    }
+    const record = body;
+    // A patch that changes nothing is a client error, not a no-op (the
+    // configure endpoint's rule — fail loud).
+    if (Object.keys(record).length === 0) {
+        return { error: "invalid_body" };
+    }
+    const patch = {};
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        switch (key) {
+            case "pinned":
+            case "archived": {
+                if (value !== null && typeof value !== "boolean") {
+                    return { error: "invalid_body" };
+                }
+                if (key === "pinned")
+                    patch.pinned = value;
+                else
+                    patch.archived = value;
+                break;
+            }
+            case "tagged": {
+                if (value === null) {
+                    patch.tagged = null;
+                    break;
+                }
+                if (!Array.isArray(value) ||
+                    value.some((tag) => typeof tag !== "string")) {
+                    return { error: "invalid_body" };
+                }
+                patch.tagged = value;
+                break;
+            }
+            case "draft": {
+                if (value === null) {
+                    patch.draft = null;
+                    break;
+                }
+                if (typeof value !== "object" || Array.isArray(value)) {
+                    return { error: "invalid_body" };
+                }
+                const sub = {};
+                for (const subKey of Object.keys(value)) {
+                    const subValue = value[subKey];
+                    switch (subKey) {
+                        case "text":
+                            if (subValue !== null && typeof subValue !== "string") {
+                                return { error: "invalid_body" };
+                            }
+                            sub.text = subValue;
+                            break;
+                        case "attachments":
+                            if (subValue !== null &&
+                                (!Array.isArray(subValue) ||
+                                    subValue.some((path) => typeof path !== "string"))) {
+                                return { error: "invalid_body" };
+                            }
+                            sub.attachments = subValue;
+                            break;
+                        default:
+                            return { error: "invalid_field", field: `draft.${subKey}` };
+                    }
+                }
+                // An empty draft sub-object changes nothing — the same client-error
+                // rule the top-level empty body gets (fail-loud consistency).
+                if (Object.keys(sub).length === 0) {
+                    return { error: "invalid_body" };
+                }
+                patch.draft = sub;
+                break;
+            }
+            case "source":
+            case "owner": {
+                // Server-only (spec §5.9): the KEY itself is the client error,
+                // whatever the value — even a `null` clear.
+                return { error: "invalid_field", field: key };
+            }
+            case "sharing": {
+                if (value === null) {
+                    patch.sharing = null;
+                    break;
+                }
+                if (!isSharing(value)) {
+                    return { error: "invalid_field", field: "sharing" };
+                }
+                patch.sharing = value;
+                break;
+            }
+            case "name": {
+                if (value !== null && typeof value !== "string") {
+                    return { error: "invalid_body" };
+                }
+                patch.name = value;
+                break;
+            }
+            default:
+                return { error: "invalid_field", field: key };
+        }
+    }
+    return patch;
+}
+/**
+ * Apply a validated patch to a session-meta draft (the merge/clear table):
+ *
+ * - `null` resets the field to its `DEFAULT_SESSION_META` value;
+ *   `name: null` and `sharing: null` remove the key entirely.
+ * - non-null values shallow-set; `tagged` replaces wholesale.
+ * - `draft: null` resets the whole draft; a draft object sub-merges: a
+ *   sub-key present sets (or `null`-clears) that sub-field, absent sub-keys
+ *   keep the stored value.
+ *
+ * Array/object values are copied on assignment: the tracker requires
+ * alias-free roots, and the wire body must never become tracked state.
+ */
+export function applySessionMetaPatch(draft, patch) {
+    if (patch.pinned !== undefined)
+        draft.pinned = patch.pinned ?? false;
+    if (patch.archived !== undefined)
+        draft.archived = patch.archived ?? false;
+    if (patch.tagged !== undefined) {
+        draft.tagged = patch.tagged === null ? [] : [...patch.tagged];
+    }
+    // `sharing` clears the same way as `name`: absent = private, and it is
+    // not in DEFAULT_SESSION_META, so the clear target is key removal.
+    if (patch.sharing !== undefined) {
+        if (patch.sharing === null)
+            delete draft.sharing;
+        else if (patch.sharing.scope === "people") {
+            draft.sharing = {
+                scope: "people",
+                users: [...patch.sharing.users],
+                level: patch.sharing.level,
+            };
+        }
+        else if (patch.sharing.scope === "household") {
+            draft.sharing = { scope: "household", level: patch.sharing.level };
+        }
+        else {
+            draft.sharing = { scope: "private" };
+        }
+    }
+    // `name` clears the same way: absent = unnamed.
+    if (patch.name !== undefined) {
+        if (patch.name === null)
+            delete draft.name;
+        else
+            draft.name = patch.name;
+    }
+    if (patch.draft !== undefined) {
+        if (patch.draft === null) {
+            draft.draft = { text: "", attachments: [] };
+        }
+        else {
+            if (patch.draft.text !== undefined) {
+                draft.draft.text = patch.draft.text ?? "";
+            }
+            if (patch.draft.attachments !== undefined) {
+                draft.draft.attachments =
+                    patch.draft.attachments === null ? [] : [...patch.draft.attachments];
+            }
+        }
+    }
+}

package/dist/server/static.js

@@ -0,0 +1,169 @@
+/**
+ * The webui channel-bundle serving seam (Task 20, spec §4.1/§6).
+ *
+ * The M2 webui is a CHANNEL BUNDLE: deploy-time static assets (the vite build
+ * of the `webui/` workspace package), never a runtime extension, never
+ * quarantined. This module resolves the bundle from config and, when present,
+ * mounts it at `/` via `@fastify/static` with an SPA fallback:
+ *
+ * - `GET /` and asset paths serve from the bundle root (fastify-static's
+ *   default index behavior);
+ * - unknown GETs outside `/v1` serve the bundle's `index.html` so
+ *   client-side-route deep links work (the standard SPA fallback) — the
+ *   index document is read ONCE at resolve time (a channel bundle is a
+ *   deploy-time asset; a redeploy restarts the process, so there is no
+ *   per-request fs read and no stale-content window);
+ * - `/v1/*` unknowns (and non-GET unknowns) keep Fastify's default-shape 404
+ *   JSON, so the API error surface is identical with or without a bundle.
+ *
+ * Resolution (build-and-webui Task 5, at SERVE time — extension-contributed
+ * bundles only exist after the loader runs, so `createServer` threads the
+ * registry as the `contributedBundles` parameter):
+ *
+ * 1. `webui.enabled === false` → no mount, API-only (nothing else resolves
+ *    — an invalid selector under a closed gate is not an error).
+ * 2. A selector that is a NAME (`^[a-z][a-z0-9_-]*$`) matching a
+ *    contributed bundle → that bundle (its name is the reported channel).
+ * 3. A selector that is a PATH (contains `/` or `\`, or starts with `.`) →
+ *    that directory, cwd-relative; a missing `index.html` is a boot error.
+ *    A selector EQUAL to the default (`webui/dist`) keeps the DEFAULT's
+ *    semantics — the bootstrap mirror story: a mirrored default must not
+ *    flip to cwd-relative resolution.
+ * 4. Unset → the built-in default bundle; an absent default is the
+ *    supported API-only deploy (no mount, `capabilities.channels` []).
+ *
+ * An EXPLICIT selector (name or path) that resolves to nothing is a boot
+ * error naming it — a misconfigured deploy intended the webui and must not
+ * boot API-only silently. A selector that is neither path-shaped nor a
+ * valid name (uppercase, spaces, …) is a validation error.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import fastifyStatic from "@fastify/static";
+import { DEFAULT_WEBUI_BUNDLE, } from "../config.js";
+/** The channel id reported in `/v1/meta` `capabilities.channels`. */
+export const WEBUI_CHANNEL = "webui";
+/**
+ * The package root this module ships in (build-and-webui Task 3):
+ * `…/<package>/dist/server` (the built module) — `../..` is the package
+ * dir, both in the repo tree (`…/src/server` → the repo root, where
+ * `webui/dist` is the workspace's vite output) and in an installed
+ * package (`…/node_modules/sigrun/dist/server` → the package carrying
+ * `webui/dist` in its npm `files`). This is what the DEFAULT bundle
+ * anchors to — see {@link webuiBundleDir}.
+ */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+/**
+ * Where the bundle directory for a selector lives on disk (build-and-webui
+ * Task 3, plan review focus #1). EXPLICIT paths are operator-authored and
+ * resolve against the process cwd — the operator's relative path means
+ * what they wrote, wherever sigrun was started from. The DEFAULT
+ * (`webui/dist`) anchors to the PACKAGE ROOT: an installed `sigrun` CLI run
+ * from an arbitrary working directory must find the bundle it ships, not
+ * the operator's cwd (an ABSOLUTE selector never reaches the `join` — it
+ * takes the `resolve` branch, which passes it through unchanged). A
+ * selector UNSET or
+ * EQUAL to the default keeps the default's anchor — the classification
+ * that pins the bootstrap mirror story (a mirrored `webui/dist` must not
+ * read as an explicit cwd-relative selection).
+ */
+export function webuiBundleDir(config) {
+    return config.webui.bundle === undefined ||
+        config.webui.bundle === DEFAULT_WEBUI_BUNDLE
+        ? join(PACKAGE_ROOT, DEFAULT_WEBUI_BUNDLE)
+        : resolve(config.webui.bundle);
+}
+/** A name-shaped selector: the contributed-bundle grammar (spec §4.1). */
+const BUNDLE_NAME = /^[a-z][a-z0-9_-]*$/;
+/** Syntactically a PATH (spec §4.1): contains `/` or `\`, or starts with `.`. */
+function isPathSelector(selector) {
+    return (selector.includes("/") ||
+        selector.includes("\\") ||
+        selector.startsWith("."));
+}
+/**
+ * Read a bundle directory at serve time. `subject` names the selection in
+ * the boot error when the directory has no `index.html`.
+ */
+async function readBundle(dir, channel, subject) {
+    const indexPath = join(dir, "index.html");
+    if (!existsSync(indexPath)) {
+        throw new Error(`${subject} has no index.html at ${dir} — the configured webui bundle is missing (build it, or unset SIGRUN_WEBUI_BUNDLE / server.webui.bundle for an API-only deploy)`);
+    }
+    return { dir, indexHtml: await readFile(indexPath, "utf8"), channel };
+}
+/**
+ * Resolve the configured bundle (Task 5's serve-time order: enabled gate →
+ * contributed NAME → PATH → default). Returns `undefined` for an absent
+ * default-path bundle or a closed gate (the API-only deploys); THROWS on
+ * an explicit selector that resolves to nothing and on a selector that is
+ * neither path-shaped nor a valid name.
+ *
+ * `contributedBundles` is the extension-contributed registry (Task 6
+ * threads it through `createServer`; an empty registry is the no-extension
+ * deploy).
+ */
+export async function resolveWebuiBundle(config, contributedBundles = []) {
+    // 1. The gate: `false` is a positively API-only deploy — nothing
+    //    mounts and nothing else resolves (not even a bad selector).
+    if (!config.webui.enabled)
+        return undefined;
+    const selector = config.webui.bundle;
+    // 4. Unset — and the default's own value mirrored back through any
+    //    selector slot — resolves the built-in default; an absent default
+    //    is the supported API-only deploy (bare checkout, no webui build).
+    if (selector === undefined || selector === DEFAULT_WEBUI_BUNDLE) {
+        const dir = webuiBundleDir(config);
+        return existsSync(join(dir, "index.html"))
+            ? await readBundle(dir, WEBUI_CHANNEL, `webui bundle ${JSON.stringify(selector)}`)
+            : undefined;
+    }
+    // 3. A PATH: cwd-relative (operator intent), missing index.html is a
+    //    boot error — today's explicit rule.
+    if (isPathSelector(selector)) {
+        return await readBundle(resolve(selector), WEBUI_CHANNEL, `webui bundle ${JSON.stringify(selector)}`);
+    }
+    // 2. A NAME: the contributed registry. Anything else is a selector
+    //    grammar error — never guessed at.
+    if (!BUNDLE_NAME.test(selector)) {
+        throw new Error(`webui bundle selector ${JSON.stringify(selector)} is neither a contributed-bundle name (lowercase letters, digits, "-" and "_", starting with a letter) nor a path (contains "/" or "\\", or starts with ".") — fix SIGRUN_WEBUI_BUNDLE / server.webui.bundle`);
+    }
+    const contributed = contributedBundles.find((bundle) => bundle.name === selector);
+    if (contributed === undefined) {
+        const available = contributedBundles.map((bundle) => bundle.name);
+        throw new Error(`webui bundle ${JSON.stringify(selector)} matches no contributed bundle (contributed: ${available.length === 0 ? "none" : available.join(", ")}) — fix SIGRUN_WEBUI_BUNDLE / server.webui.bundle or install the extension that contributes it`);
+    }
+    return await readBundle(contributed.dir, contributed.name, `webui bundle ${JSON.stringify(selector)} contributed by extension ${JSON.stringify(contributed.extension)}`);
+}
+/**
+ * Mount the bundle at `/` and install the SPA fallback as the
+ * not-found handler. Explicit `/v1/*` (and probe) routes win over the static
+ * wildcard in Fastify's radix tree, so registration order against the API
+ * routes does not matter.
+ */
+export async function serveWebuiBundle(app, bundle) {
+    await app.register(fastifyStatic, {
+        root: bundle.dir,
+        prefix: "/",
+    });
+    app.setNotFoundHandler(async (request, reply) => {
+        const path = (request.raw.url ?? "/").split("?")[0] ?? "/";
+        if (request.method === "GET" &&
+            path !== "/v1" &&
+            !path.startsWith("/v1/")) {
+            return await reply
+                .code(200)
+                .type("text/html; charset=utf-8")
+                .send(bundle.indexHtml);
+        }
+        // Fastify's default 404 body shape, restated so the API error surface
+        // is byte-identical whether or not a bundle is mounted.
+        return await reply.code(404).send({
+            message: `Route ${request.method}:${path} not found`,
+            error: "Not Found",
+            statusCode: 404,
+        });
+    });
+}

package/dist/server/views.js

@@ -0,0 +1,71 @@
+/**
+ * §5 wire serializers (Tasks 9a–9d) — the server half of the channel
+ * contract.
+ *
+ * SPLIT (build-and-webui Task 1): the wire TYPES live in the
+ * `@sigrun/shared` package (`shared/src/views.ts` — the canonical
+ * declarations both clients import; zero-dependency leaf, the intended
+ * basis for a generated OpenAPI schema later). This module owns the
+ * RUNTIME the server needs: the single serializer every §5 endpoint
+ * that returns a conversation goes through, plus a re-export surface so
+ * server-side importers keep resolving every wire type from here.
+ *
+ * Purity (test/views-purity.test.ts): this module may import TYPES from
+ * upstream (pi-durable/pi-ai, `import type` only) and re-export the
+ * shared package's wire types, but no server/framework runtime modules,
+ * no route logic, no `node:` imports — the webui/tui never import this
+ * file at runtime, and the rule keeps it that way.
+ *
+ * Spec §5: the server serves pi-durable's NATIVE views, not a bespoke
+ * endpoint list — so the conversation wire payload IS the
+ * `ConversationView` (`{ conversation, entries, docs }`; JSON-safe by
+ * construction: JsonObject docs, EntryRecords whose `model` messages
+ * are plain pi-ai JSON) PLUS the sigrun-side `steer` field (T9d,
+ * below). The captured-schema fixture (`schema-fixture.ts`,
+ * `view-schema.json`) pins the UPSTREAM shape only — `steer` is a
+ * sigrun projection, not upstream drift — and `test/schema-drift.test.ts`
+ * trips on upstream drift while asserting the wire is exactly view +
+ * `steer`.
+ *
+ * `serializeConversationView` is the single chokepoint — including each
+ * SSE watch frame (T9d) — so the fixture continues to describe the
+ * wire.
+ */
+/**
+ * Derive the steer field from the view's own docs — no extra inspect()/
+ * storage call per frame (the watch fires per revision; the docs are
+ * already in the frame).
+ *
+ * - `busy`: `docs["pi.live"].run` present — LiveState's run control
+ *   (taskId + inputs) exists "present exactly while busy"
+ *   (pi-durable live.d.ts).
+ * - `queued`: `docs["pi.inbox"].items` length — the built-in queue of
+ *   submissions waiting for a boundary; absent doc = 0.
+ */
+function deriveSteer(view) {
+    // docs is an untyped Record<string, JsonObject>; both shapes are
+    // narrowed structurally (unexpected shapes fail soft to idle — upstream
+    // drift would surface in the schema fixture first).
+    const live = view.docs["pi.live"];
+    const busy = typeof live === "object" &&
+        live !== null &&
+        typeof live.run === "object" &&
+        live.run !== null;
+    const inbox = view.docs["pi.inbox"];
+    const items = typeof inbox === "object" && inbox !== null
+        ? inbox.items
+        : undefined;
+    const queued = Array.isArray(items) ? items.length : 0;
+    return { busy, queued };
+}
+/**
+ * Serialize one conversation view onto the wire: the upstream view plus
+ * the derived `steer` field. A shallow spread (upstream frames are
+ * immutable and JSON-safe; `conversation`/`entries`/`docs` are shared
+ * by reference — the projection adds one key, it never rewrites
+ * upstream state).
+ */
+export function serializeConversationView(view) {
+    return { ...view, steer: deriveSteer(view) };
+}
+export { JSONL_CONTENT_TYPE } from "@sigrun/shared/views";