@sigrun/sigrun 0.1.4 → 0.1.6

package/dist/server/routes/extensions.js

@@ -4,7 +4,8 @@
  *
  * - `GET /v1/extensions` — one entry per loaded outcome with `status`,
  *   `error?`, the manifest `version?`, the declared
- *   `interactionKinds`/`ambientKeys`, and the idle-worker projection.
+ *   `interactionKinds`/`ambientKeys`, the idle-worker projection, and
+ *   the contributed channel ids (gateway C1, `channels?`).
  * - `GET`/`PUT /v1/extensions/:slug/settings` (PUT admin) — the
  *   `settings/<slug>.json` object verbatim. Values an extension reads at
  *   factory time apply at RESTART; per-run reads see the write live.
@@ -40,6 +41,7 @@ export function registerExtensionRoutes(app, ctx) {
             const kinds = opened.seamKinds.get(outcome.name);
             const workers = workerStatuses.get(outcome.name);
             const routes = opened.extensionRoutes.find((binding) => binding.extension === outcome.name);
+            const surfaces = opened.extensionSurfaces.find((binding) => binding.extension === outcome.name);
             return {
                 name: outcome.name,
                 status: outcome.status,
@@ -48,6 +50,18 @@ export function registerExtensionRoutes(app, ctx) {
                     ? {}
                     : { version: outcome.version }),
                 ...(outcome.builtin === true ? { builtin: true } : {}),
+                ...(outcome.channels === undefined
+                    ? {}
+                    : { channels: [...outcome.channels] }),
+                // Gateway C2: a channel contributor with NO loaded engine is
+                // INERT — its adapters never start (the boot warning says so);
+                // the row says which surface is missing. Only OK rows mark it
+                // (a quarantined loader's `channels` never landed anyway).
+                ...(outcome.channels !== undefined &&
+                    outcome.status === "ok" &&
+                    opened.gatewayEngine === undefined
+                    ? { inert: "no gateway" }
+                    : {}),
                 interactionKinds: [...(kinds?.interaction ?? [])],
                 ambientKeys: [...(kinds?.ambient ?? [])],
                 workers: workers ?? [],
@@ -56,6 +70,22 @@ export function registerExtensionRoutes(app, ctx) {
                     path: route.path,
                     auth: route.auth,
                 })) ?? [],
+                // Declared surfaces (U3 Task 1, spec §7.1): the flattened view +
+                // panel rows the channels register their rail/panel entries from —
+                // SPARSE (absent when the extension declared none).
+                ...(surfaces === undefined
+                    ? {}
+                    : {
+                        surfaces: surfaces.defs.map((def) => ({
+                            id: def.id,
+                            title: def.title,
+                            icon: def.icon,
+                            placement: def.placement,
+                            ...(def.sharedData === true
+                                ? { sharedData: true }
+                                : {}),
+                        })),
+                    }),
             };
         });
         // Replaced built-ins (Task 2 ruling 5): one row each, under the slug

package/dist/server/routes/files.js

@@ -9,25 +9,13 @@
  * all at once.
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
-import { extname } from "node:path";
 import { loadConversation } from "../conversation-handler.js";
 import { isConfinedPath } from "../content-parts.js";
 import { base64BodyLimit } from "../../config.js";
+import { ConversationOpError, readFileMetaOp, uploadOp, validUploadName, } from "../conversation-ops.js";
 import { ID_PARAMS_SCHEMA, FILE_CONTENT_MAX_BYTES, conversationEnv, decodeBase64Strict, } from "../helpers.js";
-/**
- * The one upload-name rule, shared by the base64 POST body's `name` and
- * the raw PUT's `:name` param: no `/` or `\\`, not `.` or `..`, non-empty.
- * The PUT checks it AFTER Fastify decodes the percent-encoded param
- * (`..%2Fx` arrives as `../x`, `%2e%2e` as `..`) — the check runs on the
- * decoded value, never the raw path text.
- */
-function validUploadName(name) {
-    return (name.length > 0 &&
-        !name.includes("/") &&
-        !name.includes("\\") &&
-        name !== "." &&
-        name !== "..");
-}
+/** The raw read's streaming chunk size (1 MiB): bounds reader memory. */
+const RAW_READ_CHUNK_BYTES = 1024 * 1024;
 /** The `:id` + `:name` params of the raw upload route. */
 const UPLOAD_PARAMS_SCHEMA = {
     type: "object",
@@ -35,30 +23,6 @@ const UPLOAD_PARAMS_SCHEMA = {
     required: ["id", "name"],
     additionalProperties: false,
 };
-/**
- * The extension→mime map for the raw file read (spec §7.8): the common
- * workspace-file extensions a client renders inline. A file whose
- * extension is absent from the map serves `application/octet-stream`.
- * The KEY is the LOWERCASE extension including the dot (the lookup
- * lowercases, so `Photo.PNG` maps too).
- */
-const MIME_BY_EXTENSION = new Map([
-    [".png", "image/png"],
-    [".jpg", "image/jpeg"],
-    [".jpeg", "image/jpeg"],
-    [".gif", "image/gif"],
-    [".webp", "image/webp"],
-    [".svg", "image/svg+xml"],
-    [".pdf", "application/pdf"],
-    [".txt", "text/plain"],
-    [".md", "text/markdown"],
-    [".json", "application/json"],
-    [".html", "text/html"],
-    [".css", "text/css"],
-    [".js", "text/javascript"],
-]);
-/** The raw read's streaming chunk size (1 MiB): bounds reader memory. */
-const RAW_READ_CHUNK_BYTES = 1024 * 1024;
 /** Register the upload/listing/content workspace file routes. */
 export function registerFileRoutes(app, ctx) {
     const { opened, config } = ctx;
@@ -85,6 +49,10 @@ export function registerFileRoutes(app, ctx) {
     }, async (request, reply) => {
         const conversation = request.conversation;
         const { name } = request.params;
+        // The route pre-validates to keep its exact wire body
+        // (`invalid_body`); the shared op's own `invalid_field` check is
+        // unreachable here by construction (the gateway C4b ruling: the op
+        // is the one validator, the routes keep byte-identical responses).
         if (!validUploadName(name)) {
             return await reply.code(400).send({ error: "invalid_body" });
         }
@@ -93,16 +61,7 @@ export function registerFileRoutes(app, ctx) {
         const bytes = request.body === undefined
             ? new Uint8Array(0)
             : new Uint8Array(request.body);
-        // Same namespace as the base64 route: v1 namespaces uploads per
-        // conversation, and the returned path is exactly what a content
-        // part takes.
-        const path = `uploads/${conversation.id}/${name}`;
-        const env = await conversationEnv(opened, conversation);
-        const written = await env.writeFile(path, bytes, BACKGROUND_CONTEXT);
-        if (!written.ok) {
-            // A failed upload is a server-side fault: fail loud.
-            throw written.error;
-        }
+        const { path } = await uploadOp(ctx, conversation, { name, bytes });
         return await reply.code(201).send({ path });
     });
     // Uploads (base64, one more release): materialize a base64 body into
@@ -135,17 +94,13 @@ export function registerFileRoutes(app, ctx) {
         if (bytes === undefined) {
             return await reply.code(400).send({ error: "invalid_body" });
         }
-        // v1 namespaces uploads per conversation: workspaces are static and
-        // shared in v1, so un-namespaced names would clobber across
-        // conversations. The returned path is exactly what a content part
-        // takes.
-        const path = `uploads/${conversation.id}/${name}`;
-        const env = await conversationEnv(opened, conversation);
-        const written = await env.writeFile(path, new Uint8Array(bytes), BACKGROUND_CONTEXT);
-        if (!written.ok) {
-            // A failed upload is a server-side fault: fail loud.
-            throw written.error;
-        }
+        // The shared op owns the pathing + write (same namespace as the
+        // raw route: `uploads/<conversationId>/<name>`, exactly what a
+        // content part takes).
+        const { path } = await uploadOp(ctx, conversation, {
+            name,
+            bytes: new Uint8Array(bytes),
+        });
         return await reply.code(201).send({ path });
     });
     // Files: read-only workspace listing through the conversation env.
@@ -245,27 +200,28 @@ export function registerFileRoutes(app, ctx) {
         const conversation = request.conversation;
         const query = request.query;
         const path = query.path ?? "";
-        if (!isConfinedPath(path) || path.length === 0 || path === ".") {
-            return await reply.code(400).send({ error: "invalid_path" });
+        // The shared raw-read pre-checks (gateway C4b): confinement,
+        // not_found, directory, and the cap — the SAME vocabulary this
+        // route served inline; only the cap's BODY differs (the route's
+        // `file_too_large` + `maxBytes`, not the op's `too_large`), mapped
+        // here so the wire stays byte-identical.
+        let meta;
+        try {
+            meta = await readFileMetaOp(ctx, conversation, path);
         }
-        const env = await conversationEnv(opened, conversation);
-        const info = await env.fileInfo(path, BACKGROUND_CONTEXT);
-        if (!info.ok) {
-            if (info.error.code === "not_found") {
-                return await reply.code(404).send({ error: "not_found" });
+        catch (error) {
+            if (error instanceof ConversationOpError) {
+                if (error.status === 413 && error.body.error === "too_large") {
+                    return await reply.code(413).send({
+                        error: "file_too_large",
+                        maxBytes: config.maxFileReadBytes,
+                    });
+                }
+                return await reply.code(error.status).send(error.body);
             }
-            throw info.error;
-        }
-        if (info.value.kind === "directory") {
-            return await reply.code(400).send({ error: "invalid_path" });
-        }
-        const maxBytes = config.maxFileReadBytes;
-        if (info.value.size > maxBytes) {
-            return await reply
-                .code(413)
-                .send({ error: "file_too_large", maxBytes });
+            throw error;
         }
-        const readerOpened = await env.openBinaryReader(path, undefined, BACKGROUND_CONTEXT);
+        const readerOpened = await meta.env.openBinaryReader(path, undefined, BACKGROUND_CONTEXT);
         if (!readerOpened.ok) {
             if (readerOpened.error.code === "not_found") {
                 return await reply.code(404).send({ error: "not_found" });
@@ -281,12 +237,11 @@ export function registerFileRoutes(app, ctx) {
         raw.on("error", () => { });
         try {
             raw.writeHead(200, {
-                "content-type": MIME_BY_EXTENSION.get(extname(path).toLowerCase()) ??
-                    "application/octet-stream",
-                "content-length": String(info.value.size),
+                "content-type": meta.mime,
+                "content-length": String(meta.size),
             });
-            for (let offset = 0; offset < info.value.size; offset += RAW_READ_CHUNK_BYTES) {
-                const chunk = await reader.read(offset, Math.min(RAW_READ_CHUNK_BYTES, info.value.size - offset), BACKGROUND_CONTEXT);
+            for (let offset = 0; offset < meta.size; offset += RAW_READ_CHUNK_BYTES) {
+                const chunk = await reader.read(offset, Math.min(RAW_READ_CHUNK_BYTES, meta.size - offset), BACKGROUND_CONTEXT);
                 if (!chunk.ok)
                     throw chunk.error;
                 raw.write(Buffer.from(chunk.value));

package/dist/server/routes/meta.js

@@ -41,6 +41,7 @@ export function registerMetaRoutes(app, ctx) {
             schemaVersion: SCHEMA_VERSION,
             extensions: opened.extensionOutcomes.map((outcome) => {
                 const workers = workerStatuses.get(outcome.name);
+                const surfaces = opened.extensionSurfaces.find((binding) => binding.extension === outcome.name);
                 return {
                     name: outcome.name,
                     status: outcome.status,
@@ -48,6 +49,28 @@ export function registerMetaRoutes(app, ctx) {
                     ...(workers === undefined || workers.length === 0
                         ? {}
                         : { workers }),
+                    // The declared surfaces (UI-blocks U3 Task 5): the channels'
+                    // rail/panel registration reads the DECLARATION here (never a
+                    // second fetch); access-none filtering stays render-time.
+                    ...(surfaces === undefined
+                        ? {}
+                        : {
+                            surfaces: surfaces.defs.map((def) => ({
+                                id: def.id,
+                                title: def.title,
+                                icon: def.icon,
+                                placement: def.placement,
+                                // The refresh cadence (§7.1): the channels'
+                                // visible-surface refetch intervals read it here
+                                // (never a second fetch).
+                                ...(def.refreshMs === undefined
+                                    ? {}
+                                    : { refreshMs: def.refreshMs }),
+                                // The §7.3 shared-data flag: channels refetch
+                                // fully when a since fetch answers ops-only.
+                                ...(def.sharedData === true ? { sharedData: true } : {}),
+                            })),
+                        }),
                 };
             }),
             // §5 health: pure aggregation over boot-retained §3 producers —
@@ -56,11 +79,19 @@ export function registerMetaRoutes(app, ctx) {
             // double-reported here), providers aggregated across
             // contributors (empty → "ok"), and backup from the §6.8 marker
             // derivation above ("configured" only while a fresh success
-            // exists — the one storage read this route makes).
+            // exists — the one storage read this route makes). Gateway C2 adds
+            // `gateway`: present ONLY when an engine loaded (the meta route
+            // keys on `opened.gatewayEngine`, never on the handle — a
+            // no-engine deploy reports NO gateway health, degenerate "ok" by
+            // absence), its value the HANDLE's wrapped health (throw →
+            // "degraded"; a start rejection latches degraded until restart).
             health: {
                 backup: backupHealth,
                 memory: opened.memoryHealth?.() ?? "ok",
                 providers: aggregateHealth(opened.providerHealth),
+                ...(opened.gatewayEngine === undefined || ctx.gateway === undefined
+                    ? {}
+                    : { gateway: ctx.gateway.health() }),
             },
             // The auth block (W1 Task 6, spec §5.7): the effective method list
             // (resolved once in `createServer`) + the onboarding state — both
@@ -86,6 +117,9 @@ export function registerMetaRoutes(app, ctx) {
                 // deploy (gate off or absent default) reports [].
                 channels: webuiBundle === undefined ? [] : [webuiBundle.channel],
             },
+            // §14.2/§14.4: the development flag — gates the gallery and the
+            // development error bodies (a boot constant, cached like the rest).
+            dev: config.dev,
             // The seam inventory: declaration-derived, no doc reads.
             seam: {
                 interactions: [...opened.seamKinds]

package/dist/server/routes/providers.js

@@ -19,7 +19,7 @@
  * new key up on the next refresh — no provider restart, no re-boot.
  */
 import { DEFAULT_AUTH_KEY } from "../../harness/auth.js";
-import { providerAuthStatus } from "../helpers.js";
+import { listModels, providerAuthStatus } from "../helpers.js";
 /**
  * The per-provider readiness report (the shared derivation BOTH routes
  * serve — one body, never two). The response carries ONLY a per-provider
@@ -173,26 +173,10 @@ export function registerProviderRoutes(app, ctx) {
         return readinessEntry(opened, id, producersIndex(opened));
     });
     // Models: the merged chat-model catalog as picker entries (no provider
-    // internals — baseUrl/headers/auth stay server-side).
+    // internals — baseUrl/headers/auth stay server-side). The shared
+    // construction (gateway C4b): the host's `models.list()` serves the
+    // SAME list through helpers.listModels.
     app.get("/v1/models", async () => {
-        const models = opened.models.getModels().map((model) => ({
-            id: `${model.provider}/${model.id}`,
-            provider: model.provider,
-            modelId: model.id,
-            name: model.name,
-            contextWindow: model.contextWindow,
-            maxTokens: model.maxTokens,
-            reasoning: model.reasoning,
-            input: model.input,
-            // Project the four rate fields explicitly (ModelCostRates); `tiers` is
-            // dropped for v1 (the picker doesn't use them) — no unsound cast.
-            cost: {
-                input: model.cost.input,
-                output: model.cost.output,
-                cacheRead: model.cost.cacheRead,
-                cacheWrite: model.cost.cacheWrite,
-            },
-        }));
-        return { models };
+        return { models: listModels(opened) };
     });
 }

package/dist/server/routes/submissions.js

@@ -8,9 +8,9 @@
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { UnservedModelError } from "../../harness/providers/index.js";
-import { ConversationOpError, submitOp, } from "../conversation-ops.js";
+import { abortOp, compactOp, configureOp, ConversationOpError, submitOp, } from "../conversation-ops.js";
 import { loadConversation } from "../conversation-handler.js";
-import { ID_PARAMS_SCHEMA, THINKING_LEVELS, submissionId, } from "../helpers.js";
+import { ID_PARAMS_SCHEMA, submissionId } from "../helpers.js";
 /** Integer path params for the submission status route (§7.1). */
 const SUBMISSION_PARAMS_SCHEMA = {
     type: "object",
@@ -93,110 +93,37 @@ export function registerSubmissionRoutes(app, ctx) {
         return { submission: record };
     });
     // Configure: change the conversation's model and/or thinking level.
+    // The shared configure op (gateway C4a) is the SAME code path the
+    // extension host bridge drives — the validation order and error bodies
+    // moved verbatim into the op; this route owns the HTTP mapping only.
     // v1 accepts EXACTLY `model` + `thinking` — any other key is a fail-loud
     // 400 (the agent's other knobs are not wire surface yet).
     app.post("/v1/conversations/:id/configure", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx, "write") }, async (request, reply) => {
-        const conversation = request.conversation;
-        const body = request.body;
-        if (body === undefined ||
-            body === null ||
-            typeof body !== "object" ||
-            Array.isArray(body)) {
-            return await reply.code(400).send({ error: "invalid_body" });
-        }
-        const unknownKey = Object.keys(body).find((key) => key !== "model" && key !== "thinking");
-        if (unknownKey !== undefined) {
-            return await reply
-                .code(400)
-                .send({ error: "invalid_field", field: unknownKey });
-        }
-        const model = body.model;
-        const thinking = body.thinking;
-        if (model === undefined && thinking === undefined) {
-            // A configure that changes nothing is a client error, not a no-op.
-            return await reply.code(400).send({ error: "invalid_body" });
+        try {
+            return await configureOp(ctx, request.conversation, request.body);
         }
-        // `model` is `"provider/modelId"`, split on the FIRST `/` (a modelId
-        // may itself contain slashes); both parts must be non-empty.
-        let parsedModel;
-        if (model !== undefined) {
-            if (typeof model !== "string" || !model.includes("/")) {
-                return await reply
-                    .code(400)
-                    .send({ error: "invalid_field", field: "model" });
-            }
-            const slash = model.indexOf("/");
-            const provider = model.slice(0, slash);
-            const modelId = model.slice(slash + 1);
-            if (provider.length === 0 || modelId.length === 0) {
-                return await reply
-                    .code(400)
-                    .send({ error: "invalid_field", field: "model" });
+        catch (error) {
+            if (error instanceof ConversationOpError) {
+                return await reply.code(error.status).send(error.body);
             }
-            parsedModel = { provider, modelId };
-        }
-        if (thinking !== undefined &&
-            (typeof thinking !== "string" ||
-                !THINKING_LEVELS.includes(thinking))) {
-            return await reply
-                .code(400)
-                .send({ error: "invalid_field", field: "thinking" });
+            throw error;
         }
-        // perModelThinking: a model change re-applies the store's
-        // override for the NEW model unless the request pins `thinking` —
-        // the map is the deployment default, the explicit field the caller's
-        // win. Read from the store here, so a PATCH reaches later configures.
-        const storeThinking = parsedModel === undefined
-            ? undefined
-            : opened.settings.read().perModelThinking?.[`${parsedModel.provider}/${parsedModel.modelId}`];
-        await conversation.configure({
-            ...(parsedModel === undefined ? {} : { model: parsedModel }),
-            ...(thinking !== undefined
-                ? { thinkingLevel: thinking }
-                : storeThinking === undefined
-                    ? {}
-                    : { thinkingLevel: storeThinking }),
-        }, BACKGROUND_CONTEXT);
-        // Read the agent back and project the configured surface only —
-        // resolved extensions/tools/sections stay server-side.
-        const agent = await conversation.agent(BACKGROUND_CONTEXT);
-        return {
-            ...(agent.model === undefined ? {} : { model: agent.model }),
-            thinkingLevel: agent.thinkingLevel,
-        };
     });
     // Abort: withdraw/settle the conversation's active submission.
-    // `inspect()` is the read-only union of placed run inputs and queued inbox
-    // items (all conversations); filtered to this conversation, the LOWEST id
-    // is the active one — anything queued behind a busy conversation was
-    // admitted later and has a higher id.
+    // The shared abort op (gateway C4a) is the SAME code path the host
+    // bridge drives — the inspect/reduce targeting of the conversation's
+    // lowest live submission and the 404 `no_active_submission` live in the
+    // op; this route owns the HTTP mapping only.
     app.post("/v1/conversations/:id/abort", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx, "write") }, async (request, reply) => {
-        const conversation = request.conversation;
-        const inspection = await opened.harness.inspect(BACKGROUND_CONTEXT);
-        // Lowest live id = oldest admitted = the placed run input over later-
-        // queued inbox items. reduce() with a first-element seed is ordering-
-        // independent (a future pi-durable inspect() ordering change cannot
-        // silently target the wrong submission); empty → undefined.
-        const active = inspection.submissions
-            .filter((s) => s.conversationId === conversation.id)
-            .reduce((min, s) => (min === undefined || s.id < min.id ? s : min), undefined);
-        if (active === undefined) {
-            return await reply
-                .code(404)
-                .send({ error: "no_active_submission" });
+        try {
+            return await abortOp(ctx, request.conversation);
         }
-        const result = await opened.harness.abortSubmission(active.id, BACKGROUND_CONTEXT, conversation.id);
-        // `not_found` means the submission's record vanished between `inspect`
-        // and `abort` — the conversation is no longer busy, so the honest answer
-        // is the same as nothing-active.
-        if (result === "not_found") {
-            return await reply
-                .code(404)
-                .send({ error: "no_active_submission" });
+        catch (error) {
+            if (error instanceof ConversationOpError) {
+                return await reply.code(error.status).send(error.body);
+            }
+            throw error;
         }
-        // `already_placed`/`settled` are still 200: abort is idempotent and
-        // the body reports which state the submission was found in.
-        return { result, submissionId: active.id };
     });
     // Manual compaction: `POST .../compact` (pi parity).
     // `Conversation.compact(instructions)` (pi-durable's own manual-
@@ -208,12 +135,14 @@ export function registerSubmissionRoutes(app, ctx) {
     // `enabled` (upstream doc: "manual compaction ignores `enabled`");
     // `compact()` resumes the scheduler itself. The task id is handed back —
     // the SSE stream carries the `pi.compaction` entry when the summary
-    // lands.
+    // lands. The shared compact op (gateway C4a) is the SAME code path the
+    // host bridge drives; this route owns the body validation and the 202.
     app.post("/v1/conversations/:id/compact", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx, "write") }, async (request, reply) => {
         const conversation = request.conversation;
         // Absent body is valid (no instructions); an object may carry
         // ONLY `instructions` — any other key is a fail-loud 400, the
-        // configure convention.
+        // configure convention. The instructions value itself is the op's
+        // validation (same shape for HTTP and host callers).
         const body = request.body;
         let instructions;
         if (body !== undefined && body !== null) {
@@ -227,22 +156,18 @@ export function registerSubmissionRoutes(app, ctx) {
                     .code(400)
                     .send({ error: "invalid_field", field: unknownKey });
             }
-            if (record.instructions !== undefined &&
-                typeof record.instructions !== "string") {
-                return await reply
-                    .code(400)
-                    .send({ error: "invalid_field", field: "instructions" });
+            instructions = record.instructions;
+        }
+        try {
+            const { taskId } = await compactOp(ctx, conversation, instructions);
+            return await reply.code(202).send({ taskId });
+        }
+        catch (error) {
+            if (error instanceof ConversationOpError) {
+                return await reply.code(error.status).send(error.body);
             }
-            instructions =
-                record.instructions === undefined || record.instructions === ""
-                    ? undefined
-                    : record.instructions;
+            throw error;
         }
-        const taskId = await conversation.compact(instructions, BACKGROUND_CONTEXT);
-        // 202: like submissions, the compaction is admitted, not settled —
-        // the task runs asynchronously and its summary lands as a view
-        // revision (the SSE stream).
-        return await reply.code(202).send({ taskId });
     });
     // Extension-command invocation (core hardening W5 Task 3, spec §9.3):
     // `POST /v1/conversations/:id/commands/:name {args?}` runs the winning