@agentxm/extension-materialization 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/skills/manager.js

@@ -0,0 +1,339 @@
+/**
+ * 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 { stripFileProtocol } from "@agentxm/registry-client";
+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 "../extensions/materializable-from-disk.js";
+import { enabledConfiguredEntries } from "@agentxm/workspace-state";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { sanitizeName } from "@agentxm/workspace-state";
+import { computePackageContentHash } from "@agentxm/workspace-state";
+import { makeWorkspaceRelativeSourcePath } from "@agentxm/extension-model/unstable/path-types";
+import { removeIfExists } from "@agentxm/workspace-state";
+import { SkillManager } from "../managers.js";
+import { SkillDefinitionInvalid, SkillInstallStateMissing } from "./errors.js";
+import { CodingAgentRepository, applyProjectionPlans, planSingletonProjection, } from "@agentxm/workspace-projection";
+import {} from "@agentxm/extension-model/unstable/agents/types";
+import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
+import { computeSkillSourceHash } from "./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 path = yield* Path.Path;
+    const agentRepo = yield* CodingAgentRepository;
+    const baseDir = ws.baseDir;
+    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,
+            baseDir,
+            layout: ws.layout,
+            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.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,
+                        baseDir,
+                    }),
+                },
+            });
+        }));
+        const sourceHash = ref.refType === "workspace"
+            ? ref.sourceHash
+            : ref.refType === "registry"
+                ? yield* computePackageContentHash(path.dirname(skillSrcPath))
+                : yield* computeSkillSourceHash(skillSrcPath);
+        if (ref.refType !== "workspace" && materialized.treeIntegrity === undefined) {
+            return yield* new SkillInstallStateMissing({
+                name: ref.skill.name,
+                kind: "tree-integrity",
+            });
+        }
+        return {
+            sourceHash: Option.some(sourceHash),
+            treeIntegrity: Option.fromUndefinedOr(ref.refType === "workspace" ? undefined : materialized.treeIntegrity),
+            observation: {
+                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.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({
+                        targetDir: dir,
+                        sanitizedName: sanitized,
+                    }),
+                },
+            });
+        }));
+        if (!retainCanonical) {
+            const canonical = yield* acceptedCanonicalObservation({
+                workspace: ws,
+                type: "skill",
+                name: target.name,
+            });
+            const packageRoot = removableAcceptedCanonicalPath(canonical);
+            if (Option.isSome(packageRoot))
+                yield* removeIfExists(fs, packageRoot.value);
+        }
+        return {
+            sourceHash: Option.none(),
+            treeIntegrity: Option.none(),
+            observation: {
+                agents: [],
+                targets: distinctDirs.map((dir) => ({
+                    path: path.relative(baseDir, path.join(dir, sanitized)),
+                })),
+            },
+        };
+    });
+    const materializeUninstall = makeMaterializeRemoval(false);
+    const materializeDeactivate = makeMaterializeRemoval(true);
+    return {
+        type: "skill",
+        isInstalled: Effect.fn("SkillManager.isInstalled")(function* ({ target, }) {
+            return yield* isObservedInstalled(ws, "skill", target.name);
+        }),
+        materializeInstall,
+        prepareSourceTransition: ({ ref }) => prepareAcceptedCanonicalTransition({
+            workspace: ws,
+            type: "skill",
+            name: ref.skill.name,
+            ref,
+        }),
+        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())
+                : 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, materialization, }) {
+            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 = Option.getOrUndefined(materialization.pipe(Option.flatMap((facts) => facts.sourceHash)));
+            const treeIntegrity = Option.getOrUndefined(materialization.pipe(Option.flatMap((facts) => facts.treeIntegrity)));
+            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, materialization, }) {
+            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 = Option.getOrUndefined(materialization.pipe(Option.flatMap((facts) => facts.sourceHash)));
+            const treeIntegrity = Option.getOrUndefined(materialization.pipe(Option.flatMap((facts) => facts.treeIntegrity)));
+            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,52 @@
+/**
+ * Canonical skill materialization per source kind, plus the per-agent artifact
+ * writers the skill projections apply.
+ *
+ * Every function keeps the platform in `R`; nothing captures a `FileSystem` or
+ * `Path` into a closure or provides one at a leaf.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { SkillMaterializationFailed } from "./errors.js";
+import { type TreeIntegrity } from "@agentxm/workspace-state";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { WorkspaceLayout } from "@agentxm/workspace-state";
+/** 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;
+    /** Where the already-on-disk package to copy lives. */
+    readonly sourcePath: string;
+};
+export interface MaterializedSkillCanonical {
+    readonly skillSrcPath: string;
+    readonly treeIntegrity?: TreeIntegrity;
+}
+export declare const materializeSkillCanonical: (args: {
+    readonly ref: SkillExtensionRef;
+    readonly sanitizedName: string;
+    readonly baseDir: string;
+    readonly layout: WorkspaceLayout;
+    readonly reuse?: Omit<CanonicalReuseContext, "sourcePath">;
+}) => Effect.Effect<{
+    skillSrcPath: string & import("effect/Brand").Brand<"AbsolutePath">;
+    treeIntegrity: string & import("effect/Brand").Brand<"TreeIntegrity">;
+}, import("../index.ts").CanonicalPackageProbeFailed | import("../index.ts").PackageCopyFailed | import("@agentxm/extension-resolution").AxmSkillCompatibilityUnavailable | import("@agentxm/extension-resolution").AxmSkillIncompatible | import("@agentxm/workspace-state").MaterializedTreeInvalid | import("../extensions/canonical-directory.js").CanonicalDirectoryReplacementError, FileSystem.FileSystem | Path.Path> | Effect.Effect<{
+    skillSrcPath: string & import("effect/Brand").Brand<"AbsolutePath">;
+    treeIntegrity: string & import("effect/Brand").Brand<"TreeIntegrity">;
+}, import("../index.ts").CanonicalPackageProbeFailed | import("../index.ts").ArchiveIntegrityMismatch | import("@agentxm/extension-resolution").AxmSkillCompatibilityUnavailable | import("@agentxm/extension-resolution").AxmSkillIncompatible | import("@agentxm/workspace-state").MaterializedTreeInvalid | import("@agentxm/registry-client").RegistryClientFailure | import("../extensions/canonical-directory.js").CanonicalDirectoryReplacementError, FileSystem.FileSystem | Path.Path | import("effect/unstable/http/HttpClient").HttpClient> | Effect.Effect<MaterializedSkillCanonical, import("@agentxm/workspace-state").PathTraversalDetected | import("@agentxm/extension-resolution").AxmSkillCompatibilityUnavailable | import("@agentxm/extension-resolution").AxmSkillIncompatible, FileSystem.FileSystem | Path.Path>;
+export declare const ensureSkillAgentArtifact: (args: {
+    readonly canonicalSkillSrcPath: string;
+    readonly targetDir: string;
+    readonly sanitizedName: string;
+    readonly baseDir: string;
+}) => Effect.Effect<void, SkillMaterializationFailed, FileSystem.FileSystem | Path.Path>;
+export declare const removeSkillAgentArtifact: (args: {
+    readonly targetDir: string;
+    readonly sanitizedName: string;
+}) => Effect.Effect<void, SkillMaterializationFailed, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=materialization.d.ts.map

package/dist/src/skills/materialization.js

@@ -0,0 +1,168 @@
+/**
+ * Canonical skill materialization per source kind, plus the per-agent artifact
+ * writers the skill projections apply.
+ *
+ * Every function keeps the platform in `R`; nothing captures a `FileSystem` or
+ * `Path` into a closure or provides one at a leaf.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import { stripFileProtocol } from "@agentxm/registry-client";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { SkillMaterializationFailed } from "./errors.js";
+import { canReuseExternalPackage, canReuseInstalledPackage, materializeExternalPackageWithTreeIntegrity, } from "../extensions/canonical-directory.js";
+import { materializeRegistryPackageWithTreeIntegrity } from "../registry-materialization.js";
+import { validatePathSafety } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
+import { copyExtensionDirectory } from "../extensions/copy-directory.js";
+import { computeSkillPathsForLayout } from "@agentxm/workspace-state";
+import { isPathSafe } from "@agentxm/extension-model/unstable/path-types";
+import { createSymlink } from "@agentxm/workspace-state";
+import { protectWorkspacePath } from "@agentxm/workspace-transactions";
+import { validateAxmSkillCandidate } from "@agentxm/extension-resolution";
+const replaceExternalCanonical = (baseDir, copyTarget, reuse) => Effect.gen(function* () {
+    const useExisting = yield* canReuseExternalPackage({
+        installedPath: copyTarget,
+        force: reuse.force,
+        existsFailureDetail: (target) => `Failed to check if canonical path exists: ${target}`,
+    });
+    if (useExisting && reuse.lockedTreeIntegrity !== undefined) {
+        const observedTree = yield* computeMaterializedTreeIntegrity(copyTarget);
+        if (observedTree === reuse.lockedTreeIntegrity)
+            return reuse.lockedTreeIntegrity;
+    }
+    const materialized = yield* materializeExternalPackageWithTreeIntegrity({
+        baseDir,
+        canonicalPath: copyTarget,
+        sourceLocation: reuse.sourcePath,
+        copyFailureCode: "internal",
+        copyFailureDetail: (target) => `Failed to copy skill files to ${target}`,
+    });
+    return materialized.treeIntegrity;
+});
+/**
+ * Git-hosted and local skills share one shape: the package is already on disk,
+ * so the canonical tree is either the same directory or a copy of it.
+ */
+const materializeFromDisk = (ref, sanitizedName, baseDir, layout, reuse) => Effect.gen(function* () {
+    const pathService = yield* Path.Path;
+    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* validateAxmSkillCandidate({
+        ref,
+        packageRoot,
+        skillSourcePath: sourceSkillPath,
+    });
+    const isSelfCopy = pathService.resolve(packageRoot) === pathService.resolve(canonicalPath);
+    const treeIntegrity = isSelfCopy
+        ? yield* computeMaterializedTreeIntegrity(canonicalPath)
+        : yield* replaceExternalCanonical(baseDir, canonicalPath, {
+            ...reuse,
+            sourcePath: packageRoot,
+        });
+    return { skillSrcPath, treeIntegrity };
+});
+const materializeRegistry = (ref, sanitizedName, baseDir, layout, reuse) => Effect.scoped(Effect.gen(function* () {
+    const pathService = yield* Path.Path;
+    const source = ref;
+    const { canonicalPath, skillSrcPath } = computeSkillPathsForLayout(pathService.join, layout, source, sanitizedName);
+    yield* validatePathSafety(pathService, baseDir, canonicalPath);
+    const useExisting = yield* 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* computeMaterializedTreeIntegrity(canonicalPath);
+        if (observedTree === reuse.lockedTreeIntegrity) {
+            yield* validateAxmSkillCandidate({
+                ref,
+                packageRoot: canonicalPath,
+                skillSourcePath: skillSrcPath,
+            });
+            return { skillSrcPath, treeIntegrity: reuse.lockedTreeIntegrity };
+        }
+    }
+    const materialized = yield* 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) => validateAxmSkillCandidate({
+            ref,
+            packageRoot: stagingPath,
+            skillSourcePath: pathService.join(stagingPath, "src"),
+        }).pipe(Effect.asVoid),
+    });
+    return { skillSrcPath, treeIntegrity: materialized.treeIntegrity };
+}));
+const materializeWorkspace = (ref, baseDir) => Effect.gen(function* () {
+    const pathService = yield* Path.Path;
+    yield* validatePathSafety(pathService, baseDir, ref.location);
+    const skillSourcePath = pathService.join(ref.location, "src");
+    yield* validateAxmSkillCandidate({
+        ref,
+        packageRoot: ref.location,
+        skillSourcePath,
+    });
+    const materialized = { skillSrcPath: skillSourcePath };
+    return materialized;
+});
+const defaultReuse = {
+    force: false,
+    lockedVersion: undefined,
+    lockedTreeIntegrity: undefined,
+};
+export const materializeSkillCanonical = (args) => {
+    switch (args.ref.refType) {
+        case "git-hosted":
+        case "local":
+            return materializeFromDisk(args.ref, args.sanitizedName, args.baseDir, args.layout, args.reuse ?? defaultReuse);
+        case "registry":
+            return materializeRegistry(args.ref, args.sanitizedName, args.baseDir, args.layout, args.reuse ?? defaultReuse);
+        case "workspace":
+            return materializeWorkspace(args.ref, args.baseDir);
+    }
+};
+export const ensureSkillAgentArtifact = (args) => Effect.gen(function* () {
+    const pathService = yield* Path.Path;
+    const agentSkillPath = pathService.join(args.targetDir, args.sanitizedName);
+    if (!isPathSafe(pathService, args.baseDir, agentSkillPath)) {
+        return;
+    }
+    yield* 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) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const pathService = yield* Path.Path;
+    const target = pathService.join(args.targetDir, args.sanitizedName);
+    return yield* protectWorkspacePath(target).pipe(Effect.andThen(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/skill-artifact.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Skill artifact and install-target semantics shared by the lifecycle and
+ * sync features: agent-target grouping, universal-directory folding, and the
+ * step-artifact shape describing where a skill materializes.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { JobStepArtifact, JobStepArtifactTarget } from "@agentxm/workspace-operations";
+export type InstallableSkillTarget = {
+    readonly agentId: AgentId;
+    readonly targetDir: string;
+};
+export type InstallableSkillTargetLocation = {
+    readonly targetDir: string;
+    readonly agentIds: ReadonlyArray<AgentId>;
+};
+export declare const artifactAgentIdsFromTargets: (targets: ReadonlyArray<InstallableSkillTarget>) => ReadonlyArray<string>;
+export declare const artifactTargetAgentIds: (agentIds: ReadonlyArray<AgentId>) => ReadonlyArray<string>;
+export declare const groupInstallTargetsByDirectory: (targets: ReadonlyArray<InstallableSkillTarget>, workspaceRoot: string) => Effect.Effect<ReadonlyArray<InstallableSkillTargetLocation>, never, FileSystem.FileSystem | Path.Path>;
+export declare const skillArtifactFromTargets: (args: {
+    readonly targets: ReadonlyArray<InstallableSkillTarget>;
+    readonly workspaceRoot: string;
+    readonly sanitizedName: string;
+    readonly scope: JobStepArtifact["scope"];
+    readonly change: JobStepArtifact["change"];
+    readonly workspaceTargets?: ReadonlyArray<JobStepArtifactTarget>;
+}) => Effect.Effect<{
+    targets?: JobStepArtifactTarget[];
+    path: string;
+    scope: "project" | "user";
+    agents: readonly string[];
+    change: "created" | "updated" | "removed" | "unchanged";
+}, never, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=skill-artifact.d.ts.map

package/dist/src/skills/skill-artifact.js

@@ -0,0 +1,70 @@
+/**
+ * Skill artifact and install-target semantics shared by the lifecycle and
+ * sync features: agent-target grouping, universal-directory folding, and the
+ * step-artifact shape describing where a skill materializes.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { UNIVERSAL_SKILLS_DIR, isUniversalSkillsDir, stripTrailingSeparators, } from "@agentxm/extension-model/unstable/extensions/universal-skills-dir";
+const UNIVERSAL_AGENT_ID = "universal";
+export const artifactAgentIdsFromTargets = (targets) => Array.dedupe(targets.map((target) => target.agentId).filter((agentId) => agentId !== UNIVERSAL_AGENT_ID));
+export const artifactTargetAgentIds = (agentIds) => agentIds.filter((agentId) => agentId !== UNIVERSAL_AGENT_ID);
+const normalizedTargetDir = (path, targetDir) => stripTrailingSeparators(path.normalize(targetDir));
+const targetLocationKey = (targetDir, workspaceRoot) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const normalizedDir = normalizedTargetDir(path, targetDir);
+    const normalizedWorkspaceRoot = normalizedTargetDir(path, workspaceRoot);
+    const realWorkspaceRoot = yield* fs.realPath(workspaceRoot).pipe(Effect.map((realPath) => normalizedTargetDir(path, realPath)), Effect.catch(() => Effect.succeed(normalizedWorkspaceRoot)));
+    if (isUniversalSkillsDir(normalizedDir, normalizedWorkspaceRoot) ||
+        isUniversalSkillsDir(normalizedDir, realWorkspaceRoot)) {
+        return normalizedTargetDir(path, path.join(realWorkspaceRoot, UNIVERSAL_SKILLS_DIR));
+    }
+    const parentDir = path.dirname(normalizedDir);
+    const realParentDir = yield* fs.realPath(parentDir).pipe(Effect.map((realPath) => normalizedTargetDir(path, realPath)), Effect.catch(() => Effect.succeed(parentDir)));
+    return normalizedTargetDir(path, path.join(realParentDir, path.basename(normalizedDir)));
+});
+export const groupInstallTargetsByDirectory = (targets, workspaceRoot) => Effect.gen(function* () {
+    const keyedTargets = yield* Effect.forEach(targets, (target) => targetLocationKey(target.targetDir, workspaceRoot).pipe(Effect.map((key) => ({ key, target }))), { concurrency: "unbounded" });
+    const locationsByKey = new Map();
+    for (const { key, target } of keyedTargets) {
+        const existing = locationsByKey.get(key);
+        if (existing === undefined) {
+            locationsByKey.set(key, { targetDir: target.targetDir, agentIds: [target.agentId] });
+            continue;
+        }
+        if (!existing.agentIds.includes(target.agentId)) {
+            existing.agentIds.push(target.agentId);
+        }
+    }
+    return [...locationsByKey.values()];
+});
+export const skillArtifactFromTargets = (args) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const targetLocations = yield* groupInstallTargetsByDirectory(args.targets, args.workspaceRoot);
+    const artifactTargets = [
+        ...(args.workspaceTargets ?? []),
+        ...targetLocations.map((location) => {
+            const agentIds = artifactTargetAgentIds(location.agentIds);
+            return {
+                path: path.relative(args.workspaceRoot, path.join(location.targetDir, args.sanitizedName)),
+                change: args.change,
+                ...(agentIds.length > 0 ? { agentIds } : {}),
+            };
+        }),
+    ];
+    const displayPath = artifactTargets[0]?.path ?? args.sanitizedName;
+    const artifactAgents = artifactAgentIdsFromTargets(args.targets);
+    return {
+        path: displayPath,
+        scope: args.scope,
+        agents: artifactAgents,
+        change: args.change,
+        ...(artifactTargets.length > 0 ? { targets: artifactTargets } : {}),
+    };
+});
+//# sourceMappingURL=skill-artifact.js.map