@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/install/configured.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Installing what the workspace already declares.
+ *
+ * `axm install` with no source, and every `<type> install` with no source, ask
+ * the same question: bring the workspace to the state its settings describe.
+ * Each enabled configured entry resolves to the version its declared source
+ * and the release-age policy allow, becomes its own closure, and the shared
+ * aggregate projections are rendered once at the end from the complete
+ * contributor set. A member reached twice — declared directly and required by
+ * a pack — is installed once, from the direct declaration.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager } from "@agentxm/extension-materialization";
+import { type InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { ReleaseAgePosture, ExtensionResolutionFailed } from "@agentxm/extension-resolution";
+import { type ConfiguredAgentOperation, type Plan } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../errors.js";
+import { type PackInstallRequirements } from "../packs/install/plan.js";
+import { type InstallStepRequirements, type ResolveInstallRequirements } from "./vocabulary.js";
+/** Which extension types a configured-entry sweep covers. */
+export type ConfiguredInstallableType = InstallableExtensionType;
+/** What a configured-entry sweep settled: a plan, or nothing to do. */
+export type ConfiguredInstallPlanResult = {
+    readonly _tag: "NoConfiguredExtensions";
+    readonly message: string;
+} | {
+    readonly _tag: "ConfiguredInstallPlan";
+    readonly plan: Plan<InstallStepRequirements>;
+    readonly configuredAgentOperations: ReadonlyArray<ConfiguredAgentOperation>;
+};
+/** Everything a configured-entry sweep reads before it freezes a candidate. */
+export type ConfiguredInstallRequirements = InstallStepRequirements | PackInstallRequirements | ResolveInstallRequirements | ReleaseAgePosture | HookManager | KnowledgeManager | McpServerManager | PackManager | RuleManager | SkillManager | SubagentManager;
+/**
+ * Every failure settling the configured closure can surface: this feature's
+ * own refusal, plus the resolution refusal a configured entry's source
+ * carries through with its own category and sentence.
+ */
+export type ConfiguredInstallFailure = ExtensionLifecycleFailed | ExtensionResolutionFailed;
+/**
+ * Build the configured Pack graph as one recovery candidate.
+ *
+ * Recovery only runs for Packs whose observed tree already diverged from the
+ * accepted resolution, so the installed tree is never reused.
+ */
+/** Which configured packs a recovery rebuilds, and what to call the operation. */
+export interface ConfiguredPackRecoveryRequest {
+    readonly planName: string;
+    readonly planDescription: Option.Option<string>;
+    readonly packNames: ReadonlySet<string>;
+    readonly nonInteractive: boolean;
+}
+export declare const buildConfiguredPackInstallPlan: (args: ConfiguredPackRecoveryRequest) => Effect.Effect<ConfiguredInstallPlanResult, ConfiguredInstallFailure, ConfiguredInstallRequirements>;
+/** Plan the install of every enabled configured entry, or of one type's. */
+/** Which configured entries a sweep covers, and what to call the operation. */
+export interface ConfiguredInstallRequest {
+    readonly type: Option.Option<ConfiguredInstallableType>;
+    readonly planName: string;
+    readonly planDescription: Option.Option<string>;
+    readonly nonInteractive: boolean;
+}
+export declare const buildConfiguredInstallPlan: (args: ConfiguredInstallRequest) => Effect.Effect<ConfiguredInstallPlanResult, ConfiguredInstallFailure, ConfiguredInstallRequirements>;
+//# sourceMappingURL=configured.d.ts.map

package/dist/src/install/configured.js

@@ -0,0 +1,406 @@
+/**
+ * Installing what the workspace already declares.
+ *
+ * `axm install` with no source, and every `<type> install` with no source, ask
+ * the same question: bring the workspace to the state its settings describe.
+ * Each enabled configured entry resolves to the version its declared source
+ * and the release-age policy allow, becomes its own closure, and the shared
+ * aggregate projections are rendered once at the end from the complete
+ * contributor set. A member reached twice — declared directly and required by
+ * a pack — is installed once, from the direct declaration.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, } from "@agentxm/extension-materialization";
+import { decodeExtensionNameSync, extensionTypePluralSentenceLabels, parseRegistrySourceRef, } from "@agentxm/extension-model/unstable/extensions";
+import { installableExtensionTypes, toInstallableExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { ReleaseAgePosture, acceptedPackDependencyResolver, ExtensionResolutionFailed, hydrateAcceptedPackRef, makeConfiguredReleaseAgeEvaluation, normalizeReleaseAgeRecords, resolveConfiguredHook, resolveConfiguredKnowledge, resolveConfiguredMcpServer, resolveConfiguredPack, resolveConfiguredRule, resolveConfiguredSkill, resolveConfiguredSubagent, } from "@agentxm/extension-resolution";
+import { operationPresentation, } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, acceptedResolutionRef, enabledConfiguredEntries, } from "@agentxm/workspace-state";
+import { planHookInstall } from "../hooks/install/plan.js";
+import { planKnowledgeInstall } from "../knowledge/install/plan.js";
+import { planMcpServerInstall } from "../mcps/install/plan.js";
+import { planPackInstall } from "../packs/install/plan.js";
+import { configuredPackConstraintBlockPlan, prospectivePackConstraintProblems, } from "../packs/constraint-gate.js";
+import { planRuleInstall } from "../rules/install/plan.js";
+import { planSkillInstall } from "../skills/install/plan.js";
+import { planSubagentInstall } from "../subagents/install/plan.js";
+import { buildAggregateProjectionStep } from "./aggregate-projection-step.js";
+import { inlineMcpNotApplicablePlan } from "./inline-mcp-operation.js";
+import { installRefused, } from "./vocabulary.js";
+/**
+ * The configured-agent operations this sweep projects and verifies. A step's
+ * label carries the extension name the operation is about; the collector that
+ * produced it carries the type.
+ */
+const configuredAgentOperationsFrom = (collections) => {
+    const operations = new Map();
+    for (const { type, collection } of collections) {
+        for (const fragment of collection.fragments) {
+            if (fragment.key.startsWith("not-applicable:"))
+                continue;
+            const name = fragment.step.label.replace(/^(?:Install|Reinstall|Skip|Update)\s+/u, "");
+            operations.set(`${type}:${name}`, { extensionType: type, name, plannedState: "enabled" });
+        }
+    }
+    return [...operations.values()];
+};
+const noConfiguredMessage = (type) => Option.match(type, {
+    onNone: () => "No configured extensions.",
+    onSome: (value) => `No configured ${extensionTypePluralSentenceLabels[toInstallableExtensionTypePlural(value)]}.`,
+});
+const flattenPlanSteps = (plan) => plan.jobs.flatMap((job) => job.steps);
+const toCollectedPlans = ({ plans, holdbacks = [], bypasses = [], originForStep = () => "direct", }) => ({
+    plans,
+    holdbacks: [...holdbacks, ...plans.flatMap((plan) => plan.releaseAge?.holdbacks ?? [])],
+    bypasses: [...bypasses, ...plans.flatMap((plan) => plan.releaseAge?.bypasses ?? [])],
+    fragments: plans.flatMap((plan) => flattenPlanSteps(plan).map((step, index) => ({
+        key: step.key ?? step.label,
+        origin: originForStep(index),
+        step,
+    }))),
+});
+const attachConfiguredReleaseAge = (plan, evaluation, releaseAge) => releaseAge === undefined
+    ? plan
+    : {
+        ...plan,
+        releaseAge: {
+            evaluatedAt: DateTime.formatIso(evaluation.evaluatedAt),
+            holdbacks: normalizeReleaseAgeRecords([
+                ...releaseAge.holdbacks,
+                ...(plan.releaseAge?.holdbacks ?? []),
+            ]),
+            bypasses: normalizeReleaseAgeRecords([
+                ...releaseAge.bypasses,
+                ...(plan.releaseAge?.bypasses ?? []),
+            ]),
+        },
+    };
+/**
+ * One member declared directly and also required by a pack is installed from
+ * the direct declaration: the person who wrote it down chose that version.
+ */
+const mergeFragments = (collections) => {
+    const byKey = new Map();
+    for (const fragment of collections.flatMap((collection) => collection.fragments)) {
+        const existing = byKey.get(fragment.key);
+        if (existing === undefined) {
+            byKey.set(fragment.key, fragment);
+            continue;
+        }
+        if (existing.origin === "dependency" && fragment.origin === "direct") {
+            byKey.set(fragment.key, fragment);
+        }
+    }
+    return [...byKey.values()];
+};
+/**
+ * A resolution refusal already carries its own category and fact sentence —
+ * a held release, an unsatisfiable constraint, a blocked source authority —
+ * so it travels unchanged rather than being replaced with a generic conflict
+ * the operator cannot act on. Anything else becomes this feature's refusal,
+ * naming the configured entry that could not be resolved.
+ */
+const resolutionFailed = (name) => (cause) => cause instanceof ExtensionResolutionFailed
+    ? cause
+    : installRefused({
+        category: "conflict",
+        detail: `Configured extension "${name}" could not be resolved`,
+        cause,
+    });
+const resolvePackIntent = Effect.fn("InstallExtensions.resolveConfiguredPackIntent")(function* (args) {
+    const ws = yield* WorkspaceMutations;
+    const accepted = yield* acceptedResolutionRef({
+        workspace: ws,
+        type: "pack",
+        name: args.name,
+    }).pipe(Effect.mapError(resolutionFailed(args.name)));
+    const shared = {
+        unattended: true,
+        nonInteractive: args.nonInteractive,
+        releaseAgeEvaluation: args.releaseAgeEvaluation,
+        releaseAgeHoldbackBehavior: "preserve-or-block",
+        ...(args.forceCanonical === true ? { forceCanonical: true } : {}),
+        ...(args.deferProjections === true ? { deferProjections: true } : {}),
+    };
+    if (Option.isSome(accepted) && accepted.value.type === "pack") {
+        const packToInstall = yield* hydrateAcceptedPackRef(args.name, accepted.value);
+        return {
+            intent: {
+                packToInstall,
+                versionRange: Option.fromUndefinedOr(parseRegistrySourceRef(args.source)?.versionRange),
+                dependencyResolver: acceptedPackDependencyResolver(),
+                ...shared,
+            },
+            releaseAge: undefined,
+        };
+    }
+    const resolved = yield* resolveConfiguredPack(args.name, args.source, args.releaseAgeEvaluation).pipe(Effect.mapError(resolutionFailed(args.name)));
+    return {
+        intent: {
+            packToInstall: resolved.ref,
+            versionRange: resolved.versionRange,
+            ...shared,
+        },
+        releaseAge: "releaseAge" in resolved ? resolved.releaseAge : undefined,
+    };
+});
+const collectPackPlans = Effect.fn("InstallExtensions.collectConfiguredPacks")(function* (args) {
+    const ws = yield* WorkspaceMutations;
+    const configured = yield* ws.getConfiguredPackEntries().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Configured packs could not be read",
+        cause,
+    })));
+    const entries = enabledConfiguredEntries(configured).filter(([name]) => args.selectedNames === undefined || args.selectedNames.has(name));
+    const resolvedPacks = yield* Effect.forEach(entries, ([name, entry]) => resolvePackIntent({
+        name,
+        source: entry.source,
+        releaseAgeEvaluation: args.releaseAgeEvaluation,
+        nonInteractive: args.nonInteractive,
+        ...(args.forceCanonical === undefined ? {} : { forceCanonical: args.forceCanonical }),
+        ...(args.deferProjections === undefined ? {} : { deferProjections: args.deferProjections }),
+    }), { concurrency: "unbounded" });
+    const prospectivePacks = resolvedPacks.map(({ intent }) => intent.packToInstall);
+    const constraintProblems = yield* prospectivePackConstraintProblems({
+        workspace: ws,
+        prospectivePacks,
+        ...(args.selectedNames === undefined ? {} : { selectedNames: args.selectedNames }),
+    }).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Prospective pack constraints could not be evaluated",
+        cause,
+    })));
+    const releaseAge = resolvedPacks.flatMap(({ releaseAge }) => releaseAge === undefined ? [] : [releaseAge]);
+    if (constraintProblems.length > 0) {
+        return toCollectedPlans({
+            plans: [
+                configuredPackConstraintBlockPlan({ operation: "install", problems: constraintProblems }),
+            ],
+            holdbacks: releaseAge.flatMap((record) => record.holdbacks),
+            bypasses: releaseAge.flatMap((record) => record.bypasses),
+        });
+    }
+    const plans = yield* Effect.forEach(resolvedPacks, ({ intent, releaseAge }) => planPackInstall(intent).pipe(Effect.map((plan) => attachConfiguredReleaseAge(plan, args.releaseAgeEvaluation, releaseAge))), { concurrency: "unbounded" });
+    // A pack's own step comes first; everything after it is a member the pack
+    // brought in, and a direct declaration of that member wins over it.
+    return toCollectedPlans({
+        plans,
+        originForStep: (index) => (index === 0 ? "direct" : "dependency"),
+    });
+});
+const collectSimpleTypePlans = (type, releaseAgeEvaluation, nonInteractive) => Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const readFailed = (cause) => installRefused({
+        category: "internal",
+        detail: `Configured ${type} entries could not be read`,
+        cause,
+    });
+    const planFor = (name, source) => {
+        switch (type) {
+            case "skill":
+                return resolveConfiguredSkill(name, source, releaseAgeEvaluation).pipe(Effect.mapError(resolutionFailed(name)), Effect.flatMap((resolved) => planSkillInstall({
+                    skillsToInstall: [{ ref: resolved.ref, versionRange: resolved.versionRange }],
+                }).pipe(Effect.map((plan) => attachConfiguredReleaseAge(plan, releaseAgeEvaluation, "releaseAge" in resolved ? resolved.releaseAge : undefined)))));
+            case "subagent":
+                return resolveConfiguredSubagent(name, source, releaseAgeEvaluation).pipe(Effect.mapError(resolutionFailed(name)), Effect.flatMap((resolved) => planSubagentInstall({
+                    subagentsToInstall: [{ ref: resolved.ref, versionRange: resolved.versionRange }],
+                }).pipe(Effect.map((plan) => attachConfiguredReleaseAge(plan, releaseAgeEvaluation, "releaseAge" in resolved ? resolved.releaseAge : undefined)))));
+            case "rule":
+                return resolveConfiguredRule(name, source, releaseAgeEvaluation).pipe(Effect.mapError(resolutionFailed(name)), Effect.flatMap((resolved) => planRuleInstall({
+                    refs: [{ ref: resolved.ref, versionRange: resolved.versionRange }],
+                    deferProjections: true,
+                }).pipe(Effect.map((plan) => attachConfiguredReleaseAge(plan, releaseAgeEvaluation, "releaseAge" in resolved ? resolved.releaseAge : undefined)))));
+            case "hook":
+                return resolveConfiguredHook(name, source, releaseAgeEvaluation).pipe(Effect.mapError(resolutionFailed(name)), Effect.flatMap((resolved) => planHookInstall({
+                    refs: [{ ref: resolved.ref, versionRange: resolved.versionRange }],
+                    deferProjections: true,
+                }).pipe(Effect.map((plan) => attachConfiguredReleaseAge(plan, releaseAgeEvaluation, "releaseAge" in resolved ? resolved.releaseAge : undefined)))));
+            case "knowledge":
+                return resolveConfiguredKnowledge(name, source, releaseAgeEvaluation).pipe(Effect.mapError(resolutionFailed(name)), Effect.flatMap((resolved) => planKnowledgeInstall({
+                    refs: [{ ref: resolved.ref, versionRange: resolved.versionRange }],
+                    deferProjections: true,
+                }).pipe(Effect.map((plan) => attachConfiguredReleaseAge(plan, releaseAgeEvaluation, "releaseAge" in resolved ? resolved.releaseAge : undefined)))));
+            case "mcp-server":
+                return resolveConfiguredMcpServer(name, source, releaseAgeEvaluation).pipe(Effect.mapError(resolutionFailed(name)), Effect.flatMap((resolved) => planMcpServerInstall({
+                    ref: resolved.ref,
+                    localName: decodeExtensionNameSync(name),
+                    versionRange: resolved.versionRange,
+                    force: false,
+                    nonInteractive,
+                }).pipe(Effect.map((plan) => attachConfiguredReleaseAge(plan, releaseAgeEvaluation, "releaseAge" in resolved ? resolved.releaseAge : undefined)))));
+        }
+    };
+    switch (type) {
+        case "skill": {
+            const configured = yield* ws.getConfiguredSkillEntries().pipe(Effect.mapError(readFailed));
+            // A bundled skill is shipped with the CLI, not acquired from a source.
+            const entries = enabledConfiguredEntries(configured).filter(([, entry]) => entry.origin !== "bundled");
+            return toCollectedPlans({
+                plans: yield* Effect.forEach(entries, ([name, entry]) => planFor(name, entry.source), {
+                    concurrency: "unbounded",
+                }),
+            });
+        }
+        case "subagent": {
+            const configured = yield* ws
+                .getConfiguredSubagentEntries()
+                .pipe(Effect.mapError(readFailed));
+            return toCollectedPlans({
+                plans: yield* Effect.forEach(enabledConfiguredEntries(configured), ([name, entry]) => planFor(name, entry.source), { concurrency: "unbounded" }),
+            });
+        }
+        case "rule": {
+            const configured = yield* ws.getConfiguredRuleEntries().pipe(Effect.mapError(readFailed));
+            return toCollectedPlans({
+                plans: yield* Effect.forEach(enabledConfiguredEntries(configured), ([name, entry]) => planFor(name, entry.source), { concurrency: "unbounded" }),
+            });
+        }
+        case "hook": {
+            const configured = yield* ws.getConfiguredHookEntries().pipe(Effect.mapError(readFailed));
+            return toCollectedPlans({
+                plans: yield* Effect.forEach(enabledConfiguredEntries(configured), ([name, entry]) => planFor(name, entry.source), { concurrency: "unbounded" }),
+            });
+        }
+        case "knowledge": {
+            const configured = yield* ws
+                .getConfiguredKnowledgeEntries()
+                .pipe(Effect.mapError(readFailed));
+            return toCollectedPlans({
+                plans: yield* Effect.forEach(enabledConfiguredEntries(configured), ([name, entry]) => planFor(name, entry.source), { concurrency: "unbounded" }),
+            });
+        }
+        case "mcp-server": {
+            const configured = yield* ws
+                .getConfiguredMcpServerEntries()
+                .pipe(Effect.mapError(readFailed));
+            return toCollectedPlans({
+                plans: yield* Effect.forEach(enabledConfiguredEntries(configured), ([name, entry]) => 
+                // An inline connection is workspace configuration, not an
+                // acquired package: `axm sync` reconciles it, install does not.
+                entry.kind === "inline"
+                    ? Effect.succeed(inlineMcpNotApplicablePlan(name, "install"))
+                    : planFor(name, entry.source), { concurrency: "unbounded" }),
+            });
+        }
+    }
+});
+export const buildConfiguredPackInstallPlan = Effect.fn("InstallExtensions.buildConfiguredPackInstallPlan")(function* (args) {
+    const releaseAgeEvaluation = yield* makeConfiguredReleaseAgeEvaluation().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Release-age policy could not be evaluated",
+        cause,
+    })));
+    const collection = yield* collectPackPlans({
+        releaseAgeEvaluation,
+        nonInteractive: args.nonInteractive,
+        selectedNames: args.packNames,
+        forceCanonical: true,
+    });
+    const fragments = mergeFragments([collection]);
+    if (fragments.length === 0) {
+        const nothingConfigured = {
+            _tag: "NoConfiguredExtensions",
+            message: noConfiguredMessage(Option.some("pack")),
+        };
+        return nothingConfigured;
+    }
+    const holdbacks = normalizeReleaseAgeRecords(collection.holdbacks);
+    const bypasses = normalizeReleaseAgeRecords(collection.bypasses);
+    const settled = {
+        _tag: "ConfiguredInstallPlan",
+        plan: {
+            _tag: "Plan",
+            name: args.planName,
+            description: args.planDescription,
+            presentation: operationPresentation({ imperative: "install", past: "Installed", gerund: "Installing" }, "pack"),
+            jobs: [{ concurrency: 1, steps: fragments.map((fragment) => fragment.step) }],
+            ...(holdbacks.length === 0 && bypasses.length === 0
+                ? {}
+                : {
+                    releaseAge: {
+                        evaluatedAt: DateTime.formatIso(releaseAgeEvaluation.evaluatedAt),
+                        holdbacks,
+                        bypasses,
+                    },
+                }),
+        },
+        configuredAgentOperations: [...args.packNames].map((name) => ({
+            extensionType: "pack",
+            name,
+            plannedState: "enabled",
+        })),
+    };
+    return settled;
+});
+export const buildConfiguredInstallPlan = Effect.fn("InstallExtensions.buildConfiguredInstallPlan")(function* (args) {
+    const releaseAgeEvaluation = yield* makeConfiguredReleaseAgeEvaluation().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Release-age policy could not be evaluated",
+        cause,
+    })));
+    const selectedTypes = installableExtensionTypes.filter((type) => Option.match(args.type, { onNone: () => true, onSome: (value) => value === type }));
+    const collections = yield* Effect.forEach(selectedTypes, (type) => (type === "pack"
+        ? collectPackPlans({
+            releaseAgeEvaluation,
+            nonInteractive: args.nonInteractive,
+            deferProjections: true,
+        })
+        : collectSimpleTypePlans(type, releaseAgeEvaluation, args.nonInteractive)).pipe(Effect.map((collection) => ({ type, collection }))), { concurrency: "unbounded" });
+    const fragments = mergeFragments(collections.map(({ collection }) => collection));
+    if (fragments.length === 0) {
+        const nothingConfigured = {
+            _tag: "NoConfiguredExtensions",
+            message: noConfiguredMessage(args.type),
+        };
+        return nothingConfigured;
+    }
+    // A pack contributes rules, hooks, and knowledge bundles, so its presence
+    // implies all three aggregate units may need re-rendering.
+    const aggregateTypes = new Set();
+    for (const { type, collection } of collections) {
+        if (collection.fragments.length === 0)
+            continue;
+        if (type === "pack") {
+            aggregateTypes.add("rule");
+            aggregateTypes.add("hook");
+            aggregateTypes.add("knowledge");
+        }
+        else if (type === "rule" || type === "hook" || type === "knowledge") {
+            aggregateTypes.add(type);
+        }
+    }
+    const projectionStep = yield* buildAggregateProjectionStep({ types: aggregateTypes });
+    const holdbacks = normalizeReleaseAgeRecords(collections.flatMap(({ collection }) => collection.holdbacks));
+    const bypasses = normalizeReleaseAgeRecords(collections.flatMap(({ collection }) => collection.bypasses));
+    const settled = {
+        _tag: "ConfiguredInstallPlan",
+        plan: {
+            _tag: "Plan",
+            name: args.planName,
+            description: args.planDescription,
+            presentation: operationPresentation({ imperative: "install", past: "Installed", gerund: "Installing" }, Option.getOrUndefined(args.type)),
+            jobs: [
+                {
+                    concurrency: 1,
+                    steps: [...fragments.map((fragment) => fragment.step), ...Option.toArray(projectionStep)],
+                },
+            ],
+            ...(holdbacks.length === 0 && bypasses.length === 0
+                ? {}
+                : {
+                    releaseAge: {
+                        evaluatedAt: DateTime.formatIso(releaseAgeEvaluation.evaluatedAt),
+                        holdbacks,
+                        bypasses,
+                    },
+                }),
+        },
+        configuredAgentOperations: configuredAgentOperationsFrom(collections),
+    };
+    return settled;
+});
+//# sourceMappingURL=configured.js.map

package/dist/src/install/inline-mcp-operation.d.ts

@@ -0,0 +1,4 @@
+import type { InstallStepRequirements } from "./vocabulary.js";
+import type { Plan } from "@agentxm/workspace-operations";
+export declare const inlineMcpNotApplicablePlan: (name: string, operation: "install" | "update") => Plan<InstallStepRequirements>;
+//# sourceMappingURL=inline-mcp-operation.d.ts.map

package/dist/src/install/inline-mcp-operation.js

@@ -0,0 +1,25 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+export const inlineMcpNotApplicablePlan = (name, operation) => ({
+    _tag: "Plan",
+    name: `Skip inline MCP server ${operation}`,
+    description: Option.some(`${name} is authored directly in workspace configuration`),
+    jobs: [
+        {
+            concurrency: 1,
+            steps: [
+                {
+                    key: `not-applicable:mcp-server:${name}`,
+                    readiness: "ready",
+                    label: name,
+                    run: Effect.succeed({
+                        result: "success",
+                        disposition: "skipped",
+                        message: `${name} is inline workspace configuration; run axm sync to reconcile it`,
+                    }),
+                },
+            ],
+        },
+    ],
+});
+//# sourceMappingURL=inline-mcp-operation.js.map

package/dist/src/install/install-extensions.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Installing extensions.
+ *
+ * One use case behind seventeen command spellings. `axm install` with a
+ * registry FQN, `axm <type> install <source>`, `axm install <locator>`, and
+ * either form with no source at all are the same decision with different
+ * amounts already known: which type, which source, which versions, and which
+ * of a source's contents the person wants.
+ *
+ * `prepare` settles all of that and writes nothing. The locator form is the
+ * reason it must: a locator can carry skills, rules, hooks, knowledge bundles
+ * and subagents at once, and each is an independent closure inside one
+ * prepared candidate — so the preview shows the whole set, one type failing
+ * leaves the others committed, and the operation reports every outcome.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { type ExecutionCandidate, type OperationResolution, type PlanExecution } from "@agentxm/workspace-operations";
+import type { ExtensionResolutionFailed } from "@agentxm/extension-resolution";
+import type { ExtensionLifecycleFailed } from "../errors.js";
+import { BundledAxmSkillAsset } from "../skills/install/bundled.js";
+import { type ConfiguredInstallRequirements } from "./configured.js";
+import type { ExtensionSelectionCancelled } from "./selection-interaction.js";
+import { ExtensionSelectionInteraction } from "./selection-interaction.js";
+import { type InstallExecutionFailure, type InstallStepRequirements, type PrepareInstallRequirements } from "./vocabulary.js";
+/**
+ * What the request installs: the extensions the workspace already declares,
+ * one source a person named, or the official skill the executable carries.
+ */
+export type InstallSubject = {
+    readonly kind: "configured";
+} | {
+    readonly kind: "source";
+    readonly source: string;
+} | {
+    readonly kind: "bundled";
+};
+/** One install request, whatever command spelling produced it. */
+export interface InstallExtensionsRequest {
+    /**
+     * The type the command fixed. `none` is the root form: a registry FQN names
+     * its own type and a locator is opened to find out.
+     */
+    readonly type: Option.Option<InstallableExtensionType>;
+    readonly subject: InstallSubject;
+    /** Names or glob patterns the request named inside the source. */
+    readonly names: ReadonlyArray<string>;
+    /** Take everything the source offers without asking. */
+    readonly all: boolean;
+    /** Re-materialize even when the canonical tree already matches the lockfile. */
+    readonly reinstall: boolean;
+    /** The local connection name an MCP install writes under. */
+    readonly localName: Option.Option<string>;
+    /** `KEY=VALUE` inputs an MCP install supplies. */
+    readonly env: ReadonlyArray<string>;
+    /** No prompt can open in this invocation. */
+    readonly nonInteractive: boolean;
+    /** Human-readable name for the operation, chosen by the command. */
+    readonly planName: string;
+    readonly planDescription: Option.Option<string>;
+}
+/**
+ * Evidence the settling collected that the application may show but that no
+ * decision depends on: which registries were consulted, and which packages
+ * the selected extensions declare themselves compatible with.
+ */
+export interface InstallDiagnostics {
+    readonly resolutionLines: ReadonlyArray<string>;
+    readonly companionPackages: ReadonlyArray<string>;
+}
+/**
+ * A settled install: every decision is made and nothing is written. `types`
+ * says which extension types the prepared closures cover, so a root locator
+ * install can report the five it detected.
+ */
+export interface InstallExtensionsCandidate {
+    readonly types: ReadonlyArray<InstallableExtensionType>;
+    /** Nothing matched the request; the application renders its own no-op. */
+    readonly empty: boolean;
+    /** Present only when nothing matched: what to tell the person. */
+    readonly emptyMessage: Option.Option<string>;
+    readonly diagnostics: InstallDiagnostics;
+    readonly planName: string;
+    readonly execution: ExecutionCandidate<InstallStepRequirements | BundledAxmSkillAsset>;
+}
+/**
+ * Every failure settling an install can surface before anything is written.
+ * A configured entry's resolution refusal travels with its own category and
+ * sentence rather than as this feature's generic refusal.
+ */
+export type InstallExtensionsFailure = ExtensionLifecycleFailed | ExtensionResolutionFailed | ExtensionSelectionCancelled | InstallExecutionFailure;
+/** Settle an install without writing anything. */
+export declare const prepareInstallExtensions: (request: InstallExtensionsRequest) => Effect.Effect<InstallExtensionsCandidate, InstallExtensionsFailure, PrepareInstallRequirements | ConfiguredInstallRequirements | ExtensionSelectionInteraction | BundledAxmSkillAsset>;
+/**
+ * Everything resolving a settled install writes through: the candidate's own
+ * step requirements plus the operation boundary that presents, journals, and
+ * applies it.
+ */
+export type ResolveInstallExtensionsRequirements = PrepareInstallRequirements | BundledAxmSkillAsset;
+/** Preview or apply a settled install, resolving to one operation outcome. */
+export declare const previewOrApplyInstallExtensions: (candidate: InstallExtensionsCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution, InstallExtensionsFailure, ResolveInstallExtensionsRequirements>;
+/** The install use case: settle a request, then preview or apply it. */
+export declare const InstallExtensions: {
+    readonly prepare: (request: InstallExtensionsRequest) => Effect.Effect<InstallExtensionsCandidate, InstallExtensionsFailure, PrepareInstallRequirements | ConfiguredInstallRequirements | ExtensionSelectionInteraction | BundledAxmSkillAsset>;
+    readonly previewOrApply: (candidate: InstallExtensionsCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution, InstallExtensionsFailure, ResolveInstallExtensionsRequirements>;
+};
+//# sourceMappingURL=install-extensions.d.ts.map