@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/publisher-binding.js

@@ -1,58 +1,20 @@
 /**
- * Publisher binding trust classification.
+ * Publisher-change plan shaping.
  *
- * A Registry resolution binds a publisher identity. When an operation
- * proposes to replace an already accepted binding for the same configured
- * extension with a different one, that transition is a trust decision a
- * person makes at a prompt: no flag and no unattended mode can approve it.
- * Every route that can replace an accepted binding — root and type update
- * forms, reinstall and re-resolution, and pack closures — classifies the
- * transition from the structured accepted and proposed identities here, so
- * the same rule holds everywhere the transition can occur.
- *
- * A first acceptance is not a change, and an integrity mismatch while
- * reacquiring the same accepted identity remains a hard failure elsewhere.
+ * `@agentxm/extension-resolution` classifies whether a proposed Registry
+ * acceptance replaces an accepted publisher binding. This module turns that
+ * classification into plan vocabulary: the per-step warning, the
+ * interactive-only risk condition, and the blocking condition raised when an
+ * accepted resolution cannot be read at all.
  *
  * @experimental This API is unstable and may change without notice.
  */
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { toExtensionTypePlural } from "@agentxm/extension-model/unstable/extensions/common";
+import { classifyPublisherBindingTransition, describePublisherBindingTransition, publisherTransitionWarning, } from "@agentxm/extension-resolution";
 import { acceptedResolutionRef, WorkspaceMutations } from "@agentxm/workspace-state";
-import { targetFromRef } from "@agentxm/extension-workspace";
 export const PUBLISHER_CHANGE_CONDITION_ID = "publisher-ownership-change";
 const ACCEPTED_RESOLUTION_UNREADABLE_ID = "accepted-resolution-unreadable";
-/** The structured proposal an extension ref makes, when it is a Registry ref. */
-export const registryBindingProposal = (ref) => ref.refType === "registry"
-    ? {
-        extensionType: ref.type,
-        target: targetFromRef(ref).name,
-        owner: ref.owner,
-        packageName: ref.name,
-        version: ref.version,
-        publisherBindingId: ref.publisherBindingId,
-    }
-    : undefined;
-/**
- * Classify one proposed acceptance against the accepted resolution for the
- * same configured target. Only a Registry binding replacing a different
- * Registry binding is a publisher change.
- */
-export const classifyPublisherBindingTransition = (args) => Option.flatMap(args.accepted, (accepted) => accepted.refType === "registry" &&
-    accepted.type === args.proposed.extensionType &&
-    accepted.publisherBindingId !== args.proposed.publisherBindingId
-    ? Option.some({
-        extensionType: args.proposed.extensionType,
-        target: args.proposed.target,
-        owner: args.proposed.owner,
-        packageName: args.proposed.packageName,
-        accepted: accepted.publisherBindingId,
-        proposed: args.proposed.publisherBindingId,
-    })
-    : Option.none());
-const describeTransition = (transition) => `${transition.owner}/${toExtensionTypePlural(transition.extensionType)}/${transition.packageName}`;
-/** The warning a step carries when its acceptance changes publisher. */
-export const publisherTransitionWarning = (transition) => `Publisher identity changed (${transition.accepted} → ${transition.proposed}); confirm only if you trust the current publisher`;
 /**
  * The interactive-only condition a plan carries when any of its steps
  * replaces an accepted publisher binding.
@@ -64,7 +26,7 @@ export const publisherChangeRiskCondition = (transitions) => transitions.length
         consent: "interactive-only",
         id: PUBLISHER_CHANGE_CONDITION_ID,
         detail: `Publisher identity changed for ${transitions
-            .map(describeTransition)
+            .map(describePublisherBindingTransition)
             .join(", ")}; confirm only if you trust the current publisher.`,
     };
 /** Append the publisher-change condition for the given transitions, if any. */

package/dist/src/rules/install/plan.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Installing rules.
+ *
+ * The source grammar a rule request accepts, the discovery that turns it into
+ * refs, and the closure each ref becomes — including who renders the shared
+ * instructions region when more than one rule lands in the same operation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { RuleManager } from "@agentxm/extension-materialization";
+import { type Handle } from "@agentxm/extension-model/unstable/extensions";
+import type { RuleExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/rule";
+import type { Source } from "@agentxm/extension-model/unstable/sources/types";
+import type { VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import { type Plan } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements, type ResolveInstallRequirements, type RuleInstallIntent } from "../../install/vocabulary.js";
+/** A rule source after grammar parsing, before anything is discovered. */
+export interface ParsedRuleInstallRequest {
+    readonly source: Source;
+    readonly names: ReadonlyArray<string>;
+    readonly owner: Option.Option<Handle>;
+    readonly versionRange: Option.Option<VersionRange>;
+}
+/** Read the rule source grammar: which owner, which names, which range. */
+export declare const parseRuleInstallRequest: (source: string) => Effect.Effect<ParsedRuleInstallRequest, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Discover the rules the parsed source offers. */
+export declare const discoverRuleRefs: (request: ParsedRuleInstallRequest) => Effect.Effect<ReadonlyArray<RuleExtensionRef>, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Settle which rules this request installs, or refuse when none matched. */
+export declare const finalizeRuleInstallIntent: (request: ParsedRuleInstallRequest, refs: ReadonlyArray<RuleExtensionRef>) => Effect.Effect<RuleInstallIntent, ExtensionLifecycleFailed>;
+/** The closures a settled rule intent becomes. */
+export declare const planRuleInstall: (intent: RuleInstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | RuleManager>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/src/rules/install/plan.js

@@ -0,0 +1,133 @@
+/**
+ * Installing rules.
+ *
+ * The source grammar a rule request accepts, the discovery that turns it into
+ * refs, and the closure each ref becomes — including who renders the shared
+ * instructions region when more than one rule lands in the same operation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { RuleManager, buildInstallOperation } from "@agentxm/extension-materialization";
+import { parseSourceQualifiedRegistrySourcePatternParts, } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHostProviders, resolveSource } from "@agentxm/extension-sources";
+import { operationPresentation, } from "@agentxm/workspace-operations";
+import { applyPlannedProjections } from "@agentxm/workspace-projection";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { registryLoginSuggestions } from "../../install/registry-login-suggestion.js";
+import { installRefused, } from "../../install/vocabulary.js";
+/** Read the rule source grammar: which owner, which names, which range. */
+export const parseRuleInstallRequest = Effect.fn("InstallExtensions.parseRuleRequest")(function* (source) {
+    const input = source.trim();
+    const parsed = parseSourceQualifiedRegistrySourcePatternParts(input);
+    const resolved = yield* resolveSource(input).pipe(Effect.mapError((error) => installRefused({
+        category: "validation",
+        detail: `Invalid rule source: ${error.message}`,
+        cause: error,
+    })));
+    return {
+        source: resolved,
+        names: parsed?.type === "rules" && parsed.name !== undefined ? [parsed.name] : [],
+        owner: parsed?.type === "rules"
+            ? Option.some(parsed.owner)
+            : resolved.type === "registry"
+                ? resolved.owner
+                : Option.none(),
+        versionRange: resolved.type === "registry" && parsed?.type === "rules"
+            ? Option.fromUndefinedOr(parsed.versionRange)
+            : Option.none(),
+    };
+});
+/** Discover the rules the parsed source offers. */
+export const discoverRuleRefs = Effect.fn("InstallExtensions.discoverRules")(function* (request) {
+    const sources = yield* SourceHostProviders;
+    return yield* sources
+        .find(request.source, {
+        names: request.names,
+        type: "rule",
+        owner: request.owner,
+        versionRange: request.versionRange,
+    })
+        .pipe(Effect.mapError((cause) => installRefused({
+        category: "network",
+        detail: "Rules could not be discovered from the source",
+        cause,
+    })), Effect.map((refs) => refs.filter((ref) => ref.type === "rule")));
+});
+/** Settle which rules this request installs, or refuse when none matched. */
+export const finalizeRuleInstallIntent = Effect.fn("InstallExtensions.finalizeRuleIntent")(function* (request, refs) {
+    if (refs.length === 0) {
+        const suggestions = request.source.type === "registry"
+            ? yield* registryLoginSuggestions([request.source.location.href])
+            : [];
+        return yield* installRefused({
+            category: "not_found",
+            detail: "No rules found in source",
+            suggestions,
+        });
+    }
+    return {
+        refs: refs.map((ref) => ({
+            ref,
+            versionRange: ref.refType === "registry" ? request.versionRange : Option.none(),
+        })),
+    };
+});
+/** The closures a settled rule intent becomes. */
+export const planRuleInstall = Effect.fn("InstallExtensions.planRules")(function* (intent) {
+    const ws = yield* WorkspaceMutations;
+    const ruleManager = yield* RuleManager;
+    // One rule renders the shared instructions region itself; several rules in
+    // one operation defer it so the region is rendered once, from the complete
+    // contributor set.
+    const deferProjections = intent.deferProjections === true || intent.refs.length > 1;
+    const memberSteps = intent.refs.map(({ ref, versionRange }) => buildInstallOperation(ruleManager, {
+        toStepFailure: lifecycleStepFailure,
+        ref,
+        versionRange,
+        skipProjections: deferProjections,
+        installedBefore: ruleManager.isInstalled({
+            target: { type: "rule", name: ref.rule.name },
+        }),
+        buildArtifact: ({ installedBefore }) => Effect.gen(function* () {
+            const materialization = yield* ruleManager.aggregateProjectionObservation;
+            const change = installedBefore ? "updated" : "created";
+            const targets = materialization.targets.map((target) => ({
+                path: target.path,
+                change,
+                ...(target.agentIds === undefined ? {} : { agentIds: target.agentIds }),
+            }));
+            return {
+                path: targets[0]?.path ?? ref.rule.name,
+                scope: ws.scope,
+                agents: materialization.agents,
+                ...(ref.refType === "registry" ? { version: ref.version } : {}),
+                change,
+                ...(targets.length === 0 ? {} : { fileCount: targets.length, targets }),
+            };
+        }),
+    }));
+    const projectionSteps = deferProjections && intent.deferProjections !== true
+        ? [
+            {
+                key: "projection:rule:instructions-region",
+                label: "rule projections",
+                readiness: "ready",
+                run: applyPlannedProjections(ruleManager).pipe(Effect.mapError(lifecycleStepFailure), Effect.as({
+                    result: "success",
+                    message: "Rendered installed Rules from the complete contributor set",
+                })),
+            },
+        ]
+        : [];
+    return {
+        _tag: "Plan",
+        name: "Install rules",
+        description: Option.some("Install rule"),
+        presentation: operationPresentation({ imperative: "install", past: "Installed", gerund: "Installing" }, "rule"),
+        jobs: [{ concurrency: 1, steps: [...memberSteps, ...projectionSteps] }],
+    };
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/rules/uninstall/plan.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Uninstalling a rule.
+ *
+ * A rule that is neither declared nor installed has nothing to remove, so the
+ * request settles to an empty target list rather than a refusal.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { RuleManager } from "@agentxm/extension-materialization";
+import type { Plan } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements } from "../../install/vocabulary.js";
+import type { RuleUninstallIntent } from "../../uninstall/vocabulary.js";
+/** Settle whether this rule has anything to remove. */
+export declare const parseRuleUninstallRequest: (selector: string) => Effect.Effect<RuleUninstallIntent, ExtensionLifecycleFailed, InstallStepRequirements | RuleManager>;
+/** The closures a settled rule removal becomes. */
+export declare const planRuleUninstall: (intent: RuleUninstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | RuleManager>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/src/rules/uninstall/plan.js

@@ -0,0 +1,54 @@
+/**
+ * Uninstalling a rule.
+ *
+ * A rule that is neither declared nor installed has nothing to remove, so the
+ * request settles to an empty target list rather than a refusal.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { RuleManager, buildUninstallOperation } from "@agentxm/extension-materialization";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { installRefused } from "../../install/vocabulary.js";
+import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+/** Settle whether this rule has anything to remove. */
+export const parseRuleUninstallRequest = Effect.fn("UninstallExtensions.parseRuleRequest")(function* (selector) {
+    const ruleManager = yield* RuleManager;
+    const target = { type: "rule", name: selector.trim() };
+    return yield* Effect.gen(function* () {
+        const configured = ruleManager.getConfiguredSource === undefined
+            ? Option.none()
+            : yield* ruleManager.getConfiguredSource({ target });
+        const installed = yield* ruleManager.isInstalled({ target });
+        return Option.isNone(configured) && !installed
+            ? { targets: [] }
+            : { targets: [target] };
+    }).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Rule "${target.name}" declaration could not be read`,
+        cause,
+    })));
+});
+/** The closures a settled rule removal becomes. */
+export const planRuleUninstall = Effect.fn("UninstallExtensions.planRules")(function* (intent) {
+    const ws = yield* WorkspaceMutations;
+    const ruleManager = yield* RuleManager;
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    return {
+        _tag: "Plan",
+        name: "Uninstall rule",
+        description: Option.some("Uninstall rule"),
+        jobs: [
+            {
+                concurrency: 1,
+                steps: intent.targets.map((target) => buildUninstallOperation(ruleManager, retentionPolicy, {
+                    target,
+                    toStepFailure: lifecycleStepFailure,
+                })),
+            },
+        ],
+    };
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/skills/install/bundled.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Installing the official AXM skill that ships inside the CLI.
+ *
+ * The skill's content travels with the executable rather than a registry, so
+ * the application supplies it through an asset port and the lifecycle decides
+ * everything else: that an authored copy is never overwritten, that the
+ * canonical directory is replaced atomically, that the entry is declared as
+ * bundled with no accepted external resolution behind it, and that what ends
+ * up installed is compatible with the CLI that installed it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { type Plan } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements } from "../../install/vocabulary.js";
+/** One file of the bundled skill's source tree. */
+export interface BundledAxmSkillSourceFile {
+    /** Path relative to the skill's `src` directory. */
+    readonly path: string;
+    readonly base64: string;
+}
+/**
+ * The official skill as the running executable carries it, plus the version
+ * of that executable. The generator that produces this belongs to the
+ * application; the lifecycle only reads it.
+ */
+export interface BundledAxmSkillAssetService {
+    readonly manifestJson: string;
+    readonly version: string;
+    readonly cliVersion: string;
+    readonly cliVersionRange: string;
+    readonly sourceFiles: ReadonlyArray<BundledAxmSkillSourceFile>;
+    /** The CLI version this invocation is running. */
+    readonly runningCliVersion: string;
+}
+declare const BundledAxmSkillAsset_base: ServiceMap.ServiceClass<BundledAxmSkillAsset, "@agentxm/extension-lifecycle/skills/BundledAxmSkillAsset", BundledAxmSkillAssetService>;
+export declare class BundledAxmSkillAsset extends BundledAxmSkillAsset_base {
+}
+export declare const BUNDLED_AXM_SKILL_AUTHORED_BLOCKER = "The official AXM skill is workspace-authored; bundled recovery will not overwrite its in-flight source.";
+export type BundledAxmSkillReadiness = {
+    readonly readiness: "ready";
+    readonly canonicalPath: string;
+} | {
+    readonly readiness: "error";
+    readonly canonicalPath: string;
+    readonly errorMessage: string;
+};
+/** Where the bundled skill's canonical package sits. */
+export declare const bundledAxmSkillCanonicalPath: (ws: ServiceMap.Service.Shape<typeof WorkspaceMutations>, path: Path.Path) => string;
+/** Whether bundled recovery may write, or must preserve an authored copy. */
+export declare const inspectBundledAxmSkillReadiness: Effect.Effect<{
+    readiness: "error";
+    canonicalPath: string;
+    errorMessage: string;
+} | {
+    readiness: "ready";
+    canonicalPath: string;
+    errorMessage?: never;
+}, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure, Path.Path | WorkspaceMutations>;
+/** Install the embedded official AXM skill as one rollback-safe transition. */
+export declare const installBundledAxmSkill: Effect.Effect<void, ExtensionLifecycleFailed, InstallStepRequirements | BundledAxmSkillAsset>;
+/**
+ * The single closure a bundled install becomes: one step that replaces the
+ * canonical package and declares it, refused up front when an authored copy
+ * of the official skill is in flight.
+ */
+export declare const planBundledAxmSkillInstall: Effect.Effect<Plan<InstallStepRequirements | BundledAxmSkillAsset>, ExtensionLifecycleFailed, InstallStepRequirements>;
+export {};
+//# sourceMappingURL=bundled.d.ts.map

package/dist/src/skills/install/bundled.js

@@ -0,0 +1,244 @@
+/**
+ * Installing the official AXM skill that ships inside the CLI.
+ *
+ * The skill's content travels with the executable rather than a registry, so
+ * the application supplies it through an asset port and the lifecycle decides
+ * everything else: that an authored copy is never overwritten, that the
+ * canonical directory is replaced atomically, that the entry is declared as
+ * bundled with no accepted external resolution behind it, and that what ends
+ * up installed is compatible with the CLI that installed it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { ensureSkillAgentArtifact, replaceCanonicalDirectory, } from "@agentxm/extension-materialization";
+import { AXM_SKILL_CLI_VERSION_METADATA_KEY, AXM_SKILL_CLI_VERSION_RANGE_METADATA_KEY, AXM_SKILL_FQN, evaluateAxmSkillCompatibility, } from "@agentxm/extension-resolution";
+import { operationPresentation, } from "@agentxm/workspace-operations";
+import { CodingAgentRepository } from "@agentxm/workspace-projection";
+import { WorkspaceMutations, sanitizeName } from "@agentxm/workspace-state";
+import { runWorkspaceTransaction } from "@agentxm/workspace-transactions";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { installRefused } from "../../install/vocabulary.js";
+export class BundledAxmSkillAsset extends ServiceMap.Service()("@agentxm/extension-lifecycle/skills/BundledAxmSkillAsset") {
+}
+const BUNDLED_AXM_SKILL_NAME = sanitizeName("axm");
+export const BUNDLED_AXM_SKILL_AUTHORED_BLOCKER = "The official AXM skill is workspace-authored; bundled recovery will not overwrite its in-flight source.";
+/** Where the bundled skill's canonical package sits. */
+export const bundledAxmSkillCanonicalPath = (ws, path) => path.join(ws.layout.acquiredRoot, "agentxm", "@agentxm", "skills", "axm");
+/** Whether bundled recovery may write, or must preserve an authored copy. */
+export const inspectBundledAxmSkillReadiness = Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const configured = yield* ws.getConfiguredSkillEntries();
+    const existing = configured[BUNDLED_AXM_SKILL_NAME];
+    const canonicalPath = bundledAxmSkillCanonicalPath(ws, path);
+    return existing?.source === "workspace" && existing.origin !== "bundled"
+        ? {
+            readiness: "error",
+            canonicalPath,
+            errorMessage: BUNDLED_AXM_SKILL_AUTHORED_BLOCKER,
+        }
+        : { readiness: "ready", canonicalPath };
+});
+const writeFailed = (filePath) => (cause) => installRefused({
+    category: "internal",
+    detail: `Failed to write bundled AXM skill file: ${filePath}`,
+    cause,
+});
+const materializeBundledAxmSkill = Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const agentRepo = yield* CodingAgentRepository;
+    const asset = yield* BundledAxmSkillAsset;
+    const canonicalPath = bundledAxmSkillCanonicalPath(ws, path);
+    const skillSrcPath = path.join(canonicalPath, "src");
+    yield* replaceCanonicalDirectory({
+        baseDir: ws.baseDir,
+        canonicalPath,
+        populate: (stagingPath) => {
+            const stagingSrcPath = path.join(stagingPath, "src");
+            const skillJsonPath = path.join(stagingPath, "skill.json");
+            return Effect.gen(function* () {
+                yield* fs
+                    .makeDirectory(stagingSrcPath, { recursive: true })
+                    .pipe(Effect.mapError(writeFailed(stagingSrcPath)));
+                yield* fs
+                    .writeFileString(skillJsonPath, asset.manifestJson)
+                    .pipe(Effect.mapError(writeFailed(skillJsonPath)));
+                yield* Effect.forEach(asset.sourceFiles, (sourceFile) => {
+                    const destination = path.join(stagingSrcPath, sourceFile.path);
+                    return fs
+                        .makeDirectory(path.dirname(destination), { recursive: true })
+                        .pipe(Effect.andThen(fs.writeFile(destination, Buffer.from(sourceFile.base64, "base64"))), Effect.mapError(writeFailed(destination)));
+                }, { concurrency: "unbounded", discard: true });
+            });
+        },
+    });
+    const configuredAgents = yield* agentRepo.getConfiguredAgents();
+    const resolvedAgents = yield* Effect.forEach(configuredAgents, (agent) => agent
+        .resolveEffectiveSkillsDir({ workspaceRoot: ws.baseDir })
+        .pipe(Effect.map((outcome) => ({ agentId: agent.id, outcome }))), { concurrency: "unbounded" });
+    const misconfigured = resolvedAgents.filter(({ outcome }) => outcome._tag === "misconfigured");
+    if (misconfigured.length > 0) {
+        return yield* installRefused({
+            category: "validation",
+            detail: "One or more configured agents have invalid skills directory settings",
+        });
+    }
+    const distinctTargets = [
+        ...new Set(resolvedAgents.flatMap(({ outcome }) => outcome._tag === "supported" ? [path.normalize(outcome.dir)] : [])),
+    ];
+    yield* Effect.forEach(distinctTargets, (targetDir) => ensureSkillAgentArtifact({
+        canonicalSkillSrcPath: skillSrcPath,
+        targetDir,
+        sanitizedName: BUNDLED_AXM_SKILL_NAME,
+        baseDir: ws.baseDir,
+    }), { concurrency: "unbounded" });
+    yield* ws.setSkillEntry(BUNDLED_AXM_SKILL_NAME, {
+        source: "workspace",
+        enabled: true,
+        origin: "bundled",
+    });
+    yield* ws.removeSkillLock(BUNDLED_AXM_SKILL_NAME);
+});
+/** Install the embedded official AXM skill as one rollback-safe transition. */
+export const installBundledAxmSkill = Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const agentRepo = yield* CodingAgentRepository;
+    const asset = yield* BundledAxmSkillAsset;
+    const readiness = yield* inspectBundledAxmSkillReadiness.pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Bundled AXM skill readiness could not be inspected",
+        cause,
+    })));
+    if (readiness.readiness === "error") {
+        return yield* installRefused({
+            category: "conflict",
+            detail: BUNDLED_AXM_SKILL_AUTHORED_BLOCKER,
+            recover: "Preserve the authored skill and inspect executable compatibility guidance",
+            cmd: "axm help upgrade",
+        });
+    }
+    const configuredAgents = yield* agentRepo.getConfiguredAgents().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Configured agents could not be read",
+        cause,
+    })));
+    const targetDirectories = yield* Effect.forEach(configuredAgents, (agent) => agent
+        .resolveEffectiveSkillsDir({ workspaceRoot: ws.baseDir })
+        .pipe(Effect.map((outcome) => outcome._tag === "supported"
+        ? [path.join(path.normalize(outcome.dir), BUNDLED_AXM_SKILL_NAME)]
+        : [])), { concurrency: "unbounded" }).pipe(Effect.map((paths) => paths.flat()), Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Configured skill placement could not be resolved",
+        cause,
+    })));
+    yield* runWorkspaceTransaction({
+        targets: [readiness.canonicalPath, ...targetDirectories],
+        transition: materializeBundledAxmSkill,
+        validate: () => Effect.gen(function* () {
+            const configured = yield* ws.getConfiguredSkillEntries();
+            const installedEntry = configured[BUNDLED_AXM_SKILL_NAME];
+            if (installedEntry?.source !== "workspace" || installedEntry.origin !== "bundled") {
+                return yield* installRefused({
+                    category: "internal",
+                    detail: "Bundled AXM skill did not retain its bundled source authority",
+                });
+            }
+            const locked = yield* ws.getLockedSkill(BUNDLED_AXM_SKILL_NAME);
+            if (Option.isSome(locked)) {
+                return yield* installRefused({
+                    category: "internal",
+                    detail: "Bundled AXM skill retained a superseded accepted external resolution",
+                });
+            }
+            // The installed skill must be usable by the executable that installed
+            // it, so the same compatibility policy runs inside the transaction.
+            const compatibility = evaluateAxmSkillCompatibility({
+                cliVersion: asset.runningCliVersion,
+                skill: {
+                    manifestVersion: asset.version,
+                    source: `bundled:@agentxm/skills/axm@${asset.version}`,
+                    metadata: {
+                        [AXM_SKILL_CLI_VERSION_METADATA_KEY]: asset.cliVersion,
+                        [AXM_SKILL_CLI_VERSION_RANGE_METADATA_KEY]: asset.cliVersionRange,
+                    },
+                },
+            });
+            if (compatibility.status === "incompatible") {
+                return yield* installRefused({
+                    category: "internal",
+                    detail: compatibility.detail ??
+                        "Bundled AXM skill remained incompatible after workspace installation",
+                    ...(compatibility.recovery.nextAction === null
+                        ? {}
+                        : { cmd: compatibility.recovery.nextAction }),
+                });
+            }
+        }),
+    }).pipe(Effect.mapError((cause) => cause instanceof ExtensionLifecycleFailed
+        ? cause
+        : installRefused({
+            category: "internal",
+            detail: "Bundled AXM skill installation did not complete",
+            cause,
+        })), Effect.asVoid);
+});
+/**
+ * The single closure a bundled install becomes: one step that replaces the
+ * canonical package and declares it, refused up front when an authored copy
+ * of the official skill is in flight.
+ */
+export const planBundledAxmSkillInstall = Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const readiness = yield* inspectBundledAxmSkillReadiness.pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Bundled AXM skill readiness could not be inspected",
+        cause,
+    })));
+    const artifact = {
+        path: readiness.canonicalPath,
+        scope: ws.scope,
+        change: "updated",
+    };
+    const step = readiness.readiness === "error"
+        ? {
+            key: "bundled-axm-skill-authored",
+            readiness: "error",
+            errorMessage: readiness.errorMessage,
+            label: AXM_SKILL_FQN,
+            artifact,
+        }
+        : {
+            key: "bundled-axm-skill",
+            readiness: "ready",
+            label: AXM_SKILL_FQN,
+            artifact,
+            run: installBundledAxmSkill.pipe(Effect.mapError(lifecycleStepFailure), Effect.as({
+                result: "success",
+                message: "Installed the bundled AXM skill",
+                artifact,
+            })),
+        };
+    return {
+        _tag: "Plan",
+        name: "Install bundled AXM skill",
+        description: Option.some("Install the embedded compatible official AXM skill"),
+        presentation: operationPresentation({ imperative: "install", past: "Installed", gerund: "Installing" }, "skill"),
+        failureSuggestions: [
+            {
+                description: "Preserve the authored skill and inspect executable compatibility guidance",
+                cmd: "axm help upgrade",
+            },
+        ],
+        jobs: [{ concurrency: 1, steps: [step] }],
+    };
+});
+//# sourceMappingURL=bundled.js.map