@agentxm/extension-lifecycle 0.28.4-bootstrap.0

package/dist/src/mcps/operations/enable.js

@@ -0,0 +1,218 @@
+/**
+ * Enable MCP server executor.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { CodingAgentRepository, syncInlineMcpServerToAgents, McpSharedTargetConflict, applyProjectionPlansWithResults, planSingletonProjection, inspectAgentMcpServer, sharedMcpTargetPolicyConflict, } from "@agentxm/extension-workspace";
+import { normalizeHandle, parseExtensionFqnParts, } from "@agentxm/extension-model/unstable/extensions";
+import { appendWarningsToMessage } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { agentConfigTargets, mcpServerArtifact, mcpSettingsTarget } from "./artifact.js";
+import { usableAcceptedCanonicalObservation } from "@agentxm/workspace-state";
+import { mcpSyncWarnings, requireSuccessfulMcpSync } from "./sync-outcome.js";
+import { isMcpServerApplicableToAgent } from "@agentxm/workspace-state";
+import { LifecycleFailureAdapter, withAdaptedStepFailures } from "../../failure-adapter.js";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+const enableArtifact = (args) => {
+    return mcpServerArtifact({
+        lockEntry: args.lockEntry,
+        scope: args.scope,
+        change: "updated",
+        targets: [mcpSettingsTarget(args.scope, "updated"), ...args.targets],
+    });
+};
+export const enableMcpServer = (op) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const agentRepo = yield* CodingAgentRepository;
+    const configured = yield* ws.getConfiguredMcpServerEntries();
+    const entry = configured[op.args.serverName];
+    if (entry === undefined) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "not_found",
+            detail: `MCP server "${op.args.serverName}" not found in settings`,
+        });
+    }
+    if (entry.kind === "inline") {
+        const agentIds = yield* ws.getConfiguredAgents();
+        const outcomes = yield* ws.runTransaction({
+            transition: Effect.gen(function* () {
+                const synced = yield* syncInlineMcpServerToAgents(agentIds, {
+                    workspaceRoot: ws.baseDir,
+                    serverName: op.args.serverName,
+                    entry: { ...entry, enabled: true },
+                    scope: ws.scope,
+                }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+                const agentOutcomes = agentIds.map((agentId, index) => ({
+                    agentId,
+                    outcome: synced[index] ?? {
+                        _tag: "failed",
+                        reason: "Agent sync returned no outcome",
+                    },
+                }));
+                yield* requireSuccessfulMcpSync(op.args.serverName, agentOutcomes);
+                yield* ws.updateMcpServerEntry(op.args.serverName, (current) => ({
+                    ...current,
+                    enabled: true,
+                }));
+                return synced;
+            }),
+            validate: () => Effect.void,
+        });
+        const identifiedOutcomes = agentIds.map((agentId, index) => ({
+            agentId,
+            outcome: outcomes[index] ?? {
+                _tag: "failed",
+                reason: "Agent sync returned no outcome",
+            },
+        }));
+        const warnings = mcpSyncWarnings(op.args.serverName, identifiedOutcomes);
+        const agentOutcomes = agentIds.flatMap((agentId, index) => {
+            const outcome = outcomes[index];
+            return outcome !== undefined && "targets" in outcome
+                ? [{ agentId, targets: outcome.targets }]
+                : [];
+        });
+        return {
+            result: "success",
+            message: appendWarningsToMessage(`Enabled ${op.args.serverName}`, warnings),
+            artifact: enableArtifact({
+                lockEntry: undefined,
+                scope: ws.scope,
+                targets: agentConfigTargets(agentOutcomes),
+            }),
+        };
+    }
+    const canonical = yield* usableAcceptedCanonicalObservation({
+        workspace: ws,
+        type: "mcp-server",
+        name: op.args.serverName,
+    });
+    if (Option.isNone(canonical)) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "not_found",
+            detail: `Accepted MCP server content for "${op.args.serverName}" is not usable`,
+            suggestions: [
+                {
+                    description: "Try reinstalling the MCP server.",
+                    cmd: "axm mcps install <source>",
+                },
+            ],
+        });
+    }
+    const canonicalPath = canonical.value.observation.path;
+    const accepted = canonical.value.accepted?.extensionType === "mcp-server"
+        ? canonical.value.accepted
+        : undefined;
+    const identity = canonical.value.desired.identity.startsWith("workspace:")
+        ? canonical.value.desired.identity.slice("workspace:".length)
+        : canonical.value.desired.identity;
+    const trustedIdentity = parseExtensionFqnParts(identity);
+    const owner = trustedIdentity?.type === "mcp-server" ? trustedIdentity.owner : normalizeHandle("@local");
+    const resolvedVersion = accepted?.type === "registry" ? accepted.resolvedVersion : "0.0.0";
+    const agents = yield* agentRepo.getConfiguredAgents();
+    const sharedTargetConflict = sharedMcpTargetPolicyConflict({
+        entry,
+        agentIds: agents.map((agent) => agent.id),
+        scope: ws.scope,
+    });
+    if (sharedTargetConflict !== undefined) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "conflict",
+            detail: sharedTargetConflict,
+        });
+    }
+    const outcomes = yield* ws.runTransaction({
+        transition: Effect.gen(function* () {
+            const synced = yield* applyProjectionPlansWithResults(agents.map((agent) => planSingletonProjection({
+                unitId: "mcp-server:native-config-entry",
+                targetFile: "mcp:configured-agents",
+                contributor: op.args,
+                adapter: {
+                    observe: () => Effect.succeed({
+                        unitId: "mcp-server:native-config-entry",
+                        path: `${agent.id}:${op.args.serverName}`,
+                        present: false,
+                        current: false,
+                        expectedContributors: [op.args.serverName],
+                        observedContributors: [],
+                    }),
+                    apply: () => Effect.gen(function* () {
+                        if (!isMcpServerApplicableToAgent(entry, agent.id)) {
+                            const inspection = yield* inspectAgentMcpServer({
+                                workspaceRoot: ws.baseDir,
+                                scope: ws.scope,
+                                agentId: agent.id,
+                                serverName: op.args.serverName,
+                                entry,
+                            });
+                            if (inspection.status === "unmanaged") {
+                                return yield* new McpSharedTargetConflict({
+                                    reason: `${agent.id} has an unmanaged MCP server named ${op.args.serverName}; AXM will not remove it while applying the target policy`,
+                                });
+                            }
+                            return inspection.status === "drift"
+                                ? yield* agent.removeMcpServer({
+                                    workspaceRoot: ws.baseDir,
+                                    scope: ws.scope,
+                                    serverName: op.args.serverName,
+                                })
+                                : { _tag: "success", targets: [] };
+                        }
+                        return yield* agent.addMcpServer({
+                            workspaceRoot: ws.baseDir,
+                            scope: ws.scope,
+                            serverName: op.args.serverName,
+                            canonicalPath,
+                            owner,
+                            resolvedVersion,
+                            enabled: true,
+                            configValues: entry.env,
+                        });
+                    }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path)),
+                },
+            })));
+            yield* requireSuccessfulMcpSync(op.args.serverName, agents.map((agent, index) => ({
+                agentId: agent.id,
+                outcome: synced[index] ?? {
+                    _tag: "failed",
+                    reason: "Agent sync returned no outcome",
+                },
+            })));
+            yield* ws.updateMcpServerEntry(op.args.serverName, (current) => ({
+                ...current,
+                enabled: true,
+            }));
+            return synced;
+        }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path)),
+        validate: () => Effect.void,
+    });
+    const warnings = mcpSyncWarnings(op.args.serverName, agents.map((agent, index) => ({
+        agentId: agent.id,
+        outcome: outcomes[index] ?? {
+            _tag: "failed",
+            reason: "Agent sync returned no outcome",
+        },
+    })));
+    const agentOutcomes = agents.flatMap((agent, index) => {
+        const outcome = outcomes[index];
+        return outcome !== undefined && "targets" in outcome
+            ? [{ agentId: agent.id, targets: outcome.targets }]
+            : [];
+    });
+    return {
+        result: "success",
+        message: appendWarningsToMessage(`Enabled ${op.args.serverName}`, warnings),
+        artifact: enableArtifact({
+            lockEntry: accepted,
+            scope: ws.scope,
+            targets: agentConfigTargets(agentOutcomes),
+        }),
+    };
+}).pipe(withAdaptedStepFailures);
+//# sourceMappingURL=enable.js.map

package/dist/src/mcps/operations/install.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Install MCP server executor — orchestrates the per-server installation pipeline.
+ *
+ * Registry-only install: fetch archive, extract to canonical path, update lockfile/settings.
+ * Simpler than skills — no agent symlinks.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { CodingAgentRepository } from "@agentxm/extension-workspace";
+import type { ConfigurableAgentId } from "@agentxm/extension-model/unstable/agent-capabilities";
+import type { StepFailure } from "@agentxm/workspace-operations";
+import type { JobStepResult, Operation } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import { LifecycleFailureAdapter } from "../../failure-adapter.js";
+/**
+ * Args for the install-mcp-server operation.
+ */
+export type InstallMcpServerOperationArgs = {
+    readonly ref: McpServerExtensionRef;
+    readonly force: boolean;
+    /** Explicitly permit a workspace-authored relocation during reconciliation. */
+    readonly allowWorkspaceSourceTransition?: boolean;
+    readonly versionRange: Option.Option<string>;
+    /** When true, write to lockfile only (skip settings). Used for pack dependencies. */
+    readonly skipSettings: Option.Option<boolean>;
+    /** Materialize only; the enclosing authored-package transaction owns state writes. */
+    readonly skipStateWrites?: boolean;
+    /** When true, enforce strict policy for MCP sync outcomes. */
+    readonly strictAgentSync?: Option.Option<boolean>;
+    /** Resolved MCP input values from `--env KEY=VALUE` flags. */
+    readonly env?: Option.Option<Readonly<Record<string, string>>>;
+    /**
+     * Whether the invoking surface can prompt for missing required inputs.
+     * The transport boundary resolves flag, CI, and TTY state.
+     */
+    readonly nonInteractive: boolean;
+    /** Restrict this server to a reviewed subset of configured agents. */
+    readonly agents?: ReadonlyArray<ConfigurableAgentId>;
+};
+/**
+ * Add an MCP server to the workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type InstallMcpServerOperation = Operation<"install-mcp-server", InstallMcpServerOperationArgs>;
+/**
+ * Install-mcp-server operation handler.
+ *
+ * Registry-only: fetch archive, validate integrity, extract to canonical path,
+ * then update lockfile/settings.
+ */
+export declare const installMcpServer: (op: InstallMcpServerOperation) => Effect.Effect<JobStepResult, StepFailure, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | WorkspaceMutations | CodingAgentRepository | LifecycleFailureAdapter>;
+//# sourceMappingURL=install.d.ts.map