@sigrun/sigrun 0.1.3 → 0.1.5

package/dist/harness/loader.js

@@ -82,12 +82,13 @@
  * factory-result key the loader reads is a key of `SigrunExtensionResult`.
  * The implementation and the contract cannot drift silently.
  */
+import { ICON_NAMES } from "@sigrun/shared/blocks";
 import { validateJobSpec } from "../jobs/spec.js";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { HOST_RUNTIME_MODULES, hostModuleVersion, readPackageName, readPackageVersion, resolveExtensionEntry, } from "./packages.js";
+import { HOST_RUNTIME_MODULES, hostModuleVersion, readPackageAssetsDir, readPackageName, readPackageVersion, resolveExtensionEntry, } from "./packages.js";
 import { RESERVED_CORE_SECTION_KEYS } from "./reserved-sections.js";
 import { slugifyName } from "./stores.js";
 /** Every lifecycle field name, in validation order (mirrors the contract doc). */
@@ -96,6 +97,7 @@ const LIFECYCLE_FIELDS = [
     "conversationForked",
     "conversationArchived",
     "conversationIdle",
+    "interactionSettled",
     "harnessShutdown",
     "userDeleted",
 ];
@@ -145,6 +147,7 @@ const WAKE_EVENTS = new Set([
     "conversationForked",
     "conversationArchived",
     "conversationIdle",
+    "interactionSettled",
 ]);
 /**
  * The `every` retirement message (ruling 12, jobs Task 3): jobs are the
@@ -232,10 +235,113 @@ function validateJobs(value) {
     return specs;
 }
 /**
- * The `method`/`auth` vocabularies of a `routes` declaration (spec
- * §9.2) — Sets because `includes` on a `const` tuple narrows to the
- * literal union, which an `unknown` field value can never satisfy.
+ * The icon-name membership probe (spec §10.2): the closed set from
+ * `@sigrun/shared/blocks` — a `Set` so `unknown`-typed field values can
+ * be tested without a cast.
  */
+const ICON_NAME_SET = new Set(ICON_NAMES);
+/** The refreshMs floor (spec §7.1): channels refetch no faster than 5 s. */
+const MIN_REFRESH_MS = 5000;
+/**
+ * Validate a factory result's `surfaces` declaration (UI-blocks U3
+ * Task 1, spec §7.1/§15). Absent → undefined (no surfaces). Present
+ * but malformed → throw with ONE message per problem; the loader
+ * quarantines the extension with the thrown message (fail-loud: an
+ * extension that THINKS it declared a surface must not silently lose
+ * it — the providers/health class). Per def: non-empty string `id`
+ * (unique across BOTH lists — one namespace), string `title`, `icon`
+ * in the closed set, `placement` exactly `view` (in `views`) or
+ * `panel` (in `panels`), `sharedData` a boolean, `actions` an object
+ * whose every handler is a function (message names the action),
+ * `refreshMs ≥ 5000` when present, `data()` a function when
+ * `refreshMs` is set (a data refetch would otherwise re-run `render`,
+ * §7.1), `render` a function, and NO `settings` key (reserved — the
+ * §13.3 sections are a separate workstream). Returns the
+ * FLATTENED defs (views then panels, declaration order) attributed to
+ * the slug at collection.
+ */
+function validateSurfaces(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("extension factory returned a surfaces field that is not an object");
+    }
+    // The settings sections key is RESERVED (spec §7.1 names it; §13.3
+    // owns it): this workstream cannot serve it, and a JS package
+    // declaring one must not lose it silently — quarantine loud, naming
+    // the workstream (TS consumers are already stopped by the contract's
+    // `readonly never[]`).
+    if (value.settings !== undefined) {
+        throw new Error("extension factory returned a surfaces.settings declaration — settings sections are a separate workstream (they land in U4)");
+    }
+    const defs = [];
+    const seen = new Set();
+    for (const list of ["views", "panels"]) {
+        const entries = value[list];
+        if (entries === undefined)
+            continue;
+        if (!Array.isArray(entries)) {
+            throw new Error(`extension factory returned a surfaces.${list} field that is not an array`);
+        }
+        const expected = list === "views" ? "view" : "panel";
+        for (const entry of entries) {
+            const def = entry;
+            if (typeof def?.id !== "string" || def.id.length === 0) {
+                throw new Error("extension factory returned a surface whose id is missing or not a non-empty string");
+            }
+            if (seen.has(def.id)) {
+                throw new Error(`extension factory returned a duplicate surface id "${def.id}"`);
+            }
+            seen.add(def.id);
+            if (typeof def?.title !== "string" || def.title.length === 0) {
+                throw new Error(`extension factory returned a surface "${def.id}" whose title is missing or not a non-empty string`);
+            }
+            if (typeof def?.icon !== "string" || !ICON_NAME_SET.has(def.icon)) {
+                throw new Error(`extension factory returned a surface "${def.id}" with unknown icon "${String(def?.icon)}"`);
+            }
+            if (def?.placement !== expected) {
+                throw new Error(`extension factory returned a surface "${def.id}" whose placement must be "${expected}" in surfaces.${list}`);
+            }
+            if (def?.instanceKey !== undefined && typeof def.instanceKey !== "function") {
+                throw new Error(`extension factory returned a surface "${def.id}" whose instanceKey is not a function`);
+            }
+            if (def?.sharedData !== undefined &&
+                typeof def.sharedData !== "boolean") {
+                throw new Error(`extension factory returned a surface "${def.id}" whose sharedData is not a boolean`);
+            }
+            if (def?.actions !== undefined) {
+                if (typeof def.actions !== "object" ||
+                    def.actions === null ||
+                    Array.isArray(def.actions)) {
+                    throw new Error(`extension factory returned a surface "${def.id}" whose actions is not an object`);
+                }
+                for (const [action, handler] of Object.entries(def.actions)) {
+                    if (typeof handler !== "function") {
+                        throw new Error(`extension factory returned a surface "${def.id}" whose action "${action}" handler is not a function`);
+                    }
+                }
+            }
+            if (typeof def?.render !== "function") {
+                throw new Error(`extension factory returned a surface "${def.id}" whose render is not a function`);
+            }
+            if (def?.data !== undefined && typeof def.data !== "function") {
+                throw new Error(`extension factory returned a surface "${def.id}" whose data is not a function`);
+            }
+            if (def?.refreshMs !== undefined) {
+                if (typeof def.refreshMs !== "number" ||
+                    !Number.isInteger(def.refreshMs) ||
+                    def.refreshMs < MIN_REFRESH_MS) {
+                    throw new Error(`extension factory returned a surface "${def.id}" declaring refreshMs ${String(def.refreshMs)} (minimum ${MIN_REFRESH_MS})`);
+                }
+                if (def?.data === undefined) {
+                    throw new Error(`extension factory returned a surface "${def.id}" declaring refreshMs without data()`);
+                }
+            }
+            defs.push(entry);
+        }
+    }
+    return defs;
+}
 const ROUTE_METHODS = new Set([
     "GET",
     "POST",
@@ -244,6 +350,13 @@ const ROUTE_METHODS = new Set([
     "DELETE",
 ]);
 const ROUTE_AUTHS = new Set(["user", "admin", "public"]);
+/**
+ * The route-path prefixes reserved for core under `/v1/ext/<slug>/`
+ * (spec §7.2): `surfaces/` and `assets/` are the extension-surface
+ * and asset mounts — an extension route there would shadow them, so
+ * declaring one quarantines at load, naming the route.
+ */
+const RESERVED_ROUTE_PREFIXES = ["surfaces/", "assets/"];
 /**
  * Validate a factory result's `routes` declaration (core hardening W5
  * Task 2, spec §9.2). Absent → undefined (no routes). Present but
@@ -251,9 +364,10 @@ const ROUTE_AUTHS = new Set(["user", "admin", "public"]);
  * thrown message (fail-loud: an extension that THINKS it mounted a
  * webhook must not silently lose it). Per entry: `method` in the five
  * verbs, `path` a non-empty RELATIVE string (no leading `/`, no `..` —
- * nothing may escape the `/v1/ext/<slug>/` mount), `auth` one of the
- * three values, `bodyLimit` a positive integer when present, and
- * `handler` a function.
+ * nothing may escape the `/v1/ext/<slug>/` mount, and never under a
+ * RESERVED core prefix — §7.2), `auth` one of the three values,
+ * `bodyLimit` a positive integer when present, and `handler` a
+ * function.
  */
 function validateRoutes(value) {
     if (value === undefined)
@@ -273,6 +387,13 @@ function validateRoutes(value) {
             route.path.includes("..")) {
             throw new Error(`extension factory returned a route whose path must be a non-empty relative string (no leading "/", no "..")`);
         }
+        // Reserved core prefixes (spec §7.2): surfaces/ and assets/ belong
+        // to core under this slug's mount — quarantine naming the route.
+        const path = route?.path;
+        if (typeof path === "string" &&
+            RESERVED_ROUTE_PREFIXES.some((prefix) => path.startsWith(prefix))) {
+            throw new Error(`extension factory returned a ${describe()} whose path starts with a reserved core prefix (surfaces/ and assets/ belong to core under /v1/ext/<slug>/)`);
+        }
         if (typeof route?.auth !== "string" || !ROUTE_AUTHS.has(route.auth)) {
             throw new Error(`extension factory returned a ${describe()} whose auth is not one of user, admin, public`);
         }
@@ -355,6 +476,156 @@ function validateNotifiers(value) {
     }
     return value;
 }
+/**
+ * The channel-id grammar (gateway C1, spec §7): `^[a-z][a-z0-9-]*$` —
+ * the same shape as every other extension-declared name (commands,
+ * workers, bundles), and the key the gateway engine's chat bindings are
+ * addressed by (why a collision quarantines instead of last-wins).
+ */
+const CHANNEL_ID = /^[a-z][a-z0-9-]*$/;
+/** The `chatTypes` vocabulary of a `capabilities` declaration (spec §7). */
+const CHANNEL_CHAT_TYPES = new Set([
+    "dm",
+    "group",
+    "thread",
+]);
+/** The `capabilities.format` vocabulary (spec §7). */
+const CHANNEL_FORMATS = new Set([
+    "plain",
+    "markdown",
+    "native",
+]);
+/**
+ * Validate a factory result's `channels` declaration (gateway C1, spec
+ * §7). Absent → undefined (no contributions). Present but malformed →
+ * throw; the loader quarantines the extension with the thrown message
+ * (fail-loud: an adapter that THINKS it declared a channel must not
+ * silently lose it — the providers/health class). Per entry: `id` matching
+ * the grammar, `label` a non-empty string, `capabilities` an object with
+ * `chatTypes` a non-empty array over the vocabulary, `maxMessageLength` a
+ * positive integer, `format` one of the three values, the optional
+ * `edit.minIntervalMs`/`typing.intervalMs`/`buttons.max` positive
+ * integers, `configured`/`start`/`send` functions, the optional members
+ * functions when present, and `format` REQUIRED when
+ * `capabilities.format` is `"native"` (native markup has no default
+ * renderer). Duplicate ids within one result reject — they would collide
+ * on the engine's channel-id key exactly like a cross-extension pair.
+ */
+function validateChannels(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a channels field that is not an array");
+    }
+    const seen = new Set();
+    for (const entry of value) {
+        const channel = entry;
+        const describe = () => `channel "${typeof channel?.id === "string" ? channel.id : String(channel?.id)}"`;
+        if (typeof channel?.id !== "string" ||
+            !CHANNEL_ID.test(channel.id)) {
+            throw new Error(`extension factory returned a ${describe()} whose id does not match ^[a-z][a-z0-9-]*$`);
+        }
+        if (seen.has(channel.id)) {
+            throw new Error(`extension factory returned a duplicate channel id "${channel.id}" within one result`);
+        }
+        seen.add(channel.id);
+        if (typeof channel?.label !== "string" || channel.label.length === 0) {
+            throw new Error(`extension factory returned a ${describe()} whose label is missing or empty`);
+        }
+        const capabilities = channel?.capabilities;
+        if (typeof capabilities !== "object" || capabilities === null) {
+            throw new Error(`extension factory returned a ${describe()} whose capabilities is missing or not an object`);
+        }
+        if (!Array.isArray(capabilities.chatTypes) ||
+            capabilities.chatTypes.length === 0 ||
+            capabilities.chatTypes.some((type) => typeof type !== "string" || !CHANNEL_CHAT_TYPES.has(type))) {
+            throw new Error(`extension factory returned a ${describe()} whose capabilities.chatTypes is not a non-empty array over dm, group, thread`);
+        }
+        if (typeof capabilities.maxMessageLength !== "number" ||
+            !Number.isInteger(capabilities.maxMessageLength) ||
+            capabilities.maxMessageLength <= 0) {
+            throw new Error(`extension factory returned a ${describe()} whose capabilities.maxMessageLength is not a positive integer`);
+        }
+        if (typeof capabilities.format !== "string" ||
+            !CHANNEL_FORMATS.has(capabilities.format)) {
+            throw new Error(`extension factory returned a ${describe()} whose capabilities.format is not one of plain, markdown, native`);
+        }
+        // The optional numeric members: positive integers when present.
+        if (capabilities.edit !== undefined &&
+            (typeof capabilities.edit?.minIntervalMs !== "number" ||
+                !Number.isInteger(capabilities.edit.minIntervalMs) ||
+                capabilities.edit.minIntervalMs <= 0)) {
+            throw new Error(`extension factory returned a ${describe()} whose capabilities.edit.minIntervalMs is not a positive integer`);
+        }
+        if (capabilities.buttons !== undefined &&
+            (typeof capabilities.buttons?.max !== "number" ||
+                !Number.isInteger(capabilities.buttons.max) ||
+                capabilities.buttons.max <= 0)) {
+            throw new Error(`extension factory returned a ${describe()} whose capabilities.buttons.max is not a positive integer`);
+        }
+        if (capabilities.typing !== undefined &&
+            (typeof capabilities.typing?.intervalMs !== "number" ||
+                !Number.isInteger(capabilities.typing.intervalMs) ||
+                capabilities.typing.intervalMs <= 0)) {
+            throw new Error(`extension factory returned a ${describe()} whose capabilities.typing.intervalMs is not a positive integer`);
+        }
+        if (typeof channel?.configured !== "function") {
+            throw new Error(`extension factory returned a ${describe()} whose configured is not a function`);
+        }
+        if (typeof channel?.start !== "function") {
+            throw new Error(`extension factory returned a ${describe()} whose start is not a function`);
+        }
+        if (typeof channel?.send !== "function") {
+            throw new Error(`extension factory returned a ${describe()} whose send is not a function`);
+        }
+        for (const field of [
+            "stop",
+            "edit",
+            "delete",
+            "typing",
+            "setCommands",
+            "format",
+            "classifyError",
+        ]) {
+            if (channel[field] !== undefined && typeof channel[field] !== "function") {
+                throw new Error(`extension factory returned a ${describe()} whose ${field} is not a function`);
+            }
+        }
+        if (capabilities.format === "native" && channel?.format === undefined) {
+            throw new Error(`extension factory returned a ${describe()} without a format function while its capabilities.format is "native"`);
+        }
+    }
+    return value;
+}
+/**
+ * Validate a factory result's `gateway` declaration (gateway C2, spec
+ * §8.0). Absent → undefined (no engine). Present but malformed → throw;
+ * the loader quarantines the extension with the thrown message
+ * (fail-loud: an extension that THINKS it declared the engine must not
+ * silently lose it — the providers/health class). An object whose
+ * `start`/`stopIntake`/`stop`/`health` are all functions is the shape; a
+ * result carrying BOTH `gateway` and the `health` field is a contract
+ * violation (an engine reports health through `gateway.health()` — the
+ * `health` field is the provider-contributor surface and would
+ * double-report), thrown with the documented message.
+ */
+function validateGateway(value, healthPresent) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null) {
+        throw new Error("extension factory returned a gateway field that is not an object");
+    }
+    const engine = value;
+    for (const field of ["start", "stopIntake", "stop", "health"]) {
+        if (typeof engine[field] !== "function") {
+            throw new Error(`extension factory returned a gateway whose ${field} is not a function`);
+        }
+    }
+    if (healthPresent) {
+        throw new Error("a gateway engine reports health through gateway.health(), not the health field");
+    }
+    return value;
+}
 /**
  * Validate a factory result's `skills` declaration (core hardening W5
  * Task 4, spec §9.4). Absent → undefined (no contributions). Present but
@@ -443,15 +714,20 @@ function validateWebuiBundles(value) {
     return value;
 }
 /**
- * The one host module whose version must match the host EXACTLY (spec
+ * The host modules whose version must match the host EXACTLY (spec
  * §6.4 R6): an extension's `Extension`/tool objects flow into the HOST's
  * pi-durable registry under structural typing — a different pi-durable
  * is the classic silent-breakage trap (identity never matches, hooks
- * never fire), so any difference at all quarantines. Every other host
- * module only shares the major (a minor/patch difference warns).
+ * never fire), so any difference at all quarantines. `@sigrun/sigrun`
+ * joins that tier for the same reason the spec makes it a peer dependency
+ * (§14.1): `@sigrun/sigrun/blocks` must emit the SERVER's block-set
+ * version, and a different sigrun can only ever emit a different one —
+ * any difference at all quarantines. Every other host module only shares
+ * the major (a minor/patch difference warns).
  */
 const EXACT_HOST_MODULES = new Set([
     "@earendil-works/pi-durable",
+    "@sigrun/sigrun",
 ]);
 /** The major segment of a semver-ish version string (`"1.2.0"` → `"1"`). */
 function majorSegment(version) {
@@ -675,17 +951,25 @@ async function resolvedFromFactory(factory, hostContext) {
     const commands = validateCommands(candidate.commands);
     const skills = validateSkills(candidate.skills);
     const notifiers = validateNotifiers(candidate.notifiers);
+    const channels = validateChannels(candidate.channels);
+    // The engine (gateway C2): validated against the health-field conflict
+    // rule too — a result carrying both quarantines with the documented
+    // message (an engine reports health through gateway.health()).
+    const gateway = validateGateway(candidate.gateway, candidate.health !== undefined);
+    const surfaces = validateSurfaces(candidate.surfaces);
     const extension = isExtension(candidate.extension)
         ? candidate.extension
         : undefined;
     if (extension === undefined) {
         // Contributor-only result: valid when ANY contribution field is
-        // present (`providers`, `webuiBundles`); otherwise this factory
-        // result is not the contract form (fall through to the next
+        // present (`providers`, `webuiBundles`, `channels`); otherwise this
+        // factory result is not the contract form (fall through to the next
         // resolution candidate). The contributor's name is its
         // collision-record identity — without one there is nothing to
         // attribute the contributions to, which is a contract violation.
-        if (providers === undefined && webuiBundles === undefined) {
+        if (providers === undefined &&
+            webuiBundles === undefined &&
+            channels === undefined) {
             return undefined;
         }
         if (typeof candidate.name !== "string" || candidate.name.length === 0) {
@@ -758,6 +1042,9 @@ async function resolvedFromFactory(factory, hostContext) {
         ...(commands === undefined ? {} : { commands }),
         ...(skills === undefined ? {} : { skills }),
         ...(notifiers === undefined ? {} : { notifiers }),
+        ...(channels === undefined ? {} : { channels }),
+        ...(gateway === undefined ? {} : { gateway }),
+        ...(surfaces === undefined ? {} : { surfaces }),
     };
 }
 /**
@@ -913,6 +1200,19 @@ export async function loadExtensions(specifiers, registry, options = {}) {
     // Notifier transports (W5 Task 6, spec §9.6), attributed the same way —
     // the server's notifications surface delivers to every collected entry.
     const notifierBindings = [];
+    // Channel adapters (gateway C1, spec §7), attributed the same way — the
+    // gateway engine's start context and the /v1/extensions inventory read
+    // them. Collected only for LOADED extensions (a colliding adapter never
+    // reaches here — the channelIds check below throws first).
+    const channelBindings = [];
+    // The gateway engine (gateway C2, spec §8.0): the ONE-engine rule — the
+    // first loaded declarer wins; a later result declaring `gateway`
+    // quarantines naming the first slug (an engine owns supervision over the
+    // whole channel set, so a shadowing engine would inherit another
+    // engine's bindings — the same never-last-wins reasoning as channel ids).
+    let gatewayEngine;
+    // Surfaces (U3 Task 1): the flattened validated defs, slug-attributed.
+    const surfaceBindings = [];
     // Skill roots (W5 Task 4, spec §9.4): every skill dir a loaded package
     // contributed — skills-only resolutions, entry-bearing packages' manifest
     // skills, and factory-result `skills` fields — in load order, attributed
@@ -922,6 +1222,13 @@ export async function loadExtensions(specifiers, registry, options = {}) {
     // Slug → declared name, for collision rejection at load (this boot's
     // loaded set only — quarantined extensions never claim a slug).
     const slugs = new Map();
+    // Channel id → slug (gateway C1): the same claimed-only-by-LOADED pattern
+    // as `slugs`. Chat bindings are keyed by channel id, so a shadowing
+    // adapter would inherit another adapter's chats — the collision
+    // quarantines the later loader instead of last-wins (deliberately unlike
+    // commands and bundles). Checked BEFORE `registry.install` so a colliding
+    // extension leaves no registry entry, no slug claim, and no binding.
+    const channelIds = new Map();
     for (const { name: label, entry, skills, builtin, coreResolved, packageDir } of entries) {
         const display = label ?? entry ?? "skills-only";
         try {
@@ -1101,6 +1408,25 @@ export async function loadExtensions(specifiers, registry, options = {}) {
                 };
                 options.hostContextFactory(slug, kinds, host);
             }
+            if (resolved.channels !== undefined) {
+                for (const channel of resolved.channels) {
+                    const owner = channelIds.get(channel.id);
+                    if (owner !== undefined) {
+                        throw new Error(`channel "${channel.id}" is already contributed by "${owner}" — ` +
+                            "channel ids must be unique across extensions (chat bindings are keyed by id)");
+                    }
+                }
+            }
+            // The one-engine rule (gateway C2): checked BEFORE the registry
+            // install, exactly like the channel-id collision — a second engine
+            // leaves no registry entry, no slug claim, and no binding. First
+            // loaded wins.
+            if (resolved.gateway !== undefined) {
+                if (gatewayEngine !== undefined) {
+                    throw new Error(`gateway engine already declared by "${gatewayEngine.extension}"`);
+                }
+                gatewayEngine = { extension: slug, engine: resolved.gateway };
+            }
             if (extension !== undefined) {
                 registry.install(extension);
             }
@@ -1108,6 +1434,12 @@ export async function loadExtensions(specifiers, registry, options = {}) {
             // later stage's quarantine (never loaded) leaves the slug free
             // for the next boot's specifier list.
             slugs.set(slug, declared);
+            // ...and its channel ids (the same claimed-only-by-loaded rule).
+            if (resolved.channels !== undefined) {
+                for (const channel of resolved.channels) {
+                    channelIds.set(channel.id, slug);
+                }
+            }
             // The manifest version for the §7.7 inventory: read off the
             // module's own directory (a bare entry with no manifest stays
             // versionless — the field is optional by design).
@@ -1118,6 +1450,9 @@ export async function loadExtensions(specifiers, registry, options = {}) {
                 status: "ok",
                 ...(version === undefined ? {} : { version }),
                 ...(builtin === true ? { builtin: true } : {}),
+                ...(resolved.channels === undefined
+                    ? {}
+                    : { channels: resolved.channels.map((channel) => channel.id) }),
             });
             if (extension !== undefined && resolved.health !== undefined) {
                 healthProducers.push({
@@ -1167,6 +1502,24 @@ export async function loadExtensions(specifiers, registry, options = {}) {
             if (resolved.notifiers !== undefined) {
                 notifierBindings.push({ extension: slug, notifiers: resolved.notifiers });
             }
+            if (resolved.channels !== undefined) {
+                channelBindings.push({ extension: slug, channels: resolved.channels });
+            }
+            if (resolved.surfaces !== undefined) {
+                // The §11.1 assets dir: the package manifest's `sigrun.assets`
+                // relative to the package root (the same anchor the version
+                // read below uses); absent or undeclared → `undefined` and
+                // every asset request 404s.
+                const assetsRoot = packageDir ?? extensionModuleDir(loaded);
+                const declaredAssets = assetsRoot === undefined
+                    ? undefined
+                    : readPackageAssetsDir(assetsRoot);
+                surfaceBindings.push({
+                    extension: slug,
+                    defs: resolved.surfaces,
+                    ...(declaredAssets === undefined ? {} : { assetsDir: declaredAssets }),
+                });
+            }
             if (resolved.providers !== undefined) {
                 providerContributors.push({
                     name: slug,
@@ -1232,5 +1585,8 @@ export async function loadExtensions(specifiers, registry, options = {}) {
         routeBindings,
         commandBindings,
         notifierBindings,
+        channelBindings,
+        gatewayEngine,
+        surfaces: surfaceBindings,
     };
 }

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