@agentxm/workspace-configuration 0.28.12 → 0.28.13

package/dist/src/instructions/manage-instructions.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Instruction-file management: whether this workspace propagates one source
+ * instruction file to the agents it configures, and the transition between
+ * that choice and the files on disk.
+ *
+ * Three requests share one shape. Status reports what the workspace does
+ * today without touching it. Enabling records the chosen source file and
+ * reconciles every alias AXM owns to it — including removing the aliases a
+ * previous choice owned, so changing the source filename never leaves the old
+ * arrangement behind. Disabling removes the aliases AXM owns and records that
+ * the workspace no longer propagates instructions.
+ *
+ * Every transition passes one readiness gate before it is planned: AXM
+ * refuses to reconcile a target it cannot prove it owns, and refuses to edit
+ * a `.gitignore` region it did not write. The gate is stated once here rather
+ * than at each call site, because a caller that forgot it would silently
+ * overwrite a person's file.
+ *
+ * @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 * as Schema from "effect/Schema";
+import { RuleManager, type ManagerRequirements } from "@agentxm/extension-materialization";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import { OperationJournal, ResolvePlanInteraction, type OperationResolution, type PlanExecution } from "@agentxm/workspace-operations";
+import { observeInstructions, type InstructionProjectionEffect, type ResolvedInstructionsConfig } from "@agentxm/workspace-projection";
+import { ConfiguredAgentOutcomesProvider, WorkspaceMutations, type WorkspaceStateReadFailure } from "@agentxm/workspace-state";
+import { FootprintRecorder, WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { WorkspaceConfigurationFailed, type WorkspaceConfigurationExecutionFailure } from "../errors.js";
+/** Every failure observing or planning instruction management can surface. */
+export type ManageInstructionsFailure = WorkspaceConfigurationFailed | WorkspaceStateReadFailure | Effect.Error<ReturnType<typeof observeInstructions>>;
+/** What the workspace does about instruction files right now. */
+export declare const InstructionsStatusSchema: Schema.Struct<{
+    readonly enabled: Schema.Boolean;
+    readonly sourceFileName: Schema.String;
+    readonly gitignoreAliases: Schema.Boolean;
+    readonly roots: Schema.$Array<Schema.String>;
+    readonly missingSources: Schema.$Array<Schema.String>;
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly root: Schema.String;
+        readonly agentId: Schema.String;
+        readonly agentName: Schema.String;
+        readonly sourceFile: Schema.String;
+        readonly targetFile: Schema.String;
+        readonly mechanism: Schema.String;
+        readonly health: Schema.String;
+        readonly ownership: Schema.String;
+        readonly observedForm: Schema.String;
+        readonly details: Schema.String;
+    }>>;
+    readonly staleTargets: Schema.$Array<Schema.Struct<{
+        readonly root: Schema.String;
+        readonly agentId: Schema.String;
+        readonly agentName: Schema.String;
+        readonly sourceFile: Schema.String;
+        readonly targetFile: Schema.String;
+        readonly mechanism: Schema.String;
+        readonly health: Schema.String;
+        readonly ownership: Schema.String;
+        readonly observedForm: Schema.String;
+        readonly details: Schema.String;
+    }>>;
+}>;
+export type InstructionsStatus = typeof InstructionsStatusSchema.Type;
+/**
+ * Report instruction-file management without changing it. A workspace that
+ * does not manage instruction files reports that, rather than an empty
+ * observation of a configuration it does not have.
+ */
+export declare const instructionsStatus: () => Effect.Effect<InstructionsStatus, Effect.Error<ReturnType<typeof observeInstructions>>, WorkspaceMutations | FileSystem.FileSystem | Path.Path>;
+export type ManageInstructionsRequest = {
+    readonly action: "enable";
+    /** The source-of-truth instruction file every alias points at. */
+    readonly fileName: string;
+    /** Keep the propagated alias files out of Git. */
+    readonly gitignoreAliases: boolean;
+} | {
+    readonly action: "disable";
+};
+/** A request the workspace already satisfies. */
+export interface InstructionsUnchanged {
+    readonly _tag: "Unchanged";
+    readonly action: "enable" | "disable";
+    readonly message: string;
+}
+export interface ManageInstructionsCandidate {
+    readonly _tag: "ManageInstructions";
+    readonly action: "enable" | "disable";
+    /** The configuration recorded once the change settles. */
+    readonly config: ResolvedInstructionsConfig | false;
+    /** The configuration whose aliases the transition removes first, if any. */
+    readonly supersededConfig: Option.Option<ResolvedInstructionsConfig>;
+    /** Every file the transition creates, updates, or removes. */
+    readonly effects: ReadonlyArray<InstructionProjectionEffect>;
+    /** The gate's refusal, when the workspace is not safe to reconcile. */
+    readonly blocked: Option.Option<WorkspaceConfigurationFailed>;
+    readonly scope: WorkspaceScope;
+}
+/**
+ * Settle an instruction-management request into the transition it makes.
+ *
+ * A request the workspace already satisfies is reported as unchanged rather
+ * than planned: enabling the configuration that is already recorded, and
+ * whose targets are already current, changes nothing.
+ */
+export declare const prepareManageInstructions: (request: ManageInstructionsRequest) => Effect.Effect<ManageInstructionsCandidate | InstructionsUnchanged, ManageInstructionsFailure, WorkspaceMutations | FileSystem.FileSystem | Path.Path | RuleManager | ManagerRequirements>;
+/** Every service the instruction transition and its plan resolution need. */
+export type ManageInstructionsRequirements = ConfiguredAgentOutcomesProvider | FileSystem.FileSystem | FootprintRecorder | OperationJournal | Path.Path | ResolvePlanInteraction | ManagerRequirements | RuleManager | WorkspaceMutations | WorkspaceTransactionScope;
+/**
+ * Preview or apply a settled instruction transition. The whole transition —
+ * removing superseded aliases, recording the choice, and reconciling every
+ * target — runs inside one workspace transaction, so a reconciliation that
+ * cannot complete never leaves the choice recorded.
+ */
+export declare const previewOrApplyManageInstructions: (candidate: ManageInstructionsCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution<void>, WorkspaceConfigurationExecutionFailure, ManageInstructionsRequirements>;
+/** The instruction-management use case. */
+export declare const ManageInstructions: {
+    readonly status: () => Effect.Effect<InstructionsStatus, Effect.Error<ReturnType<typeof observeInstructions>>, WorkspaceMutations | FileSystem.FileSystem | Path.Path>;
+    readonly prepare: (request: ManageInstructionsRequest) => Effect.Effect<ManageInstructionsCandidate | InstructionsUnchanged, ManageInstructionsFailure, WorkspaceMutations | FileSystem.FileSystem | Path.Path | RuleManager | ManagerRequirements>;
+    readonly previewOrApply: (candidate: ManageInstructionsCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution<void>, WorkspaceConfigurationExecutionFailure, ManageInstructionsRequirements>;
+};
+//# sourceMappingURL=manage-instructions.d.ts.map

package/dist/src/instructions/manage-instructions.js

@@ -0,0 +1,361 @@
+/**
+ * Instruction-file management: whether this workspace propagates one source
+ * instruction file to the agents it configures, and the transition between
+ * that choice and the files on disk.
+ *
+ * Three requests share one shape. Status reports what the workspace does
+ * today without touching it. Enabling records the chosen source file and
+ * reconciles every alias AXM owns to it — including removing the aliases a
+ * previous choice owned, so changing the source filename never leaves the old
+ * arrangement behind. Disabling removes the aliases AXM owns and records that
+ * the workspace no longer propagates instructions.
+ *
+ * Every transition passes one readiness gate before it is planned: AXM
+ * refuses to reconcile a target it cannot prove it owns, and refuses to edit
+ * a `.gitignore` region it did not write. The gate is stated once here rather
+ * than at each call site, because a caller that forgot it would silently
+ * overwrite a person's file.
+ *
+ * @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 * as Schema from "effect/Schema";
+import { RuleManager } from "@agentxm/extension-materialization";
+import { OperationJournal, ResolvePlanInteraction, StepFailure, prepareExecutionCandidate, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { applyPlannedProjections, disableInstructionManagement, instructionProjectionEffects, instructionProjectionRemovalEffects, instructionReconciliationReadiness, instructionStateIsCurrent, InstructionMaintenanceFailed, observeInstructions, observeProjectionPlans, reconcileInstructionTransition, removeInstructionTargetsFor, resolveInstructionsConfig, } from "@agentxm/workspace-projection";
+import { ConfiguredAgentOutcomesProvider, WorkspaceMutations, } from "@agentxm/workspace-state";
+import { FootprintRecorder, WorkspaceTransactionScope, runWorkspaceTransaction, } from "@agentxm/workspace-transactions";
+import { WorkspaceConfigurationFailed, configurationFailedToStepFailure, workspaceChangeFailedToStepFailure, } from "../errors.js";
+// -----------------------------------------------------------------------------
+// Status
+// -----------------------------------------------------------------------------
+const InstructionStatusItemSchema = Schema.Struct({
+    root: Schema.String,
+    agentId: Schema.String,
+    agentName: Schema.String,
+    sourceFile: Schema.String,
+    targetFile: Schema.String,
+    mechanism: Schema.String,
+    health: Schema.String,
+    ownership: Schema.String,
+    observedForm: Schema.String,
+    details: Schema.String,
+});
+/** What the workspace does about instruction files right now. */
+export const InstructionsStatusSchema = Schema.Struct({
+    enabled: Schema.Boolean,
+    sourceFileName: Schema.String,
+    gitignoreAliases: Schema.Boolean,
+    roots: Schema.Array(Schema.String),
+    missingSources: Schema.Array(Schema.String),
+    items: Schema.Array(InstructionStatusItemSchema),
+    staleTargets: Schema.Array(InstructionStatusItemSchema),
+});
+const DISABLED_STATUS = {
+    enabled: false,
+    sourceFileName: "AGENTS.md",
+    gitignoreAliases: false,
+    roots: [],
+    missingSources: [],
+    items: [],
+    staleTargets: [],
+};
+/**
+ * Report instruction-file management without changing it. A workspace that
+ * does not manage instruction files reports that, rather than an empty
+ * observation of a configuration it does not have.
+ */
+export const instructionsStatus = () => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const configured = yield* workspace.getInstructionsConfig();
+    if (Option.isNone(configured) || configured.value === false)
+        return DISABLED_STATUS;
+    const snapshot = yield* observeInstructions({
+        ws: workspace,
+        config: resolveInstructionsConfig(configured.value),
+    });
+    return snapshot.status;
+});
+const settingsDisplayPath = (scope) => scope === "project" ? "axm.json" : ".axm/workspace/axm.json";
+/**
+ * The transition's artifact: the settings file that records the choice, plus
+ * every instruction file the reconciliation touches, workspace-relative.
+ */
+const instructionArtifact = (args) => {
+    const settings = settingsDisplayPath(args.scope);
+    const byPath = new Map();
+    byPath.set(settings, { path: settings, change: "updated" });
+    for (const effect of args.effects) {
+        const relative = args.path.relative(args.baseDir, effect.path);
+        byPath.set(relative, { path: relative, change: effect.change });
+    }
+    return {
+        path: settings,
+        scope: args.scope,
+        change: "updated",
+        targets: [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path)),
+    };
+};
+const rawConfigMatches = (observed, desired) => {
+    if (observed === false)
+        return false;
+    const resolved = resolveInstructionsConfig(observed);
+    return (resolved.fileName === desired.fileName && resolved.gitignoreAliases === desired.gitignoreAliases);
+};
+/**
+ * The one readiness gate every instruction transition passes. It is stated
+ * here because it decides whether AXM may write at all: an unowned target or
+ * an unrecognized `.gitignore` region means the workspace holds a file AXM
+ * did not create, and reconciliation stops before it can overwrite it.
+ */
+const reconciliationGate = (snapshot) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const failure = yield* instructionReconciliationReadiness({ ws: workspace, snapshot });
+    return Option.map(failure, (readiness) => new WorkspaceConfigurationFailed({
+        category: "conflict",
+        detail: readiness._tag === "InstructionMaintenanceFailed"
+            ? readiness.detail
+            : "Instruction reconciliation cannot proceed against the current workspace",
+        cause: readiness,
+    }));
+});
+/**
+ * Settle an instruction-management request into the transition it makes.
+ *
+ * A request the workspace already satisfies is reported as unchanged rather
+ * than planned: enabling the configuration that is already recorded, and
+ * whose targets are already current, changes nothing.
+ */
+export const prepareManageInstructions = (request) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const recorded = yield* workspace.getInstructionsConfig();
+    if (request.action === "disable") {
+        if (Option.isNone(recorded) || recorded.value === false) {
+            const settled = {
+                _tag: "Unchanged",
+                action: "disable",
+                message: "Instruction-file management is already disabled.",
+            };
+            return settled;
+        }
+        const config = resolveInstructionsConfig(recorded.value);
+        const snapshot = yield* observeInstructions({ ws: workspace, config });
+        const disableCandidate = {
+            _tag: "ManageInstructions",
+            action: "disable",
+            config: false,
+            supersededConfig: Option.some(config),
+            effects: instructionProjectionRemovalEffects(snapshot),
+            blocked: yield* reconciliationGate(snapshot),
+            scope: workspace.scope,
+        };
+        return disableCandidate;
+    }
+    const desired = resolveInstructionsConfig({
+        fileName: request.fileName,
+        gitignoreAliases: request.gitignoreAliases,
+    });
+    const previous = Option.isSome(recorded) && recorded.value !== false
+        ? Option.some(resolveInstructionsConfig(recorded.value))
+        : Option.none();
+    const configChanged = Option.isSome(previous) &&
+        (previous.value.fileName !== desired.fileName ||
+            previous.value.gitignoreAliases !== desired.gitignoreAliases);
+    const observed = yield* observeInstructions({ ws: workspace, config: desired });
+    if (Option.isSome(recorded) &&
+        rawConfigMatches(recorded.value, desired) &&
+        instructionStateIsCurrent(observed)) {
+        const settled = {
+            _tag: "Unchanged",
+            action: "enable",
+            message: "Instruction-file management is already enabled.",
+        };
+        return settled;
+    }
+    // A changed configuration is preflighted against the aliases the previous
+    // configuration owns, because those are the files the transition removes.
+    const superseded = configChanged ? previous : Option.none();
+    const preflight = Option.isSome(superseded)
+        ? yield* observeInstructions({ ws: workspace, config: superseded.value })
+        : observed;
+    const ruleManager = yield* RuleManager;
+    const ruleEffects = (yield* ruleManager.projectionPlans().pipe(Effect.flatMap(observeProjectionPlans), Effect.mapError((cause) => new WorkspaceConfigurationFailed({
+        category: "internal",
+        detail: "Rule projections could not be observed before reconciling instructions",
+        cause,
+    }))))
+        .filter((observation) => !observation.current)
+        .map((observation) => ({
+        path: path.resolve(workspace.baseDir, observation.path.split("#", 1)[0] ?? observation.path),
+        change: "updated",
+    }));
+    const enableCandidate = {
+        _tag: "ManageInstructions",
+        action: "enable",
+        config: desired,
+        supersededConfig: superseded,
+        effects: [
+            ...(Option.isSome(superseded) ? instructionProjectionRemovalEffects(preflight) : []),
+            ...ruleEffects,
+            ...instructionProjectionEffects(observed),
+        ],
+        blocked: yield* reconciliationGate(preflight),
+        scope: workspace.scope,
+    };
+    return enableCandidate;
+});
+// -----------------------------------------------------------------------------
+// previewOrApply
+// -----------------------------------------------------------------------------
+const PRESENTATION = {
+    enable: {
+        name: "Enable instruction-file management",
+        verb: { imperative: "enable", past: "Enabled", gerund: "Enabling" },
+        applied: "Enabled and reconciled instruction-file management",
+    },
+    disable: {
+        name: "Disable instruction-file management",
+        verb: { imperative: "disable", past: "Disabled", gerund: "Disabling" },
+        applied: "Disabled instruction-file management and removed owned aliases",
+    },
+};
+const transitionEffect = (candidate, config) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const ruleManager = yield* RuleManager;
+    if (Option.isSome(candidate.supersededConfig)) {
+        yield* removeInstructionTargetsFor({
+            ws: workspace,
+            config: candidate.supersededConfig.value,
+        });
+    }
+    yield* workspace.setInstructionsConfig({
+        fileName: config.fileName,
+        gitignoreAliases: config.gitignoreAliases,
+    });
+    yield* applyPlannedProjections(ruleManager);
+});
+/**
+ * Serialize the instruction-projection failures the transition can surface.
+ * Ownership refusals keep the sentence the projection chose; the rest are
+ * workspace-change failures the shared conversion already renders.
+ */
+/**
+ * Serialize whatever the recorded transition failed with. The refusals this
+ * feature and the projection decide keep their own sentence and category;
+ * anything the kernel could not complete is an internal step failure that
+ * carries its cause, so the resolution still reports why.
+ */
+const transitionFailureToStepFailure = (failure) => {
+    if (failure instanceof StepFailure)
+        return failure;
+    if (failure instanceof WorkspaceConfigurationFailed) {
+        return configurationFailedToStepFailure(failure);
+    }
+    if (failure instanceof InstructionMaintenanceFailed) {
+        return new StepFailure({
+            category: failure.category,
+            detail: failure.detail,
+            ...(failure.suggestions === undefined ? {} : { suggestions: failure.suggestions }),
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        });
+    }
+    return new StepFailure({
+        category: "internal",
+        detail: `Instruction reconciliation could not complete (${failure._tag})`,
+        cause: failure,
+    });
+};
+const transitionStep = (candidate, artifact) => {
+    const presentation = PRESENTATION[candidate.action];
+    if (Option.isSome(candidate.blocked)) {
+        return {
+            label: presentation.name,
+            readiness: "error",
+            errorMessage: candidate.blocked.value.detail,
+        };
+    }
+    const transition = candidate.action === "disable"
+        ? Effect.gen(function* () {
+            const workspace = yield* WorkspaceMutations;
+            const config = Option.getOrUndefined(candidate.supersededConfig);
+            if (config === undefined) {
+                return yield* new WorkspaceConfigurationFailed({
+                    category: "internal",
+                    detail: "Instruction management has no recorded configuration to disable",
+                });
+            }
+            yield* disableInstructionManagement({ ws: workspace, config });
+        }).pipe(Effect.asVoid, Effect.mapError(transitionFailureToStepFailure))
+        : Effect.gen(function* () {
+            const workspace = yield* WorkspaceMutations;
+            const config = candidate.config;
+            if (config === false) {
+                return yield* new WorkspaceConfigurationFailed({
+                    category: "internal",
+                    detail: "Enabling instruction management has no configuration to record",
+                });
+            }
+            yield* reconcileInstructionTransition({
+                ws: workspace,
+                config,
+                ...(Option.isSome(candidate.supersededConfig)
+                    ? { preflightConfig: candidate.supersededConfig.value }
+                    : {}),
+                transition: transitionEffect({ ...candidate, action: "enable" }, config),
+            });
+        }).pipe(Effect.asVoid, Effect.mapError(transitionFailureToStepFailure));
+    return {
+        label: presentation.name,
+        readiness: "ready",
+        artifact,
+        run: runWorkspaceTransaction({
+            transition,
+            validate: () => Effect.void,
+        }).pipe(Effect.mapError(workspaceChangeFailedToStepFailure), Effect.as({
+            result: "success",
+            message: presentation.applied,
+            artifact,
+        })),
+    };
+};
+/**
+ * Preview or apply a settled instruction transition. The whole transition —
+ * removing superseded aliases, recording the choice, and reconciling every
+ * target — runs inside one workspace transaction, so a reconciliation that
+ * cannot complete never leaves the choice recorded.
+ */
+export const previewOrApplyManageInstructions = (candidate, execution) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const artifact = instructionArtifact({
+        scope: candidate.scope,
+        baseDir: workspace.baseDir,
+        path,
+        effects: candidate.effects,
+    });
+    const plan = {
+        _tag: "Plan",
+        name: PRESENTATION[candidate.action].name,
+        description: Option.some(candidate.action === "disable"
+            ? "Turn off instruction-file propagation"
+            : `Use ${candidate.config === false ? "AGENTS.md" : candidate.config.fileName} as the source instruction file`),
+        presentation: {
+            verb: PRESENTATION[candidate.action].verb,
+            subject: { singular: "instruction file", plural: "instruction files" },
+        },
+        jobs: [{ concurrency: 1, steps: [transitionStep(candidate, artifact)] }],
+    };
+    const prepared = yield* prepareExecutionCandidate(plan);
+    return yield* resolveExecutionCandidate(prepared, execution);
+});
+/** The instruction-management use case. */
+export const ManageInstructions = {
+    status: instructionsStatus,
+    prepare: prepareManageInstructions,
+    previewOrApply: previewOrApplyManageInstructions,
+};
+//# sourceMappingURL=manage-instructions.js.map

package/dist/src/mcp-import/apply.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Inline MCP adoption policy: discover import sources from configured agents'
+ * native MCP configs, rewrite adopted entries with AXM management metadata,
+ * remove entries converted into managed packages, and apply an inline import
+ * as one validated workspace transaction. Prompting, planning, and rendering
+ * stay with the application.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { type WorkspaceMutationsService } from "@agentxm/workspace-state";
+import { WorkspaceConfigurationFailed } from "../errors.js";
+import type { McpImportCandidate, McpImportSource } from "./preflight.js";
+/**
+ * Discover the native MCP config sources the configured agents contribute for
+ * this workspace scope, with unsupported-format findings.
+ */
+export declare const collectMcpImportSources: (ws: WorkspaceMutationsService, fs: FileSystem.FileSystem, path: Path.Path) => Effect.Effect<{
+    sources: McpImportSource[];
+    skipped: {
+        readonly name: string;
+        readonly reason: string;
+    }[];
+}, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | WorkspaceConfigurationFailed, never>;
+/**
+ * Adopt the losslessly importable candidates as inline settings entries and
+ * mark their native entries as AXM-managed, in one validated workspace
+ * transaction.
+ */
+export declare const applyMcpImport: (candidates: ReadonlyArray<McpImportCandidate>, ws: WorkspaceMutationsService, fs: FileSystem.FileSystem) => Effect.Effect<void, import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-transactions").WorkspaceDirectoryError | import("@agentxm/workspace-transactions").TransitionLockError | WorkspaceConfigurationFailed | import("@agentxm/workspace-transactions").WorkspaceRestorationIncomplete | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-transactions").WorkspaceSnapshotError | import("@agentxm/workspace-transactions").TransitionLockUnavailable | import("@agentxm/workspace-transactions").WorkspaceTransitionCompromised, FileSystem.FileSystem | Path.Path | import("@agentxm/workspace-transactions").WorkspaceTransactionScope>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/src/{mcp-import.js → mcp-import/apply.js}

@@ -12,9 +12,11 @@ import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import { CONFIGURABLE_AGENTS_BY_ID, } from "@agentxm/extension-model/unstable/agent-capabilities";
-import { buildAxmMcpMetadataFromSettingsSource } from "@agentxm/extension-workspace";
-import { AXM_MCP_METADATA_KEY, isAxmManagedMcpEntry, } from "@agentxm/workspace-state";
-import { WorkspaceConfigurationFailed } from "./errors.js";
+import { buildAxmMcpMetadataFromSettingsSource } from "@agentxm/agent-integration";
+import {} from "@agentxm/workspace-state";
+import { AXM_MCP_METADATA_KEY, isAxmManagedMcpEntry } from "@agentxm/agent-integration";
+import { runWorkspaceTransaction } from "@agentxm/workspace-transactions";
+import { WorkspaceConfigurationFailed } from "../errors.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isCapabilityAgentId = (id) => Object.hasOwn(CONFIGURABLE_AGENTS_BY_ID, id);
 const readAgentMcpConfig = (agent) => {
@@ -154,47 +156,6 @@ const writeAdoptedMcpConfig = (fs, adoption) => Effect.gen(function* () {
         cause: error,
     })));
 });
-/**
- * Remove a native entry converted into a managed package, refusing when the
- * native config changed since the conversion was planned.
- */
-export const removeConvertedMcpConfig = (fs, adoption) => Effect.gen(function* () {
-    const config = yield* readJsonObject(fs, adoption.filePath);
-    if (Option.isNone(config)) {
-        return yield* new WorkspaceConfigurationFailed({
-            category: "conflict",
-            detail: `MCP config disappeared before package conversion: ${adoption.filePath}`,
-        });
-    }
-    const servers = config.value[adoption.serversKey];
-    if (!isRecord(servers)) {
-        return yield* new WorkspaceConfigurationFailed({
-            category: "conflict",
-            detail: `MCP server collection changed before package conversion: ${adoption.filePath}`,
-        });
-    }
-    const entry = servers[adoption.name];
-    if (entry === undefined)
-        return;
-    if (!isRecord(entry)) {
-        return yield* new WorkspaceConfigurationFailed({
-            category: "conflict",
-            detail: `MCP server ${adoption.name} changed before package conversion`,
-        });
-    }
-    const remainingServers = Object.fromEntries(Object.entries(servers).filter(([name]) => name !== adoption.name));
-    const updatedConfig = {
-        ...config.value,
-        [adoption.serversKey]: remainingServers,
-    };
-    yield* fs
-        .writeFileString(adoption.filePath, `${JSON.stringify(updatedConfig, null, 2)}\n`)
-        .pipe(Effect.mapError((error) => new WorkspaceConfigurationFailed({
-        category: "internal",
-        detail: `Failed to replace native MCP config: ${adoption.filePath}`,
-        cause: error,
-    })));
-});
 const recordsEqual = (left, right) => {
     const leftEntries = Object.entries(left ?? {}).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
     const rightEntries = Object.entries(right ?? {}).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
@@ -230,7 +191,7 @@ const validateAdoption = (fs, adoption) => Effect.gen(function* () {
  * mark their native entries as AXM-managed, in one validated workspace
  * transaction.
  */
-export const applyMcpImport = (candidates, ws, fs, hooks = {}) => {
+export const applyMcpImport = (candidates, ws, fs) => {
     const adoptions = candidates.flatMap((candidate) => candidate.adoptions);
     const settingsEntry = (candidate) => ({
         kind: "inline",
@@ -240,16 +201,13 @@ export const applyMcpImport = (candidates, ws, fs, hooks = {}) => {
         env: candidate.env,
         enabled: true,
     });
-    return ws.runTransaction({
+    return runWorkspaceTransaction({
         targets: Array.from(new Set(adoptions.map((adoption) => adoption.filePath))).sort(),
         transition: Effect.gen(function* () {
             for (const candidate of candidates) {
                 yield* ws.setMcpServerEntry(candidate.name, settingsEntry(candidate));
             }
             for (const adoption of adoptions) {
-                if (hooks.beforeAdoptionWrite !== undefined) {
-                    yield* hooks.beforeAdoptionWrite(adoption);
-                }
                 yield* writeAdoptedMcpConfig(fs, adoption);
             }
         }),
@@ -269,4 +227,4 @@ export const applyMcpImport = (candidates, ws, fs, hooks = {}) => {
         }),
     });
 };
-//# sourceMappingURL=mcp-import.js.map
+//# sourceMappingURL=apply.js.map

package/dist/src/mcp-import/import-mcp-servers.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Adopting the MCP servers a workspace already had.
+ *
+ * People arrive with MCP servers configured directly in their coding agents.
+ * Import records each one the workspace can represent losslessly as an inline
+ * settings entry and marks the native entry as AXM-managed, so the next
+ * reconciliation recognises it instead of treating it as someone else's file.
+ * A server whose definitions disagree across agents is a conflict, not a
+ * choice AXM makes on the person's behalf.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import { OperationJournal, ResolvePlanInteraction, type OperationResolution, type PlanExecution } from "@agentxm/workspace-operations";
+import { ConfiguredAgentOutcomesProvider, WorkspaceMutations } from "@agentxm/workspace-state";
+import { FootprintRecorder, WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { WorkspaceConfigurationFailed, type WorkspaceConfigurationExecutionFailure } from "../errors.js";
+import { collectMcpImportSources } from "./apply.js";
+import { type McpImportPreflight } from "./preflight.js";
+export interface ImportMcpServersCandidate {
+    readonly _tag: "ImportMcpServers";
+    /** Every unmanaged server the workspace found, classified. */
+    readonly preflight: McpImportPreflight;
+    readonly scope: WorkspaceScope;
+}
+/**
+ * Discover and classify every unmanaged MCP server the configured agents and
+ * the workspace itself declare. Nothing is written; the candidate names the
+ * servers that can be adopted, the ones that conflict, and the ones skipped.
+ */
+export declare const prepareImportMcpServers: () => Effect.Effect<ImportMcpServersCandidate, WorkspaceConfigurationFailed | Effect.Error<ReturnType<typeof collectMcpImportSources>>, WorkspaceMutations | FileSystem.FileSystem | Path.Path>;
+/** Every service an inline import and its plan resolution need. */
+export type ImportMcpServersRequirements = ConfiguredAgentOutcomesProvider | FileSystem.FileSystem | FootprintRecorder | OperationJournal | Path.Path | ResolvePlanInteraction | WorkspaceMutations | WorkspaceTransactionScope;
+/**
+ * Preview or apply the inline adoption. Every adopted entry is recorded and
+ * every native entry marked in one transaction, and the transaction validates
+ * the readback before it settles: a half-adopted server would look managed
+ * without being managed.
+ */
+export declare const previewOrApplyImportMcpServers: (candidate: ImportMcpServersCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution<void>, WorkspaceConfigurationExecutionFailure, ImportMcpServersRequirements>;
+/** The inline MCP import use case. */
+export declare const ImportMcpServers: {
+    readonly prepare: () => Effect.Effect<ImportMcpServersCandidate, WorkspaceConfigurationFailed | Effect.Error<ReturnType<typeof collectMcpImportSources>>, WorkspaceMutations | FileSystem.FileSystem | Path.Path>;
+    readonly previewOrApply: (candidate: ImportMcpServersCandidate, execution: PlanExecution) => Effect.Effect<OperationResolution<void>, WorkspaceConfigurationExecutionFailure, ImportMcpServersRequirements>;
+};
+//# sourceMappingURL=import-mcp-servers.d.ts.map