@sigrun/sigrun 0.8.0 → 0.9.0

package/dist/harness/interactive-tools.js

@@ -0,0 +1,97 @@
+/**
+ * Interactive tools (ask-user Task 3, spec §6): the helpers that hide an
+ * extension's `interactiveTools` — tool names that need a human present —
+ * from every NON-INTERACTIVE run core creates.
+ *
+ * Core owns the definition of a non-interactive conversation (spec §6):
+ * scheduled job run conversations and the curator's internal runs. In
+ * those conversations core leaves interactive tools out of the offered
+ * tools at creation time by removing them from the ENABLED-tools filter
+ * (pi-durable `AgentDoc.tools`): a removal there makes the tool neither
+ * offered to the model NOR reachable from nested `executeTool()` calls
+ * (the nested resolution reads the same enabled set), which no
+ * `modelTools` narrowing could give.
+ *
+ * Fork reviews deliberately do NOT pass through here — they copy the
+ * parent's stored selection for byte-identical prompt prefixes (cache
+ * parity), and the curation gate blocks an interactive call instead.
+ *
+ * Jobs that fire into an EXISTING conversation are not covered by this
+ * creation-time filter either (the conversation predates the fire);
+ * the tool stays listed and must guard its own execute with
+ * `host.jobs.isJobRun` (spec §6's option A).
+ */
+import { AgentDoc, LiveDoc } from "@earendil-works/pi-durable";
+import { SessionMetaDoc } from "../server/session-meta.js";
+/**
+ * Remove every name in `names` from the conversation's stored
+ * `AgentDoc.tools` enabled filter, preserving the stored shape:
+ * - unset → `{remove: [...names].sort()}`;
+ * - an object → `remove ∪ names` (sorted);
+ * - an array → the array without the names.
+ *
+ * A no-op when `names` is empty (the no-interactive-extension deploy
+ * writes nothing). Runs inside an existing commit (the callers are the
+ * creating commits and the server create op's post-create stamp commit);
+ * document access only — no table reads.
+ */
+export async function excludeInteractiveTools(tx, conversationId, names) {
+    if (names.size === 0)
+        return;
+    const agent = await tx.doc(AgentDoc, conversationId);
+    const stored = agent.tools;
+    if (stored === undefined) {
+        agent.tools = { remove: [...names].sort() };
+        return;
+    }
+    if (Array.isArray(stored)) {
+        agent.tools = stored.filter((name) => !names.has(name));
+        return;
+    }
+    agent.tools = {
+        remove: [...new Set([...stored.remove, ...names])].sort(),
+    };
+}
+/**
+ * Whether the conversation's CURRENT run is job-driven (ask-user Task 3,
+ * spec §6): true when the session meta carries a `jobId` (a
+ * `conversation: "new"` run — the stamp persists past the run's settle,
+ * which is fine: every run of that conversation is a job run), or any
+ * input of the conversation's current run (`LiveDoc` `run.inputs`,
+ * present exactly while busy) resolves to a submission whose requestId
+ * carries the job prefix (`job:<fireKey>`, stamped by `jobs/fire.ts` on
+ * BOTH fire shapes — that branch covers a job firing into an EXISTING
+ * conversation, which carries no `jobId`). Interactive tools call this in
+ * execute and refuse instead of waiting on a human.
+ */
+export async function isJobRunConversation(harness, conversationId, context) {
+    const meta = await harness.snapshot(SessionMetaDoc, conversationId, context);
+    if (meta?.jobId !== undefined)
+        return true;
+    const live = await harness.snapshot(LiveDoc, conversationId, context);
+    for (const id of live?.run?.inputs ?? []) {
+        const submission = await harness.submission(id, context);
+        if (submission === undefined)
+            continue;
+        const record = await submission.status(context);
+        if (record.requestId?.startsWith("job:"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Filter `list` to the names outside `names` (a curator run's `allow`
+ * list losing its interactive members). Never fails — stripping must not
+ * let installing an interactive-tool extension break unrelated curation
+ * targets — but warns ONCE per call naming the removed tools and `where`
+ * (an all-interactive list then still hits the existing
+ * non-empty-`allow` check, loudly). Returns a fresh array in every case
+ * (the tracker requires alias-free roots).
+ */
+export function withoutInteractive(list, names, warn, where) {
+    const removed = list.filter((name) => names.has(name));
+    if (removed.length === 0)
+        return [...list];
+    warn(`interactive tools [${removed.join(", ")}] removed from the ${where} allow list — they need a human present`);
+    return list.filter((name) => !names.has(name));
+}

package/dist/harness/loader.js

@@ -92,7 +92,9 @@ import { fileURLToPath } from "node:url";
 import { satisfies, validRange } from "semver";
 import { HOST_RUNTIME_MODULES, hostModuleVersion, readPackageAssetsDir, readPackageName, readPackageVersion, resolveExtensionEntry, } from "./packages.js";
 import { RESERVED_CORE_SECTION_KEYS, RESERVED_EXTENSION_SLUGS, } from "./reserved-sections.js";
+import { Compile } from "typebox/compile";
 import { slugifyName } from "./stores.js";
+import { PUBLISHED_HOOK_NAME, PUBLISHED_HOOK_NAME_MAX_CHARS, } from "./published-hooks.js";
 import { wrapExtensionCurationTools } from "../curation/wrap.js";
 /** Every lifecycle field name, in validation order (mirrors the contract doc). */
 const LIFECYCLE_FIELDS = [
@@ -142,6 +144,29 @@ function validateKinds(value) {
     }
     return null;
 }
+/**
+ * Validate the `interactiveTools` declaration (ask-user Task 3, spec §6):
+ * an array of non-empty strings, every one naming a tool the extension's
+ * OWN `extension.tools` registers (hiding a tool the extension never
+ * registered is a declaration bug — it quarantines, loudly).
+ */
+function validateInteractiveTools(value, extension) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("interactiveTools must be an array of strings");
+    }
+    if (value.some((name) => typeof name !== "string" || name.length === 0)) {
+        throw new Error("interactiveTools must be an array of non-empty strings");
+    }
+    const registered = new Set(extension?.tools?.map((tool) => tool.name) ?? []);
+    for (const name of value) {
+        if (!registered.has(name)) {
+            throw new Error(`interactiveTools names "${name}", which this extension does not register`);
+        }
+    }
+    return value;
+}
 /**
  * The lifecycle event names a worker's `wakeOn` may declare (memory-seam
  * Task 5): `harnessShutdown` is excluded — workers stop BEFORE the shutdown
@@ -262,6 +287,122 @@ function validateNoticeActions(value) {
     }
     return actions;
 }
+/**
+ * Validate a factory result's `publishedHooks` declaration (knowledge C7).
+ * Absent → undefined (no hooks). Present but malformed → throw; the loader
+ * quarantines the extension with the thrown message (fail-loud: an
+ * extension that THINKS it published a hook must not silently lose it).
+ * Per entry: a string `name` matching {@link PUBLISHED_HOOK_NAME} (and the
+ * length bound), no intra-extension duplicates, `input` an object, `run` a
+ * function — plus a `Compile` of both schemas, which is what makes the
+ * registry build's compile-throw unreachable in production.
+ */
+function validatePublishedHooks(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a publishedHooks field that is not an array");
+    }
+    const seen = new Set();
+    for (const entry of value) {
+        const hook = entry;
+        const name = hook?.name;
+        if (typeof name !== "string" ||
+            name.length > PUBLISHED_HOOK_NAME_MAX_CHARS ||
+            !PUBLISHED_HOOK_NAME.test(name)) {
+            throw new Error(`extension factory returned a published hook with an invalid name ${JSON.stringify(name)} (must match ${PUBLISHED_HOOK_NAME.source}, ≤${PUBLISHED_HOOK_NAME_MAX_CHARS} chars)`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`extension factory returned a duplicate published hook name "${name}"`);
+        }
+        seen.add(name);
+        if (typeof hook?.input !== "object" ||
+            hook.input === null ||
+            Array.isArray(hook.input)) {
+            throw new Error(`extension factory returned a published hook "${name}" whose input is not a schema object`);
+        }
+        if (hook.output !== undefined && (typeof hook.output !== "object" || hook.output === null)) {
+            throw new Error(`extension factory returned a published hook "${name}" whose output is not a schema object`);
+        }
+        if (typeof hook?.run !== "function") {
+            throw new Error(`extension factory returned a published hook "${name}" whose run is not a function`);
+        }
+        // Compile ONCE here: a schema that fails to compile quarantines the
+        // extension at load, so the registry build never sees one.
+        try {
+            Compile(hook.input);
+            if (hook.output !== undefined)
+                Compile(hook.output);
+        }
+        catch (err) {
+            throw new Error(`extension factory returned a published hook "${name}" whose schema fails to compile: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return value;
+}
+/** The decision-provider id grammar (warden Task 6): also the auth.json key. */
+const DECISION_PROVIDER_ID = /^[a-z][a-z0-9-]*$/;
+/** The decision-provider id length bound. */
+const DECISION_PROVIDER_ID_MAX_CHARS = 64;
+/** The decision-model id grammar (the `"<provider>/<model>"` spec's second half). */
+const DECISION_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+/** The `credentialEnv` grammar: a process-env NAME. */
+const DECISION_CREDENTIAL_ENV = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * Validate a factory result's `decisionProviders` declaration (warden
+ * Task 6). Absent → undefined (no contributions). Present but malformed
+ * → throw; the loader quarantines the extension with the thrown message
+ * (fail-loud: an extension that THINKS it contributed a decision
+ * provider must not silently lose it — the providers/health class).
+ * Per entry: a string `id` matching {@link DECISION_PROVIDER_ID} (≤64
+ * chars), at least one model whose ids match {@link DECISION_MODEL_ID}
+ * with no intra-provider duplicates, `evaluate` a function, `readiness`
+ * absent or a function, and `credentialEnv` absent or a NAME.
+ */
+function validateDecisionProviders(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a decisionProviders field that is not an array");
+    }
+    for (const entry of value) {
+        const provider = entry;
+        if (typeof provider?.id !== "string" ||
+            provider.id.length > DECISION_PROVIDER_ID_MAX_CHARS ||
+            !DECISION_PROVIDER_ID.test(provider.id)) {
+            throw new Error(`extension factory returned a decision provider with an invalid id ${JSON.stringify(provider?.id)} (must match ${DECISION_PROVIDER_ID.source}, ≤${DECISION_PROVIDER_ID_MAX_CHARS} chars)`);
+        }
+        if (!Array.isArray(provider.models) ||
+            provider.models.length === 0) {
+            throw new Error(`extension factory returned a decision provider "${provider.id}" with no models`);
+        }
+        const seen = new Set();
+        for (const model of provider.models) {
+            const modelId = model?.id;
+            if (typeof modelId !== "string" ||
+                !DECISION_MODEL_ID.test(modelId)) {
+                throw new Error(`extension factory returned a decision provider "${provider.id}" with an invalid model id ${JSON.stringify(modelId)} (must match ${DECISION_MODEL_ID.source})`);
+            }
+            if (seen.has(modelId)) {
+                throw new Error(`extension factory returned a decision provider "${provider.id}" with a duplicate model id "${modelId}"`);
+            }
+            seen.add(modelId);
+        }
+        if (typeof provider.evaluate !== "function") {
+            throw new Error(`extension factory returned a decision provider "${provider.id}" whose evaluate is not a function`);
+        }
+        if (provider.readiness !== undefined &&
+            typeof provider.readiness !== "function") {
+            throw new Error(`extension factory returned a decision provider "${provider.id}" whose readiness is not a function`);
+        }
+        if (provider.credentialEnv !== undefined &&
+            (typeof provider.credentialEnv !== "string" ||
+                !DECISION_CREDENTIAL_ENV.test(provider.credentialEnv))) {
+            throw new Error(`extension factory returned a decision provider "${provider.id}" with an invalid credentialEnv ${JSON.stringify(provider.credentialEnv)} (must match ${DECISION_CREDENTIAL_ENV.source})`);
+        }
+    }
+    return value;
+}
 function validateCurationTargets(value) {
     if (value === undefined)
         return undefined;
@@ -290,6 +431,29 @@ function validateCurationTargets(value) {
             typeof target.maintain !== "function") {
             throw new Error(`extension factory returned a curation target "${name}" whose maintain is not a function`);
         }
+        // C5: readTools — an array of non-empty strings DISJOINT from
+        // tools (a read tool is never wrapped; a name on both lists is a
+        // contradiction). The registered-by-the-declaring-extension check
+        // lives in the load loop (no registry here).
+        const readTools = target?.readTools;
+        if (readTools !== undefined) {
+            if (!Array.isArray(readTools) ||
+                readTools.some((tool) => typeof tool !== "string" || tool.length === 0)) {
+                throw new Error(`extension factory returned a curation target "${name}" whose readTools is not an array of non-empty strings`);
+            }
+            const overlap = readTools.find((tool) => tools.includes(tool));
+            if (overlap !== undefined) {
+                throw new Error(`extension factory returned a curation target "${name}" whose readTools names "${overlap}" — a tool is either listed (wrapped) or read (never wrapped), never both`);
+            }
+        }
+        if (target?.wantsReview !== undefined &&
+            typeof target.wantsReview !== "function") {
+            throw new Error(`extension factory returned a curation target "${name}" whose wantsReview is not a function`);
+        }
+        if (target?.reviewed !== undefined &&
+            typeof target.reviewed !== "function") {
+            throw new Error(`extension factory returned a curation target "${name}" whose reviewed is not a function`);
+        }
         targets.push(entry);
     }
     return targets;
@@ -518,6 +682,18 @@ function validateSurfaces(value) {
                 typeof def.sharedData !== "boolean") {
                 throw new Error(`extension factory returned a surface "${def.id}" whose sharedData is not a boolean`);
             }
+            if (def?.perConversation !== undefined &&
+                typeof def.perConversation !== "boolean") {
+                throw new Error(`extension factory returned a surface "${def.id}" whose perConversation is not a boolean`);
+            }
+            // The flag is a PANEL property: a view cannot be attached to a
+            // conversation, so declaring it there is a declaration the host
+            // would silently ignore — fail loud. (The settings-section list is
+            // validated separately by `validateSettingsSections`, which does
+            // not read this flag.)
+            if (def?.perConversation !== undefined && expected !== "panel") {
+                throw new Error(`extension factory returned a surface "${def.id}" declares perConversation but is not a panel`);
+            }
             if (def?.actions !== undefined) {
                 if (typeof def.actions !== "object" ||
                     def.actions === null ||
@@ -1209,6 +1385,9 @@ async function resolvedFromFactory(factory, hostContext) {
         throw new Error("extension factory returned a perUserTools field that is not a boolean");
     }
     const providers = validateProviders(candidate.providers);
+    // Decision providers (warden Task 6): validated with the other
+    // contribution fields, BEFORE the contributor-only check reads them.
+    const decisionProviders = validateDecisionProviders(candidate.decisionProviders);
     const loginProviders = validateLoginProviders(candidate.loginProviders);
     const webuiBundles = validateWebuiBundles(candidate.webuiBundles);
     const jobs = validateJobs(candidate.jobs);
@@ -1237,7 +1416,8 @@ async function resolvedFromFactory(factory, hostContext) {
             loginProviders === undefined &&
             webuiBundles === undefined &&
             channels === undefined &&
-            userServices === undefined) {
+            userServices === undefined &&
+            decisionProviders === undefined) {
             return undefined;
         }
         if (typeof candidate.name !== "string" || candidate.name.length === 0) {
@@ -1271,6 +1451,11 @@ async function resolvedFromFactory(factory, hostContext) {
         validateKinds(candidate.ambientKinds);
     if (kindsProblem !== null)
         throw new Error(kindsProblem);
+    // Interactive tools (ask-user Task 3, spec §6): an array of non-empty
+    // strings, each naming a tool the extension's OWN `extension.tools`
+    // registers — hiding a tool the extension never registered is a
+    // declaration bug that must quarantine, never silently no-op.
+    const interactiveTools = validateInteractiveTools(candidate.interactiveTools, extension);
     // The settings-change hook (U4 §13.2): present-but-not-a-function is
     // the same contract violation class as the lifecycle fields — an
     // extension that THINKS it observes settings changes must not
@@ -1288,6 +1473,12 @@ async function resolvedFromFactory(factory, hostContext) {
     // Notice actions (notices Task 3): a plain object of name → handler,
     // every name grammar-checked; a malformed entry quarantines.
     const noticeActions = validateNoticeActions(candidate.noticeActions);
+    // Published hooks (knowledge C7): validated HERE (before the slug
+    // exists — ownership and shadowing are registry concerns, never
+    // load-failures); the declarations attribute to the slug at
+    // collection. A malformed entry or a schema that fails to compile
+    // quarantines the extension.
+    const publishedHooks = validatePublishedHooks(candidate.publishedHooks);
     return {
         ...(candidate.perUserTools === undefined
             ? {}
@@ -1324,12 +1515,15 @@ async function resolvedFromFactory(factory, hostContext) {
         ...(candidate.interactionKinds === undefined
             ? {}
             : { interactionKinds: candidate.interactionKinds }),
+        ...(interactiveTools === undefined ? {} : { interactiveTools }),
         ...(candidate.ambientKinds === undefined
             ? {}
             : { ambientKinds: candidate.ambientKinds }),
         ...(workers === undefined ? {} : { workers }),
         ...(curationTargets === undefined ? {} : { curationTargets }),
         ...(noticeActions === undefined ? {} : { noticeActions }),
+        ...(publishedHooks === undefined ? {} : { publishedHooks }),
+        ...(decisionProviders === undefined ? {} : { decisionProviders }),
         ...(providers === undefined ? {} : { providers }),
         ...(loginProviders === undefined ? {} : { loginProviders }),
         ...(webuiBundles === undefined ? {} : { webuiBundles }),
@@ -1529,10 +1723,21 @@ export async function loadExtensions(specifiers, registry, options = {}) {
     // these into the ONE CurationRegistry (src/curation/targets.ts).
     const curationBindings = [];
     const noticeActionBindings = [];
+    // Published hooks (knowledge C7): flat declarations, in load order,
+    // slug-attributed with the built-in flag — boot folds them into the
+    // registry AFTER `loadExtensions` returns (ownership: configured before
+    // built-ins, first per name wins — the registry's own ordering rule).
+    const publishedHookDeclarations = [];
+    // Decision-provider declarations (warden Task 6), slug-attributed —
+    // boot folds them into the ONE DecisionRegistry.
+    const decisionProviderDeclarations = [];
     const userServiceBindings = [];
     // Jobs Task 3: declared jobs, attributed to the extension slug (the
     // `ext:<slug>:<name>` id's namespace).
     const jobBindings = [];
+    // Interactive tool names (ask-user Task 3): the flat union over loaded
+    // extensions (boot folds it into the one ReadonlySet on OpenedHarness).
+    const interactiveTools = [];
     // HTTP routes (W5 Task 2), attributed to the slug like the job bindings.
     const routeBindings = [];
     // Slash commands (W5 Task 3), attributed the same way.
@@ -1821,6 +2026,13 @@ export async function loadExtensions(specifiers, registry, options = {}) {
                     if (unregistered !== undefined) {
                         throw new Error(`extension "${slug}" declares curation target "${target.name}" listing tool "${unregistered}" it does not register`);
                     }
+                    // C5: the same check for readTools (never wrapped, never fed
+                    // to the wrap feed — only registered, so the served filter and
+                    // the review gate see a real tool).
+                    const unregisteredRead = (target.readTools ?? []).find((tool) => !registered.has(tool));
+                    if (unregisteredRead !== undefined) {
+                        throw new Error(`extension "${slug}" declares curation target "${target.name}" listing read tool "${unregisteredRead}" it does not register`);
+                    }
                     // A tool names ONE target (A8): two targets — across any
                     // extensions — listing the same tool leave `byTool`
                     // first-wins arbitrary and the shadowed target's undos
@@ -1936,6 +2148,26 @@ export async function loadExtensions(specifiers, registry, options = {}) {
                     actions: resolved.noticeActions,
                 });
             }
+            // Published hooks (knowledge C7): collected AFTER the install
+            // — a quarantined extension never reaches here, so every
+            // declaration in the list comes from a LOADED extension.
+            for (const hook of resolved.publishedHooks ?? []) {
+                publishedHookDeclarations.push({
+                    extension: slug,
+                    builtin: builtin === true,
+                    hook,
+                });
+            }
+            // Decision providers (warden Task 6): collected AFTER the install
+            // — a quarantined extension never reaches here, so every
+            // declaration comes from a LOADED extension. The slug (not the
+            // declared contribution id) is the attribution.
+            for (const contribution of resolved.decisionProviders ?? []) {
+                decisionProviderDeclarations.push({
+                    extension: slug,
+                    contribution,
+                });
+            }
             if (resolved.curationTargets !== undefined) {
                 curationBindings.push({
                     extension: slug,
@@ -1951,6 +2183,13 @@ export async function loadExtensions(specifiers, registry, options = {}) {
             if (resolved.jobs !== undefined) {
                 jobBindings.push({ extension: slug, jobs: resolved.jobs });
             }
+            // Interactive tools (ask-user Task 3): collected AFTER the
+            // install, slug-attributed — a quarantined extension never
+            // reaches here, so the union boot folds comes from LOADED
+            // extensions only.
+            if (resolved.interactiveTools !== undefined) {
+                interactiveTools.push(...resolved.interactiveTools);
+            }
             if (resolved.userServices !== undefined) {
                 userServiceBindings.push({
                     extension: slug,
@@ -2067,7 +2306,10 @@ export async function loadExtensions(specifiers, registry, options = {}) {
         workerBindings,
         curationBindings,
         noticeActionBindings,
+        publishedHookDeclarations,
+        decisionProviderDeclarations,
         jobBindings,
+        interactiveTools,
         routeBindings,
         commandBindings,
         notifierBindings,

package/dist/harness/packages.js

@@ -84,6 +84,13 @@ export const HOST_RUNTIME_MODULES = [
     "@earendil-works/pi-ai",
     "@earendil-works/pi-durable",
     "@earendil-works/chord",
+    // @sigrun/ext-codemode imports CodemodeSandbox at RUNTIME. Core does not
+    // depend on pi-codemode (it arrives transitively via pi-durable), so a
+    // packages-dir install of the extension could not resolve it — the
+    // extension quarantined with "Cannot find package
+    // '@earendil-works/pi-codemode'". Linked like the other Earendil host
+    // modules so the extension resolves the copy the host actually runs.
+    "@earendil-works/pi-codemode",
     "typebox",
     // The shared workspace is host-shipped too (wire + access contracts
     // every extension family type against; @sigrun/recall is the first

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) ?? [],
+            }));
+        },
+    };
+}