@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/activation/display-paths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Stable workspace-relative paths an activation plan shows the operator.
+ *
+ * Deliberately duplicated from the application's display-path helper: a
+ * feature package may not depend on application presentation utilities, and
+ * these are small pure functions over the workspace scope, within the
+ * sanctioned duplication budget.
+ *
+ * @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";
+export declare const settingsDisplayPath: (scope: WorkspaceScope) => string;
+export declare const lockfileDisplayPath: (scope: WorkspaceScope) => string;
+export declare const canonicalRootDisplayPath: (scope: WorkspaceScope) => string;
+export declare const canonicalDisplayPath: (scope: WorkspaceScope, relativePath: string) => string;
+/** Where a desired node's canonical content lives, workspace-relative. */
+export declare const canonicalNodeDisplayPath: (path: Path.Path, ws: WorkspaceMutationsService, node: {
+    readonly type: ExtensionType;
+    readonly name: string;
+    readonly identity: string;
+}) => string;
+//# sourceMappingURL=display-paths.d.ts.map

package/dist/src/activation/display-paths.js

@@ -0,0 +1,25 @@
+/**
+ * Stable workspace-relative paths an activation plan shows the operator.
+ *
+ * Deliberately duplicated from the application's display-path helper: a
+ * feature package may not depend on application presentation utilities, and
+ * these are small pure functions over the workspace scope, within the
+ * sanctioned duplication budget.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const settingsDisplayPath = (scope) => scope === "project" ? "axm.json" : ".axm/workspace/axm.json";
+export const lockfileDisplayPath = (scope) => scope === "project" ? "axm-lock.yaml" : ".axm/workspace/axm-lock.yaml";
+export const canonicalRootDisplayPath = (scope) => scope === "project" ? "agent_extensions" : ".axm/workspace/agent_extensions";
+export const canonicalDisplayPath = (scope, relativePath) => `${canonicalRootDisplayPath(scope)}/${relativePath.replace(/^\/+/, "")}`;
+/** Where a desired node's canonical content lives, workspace-relative. */
+export const canonicalNodeDisplayPath = (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 canonicalDisplayPath(ws.scope, identity);
+};
+//# sourceMappingURL=display-paths.js.map

package/dist/src/activation/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Failures resolving a settled activation through the plan pipeline.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { ApprovalRecoveryMissing, CandidateFingerprintFailed, PlanInteractionFailed } from "@agentxm/workspace-operations";
+import type { LockfileValidationError, WorkspaceSettingsReadFailure } from "@agentxm/workspace-state";
+import type { WorkspaceTransitionAcquireFailure } from "@agentxm/workspace-transactions";
+/**
+ * Every failure resolving a settled activation can surface: the approval and
+ * interaction refusals, the candidate revalidation, and the transition the
+ * apply could not acquire. Step failures travel inside the resolution rather
+ * than being raised, so the operator still sees what each closure settled.
+ */
+export type SetActivationExecutionFailure = ApprovalRecoveryMissing | CandidateFingerprintFailed | LockfileValidationError | PlanInteractionFailed | WorkspaceSettingsReadFailure | WorkspaceTransitionAcquireFailure;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/activation/errors.js

@@ -0,0 +1,7 @@
+/**
+ * Failures resolving a settled activation through the plan pipeline.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export {};
+//# sourceMappingURL=errors.js.map

package/dist/src/activation/set-activation.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Activation: turning one installed extension on or off without changing
+ * what the workspace acquired.
+ *
+ * All seven extension types share one request, one settled candidate, and one
+ * resolution, because activation means the same thing for every type: desired
+ * state records the preference, and the projections that preference implies
+ * are created or removed. What differs is only how a type is projected — a
+ * skill through agent artifacts, an MCP server through each agent's native
+ * configuration, a rule or Knowledge bundle through a shared managed region,
+ * a Pack through the members it contributes.
+ *
+ * Two invariants hold across every type. Disabling never removes canonical
+ * content or retires an accepted resolution, so re-enabling never re-resolves
+ * or re-acquires. And a type whose projection shares a file with instruction
+ * management reconciles that file inside the same transaction, so the
+ * workspace is never left with a settings change the files do not reflect.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import type * as Scope from "effect/Scope";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import { SourceHostProviders, WorkspaceCatalog, type SourceResolutionFailure } from "@agentxm/extension-sources";
+import { ExtensionManagers, SubagentManager, type ExtensionManagerFailure, type ManagerRequirements, type McpServerInstallRequirements, type RecipeRequirements } from "@agentxm/extension-materialization";
+import { ReleaseAgePosture, type ExtensionResolutionFailed, type PackDependencyResolutionFailure, type SourceAuthorityBlocked } from "@agentxm/extension-resolution";
+import { CodingAgentRepository, type ProjectionParticipantRequirements, type ResolvedInstructionsConfig } from "@agentxm/workspace-projection";
+import { OperationJournal, ResolvePlanInteraction, type JobStepArtifact, type OperationResolution, type PlanExecution } from "@agentxm/workspace-operations";
+import { ConfiguredAgentOutcomesProvider, type ConfiguredAgentOutcome, WorkspaceMutations, type DesiredExtensionNode, type AcceptedCanonicalRefError } from "@agentxm/workspace-state";
+import { FootprintRecorder, WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { ExtensionLifecycleFailed } from "../errors.js";
+import { StepFailureConversion } from "../step-failure-conversion.js";
+import type { SetActivationExecutionFailure } from "./errors.js";
+/** Turn one installed extension on or off. */
+export interface SetActivationRequest {
+    readonly type: ExtensionType;
+    /** As the operator named it: a bare name or a fully-qualified identifier. */
+    readonly name: string;
+    readonly enabled: boolean;
+}
+/** A request the workspace already satisfies. */
+export interface ActivationUnchanged {
+    readonly _tag: "Unchanged";
+    readonly type: ExtensionType;
+    readonly name: string;
+    readonly enabled: boolean;
+    readonly message: string;
+}
+/** How the settled activation is realized, by what the type projects into. */
+export type ActivationTransition = 
+/** A per-agent artifact tree the type's own executor owns. */
+{
+    readonly kind: "skill";
+} | {
+    readonly kind: "subagent";
+} | {
+    readonly kind: "mcp-server";
+}
+/** Enabling re-runs the configured install closure for the accepted entry. */
+ | {
+    readonly kind: "reinstall";
+    readonly ref: ExtensionRef;
+    readonly versionRange: Option.Option<string>;
+}
+/** Disabling flips the preference and dematerializes the type's projection. */
+ | {
+    readonly kind: "deactivate-rule";
+} | {
+    readonly kind: "deactivate-hook";
+}
+/** Rendering the discovery region is what deactivation means for Knowledge. */
+ | {
+    readonly kind: "deactivate-knowledge";
+}
+/** A Pack contributes members; activation moves the whole member closure. */
+ | {
+    readonly kind: "pack";
+    readonly identity: string;
+    /** Members whose active/inactive state this change decides. */
+    readonly members: ReadonlyArray<DesiredExtensionNode>;
+    /** Member types whose shared aggregate units re-render once at the end. */
+    readonly aggregateTypes: ReadonlySet<ExtensionType>;
+};
+/** A settled activation change: everything the plan needs, decided. */
+export interface SetActivationCandidate {
+    readonly _tag: "SetActivation";
+    readonly type: ExtensionType;
+    /** The installed name, after resolving a fully-qualified identifier. */
+    readonly name: string;
+    readonly enabled: boolean;
+    readonly scope: WorkspaceScope;
+    readonly artifact: JobStepArtifact;
+    readonly transition: ActivationTransition;
+    /** The instruction configuration this change reconciles inside its transaction. */
+    readonly instructions: Option.Option<ResolvedInstructionsConfig>;
+    /** The refusal that stops the change before it is offered, when there is one. */
+    readonly blocked: Option.Option<ExtensionLifecycleFailed>;
+    /** A holdback or lifecycle warning the operator sees before approving. */
+    readonly warning: Option.Option<string>;
+    /** Per-agent outcomes this change projects, where the type reports them. */
+    readonly agentOutcomes: ReadonlyArray<ConfiguredAgentOutcome>;
+}
+/** Every failure settling an activation request can surface. */
+export type SetActivationFailure = AcceptedCanonicalRefError | ExtensionLifecycleFailed | ExtensionManagerFailure | ExtensionResolutionFailed | PackDependencyResolutionFailure | SourceAuthorityBlocked | SourceResolutionFailure;
+/** Everything settling and resolving an activation needs. */
+export type SetActivationRequirements = CodingAgentRepository | ConfiguredAgentOutcomesProvider | ExtensionManagers | FileSystem.FileSystem | FootprintRecorder | HttpClient.HttpClient | ManagerRequirements | OperationJournal | Path.Path | McpServerInstallRequirements | ProjectionParticipantRequirements | RecipeRequirements | ReleaseAgePosture | ResolvePlanInteraction | Scope.Scope | SourceHostProviders | StepFailureConversion | SubagentManager | WorkspaceCatalog | WorkspaceMutations | WorkspaceTransactionScope;
+/**
+ * Settle an activation request into the change it makes.
+ *
+ * A request the workspace already satisfies settles as `Unchanged` rather
+ * than as an empty plan, so repeating a command reports what is true instead
+ * of offering to do nothing. A request naming a subject the workspace does
+ * not hold fails with the type's own recovery route.
+ */
+export declare const prepareSetActivation: (request: SetActivationRequest) => Effect.Effect<SetActivationCandidate | ActivationUnchanged, SetActivationFailure, CodingAgentRepository | ExtensionManagers | FileSystem.FileSystem | HttpClient.HttpClient | ManagerRequirements | Path.Path | ReleaseAgePosture | Scope.Scope | SourceHostProviders | WorkspaceCatalog | WorkspaceMutations>;
+/**
+ * Preview or apply a settled activation. The whole change — the preference,
+ * the projections it implies, and any instruction file it shares — runs in
+ * one workspace transaction, so a projection that cannot be written never
+ * leaves the preference recorded.
+ */
+export declare const previewOrApplySetActivation: (candidate: SetActivationCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution<void>, SetActivationExecutionFailure, SetActivationRequirements>;
+/** The activation use case. */
+export declare const SetActivation: {
+    readonly prepare: (request: SetActivationRequest) => Effect.Effect<SetActivationCandidate | ActivationUnchanged, SetActivationFailure, CodingAgentRepository | ExtensionManagers | FileSystem.FileSystem | HttpClient.HttpClient | ManagerRequirements | Path.Path | ReleaseAgePosture | Scope.Scope | SourceHostProviders | WorkspaceCatalog | WorkspaceMutations>;
+    readonly previewOrApply: (candidate: SetActivationCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution<void>, SetActivationExecutionFailure, SetActivationRequirements>;
+};
+//# sourceMappingURL=set-activation.d.ts.map