@agentxm/extension-lifecycle 0.29.4 → 0.30.2

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

@@ -0,0 +1,29 @@
+import * as Option from "effect/Option";
+const gitHostedSourceOrigin = (ref) => {
+    const source = ref.source;
+    switch (source.type) {
+        case "github":
+        case "gitlab":
+        case "bitbucket":
+            return `${source.url.origin}/${source.owner}/${source.repo}`;
+        case "azurerepos":
+            return `${source.url.origin}/${source.organization}/${source.project}/_git/${source.repo}`;
+        case "git":
+            return source.url.href;
+    }
+};
+export const gitHostedSkillArtifactSource = (ref) => {
+    if (ref.refType !== "git-hosted")
+        return undefined;
+    const gitTreeHash = ref.gitTreeSha;
+    const gitRef = Option.getOrUndefined(ref.source.ref);
+    const directory = ref.sourcePath === undefined || ref.sourcePath.length === 0 ? "." : ref.sourcePath;
+    return {
+        type: ref.source.type,
+        origin: gitHostedSourceOrigin(ref),
+        ...(gitRef !== undefined ? { ref: gitRef } : {}),
+        directory,
+        gitTreeHash,
+    };
+};
+//# sourceMappingURL=artifact.js.map

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

@@ -1,3 +1,4 @@
+import { renderAxmSkillRecovery } from "@agentxm/cli-maintenance/official-skill/adapters/cli";
 /**
  * Installing the official AXM skill that ships inside the CLI.
  *
@@ -16,7 +17,7 @@ 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 { AXM_SKILL_CLI_VERSION_METADATA_KEY, AXM_SKILL_CLI_VERSION_RANGE_METADATA_KEY, AXM_SKILL_FQN, evaluateAxmSkillCompatibility, } from "@agentxm/cli-maintenance/official-skill/domain";
 import { operationPresentation, } from "@agentxm/workspace-operations";
 import { CodingAgentRepository } from "@agentxm/workspace-projection";
 import { WorkspaceMutations, sanitizeName } from "@agentxm/workspace-state";
@@ -173,13 +174,12 @@ export const installBundledAxmSkill = Effect.gen(function* () {
                 },
             });
             if (compatibility.status === "incompatible") {
+                const recovery = renderAxmSkillRecovery(compatibility.recovery);
                 return yield* installRefused({
                     category: "internal",
                     detail: compatibility.detail ??
                         "Bundled AXM skill remained incompatible after workspace installation",
-                    ...(compatibility.recovery.nextAction === null
-                        ? {}
-                        : { cmd: compatibility.recovery.nextAction }),
+                    ...(recovery.nextAction === null ? {} : { cmd: recovery.nextAction }),
                 });
             }
         }),

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

@@ -21,12 +21,11 @@ import { type PackageUrlParts } from "@agentxm/extension-model/unstable/packagin
 import type { Source } from "@agentxm/extension-model/unstable/sources/types";
 import type { VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
 import { type SourceResolutionFailure } from "@agentxm/extension-sources";
-import { type Plan } from "@agentxm/workspace-operations";
+import { type Plan, type PlannedJobStep } from "@agentxm/workspace-operations";
 import type { ExtensionLifecycleFailed } from "../../errors.js";
 import type { RegistryLookupProbe } from "../../install/registry-source-resolution.js";
-import type { ExtensionSelectionCancelled } from "../../install/selection-interaction.js";
-import { ExtensionSelectionInteraction } from "../../install/selection-interaction.js";
 import { type InstallStepRequirements, type ResolveInstallRequirements, type SkillInstallIntent } from "../../install/vocabulary.js";
+import { SkillSelectionInteraction, type SkillSelectionFailure } from "../application/index.js";
 /** A skill source after grammar parsing, before anything is discovered. */
 export interface ParsedSkillInstallRequest {
     readonly source: Source;
@@ -66,7 +65,19 @@ export declare const parseSkillInstallRequest: (args: SkillInstallArgs) => Effec
 /** Discover the skills the parsed source offers, or refuse when it has none. */
 export declare const discoverSkillRefs: (request: ParsedSkillInstallRequest) => Effect.Effect<ReadonlyArray<SkillExtensionRef>, ExtensionLifecycleFailed, ResolveInstallRequirements>;
 /** Settle which of the discovered skills this request installs. */
-export declare const finalizeSkillInstallIntent: (request: ParsedSkillInstallRequest, discovered: ReadonlyArray<SkillExtensionRef>) => Effect.Effect<SkillInstallIntent, ExtensionLifecycleFailed | ExtensionSelectionCancelled, ExtensionSelectionInteraction>;
+export declare const finalizeSkillInstallIntent: (request: ParsedSkillInstallRequest, discovered: ReadonlyArray<SkillExtensionRef>) => Effect.Effect<SkillInstallIntent, ExtensionLifecycleFailed | SkillSelectionFailure, SkillSelectionInteraction>;
+/** Installing declares intent; an update advances the resolution of existing intent. */
+export type SkillInstallationStepInput = {
+    readonly ref: SkillExtensionRef;
+    readonly force: boolean;
+} & ({
+    readonly operation: "install";
+    readonly versionRange: Option.Option<VersionRange>;
+} | {
+    readonly operation: "update";
+});
+/** One skill-owned application step, shared by install and selective update. */
+export declare const planSkillInstallationStep: (input: SkillInstallationStepInput) => Effect.Effect<PlannedJobStep<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | SkillManager | FileSystem.FileSystem | Path.Path | HttpClient.HttpClient>;
 /** The closures a settled skill intent becomes. */
 export declare const planSkillInstall: (intent: SkillInstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | SkillManager | FileSystem.FileSystem | Path.Path | HttpClient.HttpClient>;
 //# sourceMappingURL=plan.d.ts.map

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

@@ -17,7 +17,8 @@ import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
-import { SkillManager, artifactAgentIdsFromTargets, artifactTargetAgentIds, buildInstallOperation, computeSkillSourceHash, groupInstallTargetsByDirectory, } from "@agentxm/extension-materialization";
+import { SkillManager, artifactAgentIdsFromTargets, artifactTargetAgentIds, computeSkillSourceHash, groupInstallTargetsByDirectory, } from "@agentxm/extension-materialization";
+import { buildInstallOperation } from "@agentxm/workspace-reconciliation";
 import { matchesReleaseAgeExcludePattern, } from "@agentxm/extension-model/unstable/extensions";
 import { PackageUrlPartsSchema, formatPackageDisplay, } from "@agentxm/extension-model/unstable/packaging";
 import { parseInputPattern, } from "@agentxm/extension-model/unstable/sources/parser";
@@ -27,11 +28,10 @@ import { createRegistryClient } from "@agentxm/registry-client";
 import { operationPresentation, } from "@agentxm/workspace-operations";
 import { CodingAgentRepository } from "@agentxm/workspace-projection";
 import { WorkspaceMutations, sanitizeName } from "@agentxm/workspace-state";
-import { gitHostedSkillArtifactSource } from "../operations/install.js";
+import { gitHostedSkillArtifactSource } from "./artifact.js";
 import { lifecycleStepFailure } from "../../step-failure.js";
-import { ExtensionSelectionInteraction } from "../../install/selection-interaction.js";
 import { installRefused, } from "../../install/vocabulary.js";
-import { determineSkillsToInstall } from "./selection.js";
+import { determineSkillsToInstall, SkillSelectionInteraction, } from "../application/index.js";
 import { resolveSkillInstallSource } from "./source.js";
 const noSkillsFoundHowToFix = (source) => {
     if (source.type === "registry") {
@@ -316,104 +316,121 @@ const targetChangeBeforeInstall = (args) => Effect.gen(function* () {
     const exists = yield* fs.exists(args.linkPath).pipe(Effect.catch(() => Effect.succeed(false)));
     return exists ? "updated" : "created";
 });
-/** The closures a settled skill intent becomes. */
-export const planSkillInstall = Effect.fn("InstallExtensions.planSkills")(function* (intent) {
+/** One skill-owned application step, shared by install and selective update. */
+export const planSkillInstallationStep = (input) => Effect.gen(function* () {
     const ws = yield* WorkspaceMutations;
     const skillManager = yield* SkillManager;
     const agentRepo = yield* CodingAgentRepository;
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const steps = yield* Effect.forEach(intent.skillsToInstall, (entry) => Effect.gen(function* () {
-        const ref = entry.ref;
-        const previousLockEntry = yield* ws
-            .getLockedSkill(ref.skill.name)
-            .pipe(Effect.catch(() => Effect.succeed(Option.none())));
-        const previousVersion = Option.match(previousLockEntry, {
-            onNone: () => undefined,
-            onSome: previousResolvedVersion,
-        });
-        const { skillSrcPath } = yield* ws.getSkillDir(ref.skill.name, skillPathSourceFor(ref));
-        const sourceHashBeforeInstall = Option.match(previousLockEntry, {
-            onNone: () => undefined,
-            onSome: previousSourceHash,
-        }) ??
-            (yield* Effect.gen(function* () {
-                const exists = yield* fs
-                    .exists(skillSrcPath)
-                    .pipe(Effect.catch(() => Effect.succeed(false)));
-                if (!exists)
-                    return undefined;
-                return yield* computeSkillSourceHash(skillSrcPath);
-            }));
-        const configuredAgents = yield* agentRepo.getMaterializationAgents();
-        const resolvedAgents = yield* Effect.forEach(configuredAgents, (agent) => agent
-            .resolveEffectiveSkillsDir({ workspaceRoot: ws.baseDir })
-            .pipe(Effect.map((outcome) => ({ agentId: agent.id, outcome }))), { concurrency: "unbounded" });
-        const sanitizedName = sanitizeName(ref.skill.name);
-        const installableTargets = resolvedAgents.flatMap(({ agentId, outcome }) => outcome._tag === "supported"
-            ? [{ agentId, targetDir: path.normalize(outcome.dir) }]
-            : []);
-        const targetLocations = yield* groupInstallTargetsByDirectory(installableTargets, ws.baseDir);
-        const artifactAgents = artifactAgentIdsFromTargets(installableTargets);
-        const targets = yield* Effect.forEach(targetLocations, (location) => {
-            const linkPath = path.join(location.targetDir, sanitizedName);
-            return targetChangeBeforeInstall({
-                linkPath,
-                canonicalSkillSrcPath: skillSrcPath,
-            }).pipe(Effect.map((change) => {
-                const agentIds = artifactTargetAgentIds(location.agentIds);
-                return {
-                    path: path.relative(ws.baseDir, linkPath),
-                    change,
-                    ...(agentIds.length > 0 ? { agentIds } : {}),
-                };
-            }));
-        }, { concurrency: "unbounded" });
-        const firstTarget = targets[0];
-        const rawDisplayPath = firstTarget === undefined ? path.relative(ws.baseDir, skillSrcPath) : firstTarget.path;
-        const version = ref.refType === "registry" ? ref.version : undefined;
-        const installedBefore = yield* skillManager
-            .isInstalled({ target: { type: "skill", name: ref.skill.name } })
-            .pipe(Effect.catch(() => Effect.succeed(false)));
-        const releaseAgeWarning = yield* brandNewReleaseAgeWarning(ref, installedBefore);
-        return withPlanWarning(buildInstallOperation(skillManager, {
-            toStepFailure: lifecycleStepFailure,
-            ref,
-            versionRange: entry.versionRange,
-            force: intent.force === true,
-            installedBefore: Effect.succeed(installedBefore),
-            buildArtifact: ({ installedBefore }) => Effect.gen(function* () {
-                const fileCount = yield* countFiles(fs, path, skillSrcPath);
-                const currentSourceHash = yield* computeSkillSourceHash(skillSrcPath);
-                const sameVersion = previousVersion === version;
-                const sameSource = sourceHashBeforeInstall === currentSourceHash;
-                const fallbackChange = !installedBefore
-                    ? "created"
-                    : sameVersion && sameSource
-                        ? "unchanged"
-                        : "updated";
-                const artifactChange = artifactChangeFromTargets(fallbackChange, targets);
-                const sourceDetails = gitHostedSkillArtifactSource(ref);
-                return {
-                    path: rawDisplayPath.length === 0 ? "." : rawDisplayPath,
-                    scope: ws.scope,
-                    agents: artifactAgents,
-                    ...(version !== undefined ? { version } : {}),
-                    change: artifactChange,
-                    ...(previousVersion !== undefined && previousVersion !== version
-                        ? { previousVersion }
-                        : {}),
-                    fileCount,
-                    ...(targets.length > 0 ? { targets } : {}),
-                    ...(sourceDetails !== undefined ? { source: sourceDetails } : {}),
-                };
-            }),
-        }), releaseAgeWarning);
-    }).pipe(Effect.mapError((cause) => installRefused({
-        category: "internal",
-        detail: `Skill install planning failed for ${entry.ref.skill.name}`,
-        cause,
-    }))), { concurrency: 1 });
+    const ref = input.ref;
+    const previousLockEntry = yield* ws
+        .getLockedSkill(ref.skill.name)
+        .pipe(Effect.catch(() => Effect.succeed(Option.none())));
+    const previousVersion = Option.match(previousLockEntry, {
+        onNone: () => undefined,
+        onSome: previousResolvedVersion,
+    });
+    const { skillSrcPath } = yield* ws.getSkillDir(ref.skill.name, skillPathSourceFor(ref));
+    const sourceHashBeforeInstall = Option.match(previousLockEntry, {
+        onNone: () => undefined,
+        onSome: previousSourceHash,
+    }) ??
+        (yield* Effect.gen(function* () {
+            const exists = yield* fs
+                .exists(skillSrcPath)
+                .pipe(Effect.catch(() => Effect.succeed(false)));
+            if (!exists)
+                return undefined;
+            return yield* computeSkillSourceHash(skillSrcPath);
+        }));
+    const configuredAgents = yield* agentRepo.getMaterializationAgents();
+    const resolvedAgents = yield* Effect.forEach(configuredAgents, (agent) => agent
+        .resolveEffectiveSkillsDir({ workspaceRoot: ws.baseDir })
+        .pipe(Effect.map((outcome) => ({ agentId: agent.id, outcome }))), { concurrency: "unbounded" });
+    const unknownAgents = yield* agentRepo.getUnknownConfiguredAgentIds();
+    const skippedAgents = resolvedAgents.flatMap(({ agentId, outcome }) => outcome._tag === "unsupported" || outcome._tag === "disabled"
+        ? [`${agentId}: ${outcome.reason}`]
+        : []);
+    const warnings = [
+        ...(unknownAgents.length === 0
+            ? []
+            : [`Skipping unknown configured agents: ${unknownAgents.join(", ")}`]),
+        ...(skippedAgents.length === 0
+            ? []
+            : [`Skipping non-installable configured agents: ${skippedAgents.join(", ")}`]),
+    ];
+    const sanitizedName = sanitizeName(ref.skill.name);
+    const installableTargets = resolvedAgents.flatMap(({ agentId, outcome }) => outcome._tag === "supported" ? [{ agentId, targetDir: path.normalize(outcome.dir) }] : []);
+    const targetLocations = yield* groupInstallTargetsByDirectory(installableTargets, ws.baseDir);
+    const artifactAgents = artifactAgentIdsFromTargets(installableTargets);
+    const targets = yield* Effect.forEach(targetLocations, (location) => {
+        const linkPath = path.join(location.targetDir, sanitizedName);
+        return targetChangeBeforeInstall({
+            linkPath,
+            canonicalSkillSrcPath: skillSrcPath,
+        }).pipe(Effect.map((change) => {
+            const agentIds = artifactTargetAgentIds(location.agentIds);
+            return {
+                path: path.relative(ws.baseDir, linkPath),
+                change,
+                ...(agentIds.length > 0 ? { agentIds } : {}),
+            };
+        }));
+    }, { concurrency: "unbounded" });
+    const firstTarget = targets[0];
+    const rawDisplayPath = firstTarget === undefined ? path.relative(ws.baseDir, skillSrcPath) : firstTarget.path;
+    const version = ref.refType === "registry" ? ref.version : undefined;
+    const installedBefore = yield* skillManager
+        .isInstalled({ target: { type: "skill", name: ref.skill.name } })
+        .pipe(Effect.catch(() => Effect.succeed(false)));
+    const releaseAgeWarning = input.operation === "install"
+        ? yield* brandNewReleaseAgeWarning(ref, installedBefore)
+        : Option.none();
+    const step = withPlanWarning(buildInstallOperation(skillManager, {
+        toStepFailure: lifecycleStepFailure,
+        ref,
+        ...(input.operation === "install"
+            ? { declaration: { name: ref.skill.name, versionRange: input.versionRange } }
+            : {}),
+        force: input.force,
+        installedBefore: Effect.succeed(installedBefore),
+        buildArtifact: ({ installedBefore }) => Effect.gen(function* () {
+            const fileCount = yield* countFiles(fs, path, skillSrcPath);
+            const currentSourceHash = yield* computeSkillSourceHash(skillSrcPath);
+            const sameVersion = previousVersion === version;
+            const sameSource = sourceHashBeforeInstall === currentSourceHash;
+            const fallbackChange = !installedBefore
+                ? "created"
+                : sameVersion && sameSource
+                    ? "unchanged"
+                    : "updated";
+            const artifactChange = artifactChangeFromTargets(fallbackChange, targets);
+            const sourceDetails = gitHostedSkillArtifactSource(ref);
+            return {
+                path: rawDisplayPath.length === 0 ? "." : rawDisplayPath,
+                scope: ws.scope,
+                agents: artifactAgents,
+                ...(version !== undefined ? { version } : {}),
+                change: artifactChange,
+                ...(previousVersion !== undefined && previousVersion !== version
+                    ? { previousVersion }
+                    : {}),
+                fileCount,
+                ...(targets.length > 0 ? { targets } : {}),
+                ...(sourceDetails !== undefined ? { source: sourceDetails } : {}),
+            };
+        }),
+    }), releaseAgeWarning);
+    return warnings.length === 0 ? step : withPlanWarning(step, Option.some(warnings.join("; ")));
+}).pipe(Effect.mapError((cause) => installRefused({
+    category: "internal",
+    detail: `Skill install planning failed for ${input.ref.skill.name}`,
+    cause,
+})), Effect.withSpan("SkillInstallation.planStep"));
+/** The closures a settled skill intent becomes. */
+export const planSkillInstall = Effect.fn("InstallExtensions.planSkills")(function* (intent) {
+    const steps = yield* Effect.forEach(intent.skillsToInstall, (entry) => planSkillInstallationStep({ ...entry, operation: "install", force: intent.force === true }), { concurrency: 1 });
     return {
         _tag: "Plan",
         name: intent.skillsToInstall.length === 0

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

@@ -12,14 +12,16 @@ 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 { SkillManager, buildUninstallOperation, skillArtifactFromTargets, } from "@agentxm/extension-materialization";
+import { SkillManager, skillArtifactFromTargets, } from "@agentxm/extension-materialization";
+import { buildUninstallOperation } from "@agentxm/workspace-reconciliation";
 import { resolveInstalledIdentifierNameOrInput } from "@agentxm/extension-sources";
+import { parseExtensionFqnParts } from "@agentxm/extension-model/unstable/extensions";
 import { CodingAgentRepository } from "@agentxm/workspace-projection";
 import { WorkspaceMutations, acquiredExtensionDisplayPathFromLockEntry, installedRowsByName, sanitizeName, } from "@agentxm/workspace-state";
-import { expandGlob } from "../../glob.js";
+import { expandGlob } from "@agentxm/extension-model/unstable/extensions/name-patterns";
 import { lifecycleStepFailure } from "../../step-failure.js";
 import { installRefused, } from "../../install/vocabulary.js";
-import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+import { makeWorkspaceRetentionPolicy } from "@agentxm/workspace-reconciliation";
 import { workspaceAuthoredPath, workspaceCanonicalPath, workspaceCanonicalRoot, workspaceLockfilePath, workspaceSettingsPath, } from "../../workspace-paths.js";
 const skillSourceTarget = (ws, path, configuredSource, lockEntry, sanitizedName) => {
     if (Option.isSome(configuredSource) && configuredSource.value === "workspace") {
@@ -47,13 +49,19 @@ export const parseSkillUninstallRequest = Effect.fn("UninstallExtensions.parseSk
     if (selector.includes("*") && matched.length === 0) {
         return { targets: [] };
     }
+    // An identifier nothing installed answers to still names one skill: its
+    // extension name, never the fully qualified spelling as a name.
+    const unresolvedName = (input) => {
+        const fqn = parseExtensionFqnParts(input);
+        return fqn?.type === "skill" ? fqn.name : input;
+    };
     const names = matched.length > 0
         ? matched
         : [
             yield* resolveInstalledIdentifierNameOrInput({
                 input: selector,
                 resourceType: "skill",
-            }).pipe(Effect.mapError((cause) => installRefused({
+            }).pipe(Effect.map((name) => (name === selector.trim() ? unresolvedName(name) : name)), Effect.mapError((cause) => installRefused({
                 category: "not_found",
                 detail: `Skill "${selector}" could not be resolved`,
                 cause,
@@ -69,7 +77,7 @@ export const planSkillUninstall = Effect.fn("UninstallExtensions.planSkills")(fu
     const skillManager = yield* SkillManager;
     const agentRepo = yield* CodingAgentRepository;
     const path = yield* Path.Path;
-    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws, lifecycleStepFailure);
     const configuredAgents = yield* agentRepo.getMaterializationAgents().pipe(Effect.mapError((cause) => installRefused({
         category: "internal",
         detail: "Configured agents could not be read",

package/dist/src/step-failure.js

@@ -85,6 +85,18 @@ const carriedFailure = (failure) => {
 export const lifecycleStepFailure = (failure) => {
     if (failure instanceof StepFailure)
         return failure;
+    if (failure._tag === "McpSharedTargetConflict") {
+        return new StepFailure({
+            category: "conflict",
+            detail: failure.reason,
+            suggestions: [
+                {
+                    description: "Use an MCP package whose transport and symbolic inputs are supported by every configured reader of the shared target.",
+                },
+            ],
+            cause: failure,
+        });
+    }
     if (failure instanceof ExtensionLifecycleFailed) {
         return new StepFailure({
             category: failure.category,

package/dist/src/subagents/application/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Subagents selection application contract and workflow.
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Array from "effect/Array";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import { type SubagentSelectionRequest } from "../domain/selection.js";
+declare const SubagentSelectionNotFound_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: "SubagentSelectionNotFound";
+} & Readonly<A>;
+export declare class SubagentSelectionNotFound extends SubagentSelectionNotFound_base<{
+    readonly requested: ReadonlyArray<string>;
+    readonly available: ReadonlyArray<string>;
+}> {
+}
+declare const SubagentSelectionCancelled_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: "SubagentSelectionCancelled";
+} & Readonly<A>;
+export declare class SubagentSelectionCancelled extends SubagentSelectionCancelled_base<{
+    readonly message: string;
+}> {
+}
+declare const SubagentSelectionUnavailable_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: "SubagentSelectionUnavailable";
+} & Readonly<A>;
+/** The interface could not obtain a choice; this is distinct from cancellation. */
+export declare class SubagentSelectionUnavailable extends SubagentSelectionUnavailable_base<{
+    readonly cause?: unknown;
+}> {
+}
+declare const SubagentSelectionInteraction_base: Context.ServiceClass<SubagentSelectionInteraction, "@agentxm/extension-lifecycle/subagents/SubagentSelectionInteraction", {
+    readonly select: (candidates: Array.NonEmptyReadonlyArray<SubagentExtensionRef>) => Effect.Effect<ReadonlyArray<SubagentExtensionRef>, SubagentSelectionCancelled | SubagentSelectionUnavailable>;
+}>;
+export declare class SubagentSelectionInteraction extends SubagentSelectionInteraction_base {
+}
+export type SubagentSelectionFailure = SubagentSelectionNotFound | SubagentSelectionCancelled | SubagentSelectionUnavailable;
+/** Resolve the subagent-owned decision through this capability's interaction port. */
+export declare const determineSubagentsToInstall: (candidates: readonly [SubagentExtensionRef, ...SubagentExtensionRef[]], request: SubagentSelectionRequest) => Effect.Effect<readonly SubagentExtensionRef[], SubagentSelectionFailure, SubagentSelectionInteraction>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/subagents/application/index.js

@@ -0,0 +1,37 @@
+/**
+ * Subagents selection application contract and workflow.
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Array from "effect/Array";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { decideSubagentSelection } from "../domain/selection.js";
+export class SubagentSelectionNotFound extends Data.TaggedError("SubagentSelectionNotFound") {
+}
+export class SubagentSelectionCancelled extends Data.TaggedError("SubagentSelectionCancelled") {
+}
+/** The interface could not obtain a choice; this is distinct from cancellation. */
+export class SubagentSelectionUnavailable extends Data.TaggedError("SubagentSelectionUnavailable") {
+}
+export class SubagentSelectionInteraction extends Context.Service()("@agentxm/extension-lifecycle/subagents/SubagentSelectionInteraction") {
+}
+/** Resolve the subagent-owned decision through this capability's interaction port. */
+export const determineSubagentsToInstall = Effect.fn("Subagents.determineSelection")(function* (candidates, request) {
+    const names = Array.map(candidates, (ref) => ref.subagent.name);
+    const decision = decideSubagentSelection(names, request);
+    switch (decision.kind) {
+        case "selected":
+            return candidates.filter((ref) => decision.names.includes(ref.subagent.name));
+        case "unmatched":
+            return yield* new SubagentSelectionNotFound({
+                requested: request.requestedSubagents,
+                available: names,
+            });
+        case "choice-required": {
+            const interaction = yield* SubagentSelectionInteraction;
+            return yield* interaction.select(candidates);
+        }
+    }
+});
+//# sourceMappingURL=index.js.map

package/dist/src/subagents/domain/selection.d.ts

@@ -0,0 +1,22 @@
+import type * as Array from "effect/Array";
+export interface SubagentSelectionRequest {
+    readonly requestedSubagents: ReadonlyArray<string>;
+    readonly all: boolean;
+    readonly nonInteractive: boolean;
+}
+export type SubagentSelectionDecision = {
+    readonly kind: "selected";
+    readonly names: ReadonlyArray<string>;
+} | {
+    readonly kind: "choice-required";
+} | {
+    readonly kind: "unmatched";
+};
+/**
+ * Select this request's subagents, preserving source order.
+ * Named patterns take precedence over all/unattended selection. The existing
+ * union-of-matches behavior is retained; unresolved selector requirements remain
+ * explicit in the installation specification.
+ */
+export declare const decideSubagentSelection: (names: Array.NonEmptyReadonlyArray<string>, request: SubagentSelectionRequest) => SubagentSelectionDecision;
+//# sourceMappingURL=selection.d.ts.map

package/dist/src/subagents/domain/selection.js

@@ -0,0 +1,18 @@
+import { expandGlobs } from "@agentxm/extension-model/unstable/extensions/name-patterns";
+/**
+ * Select this request's subagents, preserving source order.
+ * Named patterns take precedence over all/unattended selection. The existing
+ * union-of-matches behavior is retained; unresolved selector requirements remain
+ * explicit in the installation specification.
+ */
+export const decideSubagentSelection = (names, request) => {
+    if (request.requestedSubagents.length > 0) {
+        const matched = expandGlobs(request.requestedSubagents, names);
+        return matched.length === 0 ? { kind: "unmatched" } : { kind: "selected", names: matched };
+    }
+    if (request.all || request.nonInteractive || names.length === 1) {
+        return { kind: "selected", names };
+    }
+    return { kind: "choice-required" };
+};
+//# sourceMappingURL=selection.js.map

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

@@ -18,8 +18,8 @@ import { type SourceResolutionFailure } from "@agentxm/extension-sources";
 import { type Plan } from "@agentxm/workspace-operations";
 import type { ExtensionLifecycleFailed } from "../../errors.js";
 import { type RegistryLookupProbe } from "../../install/registry-source-resolution.js";
-import { ExtensionSelectionInteraction, type ExtensionSelectionCancelled } from "../../install/selection-interaction.js";
 import { type InstallStepRequirements, type ResolveInstallRequirements, type SubagentInstallIntent } from "../../install/vocabulary.js";
+import { SubagentSelectionInteraction, type SubagentSelectionFailure } from "../application/index.js";
 /** A subagent source after grammar parsing, before anything is discovered. */
 export interface ParsedSubagentInstallRequest {
     readonly source: Source;
@@ -43,7 +43,7 @@ export declare const parseSubagentInstallRequest: (args: SubagentInstallArgs) =>
 /** Discover the subagents the parsed source offers, or refuse when it has none. */
 export declare const discoverSubagentRefs: (request: ParsedSubagentInstallRequest) => Effect.Effect<ReadonlyArray<SubagentExtensionRef>, ExtensionLifecycleFailed, ResolveInstallRequirements>;
 /** Settle which of the discovered subagents this request installs. */
-export declare const finalizeSubagentInstallIntent: (request: ParsedSubagentInstallRequest, discovered: ReadonlyArray<SubagentExtensionRef>) => Effect.Effect<SubagentInstallIntent, ExtensionLifecycleFailed | ExtensionSelectionCancelled, ExtensionSelectionInteraction>;
+export declare const finalizeSubagentInstallIntent: (request: ParsedSubagentInstallRequest, discovered: ReadonlyArray<SubagentExtensionRef>) => Effect.Effect<SubagentInstallIntent, ExtensionLifecycleFailed | SubagentSelectionFailure, SubagentSelectionInteraction>;
 /** The closures a settled subagent intent becomes. */
 export declare const planSubagentInstall: (intent: SubagentInstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | SubagentManager>;
 //# sourceMappingURL=plan.d.ts.map

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

@@ -10,7 +10,8 @@
 import * as Array from "effect/Array";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { NO_MATERIALIZATION_OBSERVATION, SubagentManager, buildInstallOperation, } from "@agentxm/extension-materialization";
+import { NO_MATERIALIZATION_OBSERVATION, SubagentManager, } from "@agentxm/extension-materialization";
+import { buildInstallOperation } from "@agentxm/workspace-reconciliation";
 import { parseInputPattern, } from "@agentxm/extension-model/unstable/sources/parser";
 import { SourceHostProviders, sourceResolutionFailureCategory, } from "@agentxm/extension-sources";
 import { operationPresentation, } from "@agentxm/workspace-operations";
@@ -18,9 +19,8 @@ import { CodingAgentRepository } from "@agentxm/workspace-projection";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
 import { lifecycleStepFailure } from "../../step-failure.js";
 import { sourceFailureDetail, } from "../../install/registry-source-resolution.js";
-import { ExtensionSelectionInteraction, } from "../../install/selection-interaction.js";
 import { installRefused, } from "../../install/vocabulary.js";
-import { determineSubagentsToInstall } from "./selection.js";
+import { determineSubagentsToInstall, SubagentSelectionInteraction, } from "../application/index.js";
 import { resolveSubagentInstallSource } from "./source.js";
 const isRemoteReadNotImplemented = (error) => sourceFailureDetail(error).includes("not implemented");
 const discoverHowToFix = (source, error) => {
@@ -216,7 +216,7 @@ export const planSubagentInstall = Effect.fn("InstallExtensions.planSubagents")(
         return buildInstallOperation(subagentManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: entry.versionRange,
+            declaration: { name: ref.subagent.name, versionRange: entry.versionRange },
             installedBefore: subagentManager
                 .isInstalled({ target: { type: "subagent", name: ref.subagent.name } })
                 .pipe(Effect.catch(() => Effect.succeed(false))),

package/dist/src/subagents/operations/enable.js

@@ -64,9 +64,7 @@ export const enableSubagent = (op) => Effect.gen(function* () {
         });
     }
     const baseDir = ws.baseDir;
-    const subagentSrcPath = canonical.value.ref.refType === "registry" || canonical.value.ref.refType === "workspace"
-        ? path.join(canonical.value.observation.path, "src")
-        : canonical.value.observation.path;
+    const subagentSrcPath = path.join(canonical.value.observation.path, "src");
     // Read and parse the subagent content file
     const expectedFilename = subagentContentFilename(op.args.subagentName);
     const contentPath = subagentContentPath(path.join, subagentSrcPath, op.args.subagentName);