@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/server/auth/principal.js

@@ -0,0 +1,26 @@
+/**
+ * The resolved caller (core hardening W1 Task 3, spec §5.2/§5.8): what
+ * the auth pipeline stamps on every request and what `whoami` serves.
+ * `method` names the proof — the empty-method naive path ("none"), a
+ * verified token ("token"), or a trusted forward-auth header set
+ * ("proxy"). `service` marks the env service token (it skips the
+ * setup gate; it is not a directory user).
+ *
+ * SINGLE-SOURCE BRIDGE (core hardening W5 Task 2, the Task 1 review's
+ * binding carry-forward): the shape is DECLARED ONCE, on the extension
+ * contract (`Principal` in src/extension.ts, shipped as the types-only
+ * `@sigrun/sigrun/extension` subpath) — this server-side name is a re-export of
+ * it, so the pipeline, the routes, and every extension handler share
+ * one spelling that cannot drift. The bridge lives HERE (server-side)
+ * because the contract's import allowlist is pi-durable/pi-ai/shared:
+ * the contract cannot import this module.
+ */
+/**
+ * Whether `p` may act as the superuser (spec §5.8): the unauthenticated
+ * naive principal on a loopback workstation (`method "none"` with no
+ * user header — the single-operator default) or a service token.
+ * Authenticated principals are superusers only via `admin`.
+ */
+export function isSuperuser(p) {
+    return (p.method === "none" && p.user === undefined) || p.service;
+}

package/dist/server/commands.js

@@ -0,0 +1,198 @@
+/**
+ * The slash-command catalog (Task 7, pi parity): 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 (the task plan's "thin catalog over the endpoints Tasks 4–6
+ * built").
+ *
+ * SPLIT (build-and-webui Task 1): the WIRE types (`SlashCommandEndpoint`,
+ * `SlashCommand`, `CommandsResponse`) live in the `@sigrun/shared` package
+ * (`shared/src/commands.ts` — the canonical declarations both clients
+ * import); this module owns the CATALOG runtime and re-exports the types
+ * for server-side importers.
+ *
+ * Scope (controller rulings): ONLY commands mapping to EXISTING endpoints.
+ * `/login`/`/logout` are core-spec §6.4 exclusions (credentials never cross
+ * the API), and `/skill:name` + prompt templates were this slice's
+ * deferral — Task 2c resolves them as `kind: "expand"` catalog entries
+ * (no endpoint: the composer inserts `/name ` into the text and the
+ * SERVER expands it at admission; see src/commands/expand.ts). `/model`
+ * and `/thinking` ARE included: both map cleanly onto `POST
+ * .../configure`'s existing `{model?, thinking?}` body (each sends
+ * exactly one of the two fields).
+ *
+ * EXTENSION COMMANDS (core hardening W5 Task 3, spec §9.3): the core
+ * table below stays untouched; `buildCommandCatalog` merges the
+ * loader-collected extension declarations into the served list.
+ * Extension entries carry the contributing `extension` slug and the ONE
+ * server-side invoke endpoint (`POST /v1/conversations/:id/commands/
+ * <name>`) — for those, unlike core commands, the composer is a pure
+ * POST-and-render client.
+ */
+/** The catalog, keyed by bare name. */
+export const SLASH_COMMANDS = new Map([
+    {
+        name: "new",
+        description: "Start a new conversation",
+        endpoint: { method: "POST", path: "/v1/conversations" },
+    },
+    {
+        name: "fork",
+        description: "Fork this conversation at an entry (default: newest)",
+        argsHint: "[at]",
+        endpoint: {
+            method: "POST",
+            path: "/v1/conversations/:id/fork",
+        },
+    },
+    {
+        name: "compact",
+        description: "Compact this conversation's history",
+        argsHint: "[instructions]",
+        endpoint: {
+            method: "POST",
+            path: "/v1/conversations/:id/compact",
+        },
+    },
+    {
+        name: "export",
+        description: "Download this conversation as JSONL",
+        endpoint: { method: "GET", path: "/v1/conversations/:id/export" },
+    },
+    {
+        name: "import",
+        description: "Create a conversation from pasted JSONL",
+        argsHint: "<jsonl>",
+        endpoint: {
+            method: "POST",
+            path: "/v1/conversations/import",
+        },
+    },
+    {
+        name: "name",
+        description: "Name this conversation",
+        argsHint: "<name>",
+        endpoint: {
+            method: "PATCH",
+            path: "/v1/conversations/:id/meta",
+        },
+    },
+    {
+        name: "model",
+        description: "Switch this conversation's model",
+        argsHint: "<provider/model>",
+        endpoint: {
+            method: "POST",
+            path: "/v1/conversations/:id/configure",
+        },
+    },
+    {
+        name: "thinking",
+        description: "Set this conversation's thinking level",
+        argsHint: "<level>",
+        endpoint: {
+            method: "POST",
+            path: "/v1/conversations/:id/configure",
+        },
+    },
+    {
+        name: "jobs",
+        description: "List jobs (name, next run, last outcome)",
+        endpoint: { method: "GET", path: "/v1/jobs" },
+    },
+].map((command) => [command.name, command]));
+/**
+ * Merge the core slash-command table with every extension's `commands`
+ * declaration (spec §9.3). Called ONCE per server (the catalog is a boot
+ * constant, like the model catalog); the two collision rules:
+ *
+ * - CORE names are reserved: an extension command naming one is DROPPED
+ *   with one console warning and NOT recorded in `collisions` — a core
+ *   command is not replaceable, so there is no winner to report. The
+ *   dropped name never reaches the served list NOR `runnable` (invoking
+ *   it is 404 `command_not_found`, never the extension's run).
+ * - ext-vs-ext collisions are LAST-REGISTERED-WINS (the load order the
+ *   loader collected): warned, recorded in `collisions`, and the winner
+ *   replaces the loser's catalog entry and `runnable` binding in place.
+ */
+export function buildCommandCatalog(core, bindings) {
+    const commands = [...core.values()];
+    const collisions = [];
+    const runnable = new Map();
+    for (const binding of bindings) {
+        for (const contribution of binding.commands) {
+            if (core.has(contribution.name)) {
+                console.warn(`extension command dropped: "${binding.extension}" declares ` +
+                    `command "${contribution.name}" — core command names are reserved`);
+                continue;
+            }
+            const command = {
+                name: contribution.name,
+                description: contribution.description,
+                ...(contribution.args === undefined
+                    ? {}
+                    : { argsHint: contribution.args }),
+                extension: binding.extension,
+                endpoint: {
+                    method: "POST",
+                    path: `/v1/conversations/:id/commands/${contribution.name}`,
+                },
+            };
+            const previous = runnable.get(contribution.name);
+            if (previous !== undefined) {
+                collisions.push({
+                    kind: "command",
+                    name: contribution.name,
+                    previous: previous.extension,
+                    contributor: binding.extension,
+                });
+                console.warn(`extension command collision: "${binding.extension}" replaces ` +
+                    `"${previous.extension}" command "${contribution.name}" ` +
+                    "(last-registered-wins)");
+                // Replace in place: the loser's position in the served list
+                // is the winner's (stable ordering, one entry per name).
+                const index = commands.findIndex((entry) => entry.name === contribution.name);
+                if (index !== -1)
+                    commands[index] = command;
+            }
+            else {
+                commands.push(command);
+            }
+            runnable.set(contribution.name, {
+                command,
+                extension: binding.extension,
+                run: contribution.run,
+            });
+        }
+    }
+    return { commands, collisions, runnable };
+}
+// ─── The expand entries (Task 2c: /skill:name and prompt templates) ─────────
+/**
+ * Build the `kind: "expand"` catalog entries for the discovered skills
+ * and templates (Task 2c): every skill becomes `skill:<name>` (including
+ * model-hidden ones — `/skill:name` works for them; the description is
+ * the skill's frontmatter description, no args hint), every template
+ * becomes `{name, description, argsHint?}` from its frontmatter. The
+ * caller (the served list) appends these AFTER the core + extension
+ * commands; they carry NO endpoint — the composer inserts `/name ` into
+ * the text and the server expands the submission at admission.
+ */
+export function expandCommandEntries(skills, templates) {
+    return [
+        ...skills.map((skill) => ({
+            name: `skill:${skill.name}`,
+            description: skill.description,
+            kind: "expand",
+        })),
+        ...templates.map((template) => ({
+            name: template.name,
+            description: template.description,
+            ...(template.argsHint === undefined
+                ? {}
+                : { argsHint: template.argsHint }),
+            kind: "expand",
+        })),
+    ];
+}

package/dist/server/content-parts.js

@@ -0,0 +1,142 @@
+/**
+ * §5 content-part resolution (Task 9b, Review Focus #1).
+ *
+ * `POST /v1/conversations/:id/submissions` accepts wire parts —
+ * `{type:"text",text}` and `{type:"image"|"file",path,mime?}` with
+ * workspace-relative `path` — and this module resolves them to the inline
+ * `UserInput` content pi-durable stores (`TextContent` / base64
+ * `ImageContent`) at SUBMIT time, through the conversation's `ExecutionEnv`
+ * (the same `envBuilder` seam tool calls use, so remote workspaces stay
+ * correct, spec §3.4/§4.5).
+ *
+ * Resolution never silently drops a part: a `not_found` path becomes an
+ * explicit error text part addressed to the model (it stays visible in the
+ * transcript, and the model can react), and any other `FileError`
+ * (permission denied, aborted, …) fails the whole request loud — the repo
+ * rule "fail-loud on workspace read errors except not_found". A binary file
+ * part that is not valid UTF-8 also becomes an explicit error part
+ * (`invalid_utf8`) rather than mojibake text.
+ */
+/** The explicit error-part marker for a part that could not be resolved. */
+function errorPart(path, reason) {
+    return { type: "text", text: `[part error] ${path}: ${reason}` };
+}
+/** Extension → mime type for image parts without an explicit `mime`. */
+const IMAGE_MIME_BY_EXTENSION = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+};
+/**
+ * Validate a submission `input` body: the §5 content-part array, or a bare
+ * string (upstream `UserInput` also admits a plain string — simple clients
+ * submit text without wrapping it in a parts array; the server maps it to
+ * one text part). Part paths must be workspace-relative (no absolute paths,
+ * no `..` traversal — `NodeExecutionEnv` resolves against its `cwd` but
+ * accepts absolute paths as-is, so the server must confine client paths
+ * itself).
+ */
+export function parseSubmissionInput(input) {
+    if (typeof input === "string") {
+        return { ok: true, parts: [{ type: "text", text: input }] };
+    }
+    if (!Array.isArray(input) || input.length === 0)
+        return { ok: false };
+    const parts = [];
+    for (const candidate of input) {
+        if (typeof candidate !== "object" || candidate === null) {
+            return { ok: false };
+        }
+        const part = candidate;
+        if (part.type === "text") {
+            if (typeof part.text !== "string")
+                return { ok: false };
+            parts.push({ type: "text", text: part.text });
+            continue;
+        }
+        if (part.type === "image" || part.type === "file") {
+            if (typeof part.path !== "string" || !isConfinedPath(part.path)) {
+                return { ok: false };
+            }
+            if (part.mime !== undefined && typeof part.mime !== "string") {
+                return { ok: false };
+            }
+            parts.push({
+                type: part.type,
+                path: part.path,
+                ...(part.mime === undefined ? {} : { mime: part.mime }),
+            });
+            continue;
+        }
+        return { ok: false };
+    }
+    return { ok: true, parts };
+}
+/**
+ * A path the server will hand to the workspace env: relative, and without a
+ * `..` segment. `.` and empty are fine (`.` is the workspace root in list
+ * calls).
+ */
+export function isConfinedPath(path) {
+    if (path.length === 0)
+        return true;
+    if (path.startsWith("/") || path.includes("\\"))
+        return false;
+    const segments = path.split("/");
+    return !segments.includes("..");
+}
+/** Read one workspace file strictly-UTF-8: `undefined` when not valid UTF-8. */
+function decodeStrictUtf8(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve one wire part against the conversation's env. */
+async function resolvePart(part, env, context) {
+    if (part.type === "text")
+        return { type: "text", text: part.text };
+    const read = await env.readBinaryFile(part.path, context);
+    if (!read.ok) {
+        if (read.error.code === "not_found") {
+            // Review Focus #1: explicit error part, never a silent drop.
+            return errorPart(part.path, "not_found");
+        }
+        // Every other workspace failure is a server-side fault: fail loud.
+        throw read.error;
+    }
+    if (part.type === "image") {
+        const mime = part.mime ??
+            IMAGE_MIME_BY_EXTENSION[extensionOf(part.path)] ??
+            "application/octet-stream";
+        return {
+            type: "image",
+            data: Buffer.from(read.value).toString("base64"),
+            mimeType: mime,
+        };
+    }
+    const text = decodeStrictUtf8(read.value);
+    if (text === undefined) {
+        return errorPart(part.path, "invalid_utf8");
+    }
+    return { type: "text", text };
+}
+function extensionOf(path) {
+    const dot = path.lastIndexOf(".");
+    return dot === -1 ? "" : path.slice(dot + 1).toLowerCase();
+}
+/**
+ * Resolve a validated parts array to inline content. Rejects (throws the
+ * `FileError`) on any non-`not_found` workspace failure — fail-loud.
+ */
+export async function resolveParts(parts, env, context) {
+    const resolved = [];
+    for (const part of parts) {
+        resolved.push(await resolvePart(part, env, context));
+    }
+    return resolved;
+}

package/dist/server/context.js

@@ -0,0 +1,13 @@
+/**
+ * The shared server context (server restructure W0): what every route
+ * module receives from `createServer` instead of capturing harness or
+ * config state directly — one immutable record, so route modules stay
+ * pure functions of `(app, ctx)`.
+ *
+ * This module also owns the Fastify request augmentation (`declare
+ * module "fastify"`): the pipeline's `principal` and the
+ * conversation pre-handler's `conversation` decoration are declared
+ * here once, so every module that imports this context (a type-only
+ * import suffices) sees the augmented fields.
+ */
+export {};

package/dist/server/conversation-handler.js

@@ -0,0 +1,61 @@
+/**
+ * The conversation pre-handler: one hook every `:id` route declares, so
+ * conversation resolution, the unknown-id 404, and the §5.9 content-
+ * access check are uniform across route modules. It runs BEFORE the
+ * handler — the SSE route's 404 lands as plain JSON before
+ * `reply.hijack()` — and after Fastify's param validation (routes keep
+ * `schema: { params: ID_PARAMS_SCHEMA }`).
+ *
+ * Access (spec §5.9): the hook snapshots the session-meta doc and
+ * resolves `accessOf(principal, meta)`:
+ *
+ * - `"none"` (hidden) → 404 `conversation_not_found` — a hidden
+ *   conversation is indistinguishable from an unknown one (no 403 tell);
+ * - `"read"` on a WRITE route → 403 `forbidden` (the route names its need
+ *   with `loadConversation(ctx, need)`; GETs are `"read"`, everything
+ *   else is `"write"`).
+ *
+ * The polling surfaces (GET interactions/ambient) do NOT take this hook —
+ * they apply the visibility half of the rule inside their handlers (a
+ * channel polling a torn-down conversation must not error; see
+ * routes/interactions.ts).
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { accessOf } from "@sigrun/shared/access";
+import { isSuperuser } from "./auth/principal.js";
+import { conversationId } from "./helpers.js";
+import { SessionMetaDoc } from "./session-meta.js";
+/**
+ * Build the pre-handler: resolve `params.id` through the harness's
+ * storage-backed line, enforce the §5.9 access rule for `need`, and
+ * decorate `request.conversation`; an id no storage ever recorded — or a
+ * conversation the caller may not see — replies 404
+ * `{error: "conversation_not_found"}`; a read-only caller on a write
+ * route gets 403 `{error: "forbidden"}`.
+ */
+export function loadConversation(ctx, need = "read") {
+    return async (request, reply) => {
+        const { id } = request.params;
+        const conversation = await ctx.opened.harness.conversation(conversationId(id), BACKGROUND_CONTEXT);
+        if (conversation === undefined) {
+            return await reply
+                .code(404)
+                .send({ error: "conversation_not_found" });
+        }
+        const meta = await ctx.opened.harness.snapshot(SessionMetaDoc, conversation.id, BACKGROUND_CONTEXT);
+        const access = accessOf({
+            user: request.principal.user,
+            superuser: isSuperuser(request.principal),
+        }, meta ?? {});
+        if (access === "none") {
+            // Hidden is 404 on every :id route (spec §5.9).
+            return await reply
+                .code(404)
+                .send({ error: "conversation_not_found" });
+        }
+        if (access === "read" && need === "write") {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        request.conversation = conversation;
+    };
+}