@plurnk/plurnk-service 1.24.0 → 1.26.0

package/dist/server/SkillsFunctionality.js

@@ -1,159 +1,101 @@
 // {§skills-functionality} — standard Agent Skills as one workspace Functionality
-// family. Universal roots and host-provided trees own resources;
-// workspace state owns enablement; the standard
-// `skills` CLI is the deterministic installer beneath `add`/`remove` and the
-// registry behind `discover`, and neither is the model's or a client's contract.
-import { execFile } from "node:child_process";
-import ExecEnv from "../schemes/exec-env.js";
+// family. Configuration roots are inputs; live references and fetched sources
+// belong to workspace definitions, never to an installation scope.
 import { createHash } from "node:crypto";
 import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { promisify, stripVTControlCharacters } from "node:util";
 import { SkillDirectory } from "@plurnk/plurnk-agent-skills";
-import { Problems, SKILL_NAME, Validator, } from "@plurnk/plurnk-contracts";
+import { SKILL_NAME, Validator, } from "@plurnk/plurnk-contracts";
 import HostPaths from "../core/HostPaths.js";
-import { Knob } from "@plurnk/plurnk-meta";
+import { ConfigurationError, Knob, ResourceEnvironment } from "@plurnk/plurnk-meta";
 import Paths from "../Paths.js";
-const execFileP = promisify(execFile);
+import SkillSource from "./SkillSource.js";
+import { agentRootScopes } from "./AgentRoots.js";
+import { SkillsActionError, actionError, messageOf } from "./skills-problems.js";
+import WorkspacePlugins from "./WorkspacePlugins.js";
 const SKILLS_FAMILY = "skills";
 const SKILLS_OWNER = "@plurnk/plurnk-core/skills";
 const DEFINITION = { $ref: "https://schemas.plurnk.xyz/v0/SkillDefinition.json" };
-// The ceiling of one skills CLI run's captured output: a bound on a child process, not a choice.
-const CLI_OUTPUT_BYTES = 8 * 1024 * 1024;
-class SkillsActionError extends Error {
-    problem;
-    constructor(problem, cause) {
-        super(problem.detail, cause === undefined ? undefined : { cause });
-        this.name = "SkillsActionError";
-        this.problem = problem;
-    }
-}
-const problem = (code, status, detail, extensions = {}) => Problems.create("skills:functionality", code, status, detail, {
-    stage: "skills-functionality",
-    retryable: status === 409 || status >= 500,
-    ...extensions,
+// {§skills-sources} — the vendor installer's knobs; each names what replaced it.
+const RETIRED_KNOBS = Object.freeze({
+    PLURNK_SERVICE_SKILLS_CLI: "add fetches git, folder and file sources itself",
+    PLURNK_SERVICE_SKILLS_CLI_TIMEOUT_MS: "PLURNK_SERVICE_SKILLS_FETCH_TIMEOUT_MS bounds each fetch",
+    PLURNK_SERVICE_SKILLS_REGISTRY_URL: "discover takes a source; Agent Skills have no standard registry",
+    PLURNK_SERVICE_SKILLS_REGISTRY_LIMIT: "discover takes a source; Agent Skills have no standard registry",
+    PLURNK_SERVICE_SKILLS_REGISTRY_TIMEOUT_MS: "discover takes a source; Agent Skills have no standard registry",
 });
-const actionError = (code, status, detail, extensions = {}, cause) => new SkillsActionError(problem(code, status, detail, extensions), cause);
+// Installed roots in precedence order: a nearer root shadows a farther one by name.
+const ROOTS = ["project", "plurnk", "global"];
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
 const missing = (cause) => {
     if (cause?.code === "ENOENT")
         return false;
     throw cause;
 };
 const isFile = (path) => stat(path).then((info) => info.isFile(), missing);
-const exists = (path) => stat(path).then(() => true, missing);
-// `skills add <source> --list` prints, after an "Available Skills" heading,
-// each skill name at one indentation and its description at a deeper one,
-// behind the CLI's box-drawing gutter. Only that structure is read.
-export const parseListing = (output) => {
-    const lines = stripVTControlCharacters(output).split(/\r?\n/u);
-    const start = lines.findIndex((line) => /Available Skills\s*$/u.test(line));
-    if (start === -1)
-        return [];
-    const skills = [];
-    for (const line of lines.slice(start + 1)) {
-        const match = /^[^\s\p{L}\p{N}]*( +)(\S.*)$/u.exec(line);
-        if (match === null)
-            continue;
-        const indent = match[1].length;
-        const text = match[2].trim();
-        if (indent === 4) {
-            if (SKILL_NAME.test(text))
-                skills.push({ name: text, description: "" });
-            continue;
+const environment = (env = process.env) => new ResourceEnvironment("PLURNK_SKILLS_", { controls: [], settings: [], aliasPattern: SKILL_NAME }, env);
+export const serviceSkills = (env = process.env) => {
+    const definitions = new Map();
+    for (const [alias, { key, value }] of environment(env).definitions) {
+        let definition;
+        try {
+            definition = Validator.assertSkillDefinition(JSON.parse(value));
         }
-        const last = skills.at(-1);
-        if (last === undefined || indent < 6)
-            continue;
-        skills[skills.length - 1] = { name: last.name, description: last.description.length === 0 ? text : `${last.description} ${text}` };
-    }
-    return skills;
-};
-export class StandardSkillsToolchain {
-    #command;
-    #registry;
-    constructor(env = process.env) {
-        // {§operator-config-only-home} — the panel states both values; an unset key is a broken floor.
-        const cli = env.PLURNK_SERVICE_SKILLS_CLI;
-        if (cli === undefined)
-            throw new Error("PLURNK_SERVICE_SKILLS_CLI is missing from the assembled environment floor.");
-        if (cli.trim().length === 0)
-            throw new Error("PLURNK_SERVICE_SKILLS_CLI must name the Agent Skills installer command.");
-        this.#command = cli.trim().split(/\s+/u);
-        const registry = env.PLURNK_SERVICE_SKILLS_REGISTRY_URL;
-        if (registry === undefined)
-            throw new Error("PLURNK_SERVICE_SKILLS_REGISTRY_URL is missing from the assembled environment floor.");
-        this.#registry = registry.trim().length === 0 ? null : registry.trim().replace(/\/+$/u, "");
-    }
-    get registry() {
-        return this.#registry;
-    }
-    async run(args, cwd, home) {
-        const [command, ...prefix] = this.#command;
-        const { stdout, stderr } = await execFileP(command, [...prefix, ...args], {
-            cwd,
-            // {§exec-env-scoped} — the registry CLI is plurnk's own tooling, so it keeps the
-            // operator's environment (npm config, proxies) but never plurnk's secrets. NO_COLOR
-            // and CI arrive as declared floors from @plurnk/plurnk-execs rather than inline.
-            env: { ...ExecEnv.withoutOwnSecrets(), HOME: home },
-            timeout: Knob.integer("PLURNK_SERVICE_SKILLS_CLI_TIMEOUT_MS", 1),
-            maxBuffer: CLI_OUTPUT_BYTES,
-        });
-        return `${stdout}\n${stderr}`;
-    }
-    async search(query) {
-        if (this.#registry === null) {
-            throw actionError("registry-not-configured", 501, "Skills registry search is disabled; PLURNK_SERVICE_SKILLS_REGISTRY_URL is empty.", { query, retryable: false });
+        catch (cause) {
+            throw new ConfigurationError(key, `${key} must contain a complete SkillDefinition.`, { cause });
         }
-        const url = `${this.#registry}/api/search?${new URLSearchParams({ q: query, limit: String(Knob.integer("PLURNK_SERVICE_SKILLS_REGISTRY_LIMIT", 1)) })}`;
-        let response;
+        if (definition.name !== alias)
+            throw new ConfigurationError(key, `${key}: the definition name must equal '${alias}'.`);
+        if (definition.source === undefined)
+            throw new ConfigurationError(key, `${key}: a configured skill requires a source.`);
+        if (definition.commit !== undefined)
+            throw new ConfigurationError(key, `${key}: commit is service-recorded; configure a Git ref instead.`);
         try {
-            response = await fetch(url, { signal: AbortSignal.timeout(Knob.integer("PLURNK_SERVICE_SKILLS_REGISTRY_TIMEOUT_MS", 1)) });
+            const remote = SkillSource.remote(definition.source);
+            if (definition.ref !== undefined && remote === null)
+                throw new Error("A ref names a branch or tag of a git source.");
         }
         catch (cause) {
-            throw actionError("registry-unreachable", 502, `Skills registry ${this.#registry} could not be reached.`, { query, registry: this.#registry, retryable: true }, cause);
+            throw new ConfigurationError(key, `${key}: invalid skill source or ref.`, { cause });
         }
-        if (!response.ok)
-            throw actionError("registry-rejected", 502, `Skills registry ${this.#registry} answered ${response.status}.`, { query, registry: this.#registry, status: response.status, retryable: true });
-        const body = await response.json();
-        if (!Array.isArray(body.skills))
-            throw actionError("registry-invalid", 502, `Skills registry ${this.#registry} returned no skills array.`, { query, registry: this.#registry, retryable: true });
-        return body.skills.flatMap((skill) => {
-            if (!isRecord(skill) || typeof skill.name !== "string" || typeof skill.id !== "string")
-                return [];
-            return [{
-                    name: skill.name,
-                    id: skill.id,
-                    source: typeof skill.source === "string" && skill.source.length > 0 ? skill.source : skill.id.split("/").slice(0, 2).join("/"),
-                    installs: typeof skill.installs === "number" ? skill.installs : null,
-                    reference: `${this.#registry}/${skill.id}`,
-                }];
-        });
+        definitions.set(alias, definition);
     }
-}
+    return definitions;
+};
 export default class SkillsFunctionality {
     family = SKILLS_FAMILY;
     aliasPattern = SKILL_NAME;
     namespaceOwner = SKILLS_OWNER;
     summary = "Manage Agent Skills";
     definitionSchema = DEFINITION;
-    example = { alias: "sql-formatter", definition: { name: "sql-formatter", scope: "project", source: "example/skills" } };
+    example = { alias: "sql-formatter", definition: { name: "sql-formatter", source: "https://git.example/acme/skills.git" } };
     docsDir = Paths.packageRoot;
     discovery = {
-        details: "`query` searches the standard skills registry; `source` inspects one installer package reference (`owner/repo`, a git URL, or a local path). A candidate carries the exact definition to add.",
+        details: "`source` lists the Agent Skills one source carries: a git remote as a full https or ssh URL, a folder, a lone SKILL.md, or a zip or tar archive. A candidate carries the exact definition to add.",
     };
     #db;
     #hostPaths;
-    #toolchain;
+    #storage;
     #provided;
+    #plugins;
     #snapshots = new Map();
     #handle = null;
-    constructor({ db, hostPaths = new HostPaths(), toolchain = new StandardSkillsToolchain(), provided = async () => new Map() }) {
+    constructor({ db, storage, hostPaths = new HostPaths(), provided = async () => new Map(), plugins }) {
         this.#db = db;
+        this.#storage = storage;
         this.#hostPaths = hostPaths;
-        this.#toolchain = toolchain;
         this.#provided = provided;
+        this.#plugins = plugins ?? new WorkspacePlugins({ db, hostPaths });
+    }
+    // Refuses the vendor installer's retired knobs, naming what replaced each, and reads the fetch deadline.
+    static validateConfiguration() {
+        for (const [knob, successor] of Object.entries(RETIRED_KNOBS)) {
+            const stale = process.env[knob];
+            if (stale !== undefined && stale.length > 0)
+                throw new ConfigurationError(knob, `${knob} is retired: ${successor}.`);
+        }
+        Knob.integer("PLURNK_SERVICE_SKILLS_FETCH_TIMEOUT_MS", 1);
+        serviceSkills();
     }
     attach(handle) {
         this.#handle = handle;
@@ -166,15 +108,14 @@ export default class SkillsFunctionality {
         return workspace?.project_root ?? null;
     }
     #rootFor(scope, projectRoot) {
-        if (scope === "service")
-            throw new TypeError("A service-provided skill has no installer root.");
+        if (!agentRootScopes().has(scope))
+            return null;
         if (scope === "global")
             return this.#hostPaths.globalSkillsDir;
+        if (scope === "plurnk")
+            return this.#hostPaths.plurnkSkillsDir;
         return projectRoot === null ? null : this.#hostPaths.projectSkillsDir(projectRoot);
     }
-    #cwdFor(scope, projectRoot) {
-        return scope === "global" || projectRoot === null ? this.#hostPaths.home : projectRoot;
-    }
     async #installedIn(scope, dir) {
         let entries;
         try {
@@ -189,57 +130,38 @@ export default class SkillsFunctionality {
         for (const entry of entries.filter((candidate) => candidate.isDirectory() || candidate.isSymbolicLink())) {
             const file = join(dir, entry.name, "SKILL.md");
             if (await isFile(file))
-                installed.push({ name: entry.name, scope, dir: join(dir, entry.name), file });
+                installed.push({ name: entry.name, dir: join(dir, entry.name), file });
         }
         return installed.toSorted((left, right) => left.name.localeCompare(right.name));
     }
-    // The effective installed union: project shadows global by name.
-    async #scan(projectRoot) {
+    // The effective installed union: project shadows plurnk shadows global, by name.
+    async #scan(workspaceId, projectRoot) {
         const union = new Map();
-        for (const scope of ["project", "global"]) {
-            const dir = this.#rootFor(scope, projectRoot);
-            if (dir === null)
-                continue;
-            for (const installed of await this.#installedIn(scope, dir)) {
+        const { plugins } = await this.#plugins.read(workspaceId);
+        for (const scope of [...ROOTS, "npm"]) {
+            const dir = scope === "npm" ? null : this.#rootFor(scope, projectRoot);
+            const standalone = scope === "npm" || dir === null ? [] : await this.#installedIn(scope, dir);
+            for (const installed of standalone) {
                 if (!union.has(installed.name))
                     union.set(installed.name, installed);
             }
-        }
-        return union;
-    }
-    // The standard installer's lock files record each installed skill's source.
-    async #lockSources(projectRoot) {
-        const sources = new Map();
-        for (const [scope, file] of [
-            ["project", projectRoot === null ? null : join(projectRoot, "skills-lock.json")],
-            ["global", this.#hostPaths.globalSkillsLockFile],
-        ]) {
-            if (file === null)
-                continue;
-            let lock;
-            try {
-                lock = JSON.parse(await readFile(file, "utf8"));
-            }
-            catch (cause) {
-                if (cause?.code === "ENOENT")
-                    continue;
-                throw new Error(`Cannot read Agent Skills lock ${file}.`, { cause });
-            }
-            if (!isRecord(lock) || !isRecord(lock.skills))
-                throw new TypeError(`Invalid Agent Skills lock ${file}: expected a skills object.`);
-            for (const [name, entry] of Object.entries(lock.skills)) {
-                if (isRecord(entry) && typeof entry.source === "string")
-                    sources.set(`${scope}:${name}`, entry.source);
+            for (const plugin of plugins.filter((candidate) => candidate.scope === scope)) {
+                for (const skill of plugin.skills) {
+                    const name = skill.document.name;
+                    if (!union.has(name))
+                        union.set(name, { name, kind: "plugin", dir: skill.directory, file: join(skill.directory, "SKILL.md") });
+                }
             }
         }
-        return sources;
+        return union;
     }
-    async #signature(projectRoot) {
+    async #signature(workspaceId, projectRoot, definitions) {
         const hash = createHash("sha256");
+        hash.update((await this.#plugins.read(workspaceId)).signature);
         for (const [name, tree] of await this.#provided()) {
             hash.update(JSON.stringify([name, "service", tree.document.source]));
         }
-        for (const scope of ["project", "global"]) {
+        for (const scope of ROOTS) {
             const root = this.#rootFor(scope, projectRoot);
             if (root === null)
                 continue;
@@ -249,70 +171,92 @@ export default class SkillsFunctionality {
                 hash.update(JSON.stringify([installed.name, scope, ...identity]));
             }
         }
-        hash.update(JSON.stringify([...(await this.#lockSources(projectRoot))]));
+        const settings = environment();
+        hash.update(JSON.stringify([...serviceSkills()]));
+        for (const [alias, raw] of definitions) {
+            const definition = raw;
+            hash.update(JSON.stringify([alias, definition, settings.enabled(alias)]));
+            if (definition.source === undefined)
+                continue;
+            try {
+                const located = await SkillSource.locate(definition.source, { projectRoot, home: this.#hostPaths.home });
+                if (located.kind !== "folder" && located.kind !== "skill-file")
+                    continue;
+                const opened = await SkillSource.open(located);
+                try {
+                    for (const found of opened.skills.filter(({ name }) => name === alias)) {
+                        hash.update(JSON.stringify([await realpath(found.dir), await readFile(join(found.dir, "SKILL.md"), "utf8")]));
+                    }
+                    hash.update(JSON.stringify(opened.invalid));
+                }
+                finally {
+                    await opened.close();
+                }
+            }
+            catch (cause) {
+                // The preparation reports the source failure; its fingerprint lets restoration trigger a retry.
+                hash.update(messageOf(cause));
+            }
+        }
         return hash.digest("hex");
     }
-    // {§skills-hotload} — filesystem installers operate out of band; before a
-    // turn assembles its packet the family republishes when the roots changed.
+    // {§skills-hotload} — skills placed, edited or deleted out of band are admitted before a turn
+    // assembles its packet. Changed content republishes; otherwise the coordinator republishes only
+    // when the skills it would publish differ from the published ones.
     async refreshIfChanged(identity) {
-        const published = this.#snapshots.get(identity.workspaceId)?.signature;
+        const published = this.#snapshots.get(identity.workspaceId);
         if (published === undefined)
             return;
-        const current = await this.#signature(await this.#projectRoot(identity.workspaceId));
-        if (current === published)
-            return;
+        const current = await this.#signature(identity.workspaceId, await this.#projectRoot(identity.workspaceId), published.definitions);
         if (this.#handle === null)
             throw new Error("Skills Functionality is not attached to its coordinator handle.");
-        await this.#handle.refresh(identity, { gate: "none" });
+        await this.#handle.refresh(identity, { gate: "none", ifChanged: current === published.signature });
     }
     async available(identity) {
-        const projectRoot = await this.#projectRoot(identity.workspaceId);
-        const sources = await this.#lockSources(projectRoot);
-        const installedSkills = await this.#scan(projectRoot);
-        const native = [...installedSkills.values()].map((installed) => {
-            const source = sources.get(`${installed.scope}:${installed.name}`);
-            const definition = { name: installed.name, scope: installed.scope, ...(source === undefined ? {} : { source }) };
-            return { alias: installed.name, definition, enabled: true };
-        });
-        const provided = [...(await this.#provided()).keys()]
-            .filter((name) => !installedSkills.has(name))
-            .map((name) => ({ alias: name, definition: { name, scope: "service" }, enabled: true }));
-        return [...native, ...provided];
+        SkillsFunctionality.validateConfiguration();
+        const installedSkills = await this.#scan(identity.workspaceId, await this.#projectRoot(identity.workspaceId));
+        const settings = environment();
+        const definitions = new Map();
+        for (const name of (await this.#provided()).keys()) {
+            definitions.set(name, { alias: name, definition: { name }, enabled: settings.enabled(name) });
+        }
+        for (const { name, dir, file, kind } of installedSkills.values()) {
+            definitions.set(name, {
+                alias: name, definition: { name, source: dir }, enabled: settings.enabled(name),
+                provenance: { kind: kind ?? "file", source: file },
+            });
+        }
+        for (const [name, definition] of serviceSkills()) {
+            definitions.set(name, {
+                alias: name, definition, enabled: settings.enabled(name),
+                provenance: { kind: "environment", source: settings.definitions.get(name).key },
+            });
+        }
+        return [...definitions.values()];
     }
     async discover(query, identity) {
         if (query.configuration !== undefined) {
-            throw actionError("configuration-unsupported", 400, "Agent Skills discovery takes a registry query or an explicit source; client configuration contributes nothing.", { retryable: false });
+            throw actionError("configuration-unsupported", 400, "Agent Skills discovery takes a source; client configuration contributes nothing.", { retryable: false });
         }
-        if (query.source !== undefined) {
-            const source = query.source;
-            const cwd = this.#cwdFor("project", await this.#projectRoot(identity.workspaceId));
-            let output;
-            try {
-                output = await this.#toolchain.run(["add", source, "--list"], cwd, this.#hostPaths.home);
-            }
-            catch (cause) {
-                throw actionError("discover-failed", 502, `Agent Skills source '${source}' could not be listed: ${messageOf(cause)}`, { source, retryable: true }, cause);
-            }
-            return parseListing(output).map((skill) => ({
+        if (query.query !== undefined) {
+            throw actionError("query-unsupported", 400, "Agent Skills have no standard registry to search; discover takes a source: a git remote as a full https or ssh URL, a folder, a lone SKILL.md, or a zip or tar archive.", { query: query.query, retryable: false });
+        }
+        if (query.source === undefined)
+            return [];
+        const source = query.source;
+        const located = await SkillSource.locate(source, { projectRoot: await this.#projectRoot(identity.workspaceId), home: this.#hostPaths.home });
+        const opened = await SkillSource.open(located);
+        try {
+            return opened.skills.map((skill) => ({
                 alias: skill.name,
-                ...(skill.description.length === 0 ? {} : { summary: skill.description }),
-                definition: { name: skill.name, scope: "project", source },
+                summary: skill.description,
+                definition: { name: skill.name, source },
                 provenance: { kind: "source", source },
             }));
         }
-        if (query.query === undefined)
-            return [];
-        const registry = await this.#toolchain.search(query.query);
-        return registry.flatMap((skill) => {
-            if (!SKILL_NAME.test(skill.name))
-                return [];
-            return [{
-                    alias: skill.name,
-                    ...(skill.installs === null ? {} : { summary: `${skill.installs} installs` }),
-                    definition: { name: skill.name, scope: "project", source: skill.source },
-                    provenance: { kind: "registry", source: skill.source, reference: skill.reference },
-                }];
-        });
+        finally {
+            await opened.close();
+        }
     }
     async admit(input, identity) {
         const params = isRecord(input) ? input : {};
@@ -327,99 +271,103 @@ export default class SkillsFunctionality {
         if (alias !== definition.name) {
             throw actionError("alias-mismatch", 400, `Alias '${alias}' must equal the skill name '${definition.name}'.`, { alias, name: definition.name, retryable: false });
         }
-        if (definition.scope === "service") {
-            throw actionError("scope-not-installable", 400, "Service-provided skills can be enabled or disabled; adding a skill requires project or global scope.", { alias, retryable: false });
+        if (definition.commit !== undefined) {
+            throw actionError("definition-invalid", 400, "The service records the commit a skill was added at; name a ref instead.", { alias, retryable: false });
         }
         if (definition.source === undefined) {
-            throw actionError("source-required", 400, `Adding '${alias}' requires the standard installer source that provides it.`, { alias, retryable: false });
+            throw actionError("source-required", 400, `Adding '${alias}' requires the source that provides it.`, { alias, retryable: false });
         }
-        if (definition.scope === "project" && await this.#projectRoot(identity.workspaceId) === null) {
-            throw actionError("project-root-required", 400, `'${alias}' targets the project scope, but this workspace has no project root.`, { alias, recovery: "Add it with scope \"global\" or open a workspace rooted in a project.", retryable: false });
-        }
-        return { alias, definition };
-    }
-    async #install(definition, root, cwd) {
-        const args = ["add", definition.source, "--agent", "universal", "--skill", definition.name, "--yes", ...(definition.scope === "global" ? ["--global"] : [])];
-        let output;
-        try {
-            output = await this.#toolchain.run(args, cwd, this.#hostPaths.home);
-        }
-        catch (cause) {
-            throw actionError("install-failed", 502, `Agent Skill '${definition.name}' could not be installed from '${definition.source}': ${messageOf(cause)}`, { name: definition.name, source: definition.source, scope: definition.scope, retryable: true }, cause);
-        }
-        const file = join(root, definition.name, "SKILL.md");
-        if (!(await isFile(file))) {
-            throw actionError("install-failed", 502, `The installer reported '${definition.name}' from '${definition.source}' but ${file} does not exist.`, { name: definition.name, source: definition.source, scope: definition.scope, output: stripVTControlCharacters(output).trim().slice(-2000), retryable: true });
+        const projectRoot = await this.#projectRoot(identity.workspaceId);
+        const located = await SkillSource.locate(definition.source, { projectRoot, home: this.#hostPaths.home });
+        if (located.kind !== "git") {
+            if (definition.ref !== undefined)
+                throw actionError("definition-invalid", 400, "A ref names a branch or tag of a git source.", { alias, retryable: false });
+            return { alias, definition: { ...definition, source: located.location } };
         }
-        return { name: definition.name, scope: definition.scope, dir: join(root, definition.name), file };
+        return { alias, definition: { ...definition, commit: await SkillSource.resolveCommit(located.location, definition.ref) } };
     }
-    // {§skills-remove} — the coordinator forgets the workspace definition;
-    // the adapter uninstalls what that definition installed at its scope.
-    async forget(source, identity) {
-        const definition = source.definition;
-        const projectRoot = await this.#projectRoot(identity.workspaceId);
-        const root = this.#rootFor(definition.scope, projectRoot);
-        if (root === null)
-            return;
-        const dir = join(root, definition.name);
-        if (!(await exists(dir)))
-            return;
+    // {§skills-sources} — complete source identity owns a reusable materialization within one workspace.
+    async #loadSource(definition, workspaceId, projectRoot) {
+        const key = createHash("sha256").update(JSON.stringify([
+            definition.name, definition.source, definition.ref ?? null, definition.commit ?? null,
+        ])).digest("hex");
+        const root = join(await this.#storage.directory(workspaceId, SKILLS_OWNER), key);
+        const cached = join(root, definition.name);
+        if (await isFile(join(cached, "SKILL.md")))
+            return this.#loadDirectory(definition.name, cached);
+        const located = await SkillSource.locate(definition.source, { projectRoot, home: this.#hostPaths.home });
+        const opened = await SkillSource.open(located, {
+            ...(definition.ref === undefined ? {} : { ref: definition.ref }),
+            ...(definition.commit === undefined ? {} : { commit: definition.commit }),
+        });
         try {
-            await this.#toolchain.run(["remove", definition.name, "--yes", ...(definition.scope === "global" ? ["--global"] : [])], this.#cwdFor(definition.scope, projectRoot), this.#hostPaths.home);
+            const matches = opened.skills.filter(({ name }) => name === definition.name);
+            if (matches.length > 1) {
+                throw actionError("skill-ambiguous", 409, `'${definition.source}' carries ${matches.length} skills named '${definition.name}'.`, {
+                    name: definition.name, source: definition.source, retryable: false,
+                });
+            }
+            const match = matches[0];
+            if (match === undefined) {
+                const broken = opened.invalid.find(({ dir }) => dir.endsWith(`/${definition.name}`));
+                if (broken !== undefined) {
+                    throw actionError("skill-invalid", 422, `Agent Skill '${definition.name}' in '${definition.source}' is not a valid standard skill: ${broken.reason}`, {
+                        name: definition.name, source: definition.source, retryable: false,
+                    });
+                }
+                throw actionError("skill-not-found", 404, `'${definition.source}' carries no Agent Skill named '${definition.name}'.`, {
+                    name: definition.name, source: definition.source, retryable: false,
+                });
+            }
+            if (located.kind === "folder" || located.kind === "skill-file") {
+                await SkillSource.assertInward(match.dir);
+                return await this.#loadDirectory(definition.name, match.dir);
+            }
+            let dir;
+            try {
+                dir = await SkillSource.install(match, root);
+            }
+            catch (cause) {
+                if (cause instanceof SkillsActionError)
+                    throw cause;
+                throw actionError("install-failed", 500, `Agent Skill '${definition.name}' could not be placed under ${root}: ${messageOf(cause)}`, {
+                    name: definition.name, retryable: false,
+                }, cause);
+            }
+            return await this.#loadDirectory(definition.name, dir);
         }
-        catch (cause) {
-            throw actionError("uninstall-failed", 502, `Agent Skill '${definition.name}' could not be removed from its ${definition.scope} root: ${messageOf(cause)}`, { name: definition.name, scope: definition.scope, retryable: true }, cause);
+        finally {
+            await opened.close();
         }
-        if (await exists(dir))
-            throw actionError("uninstall-failed", 502, `The installer reported removal of '${definition.name}' but ${dir} still exists.`, { name: definition.name, scope: definition.scope, retryable: true });
     }
-    async #locate(alias, definition, installed, projectRoot) {
-        const shadowing = installed.get(alias);
-        if (shadowing === undefined || shadowing.scope === definition.scope)
-            return shadowing;
-        // The workspace definition names a root below the one currently
-        // shadowing that name; the definition's scope is truth.
-        const root = this.#rootFor(definition.scope, projectRoot);
-        if (root === null)
-            return undefined;
-        const file = join(root, alias, "SKILL.md");
-        return (await isFile(file)) ? { name: alias, scope: definition.scope, dir: join(root, alias), file } : undefined;
-    }
-    async #loadInstalled(alias, definition, installed, projectRoot) {
-        let located = await this.#locate(alias, definition, installed, projectRoot);
-        if (located === undefined) {
-            const root = this.#rootFor(definition.scope, projectRoot);
-            if (root === null)
-                throw actionError("project-root-required", 409, `'${alias}' targets the project scope, but this workspace has no project root.`, { name: alias, retryable: false });
-            if (definition.source === undefined)
-                throw actionError("skill-missing", 404, `Agent Skill '${alias}' is not installed under its ${definition.scope} root.`, { name: alias, scope: definition.scope, root, retryable: false });
-            located = await this.#install(definition, root, this.#cwdFor(definition.scope, projectRoot));
-        }
+    async #loadDirectory(alias, dir) {
         try {
-            return await SkillDirectory.load(located.dir);
+            return await SkillDirectory.load(dir);
         }
         catch (cause) {
-            throw actionError("skill-invalid", 422, `Agent Skill '${alias}' is not a valid standard skill: ${messageOf(cause)}`, { name: alias, scope: located.scope, path: located.file, retryable: false }, cause);
+            throw actionError("skill-invalid", 422, `Agent Skill '${alias}' is not a valid standard skill: ${messageOf(cause)}`, { name: alias, path: join(dir, "SKILL.md"), retryable: false }, cause);
         }
     }
     async prepare(preparation) {
         const projectRoot = await this.#projectRoot(preparation.workspaceId);
-        const installed = await this.#scan(projectRoot);
+        const definitions = new Map([...preparation.enabled].map(([alias, { definition }]) => [alias, definition]));
+        // Read before the skills it describes, so content changed while they load is seen as changed.
+        const signature = await this.#signature(preparation.workspaceId, projectRoot, definitions);
         const provided = await this.#provided();
         const previous = preparation.previous;
         const carried = new Set(previous?.unavailable ?? []);
         const outcomes = new Map();
         const trees = new Map();
-        for (const [alias, raw] of preparation.enabled) {
+        for (const [alias, raw] of definitions) {
+            preparation.progress(alias);
             const definition = raw;
             try {
-                const tree = definition.scope === "service" ? provided.get(alias)
-                    : await this.#loadInstalled(alias, definition, installed, projectRoot);
+                const tree = definition.source === undefined ? provided.get(alias)
+                    : await this.#loadSource(definition, preparation.workspaceId, projectRoot);
                 if (tree === undefined)
                     throw actionError("skill-missing", 404, `Agent Skill '${alias}' is not provided by this service.`, { name: alias, retryable: false });
                 trees.set(new URL(`skill://${alias}/`).hostname, tree);
                 outcomes.set(alias, { state: "active", detail: {
-                        scope: definition.scope,
                         ...(tree instanceof SkillDirectory ? { path: tree.directory } : {}),
                         description: tree.document.description,
                     } });
@@ -435,10 +383,10 @@ export default class SkillsFunctionality {
                 outcomes.set(alias, { state: "unavailable", problem: structuredClone(cause.problem) });
             }
         }
-        const signature = await this.#signature(projectRoot);
         const snapshot = {
             signature,
             trees,
+            definitions,
             unavailable: [...outcomes].filter(([, outcome]) => outcome.state === "unavailable").map(([alias]) => alias),
         };
         const { workspaceId } = preparation;