@sigrun/sigrun 0.7.0 → 0.9.0

package/dist/harness/published-hooks.js

@@ -0,0 +1,208 @@
+/**
+ * Task 1 (knowledge plan): the published-hook registry — the pure core of
+ * the extension-to-extension call seam. Given the loader's declarations
+ * (configured extensions first, then built-ins; first per name owns), it
+ * builds a registry whose `call` validates the payload against the
+ * provider's compiled input schema, resolves the acting-user identity,
+ * runs the provider under a linked abort controller plus a deadline, and
+ * bounds payload size, result size, and recursion depth. `call` NEVER
+ * throws; validators compile ONCE here at build, and a schema that fails
+ * `Compile` throws FROM THE BUILD (Task 2 turns that into a load-time
+ * quarantine, so the build never sees one in production).
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Compile } from "typebox/compile";
+/** Legal hook names: dotted lowercase segments (`memory.recall`). */
+export const PUBLISHED_HOOK_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+/** Hook names are also bounded in length. */
+export const PUBLISHED_HOOK_NAME_MAX_CHARS = 128;
+/** Maximum hook-call nesting before `failed/too-deep`. */
+export const PUBLISHED_HOOK_MAX_DEPTH = 4;
+/** Payload and result size cap (1 MiB of JSON). */
+export const PUBLISHED_HOOK_MAX_BYTES = 1_048_576;
+const depthStorage = new AsyncLocalStorage();
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function describeErrors(validator, value) {
+    const out = [];
+    for (const err of validator.Errors(value)) {
+        out.push({ path: err.instancePath, message: err.message ?? "invalid" });
+    }
+    return out.length > 0 ? out : [{ path: "", message: "invalid" }];
+}
+export function buildPublishedHookRegistry(declarations, deps) {
+    // Ownership: the declarations arrive in loader order; configured
+    // extensions sort BEFORE built-ins regardless of arrival order, and
+    // the first per name owns it. Shadowed providers record under the
+    // owner (configured losers BEFORE built-in losers) and each loser
+    // warns once.
+    const ordered = [...declarations].sort((a, b) => Number(a.builtin) - Number(b.builtin));
+    const owners = new Map();
+    const shadowedBy = new Map();
+    for (const declaration of ordered) {
+        const hook = declaration.hook;
+        const existing = owners.get(hook.name);
+        if (existing) {
+            const owner = existing.declaration.extension;
+            const loser = declaration.extension;
+            const advice = declaration.builtin
+                ? `replace the built-in ${loser} by package name, or remove ${owner}`
+                : "reorder extensions[] to switch";
+            deps.warn(`published hook "${hook.name}": owned by ${owner}, shadowed ${loser} — ${advice}`);
+            const list = shadowedBy.get(hook.name);
+            if (list)
+                list.push(loser);
+            else
+                shadowedBy.set(hook.name, [loser]);
+            continue;
+        }
+        owners.set(hook.name, {
+            declaration,
+            input: Compile(hook.input),
+            output: hook.output !== undefined ? Compile(hook.output) : undefined,
+        });
+    }
+    async function call(caller, name, payload, opts = {}) {
+        // Depth is checked BEFORE ownership lookup so a nested call under
+        // an unknown name still reports too-deep rather than absent.
+        const depth = depthStorage.getStore() ?? 0;
+        if (depth >= PUBLISHED_HOOK_MAX_DEPTH) {
+            return {
+                status: "failed",
+                provider: owners.get(name)?.declaration.extension ?? "?",
+                reason: "too-deep",
+                error: `published hook depth ${depth + 1} exceeds ${PUBLISHED_HOOK_MAX_DEPTH}`,
+            };
+        }
+        const entry = owners.get(name);
+        if (!entry)
+            return { status: "absent" };
+        const provider = entry.declaration.extension;
+        let serialized;
+        try {
+            serialized = JSON.stringify(payload);
+        }
+        catch (err) {
+            return {
+                status: "rejected",
+                provider,
+                errors: [{ path: "", message: `payload is not JSON-serializable: ${errorMessage(err)}` }],
+            };
+        }
+        if (serialized.length > PUBLISHED_HOOK_MAX_BYTES) {
+            return {
+                status: "rejected",
+                provider,
+                errors: [
+                    {
+                        path: "",
+                        message: `payload is ${serialized.length} bytes; the cap is ${PUBLISHED_HOOK_MAX_BYTES}`,
+                    },
+                ],
+            };
+        }
+        if (!entry.input.Check(payload)) {
+            return { status: "rejected", provider, errors: describeErrors(entry.input, payload) };
+        }
+        let user;
+        if (opts.conversationId !== undefined) {
+            user = await deps.actingUser(opts.conversationId);
+            if (opts.user !== undefined && opts.user !== user) {
+                return {
+                    status: "rejected",
+                    provider,
+                    errors: [
+                        {
+                            path: "user",
+                            message: `caller declares user "${opts.user}" but the conversation's acting user is "${user ?? "unknown"}"`,
+                        },
+                    ],
+                };
+            }
+        }
+        else {
+            user = opts.user;
+        }
+        const controller = new AbortController();
+        let timedOut = false;
+        let callerAborted = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, deps.deadlineMs);
+        const onCallerAbort = () => {
+            callerAborted = true;
+            controller.abort();
+        };
+        opts.abortSignal?.addEventListener("abort", onCallerAbort, { once: true });
+        const hookCall = {
+            caller,
+            user,
+            conversationId: opts.conversationId,
+            abortSignal: controller.signal,
+        };
+        let value;
+        try {
+            value = await depthStorage.run(depth + 1, () => entry.declaration.hook.run(payload, hookCall));
+        }
+        catch (err) {
+            const reason = timedOut ? "timeout" : callerAborted ? "aborted" : "threw";
+            return { status: "failed", provider, reason, error: errorMessage(err) };
+        }
+        finally {
+            clearTimeout(timer);
+            opts.abortSignal?.removeEventListener("abort", onCallerAbort);
+        }
+        let resultJson;
+        try {
+            resultJson = JSON.stringify(value);
+        }
+        catch (err) {
+            return {
+                status: "failed",
+                provider,
+                reason: "too-large",
+                error: `result is not JSON-serializable: ${errorMessage(err)}`,
+            };
+        }
+        if (resultJson.length > PUBLISHED_HOOK_MAX_BYTES) {
+            return {
+                status: "failed",
+                provider,
+                reason: "too-large",
+                error: `result is ${resultJson.length} bytes; the cap is ${PUBLISHED_HOOK_MAX_BYTES}`,
+            };
+        }
+        if (entry.output && !entry.output.Check(value)) {
+            const first = describeErrors(entry.output, value)[0];
+            return {
+                status: "failed",
+                provider,
+                reason: "bad-output",
+                error: `result fails the declared output schema at ${first?.path ?? ""}: ${first?.message ?? "invalid"}`,
+            };
+        }
+        return { status: "ok", provider, value };
+    }
+    return {
+        get(name) {
+            const entry = owners.get(name);
+            if (!entry)
+                return undefined;
+            return {
+                provider: entry.declaration.extension,
+                input: entry.declaration.hook.input,
+                output: entry.declaration.hook.output,
+            };
+        },
+        call,
+        listing() {
+            return [...owners.entries()].map(([name, entry]) => ({
+                name,
+                provider: entry.declaration.extension,
+                shadowed: shadowedBy.get(name) ?? [],
+            }));
+        },
+    };
+}

package/dist/harness/seam-host.js

@@ -17,7 +17,7 @@
  * extension; a throw later (tool execute) surfaces to the caller.
  */
 import { AmbientDoc, AmbientOwnersDoc, validateAmbient, } from "./ambient.js";
-import { InteractionDoc, InteractionsIndexDoc, applyAnswer, asInteractionRecord, indexPending, indexSettled, sweepSecretDelivery, takeSecretDelivery, validateInteraction, } from "./interactions.js";
+import { InteractionDoc, InteractionsIndexDoc, QueuedHumanInputsDoc, applyAnswer, applyDecline, asInteractionRecord, indexPending, indexSettled, sweepSecretDelivery, takeSecretDelivery, validateInteraction, } from "./interactions.js";
 import { toDurableContext } from "./context.js";
 import { scopedExtensionStores, } from "./stores.js";
 /** One seam violation. Name carries the surface ("interaction"/"ambient"). */
@@ -212,11 +212,79 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
                 throw new SeamError("interaction", problem);
             context = toDurableContext(context);
             const h = await harness(context);
+            // A declinable record seeded after a human message is immediately
+            // declined when that message is still queued (ask-user Task 2,
+            // spec 5.3): the message was admitted BEFORE the card existed and
+            // must never get stuck behind it. Read each recorded submission's
+            // current status here (outside the commit — submission status is
+            // a table read) and drop any entry that is no longer queued.
+            let preDeclineUser;
+            let preDeclined = false;
+            const stillQueuedIds = new Set();
+            const seen = new Set();
+            if (record.declinable === true) {
+                const queuedDoc = await h.snapshot(QueuedHumanInputsDoc, conversationId, context);
+                const byId = queuedDoc?.byId ?? {};
+                // Snapshot key set: the commit-time cleanup below may only drop
+                // keys THIS read saw. A submission recorded by a concurrent
+                // submitOp ledger commit that lands between the snapshot and our
+                // commit is not in `seen` and must survive.
+                for (const key of Object.keys(byId))
+                    seen.add(key);
+                const stillQueued = [];
+                for (const [submissionId] of Object.entries(byId)) {
+                    const submission = await h.submission(Number(submissionId), context);
+                    if (submission === undefined)
+                        continue; // gone — drop below
+                    const status = await submission.status(context);
+                    // Fork isolation: QueuedHumanInputsDoc forks with the
+                    // conversation, so a child inherits the parent's entries.
+                    // Only same-conversation submissions count as queued here.
+                    if (status.status === "queued" &&
+                        status.conversationId === conversationId) {
+                        stillQueued.push(submissionId);
+                        stillQueuedIds.add(submissionId);
+                    }
+                }
+                if (stillQueued.length > 0) {
+                    // Earliest recorded submission wins (ascending id order).
+                    stillQueued.sort((a, b) => Number(a) - Number(b));
+                    preDeclineUser = byId[stillQueued[0]]?.user;
+                    preDeclined = true;
+                }
+            }
             await h.commit(async (tx) => {
                 // Maintain the index in the SAME commit as the record.
                 const existing = await tx.doc(InteractionDoc, conversationId, record.callId, record.callId);
                 if (existing.status !== "pending")
                     return; // first-write wins
+                if (record.declinable === true) {
+                    // Drop ledger entries whose submission is no longer queued
+                    // (they were read above; only stale ones are removed).
+                    const queuedDraft = await tx.doc(QueuedHumanInputsDoc, conversationId);
+                    const mutableById = queuedDraft.byId;
+                    for (const key of Object.keys(mutableById)) {
+                        if (seen.has(key) && !stillQueuedIds.has(key)) {
+                            delete mutableById[key];
+                        }
+                    }
+                }
+                if (preDeclined) {
+                    // Seed already settled: the human's queued message declines
+                    // the question before it is ever shown. Reuses applyDecline's
+                    // single definition of the settled shape.
+                    Object.assign(existing, record);
+                    // A self-declared-terminal seed (the extension passed a
+                    // non-pending status) must NOT survive the assign: the
+                    // queued human message declined it, so applyDecline stamps
+                    // declinedVia/answeredBy on a pending baseline.
+                    Object.assign(existing, { status: "pending" });
+                    applyDecline(existing, "message", Date.now(), preDeclineUser);
+                    // No index entry — it is not pending. Sweep any secret
+                    // delivery staged for this record (defensive).
+                    sweepSecretDelivery(conversationId, record.callId);
+                    return;
+                }
                 Object.assign(existing, record);
                 const index = await tx.doc(InteractionsIndexDoc);
                 indexPending(index, conversationId, record.callId);
@@ -264,6 +332,22 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
                 return true;
             }, context);
         },
+        async declineInteraction(conversationId, callId, context, opts) {
+            context = toDurableContext(context);
+            const h = await harness(context);
+            // Same commit shape as settleInteraction: the sweep lands INSIDE
+            // the commit and only on the applied terminal transition.
+            return await h.commit(async (tx) => {
+                const draft = await tx.doc(InteractionDoc, conversationId, callId, callId);
+                const outcome = applyDecline(draft, "button", Date.now(), opts?.user);
+                if (outcome !== "declined")
+                    return false;
+                const index = await tx.doc(InteractionsIndexDoc);
+                indexSettled(index, conversationId, callId);
+                sweepSecretDelivery(conversationId, callId);
+                return true;
+            }, context);
+        },
         async peekInteraction(conversationId, callId, context) {
             // The non-consuming inspection read (release-readiness-2 §1):
             // the SAME stored projection as snapshotInteraction, with NO
@@ -422,6 +506,12 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
             async get(id) {
                 return (await hostBridge("jobs.get")).jobs.get(id);
             },
+            async activeRun(conversationId) {
+                return (await hostBridge("jobs.activeRun")).jobs.activeRun(conversationId);
+            },
+            async isJobRun(conversationId, context) {
+                return (await hostBridge("jobs.isJobRun")).jobs.isJobRun(conversationId, context);
+            },
         },
         users: {
             async list() {
@@ -530,6 +620,29 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
             async list() {
                 return (await hostBridge("models.list")).models.list();
             },
+            async complete(input) {
+                return (await hostBridge("models.complete")).models.complete(input);
+            },
+        },
+        // Warden Task 6: the decisions surface delegates to the host
+        // bridge (the bridge owns the registry's body); `caller` is the
+        // identity name read AT CALL TIME (the same rekey-aware pattern as
+        // `publishedHooks.call` — the host rekeys in place), so a calling
+        // extension can never claim another identity.
+        decisions: {
+            async evaluate(request, opts = {}) {
+                const bridge = await hostBridge("decisions.evaluate");
+                if (bridge.decisions === undefined) {
+                    return { ok: false, code: "no_model", error: "no decision provider is registered" };
+                }
+                return bridge.decisions.evaluate(identity.name, request, opts);
+            },
+            async list() {
+                const bridge = await hostBridge("decisions.list");
+                if (bridge.decisions === undefined)
+                    return [];
+                return bridge.decisions.list();
+            },
         },
         commands: {
             async list() {
@@ -542,6 +655,19 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
         async notify(input) {
             return (await hostBridge("notify")).notify(identity.name, input);
         },
+        // Notices Task 3: the per-user notices channel — the bridge owns
+        // every body, the seam host supplies its slug (the notify pattern).
+        notices: {
+            async post(input) {
+                return (await hostBridge("notices.post")).notices.post(identity.name, input);
+            },
+            async clear(selector) {
+                return (await hostBridge("notices.clear")).notices.clear(identity.name, selector);
+            },
+            async list(user) {
+                return (await hostBridge("notices.list")).notices.list(identity.name, user);
+            },
+        },
         // 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
@@ -574,6 +700,28 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
                 });
             },
         },
+        // Knowledge C7: the seam's published-hook surface. `get` reads the
+        // slot directly (undefined while loading still runs); `call` waits
+        // for the registry-ready deferred, then delegates with the caller
+        // identity read AT CALL TIME (the host rekeys in place).
+        publishedHooks: {
+            get(name) {
+                return options?.publishedHooks?.current.registry?.get(name);
+            },
+            async call(name, payload, opts) {
+                const slot = options?.publishedHooks;
+                if (slot === undefined) {
+                    // No registry wiring (a bare-loader test rig): every name is
+                    // absent — `call` never throws.
+                    return { status: "absent" };
+                }
+                await slot.ready;
+                const registry = slot.current.registry;
+                if (registry === undefined)
+                    return { status: "absent" };
+                return registry.call(identity.name, name, payload, opts);
+            },
+        },
         bindBridge(bridge) {
             bridgeBound = true;
             bridgeReleased(bridge);

package/dist/harness/settings.js

@@ -91,6 +91,8 @@ const SETTING_KEYS = [
     "jobHistory",
     "defaultModel",
     "namingModel",
+    "decisionModel",
+    "decisions",
     "defaultProvider",
     "skills",
     "notifications",
@@ -326,6 +328,33 @@ function validate(value) {
             throw new SettingsValidationError("namingModel", "must have a non-empty provider and model id");
         }
     }
+    if (value.decisionModel !== undefined) {
+        // Exactly defaultModel's spec rules (no `false` disable — a
+        // decision call without a default resolves the first-registered
+        // provider's first model).
+        const spec = value.decisionModel;
+        if (typeof spec !== "string" || spec.trim() === "") {
+            throw new SettingsValidationError("decisionModel", "must be a non-empty provider/model-id string");
+        }
+        const trimmed = spec.trim();
+        const slash = trimmed.indexOf("/");
+        if (slash !== -1 &&
+            (trimmed.slice(0, slash) === "" || trimmed.slice(slash + 1) === "")) {
+            throw new SettingsValidationError("decisionModel", "must have a non-empty provider and model id");
+        }
+    }
+    // The decision surface's toggles (warden Task 6): a flat section —
+    // `tool` a boolean.
+    if (value.decisions !== undefined) {
+        const decisions = asRecord(value.decisions);
+        if (decisions === undefined) {
+            throw new SettingsValidationError("decisions", "must be an object");
+        }
+        checkKeys("decisions.", decisions, ["tool"]);
+        if (decisions.tool !== undefined && typeof decisions.tool !== "boolean") {
+            throw new SettingsValidationError("decisions.tool", "must be a boolean");
+        }
+    }
     if (value.defaultProvider !== undefined) {
         const provider = asRecord(value.defaultProvider);
         if (provider === undefined) {
@@ -418,6 +447,7 @@ function validateServer(server) {
         "dev",
         "supervised",
         "backup",
+        "decisions",
     ]);
     // The jobs default timezone (§8.2): an IANA name — `Intl` accepts
     // exactly the names croner's evaluation path resolves, and throws on
@@ -570,6 +600,17 @@ function validateServer(server) {
             }
         }
     }
+    if (record.decisions !== undefined) {
+        const decisions = asRecord(record.decisions);
+        if (decisions === undefined) {
+            throw new SettingsValidationError("server.decisions", "must be an object");
+        }
+        checkKeys("server.decisions.", decisions, ["timeoutMs"]);
+        if (decisions.timeoutMs !== undefined &&
+            !isPositiveInt(decisions.timeoutMs)) {
+            throw new SettingsValidationError("server.decisions.timeoutMs", "must be a positive integer");
+        }
+    }
     if (record.isolation !== undefined) {
         const isolation = asRecord(record.isolation);
         if (isolation === undefined) {

package/dist/history/git.js

@@ -490,8 +490,12 @@ export class GitHistory {
     }
     /** Corrupt git dir → move aside, re-init, snapshot commit (loud log). */
     async recoverCorrupt() {
-        const brokenName = `${this.spec.gitDir.split(sep).pop() ?? "repo"}.broken-${utcStamp(this.now())}`;
-        const brokenPath = `${this.spec.gitDir}.broken-${utcStamp(this.now())}`;
+        // ONE stamp: the summary must name the directory the rename made —
+        // two utcStamp(now) calls can straddle a clock tick and name a
+        // path that was never created (seen as a CI flake).
+        const stamp = utcStamp(this.now());
+        const brokenName = `${this.spec.gitDir.split(sep).pop() ?? "repo"}.broken-${stamp}`;
+        const brokenPath = `${this.spec.gitDir}.broken-${stamp}`;
         await rename(this.spec.gitDir, brokenPath);
         this.logLine(`corrupt git dir moved aside: ${this.spec.gitDir} → ${brokenPath}`);
         await this.run(["init", "--initial-branch=main"]);

package/dist/jobs/fire.js

@@ -38,6 +38,7 @@ import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { parseModelSpec } from "../config.js";
 import { expandInput } from "../commands/expand.js";
 import { SessionMetaDoc } from "../server/session-meta.js";
+import { excludeInteractiveTools } from "../harness/interactive-tools.js";
 import { noteThen } from "../server/turns/submit-turn.js";
 import { recordAuthor } from "../curation/attribution.js";
 import { JobRunDoc, patchJob, readJob } from "./docs.js";
@@ -172,6 +173,11 @@ async function firePrompt(deps, id, record, fireKey, baseRun, prior, context) {
         if (prior === undefined) {
             await deps.harness.commit(async (tx) => {
                 await tx.doc(JobRunDoc, fireKey, run);
+                // NO meta.jobId stamp here (the 2026-11-05 reconciliation with
+                // ask-user's isJobRun): a fire INTO an existing conversation must
+                // not mark every later run of that conversation job-driven. The
+                // runSettled observer settles this run from the submission's
+                // `job:<fireKey>` requestId instead (observe.ts).
             }, context);
             await patchJob(deps.harness, id, (draft) => {
                 draft.lastRun = run;
@@ -233,6 +239,10 @@ async function firePrompt(deps, id, record, fireKey, baseRun, prior, context) {
                 if (owner !== undefined)
                     meta.owner = owner;
                 await deps.rewriteUserSelection?.(tx, newId, undefined, owner);
+                // Ask-user Task 3: the job-run conversation never offers an
+                // interactive tool (the tool is never listed, so the model
+                // never tries — §6's prompt section keys off tool presence).
+                await excludeInteractiveTools(tx, newId, deps.interactiveTools ?? new Set());
                 if (action.runSharing !== undefined)
                     meta.sharing = action.runSharing;
                 meta.name = runName(record.spec.name, deps.now(), record, deps);

package/dist/jobs/observe.js

@@ -66,9 +66,34 @@ export function registerJobObservers(deps) {
     // auto-namer — a job observation never delays an extension's).
     const runSettled = async (event) => {
         try {
+            // The job to settle from, in resolution order:
+            //  1. the session meta's `jobId` (a `conversation: "new"` fire —
+            //     the stamp persists for the conversation's life);
+            //  2. a `job:<fireKey>` requestId on one of the run's inputs (the
+            //     FIXED-conversation fire shape — `jobs/fire.ts` stamps the
+            //     prefix on BOTH shapes; a fire INTO an existing conversation
+            //     deliberately leaves the meta unstamped so later ordinary
+            //     runs there are not job runs, per isJobRun's contract).
+            let jobId;
             const meta = await deps.harness.snapshot(SessionMetaDoc, event.conversationId, ctx);
-            const jobId = meta?.jobId;
-            if (typeof jobId !== "string")
+            const metaJobId = meta?.jobId;
+            if (typeof metaJobId === "string") {
+                jobId = metaJobId;
+            }
+            else {
+                for (const id of event.inputs) {
+                    const submission = await deps.harness.submission(id, ctx);
+                    if (submission === undefined)
+                        continue;
+                    const record = await submission.status(ctx);
+                    const requestId = record.requestId;
+                    if (requestId !== undefined && requestId.startsWith("job:")) {
+                        jobId = requestId.slice("job:".length).split(":")[0];
+                        break;
+                    }
+                }
+            }
+            if (jobId === undefined)
                 return;
             const runs = await listRuns(deps.storage, jobId, Number.MAX_SAFE_INTEGER, ctx);
             const run = runs.find((one) => one.outcome === "running" &&

package/dist/notices/events.js

@@ -0,0 +1,8 @@
+/**
+ * The hub-internal notice.changed event (notices spec §4): the wire shape
+ * PLUS the recipient `user`, attached at publish time (the store's
+ * `NoticeChange` always names its user). The events route reads `user`
+ * and strips it before delivery — the wire shape carries no user, and a
+ * notice event never crosses to another principal's stream.
+ */
+export {};