@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/update/update-extensions.js

@@ -0,0 +1,579 @@
+/**
+ * Advancing what the workspace already accepted.
+ *
+ * Update is one use case with two shapes of request. A person can name one
+ * extension by its Registry identity, or ask the workspace to sweep every
+ * configured entry — optionally narrowed to one type, or to a selection of
+ * installed names. Both shapes answer the same question: within the intent
+ * the workspace recorded, is there a newer version its source is willing to
+ * offer, and may this workspace accept it?
+ *
+ * Everything that decides the answer lives here. A named update is classified
+ * against the desired graph first, so a refusal is reported before any
+ * Registry is contacted: an extension the workspace never asked for is not
+ * installed on its behalf, a Pack-owned member is not forked into direct
+ * intent, and a bundled or workspace-authored source is never replaced from
+ * the Registry. A sweep resolves each configured entry independently, so one
+ * unreachable source blocks one unit rather than the operation.
+ *
+ * `prepare` settles all of it and writes nothing: it produces either a frozen
+ * execution candidate or the settled reason there is nothing to execute.
+ * `previewOrApply` resolves that same candidate, so the preview a person
+ * reads and the apply that follows describe one decision.
+ *
+ * @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 { parseSourceQualifiedRegistrySourcePatternParts, decodeExtensionNameSync, } from "@agentxm/extension-model/unstable/extensions";
+import { decodeVersionRangeSync, versionSatisfiesRange, } from "@agentxm/extension-model/unstable/version-constraints";
+import { ReleaseAgePosture, makeConfiguredReleaseAgeEvaluation, normalizeReleaseAgeRecords, resolveTargetedUpdateContext, } from "@agentxm/extension-resolution";
+import { SourceHostProviders, WorkspaceCatalog, resolveSource, } from "@agentxm/extension-sources";
+import { makeOperationResolution, operationPresentation, prepareExecutionCandidate, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, WorkspaceRecords, acceptedResolutionRef, usableAcceptedCanonical, } from "@agentxm/workspace-state";
+import { ExtensionLifecycleFailed } from "../errors.js";
+import { buildPackMemberInstallStep } from "../packs/member-install-step.js";
+import { withPublisherTrust } from "../publisher-binding.js";
+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 { planRuleInstall } from "../rules/install/plan.js";
+import { planSkillInstall } from "../skills/install/plan.js";
+import { planSubagentInstall } from "../subagents/install/plan.js";
+import { blockerClass, blockerDetail, staleOutputContext } from "./blockers.js";
+import { buildWorkspaceUpdatePlan } from "./configured.js";
+import { resolveConfiguredUpdateSelection } from "./selector.js";
+import { resolveRootUpdateIntent } from "./root-request.js";
+import { wrapTargetedUpdatePlan } from "./targeted-plan.js";
+// -----------------------------------------------------------------------------
+// Release-age evidence
+// -----------------------------------------------------------------------------
+const updatePresentation = (type) => operationPresentation({ imperative: "update", past: "Updated", gerund: "Updating" }, type);
+const releaseAgeRecord = (args) => ({
+    reason: "minimum-release-age",
+    target: args.intent.target,
+    dependencyPath: [args.intent.target],
+    ...Option.match(args.intent.versionRange, {
+        onNone: () => ({}),
+        onSome: (requestedRange) => ({ requestedRange }),
+    }),
+    ...(args.currentVersion === undefined ? {} : { currentVersion: args.currentVersion }),
+    ...(args.selectedVersion === undefined ? {} : { selectedVersion: args.selectedVersion }),
+    candidateVersion: args.evidence.version,
+    publishedAt: args.evidence.publishedAt,
+    eligibleAt: args.evidence.eligibleAt,
+    minimumReleaseAgeSeconds: args.evidence.minimumReleaseAgeSeconds,
+});
+// -----------------------------------------------------------------------------
+// Desired-state facts a targeted update is decided against
+// -----------------------------------------------------------------------------
+const normalizedPackIdentity = (identity) => identity.startsWith("workspace:") ? identity.slice("workspace:".length) : identity;
+const desiredNodeForIntent = (graph, intent) => graph.nodes.find((node) => {
+    if (node.type !== intent.type)
+        return false;
+    if (normalizedPackIdentity(node.identity) === intent.target)
+        return true;
+    if (node.type !== "mcp-server" || node.source === undefined)
+        return false;
+    const parsed = parseSourceQualifiedRegistrySourcePatternParts(node.source);
+    return (parsed?.name !== undefined &&
+        `${parsed.owner}/${parsed.type}/${parsed.name}` === intent.target);
+});
+/**
+ * The version a held release would preserve: the accepted one, when it is
+ * still usable, still the same package, and still inside the requested range.
+ * A Pack preserves only when its whole member closure is usable too.
+ */
+const preservableRegistryVersion = Effect.fn("UpdateExtensions.preservableVersion")(function* (intent) {
+    const workspace = yield* WorkspaceMutations;
+    const graph = yield* workspace.getDesiredStateGraph();
+    if (!graph.complete)
+        return Option.none();
+    const desired = desiredNodeForIntent(graph, intent);
+    if (desired === undefined)
+        return Option.none();
+    const canonical = yield* usableAcceptedCanonical({
+        workspace,
+        type: intent.type,
+        name: desired.name,
+    });
+    if (Option.isNone(canonical))
+        return Option.none();
+    const ref = canonical.value.ref;
+    if (ref.refType !== "registry" || ref.owner !== intent.owner || ref.name !== intent.name) {
+        return Option.none();
+    }
+    if (Option.isSome(intent.versionRange) &&
+        !versionSatisfiesRange(ref.version, decodeVersionRangeSync(intent.versionRange.value))) {
+        return Option.none();
+    }
+    if (intent.type === "pack") {
+        const graphNodes = graph.nodes.filter((node) => (node.type === "pack" && node.name === intent.name) ||
+            node.origins.some((origin) => origin.type === "pack" && normalizedPackIdentity(origin.pack) === intent.target));
+        const usable = yield* Effect.forEach(graphNodes, (node) => usableAcceptedCanonical({ workspace, type: node.type, name: node.name }).pipe(Effect.map(Option.isSome)));
+        if (usable.some((value) => !value))
+            return Option.none();
+    }
+    return Option.some(ref.version);
+});
+/** The accepted version a resolution must not fall below, when there is one. */
+const acceptedRegistryFloor = Effect.fn("UpdateExtensions.acceptedFloor")(function* (intent) {
+    const workspace = yield* WorkspaceMutations;
+    const graph = yield* workspace.getDesiredStateGraph();
+    const desired = desiredNodeForIntent(graph, intent);
+    if (desired === undefined) {
+        return Option.none();
+    }
+    const accepted = yield* acceptedResolutionRef({
+        workspace,
+        type: intent.type,
+        name: desired.name,
+    });
+    return Option.flatMap(accepted, (ref) => ref.refType === "registry" && ref.owner === intent.owner && ref.name === intent.name
+        ? Option.some({ version: ref.version, publisherBindingId: ref.publisherBindingId })
+        : Option.none());
+});
+// -----------------------------------------------------------------------------
+// Per-type planning from one resolved ref
+// -----------------------------------------------------------------------------
+/**
+ * Plan the advance for one resolved Registry ref through the same per-type
+ * planner the install routes use: advancing an accepted resolution is
+ * installing the version its source now offers.
+ */
+const planResolvedTarget = Effect.fn("UpdateExtensions.planResolvedTarget")(function* (args) {
+    const { intent, ref, versionRange } = args;
+    const mismatch = () => Effect.fail(new ExtensionLifecycleFailed({
+        category: "internal",
+        detail: `Registry resolved ${intent.target} as ${ref.type}, expected ${intent.type}`,
+    }));
+    switch (intent.type) {
+        case "skill":
+            return ref.type !== "skill"
+                ? yield* mismatch()
+                : yield* planSkillInstall({ skillsToInstall: [{ ref, versionRange }] });
+        case "subagent":
+            return ref.type !== "subagent"
+                ? yield* mismatch()
+                : yield* planSubagentInstall({ subagentsToInstall: [{ ref, versionRange }] });
+        case "rule":
+            return ref.type !== "rule"
+                ? yield* mismatch()
+                : yield* planRuleInstall({ refs: [{ ref, versionRange }] });
+        case "hook":
+            return ref.type !== "hook"
+                ? yield* mismatch()
+                : yield* planHookInstall({ refs: [{ ref, versionRange }] });
+        case "knowledge":
+            return ref.type !== "knowledge"
+                ? yield* mismatch()
+                : yield* planKnowledgeInstall({ refs: [{ ref, versionRange }] });
+        case "mcp-server": {
+            if (ref.type !== "mcp-server")
+                return yield* mismatch();
+            const workspace = yield* WorkspaceMutations;
+            const graph = yield* workspace.getDesiredStateGraph();
+            const desired = desiredNodeForIntent(graph, intent);
+            return yield* planMcpServerInstall({
+                ref,
+                localName: decodeExtensionNameSync(desired?.name ?? ref.server.name),
+                versionRange: Option.map(versionRange, (range) => range),
+                force: false,
+                nonInteractive: args.nonInteractive,
+            });
+        }
+        case "pack":
+            return ref.type !== "pack"
+                ? yield* mismatch()
+                : yield* planPackInstall({
+                    packToInstall: ref,
+                    versionRange,
+                    unattended: true,
+                    nonInteractive: args.nonInteractive,
+                    releaseAgeEvaluation: args.releaseAgeEvaluation,
+                    releaseAgeHoldbackBehavior: "preserve-or-block",
+                });
+    }
+});
+// -----------------------------------------------------------------------------
+// Targeted preparation
+// -----------------------------------------------------------------------------
+const blockedCandidate = (context) => ({
+    outcome: "blocked",
+    name: `Update ${context.target.fqn}`,
+    detail: blockerDetail(context),
+    subject: context.target.fqn,
+    subjectType: context.target.type,
+    blockingClass: blockerClass(context.blocker),
+    ...(context.blocker === undefined ? {} : { reference: context.blocker }),
+    targetedContext: context,
+});
+/**
+ * A Pack is classified as a closure rather than a member, so the
+ * member-oriented blockers never see it. Desired state still gates it:
+ * updating a Pack the workspace never asked for would acquire the Pack and
+ * its whole member closure.
+ */
+const blockedUndesiredPack = (intent) => ({
+    outcome: "blocked",
+    name: `Update ${intent.target}`,
+    detail: `${intent.target} is not desired by this workspace`,
+    subject: intent.target,
+    subjectType: intent.type,
+    blockingClass: "precondition-unmet",
+    reference: "not-desired",
+});
+/** The outcome a held release settles into: preserve, or block with evidence. */
+const heldCandidate = Effect.fn("UpdateExtensions.heldCandidate")(function* (args) {
+    const currentVersion = yield* preservableRegistryVersion(args.intent);
+    const record = releaseAgeRecord({
+        intent: args.intent,
+        evidence: args.evidence,
+        ...(Option.isNone(currentVersion)
+            ? {}
+            : { currentVersion: currentVersion.value, selectedVersion: currentVersion.value }),
+    });
+    const releaseAge = {
+        evaluatedAt: args.evaluatedAt,
+        holdbacks: [record],
+        bypasses: [],
+    };
+    if (Option.isSome(currentVersion)) {
+        return {
+            outcome: "preserved",
+            name: `Update ${args.intent.target}`,
+            description: `Preserve ${args.intent.target} until its selected release is eligible`,
+            subjectType: args.intent.type,
+            releaseAge,
+            ...(args.context === undefined ? {} : { targetedContext: args.context }),
+        };
+    }
+    return {
+        outcome: "blocked",
+        name: `Update ${args.intent.target}`,
+        detail: `${args.intent.target}'s selected release is held by the minimum release age until ${args.evidence.eligibleAt}`,
+        subject: args.intent.target,
+        subjectType: args.intent.type,
+        blockingClass: "policy-excluded",
+        reference: "release-age-held",
+        releaseAge,
+        ...(args.context === undefined ? {} : { targetedContext: args.context }),
+    };
+});
+/** Settle a request that names one extension by its Registry identity. */
+const prepareTargeted = Effect.fn("UpdateExtensions.prepareTargeted")(function* (request) {
+    const intent = yield* resolveRootUpdateIntent(request.source);
+    let targetedContext;
+    if (intent.type === "pack") {
+        const workspace = yield* WorkspaceMutations;
+        const graph = yield* workspace.getDesiredStateGraph();
+        if (desiredNodeForIntent(graph, intent) === undefined) {
+            return blockedUndesiredPack(intent);
+        }
+    }
+    else {
+        targetedContext = yield* resolveTargetedUpdateContext({
+            target: { type: intent.type, name: intent.name, fqn: intent.target },
+            ...(Option.isNone(intent.versionRange) ? {} : { explicitRange: intent.versionRange.value }),
+        });
+        if (targetedContext.public.blocker !== undefined) {
+            return blockedCandidate(targetedContext.public);
+        }
+    }
+    const releaseAgeEvaluation = yield* makeConfiguredReleaseAgeEvaluation();
+    const evaluatedAtText = DateTime.formatIso(releaseAgeEvaluation.evaluatedAt);
+    const source = yield* resolveSource(intent.source);
+    if (source.type !== "registry") {
+        return yield* new ExtensionLifecycleFailed({
+            category: "usage",
+            detail: "Root update requires a Registry FQN",
+        });
+    }
+    const providers = yield* SourceHostProviders;
+    const accepted = yield* acceptedRegistryFloor(intent);
+    const selected = yield* providers.resolveNamedRegistry(source, {
+        name: intent.name,
+        type: intent.type,
+        owner: intent.owner,
+        versionRange: targetedContext?.public.effectiveConstraint === undefined
+            ? intent.versionRange
+            : Option.some(decodeVersionRangeSync(targetedContext.public.effectiveConstraint)),
+        releaseAgeEvaluation,
+        ...(Option.isSome(accepted) ? { accepted: accepted.value } : {}),
+    });
+    if (selected.kind === "not_found") {
+        return yield* new ExtensionLifecycleFailed({
+            category: "not_found",
+            detail: `Registry extension "${selected.target}" was not found`,
+        });
+    }
+    if (selected.kind === "version_unsatisfied") {
+        return yield* new ExtensionLifecycleFailed({
+            category: "conflict",
+            title: "No compatible version",
+            detail: `No visible version of "${selected.target}" satisfies ${selected.requestedRange}`,
+        });
+    }
+    if (selected.kind === "policy_held") {
+        return yield* heldCandidate({
+            intent,
+            evidence: selected.candidate,
+            evaluatedAt: evaluatedAtText,
+            ...(targetedContext === undefined ? {} : { context: targetedContext.public }),
+        });
+    }
+    // A Pack-owned member advances inside its Pack's graph, so its step is the
+    // member transition rather than a direct install: nothing writes a direct
+    // declaration the workspace did not ask for.
+    const plan = targetedContext?.public.authority === "pack-aware"
+        ? yield* wrapTargetedUpdatePlan({
+            plan: yield* withPublisherTrust({
+                _tag: "Plan",
+                name: `Update ${intent.target}`,
+                description: Option.some(`Update pack-derived member ${intent.target}`),
+                jobs: [
+                    {
+                        concurrency: 1,
+                        steps: [
+                            yield* buildPackMemberInstallStep({
+                                ref: yield* requirePackMemberRef(intent, selected.ref),
+                                graphComplete: true,
+                                nonInteractive: request.nonInteractive,
+                            }),
+                        ],
+                    },
+                ],
+            }),
+            context: targetedContext,
+        })
+        : yield* planTargetedDirect({
+            intent,
+            ref: selected.ref,
+            nonInteractive: request.nonInteractive,
+            releaseAgeEvaluation,
+            ...(targetedContext === undefined ? {} : { context: targetedContext }),
+        });
+    const holdbacks = selected.kind === "exempted" || selected.newerHeld === undefined
+        ? []
+        : [
+            releaseAgeRecord({
+                intent,
+                evidence: selected.newerHeld,
+                selectedVersion: selected.ref.version,
+                ...(Option.isSome(accepted) && accepted.value.version === selected.ref.version
+                    ? { currentVersion: accepted.value.version }
+                    : {}),
+            }),
+        ];
+    const bypasses = selected.kind === "selected"
+        ? []
+        : [
+            {
+                ...releaseAgeRecord({
+                    intent,
+                    evidence: selected.bypassed,
+                    selectedVersion: selected.ref.version,
+                }),
+                ...selected.exemption,
+            },
+        ];
+    return {
+        outcome: "planned",
+        subjectType: intent.type,
+        execution: yield* prepareExecutionCandidate(plan),
+        releaseAge: { evaluatedAt: evaluatedAtText, holdbacks, bypasses },
+        ...(targetedContext === undefined
+            ? {}
+            : { targetedContext: targetedContext.public, fingerprintedContext: targetedContext }),
+    };
+});
+/** A Pack member step accepts every installable ref except a nested Pack. */
+const requirePackMemberRef = (intent, ref) => ref.type === "pack"
+    ? Effect.fail(new ExtensionLifecycleFailed({
+        category: "internal",
+        detail: `Registry resolved ${intent.target} as an unexpected pack`,
+    }))
+    : ref.type !== intent.type
+        ? Effect.fail(new ExtensionLifecycleFailed({
+            category: "internal",
+            detail: `Registry resolved ${intent.target} as ${ref.type}, expected ${intent.type}`,
+        }))
+        : Effect.succeed(ref);
+/**
+ * Plan a direct advance. The durable range a direct declaration keeps is the
+ * one the request named, or the one the declaration already recorded — a
+ * targeted update never widens the intent the workspace expressed.
+ */
+const planTargetedDirect = Effect.fn("UpdateExtensions.planTargetedDirect")(function* (args) {
+    const { intent, context } = args;
+    const durableRange = intent.type === "pack"
+        ? intent.versionRange
+        : Option.fromUndefinedOr(Option.getOrUndefined(intent.versionRange) ?? context?.public.direct?.constraint).pipe(Option.map(decodeVersionRangeSync));
+    const planned = yield* planResolvedTarget({
+        intent,
+        ref: args.ref,
+        versionRange: durableRange,
+        nonInteractive: args.nonInteractive,
+        releaseAgeEvaluation: args.releaseAgeEvaluation,
+    });
+    if (context === undefined) {
+        return {
+            ...planned,
+            presentation: updatePresentation(intent.type),
+        };
+    }
+    return yield* wrapTargetedUpdatePlan({
+        plan: yield* withPublisherTrust(planned),
+        context,
+        ...(Option.isNone(intent.versionRange) ? {} : { explicitRange: intent.versionRange.value }),
+    });
+});
+// -----------------------------------------------------------------------------
+// Configured preparation
+// -----------------------------------------------------------------------------
+/**
+ * Which configured-agent outcomes the candidate projects: every selected name
+ * whose unit can actually converge. A unit that is not applicable, or that
+ * failed to plan, is excluded — projecting an outcome for it would promise an
+ * agent state nothing is going to establish.
+ */
+const configuredAgentOperations = (plan, type, names) => Option.match(type, {
+    onNone: () => [],
+    onSome: (extensionType) => {
+        const nonConverging = new Set(plan.jobs.flatMap((job) => job.steps.flatMap((step) => step.key?.startsWith("not-applicable:") === true ||
+            step.key?.endsWith(":planning-error") === true
+            ? [step.label]
+            : [])));
+        return [
+            ...new Set(names ??
+                plan.jobs.flatMap((job) => job.steps.map((step) => step.label.replace(/^(?:Skip|Update)\s+/u, "")))),
+        ]
+            .filter((name) => !nonConverging.has(name))
+            .map((name) => ({ extensionType, name, plannedState: "enabled" }));
+    },
+});
+/** Settle a request that sweeps the configured entries. */
+const prepareConfigured = Effect.fn("UpdateExtensions.prepareConfigured")(function* (request) {
+    const nothingToAdvance = (message) => ({
+        outcome: "nothing-configured",
+        message,
+        subjectType: Option.getOrElse(request.type, () => "mixed"),
+        planDescription: request.planDescription,
+    });
+    const selection = request.selector === undefined
+        ? { _tag: "All" }
+        : yield* resolveConfiguredUpdateSelection(request.selector);
+    if (selection._tag === "NoMatch")
+        return nothingToAdvance(selection.message);
+    const names = selection._tag === "Names" ? selection.names : undefined;
+    const result = yield* buildWorkspaceUpdatePlan({
+        type: request.type,
+        planName: request.planName,
+        planDescription: request.planDescription,
+        nonInteractive: request.nonInteractive,
+        ...(names === undefined ? {} : { names }),
+    });
+    if (result._tag === "NoConfiguredExtensions") {
+        return nothingToAdvance(result.message);
+    }
+    // Every Registry acceptance the sweep proposed is classified against the
+    // accepted resolution, so a replaced publisher binding carries the same
+    // interactive-only condition here as on the install routes.
+    const plan = yield* withPublisherTrust(result.plan);
+    return {
+        outcome: "planned",
+        subjectType: Option.getOrElse(request.type, () => "mixed"),
+        execution: yield* prepareExecutionCandidate(plan, {
+            configuredAgentOperations: configuredAgentOperations(plan, request.type, names),
+        }),
+        ...(names === undefined ? {} : { selectedNames: names }),
+    };
+});
+// -----------------------------------------------------------------------------
+// prepare
+// -----------------------------------------------------------------------------
+/**
+ * Settle an update: read the request, decide what may advance, and freeze
+ * either the execution candidate or the reason there is nothing to execute.
+ */
+export const prepareUpdate = Effect.fn("UpdateExtensions.prepare")(function* (request) {
+    return request.kind === "targeted"
+        ? yield* prepareTargeted(request)
+        : yield* prepareConfigured(request);
+});
+// -----------------------------------------------------------------------------
+// previewOrApply
+// -----------------------------------------------------------------------------
+/** A settled refusal or preservation, said as one operation outcome. */
+const settledResolution = (candidate, execution) => {
+    const mode = execution.request.mode;
+    switch (candidate.outcome) {
+        case "blocked":
+            return makeOperationResolution({
+                name: candidate.name,
+                description: Option.some(candidate.detail),
+                mode,
+                atomicity: { declared: "closure-atomic", applied: "closure-atomic" },
+                units: [],
+                presentation: updatePresentation(candidate.subjectType),
+                ...(candidate.releaseAge === undefined ? {} : { releaseAge: candidate.releaseAge }),
+                blocking: {
+                    class: candidate.blockingClass,
+                    subject: candidate.subject,
+                    phase: "planning",
+                    detail: candidate.detail,
+                    causeCode: "conflict",
+                    ...(candidate.reference === undefined ? {} : { reference: candidate.reference }),
+                },
+            });
+        case "preserved":
+            return makeOperationResolution({
+                name: candidate.name,
+                description: Option.some(candidate.description),
+                mode,
+                atomicity: { declared: "closure-atomic", applied: "closure-atomic" },
+                units: [],
+                presentation: updatePresentation(candidate.subjectType),
+                releaseAge: candidate.releaseAge,
+            });
+    }
+};
+/**
+ * Preview or apply a settled update, resolving to one operation outcome.
+ *
+ * A sweep that found nothing configured has no operation to resolve: the
+ * application reports it as the no-op it is, so this takes only the
+ * candidates that do describe an operation.
+ */
+export const previewOrApplyUpdate = (candidate, execution) => candidate.outcome === "planned"
+    ? resolveExecutionCandidate(candidate.execution, execution).pipe(Effect.map((resolution) => candidate.releaseAge === undefined
+        ? resolution
+        : {
+            ...resolution,
+            releaseAge: {
+                evaluatedAt: candidate.releaseAge.evaluatedAt,
+                holdbacks: normalizeReleaseAgeRecords([
+                    ...candidate.releaseAge.holdbacks,
+                    ...(resolution.releaseAge?.holdbacks ?? []),
+                ]),
+                bypasses: normalizeReleaseAgeRecords([
+                    ...candidate.releaseAge.bypasses,
+                    ...(resolution.releaseAge?.bypasses ?? []),
+                ]),
+            },
+        }))
+    : Effect.succeed(settledResolution(candidate, execution));
+/**
+ * The ownership context an outcome reports: a stale-candidate outcome says
+ * nothing moved, whatever the classification said before the transition.
+ */
+export const contextForResolution = (context, resolution) => resolution.blocking?.class === "stale-candidate" ? staleOutputContext(context) : context;
+/** The update use case: settle a request, then preview or apply it. */
+export const UpdateExtensions = {
+    prepare: prepareUpdate,
+    previewOrApply: previewOrApplyUpdate,
+};
+//# sourceMappingURL=update-extensions.js.map

package/dist/src/workspace-paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Stable workspace-relative paths a plan and its result name.
+ *
+ * A removal reports what it touched — settings, the lockfile, the canonical
+ * package — as paths a person can open. They are derived from the workspace
+ * layout rather than from where the workspace happens to sit on disk, so the
+ * same operation reads identically from any checkout.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as Path from "effect/Path";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import type { WorkspaceMutationsService } from "@agentxm/workspace-state";
+/** Where the workspace's settings file sits, relative to the workspace root. */
+export declare const workspaceSettingsPath: (scope: WorkspaceScope) => string;
+/** Where the workspace's lockfile sits, relative to the workspace root. */
+export declare const workspaceLockfilePath: (scope: WorkspaceScope) => string;
+/** The root every acquired package sits under, relative to the workspace root. */
+export declare const workspaceCanonicalRoot: (scope: WorkspaceScope) => string;
+/** One acquired package's path, relative to the workspace root. */
+export declare const workspaceCanonicalPath: (scope: WorkspaceScope, relativePath: string) => string;
+/** Where one desired-graph node's package sits, authored or acquired. */
+export declare const workspaceCanonicalNodePath: (path: Path.Path, ws: WorkspaceMutationsService, node: {
+    readonly type: ExtensionType;
+    readonly name: string;
+    readonly identity: string;
+}) => string;
+/** Where a workspace-authored package of this type and name sits. */
+export declare const workspaceAuthoredPath: (path: Path.Path, ws: WorkspaceMutationsService, type: ExtensionType, name: string) => string;
+//# sourceMappingURL=workspace-paths.d.ts.map

package/dist/src/workspace-paths.js

@@ -0,0 +1,46 @@
+/**
+ * Stable workspace-relative paths a plan and its result name.
+ *
+ * A removal reports what it touched — settings, the lockfile, the canonical
+ * package — as paths a person can open. They are derived from the workspace
+ * layout rather than from where the workspace happens to sit on disk, so the
+ * same operation reads identically from any checkout.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/** Where the workspace's settings file sits, relative to the workspace root. */
+export const workspaceSettingsPath = (scope) => scope === "project" ? "axm.json" : ".axm/workspace/axm.json";
+/** Where the workspace's lockfile sits, relative to the workspace root. */
+export const workspaceLockfilePath = (scope) => scope === "project" ? "axm-lock.yaml" : ".axm/workspace/axm-lock.yaml";
+/** The root every acquired package sits under, relative to the workspace root. */
+export const workspaceCanonicalRoot = (scope) => scope === "project" ? "agent_extensions" : ".axm/workspace/agent_extensions";
+/** One acquired package's path, relative to the workspace root. */
+export const workspaceCanonicalPath = (scope, relativePath) => `${workspaceCanonicalRoot(scope)}/${relativePath.replace(/^\/+/, "")}`;
+const extensionDirectory = {
+    skill: "skills",
+    "mcp-server": "mcps",
+    subagent: "subagents",
+    rule: "rules",
+    hook: "hooks",
+    knowledge: "knowledge",
+    pack: "packs",
+};
+/** Where one desired-graph node's package sits, authored or acquired. */
+export const workspaceCanonicalNodePath = (path, ws, node) => {
+    if (node.identity.startsWith("workspace:") && ws.layout.scope === "project") {
+        return path.join(path.relative(ws.baseDir, ws.layout.authoredRoot(node.type)), node.name);
+    }
+    const identity = node.identity.startsWith("workspace:")
+        ? node.identity.slice("workspace:".length)
+        : node.identity;
+    return workspaceCanonicalPath(ws.scope, identity);
+};
+/** Where a workspace-authored package of this type and name sits. */
+export const workspaceAuthoredPath = (path, ws, type, name) => {
+    if (ws.layout.scope === "project") {
+        return path.join(path.relative(ws.baseDir, ws.layout.authoredRoot(type)), name);
+    }
+    const owner = ws.layout.owner ?? "@workspace";
+    return workspaceCanonicalPath(ws.scope, `${owner}/${extensionDirectory[type]}/${name}`);
+};
+//# sourceMappingURL=workspace-paths.js.map