@sigrun/sigrun 0.1.6 → 0.2.0

package/dist/harness/loader.js

@@ -84,12 +84,13 @@
  */
 import { ICON_NAMES } from "@sigrun/shared/blocks";
 import { validateJobSpec } from "../jobs/spec.js";
+import { validateTree } from "../blocks/validate.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, readPackageAssetsDir, readPackageName, readPackageVersion, resolveExtensionEntry, } from "./packages.js";
-import { RESERVED_CORE_SECTION_KEYS } from "./reserved-sections.js";
+import { RESERVED_CORE_SECTION_KEYS, RESERVED_EXTENSION_SLUGS, } from "./reserved-sections.js";
 import { slugifyName } from "./stores.js";
 /** Every lifecycle field name, in validation order (mirrors the contract doc). */
 const LIFECYCLE_FIELDS = [
@@ -107,6 +108,8 @@ const LIFECYCLE_FIELDS = [
  * union, which a section's `string` key can never satisfy.
  */
 const RESERVED_SECTION_KEY_SET = new Set(RESERVED_CORE_SECTION_KEYS);
+/** Reserved store-root directory names may not become extension identities. */
+const RESERVED_EXTENSION_SLUG_SET = new Set(RESERVED_EXTENSION_SLUGS);
 /** A structural check for "looks like a pi-durable Extension". */
 function isExtension(value) {
     return (typeof value === "object" &&
@@ -213,6 +216,27 @@ function validateWorkers(value) {
  * (the §8.2 grammar), and duplicate names within one extension are
  * rejected (they would collide on the `ext:<slug>:<name>` id).
  */
+function validateUserServices(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error("extension factory returned a userServices field that is not an array");
+    const names = new Set();
+    for (const candidate of value) {
+        const service = candidate;
+        if (typeof service?.name !== "string" || service.name === "")
+            throw new Error("extension factory returned a user service without a name");
+        if (names.has(service.name))
+            throw new Error(`extension factory returned a duplicate user service name "${service.name}"`);
+        names.add(service.name);
+        if (typeof service.start !== "function")
+            throw new Error(`extension factory returned a user service "${service.name}" whose start is not a function`);
+        if (service.idleMinutes !== undefined && (typeof service.idleMinutes !== "number" || !Number.isFinite(service.idleMinutes) || service.idleMinutes <= 0)) {
+            throw new Error(`extension factory returned a user service "${service.name}" with an invalid idleMinutes`);
+        }
+    }
+    return value;
+}
 function validateJobs(value) {
     if (value === undefined)
         return undefined;
@@ -242,6 +266,117 @@ function validateJobs(value) {
 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;
+/**
+ * The `settings` placement's field-name walk (UI-blocks U4 Task 3):
+ * every field of a settings form must be a TOP-LEVEL key of the
+ * extension's settings object (spec §13.3 — the form binds to
+ * `settings/<slug>.json`; a dotted or nested name would write a shape
+ * the verbatim settings routes cannot show).
+ */
+function* walkFormFields(root) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (Array.isArray(node)) {
+            stack.push(...node);
+            continue;
+        }
+        if (typeof node !== "object" || node === null)
+            continue;
+        const record = node;
+        for (const key of ["children", "fields", "root", "main", "sidebar", "detail"]) {
+            if (record[key] !== undefined)
+                stack.push(record[key]);
+        }
+        if (record.block !== undefined)
+            stack.push(record.block);
+        if (record.item !== undefined)
+            stack.push(record.item);
+        if (typeof record.name === "string" && typeof record.type === "string") {
+            yield record;
+        }
+    }
+}
+/**
+ * Validate a factory result's `surfaces.settings` list (UI-blocks U4
+ * Task 3, spec §13.3). Each entry: non-empty string `id`, `title`,
+ * `icon` (optional, in the closed set), `form` a Tree validating
+ * against the `settings` placement with a root `form` block, every
+ * field name a TOP-LEVEL key (no dots), optional `secrets` entries
+ * `{key, label, help?}`, and `admin` a boolean when present. The
+ * `save` handler name is core-owned (the adapter's), so `onSubmit`
+ * names outside `{save, submit}` are rejected (an extension thinking
+ * it owns its save handler would silently never fire).
+ */
+function validateSettingsSections(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a surfaces.settings field that is not an array");
+    }
+    const defs = [];
+    const seen = new Set();
+    for (const entry of value) {
+        const def = entry;
+        if (typeof def?.id !== "string" || def.id.length === 0) {
+            throw new Error("extension factory returned a settings section whose id is missing or not a non-empty string");
+        }
+        if (seen.has(def.id)) {
+            throw new Error(`extension factory returned a duplicate settings section id "${def.id}"`);
+        }
+        seen.add(def.id);
+        if (typeof def?.title !== "string" || def.title.length === 0) {
+            throw new Error(`extension factory returned a settings section "${def.id}" whose title is missing or not a non-empty string`);
+        }
+        if (def?.icon !== undefined &&
+            (typeof def.icon !== "string" || !ICON_NAME_SET.has(def.icon))) {
+            throw new Error(`extension factory returned a settings section "${def.id}" with unknown icon "${String(def?.icon)}"`);
+        }
+        if (def?.admin !== undefined && typeof def.admin !== "boolean") {
+            throw new Error(`extension factory returned a settings section "${def.id}" whose admin is not a boolean`);
+        }
+        if (def?.scope !== undefined && def.scope !== "server" && def.scope !== "user") {
+            throw new Error(`extension factory returned a settings section "${def.id}" whose scope is not "server" or "user"`);
+        }
+        if (def?.secrets !== undefined) {
+            if (!Array.isArray(def.secrets)) {
+                throw new Error(`extension factory returned a settings section "${def.id}" whose secrets is not an array`);
+            }
+            for (const secret of def.secrets) {
+                const entry2 = secret;
+                if (typeof entry2?.key !== "string" || entry2.key.length === 0) {
+                    throw new Error(`extension factory returned a settings section "${def.id}" whose secrets entry is missing a key`);
+                }
+                if (typeof entry2?.label !== "string" || entry2.label.length === 0) {
+                    throw new Error(`extension factory returned a settings section "${def.id}" whose secrets entry "${String(entry2?.key)}" is missing a label`);
+                }
+                if (entry2?.help !== undefined && typeof entry2.help !== "string") {
+                    throw new Error(`extension factory returned a settings section "${def.id}" whose secrets entry "${entry2.key}" carries a non-string help`);
+                }
+            }
+        }
+        if (typeof def?.form !== "object" || def.form === null) {
+            throw new Error(`extension factory returned a settings section "${def.id}" whose form is missing or not a Tree`);
+        }
+        const validation = validateTree(def.form, {
+            placement: "settings",
+            handlers: new Set(["save", "submit"]),
+        });
+        if (!validation.ok) {
+            throw new Error(`extension factory returned a settings section "${def.id}" whose form is invalid: ` +
+                validation.errors.map((err) => `${err.path}: ${err.message}`).join("; "));
+        }
+        for (const field of walkFormFields(validation.tree.root)) {
+            if (typeof field.name !== "string" || field.name.length === 0)
+                continue;
+            if (field.name.includes(".") || field.name.includes("/")) {
+                throw new Error(`extension factory returned a settings section "${def.id}" whose field "${field.name}" is not a top-level settings key (no dots or slashes)`);
+            }
+        }
+        defs.push(entry);
+    }
+    return defs;
+}
 /**
  * Validate a factory result's `surfaces` declaration (UI-blocks U3
  * Task 1, spec §7.1/§15). Absent → undefined (no surfaces). Present
@@ -255,10 +390,10 @@ const MIN_REFRESH_MS = 5000;
  * 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.
+ * §7.1), `render` a function — plus the `settings` list (§13.3, U4
+ * Task 3), validated by `validateSettingsSections`. Returns the
+ * FLATTENED defs (views then panels, declaration order) and the
+ * settings sections, attributed to the slug at collection.
  */
 function validateSurfaces(value) {
     if (value === undefined)
@@ -266,16 +401,12 @@ function validateSurfaces(value) {
     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)");
-    }
+    // §13.3 settings sections (UI-blocks U4 Task 3): validated with the
+    // settings placement; a malformed list quarantines like every other
+    // malformed surfaces member.
+    const settings = validateSettingsSections(value.settings);
     const defs = [];
-    const seen = new Set();
+    const seen = new Set(settings?.map((def) => def.id) ?? []);
     for (const list of ["views", "panels"]) {
         const entries = value[list];
         if (entries === undefined)
@@ -340,7 +471,7 @@ function validateSurfaces(value) {
             defs.push(entry);
         }
     }
-    return defs;
+    return { defs, ...(settings === undefined ? {} : { settings }) };
 }
 const ROUTE_METHODS = new Set([
     "GET",
@@ -944,9 +1075,15 @@ async function resolvedFromFactory(factory, hostContext) {
     // and the `LoaderReadKeys` assertion (above ResolvedExtension) pins the
     // full read list to the contract's keys.
     const candidate = awaited;
+    if (candidate.perUserTools !== undefined &&
+        typeof candidate.perUserTools !== "boolean") {
+        throw new Error("extension factory returned a perUserTools field that is not a boolean");
+    }
     const providers = validateProviders(candidate.providers);
+    const loginProviders = validateLoginProviders(candidate.loginProviders);
     const webuiBundles = validateWebuiBundles(candidate.webuiBundles);
     const jobs = validateJobs(candidate.jobs);
+    const userServices = validateUserServices(candidate.userServices);
     const routes = validateRoutes(candidate.routes);
     const commands = validateCommands(candidate.commands);
     const skills = validateSkills(candidate.skills);
@@ -968,8 +1105,10 @@ async function resolvedFromFactory(factory, hostContext) {
         // collision-record identity — without one there is nothing to
         // attribute the contributions to, which is a contract violation.
         if (providers === undefined &&
+            loginProviders === undefined &&
             webuiBundles === undefined &&
-            channels === undefined) {
+            channels === undefined &&
+            userServices === undefined) {
             return undefined;
         }
         if (typeof candidate.name !== "string" || candidate.name.length === 0) {
@@ -1003,9 +1142,20 @@ async function resolvedFromFactory(factory, hostContext) {
         validateKinds(candidate.ambientKinds);
     if (kindsProblem !== null)
         throw new Error(kindsProblem);
+    // 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
+    // silently miss them.
+    const onSettingsChanged = candidate.onSettingsChanged;
+    if (onSettingsChanged !== undefined && typeof onSettingsChanged !== "function") {
+        throw new Error("extension factory returned an onSettingsChanged field that is not a function");
+    }
     // `workers` is a contract key — the candidate read needs no cast.
     const workers = validateWorkers(candidate.workers);
     return {
+        ...(candidate.perUserTools === undefined
+            ? {}
+            : { perUserTools: candidate.perUserTools }),
         // Identity: the extension when one was carried, else the
         // provider-only contributor's validated `name`.
         ...(extension !== undefined
@@ -1020,6 +1170,13 @@ async function resolvedFromFactory(factory, hostContext) {
         ...(candidate.runSettled === undefined
             ? {}
             : { runSettled: candidate.runSettled }),
+        ...(onSettingsChanged === undefined
+            ? {}
+            : {
+                // SAFETY: the typeof-function check above is the validation —
+                // the cast supplies the contract's parameter type only.
+                onSettingsChanged: onSettingsChanged,
+            }),
         ...(anyLifecycle
             ? {
                 // SAFETY: every value under `lifecycle` passed `typeof === "function"`
@@ -1036,17 +1193,54 @@ async function resolvedFromFactory(factory, hostContext) {
             : { ambientKinds: candidate.ambientKinds }),
         ...(workers === undefined ? {} : { workers }),
         ...(providers === undefined ? {} : { providers }),
+        ...(loginProviders === undefined ? {} : { loginProviders }),
         ...(webuiBundles === undefined ? {} : { webuiBundles }),
         ...(jobs === undefined ? {} : { jobs }),
+        ...(userServices === undefined ? {} : { userServices }),
         ...(routes === undefined ? {} : { routes }),
         ...(commands === undefined ? {} : { commands }),
         ...(skills === undefined ? {} : { skills }),
         ...(notifiers === undefined ? {} : { notifiers }),
         ...(channels === undefined ? {} : { channels }),
         ...(gateway === undefined ? {} : { gateway }),
-        ...(surfaces === undefined ? {} : { surfaces }),
+        ...(surfaces === undefined ? {} : { surfaces: surfaces.defs }),
+        ...(surfaces?.settings === undefined
+            ? {}
+            : { settingsSections: surfaces.settings }),
     };
 }
+/** Validate and retain login providers; all-or-nothing for one extension. */
+function validateLoginProviders(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a loginProviders field that is not an array");
+    }
+    const ids = new Set();
+    for (const candidate of value) {
+        if (typeof candidate !== "object" || candidate === null) {
+            throw new Error("extension factory returned a loginProviders entry that is not an object");
+        }
+        const entry = candidate;
+        if (typeof entry.id !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(entry.id)) {
+            throw new Error("extension factory returned a loginProviders entry with an invalid id");
+        }
+        if (ids.has(entry.id)) {
+            throw new Error(`extension factory returned duplicate login provider id "${entry.id}"`);
+        }
+        ids.add(entry.id);
+        if (typeof entry.label !== "string") {
+            throw new Error("extension factory returned a loginProviders entry whose label is not a string");
+        }
+        if (entry.icon !== undefined && typeof entry.icon !== "string") {
+            throw new Error("extension factory returned a loginProviders entry whose icon is not a string");
+        }
+        if (typeof entry.begin !== "function" || typeof entry.complete !== "function") {
+            throw new Error("extension factory returned a loginProviders entry whose begin/complete is not a function");
+        }
+    }
+    return value;
+}
 /**
  * Resolve one imported module to the extension the loader installs, per the
  * contract order documented on this module, retaining a factory-result §3
@@ -1184,12 +1378,15 @@ export async function loadExtensions(specifiers, registry, options = {}) {
         ? { name: undefined, entry: spec, skills: undefined, builtin: undefined, coreResolved: undefined, packageDir: undefined }
         : { name: spec.name, entry: spec.entry, skills: spec.skills, builtin: spec.builtin, coreResolved: spec.coreResolved, packageDir: spec.packageDir });
     const outcomes = [];
+    const perUserSlugs = [];
     const providerContributors = [];
     const webuiBundles = [];
     const healthProducers = [];
     const runSettledBindings = [];
+    const settingsChangedBindings = [];
     const lifecycleBindings = [];
     const workerBindings = [];
+    const userServiceBindings = [];
     // Jobs Task 3: declared jobs, attributed to the extension slug (the
     // `ext:<slug>:<name>` id's namespace).
     const jobBindings = [];
@@ -1205,6 +1402,8 @@ export async function loadExtensions(specifiers, registry, options = {}) {
     // them. Collected only for LOADED extensions (a colliding adapter never
     // reaches here — the channelIds check below throws first).
     const channelBindings = [];
+    // Login providers (multi-user M3b): flat, slug-qualified, in load order.
+    const loginProviders = [];
     // 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
@@ -1213,6 +1412,8 @@ export async function loadExtensions(specifiers, registry, options = {}) {
     let gatewayEngine;
     // Surfaces (U3 Task 1): the flattened validated defs, slug-attributed.
     const surfaceBindings = [];
+    // Settings sections (U4 Task 3, spec §13.3): validated, slug-attributed.
+    const settingsSectionBindings = [];
     // 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
@@ -1231,6 +1432,7 @@ export async function loadExtensions(specifiers, registry, options = {}) {
     const channelIds = new Map();
     for (const { name: label, entry, skills, builtin, coreResolved, packageDir } of entries) {
         const display = label ?? entry ?? "skills-only";
+        let quarantineSlug = slugifyName(label ?? entry ?? "");
         try {
             // Skills-only resolution (§9.4): the package declared skill dirs and
             // has NO loadable entry — nothing is imported. The outcome records
@@ -1343,10 +1545,26 @@ export async function loadExtensions(specifiers, registry, options = {}) {
                 throw new Error("factory result carried neither an extension nor a contributor name");
             }
             const slug = slugifyName(declared);
+            quarantineSlug = slug;
             if (slug === "") {
                 throw new Error(`extension name "${declared}" sanitizes to an empty slug ` +
                     "(nothing survives [a-z0-9_-] folding); refusing to load");
             }
+            // The `core` slug is RESERVED (UI-blocks U4 Task 3, spec §13.4):
+            // core's own settings sections serve under it, so an extension
+            // claiming the slug would shadow them (and every other
+            // core-served `/v1/ext/core/` surface).
+            if (slug === "core") {
+                throw new Error(`extension name "${declared}" sanitizes to the reserved slug "core" ` +
+                    "(core's own settings sections use it); refusing to load");
+            }
+            // Multi-user M1: core-owned store-root directories are not available
+            // as extension identities. Check after the slug is final, before
+            // any contribution is collected (the same load-time quarantine as
+            // the reserved section-key check below).
+            if (RESERVED_EXTENSION_SLUG_SET.has(slug)) {
+                throw new Error(`reserved extension slug "${slug}"`);
+            }
             const collides = slugs.get(slug);
             if (collides !== undefined) {
                 throw new Error(`slug collision: extension "${declared}" sanitizes to ` +
@@ -1430,6 +1648,8 @@ export async function loadExtensions(specifiers, registry, options = {}) {
             if (extension !== undefined) {
                 registry.install(extension);
             }
+            if (resolved.perUserTools === true)
+                perUserSlugs.push(slug);
             // Only a LOADED extension or contributor claims its slug — a
             // later stage's quarantine (never loaded) leaves the slug free
             // for the next boot's specifier list.
@@ -1478,6 +1698,13 @@ export async function loadExtensions(specifiers, registry, options = {}) {
                     runSettled: resolved.runSettled,
                 });
             }
+            if (extension !== undefined &&
+                resolved.onSettingsChanged !== undefined) {
+                settingsChangedBindings.push({
+                    extension,
+                    onSettingsChanged: resolved.onSettingsChanged,
+                });
+            }
             if (extension !== undefined && resolved.lifecycle !== undefined) {
                 lifecycleBindings.push({
                     extension,
@@ -1493,6 +1720,13 @@ export async function loadExtensions(specifiers, registry, options = {}) {
             if (resolved.jobs !== undefined) {
                 jobBindings.push({ extension: slug, jobs: resolved.jobs });
             }
+            if (resolved.userServices !== undefined) {
+                userServiceBindings.push({
+                    extension: slug,
+                    services: resolved.userServices,
+                    packageDir: realpathSync(packageDir ?? extensionModuleDir(loaded) ?? "."),
+                });
+            }
             if (resolved.routes !== undefined) {
                 routeBindings.push({ extension: slug, routes: resolved.routes });
             }
@@ -1520,6 +1754,20 @@ export async function loadExtensions(specifiers, registry, options = {}) {
                     ...(declaredAssets === undefined ? {} : { assetsDir: declaredAssets }),
                 });
             }
+            if (resolved.settingsSections !== undefined) {
+                settingsSectionBindings.push({
+                    extension: slug,
+                    defs: resolved.settingsSections,
+                });
+            }
+            if (resolved.loginProviders !== undefined) {
+                for (const contribution of resolved.loginProviders) {
+                    loginProviders.push({
+                        provider: `login:${slug}:${contribution.id}`,
+                        contribution,
+                    });
+                }
+            }
             if (resolved.providers !== undefined) {
                 providerContributors.push({
                     name: slug,
@@ -1556,6 +1804,7 @@ export async function loadExtensions(specifiers, registry, options = {}) {
             }
         }
         catch (cause) {
+            await options.onQuarantine?.(quarantineSlug);
             const message = cause instanceof Error ? cause.message : String(cause);
             console.warn(`extension quarantined: ${display} failed to load: ${message}`);
             outcomes.push({
@@ -1574,11 +1823,15 @@ export async function loadExtensions(specifiers, registry, options = {}) {
     warnToolNameCollisions(registry);
     return {
         outcomes,
+        userServices: userServiceBindings,
+        perUserSlugs,
         providerContributors,
+        loginProviders,
         webuiBundles,
         skillRoots,
         healthProducers,
         runSettledBindings,
+        settingsChangedBindings,
         lifecycleBindings,
         workerBindings,
         jobBindings,
@@ -1588,5 +1841,6 @@ export async function loadExtensions(specifiers, registry, options = {}) {
         channelBindings,
         gatewayEngine,
         surfaces: surfaceBindings,
+        settingsSections: settingsSectionBindings,
     };
 }

package/dist/harness/packages.js

@@ -121,7 +121,7 @@ export function hostModuleVersion(name) {
  * install resolves through its OWN root, which is this same dir).
  * `undefined` when no ancestor carries the manifest.
  */
-function selfPackageRoot() {
+export function selfPackageRoot() {
     let dir = dirname(fileURLToPath(import.meta.url));
     for (let hops = 0; hops < 10; hops++) {
         const manifest = join(dir, "package.json");

package/dist/harness/reserved-sections.js

@@ -22,3 +22,24 @@ export const RESERVED_CORE_SECTION_KEYS = [
     "tool-guidance",
     "execution-guidance",
 ];
+/**
+ * Core-owned directory names directly under a store root (multi-user M1).
+ * The loader refuses these as extension identities before collecting any
+ * contribution. This list also feeds grant validation, which deliberately
+ * treats the data-side entries as CORE data dirs, not foreign extension
+ * dirs — see src/sandbox/grants.ts.
+ */
+export const RESERVED_EXTENSION_SLUGS = [
+    "users",
+    "workspace",
+    "models",
+    "sandbox",
+    "settings",
+    "user-settings",
+    "user-secrets",
+    "skills",
+    "prompts",
+    "packages",
+    "git",
+    "core",
+];