@fungi.computer/truffle 0.1.1 → 0.2.0

package/dist/internal/private-workerd-sandbox-worker.mjs

@@ -21554,19 +21554,9 @@ function parseCatalog(input) {
     }
   }
   const preparedOperations = operations.map((operation) => prepareOperation(operation));
-  const namespaces = /* @__PURE__ */ new Map();
   for (const operation of preparedOperations) {
-    const namespace = operation.path.slice(0, operation.path.lastIndexOf("."));
-    const group = namespaces.get(namespace) ?? [];
-    group.push(operation);
-    namespaces.set(namespace, group);
-  }
-  for (const [namespace, group] of namespaces) {
-    const rendered = group.map((operation) => operation.rendered);
-    const index = renderNamespaceIndex(rendered);
-    const full = renderOperationTypes(rendered);
-    if (index.length > maximumDescriptionTypes || full.length > maximumDescriptionTypes) {
-      throw new ForageError("invalid_input", `Namespace description exceeds the bounded output: ${namespace}`);
+    if (renderOperationTypes([operation.rendered]).length > maximumDescriptionTypes) {
+      throw new ForageError("invalid_input", `Operation description exceeds the bounded output: ${operation.path}`);
     }
   }
   return {
@@ -27027,6 +27017,10 @@ var GuestThrew = class extends TaggedError2("GuestThrew") {
 };
 var DeadlineExceeded = class extends TaggedError2("DeadlineExceeded") {
 };
+var SandboxBusy = class extends TaggedError2("SandboxBusy") {
+  /** Stable contention code, not a sandbox health failure. */
+  code = "sandbox-busy";
+};
 var Cancelled = class extends TaggedError2("Cancelled") {
 };
 var DispatchLost = class extends TaggedError2("DispatchLost") {
@@ -27064,6 +27058,9 @@ function sandboxFailureMessage(failure, includeReference = true) {
     case "DeadlineExceeded":
       text = `execute hit its ${String(failure.limitMs)} ms deadline after ${String(failure.elapsedMs)} ms; split the work or persist progress${failure.acknowledged === false ? "; sandbox did not acknowledge cancellation" : ""}`;
       break;
+    case "SandboxBusy":
+      text = `sandbox-busy: all ${String(failure.capacity)} sandbox slots remained occupied after waiting ${String(failure.waitedMs)} ms. Nothing ran; retry this call after capacity becomes available.`;
+      break;
     case "Cancelled":
       text = failure.acknowledged === false ? "Sandbox did not acknowledge cancellation" : "Execution was cancelled";
       break;
@@ -27096,6 +27093,7 @@ var ownedFailureSchema = external_exports.lazy(() => external_exports.union([
   external_exports.instanceof(SourceInvalid),
   external_exports.instanceof(GuestThrew),
   external_exports.instanceof(DeadlineExceeded),
+  external_exports.instanceof(SandboxBusy),
   external_exports.instanceof(Cancelled),
   external_exports.instanceof(DispatchLost),
   external_exports.instanceof(SandboxCrashed),
@@ -27207,6 +27205,7 @@ var transportEnvelopeSchema = external_exports.lazy(() => external_exports.stric
     "SourceInvalid",
     "GuestThrew",
     "DeadlineExceeded",
+    "SandboxBusy",
     "Cancelled",
     "DispatchLost",
     "SandboxCrashed",

package/dist/internal/sandbox-metafile.json

@@ -2066,7 +2066,7 @@
       "format": "esm"
     },
     "../../packages/forage/dist/catalog.js": {
-      "bytes": 5055,
+      "bytes": 4793,
       "imports": [
         {
           "path": "../../packages/forage/dist/errors.js",
@@ -6156,7 +6156,7 @@
       "format": "esm"
     },
     "../../packages/mycelium/dist/sandbox-failure.js": {
-      "bytes": 6983,
+      "bytes": 7648,
       "imports": [
         {
           "path": "../../node_modules/.pnpm/effect@4.0.2/node_modules/effect/dist/Data.js",
@@ -6167,7 +6167,7 @@
       "format": "esm"
     },
     "../../packages/mycelium/dist/sandbox-boundary.js": {
-      "bytes": 13321,
+      "bytes": 13388,
       "imports": [
         {
           "path": "../../packages/cairn/dist/index.js",
@@ -6558,7 +6558,7 @@
           "bytesInOutput": 1793
         },
         "../../packages/forage/dist/catalog.js": {
-          "bytesInOutput": 4139
+          "bytesInOutput": 3677
         },
         "../../packages/forage/dist/app-api.js": {
           "bytesInOutput": 1649
@@ -6708,10 +6708,10 @@
           "bytesInOutput": 9993
         },
         "../../packages/mycelium/dist/sandbox-failure.js": {
-          "bytesInOutput": 3277
+          "bytesInOutput": 3670
         },
         "../../packages/mycelium/dist/sandbox-boundary.js": {
-          "bytesInOutput": 6369
+          "bytesInOutput": 6432
         },
         "../../packages/mycelium/dist/sandbox-guest.js": {
           "bytesInOutput": 4954
@@ -6720,7 +6720,7 @@
           "bytesInOutput": 4648
         }
       },
-      "bytes": 993382
+      "bytes": 993376
     }
   }
 }

package/dist/local-archive-handoff.d.ts

@@ -0,0 +1,12 @@
+import type { ExtensionGrantV0, RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
+/** What the Local roster gains for the compaction archive. */
+export type LocalArchiveHandoff = Readonly<{
+    roster: readonly RosteredExtensionV0[];
+    grants: readonly ExtensionGrantV0[];
+}>;
+/**
+ * Zookeeper's compaction handoff over files beside the Agent store. An
+ * installed extension the owner chose keeps the single `compaction_handoff`
+ * slot: Zookeeper is then skipped and the skip is reported, never a failure.
+ */
+export declare function localArchiveHandoff(storeDirectory: string, installedGrants: readonly ExtensionGrantV0[], report?: (operation: string, cause: unknown) => void): LocalArchiveHandoff;

package/dist/local-archive-handoff.js

@@ -0,0 +1,21 @@
+import { zookeeperCompaction, zookeeperCompactionGrant, } from "@fungi.computer/zookeeper";
+import { logEvent } from "./log-event.js";
+import { localArchiveWriter } from "./local-session-archives.js";
+/**
+ * Zookeeper's compaction handoff over files beside the Agent store. An
+ * installed extension the owner chose keeps the single `compaction_handoff`
+ * slot: Zookeeper is then skipped and the skip is reported, never a failure.
+ */
+export function localArchiveHandoff(storeDirectory, installedGrants, report = logEvent) {
+    const holder = installedGrants.find(({ capabilities }) => capabilities.includes("compaction_handoff"));
+    if (holder !== undefined) {
+        report("local-zookeeper-skipped", new Error(`Installed extension ${holder.id} holds the compaction handoff; Zookeeper archives are off for this Agent`));
+        return { roster: [], grants: [] };
+    }
+    return {
+        roster: [
+            zookeeperCompaction({ writer: localArchiveWriter(storeDirectory) }),
+        ],
+        grants: [zookeeperCompactionGrant],
+    };
+}

package/dist/local-extensions.d.ts

@@ -1,7 +1,8 @@
 import { Mycelium } from "@fungi.computer/mycelium";
 import { defineExtension, type ExtensionCapabilityV0, type ExtensionGrantV0, type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
 import { z } from "zod";
-export type LocalExtensionFailureReason = "install" | "manifest" | "artifact" | "not-installed" | "not-enabled" | "no-tools" | "load";
+import { type ExtensionSkillFolder } from "./local-skill-source.js";
+export type LocalExtensionFailureReason = "install" | "manifest" | "artifact" | "not-installed" | "not-enabled" | "no-tools" | "no-skills" | "not-held" | "load";
 /** A typed refusal from the extension owner; never reported as usable. */
 export declare class LocalExtensionError extends Error {
     readonly name = "LocalExtensionError";
@@ -21,6 +22,10 @@ export type LocalExtensionHostV1 = Readonly<{
 }>;
 /** What an installed package's `./host` entry exports by default. */
 export type LocalExtensionFactoryV1 = (host: LocalExtensionHostV1) => RosteredExtensionV0 | Promise<RosteredExtensionV0>;
+/** What `add` reports: the summary plus the names of the skills it ships. */
+export type LocalInstalledExtension = LocalExtensionSummary & Readonly<{
+    skills: readonly string[];
+}>;
 export type LocalExtensionSummary = Readonly<{
     id: string;
     revision: string;
@@ -50,6 +55,8 @@ export type LocalProjectExtensions = Readonly<{
 export type LocalAgentExtensions = Readonly<{
     roster: readonly RosteredExtensionV0[];
     grants: readonly ExtensionGrantV0[];
+    /** Skills folders of extensions this Agent opted into, read in place. */
+    skills: readonly ExtensionSkillFolder[];
     /** Extensions left out of this Agent's roster, and why. */
     diagnostics: readonly Readonly<{
         extensionId: string;
@@ -57,11 +64,11 @@ export type LocalAgentExtensions = Readonly<{
     }>[];
 }>;
 export type LocalExtensionsOptions = Readonly<{
-    /** The user home that owns `.fungi/extensions`; defaults to the OS home. */
-    home?: string | undefined;
+    /** The selected user home that owns `.fungi/extensions`. */
+    home: string;
 }>;
 /** Open the one extension owner for a user home. */
-export declare function localExtensions(options?: LocalExtensionsOptions): {
+export declare function localExtensions(options: LocalExtensionsOptions): {
     root: string;
     /**
      * Install a package with the shipped Bun package manager (lifecycle
@@ -69,29 +76,68 @@ export declare function localExtensions(options?: LocalExtensionsOptions): {
      * is pinned to the commit Bun's lockfile resolved; updating is another
      * explicit `add`. Missing declared artifacts are a refusal.
      */
-    add(source: string): Promise<LocalExtensionSummary>;
+    add(source: string): Promise<LocalInstalledExtension>;
     /** Remove the package and every activation that references it. */
     remove(id: string): Promise<boolean>;
     list(): Promise<readonly LocalExtensionSummary[]>;
     /** Enable the current revision's client part and programs for a project. */
     enableProject(projectRoot: string, id: string): Promise<string>;
     disableProject(projectRoot: string, id: string): Promise<boolean>;
+    /**
+     * The one check that an Agent holds an extension: refuses with
+     * `not-held`, naming every id it lacks. Callers needing a whole request
+     * judged before any effect call this first; `enableAgent` applies it too.
+     */
+    assertHeldByAgent(agentStoreDirectory: string, ids: readonly string[]): Promise<void>;
     /**
      * Grant one Agent store the current revision's declared capabilities.
      * Running work keeps its captured roster; the Agent applies this when it
-     * next opens.
+     * next opens. A human (the CLI) names no requester. When an Agent asks, it
+     * must hold the extension itself.
      */
-    enableAgent(storeDirectory: string, id: string): Promise<{
+    enableAgent(storeDirectory: string, id: string, requester?: Readonly<{
+        agentStoreDirectory: string;
+    }>): Promise<{
         revision: string;
         capabilities: ("state" | "attention" | "settled" | "send" | "timers" | "commands" | "projection" | "run_tools" | "files" | "prompt" | "compaction_handoff")[];
+        skills: boolean;
     }>;
+    /**
+     * Opt one Agent store into the skills the extension ships, without
+     * granting any tools. An existing activation keeps its revision and its
+     * capabilities; a new one carries none.
+     */
+    enableAgentSkills(storeDirectory: string, id: string): Promise<string>;
+    /**
+     * Turn only the skills off. Tools stay granted; an activation left with
+     * neither is removed.
+     */
+    disableAgentSkills(storeDirectory: string, id: string): Promise<boolean>;
     disableAgent(storeDirectory: string, id: string): Promise<boolean>;
     /** The project's enabled client entries and program launchers. */
     project(projectRoot: string): Promise<LocalProjectExtensions>;
-    /**
-     * Load the Agent's enabled server extensions through their host factory.
-     * Each failure is isolated to its extension and reported.
-     */
-    agent(storeDirectory: string, projectRoot: string): Promise<LocalAgentExtensions>;
+    /** Capture validated records so one reload cannot mix file generations. */
+    captureAgent(): Promise<(storeDirectory: string, projectRoot: string) => Promise<Readonly<{
+        roster: readonly RosteredExtensionV0[];
+        grants: readonly ExtensionGrantV0[];
+        /** Skills folders of extensions this Agent opted into, read in place. */
+        skills: readonly ExtensionSkillFolder[];
+        /** Extensions left out of this Agent's roster, and why. */
+        diagnostics: readonly Readonly<{
+            extensionId: string;
+            error: Error;
+        }>[];
+    }>>>;
+    agent(storeDirectory: string, projectRoot: string): Promise<Readonly<{
+        roster: readonly RosteredExtensionV0[];
+        grants: readonly ExtensionGrantV0[];
+        /** Skills folders of extensions this Agent opted into, read in place. */
+        skills: readonly ExtensionSkillFolder[];
+        /** Extensions left out of this Agent's roster, and why. */
+        diagnostics: readonly Readonly<{
+            extensionId: string;
+            error: Error;
+        }>[];
+    }>>;
 };
 export type LocalExtensions = ReturnType<typeof localExtensions>;

package/dist/local-extensions.js

@@ -1,6 +1,5 @@
 import { createHash } from "node:crypto";
-import { access, constants, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
-import { homedir } from "node:os";
+import { access, constants, mkdir, mkdtemp, readFile, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Mycelium } from "@fungi.computer/mycelium";
@@ -10,12 +9,19 @@ import * as Schema from "effect/Schema";
 import lockfile from "proper-lockfile";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
+import { describeExtensionSkills, } from "./local-skill-source.js";
 /**
  * Installed Local extensions. One owner holds the package bytes under
  * `~/.fungi/extensions`, and the activations its typed operations write. A
  * project's client part and program launchers, and an Agent's tools, are
  * separate activations keyed by canonical path. Nothing under a project or
  * Agent store authorizes anything: a copied folder starts disabled.
+ *
+ * A package may also ship a `skills` folder. Its skills are read in place
+ * from the installed package (nothing is copied or symlinked) and only while
+ * the Agent's activation opts in, so disabling or removing the extension ends
+ * them. This covers Local installed extensions only; Hub-hosted extensions
+ * are not covered.
  */
 const capabilities = [
     "state",
@@ -36,6 +42,8 @@ const revisionPattern = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/u;
 const manifestSchema = z.strictObject({
     id: z.string().transform((value) => decodeExtensionId(value)),
     capabilities: z.array(z.enum(capabilities)).max(10).default([]),
+    /** Package-relative folder of skills, offered to an Agent that opts in. */
+    skills: z.string().startsWith("./").max(1_024).optional(),
     terminals: z
         .array(z.strictObject({
         id: identifier.max(64),
@@ -77,6 +85,7 @@ const revisionRecord = z.strictObject({
     terminals: z.array(terminalRecord),
     host: z.string().nullable(),
     client: z.string().nullable(),
+    skills: z.string().nullable(),
 });
 const installedSchema = z.strictObject({
     extensions: z.record(z.string(), z.strictObject({
@@ -89,6 +98,8 @@ const activationsSchema = z.strictObject({
     agents: z.record(z.string(), z.record(z.string(), z.strictObject({
         revision: z.string(),
         capabilities: z.array(z.enum(capabilities)),
+        /** The opt-in to the revision's skills folder; separate from tools. */
+        skills: z.boolean(),
     }))),
 });
 const lockSchema = z.looseObject({
@@ -112,6 +123,24 @@ export class LocalExtensionError extends Error {
         this.reason = reason;
     }
 }
+/**
+ * An Agent holds an extension when its store has granted tools, covering every
+ * capability of the current revision. Opting into only the extension's skills
+ * is not holding it: skills carry no authority to hand its tools on.
+ */
+function assertAgentHolds(held, installed, ids) {
+    const missing = ids.filter((id) => {
+        const activation = held?.[id];
+        if (activation === undefined || activation.capabilities.length === 0)
+            return true;
+        const entry = installed.extensions[id];
+        const needed = (entry === undefined ? undefined : entry.revisions[entry.current])
+            ?.capabilities ?? [];
+        return !needed.every((capability) => activation.capabilities.includes(capability));
+    });
+    if (missing.length > 0)
+        throw new LocalExtensionError("not-held", `An Agent cannot give ${missing.join(", ")} to another Agent: it does not hold ${missing.length === 1 ? "it" : "them"} itself`);
+}
 function failure(cause) {
     return cause instanceof Error ? cause : new Error(String(cause));
 }
@@ -121,11 +150,11 @@ function absent(cause) {
         (cause.code === "ENOENT" || cause.code === "ENOTDIR"));
 }
 /** Open the one extension owner for a user home. */
-export function localExtensions(options = {}) {
-    const root = join(resolve(options.home ?? homedir()), ".fungi", "extensions");
+export function localExtensions(options) {
+    const root = join(resolve(options.home), ".fungi", "extensions");
     const installedPath = join(root, "installed.json");
     const activationsPath = join(root, "activations.json");
-    async function readJson(path, schema, empty) {
+    async function readJson(path, schema, empty, remedy) {
         let text;
         try {
             text = await readFile(path, "utf8");
@@ -135,10 +164,13 @@ export function localExtensions(options = {}) {
                 return empty;
             throw cause;
         }
-        return schema.parse(JSON.parse(text));
+        const parsed = schema.safeParse(JSON.parse(text));
+        if (!parsed.success)
+            throw new LocalExtensionError("install", `${path} is from an earlier extension format; ${remedy}`, { cause: parsed.error });
+        return parsed.data;
     }
-    const readInstalled = () => readJson(installedPath, installedSchema, { extensions: {} });
-    const readActivations = () => readJson(activationsPath, activationsSchema, { projects: {}, agents: {} });
+    const readInstalled = () => readJson(installedPath, installedSchema, { extensions: {} }, "delete it and run `fungi extension add` again");
+    const readActivations = () => readJson(activationsPath, activationsSchema, { projects: {}, agents: {} }, "delete it, then re-enable your extensions");
     /** Serialize owner writes across CLI and service processes. */
     async function update(change) {
         await mkdir(root, { recursive: true, mode: 0o700 });
@@ -195,6 +227,27 @@ export function localExtensions(options = {}) {
         }
         return path;
     }
+    /** A declared skills folder must be a directory inside the package. */
+    async function declaredSkills(directory, declared) {
+        if (declared === undefined)
+            return null;
+        const path = resolve(directory, declared);
+        if (!path.startsWith(`${directory}${sep}`))
+            throw new LocalExtensionError("manifest", "skills must point inside its package");
+        try {
+            const real = await realpath(path);
+            if (!real.startsWith(`${await realpath(directory)}${sep}`))
+                throw new LocalExtensionError("manifest", "skills must point inside its package");
+            if (!(await stat(real)).isDirectory())
+                throw new LocalExtensionError("artifact", `The package declares skills but ${declared} is not a directory`);
+        }
+        catch (cause) {
+            if (cause instanceof LocalExtensionError)
+                throw cause;
+            throw new LocalExtensionError("artifact", `The package declares skills but ${declared} is not in the installed package`, { cause });
+        }
+        return path;
+    }
     return {
         root,
         /**
@@ -246,6 +299,12 @@ export function localExtensions(options = {}) {
                 const manifest = selected.pkg.fungi;
                 const host = await declaredEntry(selected.directory, selected.pkg.exports, "./host");
                 const client = await declaredEntry(selected.directory, selected.pkg.exports, "./client");
+                const skills = await declaredSkills(selected.directory, manifest.skills);
+                const skillNames = skills === null
+                    ? []
+                    : (await describeExtensionSkills({ extensionId: manifest.id, directory: skills }, AbortSignal.timeout(10_000))).skills.map((skill) => skill.name);
+                if (skills !== null && skillNames.length === 0)
+                    throw new LocalExtensionError("artifact", `${manifest.id} declares skills but ${manifest.skills ?? ""} contains none`);
                 if (manifest.capabilities.length > 0 && host === null)
                     throw new LocalExtensionError("artifact", `${manifest.id} declares Agent capabilities but its package exports no ./host entry`);
                 for (const terminal of manifest.terminals) {
@@ -282,6 +341,9 @@ export function localExtensions(options = {}) {
                     client: client === null
                         ? null
                         : join(target, client.slice(staging.length + sep.length)),
+                    skills: skills === null
+                        ? null
+                        : join(target, skills.slice(staging.length + sep.length)),
                 };
                 await update((installed) => {
                     const existing = installed.extensions[manifest.id];
@@ -301,6 +363,7 @@ export function localExtensions(options = {}) {
                     commit,
                     capabilities: record.capabilities,
                     terminals: record.terminals.map((terminal) => terminal.id),
+                    skills: skillNames,
                 };
             }
             finally {
@@ -365,22 +428,86 @@ export function localExtensions(options = {}) {
                 return true;
             });
         },
+        /**
+         * The one check that an Agent holds an extension: refuses with
+         * `not-held`, naming every id it lacks. Callers needing a whole request
+         * judged before any effect call this first; `enableAgent` applies it too.
+         */
+        async assertHeldByAgent(agentStoreDirectory, ids) {
+            const store = await realpath(agentStoreDirectory);
+            const [installed, activations] = await Promise.all([
+                readInstalled(),
+                readActivations(),
+            ]);
+            assertAgentHolds(activations.agents[store], installed, ids);
+        },
         /**
          * Grant one Agent store the current revision's declared capabilities.
          * Running work keeps its captured roster; the Agent applies this when it
-         * next opens.
+         * next opens. A human (the CLI) names no requester. When an Agent asks, it
+         * must hold the extension itself.
          */
-        async enableAgent(storeDirectory, id) {
+        async enableAgent(storeDirectory, id, requester) {
             const store = await realpath(storeDirectory);
+            const requesterStore = requester === undefined
+                ? undefined
+                : await realpath(requester.agentStoreDirectory);
             return update((installed, activations) => {
+                if (requesterStore !== undefined)
+                    assertAgentHolds(activations.agents[requesterStore], installed, [id]);
                 const { revision, record } = currentRevision(installed, id);
                 if (record.host === null || record.capabilities.length === 0)
                     throw new LocalExtensionError("no-tools", `Extension ${id} declares no Agent capabilities`);
+                const skills = activations.agents[store]?.[id]?.skills === true &&
+                    record.skills !== null;
+                activations.agents[store] = {
+                    ...activations.agents[store],
+                    [id]: { revision, capabilities: record.capabilities, skills },
+                };
+                return { revision, capabilities: record.capabilities, skills };
+            });
+        },
+        /**
+         * Opt one Agent store into the skills the extension ships, without
+         * granting any tools. An existing activation keeps its revision and its
+         * capabilities; a new one carries none.
+         */
+        async enableAgentSkills(storeDirectory, id) {
+            const store = await realpath(storeDirectory);
+            return update((installed, activations) => {
+                const current = currentRevision(installed, id);
+                const prior = activations.agents[store]?.[id];
+                const revision = prior?.revision ?? current.revision;
+                const record = installed.extensions[id]?.revisions[revision];
+                if (!record?.skills)
+                    throw new LocalExtensionError("no-skills", `Extension ${id}@${revision} ships no skills`);
                 activations.agents[store] = {
                     ...activations.agents[store],
-                    [id]: { revision, capabilities: record.capabilities },
+                    [id]: {
+                        revision,
+                        capabilities: prior?.capabilities ?? [],
+                        skills: true,
+                    },
                 };
-                return { revision, capabilities: record.capabilities };
+                return revision;
+            });
+        },
+        /**
+         * Turn only the skills off. Tools stay granted; an activation left with
+         * neither is removed.
+         */
+        async disableAgentSkills(storeDirectory, id) {
+            const store = await realpath(storeDirectory);
+            return update((_installed, activations) => {
+                const enabled = activations.agents[store];
+                const activation = enabled?.[id];
+                if (enabled === undefined || activation?.skills !== true)
+                    return false;
+                if (activation.capabilities.length === 0)
+                    Reflect.deleteProperty(enabled, id);
+                else
+                    enabled[id] = { ...activation, skills: false };
+                return true;
             });
         },
         async disableAgent(storeDirectory, id) {
@@ -432,53 +559,66 @@ export function localExtensions(options = {}) {
             }
             return { clients, terminals, diagnostics };
         },
-        /**
-         * Load the Agent's enabled server extensions through their host factory.
-         * Each failure is isolated to its extension and reported.
-         */
-        async agent(storeDirectory, projectRoot) {
-            const store = await realpath(storeDirectory);
+        /** Capture validated records so one reload cannot mix file generations. */
+        async captureAgent() {
             const [installed, activations] = await Promise.all([
                 readInstalled(),
                 readActivations(),
             ]);
-            const roster = [];
-            const grants = [];
-            const diagnostics = [];
-            for (const [id, activation] of Object.entries(activations.agents[store] ?? {})) {
-                const record = installed.extensions[id]?.revisions[activation.revision];
-                try {
-                    if (record?.host === null || record === undefined)
-                        throw new LocalExtensionError("not-installed", `Extension ${id}@${activation.revision} is enabled but its host entry is not installed`);
-                    const module = hostModuleSchema.parse(await import(pathToFileURL(record.host).href));
-                    const extension = await module.default({
-                        runtimeDirectory: await runtimeDirectory(projectRoot, id),
-                        defineExtension,
-                        Mycelium,
-                        z,
-                    });
-                    const parsed = rosteredSchema.parse(extension);
-                    if (parsed.manifest.id !== id)
-                        throw new LocalExtensionError("load", `Extension ${id} host returned ${parsed.manifest.id}`);
-                    const requested = new Set(parsed.manifest.requests);
-                    roster.push(z
-                        .custom((value) => rosteredSchema.safeParse(value).success)
-                        .parse(extension));
-                    grants.push({
-                        id: decodeExtensionId(id),
-                        capabilities: activation.capabilities.filter((capability) => requested.has(capability)),
-                    });
-                }
-                catch (cause) {
-                    diagnostics.push({
-                        extensionId: id,
-                        error: cause instanceof LocalExtensionError
-                            ? cause
-                            : new LocalExtensionError("load", `Extension ${id} could not load`, { cause: failure(cause) }),
-                    });
-                }
-            }
-            return { roster, grants, diagnostics };
+            return (storeDirectory, projectRoot) => loadAgent(installed, activations, storeDirectory, projectRoot);
+        },
+        async agent(storeDirectory, projectRoot) {
+            return loadAgent(await readInstalled(), await readActivations(), storeDirectory, projectRoot);
         },
     };
+    async function loadAgent(installed, activations, storeDirectory, projectRoot) {
+        const store = await realpath(storeDirectory);
+        const roster = [];
+        const grants = [];
+        const skills = [];
+        const diagnostics = [];
+        for (const [id, activation] of Object.entries(activations.agents[store] ?? {})) {
+            const record = installed.extensions[id]?.revisions[activation.revision];
+            try {
+                if (record === undefined)
+                    throw new LocalExtensionError("not-installed", `Extension ${id}@${activation.revision} is enabled but not installed`);
+                if (activation.skills && record.skills !== null)
+                    skills.push({ extensionId: id, directory: record.skills });
+                // A skills-only activation grants no tools and loads no host code.
+                if (activation.capabilities.length === 0)
+                    continue;
+                if (record.host === null)
+                    throw new LocalExtensionError("not-installed", `Extension ${id}@${activation.revision} is enabled but its host entry is not installed`);
+                const module = hostModuleSchema.parse(await import(pathToFileURL(record.host).href));
+                const extension = await module.default({
+                    runtimeDirectory: await runtimeDirectory(projectRoot, id),
+                    defineExtension,
+                    Mycelium,
+                    z,
+                });
+                const parsed = rosteredSchema.parse(extension);
+                if (parsed.manifest.id !== id)
+                    throw new LocalExtensionError("load", `Extension ${id} host returned ${parsed.manifest.id}`);
+                const requested = new Set(parsed.manifest.requests);
+                roster.push(z
+                    .custom((value) => rosteredSchema.safeParse(value).success)
+                    .parse(extension));
+                grants.push({
+                    id: decodeExtensionId(id),
+                    capabilities: activation.capabilities.filter((capability) => requested.has(capability)),
+                });
+            }
+            catch (cause) {
+                diagnostics.push({
+                    extensionId: id,
+                    error: cause instanceof LocalExtensionError
+                        ? cause
+                        : new LocalExtensionError("load", `Extension ${id} could not load`, { cause: failure(cause) }),
+                });
+            }
+        }
+        // Same skill name in two extensions: the lower extension id wins, always.
+        skills.sort((a, b) => a.extensionId.localeCompare(b.extensionId));
+        return { roster, grants, skills, diagnostics };
+    }
 }