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

package/dist/src/mcps/manager.js

@@ -0,0 +1,253 @@
+/**
+ * MCP server extension manager service.
+ *
+ * Implements ExtensionManager<McpServerExtensionRef>. Delegates to existing
+ * MCP server materialization functions and workspace service methods.
+ *
+ * @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 Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { McpInstallStateMissing, McpRegistryOnlyInstall } from "./errors.js";
+import { applyProjectionPlans, planSingletonProjection } from "@agentxm/workspace-projection";
+import { McpConfigIoFailed, removeMcpServerFromManifest } from "@agentxm/agent-integration";
+import { NO_MATERIALIZATION_OBSERVATION } from "../manager-contract.js";
+import { McpServerManager } from "../managers.js";
+import { configuredMcpServersToDiskRefs } from "../extensions/materializable-from-disk.js";
+import { mcpRegistryResolutionKey, WorkspaceMutations } from "@agentxm/workspace-state";
+import { canReuseInstalledPackage } from "../extensions/canonical-directory.js";
+import { materializeRegistryPackageWithTreeIntegrity } from "../registry-materialization.js";
+import { computeExtensionPathsForLayout } from "@agentxm/workspace-state";
+import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { configuredRowsByName } from "@agentxm/workspace-state";
+import { isObservedInstalled } from "@agentxm/workspace-state";
+import { acceptedCanonicalObservation, prepareAcceptedCanonicalTransition, removableAcceptedCanonicalPath, } from "@agentxm/workspace-state";
+import { protectWorkspacePath } from "@agentxm/workspace-transactions";
+import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
+// Build lock entry from registry ref
+const buildMcpServerLockEntry = (ref, treeIntegrity) => ({
+    type: "registry",
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: ref.source.location,
+    extensionType: "mcp-server",
+    workspaceName: ref.server.name,
+    owner: ref.owner,
+    name: ref.name,
+    resolvedVersion: decodeVersionSync(ref.version),
+    integrity: Option.getOrElse(ref.integrity, () => ""),
+    sourceName: ref.source.name,
+    publisherBindingId: ref.publisherBindingId,
+    treeIntegrity,
+});
+// -----------------------------------------------------------------------------
+// Live Layer
+// -----------------------------------------------------------------------------
+export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const baseDir = ws.baseDir;
+    const acquired = (treeIntegrity) => ({
+        observation: NO_MATERIALIZATION_OBSERVATION,
+        treeIntegrity,
+        removal: Option.none(),
+    });
+    const materializeInstall = Effect.fn("McpServerManager.materializeInstall")(function* ({ ref, force, }) {
+        if (ref.refType !== "registry") {
+            return yield* new McpRegistryOnlyInstall({
+                serverName: ref.server.name,
+                refType: ref.refType,
+            });
+        }
+        const registryRef = ref;
+        const canonicalPath = computeExtensionPathsForLayout(path.join, ws.layout, registryRef, "mcps", registryRef.name).canonicalPath;
+        const lockedEntry = yield* ws.getLockedMcpServer(mcpRegistryResolutionKey({
+            authority: registryRef.source.location,
+            owner: registryRef.owner,
+            name: registryRef.server.name,
+        }));
+        const lockedVersion = acceptedRegistryVersionForRef(lockedEntry, registryRef);
+        const useExisting = yield* canReuseInstalledPackage({
+            installedPath: canonicalPath,
+            force: force === true,
+            refVersion: registryRef.version,
+            hasIntegrity: Option.isSome(registryRef.integrity),
+            ...(lockedVersion === undefined ? {} : { lockedVersion }),
+            existsFailureDetail: (target) => `Failed to check if canonical path exists: ${target}`,
+        });
+        if (useExisting && Option.isSome(lockedEntry)) {
+            const observedTree = yield* computeMaterializedTreeIntegrity(canonicalPath);
+            if (observedTree === lockedEntry.value.treeIntegrity) {
+                return acquired(Option.some(lockedEntry.value.treeIntegrity));
+            }
+        }
+        const materialized = yield* materializeRegistryPackageWithTreeIntegrity({
+            baseDir,
+            destinationPath: canonicalPath,
+            sourceLocation: registryRef.source.location,
+            owner: registryRef.owner,
+            type: "mcp-server",
+            name: registryRef.name,
+            version: registryRef.version,
+            integrity: registryRef.integrity,
+            messages: {
+                integrityMismatchDetail: `Integrity mismatch for ${registryRef.name}@${registryRef.version}`,
+            },
+        });
+        return acquired(Option.some(materialized.treeIntegrity));
+    });
+    const makeMaterializeRemoval = (retainCanonical) => Effect.fn("McpServerManager.materializeRemoval")(function* ({ target }) {
+        const graph = yield* ws.getDesiredStateGraph();
+        const desiredNode = graph.nodes.find((node) => node.type === "mcp-server" && node.name === target.name);
+        const closure = desiredNode === undefined || desiredNode.authority === "inline"
+            ? undefined
+            : graph.mcpSourceClosures.find((candidate) => candidate.identity === desiredNode.identity);
+        const retainShared = closure !== undefined && closure.localNames.some((name) => name !== target.name);
+        const withdrawn = {
+            observation: NO_MATERIALIZATION_OBSERVATION,
+            treeIntegrity: Option.none(),
+            removal: Option.some({
+                resolutionKey: desiredNode === undefined || desiredNode.authority === "inline"
+                    ? Option.none()
+                    : Option.some(desiredNode.identity),
+                retainShared,
+            }),
+        };
+        const configuredAgents = yield* ws.getConfiguredAgents();
+        yield* applyProjectionPlans(configuredAgents.map((agentId) => planSingletonProjection({
+            unitId: "mcp-server:native-config-entry",
+            // Multiple configured agents may share one native config file.
+            targetFile: `mcp:${target.name}:configured-agents`,
+            contributor: target,
+            adapter: {
+                observe: () => Effect.succeed({
+                    unitId: "mcp-server:native-config-entry",
+                    path: `${agentId}:${target.name}`,
+                    present: true,
+                    current: false,
+                    expectedContributors: [],
+                    observedContributors: [target.name],
+                }),
+                apply: () => removeMcpServerFromManifest(agentId, {
+                    workspaceRoot: baseDir,
+                    scope: ws.scope,
+                    serverName: target.name,
+                }).pipe(Effect.asVoid),
+            },
+        })));
+        if (retainCanonical || retainShared)
+            return withdrawn;
+        const canonical = yield* acceptedCanonicalObservation({
+            workspace: ws,
+            type: "mcp-server",
+            name: target.name,
+        });
+        const serverPath = removableAcceptedCanonicalPath(canonical);
+        if (Option.isSome(serverPath)) {
+            yield* protectWorkspacePath(serverPath.value);
+            yield* fs.remove(serverPath.value, { recursive: true, force: true }).pipe(Effect.mapError((cause) => new McpConfigIoFailed({
+                detail: `Failed to remove MCP server package: ${serverPath.value}`,
+                cause,
+            })));
+        }
+        return withdrawn;
+    });
+    const materializeUninstall = makeMaterializeRemoval(false);
+    const materializeDeactivate = makeMaterializeRemoval(true);
+    return {
+        type: "mcp-server",
+        isInstalled: Effect.fn("McpServerManager.isInstalled")(function* ({ target, }) {
+            return yield* isObservedInstalled(ws, "mcp-server", target.name);
+        }),
+        materializeInstall,
+        prepareSourceTransition: ({ ref }) => prepareAcceptedCanonicalTransition({
+            workspace: ws,
+            type: "mcp-server",
+            name: ref.server.name,
+            ref,
+        }),
+        getConfiguredSource: Effect.fn("McpServerManager.getConfiguredSource")(function* ({ target, }) {
+            const configured = yield* ws.getConfiguredMcpServerEntries();
+            return Option.fromUndefinedOr(configured[target.name]?.source);
+        }),
+        isConfigured: Effect.fn("McpServerManager.isConfigured")(function* ({ target }) {
+            const configured = yield* ws.getConfiguredMcpServerEntries();
+            return configured[target.name] !== undefined;
+        }),
+        listMaterializable: Effect.fn("McpServerManager.listMaterializable")(function* () {
+            const configured = yield* ws.records
+                .rows("mcp-server")
+                .pipe(Effect.map(configuredRowsByName));
+            return yield* configuredMcpServersToDiskRefs({ fs, path, baseDir, scope: ws.scope, layout: ws.layout }, configured);
+        }),
+        materializeUninstall,
+        materializeDeactivate,
+        upsertSettingsEntry: ({ ref, versionRange, materialization, }) => {
+            if (ref.refType !== "registry")
+                return Effect.void.pipe(Effect.withSpan("McpServerManager.upsertSettingsEntry"));
+            const registryRef = ref;
+            return validateExactResolvedVersion(`mcpServers.${ref.server.name}.resolvedVersion`, registryRef.version).pipe(Effect.flatMap(() => {
+                const treeIntegrity = materialization.pipe(Option.flatMap((facts) => facts.treeIntegrity));
+                if (Option.isNone(treeIntegrity)) {
+                    return Effect.fail(new McpInstallStateMissing({ name: registryRef.server.name }));
+                }
+                const lockEntry = buildMcpServerLockEntry(registryRef, treeIntegrity.value);
+                return ws.setMcpServer({
+                    name: ref.server.name,
+                    resolutionKey: mcpRegistryResolutionKey({
+                        authority: registryRef.source.location,
+                        owner: registryRef.owner,
+                        name: registryRef.server.name,
+                    }),
+                    lockEntry,
+                    versionRange,
+                });
+            }), Effect.withSpan("McpServerManager.upsertSettingsEntry"));
+        },
+        removeSettingsEntry: ({ target }) => ws
+            .removeMcpServerSettings(target.name)
+            .pipe(Effect.withSpan("McpServerManager.removeSettingsEntry")),
+        upsertLockfileEntry: ({ ref, materialization, }) => {
+            if (ref.refType !== "registry")
+                return ws
+                    .removeMcpServerLock(ref.server.name)
+                    .pipe(Effect.withSpan("McpServerManager.upsertLockfileEntry"));
+            const registryRef = ref;
+            return validateExactResolvedVersion(`mcpServers.${ref.server.name}.resolvedVersion`, registryRef.version).pipe(Effect.flatMap(() => {
+                const treeIntegrity = materialization.pipe(Option.flatMap((facts) => facts.treeIntegrity));
+                if (Option.isNone(treeIntegrity)) {
+                    return Effect.fail(new McpInstallStateMissing({ name: registryRef.server.name }));
+                }
+                const lockEntry = buildMcpServerLockEntry(registryRef, treeIntegrity.value);
+                return ws.setMcpServerLock({
+                    name: ref.server.name,
+                    resolutionKey: mcpRegistryResolutionKey({
+                        authority: registryRef.source.location,
+                        owner: registryRef.owner,
+                        name: registryRef.server.name,
+                    }),
+                    lockEntry,
+                    versionRange: Option.none(),
+                });
+            }), Effect.withSpan("McpServerManager.upsertLockfileEntry"));
+        },
+        removeLockfileEntry: ({ materialization, }) => {
+            const removal = materialization.pipe(Option.flatMap((facts) => facts.removal));
+            if (Option.isNone(removal)) {
+                return Effect.void.pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+            }
+            if (removal.value.retainShared || Option.isNone(removal.value.resolutionKey)) {
+                return Effect.void.pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+            }
+            return ws
+                .removeMcpServerLock(removal.value.resolutionKey.value)
+                .pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+        },
+    };
+}));
+//# sourceMappingURL=manager.js.map

package/dist/src/mcps/native-entry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Retiring a native MCP entry that a managed package now represents.
+ *
+ * Converting a native connection into an authored package leaves the original
+ * declaration in the agent's own config file. Removing it is the last step of
+ * that conversion and belongs inside the same transaction that publishes the
+ * package, so it lives in this capability beside `installMcpServer` rather
+ * than in the feature that discovered the native entry: the authoring routes
+ * that perform the conversion may not import a peer feature.
+ *
+ * The removal is conditional on the config still saying what it said when the
+ * conversion was planned. A native file that changed underneath is reported,
+ * never overwritten.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+/** One native MCP declaration, addressed exactly as its config file holds it. */
+export interface NativeMcpEntryRef {
+    /** Absolute path of the agent-native config file holding the declaration. */
+    readonly filePath: string;
+    /** Key under which that file collects its MCP servers. */
+    readonly serversKey: string;
+    /** The native connection key being retired. */
+    readonly name: string;
+}
+declare const NativeMcpEntryRetirementFailed_base: Schema.Class<NativeMcpEntryRetirementFailed, Schema.TaggedStruct<"NativeMcpEntryRetirementFailed", {
+    readonly category: Schema.Literals<readonly ["conflict", "internal", "validation"]>;
+    readonly detail: Schema.String;
+    readonly filePath: Schema.String;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A native declaration could not be retired. `category` and `detail` are the
+ * producer's own decision so the surrounding closure reports the fact rather
+ * than a generic sentence.
+ */
+export declare class NativeMcpEntryRetirementFailed extends NativeMcpEntryRetirementFailed_base {
+}
+/**
+ * Remove one native entry that a managed package replaced.
+ *
+ * A declaration that is already gone is a settled outcome: the conversion is
+ * idempotent, so re-running it after a partial retirement completes rather
+ * than refusing.
+ */
+export declare const retireNativeMcpEntry: (entry: NativeMcpEntryRef) => Effect.Effect<void, NativeMcpEntryRetirementFailed, FileSystem.FileSystem>;
+export {};
+//# sourceMappingURL=native-entry.d.ts.map

package/dist/src/mcps/native-entry.js

@@ -0,0 +1,100 @@
+/**
+ * Retiring a native MCP entry that a managed package now represents.
+ *
+ * Converting a native connection into an authored package leaves the original
+ * declaration in the agent's own config file. Removing it is the last step of
+ * that conversion and belongs inside the same transaction that publishes the
+ * package, so it lives in this capability beside `installMcpServer` rather
+ * than in the feature that discovered the native entry: the authoring routes
+ * that perform the conversion may not import a peer feature.
+ *
+ * The removal is conditional on the config still saying what it said when the
+ * conversion was planned. A native file that changed underneath is reported,
+ * never overwritten.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+/**
+ * A native declaration could not be retired. `category` and `detail` are the
+ * producer's own decision so the surrounding closure reports the fact rather
+ * than a generic sentence.
+ */
+export class NativeMcpEntryRetirementFailed extends Schema.TaggedError()("NativeMcpEntryRetirementFailed", {
+    category: Schema.Literals(["conflict", "internal", "validation"]),
+    detail: Schema.String,
+    filePath: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+}) {
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Remove one native entry that a managed package replaced.
+ *
+ * A declaration that is already gone is a settled outcome: the conversion is
+ * idempotent, so re-running it after a partial retirement completes rather
+ * than refusing.
+ */
+export const retireNativeMcpEntry = (entry) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const exists = yield* fs.exists(entry.filePath).pipe(Effect.catch(() => Effect.succeed(false)));
+    if (!exists) {
+        return yield* new NativeMcpEntryRetirementFailed({
+            category: "conflict",
+            detail: `MCP config disappeared before package conversion: ${entry.filePath}`,
+            filePath: entry.filePath,
+        });
+    }
+    const raw = yield* fs.readFileString(entry.filePath).pipe(Effect.mapError((cause) => new NativeMcpEntryRetirementFailed({
+        category: "internal",
+        detail: `Failed to read MCP config: ${entry.filePath}`,
+        filePath: entry.filePath,
+        cause,
+    })));
+    const parsed = yield* Effect.try({
+        try: () => JSON.parse(raw),
+        catch: (cause) => new NativeMcpEntryRetirementFailed({
+            category: "validation",
+            detail: `Invalid JSON in MCP config: ${entry.filePath}`,
+            filePath: entry.filePath,
+            cause,
+        }),
+    });
+    if (!isRecord(parsed)) {
+        return yield* new NativeMcpEntryRetirementFailed({
+            category: "conflict",
+            detail: `MCP config disappeared before package conversion: ${entry.filePath}`,
+            filePath: entry.filePath,
+        });
+    }
+    const servers = parsed[entry.serversKey];
+    if (!isRecord(servers)) {
+        return yield* new NativeMcpEntryRetirementFailed({
+            category: "conflict",
+            detail: `MCP server collection changed before package conversion: ${entry.filePath}`,
+            filePath: entry.filePath,
+        });
+    }
+    const declaration = servers[entry.name];
+    if (declaration === undefined)
+        return;
+    if (!isRecord(declaration)) {
+        return yield* new NativeMcpEntryRetirementFailed({
+            category: "conflict",
+            detail: `MCP server ${entry.name} changed before package conversion`,
+            filePath: entry.filePath,
+        });
+    }
+    const remaining = Object.fromEntries(Object.entries(servers).filter(([name]) => name !== entry.name));
+    yield* fs
+        .writeFileString(entry.filePath, `${JSON.stringify({ ...parsed, [entry.serversKey]: remaining }, null, 2)}\n`)
+        .pipe(Effect.mapError((cause) => new NativeMcpEntryRetirementFailed({
+        category: "internal",
+        detail: `Failed to replace native MCP config: ${entry.filePath}`,
+        filePath: entry.filePath,
+        cause,
+    })));
+});
+//# sourceMappingURL=native-entry.js.map

package/dist/src/mcps/secret-store-live.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The system-keychain implementation of {@link McpSecretStore}.
+ *
+ * The native binding is loaded lazily: a machine without a usable keychain
+ * still installs MCP servers, reporting the credential action instead of
+ * failing the closure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Layer from "effect/Layer";
+import { McpSecretStore } from "./secret-store.js";
+/** The system keychain, behind the MCP secret-store port. */
+export declare const McpSecretStoreLive: Layer.Layer<McpSecretStore>;
+//# sourceMappingURL=secret-store-live.d.ts.map

package/dist/src/mcps/secret-store-live.js

@@ -0,0 +1,58 @@
+/**
+ * The system-keychain implementation of {@link McpSecretStore}.
+ *
+ * The native binding is loaded lazily: a machine without a usable keychain
+ * still installs MCP servers, reporting the credential action instead of
+ * failing the closure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { MCP_SECRET_SERVICE, McpSecretStore, } from "./secret-store.js";
+const keyringModuleSpecifier = ["@napi-rs", "keyring"].join("/");
+const loadKeyringEntry = Effect.tryPromise({
+    try: async () => {
+        const keyring = await import(__rewriteRelativeImportExtension(keyringModuleSpecifier));
+        return keyring.Entry;
+    },
+    catch: () => undefined,
+});
+const service = {
+    read: (account) => Effect.gen(function* () {
+        const Entry = yield* loadKeyringEntry;
+        return yield* Effect.try({
+            try: () => Option.fromNullOr(new Entry(MCP_SECRET_SERVICE, account).getPassword()),
+            catch: () => undefined,
+        }).pipe(Effect.catch(() => Effect.succeed(Option.none())));
+    }).pipe(Effect.catch(() => Effect.succeed(Option.none()))),
+    write: (account, value) => Effect.gen(function* () {
+        const Entry = yield* loadKeyringEntry;
+        return yield* Effect.try({
+            try: () => {
+                new Entry(MCP_SECRET_SERVICE, account).setPassword(value);
+                return "saved";
+            },
+            catch: () => undefined,
+        });
+    }).pipe(Effect.catch(() => Effect.succeed("failed"))),
+    erase: (account) => Effect.gen(function* () {
+        const Entry = yield* loadKeyringEntry;
+        return yield* Effect.try({
+            try: () => new Entry(MCP_SECRET_SERVICE, account).deletePassword() ? "deleted" : "absent",
+            catch: () => undefined,
+        });
+    }).pipe(Effect.catch(() => Effect.succeed("failed"))),
+};
+/** The system keychain, behind the MCP secret-store port. */
+export const McpSecretStoreLive = Layer.succeed(McpSecretStore, service);
+//# sourceMappingURL=secret-store-live.js.map

package/dist/src/mcps/secret-store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The credential store MCP connection secrets are persisted in, declared as a
+ * port so the materialization capability never reaches for a platform module
+ * directly.
+ *
+ * Secrets are addressed by an opaque account derived from the workspace scope
+ * root, the local connection name, the source identity, and the input name, so
+ * two connections that share a source keep separate credentials and a
+ * workspace never reads another workspace's.
+ *
+ * Every surface answers with a typed outcome rather than failing: a keychain
+ * that is unavailable, locked, or refuses a write is an ordinary condition the
+ * install reports as a warning, not a defect that aborts an applied closure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/** The credential-store service name every AXM MCP secret is filed under. */
+export declare const MCP_SECRET_SERVICE = "axm-mcp";
+/** What identifies one stored secret. */
+export interface McpSecretIdentity {
+    /** Absolute, resolved root of the workspace scope holding the connection. */
+    readonly scopeRoot: string;
+    /** The agent-native MCP key the connection is installed as. */
+    readonly localName: string;
+    /** The resolution key (registry) or workspace identity of the source. */
+    readonly sourceIdentity: string;
+}
+/**
+ * The account one secret is stored under: an opaque digest of the four facts
+ * that make the credential unique, so no workspace path, connection name, or
+ * source appears in the credential store in clear text.
+ */
+export declare const mcpSecretAccount: (args: McpSecretIdentity & {
+    readonly inputName: string;
+}) => string;
+/** What persisting one secret settled as. */
+export type McpSecretWriteOutcome = "saved" | "failed";
+/** What erasing one secret settled as. */
+export type McpSecretEraseOutcome = "deleted" | "absent" | "failed";
+export interface McpSecretStoreService {
+    /** The stored value, or none when nothing is stored or the store is unavailable. */
+    readonly read: (account: string) => Effect.Effect<Option.Option<string>>;
+    /** Persist one value, answering whether the store accepted it. */
+    readonly write: (account: string, value: string) => Effect.Effect<McpSecretWriteOutcome>;
+    /** Erase one value, answering whether anything was there to erase. */
+    readonly erase: (account: string) => Effect.Effect<McpSecretEraseOutcome>;
+}
+declare const McpSecretStore_base: ServiceMap.ServiceClass<McpSecretStore, "@agentxm/extension-materialization/mcps/McpSecretStore", McpSecretStoreService>;
+export declare class McpSecretStore extends McpSecretStore_base {
+}
+export {};
+//# sourceMappingURL=secret-store.d.ts.map

package/dist/src/mcps/secret-store.js

@@ -0,0 +1,33 @@
+/**
+ * The credential store MCP connection secrets are persisted in, declared as a
+ * port so the materialization capability never reaches for a platform module
+ * directly.
+ *
+ * Secrets are addressed by an opaque account derived from the workspace scope
+ * root, the local connection name, the source identity, and the input name, so
+ * two connections that share a source keep separate credentials and a
+ * workspace never reads another workspace's.
+ *
+ * Every surface answers with a typed outcome rather than failing: a keychain
+ * that is unavailable, locked, or refuses a write is an ordinary condition the
+ * install reports as a warning, not a defect that aborts an applied closure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { createHash } from "node:crypto";
+/** The credential-store service name every AXM MCP secret is filed under. */
+export const MCP_SECRET_SERVICE = "axm-mcp";
+/**
+ * The account one secret is stored under: an opaque digest of the four facts
+ * that make the credential unique, so no workspace path, connection name, or
+ * source appears in the credential store in clear text.
+ */
+export const mcpSecretAccount = (args) => createHash("sha256")
+    .update([args.scopeRoot, args.localName, args.sourceIdentity, args.inputName].join("\0"))
+    .digest("hex");
+export class McpSecretStore extends ServiceMap.Service()("@agentxm/extension-materialization/mcps/McpSecretStore") {
+}
+//# sourceMappingURL=secret-store.js.map

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

@@ -0,0 +1,50 @@
+/**
+ * Typed failure family for the pack manager and dependency resolution.
+ * 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 { PackDependencyResolutionFailure } from "@agentxm/extension-resolution";
+declare const PackDefinitionInvalid_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: "PackDefinitionInvalid";
+} & Readonly<A>;
+/**
+ * A pack source or manifest input did not validate. `detail` carries the
+ * site's fact sentence verbatim.
+ */
+export declare class PackDefinitionInvalid extends PackDefinitionInvalid_base<{
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const PackInstallStateMissing_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: "PackInstallStateMissing";
+} & Readonly<A>;
+/** A lock entry was requested before install recorded the package state. */
+export declare class PackInstallStateMissing extends PackInstallStateMissing_base<{
+    readonly name: string;
+}> {
+}
+declare const PackArchiveFetchFailed_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: "PackArchiveFetchFailed";
+} & Readonly<A>;
+/** Fetching the pack archive from its source failed. */
+export declare class PackArchiveFetchFailed extends PackArchiveFetchFailed_base<{
+    readonly message: string;
+    readonly cause: unknown;
+}> {
+}
+declare const PackStagingFailed_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: "PackStagingFailed";
+} & Readonly<A>;
+/** Staging fetched pack content into the canonical tree failed. */
+export declare class PackStagingFailed extends PackStagingFailed_base<{
+    readonly packDir: string;
+    readonly cause: unknown;
+}> {
+}
+/** Every failure the pack module constructs. */
+export type PackManagerError = PackDefinitionInvalid | PackInstallStateMissing | PackArchiveFetchFailed | PackStagingFailed | PackDependencyResolutionFailure;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/packs/errors.js

@@ -0,0 +1,24 @@
+/**
+ * Typed failure family for the pack manager and dependency resolution.
+ * 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";
+/**
+ * A pack source or manifest input did not validate. `detail` carries the
+ * site's fact sentence verbatim.
+ */
+export class PackDefinitionInvalid extends Data.TaggedError("PackDefinitionInvalid") {
+}
+/** A lock entry was requested before install recorded the package state. */
+export class PackInstallStateMissing extends Data.TaggedError("PackInstallStateMissing") {
+}
+/** Fetching the pack archive from its source failed. */
+export class PackArchiveFetchFailed extends Data.TaggedError("PackArchiveFetchFailed") {
+}
+/** Staging fetched pack content into the canonical tree failed. */
+export class PackStagingFailed extends Data.TaggedError("PackStagingFailed") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/packs/manager.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pack manager service.
+ *
+ * Implements ExtensionManager<PackRef>. Delegates to existing
+ * pack materialization functions and workspace service methods.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Layer from "effect/Layer";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { PackManager } from "../managers.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+export declare const PackManagerLive: Layer.Layer<PackManager, never, FileSystem.FileSystem | Path.Path | WorkspaceMutations | SourceHostProviders>;
+//# sourceMappingURL=manager.d.ts.map