@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/step-failure.js

@@ -0,0 +1,130 @@
+/**
+ * How a lifecycle closure serializes a failure into the plan-step vocabulary.
+ *
+ * The feature owns this: a lifecycle step that failed must report the same
+ * category, sentence, and recovery whether the failure came from lifecycle
+ * policy, from the materialization machinery underneath it, from workspace
+ * state, or from the transaction around it. Nothing is supplied by the
+ * application, so a lifecycle use case carries no failure adapter in its
+ * requirements.
+ *
+ * Categories and detail sentences are the serialized contract of machine
+ * output; families that already carry their own category and fact sentence
+ * keep both rather than being replaced with a generic sentence.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { OPERATION_ERROR_CATEGORIES, StepFailure, restorationIncompleteToStepFailure, workspaceStateReadFailureToStepFailure, workspaceTransactionFailureToStepFailure, } from "@agentxm/workspace-operations";
+import { LifecyclePostconditionViolated, projectionErrorToStepFailure, } from "@agentxm/extension-materialization";
+import { isProjectionError } from "@agentxm/workspace-projection";
+import { WorkspaceRestorationIncomplete, } from "@agentxm/workspace-transactions";
+import { ExtensionLifecycleFailed } from "./errors.js";
+const CATEGORIES = new Set(OPERATION_ERROR_CATEGORIES);
+const isCategory = (value) => typeof value === "string" && CATEGORIES.has(value);
+const property = (failure, key) => key in failure ? Reflect.get(failure, key) : undefined;
+const WORKSPACE_STATE_READ_TAGS = new Set([
+    "SettingsDecodeError",
+    "SettingsParseError",
+    "SettingsIoError",
+    "LockfileIoError",
+    "LockfileParseError",
+    "LockfileDecodeError",
+    "LockfileVersionUnsupported",
+    "WorkspaceRootEscape",
+]);
+const WORKSPACE_TRANSACTION_TAGS = new Set([
+    "WorkspaceSnapshotError",
+    "WorkspaceDirectoryError",
+    "TransitionLockError",
+    "TransitionLockUnavailable",
+    "WorkspaceTransitionCompromised",
+]);
+const isWorkspaceStateReadFailure = (failure) => WORKSPACE_STATE_READ_TAGS.has(failure._tag);
+const isWorkspaceTransactionFailure = (failure) => WORKSPACE_TRANSACTION_TAGS.has(failure._tag);
+const postconditionDetail = (failure) => {
+    switch (failure.postcondition) {
+        case "install-observable":
+            return `Installed ${failure.targetType} "${failure.targetName}" did not satisfy its observable contract`;
+        case "install-declared":
+            return `Installed ${failure.targetType} "${failure.targetName}" has no desired-state declaration`;
+        case "new-observable":
+            return `New ${failure.targetType} "${failure.targetName}" did not satisfy its observable contract`;
+        case "new-declared":
+            return `New ${failure.targetType} "${failure.targetName}" has no desired-state declaration`;
+        case "materialize-observable":
+            return `Reconciled ${failure.targetType} "${failure.targetName}" did not satisfy its observable contract`;
+        case "uninstall-remains-declared":
+            return `Uninstalled ${failure.targetType} "${failure.targetName}" remains declared`;
+        case "uninstall-observed-state":
+            return `Uninstalled ${failure.targetType} "${failure.targetName}" has an invalid observed postcondition`;
+    }
+};
+/**
+ * A family this conversion does not name still carries its own decision: the
+ * producer recorded a category and a fact sentence, so both survive, and the
+ * failure itself stays in `cause` for the diagnostic chain.
+ */
+const carriedFailure = (failure) => {
+    const carriedCategory = property(failure, "category");
+    const carriedDetail = property(failure, "detail");
+    return new StepFailure({
+        category: isCategory(carriedCategory) ? carriedCategory : "internal",
+        detail: typeof carriedDetail === "string"
+            ? carriedDetail
+            : `The lifecycle step failed with ${failure._tag}`,
+        cause: failure,
+    });
+};
+/**
+ * Serialize one lifecycle-closure failure into the plan-step vocabulary.
+ *
+ * Families this feature or the machinery beneath it constructs are rendered
+ * exactly; families the kernel already serializes are delegated to it; and
+ * anything else carries its producer's own category and sentence through.
+ */
+export const lifecycleStepFailure = (failure) => {
+    if (failure instanceof StepFailure)
+        return failure;
+    if (failure instanceof ExtensionLifecycleFailed) {
+        return new StepFailure({
+            category: failure.category,
+            detail: failure.detail ?? `The lifecycle step was refused (${failure.category})`,
+            ...(failure.recover === undefined && failure.suggestions === undefined
+                ? {}
+                : {
+                    suggestions: [
+                        ...(failure.recover === undefined
+                            ? []
+                            : [
+                                {
+                                    description: failure.recover,
+                                    ...(failure.cmd === undefined ? {} : { cmd: failure.cmd }),
+                                },
+                            ]),
+                        ...(failure.suggestions ?? []),
+                    ],
+                }),
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        });
+    }
+    if (failure instanceof LifecyclePostconditionViolated) {
+        return new StepFailure({ category: "internal", detail: postconditionDetail(failure) });
+    }
+    if (failure instanceof WorkspaceRestorationIncomplete) {
+        return restorationIncompleteToStepFailure(failure);
+    }
+    if (isWorkspaceTransactionFailure(failure)) {
+        return workspaceTransactionFailureToStepFailure(failure);
+    }
+    if (isWorkspaceStateReadFailure(failure)) {
+        return workspaceStateReadFailureToStepFailure(failure);
+    }
+    // Shared projection states domain facts and renders nothing, so the
+    // capability that unions it renders it; `carriedFailure` would find no
+    // category and report a projection refusal as an internal defect.
+    if (isProjectionError(failure)) {
+        return projectionErrorToStepFailure(failure);
+    }
+    return carriedFailure(failure);
+};
+//# sourceMappingURL=step-failure.js.map

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

@@ -0,0 +1,49 @@
+/**
+ * Installing subagents.
+ *
+ * A subagent is rendered into each configured agent's own subagents
+ * directory, so a user-scope workspace can only hold one when every
+ * configured agent has a user-scope placement to render into.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { SubagentManager } from "@agentxm/extension-materialization";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+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 { 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";
+/** A subagent source after grammar parsing, before anything is discovered. */
+export interface ParsedSubagentInstallRequest {
+    readonly source: Source;
+    readonly versionRange: Option.Option<VersionRange>;
+    readonly requestedSubagents: ReadonlyArray<string>;
+    readonly requestedOwner: Option.Option<Handle>;
+    /** Which configured registry hosts were consulted, and what each answered. */
+    readonly resolutionProbes: ReadonlyArray<RegistryLookupProbe>;
+    readonly all: boolean;
+    readonly nonInteractive: boolean;
+}
+/** What a subagent install command supplies before anything is parsed. */
+export interface SubagentInstallArgs {
+    readonly source: string;
+    readonly subagents: ReadonlyArray<string>;
+    readonly all: boolean;
+    readonly nonInteractive: boolean;
+}
+/** Read the subagent source grammar and route it to the source that serves it. */
+export declare const parseSubagentInstallRequest: (args: SubagentInstallArgs) => Effect.Effect<ParsedSubagentInstallRequest, ExtensionLifecycleFailed | SourceResolutionFailure, ResolveInstallRequirements>;
+/** 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>;
+/** 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

@@ -0,0 +1,270 @@
+/**
+ * Installing subagents.
+ *
+ * A subagent is rendered into each configured agent's own subagents
+ * directory, so a user-scope workspace can only hold one when every
+ * configured agent has a user-scope placement to render into.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+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 { parseInputPattern, } from "@agentxm/extension-model/unstable/sources/parser";
+import { SourceHostProviders, sourceResolutionFailureCategory, } from "@agentxm/extension-sources";
+import { operationPresentation, } from "@agentxm/workspace-operations";
+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 { resolveSubagentInstallSource } from "./source.js";
+const isRemoteReadNotImplemented = (error) => sourceFailureDetail(error).includes("not implemented");
+const discoverHowToFix = (source, error) => {
+    if (source.type === "registry") {
+        if (isRemoteReadNotImplemented(error)) {
+            return "Remote registry discovery is not yet supported for HTTP(S) sources. Use a file:// registry source, or install from github:owner/repo.";
+        }
+        return "Verify the configured registry is reachable and contains the requested owner/subagent.";
+    }
+    if (source.type === "local") {
+        return "Verify the source path contains subagent directories with <name>.md files.";
+    }
+    return "Verify the source is reachable and contains valid subagent directories.";
+};
+const noSubagentsFoundHowToFix = (source) => {
+    if (source.type === "registry") {
+        return "Verify the owner and subagent name exist in the configured registry.";
+    }
+    if (source.type === "local") {
+        return "Verify the source path contains subagent directories with <name>.md files.";
+    }
+    return "Verify the source contains subagent directories with <name>.md files.";
+};
+const extractRequestedSubagents = (argSubagents, parsedSource) => argSubagents.length > 0
+    ? argSubagents
+    : parsedSource.pattern.pattern === "name-input"
+        ? [parsedSource.pattern.name]
+        : parsedSource.pattern.pattern === "registry-pattern-input"
+            ? Option.isSome(parsedSource.pattern.name)
+                ? [parsedSource.pattern.name.value]
+                : []
+            : [];
+const extractRequestedOwner = (parsedSource, source) => parsedSource.pattern.pattern === "registry-pattern-input"
+    ? Option.some(parsedSource.pattern.owner)
+    : source.type === "registry"
+        ? source.owner
+        : Option.none();
+const previousResolvedVersion = (entry) => {
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    if (!("type" in entry) || entry.type !== "registry")
+        return undefined;
+    if (!("resolvedVersion" in entry) || typeof entry.resolvedVersion !== "string")
+        return undefined;
+    return entry.resolvedVersion;
+};
+const previousContentIdentity = (entry) => {
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    if (!("contentIdentity" in entry) || typeof entry.contentIdentity !== "string")
+        return undefined;
+    return entry.contentIdentity;
+};
+const artifactChange = (args) => {
+    if (!args.installedBefore)
+        return "created";
+    const sameVersion = args.previousVersion === args.version;
+    const sameSource = args.previousSourceHash === undefined ||
+        args.sourceHash === undefined ||
+        args.previousSourceHash === args.sourceHash;
+    return sameVersion && sameSource ? "unchanged" : "updated";
+};
+/** Read the subagent source grammar and route it to the source that serves it. */
+export const parseSubagentInstallRequest = Effect.fn("InstallExtensions.parseSubagentRequest")(function* (args) {
+    const parsedSourceOption = parseInputPattern(args.source.trim());
+    if (Option.isNone(parsedSourceOption)) {
+        return yield* installRefused({
+            category: "validation",
+            detail: "Invalid source: Unable to parse source",
+            suggestions: [
+                {
+                    description: "Valid formats: local path, github:owner/repo, gitlab:owner/repo, or https://example.com",
+                },
+            ],
+        });
+    }
+    const parsedSource = parsedSourceOption.value;
+    const versionRange = parsedSource.pattern.pattern === "registry-pattern-input"
+        ? parsedSource.pattern.versionRange
+        : Option.none();
+    const resolutionProbes = [];
+    const source = yield* resolveSubagentInstallSource(parsedSource, {
+        onRegistryProbe: (probe) => {
+            resolutionProbes.push(probe);
+        },
+    });
+    return {
+        source,
+        versionRange,
+        requestedSubagents: extractRequestedSubagents(args.subagents, parsedSource),
+        requestedOwner: extractRequestedOwner(parsedSource, source),
+        resolutionProbes,
+        all: args.all,
+        nonInteractive: args.nonInteractive,
+    };
+});
+/** Discover the subagents the parsed source offers, or refuse when it has none. */
+export const discoverSubagentRefs = Effect.fn("InstallExtensions.discoverSubagents")(function* (request) {
+    const sources = yield* SourceHostProviders;
+    const discovered = yield* sources
+        .find(request.source, {
+        names: request.requestedSubagents,
+        type: "subagent",
+        owner: request.requestedOwner,
+        versionRange: request.versionRange,
+    })
+        .pipe(Effect.map(Array.filter((ref) => ref.type === "subagent")), Effect.mapError((cause) => installRefused({
+        category: sourceResolutionFailureCategory(cause) === "not_found" ? "not_found" : "usage",
+        detail: "Failed to discover subagents from source",
+        suggestions: [{ description: discoverHowToFix(request.source, cause) }],
+        cause,
+    })));
+    if (Array.isReadonlyArrayEmpty(discovered)) {
+        return yield* installRefused({
+            category: "not_found",
+            detail: "No subagents found in source",
+            suggestions: [{ description: noSubagentsFoundHowToFix(request.source) }],
+        });
+    }
+    return discovered;
+});
+/** Settle which of the discovered subagents this request installs. */
+export const finalizeSubagentInstallIntent = Effect.fn("InstallExtensions.finalizeSubagentIntent")(function* (request, discovered) {
+    const [first, ...rest] = discovered;
+    if (first === undefined) {
+        return yield* installRefused({
+            category: "not_found",
+            detail: "No subagents found in source",
+        });
+    }
+    const candidates = [first, ...rest];
+    const selected = yield* determineSubagentsToInstall(candidates, {
+        requestedSubagents: request.requestedSubagents,
+        all: request.all,
+        nonInteractive: request.nonInteractive,
+    });
+    if (Array.isReadonlyArrayEmpty(selected)) {
+        return { subagentsToInstall: [] };
+    }
+    return {
+        subagentsToInstall: selected.map((ref) => ({
+            ref,
+            versionRange: ref.refType === "registry" ? request.versionRange : Option.none(),
+        })),
+    };
+});
+/** The closures a settled subagent intent becomes. */
+export const planSubagentInstall = Effect.fn("InstallExtensions.planSubagents")(function* (intent) {
+    const ws = yield* WorkspaceMutations;
+    const subagentManager = yield* SubagentManager;
+    const agentRepo = yield* CodingAgentRepository;
+    // A user-scope workspace can only hold subagents when every configured
+    // agent has a user-scope placement to render them into.
+    if (ws.scope === "user") {
+        const agents = yield* agentRepo.getConfiguredAgents().pipe(Effect.mapError((cause) => installRefused({
+            category: "internal",
+            detail: "Configured agents could not be read",
+            cause,
+        })));
+        const placements = yield* Effect.forEach(agents, (agent) => agent
+            .resolveEffectiveSubagentsDir({ workspaceRoot: ws.baseDir, scope: ws.scope })
+            .pipe(Effect.map((outcome) => ({ agentId: agent.id, outcome }))), { concurrency: "unbounded" }).pipe(Effect.mapError((cause) => installRefused({
+            category: "internal",
+            detail: "Configured subagent placement could not be resolved",
+            cause,
+        })));
+        const refused = placements.flatMap(({ agentId, outcome }) => outcome._tag === "unsupported" ||
+            outcome._tag === "misconfigured" ||
+            outcome._tag === "disabled"
+            ? [`${agentId}: ${outcome.reason}`]
+            : []);
+        if (refused.length > 0) {
+            return yield* installRefused({
+                category: "validation",
+                detail: `Cannot install subagents in user scope for the configured agent placement: ${refused.join("; ")}`,
+            });
+        }
+    }
+    const steps = yield* Effect.forEach(intent.subagentsToInstall, (entry) => Effect.gen(function* () {
+        const ref = entry.ref;
+        const previousLockEntry = yield* ws
+            .getLockedSubagent(ref.subagent.name)
+            .pipe(Effect.catch(() => Effect.succeed(Option.none())));
+        const previousVersion = Option.match(previousLockEntry, {
+            onNone: () => undefined,
+            onSome: previousResolvedVersion,
+        });
+        const sourceHashBeforeInstall = Option.match(previousLockEntry, {
+            onNone: () => undefined,
+            onSome: previousContentIdentity,
+        });
+        const version = ref.refType === "registry" ? ref.version : undefined;
+        return buildInstallOperation(subagentManager, {
+            toStepFailure: lifecycleStepFailure,
+            ref,
+            versionRange: entry.versionRange,
+            installedBefore: subagentManager
+                .isInstalled({ target: { type: "subagent", name: ref.subagent.name } })
+                .pipe(Effect.catch(() => Effect.succeed(false))),
+            buildArtifact: ({ installedBefore, materialization, }) => Effect.gen(function* () {
+                const lockEntryOption = yield* ws
+                    .getLockedSubagent(ref.subagent.name)
+                    .pipe(Effect.catch(() => Effect.succeed(Option.none())));
+                const sourceHash = previousContentIdentity(Option.getOrUndefined(lockEntryOption));
+                const change = artifactChange({
+                    installedBefore,
+                    previousVersion,
+                    version,
+                    previousSourceHash: sourceHashBeforeInstall,
+                    sourceHash,
+                });
+                const observation = Option.match(materialization, {
+                    onNone: () => NO_MATERIALIZATION_OBSERVATION,
+                    onSome: (facts) => facts.observation,
+                });
+                const targets = observation.targets.map((target) => ({
+                    path: target.path,
+                    change,
+                    ...(target.agentIds === undefined ? {} : { agentIds: target.agentIds }),
+                }));
+                return {
+                    path: targets[0]?.path ?? ref.subagent.name,
+                    scope: ws.scope,
+                    agents: observation.agents,
+                    ...(version !== undefined ? { version } : {}),
+                    change,
+                    ...(previousVersion !== undefined && previousVersion !== version
+                        ? { previousVersion }
+                        : {}),
+                    ...(targets.length === 0 ? {} : { fileCount: targets.length, targets }),
+                };
+            }),
+        });
+    }).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Subagent install planning failed for ${entry.ref.subagent.name}`,
+        cause,
+    }))), { concurrency: 1 });
+    return {
+        _tag: "Plan",
+        name: intent.subagentsToInstall.length === 1 ? "Install subagent" : "Install subagents",
+        description: Option.none(),
+        presentation: operationPresentation({ imperative: "install", past: "Installed", gerund: "Installing" }, "subagent"),
+        jobs: [{ concurrency: 1, steps }],
+    };
+});
+//# sourceMappingURL=plan.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Which of a source's subagents this request installs.
+ *
+ * The same decision the skill route makes, over subagent names: named
+ * patterns must match, `--all` and an unattended invocation take everything,
+ * a single subagent needs no decision, and anything else is a person's
+ * choice.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { ExtensionSelectionInteraction, type ExtensionSelectionCancelled } from "../../install/selection-interaction.js";
+export interface SubagentSelectionRequest {
+    /** Names or glob patterns the request named explicitly. */
+    readonly requestedSubagents: ReadonlyArray<string>;
+    /** Take everything the source offers without asking. */
+    readonly all: boolean;
+    /** No prompt can open in this invocation. */
+    readonly nonInteractive: boolean;
+}
+/** Settle which discovered subagents this request installs. */
+export declare const determineSubagentsToInstall: (subagents: Array.NonEmptyReadonlyArray<SubagentExtensionRef>, request: SubagentSelectionRequest) => Effect.Effect<ReadonlyArray<SubagentExtensionRef>, ExtensionLifecycleFailed | ExtensionSelectionCancelled, ExtensionSelectionInteraction>;
+//# sourceMappingURL=selection.d.ts.map

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

@@ -0,0 +1,37 @@
+/**
+ * Which of a source's subagents this request installs.
+ *
+ * The same decision the skill route makes, over subagent names: named
+ * patterns must match, `--all` and an unattended invocation take everything,
+ * a single subagent needs no decision, and anything else is a person's
+ * choice.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import { expandGlobs } from "../../glob.js";
+import { ExtensionSelectionInteraction, } from "../../install/selection-interaction.js";
+import { installRefused } from "../../install/vocabulary.js";
+/** Settle which discovered subagents this request installs. */
+export const determineSubagentsToInstall = Effect.fn("InstallExtensions.determineSubagentsToInstall")(function* (subagents, request) {
+    if (request.requestedSubagents.length > 0) {
+        const allNames = Array.map(subagents, (subagent) => subagent.subagent.name);
+        const matched = expandGlobs(request.requestedSubagents, allNames);
+        if (matched.length === 0) {
+            return yield* installRefused({
+                category: "internal",
+                detail: `No subagents matched: ${request.requestedSubagents.join(", ")}`,
+                suggestions: [{ description: "Check the subagent names or patterns and try again." }],
+            });
+        }
+        return Array.filter(subagents, (subagent) => matched.includes(subagent.subagent.name));
+    }
+    if (request.all || request.nonInteractive)
+        return subagents;
+    if (subagents.length === 1)
+        return subagents;
+    const interaction = yield* ExtensionSelectionInteraction;
+    return yield* interaction.selectSubagents(subagents);
+});
+//# sourceMappingURL=selection.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * Which source a subagent install request names.
+ *
+ * The same routing the skill request uses, minus the SCP address form, which
+ * no subagent source has ever been published under.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type { InputParseResult } from "@agentxm/extension-model/unstable/sources/parser";
+import type { Source } from "@agentxm/extension-model/unstable/sources/types";
+import { type SourceResolutionFailure } from "@agentxm/extension-sources";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type RegistryResolutionOptions } from "../../install/registry-source-resolution.js";
+import { type ResolveInstallRequirements } from "../../install/vocabulary.js";
+/** Route one parsed subagent locator to the source that serves it. */
+export declare const resolveSubagentInstallSource: (parseResult: InputParseResult, options?: RegistryResolutionOptions) => Effect.Effect<Source, ExtensionLifecycleFailed | SourceResolutionFailure, ResolveInstallRequirements>;
+//# sourceMappingURL=source.d.ts.map

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

@@ -0,0 +1,72 @@
+/**
+ * Which source a subagent install request names.
+ *
+ * The same routing the skill request uses, minus the SCP address form, which
+ * no subagent source has ever been published under.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { resolveShorthandInputSource, resolveSlashInputSource, routeUrlInput, } from "@agentxm/extension-sources";
+import { resolveConfiguredRegistrySource, resolveDefaultRegistrySourceByName, } from "../../install/registry-source-resolution.js";
+import { installRefused } from "../../install/vocabulary.js";
+const resolveSubagentRegistrySource = (pattern, options) => Effect.gen(function* () {
+    if (Option.isSome(pattern.type) && pattern.type.value !== "subagents") {
+        return yield* installRefused({
+            category: "usage",
+            detail: `Cannot install "${pattern.type.value}" extensions with "subagents install"`,
+            recover: `Use the "${pattern.type.value}" command instead, or remove the type qualifier to install as a subagent`,
+        });
+    }
+    return yield* resolveConfiguredRegistrySource({
+        sourceName: pattern.sourceName,
+        owner: pattern.owner,
+        extensionType: "subagent",
+        extensionName: pattern.name,
+        options,
+    });
+});
+/** Route one parsed subagent locator to the source that serves it. */
+export const resolveSubagentInstallSource = Effect.fn("InstallExtensions.resolveSubagentSource")(function* (parseResult, options) {
+    const resolutionOptions = Option.fromUndefinedOr(options);
+    const pattern = parseResult.pattern;
+    switch (pattern.pattern) {
+        case "registry-pattern-input":
+            return yield* resolveSubagentRegistrySource(pattern, resolutionOptions);
+        case "shorthand-input":
+            return yield* resolveShorthandInputSource({
+                pattern,
+                originalInput: parseResult.originalInput,
+            });
+        case "slash-pattern":
+            return yield* resolveSlashInputSource(pattern, parseResult.originalInput);
+        case "name-input":
+            return yield* resolveDefaultRegistrySourceByName({
+                name: pattern.name,
+                extensionType: "subagent",
+                options: resolutionOptions,
+            });
+        case "url-input":
+            return yield* routeUrlInput(pattern.url, parseResult.originalInput);
+        case "file-path-pattern":
+            return { type: "local", path: pattern.path };
+        case "workspace-pattern-input":
+            return yield* installRefused({
+                category: "conflict",
+                detail: `Workspace source "${parseResult.originalInput}" is locally authoritative and cannot be installed over`,
+                suggestions: [
+                    { description: "Sync the workspace package", cmd: "axm sync" },
+                    { description: "Enable the workspace subagent", cmd: "axm subagents enable <name>" },
+                ],
+            });
+        case "git-scp-address":
+        case "glob-input":
+            return yield* installRefused({
+                category: "usage",
+                detail: `Input pattern "${pattern.pattern}" is not supported for subagent installation`,
+                recover: "Use a registry reference (e.g., @owner/subagents/name), a URL, or a shorthand (owner/repo) instead",
+            });
+    }
+});
+//# sourceMappingURL=source.js.map

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

@@ -6,13 +6,15 @@
  *
  * @experimental This API is unstable and may change without notice.
  */
+import { NativeWriteAuthority } from "@agentxm/agent-integration";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
-import { CodingAgentRepository } from "@agentxm/extension-workspace";
-import { LifecycleFailureAdapter } from "../../failure-adapter.js";
+import { CodingAgentRepository } from "@agentxm/workspace-projection";
+import { StepFailureConversion } from "../../step-failure-conversion.js";
 import type { OperationHandler } from "@agentxm/workspace-operations";
 import type { Operation } from "@agentxm/workspace-operations";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
 /**
  * Disable a subagent (remove rendered files but keep settings/lockfile entry).
  *
@@ -28,5 +30,5 @@ export type DisableSubagentOperation = Operation<"disable-subagent", {
  * rendered files, and promotes implicit pack members to a direct disabled
  * preference. Canonical source files are preserved for later re-enablement.
  */
-export declare const disableSubagent: OperationHandler<DisableSubagentOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | CodingAgentRepository | LifecycleFailureAdapter>;
+export declare const disableSubagent: OperationHandler<DisableSubagentOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | WorkspaceTransactionScope | CodingAgentRepository | NativeWriteAuthority | StepFailureConversion>;
 //# sourceMappingURL=disable.d.ts.map

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

@@ -6,14 +6,16 @@
  *
  * @experimental This API is unstable and may change without notice.
  */
+import { NativeWriteAuthority } from "@agentxm/agent-integration";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { CodingAgentRepository, findManagedSubagentFiles } from "@agentxm/extension-workspace";
+import { CodingAgentRepository, findManagedSubagentFiles } from "@agentxm/workspace-projection";
 import { ExtensionLifecycleFailed } from "../../errors.js";
-import { LifecycleFailureAdapter, withAdaptedStepFailures } from "../../failure-adapter.js";
+import { StepFailureConversion, withAdaptedStepFailures } from "../../step-failure-conversion.js";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { WorkspaceTransactionScope, runWorkspaceTransaction, } from "@agentxm/workspace-transactions";
 import { subagentLifecycleArtifact } from "./artifact.js";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
@@ -53,7 +55,7 @@ export const disableSubagent = (op) => Effect.gen(function* () {
     const desiredBeforeDisable = graph.nodes.find((node) => node.type === "subagent" && node.name === op.args.subagentName);
     const renderedFiles = {};
     const configuredAgents = yield* agentRepo.getConfiguredAgents();
-    yield* ws.runTransaction({
+    yield* runWorkspaceTransaction({
         transition: Effect.gen(function* () {
             if (isImplicit) {
                 const source = desiredBeforeDisable?.source ?? Option.getOrElse(installed.source, () => undefined);