@agentxm/extension-materialization 0.28.14-preview.1789139351.5cd4595aa

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

@@ -0,0 +1,105 @@
+/**
+ * Typed failure family for the MCP server manager, the MCP install operation,
+ * and MCP inspection.
+ *
+ * The native-config failures the agent writers construct live in
+ * `@agentxm/agent-integration`; this module owns what materialization itself
+ * decides. Fields are domain facts; the application error boundary owns
+ * rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { McpInspectionError } from "@agentxm/workspace-projection";
+declare const McpRegistryOnlyInstall_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "McpRegistryOnlyInstall";
+} & Readonly<A>;
+/** MCP servers install only from registry packages. */
+export declare class McpRegistryOnlyInstall extends McpRegistryOnlyInstall_base<{
+    readonly serverName: string;
+    readonly refType: string;
+}> {
+}
+declare const McpInstallStateMissing_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "McpInstallStateMissing";
+} & Readonly<A>;
+/** A lock entry was requested before install recorded the package state. */
+export declare class McpInstallStateMissing extends McpInstallStateMissing_base<{
+    readonly name: string;
+}> {
+}
+declare const McpLocalNameConflict_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "McpLocalNameConflict";
+} & Readonly<A>;
+/**
+ * The requested local connection name already stands for a different source,
+ * so accepting the request would silently repoint an installed connection.
+ */
+export declare class McpLocalNameConflict extends McpLocalNameConflict_base<{
+    readonly localName: string;
+    /** Source identity the request would install. */
+    readonly requestedIdentity: string;
+    /** Source identity the name already stands for, or `inline` for an authored entry. */
+    readonly owningIdentity: string;
+}> {
+}
+declare const McpCanonicalPathUnsafe_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "McpCanonicalPathUnsafe";
+} & Readonly<A>;
+/** The canonical path a registry MCP package would occupy escapes the workspace. */
+export declare class McpCanonicalPathUnsafe extends McpCanonicalPathUnsafe_base<{
+    readonly serverName: string;
+    readonly canonicalPath: string;
+}> {
+}
+/** Why a workspace-authored MCP package cannot be installed from where it says it is. */
+export type McpWorkspacePackageFault = "outside-workspace" | "missing" | "unreadable";
+declare const McpWorkspacePackageInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "McpWorkspacePackageInvalid";
+} & Readonly<A>;
+/** A workspace-sourced MCP package is not where the reference says it is. */
+export declare class McpWorkspacePackageInvalid extends McpWorkspacePackageInvalid_base<{
+    readonly serverName: string;
+    readonly location: string;
+    readonly fault: McpWorkspacePackageFault;
+    readonly cause?: unknown;
+}> {
+}
+declare const McpRequiredInputsMissing_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "McpRequiredInputsMissing";
+} & Readonly<A>;
+/**
+ * The manifest declares required inputs nothing supplied, and the invoking
+ * surface said it cannot prompt.
+ */
+export declare class McpRequiredInputsMissing extends McpRequiredInputsMissing_base<{
+    readonly localName: string;
+    /** Input names still unsatisfied, sorted. */
+    readonly inputNames: ReadonlyArray<string>;
+}> {
+}
+/** Why projecting an MCP connection to the configured agents was refused. */
+export type McpAgentSyncFault = 
+/** Settings name agents AXM does not know, and the caller asked for strict sync. */
+"unknown-agents"
+/** An agent's native configuration cannot represent the connection. */
+ | "misconfigured"
+/** An agent write failed and the caller asked for strict sync. */
+ | "failed"
+/** An agent AXM requires refused the connection and the caller asked for strict sync. */
+ | "disabled";
+declare const McpAgentSyncRefused_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "McpAgentSyncRefused";
+} & Readonly<A>;
+/** Projecting an MCP connection into the configured agents could not settle. */
+export declare class McpAgentSyncRefused extends McpAgentSyncRefused_base<{
+    readonly serverName: string;
+    readonly fault: McpAgentSyncFault;
+    /** The agents the fault is about; empty when it is about none in particular. */
+    readonly agentIds: ReadonlyArray<AgentId | string>;
+}> {
+}
+/** Every failure the MCP module surfaces. */
+export type McpManagerError = McpInspectionError | McpRegistryOnlyInstall | McpInstallStateMissing | McpLocalNameConflict | McpCanonicalPathUnsafe | McpWorkspacePackageInvalid | McpRequiredInputsMissing | McpAgentSyncRefused;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/mcps/errors.js

@@ -0,0 +1,40 @@
+/**
+ * Typed failure family for the MCP server manager, the MCP install operation,
+ * and MCP inspection.
+ *
+ * The native-config failures the agent writers construct live in
+ * `@agentxm/agent-integration`; this module owns what materialization itself
+ * decides. Fields are domain facts; the application error boundary owns
+ * rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/** MCP servers install only from registry packages. */
+export class McpRegistryOnlyInstall extends Data.TaggedError("McpRegistryOnlyInstall") {
+}
+/** A lock entry was requested before install recorded the package state. */
+export class McpInstallStateMissing extends Data.TaggedError("McpInstallStateMissing") {
+}
+/**
+ * The requested local connection name already stands for a different source,
+ * so accepting the request would silently repoint an installed connection.
+ */
+export class McpLocalNameConflict extends Data.TaggedError("McpLocalNameConflict") {
+}
+/** The canonical path a registry MCP package would occupy escapes the workspace. */
+export class McpCanonicalPathUnsafe extends Data.TaggedError("McpCanonicalPathUnsafe") {
+}
+/** A workspace-sourced MCP package is not where the reference says it is. */
+export class McpWorkspacePackageInvalid extends Data.TaggedError("McpWorkspacePackageInvalid") {
+}
+/**
+ * The manifest declares required inputs nothing supplied, and the invoking
+ * surface said it cannot prompt.
+ */
+export class McpRequiredInputsMissing extends Data.TaggedError("McpRequiredInputsMissing") {
+}
+/** Projecting an MCP connection into the configured agents could not settle. */
+export class McpAgentSyncRefused extends Data.TaggedError("McpAgentSyncRefused") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/mcps/install-operation.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The MCP server installation operation: acquire the package, reconcile the
+ * connection's credentials, record the accepted resolution and the settings
+ * entry, and project the connection into every configured agent.
+ *
+ * It lives in the materialization capability rather than in a feature because
+ * four surfaces need it — `axm mcps install`, pack member installation,
+ * reconciliation, and the authoring routes that install an MCP server they
+ * have just scaffolded, forked, adopted, or imported — and a feature may not
+ * import a peer feature. Requirements stay in `R` and failures stay typed in
+ * `E`; the caller composes the layer and renders the failure.
+ *
+ * @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 { NativeWriteAuthority } from "@agentxm/agent-integration";
+import { CodingAgentRepository } from "@agentxm/workspace-projection";
+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 { type McpServerManifest } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
+import type { ExtensionManagerFailure } from "../errors.js";
+import { McpSecretStore, type McpSecretIdentity } from "./secret-store.js";
+/**
+ * Args for the install-mcp-server operation.
+ */
+export type InstallMcpServerOperationArgs = {
+    readonly ref: McpServerExtensionRef;
+    /** Local connection identity and exact agent-native MCP key. */
+    readonly localName?: string;
+    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;
+};
+/**
+ * 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>;
+export type McpSecretDeletionOutcome = {
+    readonly _tag: "deleted";
+    readonly inputName: string;
+} | {
+    readonly _tag: "absent";
+    readonly inputName: string;
+} | {
+    readonly _tag: "failed";
+    readonly inputName: string;
+};
+export declare const collectSecretInputNames: (manifest: McpServerManifest) => ReadonlySet<string>;
+export declare const readMcpServerManifest: (canonicalPath: string) => Effect.Effect<Option.Option<McpServerManifest>, never, FileSystem.FileSystem | Path.Path>;
+/**
+ * Erase every credential one connection holds. Erasure is reported per input:
+ * a credential store that is unavailable leaves the secret behind and says so,
+ * rather than failing the removal that has already settled.
+ */
+export declare const deleteMcpSecrets: (identity: McpSecretIdentity, secretNames: ReadonlySet<string>) => Effect.Effect<ReadonlyArray<McpSecretDeletionOutcome>, never, McpSecretStore>;
+/**
+ * Everything the MCP install operation needs from its composition root.
+ */
+export type McpServerInstallRequirements = FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | WorkspaceMutations | CodingAgentRepository | NativeWriteAuthority | McpSecretStore;
+/**
+ * Install one MCP server: acquire the package (registry archive or the
+ * workspace-authored directory), merge the connection's inputs with what the
+ * credential store already holds, record the settings entry and the accepted
+ * resolution, and project the connection into every configured agent.
+ *
+ * Failures stay typed: a refused request, an unrepresentable connection, and a
+ * credential store that will not persist a secret are three different facts,
+ * and the caller decides how each is reported.
+ */
+export declare const installMcpServer: (op: InstallMcpServerOperation) => Effect.Effect<JobStepResult, ExtensionManagerFailure, McpServerInstallRequirements>;
+//# sourceMappingURL=install-operation.d.ts.map