@sigrun/sigrun 0.1.4 → 0.1.6

package/dist/harness/packages.js

@@ -69,12 +69,23 @@ export const NPM_TIMEOUT_MS = 120_000;
  * own. {@link ensureHostModuleLinks} links sigrun's own copies into the
  * packages dir's node_modules so the dynamic import of such a package
  * resolves them — the SAME module instances the host runs.
+ *
+ * `@sigrun/sigrun` itself is here too (spec §14.1): the builders behind
+ * `@sigrun/sigrun/blocks` must emit the SERVER's block-set version, so
+ * extensions import the running copy — never a bundled or
+ * registry-fetched one (the loader's exact-match rule quarantines a
+ * tree that resolves a different version). Sigrun is the RUNNING
+ * package, not a dependency: {@link resolveHostModuleDir} resolves it
+ * to its own root instead of walking node_modules.
  */
+/** The package this code ships in — the host runtime module that is the host itself. */
+const SELF_MODULE_NAME = "@sigrun/sigrun";
 export const HOST_RUNTIME_MODULES = [
     "@earendil-works/pi-ai",
     "@earendil-works/pi-durable",
     "@earendil-works/chord",
     "typebox",
+    SELF_MODULE_NAME,
 ];
 /**
  * Read the `version` field of the package at `moduleDir` (following
@@ -101,13 +112,47 @@ export function hostModuleVersion(name) {
     const dir = resolveHostModuleDir(name);
     return dir === undefined ? undefined : installedVersionAt(dir);
 }
+/**
+ * The running package's own root: the nearest ancestor of THIS module
+ * whose manifest is named `@sigrun/sigrun`. The node_modules walk below
+ * can never find the running package — sigrun is not a dependency of
+ * itself, and a source checkout carries no
+ * `node_modules/@sigrun/sigrun` anywhere above `src/` (the published
+ * install resolves through its OWN root, which is this same dir).
+ * `undefined` when no ancestor carries the manifest.
+ */
+function selfPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let hops = 0; hops < 10; hops++) {
+        const manifest = join(dir, "package.json");
+        if (existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+                if (parsed.name === SELF_MODULE_NAME)
+                    return dir;
+            }
+            catch {
+                // Unreadable manifest — keep walking.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
 /**
  * Resolve a host runtime module's package dir from sigrun's own tree: the
  * nearest `node_modules/<name>` walking up from THIS module's location
  * (the repo root in every deploy shape — sigrun runs from source). The
  * walk stops at the filesystem root; `undefined` when nothing resolves.
+ * The ONE exception is sigrun itself (see {@link selfPackageRoot}): the
+ * link target is the running package's own root.
  */
 function resolveHostModuleDir(name) {
+    if (name === SELF_MODULE_NAME)
+        return selfPackageRoot();
     let dir = dirname(fileURLToPath(import.meta.url));
     for (let hops = 0; hops < 10; hops++) {
         const candidate = join(dir, "node_modules", ...name.split("/"));
@@ -210,13 +255,25 @@ export class PackageSyncError extends Error {
 }
 /**
  * One `npm <args>` invocation against the packages dir (execFile — no
- * shell, so no quoting surface). Failures and timeouts reject with a
+ * shell, so no quoting surface). `--legacy-peer-deps` disables npm's
+ * peer-resolution for every managed install — pi's own posture for its
+ * extension installs: an extension declaring `@sigrun/sigrun` (or
+ * pi-durable/pi-ai) a `peerDependency: "*"` must resolve the HOST's
+ * linked copy, never an npm-solved registry copy whose version would
+ * quarantine the extension at load. Failures and timeouts reject with a
  * `PackageSyncError` carrying npm's stderr tail; `verbose` captures the
  * full output for the error message.
  */
 function runNpm(args, packagesDir, verbose) {
     return new Promise((resolve, reject) => {
-        execFile("npm", [...args, "--prefix", packagesDir, "--no-audit", "--no-fund"], { timeout: NPM_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+        execFile("npm", [
+            ...args,
+            "--prefix",
+            packagesDir,
+            "--no-audit",
+            "--no-fund",
+            "--legacy-peer-deps",
+        ], { timeout: NPM_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
             if (error === null) {
                 if (verbose === true && stderr !== "") {
                     console.warn(`packages: npm ${args[0] ?? ""}: ${stderr.trim()}`);
@@ -346,6 +403,18 @@ export function readPackageVersion(absPath) {
     const version = readManifest(absPath)?.version;
     return typeof version === "string" && version !== "" ? version : undefined;
 }
+/**
+ * The declared `sigrun.assets` directory (spec §11.1), resolved
+ * absolute against the package root; `undefined` when the manifest
+ * declares none (or no manifest reads). A non-string declaration is
+ * ignored — assets are simply absent.
+ */
+export function readPackageAssetsDir(absPath) {
+    const declared = readManifest(absPath)?.sigrun?.assets;
+    if (typeof declared !== "string" || declared === "")
+        return undefined;
+    return resolve(absPath, declared);
+}
 /**
  * The identity a specifier installs under: registry specs key by their
  * parsed name; path specs key by the target package's OWN manifest name

package/dist/harness/seam-host.js

@@ -103,13 +103,16 @@ export function createSeamHost(identity, kinds, bind, sharedStores) {
                 indexPending(index, conversationId, record.callId);
             }, context);
         },
-        async answerInteraction(conversationId, callId, answer, context) {
+        async answerInteraction(conversationId, callId, answer, context, opts) {
             const h = await harness(context);
             return await h.commit(async (tx) => {
                 const draft = await tx.doc(InteractionDoc, conversationId, callId, callId);
                 if (draft.status !== "pending")
                     return false;
-                const applied = applyAnswer(draft, answer, "extension", Date.now());
+                // Gateway C5: a host caller naming a user answers AS that human
+                // (the route's path — the same applyAnswer line); without a user
+                // the extension answered itself.
+                const applied = applyAnswer(draft, answer, opts?.user === undefined ? "extension" : "human", Date.now(), opts?.user);
                 if (applied) {
                     const index = await tx.doc(InteractionsIndexDoc);
                     indexSettled(index, conversationId, callId);
@@ -193,6 +196,7 @@ export function createSeamHost(identity, kinds, bind, sharedStores) {
                     ...(opts.owner === undefined ? {} : { owner: opts.owner }),
                     ...(opts.sharing === undefined ? {} : { sharing: opts.sharing }),
                     ...(opts.name === undefined ? {} : { name: opts.name }),
+                    ...(opts.agent === undefined ? {} : { agent: opts.agent }),
                     // The source default: the CALLING extension's slug (spec §9.5).
                     source: opts.source ?? identity.name,
                 });
@@ -213,6 +217,30 @@ export function createSeamHost(identity, kinds, bind, sharedStores) {
                 const bridge = await hostBridge();
                 return bridge.conversations.meta(id);
             },
+            // The C4a ops: straight delegation (the bridge resolves the id and
+            // runs the op its HTTP twin runs).
+            async abort(id) {
+                return (await hostBridge()).conversations.abort(id);
+            },
+            async configure(id, opts) {
+                return (await hostBridge()).conversations.configure(id, opts);
+            },
+            async compact(id) {
+                return (await hostBridge()).conversations.compact(id);
+            },
+            async fork(id, opts) {
+                return (await hostBridge()).conversations.fork(id, opts);
+            },
+            async patchMeta(id, patch) {
+                return (await hostBridge()).conversations.patchMeta(id, patch);
+            },
+            // The C4b ops: same straight delegation.
+            async upload(id, file) {
+                return (await hostBridge()).conversations.upload(id, file);
+            },
+            async readFile(id, path) {
+                return (await hostBridge()).conversations.readFile(id, path);
+            },
         },
         users: {
             async list() {
@@ -232,6 +260,45 @@ export function createSeamHost(identity, kinds, bind, sharedStores) {
                 return (await hostBridge()).identity.actingUser(conversationId);
             },
         },
+        // Gateway C4b: straight delegation (the bridge owns both bodies).
+        models: {
+            async list() {
+                return (await hostBridge()).models.list();
+            },
+        },
+        commands: {
+            async list() {
+                return (await hostBridge()).commands.list();
+            },
+            async run(conversationId, name, args, opts) {
+                return (await hostBridge()).commands.run(conversationId, name, args, opts);
+            },
+        },
+        // The surfaces seam (UI-blocks U3 Task 4): `changed` awaits the
+        // bridge (so a factory-body call waits, never resolves early) and
+        // delegates to the server-side SurfaceService — the rev bump + the
+        // hub event are the service's one code path (the actions route and
+        // the host seam share it).
+        surfaces: {
+            changed(id, key, update) {
+                const host = identity; // capture for the async lane
+                const ran = () => {
+                    // The Review Focus 4 observability seam (the fixture
+                    // surfaces-early pattern): a call that WAITED for the
+                    // bridge is distinguishable from an early no-op. Inert in
+                    // production (nothing sets it).
+                    globalThis.__sigrunSurfaceChanged?.(host.name);
+                };
+                void hostBridge()
+                    .then((bridge) => {
+                    ran();
+                    bridge.surfaces.changed(identity.name, id, key, update);
+                })
+                    .catch((error) => {
+                    console.error(`seam host: surfaces.changed (${identity.name}/${id}) failed:`, error);
+                });
+            },
+        },
         bindBridge(bridge) {
             bridgeReleased(bridge);
         },

package/dist/harness/settings.js

@@ -413,6 +413,7 @@ function validateServer(server) {
         "providers",
         "auth",
         "metrics",
+        "dev",
         "backup",
     ]);
     // The jobs default timezone (§8.2): an IANA name — `Intl` accepts
@@ -611,6 +612,10 @@ function validateServer(server) {
             throw new SettingsValidationError("server.metrics.public", "must be a boolean");
         }
     }
+    // The development flag (§14.2/§14.4) — a flat boolean, no section.
+    if (record.dev !== undefined && typeof record.dev !== "boolean") {
+        throw new SettingsValidationError("server.dev", "must be a boolean");
+    }
     if (record.backup !== undefined) {
         const backup = asRecord(record.backup);
         if (backup === undefined) {

package/dist/harness/workspace.js

@@ -15,15 +15,17 @@
  * adapter below: pi-durable passes it through `EnvTarget.cwd` and applies
  * nothing itself, so the adapter must root the env at it.
  */
-import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+import { AgentExecutionEnv } from "./agent-env.js";
 import { isAbsolute, resolve } from "node:path";
 /**
  * Build the static workspace service.
  *
  * v1 resolves every conversation from `prefs.defaultWorkspace` — the spec's
  * static configuration — so the service carries no state of its own. The
- * returned env is an upstream `NodeExecutionEnv` (pi-durable's local Node
- * `ExecutionEnv`): its `FileSystem.id` is the stable `"node:local"` (every
+ * returned env is an {@link AgentExecutionEnv}: upstream's local Node
+ * `ExecutionEnv` with commands confined to the agent environment
+ * allowlist (multi-user spec §8). Its `FileSystem.id` is the stable
+ * `"node:local"` (every
  * local environment sees the same files), and its `Shell` runs commands
  * rooted at the workspace `cwd`. A fresh instance per call matches how
  * upstream builds envs; equal ids see the same files whatever their `cwd`.
@@ -37,7 +39,7 @@ export function createWorkspaceService() {
                 // type reaching here means the preferences are not v1's.
                 throw new Error(`Unsupported workspace type: ${JSON.stringify(workspace.type)}`);
             }
-            return new NodeExecutionEnv({ cwd: workspace.path });
+            return new AgentExecutionEnv({ cwd: workspace.path });
         },
     };
 }

package/dist/jobs/fire.js

@@ -188,6 +188,12 @@ async function firePrompt(deps, id, record, fireKey, baseRun, prior, context) {
     // conversation: "new" — the run record + conversation in ONE commit.
     let conversationId = prior?.conversationId;
     if (conversationId === undefined) {
+        // Gateway C7: the deliver targets need a deliverer. With no engine
+        // loaded the stamped targets point at nothing — ONE warning per run
+        // (the fire itself proceeds; the stamp stays for whoever reads it).
+        if (action.deliver !== undefined && !deps.gatewayLoaded) {
+            console.warn("deliver targets ignored: no gateway");
+        }
         const model = action.model !== undefined
             ? parseModelSpec(action.model, "job action model")
             : deps.defaultModel;
@@ -207,7 +213,12 @@ async function firePrompt(deps, id, record, fireKey, baseRun, prior, context) {
                 await tx.doc(JobRunDoc, fireKey, run);
                 const meta = await tx.doc(SessionMetaDoc, newId);
                 meta.source = "cron";
+                // Gateway C7: the job stamp — typed SessionMeta fields (the
+                // pre-C7 cast is gone). Copy, never alias: the doc tracker
+                // takes alias-free ownership of the array.
                 meta.jobId = id;
+                if (action.deliver !== undefined)
+                    meta.deliver = [...action.deliver];
                 if (record.owner !== undefined)
                     meta.owner = record.owner;
                 if (action.runSharing !== undefined)

package/dist/jobs/spec.js

@@ -170,6 +170,23 @@ function validateAction(value) {
         if (record.runSharing !== undefined && !isSharing(record.runSharing)) {
             return invalid("action.runSharing", "runSharing must be a Sharing value");
         }
+        // Gateway C7 (spec §8.0): deliver targets ride ONLY new-conversation
+        // prompt jobs — a conversation bound to a chat already delivers
+        // there, so deliver on a fixed id is a spec error naming this field.
+        // Shape-only: the target grammar belongs to the gateway.
+        if (record.deliver !== undefined) {
+            if (record.conversation !== "new") {
+                return invalid("action.deliver", 'deliver requires conversation "new"');
+            }
+            if (!Array.isArray(record.deliver) ||
+                record.deliver.length < 1 ||
+                record.deliver.length > 8 ||
+                record.deliver.some((target) => typeof target !== "string" ||
+                    target.length < 1 ||
+                    target.length > 256)) {
+                return invalid("action.deliver", "deliver must be an array of 1-8 strings, each 1-256 chars");
+            }
+        }
         const action = {
             kind: "prompt",
             prompt: record.prompt,
@@ -182,6 +199,8 @@ function validateAction(value) {
             action.thinking = record.thinking;
         if (record.runSharing !== undefined)
             action.runSharing = record.runSharing;
+        if (record.deliver !== undefined)
+            action.deliver = [...record.deliver];
         return { ok: true, action };
     }
     if (record.kind === "task") {

package/dist/serve.js

@@ -28,8 +28,10 @@ import { envServerSection, loadConfig } from "./config.js";
 import { openHarness } from "./harness/boot.js";
 import { packagesDirOf, syncPackages } from "./harness/packages.js";
 import { defaultSettingsDir, SettingsStore } from "./harness/settings.js";
+import { startGateway } from "./server/gateway.js";
 import { SIGRUN_VERSION } from "./server/schema-fixture.js";
 import { createServer } from "./server/index.js";
+import { createShutdown } from "./server/shutdown.js";
 /**
  * Boot the harness + server composition and listen on
  * `options.host ?? "0.0.0.0"` + `<port>` (the default is the container's
@@ -88,44 +90,43 @@ export async function serve(env, options) {
     const { mkdir } = await import("node:fs/promises");
     await mkdir(config.workspace.path, { recursive: true });
     const opened = await openHarness(config, { extensionEntries: extensionResolutions });
+    // The gateway handle (gateway C2) exists BEFORE the server: the meta
+    // route reaches it through ServerContext, so the engine's health is
+    // reportable from the first request. The ENGINE STARTS after listen
+    // (below) — an engine supervising chat transports starts once the
+    // server it delivers through is up.
+    const gateway = startGateway(opened);
     // The contributed-bundle registry (build-and-webui Task 6): boot folded
     // the loader's extension contributions into the name-keyed registry;
     // the server's serve-time NAME-selector resolution reads it here.
     const app = await createServer(opened, config, opened.webuiBundles, {
         listenHost: options?.host ?? "0.0.0.0",
         env,
+        gateway,
     });
     const host = options?.host ?? "0.0.0.0";
     await app.listen({ port: config.port, host });
+    // The engine starts with the listener live (gateway C2's lifecycle:
+    // start after listen — a failed start latches degraded inside the
+    // handle, never wedges boot). AWAITED: serve() resolves only once the
+    // engine start completed (or failed-and-latched) — the constraint's
+    // intent; the lazy `started` never rejects, so this await cannot throw.
+    await gateway.started;
     // Machine-greppable: the deploy-entry test waits for this line, and an
     // operator reading pod logs sees the bound port without guessing. The
     // version rides the same line (what an operator quotes in a bug report).
     console.log(`sigrun v${SIGRUN_VERSION} listening on http://${host}:${config.port}`);
-    const shutdown = async () => {
-        const failures = [];
-        // SSE streams FIRST (the ctrl+c fix): hijacked event streams never
-        // end on their own, and app.close()'s drain waits for in-flight
-        // requests — with any webui tab open, shutdown hung forever on its
-        // /v1/events connection. End every live stream BEFORE the drain.
-        try {
-            app.sse.endAll();
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        try {
-            await app.close();
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        try {
-            await opened.eventBus.shutdownSequence(BACKGROUND_CONTEXT);
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        try {
+    // The ordered shutdown (gateway C2's extraction of the inline original
+    // into src/server/shutdown.ts): SSE streams FIRST, the app drain, the
+    // engine's intake close, the event-bus sequence (drain + flush), the
+    // engine stop, the refresh stop + bounded boot-refresh join, the
+    // harness close — each failure collected, all steps always run.
+    const shutdown = createShutdown({
+        endStreams: () => app.sse.endAll(),
+        closeApp: () => app.close(),
+        gateway,
+        eventBusShutdown: () => opened.eventBus.shutdownSequence(BACKGROUND_CONTEXT),
+        stopProviderRefresh: async () => {
             // The interval refresh scheduler (provider plugins Task 5) stops
             // BEFORE the harness closes. The T4 boot refresh promise is raced
             // against a bounded join: a wedged catalog fetch must not hold the
@@ -150,20 +151,9 @@ export async function serve(env, options) {
             if (!joined) {
                 console.warn(`sigrun: boot refresh still in flight after ${BOOT_REFRESH_JOIN_MS}ms at shutdown — abandoning the join`);
             }
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        try {
-            await opened.harness.close(BACKGROUND_CONTEXT);
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        if (failures.length > 0) {
-            throw new AggregateError(failures, "sigrun shutdown failed");
-        }
-    };
+        },
+        closeHarness: () => opened.harness.close(BACKGROUND_CONTEXT),
+    });
     let stopping;
     return {
         port: config.port,

package/dist/server/auth/pipeline.js

@@ -209,6 +209,7 @@ async function resolveProxy(request, ctx) {
     if (existing === undefined && !proxy.autoProvision) {
         return { status: 403, error: "user_not_provisioned" };
     }
+    const groupAdmin = groups.some((group) => adminGroups.includes(group));
     const record = existing ??
         (await users.add({
             user,
@@ -219,9 +220,23 @@ async function resolveProxy(request, ctx) {
                 ? {}
                 : { email: headerOf(request, proxy.emailHeader) }),
             admin: false,
+            // Gateway C8: the grant is stamped at provision — host-side
+            // checks (chat commands, no headers) read it from the record.
+            ...(adminGroups.length > 0 ? { groupAdmin } : {}),
             source: "proxy",
         }));
-    const groupAdmin = groups.some((group) => adminGroups.includes(group));
+    // Gateway C8 write-through: host-side code has no request headers, so
+    // the computed group grant must live on the directory record. Only a
+    // CHANGE writes (the steady state never rewrites the file), and only
+    // while `adminGroups` is configured — an empty list leaves the field
+    // untouched (a group-exit clears it at this user's next request under
+    // a non-empty list, never under an empty one). Absent counts as false;
+    // the auto-provisioned record was added with the flag already set, so
+    // the comparison is against the RESOLVED record, never `existing`.
+    if (adminGroups.length > 0 &&
+        (record.groupAdmin ?? false) !== groupAdmin) {
+        await users.update(user, { groupAdmin });
+    }
     return {
         user: record.user,
         ...(record.name === undefined ? {} : { name: record.name }),