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

package/dist/src/rules/manager.js

@@ -0,0 +1,492 @@
+/**
+ * Rule manager service.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { stripFileProtocol } from "@agentxm/registry-client";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { RuleDefinitionInvalid, RuleInstallStateMissing } from "./errors.js";
+import { activeContributors, applyProjectionPlans, planAggregateProjection, reconcileManagedRegionFile, projectionGeneration, assertInstructionTargetsSafe, assertInstructionsGitignoreSafe, observeInstructionProjection, reconcileInstructionTargets, resolveInstructionsConfig, } from "@agentxm/workspace-projection";
+import { MARKER_KIND_POINT, MARKER_VERSION, serializeMarker } from "@agentxm/agent-integration";
+import { decodeExtensionNameSync, formatFqn } from "@agentxm/extension-model/unstable/extensions";
+import { canReuseInstalledPackage, materializeExternalPackageWithTreeIntegrity, } from "../extensions/canonical-directory.js";
+import { enabledConfiguredEntries } from "@agentxm/workspace-state";
+import { materializeRegistryPackageWithTreeIntegrity } from "../registry-materialization.js";
+import { computeExtensionPathsForLayout } from "@agentxm/workspace-state";
+import { RuleManager } from "../managers.js";
+import { RULES_REGION_OWNER } from "@agentxm/workspace-projection";
+import { parseFrontmatterEffect } from "@agentxm/extension-content";
+import { computePackageContentHash } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
+import {} from "@agentxm/extension-model/unstable/sources/source-hash";
+import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
+import { MaterializedFileTargetSchema } from "@agentxm/workspace-state";
+import { gitSourceLockFields } from "@agentxm/workspace-state";
+import { SourceHostProviders, WorkspaceCatalog } from "@agentxm/extension-sources";
+import { makeWorkspaceRelativeSourcePath } from "@agentxm/extension-model/unstable/path-types";
+import { removeIfExists } from "@agentxm/workspace-state";
+import { makeWorkspaceRelativePath } from "@agentxm/extension-model/unstable/path-types";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { NO_MATERIALIZATION_OBSERVATION } from "../manager-contract.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { usableAcceptedCanonicalRef } from "@agentxm/workspace-state";
+import { isObservedInstalled } from "@agentxm/workspace-state";
+import { acceptedCanonicalObservation, prepareAcceptedCanonicalTransition, removableAcceptedCanonicalPath, } from "@agentxm/workspace-state";
+import { RULE_BODY_FILENAME, RULE_EXTENSION_DIR, RULE_MANIFEST_FILENAME, RuleManifestSchema, } from "@agentxm/extension-model/unstable/rules/manifest-schema";
+import {} from "@agentxm/extension-model/unstable/extensions/refs/rule";
+const RULES_REGION = "rules";
+const decodeRuleManifest = Schema.decodeUnknownEffect(RuleManifestSchema);
+const decodeMaterializedTarget = Schema.decodeUnknownSync(MaterializedFileTargetSchema);
+const registryRuleLockEntry = (ref, treeIntegrity) => ({
+    type: "registry",
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: ref.source.location,
+    extensionType: "rule",
+    workspaceName: ref.rule.name,
+    owner: ref.owner,
+    name: ref.name,
+    resolvedVersion: decodeVersionSync(ref.version),
+    integrity: Option.getOrElse(ref.integrity, () => ""),
+    sourceName: ref.source.name,
+    publisherBindingId: ref.publisherBindingId,
+    treeIntegrity,
+});
+const gitRuleLockEntry = (ref, contentIdentity, treeIntegrity) => ({
+    ...gitSourceLockFields(ref.source, "rule", ref.rule.name, Option.fromUndefinedOr(ref.sourcePath), ref.gitCommitSha, ref.gitTreeSha, contentIdentity, ref.owner, ref.name, treeIntegrity),
+});
+const localRuleLockEntry = (ref, workspaceRelativeLocalSourcePath, contentIdentity, treeIntegrity) => ({
+    type: "local",
+    sourceType: "local",
+    sourceName: "local",
+    extensionType: "rule",
+    workspaceName: ref.rule.name,
+    packageFormat: "agentxm",
+    packageOwner: ref.owner,
+    packageName: ref.name,
+    path: Option.getOrElse(workspaceRelativeLocalSourcePath, () => ref.source.path),
+    contentIdentity,
+    treeIntegrity,
+});
+const normalizeMarkdown = (content) => content
+    .replace(/\r\n?/g, "\n")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trim();
+export const ruleMaterializationObservation = (managedTarget, instructionItems) => {
+    const agents = Array.from(new Set(instructionItems
+        .filter(({ agentId, health }) => health === "ok" && agentId !== "universal")
+        .map(({ agentId }) => agentId)));
+    return {
+        agents,
+        targets: [
+            {
+                path: managedTarget,
+                ...(agents.length === 0 ? {} : { agentIds: agents }),
+            },
+        ],
+    };
+};
+export const RuleManagerLive = Layer.effect(RuleManager, Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const sources = yield* SourceHostProviders;
+    const catalog = yield* WorkspaceCatalog;
+    const baseDir = ws.baseDir;
+    const workspaceScope = ws.scope;
+    // The workspace facade and the source integration are this layer's own
+    // dependencies; the platform stays in `R` for every member.
+    const provide = (effect) => effect.pipe(Effect.provideService(WorkspaceMutations, ws), Effect.provideService(SourceHostProviders, sources), Effect.provideService(WorkspaceCatalog, catalog));
+    // The instructions region is an aggregate unit: it renders after desired
+    // state commits, so the closure reads back what the render projected.
+    const lastProjection = yield* Ref.make(NO_MATERIALIZATION_OBSERVATION);
+    const materializeFromRegistry = (ref, force) => Effect.gen(function* () {
+        const canonicalPath = computeExtensionPathsForLayout(path.join, ws.layout, ref, RULE_EXTENSION_DIR, ref.name).canonicalPath;
+        const lockedEntry = yield* ws.getLockedRuleEntry(ref.rule.name);
+        const lockedVersion = acceptedRegistryVersionForRef(lockedEntry, ref);
+        const reuse = yield* provide(canReuseInstalledPackage({
+            installedPath: canonicalPath,
+            force,
+            refVersion: ref.version,
+            hasIntegrity: Option.isSome(ref.integrity),
+            ...(lockedVersion === undefined ? {} : { lockedVersion }),
+            existsFailureDetail: (target) => `Failed to check if canonical rule package path exists: ${target}`,
+        }));
+        if (reuse && Option.isSome(lockedEntry)) {
+            const observedTree = yield* provide(computeMaterializedTreeIntegrity(canonicalPath));
+            if (observedTree === lockedEntry.value.treeIntegrity) {
+                return { packageRoot: canonicalPath, treeIntegrity: lockedEntry.value.treeIntegrity };
+            }
+        }
+        const materialized = yield* provide(materializeRegistryPackageWithTreeIntegrity({
+            baseDir,
+            destinationPath: canonicalPath,
+            sourceLocation: ref.source.location,
+            owner: ref.owner,
+            type: "rule",
+            name: ref.name,
+            version: ref.version,
+            integrity: ref.integrity,
+            messages: {
+                integrityMismatchDetail: `Integrity mismatch for rule:${ref.name}@${ref.version}`,
+            },
+        }));
+        return {
+            packageRoot: materialized.canonicalPath,
+            treeIntegrity: materialized.treeIntegrity,
+        };
+    });
+    const materializeFromExternal = (ref) => provide(materializeExternalPackageWithTreeIntegrity({
+        baseDir,
+        canonicalPath: computeExtensionPathsForLayout(path.join, ws.layout, ref, RULE_EXTENSION_DIR, ref.rule.name).canonicalPath,
+        sourceLocation: ref.location,
+        copyFailureCode: "validation",
+        copyFailureDetail: (canonicalPath) => `Failed to copy rule package files to ${canonicalPath}`,
+    }).pipe(Effect.map((materialized) => ({
+        packageRoot: materialized.canonicalPath,
+        treeIntegrity: materialized.treeIntegrity,
+    }))));
+    const materializePackage = (ref, force = false) => Effect.gen(function* () {
+        switch (ref.refType) {
+            case "registry":
+                return yield* materializeFromRegistry(ref, force);
+            case "git-hosted":
+            case "local":
+                return yield* materializeFromExternal(ref);
+            case "workspace": {
+                const expectedPath = computeExtensionPathsForLayout(path.join, ws.layout, ref, RULE_EXTENSION_DIR, ref.name).canonicalPath;
+                if (ref.scope !== ws.scope ||
+                    path.resolve(ref.location) !== path.resolve(expectedPath)) {
+                    return yield* new RuleDefinitionInvalid({
+                        detail: `Invalid workspace rule source location: ${ref.location}`,
+                    });
+                }
+                return {
+                    packageRoot: ref.location,
+                    treeIntegrity: yield* provide(computeMaterializedTreeIntegrity(ref.location)),
+                };
+            }
+        }
+    });
+    const readManifest = (packageRoot) => fs.readFileString(path.join(packageRoot, RULE_MANIFEST_FILENAME)).pipe(Effect.flatMap((content) => Effect.try({
+        try: () => JSON.parse(content),
+        catch: (error) => new RuleDefinitionInvalid({
+            detail: `Failed to parse ${RULE_MANIFEST_FILENAME}`,
+            cause: error,
+        }),
+    })), Effect.flatMap((content) => decodeRuleManifest(content)), Effect.mapError((error) => new RuleDefinitionInvalid({
+        detail: `Failed to read ${RULE_MANIFEST_FILENAME}`,
+        cause: error,
+    })));
+    const sourceFileTarget = () => Effect.gen(function* () {
+        const config = yield* ws.getInstructionsConfig();
+        const resolved = resolveInstructionsConfig(Option.isSome(config) && config.value !== false ? config.value : undefined);
+        const relative = makeWorkspaceRelativePath(path, baseDir, resolved.fileName);
+        if (Option.isNone(relative)) {
+            return yield* new RuleDefinitionInvalid({
+                detail: `Rule instruction source escapes workspace: ${resolved.fileName}`,
+            });
+        }
+        return {
+            relative: relative.value,
+            absolute: path.resolve(baseDir, relative.value),
+        };
+    });
+    const activeInstructions = () => Effect.gen(function* () {
+        const config = yield* ws.getInstructionsConfig();
+        if (Option.isNone(config) || config.value === false) {
+            return Option.none();
+        }
+        return Option.some({
+            config: resolveInstructionsConfig(config.value),
+            agents: yield* ws.getConfiguredAgents(),
+        });
+    });
+    const readRuleBody = (packageRoot) => fs.readFileString(path.join(packageRoot, "src", RULE_BODY_FILENAME)).pipe(Effect.flatMap((content) => parseFrontmatterEffect(content)), Effect.map((parsed) => normalizeMarkdown(parsed.body)), Effect.mapError((error) => new RuleDefinitionInvalid({
+        detail: `Failed to read src/${RULE_BODY_FILENAME}`,
+        cause: error,
+    })));
+    const renderRuleBlock = (args) => {
+        const header = args.manifest.title !== undefined && !args.body.startsWith("#")
+            ? `# ${args.manifest.title}\n\n`
+            : "";
+        const marker = serializeMarker({
+            kind: MARKER_KIND_POINT,
+            v: MARKER_VERSION,
+            pointKind: "rule",
+            ext: `${args.marker}@${args.manifest.version}`,
+        }, { kind: "block", open: "<!--", close: "-->" });
+        return `${marker}\n\n${header}${args.body}`;
+    };
+    const selectRuleContributors = (args) => provide(activeContributors({
+        layout: ws.layout,
+        path,
+        type: "rule",
+        extensionDir: RULE_EXTENSION_DIR,
+        graph: args.graph,
+        locked: args.locked,
+    })).pipe(Effect.flatMap((contributors) => Effect.forEach(contributors, (contributor) => Effect.gen(function* () {
+        const manifest = yield* readManifest(contributor.packageRoot);
+        const body = yield* readRuleBody(contributor.packageRoot);
+        const marker = Option.match(contributor.identityOwner, {
+            onSome: (owner) => formatFqn({
+                owner,
+                type: "rule",
+                name: decodeExtensionNameSync(contributor.node.name),
+            }),
+            onNone: () => formatFqn({ owner: manifest.owner, type: "rule", name: manifest.name }),
+        });
+        return { name: contributor.node.name, marker, manifest, body };
+    }), { concurrency: "unbounded" })), Effect.map((resolved) => {
+        const sorted = [...resolved].sort((a, b) => {
+            const byPriority = (a.manifest.priority ?? 100) - (b.manifest.priority ?? 100);
+            if (byPriority !== 0)
+                return byPriority;
+            return a.marker.localeCompare(b.marker);
+        });
+        return sorted;
+    }));
+    const reconcileRulesRegion = (args) => Effect.gen(function* () {
+        const { target } = args;
+        const contributors = args.input.contributors;
+        const rendered = contributors.map(renderRuleBlock).join("\n\n");
+        const generation = projectionGeneration([
+            "rule-instructions-region-v1",
+            target.relative,
+            RULES_REGION_OWNER,
+            ...contributors.flatMap((contributor) => [
+                contributor.name,
+                contributor.marker,
+                contributor.body,
+                JSON.stringify(contributor.manifest),
+            ]),
+        ]);
+        const instructions = args.instructions;
+        if (args.dryRun !== true && Option.isSome(instructions)) {
+            yield* provide(Effect.gen(function* () {
+                const snapshot = yield* observeInstructionProjection({
+                    workspaceRoot: baseDir,
+                    scope: workspaceScope,
+                    configuredAgents: instructions.value.agents,
+                    config: instructions.value.config,
+                });
+                yield* assertInstructionTargetsSafe(snapshot.status);
+                yield* assertInstructionsGitignoreSafe(baseDir);
+            }));
+        }
+        const reconciliation = yield* provide(reconcileManagedRegionFile({
+            targetPath: target.absolute,
+            displayPath: target.relative,
+            region: RULES_REGION,
+            owner: RULES_REGION_OWNER,
+            rendered,
+            generation,
+            ...(args.dryRun === undefined ? {} : { dryRun: args.dryRun }),
+            writeWhenMissing: true,
+            unsupportedTargetDetail: `Instruction source does not support managed regions: ${target.relative}`,
+        }));
+        const { changed, observedRegion } = reconciliation;
+        const materializedTarget = decodeMaterializedTarget({
+            target: target.relative,
+            mode: "managed-region",
+            region: RULES_REGION,
+        });
+        const projectionUnitObservation = {
+            unitId: "rule:instructions-region",
+            path: `${target.relative}#${RULES_REGION}`,
+            owner: RULES_REGION_OWNER,
+            present: Option.isSome(observedRegion),
+            current: !changed,
+            expectedContributors: contributors.map(({ marker }) => marker),
+        };
+        if (args.dryRun === true) {
+            return {
+                materializedTarget,
+                materialization: ruleMaterializationObservation(target.relative, []),
+                changed,
+                projectionUnitObservation,
+            };
+        }
+        const instructionItems = Option.isSome(instructions)
+            ? (yield* provide(reconcileInstructionTargets({
+                workspaceRoot: baseDir,
+                scope: workspaceScope,
+                configuredAgents: instructions.value.agents,
+                config: instructions.value.config,
+            }))).snapshot.status.items
+            : [];
+        const materialization = ruleMaterializationObservation(target.relative, instructionItems);
+        yield* Ref.set(lastProjection, materialization);
+        return { materializedTarget, materialization, changed, projectionUnitObservation };
+    });
+    const makeRulesProjectionPlan = () => Effect.gen(function* () {
+        const target = yield* sourceFileTarget();
+        const instructions = yield* activeInstructions();
+        const graph = yield* ws.getDesiredStateGraph();
+        const locked = yield* ws.getLockedRules();
+        return yield* planAggregateProjection({
+            unitId: "rule:instructions-region",
+            targetFile: target.absolute,
+            graph,
+            // Rule contributors are decided from desired state alone, so the
+            // instructions region never excludes one.
+            select: (completeGraph) => selectRuleContributors({ graph: completeGraph, locked }).pipe(Effect.map((contributors) => ({ contributors, exclusions: [] }))),
+            adapter: {
+                observe: (input) => reconcileRulesRegion({ input, target, instructions, dryRun: true }).pipe(Effect.map(({ projectionUnitObservation }) => projectionUnitObservation)),
+                apply: (input) => reconcileRulesRegion({ input, target, instructions }).pipe(Effect.asVoid),
+            },
+        });
+    });
+    const projectionPlans = () => makeRulesProjectionPlan().pipe(Effect.map((plan) => [plan]));
+    const applyRulesProjection = projectionPlans().pipe(Effect.flatMap(applyProjectionPlans));
+    const materializeInstall = Effect.fn("RuleManager.materializeInstall")(function* ({ ref, force, }) {
+        const materialized = yield* materializePackage(ref, force === true);
+        const packageRoot = materialized.packageRoot;
+        yield* readManifest(packageRoot);
+        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 RuleDefinitionInvalid({
+                detail: `Local rule source path must stay within the workspace root: ${ref.source.path}`,
+            });
+        }
+        const sourceHash = yield* computePackageContentHash(packageRoot);
+        return {
+            observation: NO_MATERIALIZATION_OBSERVATION,
+            treeIntegrity: Option.some(materialized.treeIntegrity),
+            acquired: Option.some({
+                ref,
+                workspaceRelativeLocalSourcePath,
+                sourceHash,
+                treeIntegrity: materialized.treeIntegrity,
+            }),
+        };
+    });
+    const buildLockEntry = (ref, materialization) => Effect.gen(function* () {
+        const state = Option.getOrUndefined(materialization.pipe(Option.flatMap((facts) => facts.acquired)));
+        switch (ref.refType) {
+            case "registry":
+                return state === undefined
+                    ? yield* new RuleInstallStateMissing({ name: ref.rule.name, kind: "tree-integrity" })
+                    : Option.some(registryRuleLockEntry(ref, state.treeIntegrity));
+            case "git-hosted":
+                return state === undefined
+                    ? yield* new RuleInstallStateMissing({
+                        name: ref.rule.name,
+                        kind: "content-identity",
+                    })
+                    : Option.some(gitRuleLockEntry(ref, state.sourceHash, state.treeIntegrity));
+            case "local":
+                return state === undefined
+                    ? yield* new RuleInstallStateMissing({
+                        name: ref.rule.name,
+                        kind: "content-identity",
+                    })
+                    : Option.some(localRuleLockEntry(ref, state.workspaceRelativeLocalSourcePath, state.sourceHash, state.treeIntegrity));
+            case "workspace":
+                return Option.none();
+        }
+    });
+    // Canonical removal only. The shared operation flow re-renders the region
+    // after settings and lock removal, once the target has left the graph.
+    const withdrawn = {
+        observation: NO_MATERIALIZATION_OBSERVATION,
+        treeIntegrity: Option.none(),
+        acquired: Option.none(),
+    };
+    const materializeUninstall = Effect.fn("RuleManager.materializeUninstall")(function* ({ target, }) {
+        const canonical = yield* provide(acceptedCanonicalObservation({
+            workspace: ws,
+            type: "rule",
+            name: target.name,
+        }));
+        const packageRoot = removableAcceptedCanonicalPath(canonical);
+        if (Option.isSome(packageRoot)) {
+            yield* removeIfExists(fs, packageRoot.value);
+        }
+        return withdrawn;
+    });
+    // Deactivation retains canonical content; the caller updates settings
+    // first, so re-rendering the whole region drops this rule's contribution.
+    const materializeDeactivate = Effect.fn("RuleManager.materializeDeactivate")(() => applyRulesProjection.pipe(Effect.as(withdrawn)));
+    return {
+        type: "rule",
+        projectionPlans,
+        aggregateProjectionObservation: Ref.get(lastProjection),
+        isInstalled: ({ target }) => isObservedInstalled(ws, "rule", target.name).pipe(Effect.withSpan("RuleManager.isInstalled")),
+        materializeInstall,
+        prepareSourceTransition: ({ ref }) => provide(prepareAcceptedCanonicalTransition({
+            workspace: ws,
+            type: "rule",
+            name: ref.rule.name,
+            ref,
+        })),
+        getConfiguredSource: Effect.fn("RuleManager.getConfiguredSource")(function* ({ target }) {
+            const configured = yield* ws.getConfiguredRuleEntries();
+            return Option.fromUndefinedOr(configured[target.name]?.source);
+        }),
+        /**
+         * Every enabled entry's accepted canonical package, read from accepted
+         * resolution rather than re-resolved from source. Materialization
+         * realizes what the workspace already accepted; going back to the
+         * source would put an unrelated configured entry's release age between
+         * an operator and the extension they are authoring.
+         */
+        listMaterializable: Effect.fn("RuleManager.listMaterializable")(function* () {
+            const configured = yield* ws.getConfiguredRuleEntries();
+            const refs = yield* Effect.forEach(enabledConfiguredEntries(configured), ([name]) => provide(usableAcceptedCanonicalRef({ workspace: ws, type: "rule", name }).pipe(Effect.map(Option.filter((ref) => ref.type === "rule")))), { concurrency: "unbounded" });
+            return refs.flatMap((ref) => (Option.isSome(ref) ? [ref.value] : []));
+        }),
+        materializeUninstall,
+        materializeDeactivate,
+        upsertSettingsEntry: Effect.fn("RuleManager.upsertSettingsEntry")(function* ({ ref, versionRange, materialization, }) {
+            const lockEntry = yield* buildLockEntry(ref, materialization);
+            if (Option.isNone(lockEntry)) {
+                yield* ws.setRuleEntry(ref.rule.name, {
+                    source: "workspace",
+                    enabled: true,
+                });
+                return;
+            }
+            if (lockEntry.value.type === "registry") {
+                yield* validateExactResolvedVersion(`rules.${ref.rule.name}.resolvedVersion`, lockEntry.value.resolvedVersion);
+            }
+            yield* ws.setRule({
+                name: ref.rule.name,
+                lockEntry: lockEntry.value,
+                versionRange,
+            });
+        }),
+        removeSettingsEntry: Effect.fn("RuleManager.removeSettingsEntry")(function* ({ target }) {
+            yield* ws.removeRuleSettings(target.name);
+        }),
+        upsertLockfileEntry: Effect.fn("RuleManager.upsertLockfileEntry")(function* ({ ref, materialization, }) {
+            const lockEntry = yield* buildLockEntry(ref, materialization);
+            if (Option.isNone(lockEntry)) {
+                yield* ws.removeRuleLock(ref.rule.name);
+                return;
+            }
+            if (lockEntry.value.type === "registry") {
+                yield* validateExactResolvedVersion(`rules.${ref.rule.name}.resolvedVersion`, lockEntry.value.resolvedVersion);
+            }
+            yield* ws.setRuleLock({
+                name: ref.rule.name,
+                lockEntry: lockEntry.value,
+                versionRange: Option.none(),
+            });
+        }),
+        removeLockfileEntry: Effect.fn("RuleManager.removeLockfileEntry")(function* ({ target }) {
+            yield* ws.removeRuleLock(target.name);
+        }),
+    };
+}));
+//# sourceMappingURL=manager.js.map

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

@@ -0,0 +1,42 @@
+/**
+ * Typed failure family for the skill manager and materialization. Fields are
+ * domain facts; the application error boundary owns rendering, codes, and
+ * suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { AxmSkillCompatibilityUnavailable, AxmSkillIncompatible } from "@agentxm/extension-resolution";
+declare const SkillDefinitionInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SkillDefinitionInvalid";
+} & Readonly<A>;
+/**
+ * A skill source or agent configuration did not validate. `detail` carries
+ * the site's fact sentence verbatim.
+ */
+export declare class SkillDefinitionInvalid extends SkillDefinitionInvalid_base<{
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const SkillMaterializationFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SkillMaterializationFailed";
+} & Readonly<A>;
+/** A skill artifact filesystem step failed; `detail` carries the site's fact sentence. */
+export declare class SkillMaterializationFailed extends SkillMaterializationFailed_base<{
+    readonly detail: string;
+    readonly cause: unknown;
+}> {
+}
+declare const SkillInstallStateMissing_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SkillInstallStateMissing";
+} & Readonly<A>;
+/** A lock entry was requested before install recorded the package state. */
+export declare class SkillInstallStateMissing extends SkillInstallStateMissing_base<{
+    readonly name: string;
+    readonly kind: "tree-integrity" | "content-identity" | "external-resolution";
+}> {
+}
+/** Every failure the skill module constructs. */
+export type SkillManagerError = SkillDefinitionInvalid | SkillMaterializationFailed | SkillInstallStateMissing | AxmSkillCompatibilityUnavailable | AxmSkillIncompatible;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/skills/errors.js

@@ -0,0 +1,21 @@
+/**
+ * Typed failure family for the skill manager and materialization. Fields are
+ * domain facts; the application error boundary owns rendering, codes, and
+ * suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/**
+ * A skill source or agent configuration did not validate. `detail` carries
+ * the site's fact sentence verbatim.
+ */
+export class SkillDefinitionInvalid extends Data.TaggedError("SkillDefinitionInvalid") {
+}
+/** A skill artifact filesystem step failed; `detail` carries the site's fact sentence. */
+export class SkillMaterializationFailed extends Data.TaggedError("SkillMaterializationFailed") {
+}
+/** A lock entry was requested before install recorded the package state. */
+export class SkillInstallStateMissing extends Data.TaggedError("SkillInstallStateMissing") {
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * 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 Path from "effect/Path";
+import * as Layer from "effect/Layer";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { SkillManager } from "../managers.js";
+import { CodingAgentRepository } from "@agentxm/workspace-projection";
+export declare const SkillManagerLive: Layer.Layer<SkillManager, never, FileSystem.FileSystem | Path.Path | WorkspaceMutations | CodingAgentRepository>;
+//# sourceMappingURL=manager.d.ts.map