@agentxm/extension-lifecycle 0.28.4-bootstrap.0

package/dist/src/skills/manager.js

@@ -0,0 +1,346 @@
+/**
+ * Skill extension manager service.
+ *
+ * Implements ExtensionManager<SkillExtensionRef> with native/non-native
+ * branching in materializeInstall and agent symlink creation for all
+ * configured agents.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { sourceToLockEntry } from "@agentxm/workspace-state";
+import { configuredSkillsToDiskRefs } from "@agentxm/extension-workspace";
+import { enabledConfiguredEntries } from "@agentxm/extension-workspace";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { sanitizeName } from "@agentxm/workspace-state";
+import { computePackageContentHash } from "@agentxm/workspace-state";
+import { stripFileProtocol } from "../internal/fs-helpers.js";
+import { makeWorkspaceRelativeSourcePath } from "@agentxm/extension-model/unstable/path-types";
+import { removeIfExists } from "@agentxm/workspace-state";
+import { CodingAgentRepository, SkillManager, applyProjectionPlans, planSingletonProjection, SkillDefinitionInvalid, SkillInstallStateMissing, } from "@agentxm/extension-workspace";
+import {} from "@agentxm/extension-model/unstable/agents/types";
+import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
+import { computeSkillSourceHash } from "./operations/source-hash.js";
+import { ensureSkillAgentArtifact, materializeSkillCanonical, removeSkillAgentArtifact, } from "./materialization.js";
+import { configuredRowsByName } from "@agentxm/workspace-state";
+import { acceptedCanonicalObservation, prepareAcceptedCanonicalTransition, removableAcceptedCanonicalPath, usableAcceptedCanonicalRef, } from "@agentxm/workspace-state";
+import { isObservedInstalled } from "@agentxm/workspace-state";
+// -----------------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------------
+// Build skill lock entry from ref
+const buildSkillLockEntry = (ref, workspaceRelativeLocalSourcePath, contentIdentity, treeIntegrity) => sourceToLockEntry({
+    ref,
+    sourceName: Option.none(),
+    contentIdentity,
+    treeIntegrity,
+    workspaceRelativeLocalSourcePath,
+});
+// -----------------------------------------------------------------------------
+// Live Layer
+// -----------------------------------------------------------------------------
+export const SkillManagerLive = Layer.effect(SkillManager, Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const httpClient = yield* HttpClient.HttpClient;
+    const path = yield* Path.Path;
+    const sources = yield* SourceHostProviders;
+    const agentRepo = yield* CodingAgentRepository;
+    const baseDir = ws.baseDir;
+    // Build a layer to provide FileSystem + Path to inner effects
+    const fsPathLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path));
+    const registryMaterializationLayer = Layer.merge(fsPathLayer, Layer.succeed(HttpClient.HttpClient, httpClient));
+    // Provide FileSystem + Path to an effect that needs them
+    const provide = (effect) => Effect.provide(effect, fsPathLayer);
+    const provideRegistry = (effect) => Effect.provide(effect, registryMaterializationLayer);
+    const lastSourceHashes = new Map();
+    const lastTreeIntegrities = new Map();
+    const lastMaterializations = new Map();
+    const materializeInstall = Effect.fn("SkillManager.materializeInstall")(function* ({ ref, force }) {
+        const sanitized = sanitizeName(ref.skill.name);
+        const lockedEntry = yield* ws.getLockedSkill(ref.skill.name);
+        const lockedVersion = ref.refType === "registry" ? acceptedRegistryVersionForRef(lockedEntry, ref) : undefined;
+        const materialized = yield* materializeSkillCanonical({
+            ref,
+            sanitizedName: sanitized,
+            fs,
+            pathService: path,
+            baseDir,
+            layout: ws.layout,
+            sources,
+            provide,
+            provideRegistry,
+            reuse: {
+                force: force === true,
+                lockedVersion,
+                lockedTreeIntegrity: Option.isSome(lockedEntry)
+                    ? lockedEntry.value.treeIntegrity
+                    : undefined,
+            },
+        });
+        const skillSrcPath = materialized.skillSrcPath;
+        const configuredAgents = yield* agentRepo
+            .getMaterializationAgents()
+            .pipe(Effect.provideService(WorkspaceMutations, ws));
+        const resolved = yield* Effect.forEach(configuredAgents, (agent) => agent.resolveEffectiveSkillsDir({ workspaceRoot: baseDir }).pipe(Effect.provide(fsPathLayer), Effect.map((outcome) => ({ agent, outcome }))), { concurrency: "unbounded" });
+        const misconfigured = Array.filter(resolved, ({ outcome }) => outcome._tag === "misconfigured");
+        if (misconfigured.length > 0) {
+            return yield* new SkillDefinitionInvalid({
+                detail: "One or more configured agents have invalid skills directory settings",
+            });
+        }
+        const installTargets = [];
+        for (const { agent, outcome } of resolved) {
+            if (outcome._tag === "supported") {
+                installTargets.push({ agentId: agent.id, dir: path.normalize(outcome.dir) });
+            }
+        }
+        const locations = new Map();
+        for (const target of installTargets) {
+            const existing = locations.get(target.dir);
+            if (existing === undefined) {
+                locations.set(target.dir, { dir: target.dir, agentIds: [target.agentId] });
+            }
+            else if (!existing.agentIds.includes(target.agentId)) {
+                existing.agentIds.push(target.agentId);
+            }
+        }
+        yield* applyProjectionPlans([...locations.values()].map((location) => {
+            const targetFile = path.join(location.dir, sanitized);
+            return planSingletonProjection({
+                unitId: "skill:agent-skill-directory",
+                targetFile,
+                contributor: ref,
+                adapter: {
+                    observe: () => Effect.succeed({
+                        unitId: "skill:agent-skill-directory",
+                        path: path.relative(baseDir, targetFile),
+                        present: false,
+                        current: false,
+                        expectedContributors: [ref.skill.name],
+                        observedContributors: [],
+                    }),
+                    apply: () => ensureSkillAgentArtifact({
+                        canonicalSkillSrcPath: skillSrcPath,
+                        targetDir: location.dir,
+                        sanitizedName: sanitized,
+                        pathService: path,
+                        baseDir,
+                        provide,
+                    }),
+                },
+            });
+        }));
+        const sourceHash = ref.refType === "workspace"
+            ? ref.sourceHash
+            : ref.refType === "registry"
+                ? yield* provide(computePackageContentHash(path.dirname(skillSrcPath)))
+                : yield* provide(computeSkillSourceHash(skillSrcPath));
+        lastSourceHashes.set(ref.skill.name, sourceHash);
+        if (ref.refType !== "workspace") {
+            if (materialized.treeIntegrity === undefined) {
+                return yield* new SkillInstallStateMissing({
+                    name: ref.skill.name,
+                    kind: "tree-integrity",
+                });
+            }
+            lastTreeIntegrities.set(ref.skill.name, materialized.treeIntegrity);
+        }
+        lastMaterializations.set(ref.skill.name, {
+            agents: Array.dedupe(installTargets
+                .map((target) => target.agentId)
+                .filter((agentId) => agentId !== "universal")),
+            targets: [...locations.values()].map((location) => {
+                const agentIds = location.agentIds.filter((agentId) => agentId !== "universal");
+                return {
+                    path: path.relative(baseDir, path.join(location.dir, sanitized)),
+                    ...(agentIds.length === 0 ? {} : { agentIds }),
+                };
+            }),
+        });
+    });
+    const makeMaterializeRemoval = (retainCanonical) => Effect.fn("SkillManager.materializeRemoval")(function* ({ target }) {
+        const sanitized = sanitizeName(target.name);
+        const configuredAgents = yield* agentRepo
+            .getMaterializationAgents()
+            .pipe(Effect.provideService(WorkspaceMutations, ws));
+        const resolved = yield* Effect.forEach(configuredAgents, (agent) => agent.resolveEffectiveSkillsDir({ workspaceRoot: baseDir }).pipe(Effect.provide(fsPathLayer), Effect.map((outcome) => ({ agent, outcome }))), { concurrency: "unbounded" });
+        const uninstallTargets = [];
+        for (const { outcome } of resolved) {
+            if (outcome._tag === "supported") {
+                uninstallTargets.push(path.normalize(outcome.dir));
+            }
+        }
+        const distinctDirs = Array.dedupe(uninstallTargets);
+        yield* applyProjectionPlans(distinctDirs.map((dir) => {
+            const targetFile = path.join(dir, sanitized);
+            return planSingletonProjection({
+                unitId: "skill:agent-skill-directory",
+                targetFile,
+                contributor: target,
+                adapter: {
+                    observe: () => Effect.succeed({
+                        unitId: "skill:agent-skill-directory",
+                        path: path.relative(baseDir, targetFile),
+                        present: true,
+                        current: false,
+                        expectedContributors: [],
+                        observedContributors: [target.name],
+                    }),
+                    apply: () => removeSkillAgentArtifact({
+                        fs,
+                        pathService: path,
+                        targetDir: dir,
+                        sanitizedName: sanitized,
+                    }),
+                },
+            });
+        }));
+        if (!retainCanonical) {
+            const canonical = yield* provide(acceptedCanonicalObservation({ workspace: ws, type: "skill", name: target.name }));
+            const packageRoot = removableAcceptedCanonicalPath(canonical);
+            if (Option.isSome(packageRoot))
+                yield* removeIfExists(fs, packageRoot.value);
+        }
+    });
+    const materializeUninstall = makeMaterializeRemoval(false);
+    const materializeDeactivate = makeMaterializeRemoval(true);
+    return {
+        type: "skill",
+        runTransaction: ws.runTransaction,
+        isInstalled: Effect.fn("SkillManager.isInstalled")(function* ({ target, }) {
+            return yield* isObservedInstalled(ws, "skill", target.name);
+        }),
+        materializeInstall,
+        prepareSourceTransition: ({ ref }) => provide(prepareAcceptedCanonicalTransition({
+            workspace: ws,
+            type: "skill",
+            name: ref.skill.name,
+            ref,
+        })),
+        getLastMaterialization: ({ target }) => Effect.succeed(lastMaterializations.get(target.name) ?? {
+            agents: [],
+            targets: [],
+        }),
+        getConfiguredSource: Effect.fn("SkillManager.getConfiguredSource")(function* ({ target }) {
+            const configured = yield* ws.getConfiguredSkillEntries();
+            const entry = configured[target.name];
+            if (entry?.origin === "bundled") {
+                return Option.some(`bundled:@agentxm/skills/${target.name}`);
+            }
+            return Option.fromUndefinedOr(entry?.source);
+        }),
+        listMaterializable: Effect.fn("SkillManager.listMaterializable")(function* () {
+            const configured = yield* ws.records
+                .rows("skill")
+                .pipe(Effect.map(configuredRowsByName));
+            const configuredEntries = yield* ws.getConfiguredSkillEntries();
+            const configuredWithoutBundled = Object.fromEntries(Object.entries(configured).filter(([name]) => configuredEntries[name]?.origin !== "bundled"));
+            const workspaceRefs = yield* configuredSkillsToDiskRefs({ fs, path, baseDir, scope: ws.scope, layout: ws.layout }, configuredWithoutBundled);
+            const trustedRefs = yield* Effect.forEach(enabledConfiguredEntries(configured), ([name]) => configuredEntries[name]?.origin === "bundled"
+                ? Effect.succeed(Option.none())
+                : provide(usableAcceptedCanonicalRef({ workspace: ws, type: "skill", name }).pipe(Effect.map(Option.filter((ref) => ref.type === "skill")))), { concurrency: "unbounded" });
+            const refsByName = new Map(workspaceRefs.map((ref) => [ref.skill.name, ref]));
+            for (const ref of trustedRefs) {
+                if (Option.isSome(ref))
+                    refsByName.set(ref.value.skill.name, ref.value);
+            }
+            return [...refsByName.values()];
+        }),
+        materializeUninstall,
+        materializeDeactivate,
+        upsertSettingsEntry: Effect.fn("SkillManager.upsertSettingsEntry")(function* ({ ref, versionRange, }) {
+            const workspaceRelativeLocalSourcePath = ref.refType === "local"
+                ? makeWorkspaceRelativeSourcePath(path, baseDir, ref.sourcePath ?? stripFileProtocol(ref.location))
+                : Option.none();
+            if (ref.refType === "local" && Option.isNone(workspaceRelativeLocalSourcePath)) {
+                return yield* new SkillDefinitionInvalid({
+                    detail: `Local skill source path must stay within the workspace root: ${ref.source.path}`,
+                });
+            }
+            const sourceHash = lastSourceHashes.get(ref.skill.name);
+            const treeIntegrity = lastTreeIntegrities.get(ref.skill.name);
+            if (ref.refType === "workspace") {
+                return yield* ws.setSkillEntry(ref.skill.name, {
+                    source: "workspace",
+                    enabled: true,
+                });
+            }
+            if (sourceHash === undefined || treeIntegrity === undefined) {
+                return yield* new SkillInstallStateMissing({
+                    name: ref.skill.name,
+                    kind: "content-identity",
+                });
+            }
+            const lockEntry = buildSkillLockEntry(ref, workspaceRelativeLocalSourcePath, sourceHash, treeIntegrity);
+            if (lockEntry === undefined) {
+                return yield* new SkillInstallStateMissing({
+                    name: ref.skill.name,
+                    kind: "external-resolution",
+                });
+            }
+            if (lockEntry.type === "registry") {
+                yield* validateExactResolvedVersion(`skills.${ref.skill.name}.resolvedVersion`, lockEntry.resolvedVersion);
+            }
+            return yield* ws.setSkill({
+                name: ref.skill.name,
+                lockEntry,
+                versionRange,
+            });
+        }),
+        removeSettingsEntry: ({ target }) => ws
+            .removeSkillFromSettings(target.name)
+            .pipe(Effect.withSpan("SkillManager.removeSettingsEntry")),
+        upsertLockfileEntry: Effect.fn("SkillManager.upsertLockfileEntry")(function* ({ ref, }) {
+            const workspaceRelativeLocalSourcePath = ref.refType === "local"
+                ? makeWorkspaceRelativeSourcePath(path, baseDir, ref.sourcePath ?? stripFileProtocol(ref.location))
+                : Option.none();
+            if (ref.refType === "local" && Option.isNone(workspaceRelativeLocalSourcePath)) {
+                return yield* new SkillDefinitionInvalid({
+                    detail: `Local skill source path must stay within the workspace root: ${ref.source.path}`,
+                });
+            }
+            if (ref.refType === "workspace") {
+                yield* ws.removeSkillLock(ref.skill.name);
+                return;
+            }
+            const sourceHash = lastSourceHashes.get(ref.skill.name);
+            const treeIntegrity = lastTreeIntegrities.get(ref.skill.name);
+            if (sourceHash === undefined || treeIntegrity === undefined) {
+                return yield* new SkillInstallStateMissing({
+                    name: ref.skill.name,
+                    kind: "content-identity",
+                });
+            }
+            const lockEntry = buildSkillLockEntry(ref, workspaceRelativeLocalSourcePath, sourceHash, treeIntegrity);
+            if (lockEntry === undefined) {
+                return yield* new SkillInstallStateMissing({
+                    name: ref.skill.name,
+                    kind: "external-resolution",
+                });
+            }
+            if (lockEntry.type === "registry") {
+                yield* validateExactResolvedVersion(`skills.${ref.skill.name}.resolvedVersion`, lockEntry.resolvedVersion);
+            }
+            return yield* ws.setSkillLock({
+                name: ref.skill.name,
+                lockEntry,
+                versionRange: Option.none(),
+            });
+        }),
+        removeLockfileEntry: ({ target }) => ws
+            .removeSkillLock(target.name)
+            .pipe(Effect.withSpan("SkillManager.removeLockfileEntry")),
+    };
+}));
+// -----------------------------------------------------------------------------
+// Internal materialization helpers
+// -----------------------------------------------------------------------------
+//# sourceMappingURL=manager.js.map

package/dist/src/skills/materialization.d.ts

@@ -0,0 +1,54 @@
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { SkillMaterializationFailed } from "@agentxm/extension-workspace";
+import { type TreeIntegrity } from "@agentxm/workspace-state";
+import type { SourceHostProvidersService } from "@agentxm/extension-sources";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { WorkspaceLayout } from "@agentxm/workspace-state";
+export type ProvideFs = <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, FileSystem.FileSystem | Path.Path>>;
+export type ProvideRegistryMaterialization = <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>>;
+/** Reuse inputs sourced from the caller's operation context and lockfile. */
+export type CanonicalReuseContext = {
+    readonly force: boolean;
+    readonly lockedVersion: string | undefined;
+    readonly lockedTreeIntegrity: TreeIntegrity | undefined;
+};
+export interface MaterializedSkillCanonical {
+    readonly skillSrcPath: string;
+    readonly treeIntegrity?: TreeIntegrity;
+}
+export declare const materializeSkillCanonical: (args: {
+    readonly ref: SkillExtensionRef;
+    readonly sanitizedName: string;
+    readonly fs: FileSystem.FileSystem;
+    readonly pathService: Path.Path;
+    readonly baseDir: string;
+    readonly layout: WorkspaceLayout;
+    readonly sources: SourceHostProvidersService;
+    readonly provide: ProvideFs;
+    readonly provideRegistry: ProvideRegistryMaterialization;
+    readonly reuse?: CanonicalReuseContext;
+}) => Effect.Effect<{
+    skillSrcPath: string & import("effect/Brand").Brand<"AbsolutePath">;
+    treeIntegrity: string & import("effect/Brand").Brand<"TreeIntegrity">;
+}, import("@agentxm/extension-workspace").CanonicalDirectoryReplacementError | import("@agentxm/workspace-state").MaterializedTreeInvalid | import("@agentxm/extension-workspace").PackageCopyFailed | import("@agentxm/extension-workspace").CanonicalPackageProbeFailed | import("@agentxm/extension-workspace").AxmSkillCompatibilityUnavailable | import("@agentxm/extension-workspace").AxmSkillIncompatible, never> | Effect.Effect<{
+    skillSrcPath: string & import("effect/Brand").Brand<"AbsolutePath">;
+    treeIntegrity: string & import("effect/Brand").Brand<"TreeIntegrity">;
+}, import("@agentxm/extension-workspace").CoupledDependencyFailure | import("@agentxm/extension-workspace").ArchiveIntegrityMismatch | import("@agentxm/extension-workspace").CanonicalDirectoryReplacementError | import("@agentxm/workspace-state").MaterializedTreeInvalid | import("@agentxm/extension-workspace").CanonicalPackageProbeFailed | import("@agentxm/extension-workspace").AxmSkillCompatibilityUnavailable | import("@agentxm/extension-workspace").AxmSkillIncompatible, never> | Effect.Effect<MaterializedSkillCanonical, import("@agentxm/workspace-state").PathTraversalDetected | import("@agentxm/extension-workspace").AxmSkillCompatibilityUnavailable | import("@agentxm/extension-workspace").AxmSkillIncompatible, never>;
+export declare const ensureSkillAgentArtifact: (args: {
+    readonly canonicalSkillSrcPath: string;
+    readonly targetDir: string;
+    readonly sanitizedName: string;
+    readonly pathService: Path.Path;
+    readonly baseDir: string;
+    readonly provide: ProvideFs;
+}) => Effect.Effect<void, SkillMaterializationFailed, never>;
+export declare const removeSkillAgentArtifact: (args: {
+    readonly fs: FileSystem.FileSystem;
+    readonly pathService: Path.Path;
+    readonly targetDir: string;
+    readonly sanitizedName: string;
+}) => Effect.Effect<void, SkillMaterializationFailed, never>;
+//# sourceMappingURL=materialization.d.ts.map

package/dist/src/skills/materialization.js

@@ -0,0 +1,158 @@
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { SkillMaterializationFailed, validateAxmSkillCandidate, } from "@agentxm/extension-workspace";
+import { canReuseExternalPackage, canReuseInstalledPackage, materializeExternalPackageWithTreeIntegrity, } from "@agentxm/extension-workspace";
+import { materializeRegistryPackageWithTreeIntegrity } from "../registry-materialization.js";
+import { validatePathSafety } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
+import { copyExtensionDirectory } from "@agentxm/extension-workspace";
+import { computeSkillPathsForLayout } from "@agentxm/workspace-state";
+import { stripFileProtocol } from "../internal/fs-helpers.js";
+import { isPathSafe } from "@agentxm/workspace-state";
+import { createSymlink } from "@agentxm/workspace-state";
+import { protectWorkspacePath } from "@agentxm/workspace-state";
+const replaceExternalCanonical = (fs, pathService, baseDir, sanitizedName, sourcePath, copyTarget, reuse, provide) => Effect.gen(function* () {
+    const useExisting = yield* provide(canReuseExternalPackage({
+        installedPath: copyTarget,
+        force: reuse.force,
+        existsFailureDetail: (target) => `Failed to check if canonical path exists: ${target}`,
+    }));
+    if (useExisting && reuse.lockedTreeIntegrity !== undefined) {
+        const observedTree = yield* provide(computeMaterializedTreeIntegrity(copyTarget));
+        if (observedTree === reuse.lockedTreeIntegrity)
+            return reuse.lockedTreeIntegrity;
+    }
+    const materialized = yield* provide(materializeExternalPackageWithTreeIntegrity({
+        baseDir,
+        canonicalPath: copyTarget,
+        sourceLocation: sourcePath,
+        copyFailureCode: "internal",
+        copyFailureDetail: (target) => `Failed to copy skill files to ${target}`,
+    }));
+    return materialized.treeIntegrity;
+});
+const materializeGitHosted = (ref, sanitizedName, fs, pathService, baseDir, layout, provide, reuse) => Effect.gen(function* () {
+    const { canonicalPath, skillSrcPath } = computeSkillPathsForLayout(pathService.join, layout, ref, sanitizedName);
+    yield* validatePathSafety(pathService, baseDir, canonicalPath);
+    const packageRoot = stripFileProtocol(ref.location);
+    const sourceSkillPath = ref.portable === true ? packageRoot : pathService.join(packageRoot, "src");
+    yield* provide(validateAxmSkillCandidate({
+        ref,
+        packageRoot,
+        skillSourcePath: sourceSkillPath,
+    }));
+    const isSelfCopy = pathService.resolve(packageRoot) === pathService.resolve(canonicalPath);
+    const treeIntegrity = isSelfCopy
+        ? yield* provide(computeMaterializedTreeIntegrity(canonicalPath))
+        : yield* replaceExternalCanonical(fs, pathService, baseDir, sanitizedName, packageRoot, canonicalPath, reuse, provide);
+    return { skillSrcPath, treeIntegrity };
+});
+const materializeLocal = (ref, sanitizedName, fs, pathService, baseDir, layout, provide, reuse) => Effect.gen(function* () {
+    const { canonicalPath, skillSrcPath } = computeSkillPathsForLayout(pathService.join, layout, ref, sanitizedName);
+    yield* validatePathSafety(pathService, baseDir, canonicalPath);
+    const packageRoot = stripFileProtocol(ref.location);
+    const sourceSkillPath = ref.portable === true ? packageRoot : pathService.join(packageRoot, "src");
+    yield* provide(validateAxmSkillCandidate({
+        ref,
+        packageRoot,
+        skillSourcePath: sourceSkillPath,
+    }));
+    const isSelfCopy = pathService.resolve(packageRoot) === pathService.resolve(canonicalPath);
+    const treeIntegrity = isSelfCopy
+        ? yield* provide(computeMaterializedTreeIntegrity(canonicalPath))
+        : yield* replaceExternalCanonical(fs, pathService, baseDir, sanitizedName, packageRoot, canonicalPath, reuse, provide);
+    return { skillSrcPath, treeIntegrity };
+});
+const materializeRegistry = (ref, sanitizedName, fs, pathService, baseDir, layout, provide, provideRegistry, reuse) => Effect.scoped(Effect.gen(function* () {
+    const source = ref;
+    const { canonicalPath, skillSrcPath } = computeSkillPathsForLayout(pathService.join, layout, source, sanitizedName);
+    yield* validatePathSafety(pathService, baseDir, canonicalPath);
+    const useExisting = yield* provide(canReuseInstalledPackage({
+        installedPath: canonicalPath,
+        force: reuse.force,
+        refVersion: ref.version,
+        hasIntegrity: Option.isSome(ref.integrity),
+        ...(reuse.lockedVersion === undefined ? {} : { lockedVersion: reuse.lockedVersion }),
+        existsFailureDetail: (target) => `Failed to check if canonical path exists: ${target}`,
+    }));
+    if (useExisting && reuse.lockedTreeIntegrity !== undefined) {
+        const observedTree = yield* provide(computeMaterializedTreeIntegrity(canonicalPath));
+        if (observedTree === reuse.lockedTreeIntegrity) {
+            yield* provide(validateAxmSkillCandidate({
+                ref,
+                packageRoot: canonicalPath,
+                skillSourcePath: skillSrcPath,
+            }));
+            return { skillSrcPath, treeIntegrity: reuse.lockedTreeIntegrity };
+        }
+    }
+    const materialized = yield* provideRegistry(materializeRegistryPackageWithTreeIntegrity({
+        baseDir,
+        destinationPath: canonicalPath,
+        sourceLocation: ref.source.location,
+        owner: ref.owner,
+        type: "skill",
+        name: ref.name,
+        version: ref.version,
+        integrity: ref.integrity,
+        messages: {
+            integrityMismatchDetail: `Integrity mismatch for ${ref.name}@${ref.version}`,
+        },
+        validate: (stagingPath) => provide(validateAxmSkillCandidate({
+            ref,
+            packageRoot: stagingPath,
+            skillSourcePath: pathService.join(stagingPath, "src"),
+        }).pipe(Effect.asVoid)),
+    }));
+    return { skillSrcPath, treeIntegrity: materialized.treeIntegrity };
+}));
+const materializeWorkspace = (ref, pathService, baseDir, provide) => Effect.gen(function* () {
+    yield* validatePathSafety(pathService, baseDir, ref.location);
+    const skillSourcePath = pathService.join(ref.location, "src");
+    yield* provide(validateAxmSkillCandidate({
+        ref,
+        packageRoot: ref.location,
+        skillSourcePath,
+    }));
+    const materialized = { skillSrcPath: skillSourcePath };
+    return materialized;
+});
+export const materializeSkillCanonical = (args) => {
+    switch (args.ref.refType) {
+        case "git-hosted":
+            return materializeGitHosted(args.ref, args.sanitizedName, args.fs, args.pathService, args.baseDir, args.layout, args.provide, args.reuse ?? { force: false, lockedVersion: undefined, lockedTreeIntegrity: undefined });
+        case "local":
+            return materializeLocal(args.ref, args.sanitizedName, args.fs, args.pathService, args.baseDir, args.layout, args.provide, args.reuse ?? { force: false, lockedVersion: undefined, lockedTreeIntegrity: undefined });
+        case "registry":
+            return materializeRegistry(args.ref, args.sanitizedName, args.fs, args.pathService, args.baseDir, args.layout, args.provide, args.provideRegistry, args.reuse ?? { force: false, lockedVersion: undefined, lockedTreeIntegrity: undefined });
+        case "workspace":
+            return materializeWorkspace(args.ref, args.pathService, args.baseDir, args.provide);
+    }
+};
+export const ensureSkillAgentArtifact = (args) => Effect.gen(function* () {
+    const agentSkillPath = args.pathService.join(args.targetDir, args.sanitizedName);
+    if (!isPathSafe(args.pathService, args.baseDir, agentSkillPath)) {
+        return;
+    }
+    yield* args.provide(createSymlink({
+        target: args.canonicalSkillSrcPath,
+        link: agentSkillPath,
+    }).pipe(Effect.catch(() => copyExtensionDirectory(args.canonicalSkillSrcPath, agentSkillPath).pipe(
+    // If the copy fallback also fails, surface it — otherwise sync
+    // reports success with no materialized skill artifact.
+    Effect.mapError((cause) => new SkillMaterializationFailed({
+        detail: `Failed to materialize skill artifact at ${agentSkillPath}`,
+        cause,
+    }))))));
+});
+export const removeSkillAgentArtifact = (args) => {
+    const target = args.pathService.join(args.targetDir, args.sanitizedName);
+    return protectWorkspacePath(target).pipe(Effect.andThen(args.fs.remove(target, { recursive: true, force: true })), Effect.mapError((cause) => new SkillMaterializationFailed({
+        detail: `Failed to remove skill artifact at ${target}`,
+        cause,
+    })));
+};
+//# sourceMappingURL=materialization.js.map

package/dist/src/skills/operations/disable.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Disable skill executor — removes agent symlinks but preserves canonical files.
+ *
+ * Materialized artifacts are observed directly. Accepted-resolution rows identify
+ * source content but do not prove that canonical or projected files exist.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { LifecycleFailureAdapter } from "../../failure-adapter.js";
+import type { OperationHandler } from "@agentxm/workspace-operations";
+import type { Operation } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+/**
+ * Disable a skill (remove files but keep settings/lockfile entry).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type DisableSkillOperation = Operation<"disable-skill", {
+    readonly skillName: string;
+}>;
+/**
+ * Disable-skill operation handler.
+ *
+ * Determines lifecycle from the workspace read model, removes observable
+ * materialized targets, and promotes implicit pack members to a direct disabled
+ * preference. Canonical files are preserved for later re-enablement.
+ */
+export declare const disableSkill: OperationHandler<DisableSkillOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | LifecycleFailureAdapter>;
+//# sourceMappingURL=disable.d.ts.map