effect-agent 0.1.0-beta.85 → 0.1.0-beta.87

package/dist/capabilities/Mcp.d.mts

@@ -0,0 +1,108 @@
+import { Tool, Toolkit } from "effect/unstable/ai";
+import { Context, Crypto, Effect, Layer, Option, Schema, Scope } from "effect";
+import * as McpSchema from "effect/unstable/ai/McpSchema";
+declare namespace Mcp_d_exports {
+  export { McpConnectedServer, McpConnection, McpConnectionError, McpConnectionRequest, McpConnector, McpDiscovery, McpDiscoveryLimitExceeded, McpServerIdentity, McpToolOutputSchema, McpToolkitMismatch, connectMcp, validateMcpDiscovery };
+}
+declare const McpServerIdentity_base: Schema.Class<McpServerIdentity, Schema.Struct<{
+  readonly serverId: Schema.NonEmptyString;
+  readonly implementation: typeof McpSchema.Implementation;
+}>, {}>;
+/** Server identity copied directly from Effect AI's native MCP initialization schema. */
+declare class McpServerIdentity extends McpServerIdentity_base {}
+declare const McpConnectionRequest_base: Schema.Class<McpConnectionRequest, Schema.Struct<{
+  readonly serverId: Schema.NonEmptyString;
+  readonly maxToolCount: Schema.Int;
+  readonly maxToolDescriptionBytes: Schema.Int;
+  readonly maxDiscoveryBytes: Schema.Int;
+  readonly connectTimeoutMillis: Schema.Int;
+  readonly expectedToolkitSchemaDigest: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * Requested hard limits for an adapter-owned MCP connection and discovery response.
+ *
+ * `expectedToolkitSchemaDigest` pins the tool contract an Agent was authored
+ * against: when a connector derives its Toolkit from live discovery, a server
+ * that adds, removes, or reshapes a tool fails closed instead of silently
+ * changing what the model can call.
+ */
+declare class McpConnectionRequest extends McpConnectionRequest_base {}
+declare const McpToolOutputSchema_base: Context.ServiceClass<McpToolOutputSchema, "@effect-agent/capabilities/McpToolOutputSchema", Option.Option<McpSchema.ToolJsonSchema>>;
+/**
+ * Tool annotation recording the `outputSchema` an MCP server advertised for a
+ * Tool the framework client derived from discovery, or `None` when the server
+ * advertised none. Such a Tool's Effect success Schema is the client's result
+ * envelope rather than the wire contract, so discovery validation compares
+ * this annotation instead. Tools without the annotation, including dynamic
+ * Tools from other connectors, keep deriving it from their success Schema.
+ */
+declare class McpToolOutputSchema extends McpToolOutputSchema_base {}
+declare const McpConnectionError_base: Schema.Class<McpConnectionError, Schema.TaggedStruct<"McpConnectionError", {
+  readonly serverId: Schema.NonEmptyString;
+  readonly message: Schema.String;
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/** Typed remote connection failure; no remote execution is claimed exactly-once. */
+declare class McpConnectionError extends McpConnectionError_base {}
+declare const McpDiscoveryLimitExceeded_base: Schema.Class<McpDiscoveryLimitExceeded, Schema.TaggedStruct<"McpDiscoveryLimitExceeded", {
+  readonly serverId: Schema.NonEmptyString;
+  readonly limit: Schema.Literals<readonly ["tool-count", "tool-description-bytes", "discovery-bytes"]>;
+  readonly limitValue: Schema.Natural;
+  readonly observedValue: Schema.Natural;
+}>, import("effect/Cause").YieldableError>;
+/** Discovery exceeded an explicit caller or framework hard bound. */
+declare class McpDiscoveryLimitExceeded extends McpDiscoveryLimitExceeded_base {}
+declare const McpToolkitMismatch_base: Schema.Class<McpToolkitMismatch, Schema.TaggedStruct<"McpToolkitMismatch", {
+  readonly serverId: Schema.NonEmptyString;
+  readonly message: Schema.String;
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/** Native dynamic Toolkit names did not match the bounded MCP discovery response. */
+declare class McpToolkitMismatch extends McpToolkitMismatch_base {}
+declare const McpDiscovery_base: Schema.Class<McpDiscovery, Schema.Struct<{
+  readonly identity: typeof McpServerIdentity;
+  readonly capabilities: typeof McpSchema.ServerCapabilities;
+  readonly tools: Schema.$Array<typeof McpSchema.Tool>;
+  readonly encodedBytes: Schema.Natural;
+  readonly toolkitSchemaDigest: Schema.String;
+}>, {}>;
+/** Validated discovery metadata; native Effect AI MCP values retain provider detail. */
+declare class McpDiscovery extends McpDiscovery_base {}
+/**
+ * Raw adapter result before the framework validates count and byte limits.
+ * A connector that executes tools remotely supplies `handlers`; a connector
+ * serving an application-authored Toolkit leaves them to the application.
+ */
+interface McpConnectedServer {
+  readonly identity: McpServerIdentity;
+  readonly capabilities: McpSchema.ServerCapabilities;
+  readonly tools: ReadonlyArray<McpSchema.Tool>;
+  readonly toolkit: Toolkit.Any;
+  readonly handlers?: Layer.Layer<Tool.Handler<string>> | undefined;
+}
+/** Scoped validated MCP connection with native Effect AI dynamic Toolkit values. */
+interface McpConnection {
+  readonly discovery: McpDiscovery;
+  readonly toolkit: Toolkit.Any;
+  /** Handler Layer for `toolkit` when the connector executes tools remotely. */
+  readonly handlers?: Layer.Layer<Tool.Handler<string>> | undefined;
+}
+declare const McpConnector_base: Context.ServiceClass<McpConnector, "@effect-agent/capabilities/McpConnector", {
+  readonly connect: (request: McpConnectionRequest) => Effect.Effect<McpConnectedServer, McpConnectionError, Scope.Scope>;
+}>;
+/** Adapter port for native Effect AI MCP protocol/schema integration. */
+declare class McpConnector extends McpConnector_base {}
+/** Validate native discovery data before it enters Agent Tool context. */
+declare const validateMcpDiscovery: (request: McpConnectionRequest, server: McpConnectedServer) => Effect.Effect<McpDiscovery, McpConnectionError | McpDiscoveryLimitExceeded | McpToolkitMismatch, Crypto.Crypto>;
+/**
+ * Acquire a native connection in Scope, enforce a Clock-controlled timeout,
+ * then validate discovery before exposing its Toolkit.
+ */
+declare const connectMcp: (request: McpConnectionRequest) => Effect.Effect<{
+  discovery: McpDiscovery;
+  toolkit: Toolkit.Any;
+  handlers?: Layer.Layer<Tool.Handler<string>, never, never> | undefined;
+}, McpConnectionError | McpDiscoveryLimitExceeded | McpToolkitMismatch, Crypto.Crypto | McpConnector | Scope.Scope>;
+//#endregion
+export { McpConnectedServer, McpConnection, McpConnectionError, McpConnectionRequest, McpConnector, McpDiscovery, McpDiscoveryLimitExceeded, McpServerIdentity, McpToolOutputSchema, McpToolkitMismatch, connectMcp, Mcp_d_exports as t, validateMcpDiscovery };
+//# sourceMappingURL=Mcp.d.mts.map

package/dist/capabilities/Mcp.mjs

@@ -0,0 +1,260 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { n as utf8ByteLength } from "../utf8-DchGZRBd.mjs";
+import { Tool } from "effect/unstable/ai";
+import { Array, Context, Crypto, Duration, Effect, Encoding, JsonPointer, Option, Schema } from "effect";
+import * as McpSchema from "effect/unstable/ai/McpSchema";
+//#region src/capabilities/Mcp.ts
+var Mcp_exports = /* @__PURE__ */ __exportAll({
+	McpConnectionError: () => McpConnectionError,
+	McpConnectionRequest: () => McpConnectionRequest,
+	McpConnector: () => McpConnector,
+	McpDiscovery: () => McpDiscovery,
+	McpDiscoveryLimitExceeded: () => McpDiscoveryLimitExceeded,
+	McpServerIdentity: () => McpServerIdentity,
+	McpToolOutputSchema: () => McpToolOutputSchema,
+	McpToolkitMismatch: () => McpToolkitMismatch,
+	connectMcp: () => connectMcp,
+	validateMcpDiscovery: () => validateMcpDiscovery
+});
+const MAX_MCP_TOOLS = 128;
+const MAX_MCP_DISCOVERY_BYTES = 1048576;
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+const Sha256Digest = Schema.String.check(Schema.isPattern(/^sha256:[a-f0-9]{64}$/));
+/** Server identity copied directly from Effect AI's native MCP initialization schema. */
+var McpServerIdentity = class extends Schema.Class("@effect-agent/capabilities/McpServerIdentity")({
+	serverId: Schema.NonEmptyString,
+	implementation: McpSchema.Implementation
+}) {};
+/**
+* Requested hard limits for an adapter-owned MCP connection and discovery response.
+*
+* `expectedToolkitSchemaDigest` pins the tool contract an Agent was authored
+* against: when a connector derives its Toolkit from live discovery, a server
+* that adds, removes, or reshapes a tool fails closed instead of silently
+* changing what the model can call.
+*/
+var McpConnectionRequest = class extends Schema.Class("@effect-agent/capabilities/McpConnectionRequest")({
+	serverId: Schema.NonEmptyString,
+	maxToolCount: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_MCP_TOOLS)),
+	maxToolDescriptionBytes: PositiveInt,
+	maxDiscoveryBytes: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_MCP_DISCOVERY_BYTES)),
+	connectTimeoutMillis: PositiveInt,
+	expectedToolkitSchemaDigest: Schema.optionalKey(Sha256Digest)
+}) {};
+/**
+* Tool annotation recording the `outputSchema` an MCP server advertised for a
+* Tool the framework client derived from discovery, or `None` when the server
+* advertised none. Such a Tool's Effect success Schema is the client's result
+* envelope rather than the wire contract, so discovery validation compares
+* this annotation instead. Tools without the annotation, including dynamic
+* Tools from other connectors, keep deriving it from their success Schema.
+*/
+var McpToolOutputSchema = class extends Context.Service()("@effect-agent/capabilities/McpToolOutputSchema") {};
+/** Typed remote connection failure; no remote execution is claimed exactly-once. */
+var McpConnectionError = class extends Schema.TaggedError()("McpConnectionError", {
+	serverId: Schema.NonEmptyString,
+	message: Schema.String,
+	cause: Schema.optionalKey(Schema.Defect())
+}) {};
+/** Discovery exceeded an explicit caller or framework hard bound. */
+var McpDiscoveryLimitExceeded = class extends Schema.TaggedError()("McpDiscoveryLimitExceeded", {
+	serverId: Schema.NonEmptyString,
+	limit: Schema.Literals([
+		"tool-count",
+		"tool-description-bytes",
+		"discovery-bytes"
+	]),
+	limitValue: Schema.Natural,
+	observedValue: Schema.Natural
+}) {};
+/** Native dynamic Toolkit names did not match the bounded MCP discovery response. */
+var McpToolkitMismatch = class extends Schema.TaggedError()("McpToolkitMismatch", {
+	serverId: Schema.NonEmptyString,
+	message: Schema.String,
+	cause: Schema.optionalKey(Schema.Defect())
+}) {};
+/** Validated discovery metadata; native Effect AI MCP values retain provider detail. */
+var McpDiscovery = class extends Schema.Class("@effect-agent/capabilities/McpDiscovery")({
+	identity: McpServerIdentity,
+	capabilities: McpSchema.ServerCapabilities,
+	tools: Schema.Array(McpSchema.Tool).check(Schema.isMaxLength(MAX_MCP_TOOLS)),
+	encodedBytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_MCP_DISCOVERY_BYTES)),
+	toolkitSchemaDigest: Sha256Digest
+}) {};
+/** Adapter port for native Effect AI MCP protocol/schema integration. */
+var McpConnector = class extends Context.Service()("@effect-agent/capabilities/McpConnector") {};
+/**
+* `Tool.getJsonSchema`/`Tool.getJsonSchemaFromSchema` hoist a named, refined
+* type into `$defs` with a top-level `$ref`, but a real MCP server can only
+* ever advertise a flat `{ type: "object", ... }` `inputSchema`/`outputSchema`
+* (`McpSchema.ToolJsonSchema` has no `$ref` case). Comparing an unresolved
+* `$ref` derivation against a real discovered schema would report every tool
+* with a named parameter or success type as permanently drifted, so this
+* inlines a single top-level `$ref` before either side is digested.
+*/
+const flattenTopLevelRef = (schema) => {
+	const ref = schema["$ref"];
+	const defs = schema["$defs"];
+	if (typeof ref !== "string" || defs === void 0) return schema;
+	const key = ref.startsWith("#/$defs/") ? JsonPointer.unescapeToken(ref.slice(8)) : void 0;
+	return key !== void 0 && Object.hasOwn(defs, key) ? defs[key] : schema;
+};
+const canonicalJson = (value) => {
+	if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") return value;
+	if (Array.isArray(value)) return value.map(canonicalJson);
+	const output = {};
+	for (const [key, item] of Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) output[key] = canonicalJson(item);
+	return output;
+};
+const utf8 = (value) => {
+	const hex = Encoding.encodeHex(value);
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	return bytes;
+};
+/**
+* The `outputSchema` a Toolkit member claims. A Tool annotated with
+* `McpToolOutputSchema` reports exactly what discovery advertised, present or
+* absent; every other Tool derives it from its success Schema.
+*/
+const toolkitOutputSchema = (tool) => {
+	const discovered = Context.getOption(tool.annotations, McpToolOutputSchema);
+	if (Option.isSome(discovered)) return Option.getOrUndefined(discovered.value);
+	const derived = flattenTopLevelRef(Tool.getJsonSchemaFromSchema(tool.successSchema));
+	return derived.type === "object" ? derived : void 0;
+};
+const digestJson = Effect.fn("digestMcpSchema")(function* (serverId, value) {
+	const json = yield* Schema.decodeUnknownEffect(Schema.Json)(value).pipe(Effect.mapError((error) => McpToolkitMismatch.make({
+		cause: error,
+		serverId,
+		message: `MCP Tool schema is not canonical JSON: ${error.message}`
+	})));
+	const encoded = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Json))(canonicalJson(json)).pipe(Effect.mapError((error) => McpToolkitMismatch.make({
+		cause: error,
+		serverId,
+		message: `Could not encode canonical MCP Tool schema JSON: ${error.message}`
+	})));
+	const digest = yield* (yield* Crypto.Crypto).digest("SHA-256", utf8(encoded)).pipe(Effect.mapError((cause) => McpToolkitMismatch.make({
+		cause,
+		serverId,
+		message: "Could not hash MCP Tool schemas"
+	})));
+	return `sha256:${Encoding.encodeHex(digest)}`;
+});
+/** Validate native discovery data before it enters Agent Tool context. */
+const validateMcpDiscovery = Effect.fn("validateMcpDiscovery")(function* (request, server) {
+	if (server.identity.serverId !== request.serverId) return yield* McpToolkitMismatch.make({
+		serverId: request.serverId,
+		message: `Connected server identity '${server.identity.serverId}' does not match the requested server`
+	});
+	if (server.tools.length > request.maxToolCount) return yield* McpDiscoveryLimitExceeded.make({
+		serverId: request.serverId,
+		limit: "tool-count",
+		limitValue: request.maxToolCount,
+		observedValue: server.tools.length
+	});
+	for (const tool of server.tools) {
+		const descriptionBytes = utf8ByteLength(tool.description ?? "");
+		if (descriptionBytes > request.maxToolDescriptionBytes) return yield* McpDiscoveryLimitExceeded.make({
+			serverId: request.serverId,
+			limit: "tool-description-bytes",
+			limitValue: request.maxToolDescriptionBytes,
+			observedValue: descriptionBytes
+		});
+	}
+	const discoveredNames = server.tools.map((tool) => tool.name).sort();
+	const toolkitNames = Object.keys(server.toolkit.tools).sort();
+	if (discoveredNames.length !== toolkitNames.length || discoveredNames.some((name, index) => name !== toolkitNames[index])) return yield* McpToolkitMismatch.make({
+		serverId: request.serverId,
+		message: "Native Effect AI Toolkit names do not match MCP tool discovery"
+	});
+	const discoverySchemas = server.tools.map((tool) => ({
+		name: tool.name,
+		inputSchema: tool.inputSchema,
+		...tool.outputSchema !== void 0 ? { outputSchema: tool.outputSchema } : {}
+	})).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+	const toolkitSchemas = yield* Effect.try({
+		try: () => Object.values(server.toolkit.tools).map((tool) => {
+			const outputSchema = toolkitOutputSchema(tool);
+			return {
+				name: tool.name,
+				inputSchema: flattenTopLevelRef(Tool.getJsonSchema(tool)),
+				...outputSchema === void 0 ? {} : { outputSchema }
+			};
+		}).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0),
+		catch: (cause) => McpToolkitMismatch.make({
+			cause,
+			serverId: request.serverId,
+			message: "Could not derive JSON Schema from the native Effect AI Toolkit"
+		})
+	});
+	const discoveryDigest = yield* digestJson(request.serverId, discoverySchemas);
+	const toolkitDigest = yield* digestJson(request.serverId, toolkitSchemas);
+	if (discoveryDigest !== toolkitDigest) return yield* McpToolkitMismatch.make({
+		serverId: request.serverId,
+		message: "Native Effect AI Toolkit schemas do not match MCP tool discovery"
+	});
+	if (request.expectedToolkitSchemaDigest !== void 0 && request.expectedToolkitSchemaDigest !== toolkitDigest) return yield* McpToolkitMismatch.make({
+		serverId: request.serverId,
+		message: `MCP tool discovery digest ${toolkitDigest} does not match the expected ${request.expectedToolkitSchemaDigest}`
+	});
+	const encoded = yield* Schema.encodeEffect(Schema.Struct({
+		identity: McpServerIdentity,
+		capabilities: McpSchema.ServerCapabilities,
+		tools: Schema.Array(McpSchema.Tool)
+	}))({
+		identity: server.identity,
+		capabilities: server.capabilities,
+		tools: server.tools
+	}).pipe(Effect.mapError((error) => McpConnectionError.make({
+		cause: error,
+		serverId: request.serverId,
+		message: `Could not encode MCP discovery response: ${error.message}`
+	})));
+	const discoveryJson = yield* Schema.decodeEffect(Schema.Json)(encoded).pipe(Effect.mapError((error) => McpConnectionError.make({
+		cause: error,
+		serverId: request.serverId,
+		message: `Could not normalize MCP discovery response as JSON: ${error.message}`
+	})));
+	const discoveryText = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Json))(discoveryJson).pipe(Effect.mapError((error) => McpConnectionError.make({
+		cause: error,
+		serverId: request.serverId,
+		message: `Could not serialize MCP discovery response: ${error.message}`
+	})));
+	const discoveryBytes = utf8ByteLength(discoveryText);
+	if (discoveryBytes > request.maxDiscoveryBytes) return yield* McpDiscoveryLimitExceeded.make({
+		serverId: request.serverId,
+		limit: "discovery-bytes",
+		limitValue: request.maxDiscoveryBytes,
+		observedValue: discoveryBytes
+	});
+	return McpDiscovery.make({
+		identity: server.identity,
+		capabilities: server.capabilities,
+		tools: server.tools,
+		encodedBytes: discoveryBytes,
+		toolkitSchemaDigest: toolkitDigest
+	});
+});
+/**
+* Acquire a native connection in Scope, enforce a Clock-controlled timeout,
+* then validate discovery before exposing its Toolkit.
+*/
+const connectMcp = Effect.fn("connectMcp")(function* (request) {
+	const server = yield* (yield* McpConnector).connect(request).pipe(Effect.timeoutOrElse({
+		duration: Duration.millis(request.connectTimeoutMillis),
+		orElse: () => Effect.fail(McpConnectionError.make({
+			serverId: request.serverId,
+			message: "MCP connection timed out"
+		}))
+	}));
+	return {
+		discovery: yield* validateMcpDiscovery(request, server),
+		toolkit: server.toolkit,
+		...server.handlers === void 0 ? {} : { handlers: server.handlers }
+	};
+});
+//#endregion
+export { McpConnectionError, McpConnectionRequest, McpConnector, McpDiscovery, McpDiscoveryLimitExceeded, McpServerIdentity, McpToolOutputSchema, McpToolkitMismatch, connectMcp, Mcp_exports as t, validateMcpDiscovery };
+
+//# sourceMappingURL=Mcp.mjs.map

package/dist/capabilities/Mcp.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mcp.mjs","names":[],"sources":["../../src/capabilities/Mcp.ts"],"sourcesContent":["import {\n  Array,\n  type JsonSchema,\n  Context,\n  Crypto,\n  Duration,\n  Effect,\n  Encoding,\n  JsonPointer,\n  type Layer,\n  Option,\n  Schema,\n  type Scope,\n} from \"effect\";\nimport { Tool, type Toolkit } from \"effect/unstable/ai\";\nimport * as McpSchema from \"effect/unstable/ai/McpSchema\";\n\nimport { utf8ByteLength } from \"../core/internal/utf8.ts\";\n\nconst MAX_MCP_TOOLS = 128;\nconst MAX_MCP_DISCOVERY_BYTES = 1024 * 1024;\nconst PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));\nconst Sha256Digest = Schema.String.check(Schema.isPattern(/^sha256:[a-f0-9]{64}$/));\n\n/** Server identity copied directly from Effect AI's native MCP initialization schema. */\nexport class McpServerIdentity extends Schema.Class<McpServerIdentity>(\n  \"@effect-agent/capabilities/McpServerIdentity\",\n)({\n  serverId: Schema.NonEmptyString,\n  implementation: McpSchema.Implementation,\n}) {}\n\n/**\n * Requested hard limits for an adapter-owned MCP connection and discovery response.\n *\n * `expectedToolkitSchemaDigest` pins the tool contract an Agent was authored\n * against: when a connector derives its Toolkit from live discovery, a server\n * that adds, removes, or reshapes a tool fails closed instead of silently\n * changing what the model can call.\n */\nexport class McpConnectionRequest extends Schema.Class<McpConnectionRequest>(\n  \"@effect-agent/capabilities/McpConnectionRequest\",\n)({\n  serverId: Schema.NonEmptyString,\n  maxToolCount: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_MCP_TOOLS)),\n  maxToolDescriptionBytes: PositiveInt,\n  maxDiscoveryBytes: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_MCP_DISCOVERY_BYTES)),\n  connectTimeoutMillis: PositiveInt,\n  expectedToolkitSchemaDigest: Schema.optionalKey(Sha256Digest),\n}) {}\n\n/**\n * Tool annotation recording the `outputSchema` an MCP server advertised for a\n * Tool the framework client derived from discovery, or `None` when the server\n * advertised none. Such a Tool's Effect success Schema is the client's result\n * envelope rather than the wire contract, so discovery validation compares\n * this annotation instead. Tools without the annotation, including dynamic\n * Tools from other connectors, keep deriving it from their success Schema.\n */\nexport class McpToolOutputSchema extends Context.Service<\n  McpToolOutputSchema,\n  Option.Option<McpSchema.ToolJsonSchema>\n>()(\"@effect-agent/capabilities/McpToolOutputSchema\") {}\n\n/** Typed remote connection failure; no remote execution is claimed exactly-once. */\nexport class McpConnectionError extends Schema.TaggedError<McpConnectionError>()(\n  \"McpConnectionError\",\n  {\n    serverId: Schema.NonEmptyString,\n    message: Schema.String,\n    cause: Schema.optionalKey(Schema.Defect()),\n  },\n) {}\n\n/** Discovery exceeded an explicit caller or framework hard bound. */\nexport class McpDiscoveryLimitExceeded extends Schema.TaggedError<McpDiscoveryLimitExceeded>()(\n  \"McpDiscoveryLimitExceeded\",\n  {\n    serverId: Schema.NonEmptyString,\n    limit: Schema.Literals([\"tool-count\", \"tool-description-bytes\", \"discovery-bytes\"]),\n    limitValue: Schema.Natural,\n    observedValue: Schema.Natural,\n  },\n) {}\n\n/** Native dynamic Toolkit names did not match the bounded MCP discovery response. */\nexport class McpToolkitMismatch extends Schema.TaggedError<McpToolkitMismatch>()(\n  \"McpToolkitMismatch\",\n  {\n    serverId: Schema.NonEmptyString,\n    message: Schema.String,\n    cause: Schema.optionalKey(Schema.Defect()),\n  },\n) {}\n\n/** Validated discovery metadata; native Effect AI MCP values retain provider detail. */\nexport class McpDiscovery extends Schema.Class<McpDiscovery>(\n  \"@effect-agent/capabilities/McpDiscovery\",\n)({\n  identity: McpServerIdentity,\n  capabilities: McpSchema.ServerCapabilities,\n  tools: Schema.Array(McpSchema.Tool).check(Schema.isMaxLength(MAX_MCP_TOOLS)),\n  encodedBytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_MCP_DISCOVERY_BYTES)),\n  toolkitSchemaDigest: Sha256Digest,\n}) {}\n\n/**\n * Raw adapter result before the framework validates count and byte limits.\n * A connector that executes tools remotely supplies `handlers`; a connector\n * serving an application-authored Toolkit leaves them to the application.\n */\nexport interface McpConnectedServer {\n  readonly identity: McpServerIdentity;\n  readonly capabilities: McpSchema.ServerCapabilities;\n  readonly tools: ReadonlyArray<McpSchema.Tool>;\n  readonly toolkit: Toolkit.Any;\n  readonly handlers?: Layer.Layer<Tool.Handler<string>> | undefined;\n}\n\n/** Scoped validated MCP connection with native Effect AI dynamic Toolkit values. */\nexport interface McpConnection {\n  readonly discovery: McpDiscovery;\n  readonly toolkit: Toolkit.Any;\n  /** Handler Layer for `toolkit` when the connector executes tools remotely. */\n  readonly handlers?: Layer.Layer<Tool.Handler<string>> | undefined;\n}\n\n/** Adapter port for native Effect AI MCP protocol/schema integration. */\nexport class McpConnector extends Context.Service<\n  McpConnector,\n  {\n    readonly connect: (\n      request: McpConnectionRequest,\n    ) => Effect.Effect<McpConnectedServer, McpConnectionError, Scope.Scope>;\n  }\n>()(\"@effect-agent/capabilities/McpConnector\") {}\n\n/**\n * `Tool.getJsonSchema`/`Tool.getJsonSchemaFromSchema` hoist a named, refined\n * type into `$defs` with a top-level `$ref`, but a real MCP server can only\n * ever advertise a flat `{ type: \"object\", ... }` `inputSchema`/`outputSchema`\n * (`McpSchema.ToolJsonSchema` has no `$ref` case). Comparing an unresolved\n * `$ref` derivation against a real discovered schema would report every tool\n * with a named parameter or success type as permanently drifted, so this\n * inlines a single top-level `$ref` before either side is digested.\n */\nconst flattenTopLevelRef = (schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema => {\n  const ref = schema[\"$ref\"];\n  const defs = schema[\"$defs\"] as JsonSchema.Definitions | undefined;\n\n  if (typeof ref !== \"string\" || defs === undefined) return schema;\n\n  const key = ref.startsWith(\"#/$defs/\")\n    ? JsonPointer.unescapeToken(ref.slice(\"#/$defs/\".length))\n    : undefined;\n\n  return key !== undefined && Object.hasOwn(defs, key) ? defs[key] : schema;\n};\n\nconst canonicalJson = (value: Schema.Json): Schema.Json => {\n  if (\n    value === null ||\n    typeof value === \"string\" ||\n    typeof value === \"boolean\" ||\n    typeof value === \"number\"\n  ) {\n    return value;\n  }\n  if (Array.isArray<Schema.Json>(value)) return value.map(canonicalJson);\n  const output: Record<string, Schema.Json> = {};\n\n  // Keys sort by UTF-16 code units (RFC 8785 style): locale-aware collation varies\n  // across hosts and treats canonically equivalent distinct key sequences as equal.\n  for (const [key, item] of Object.entries(value).sort(([left], [right]) =>\n    left < right ? -1 : left > right ? 1 : 0,\n  )) {\n    output[key] = canonicalJson(item);\n  }\n\n  return output;\n};\n\nconst utf8 = (value: string): Uint8Array => {\n  const hex = Encoding.encodeHex(value);\n  const bytes = new Uint8Array(hex.length / 2);\n\n  for (let index = 0; index < bytes.length; index += 1) {\n    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);\n  }\n\n  return bytes;\n};\n\n/**\n * The `outputSchema` a Toolkit member claims. A Tool annotated with\n * `McpToolOutputSchema` reports exactly what discovery advertised, present or\n * absent; every other Tool derives it from its success Schema.\n */\nconst toolkitOutputSchema = (tool: Tool.Any): JsonSchema.JsonSchema | undefined => {\n  const discovered = Context.getOption(tool.annotations, McpToolOutputSchema);\n\n  if (Option.isSome(discovered)) return Option.getOrUndefined(discovered.value);\n  const derived = flattenTopLevelRef(Tool.getJsonSchemaFromSchema(tool.successSchema));\n\n  return derived.type === \"object\" ? derived : undefined;\n};\n\nconst digestJson = Effect.fn(\"digestMcpSchema\")(function* (serverId: string, value: unknown) {\n  const json = yield* Schema.decodeUnknownEffect(Schema.Json)(value).pipe(\n    Effect.mapError((error) =>\n      McpToolkitMismatch.make({\n        cause: error,\n        serverId,\n        message: `MCP Tool schema is not canonical JSON: ${error.message}`,\n      }),\n    ),\n  );\n\n  const encoded = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Json))(\n    canonicalJson(json),\n  ).pipe(\n    Effect.mapError((error) =>\n      McpToolkitMismatch.make({\n        cause: error,\n        serverId,\n        message: `Could not encode canonical MCP Tool schema JSON: ${error.message}`,\n      }),\n    ),\n  );\n\n  const crypto = yield* Crypto.Crypto;\n\n  const digest = yield* crypto.digest(\"SHA-256\", utf8(encoded)).pipe(\n    Effect.mapError((cause) =>\n      McpToolkitMismatch.make({\n        cause,\n        serverId,\n        message: \"Could not hash MCP Tool schemas\",\n      }),\n    ),\n  );\n\n  return `sha256:${Encoding.encodeHex(digest)}`;\n});\n\n/** Validate native discovery data before it enters Agent Tool context. */\nexport const validateMcpDiscovery = Effect.fn(\"validateMcpDiscovery\")(function* (\n  request: McpConnectionRequest,\n  server: McpConnectedServer,\n) {\n  if (server.identity.serverId !== request.serverId) {\n    return yield* McpToolkitMismatch.make({\n      serverId: request.serverId,\n      message: `Connected server identity '${server.identity.serverId}' does not match the requested server`,\n    });\n  }\n  if (server.tools.length > request.maxToolCount) {\n    return yield* McpDiscoveryLimitExceeded.make({\n      serverId: request.serverId,\n      limit: \"tool-count\",\n      limitValue: request.maxToolCount,\n      observedValue: server.tools.length,\n    });\n  }\n  for (const tool of server.tools) {\n    const descriptionBytes = utf8ByteLength(tool.description ?? \"\");\n\n    if (descriptionBytes > request.maxToolDescriptionBytes) {\n      return yield* McpDiscoveryLimitExceeded.make({\n        serverId: request.serverId,\n        limit: \"tool-description-bytes\",\n        limitValue: request.maxToolDescriptionBytes,\n        observedValue: descriptionBytes,\n      });\n    }\n  }\n  const discoveredNames = server.tools.map((tool) => tool.name).sort();\n  const toolkitNames = Object.keys(server.toolkit.tools).sort();\n\n  if (\n    discoveredNames.length !== toolkitNames.length ||\n    discoveredNames.some((name, index) => name !== toolkitNames[index])\n  ) {\n    return yield* McpToolkitMismatch.make({\n      serverId: request.serverId,\n      message: \"Native Effect AI Toolkit names do not match MCP tool discovery\",\n    });\n  }\n\n  const discoverySchemas = server.tools\n    .map((tool) => ({\n      name: tool.name,\n      inputSchema: tool.inputSchema,\n      ...(tool.outputSchema !== undefined ? { outputSchema: tool.outputSchema } : {}),\n    }))\n    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));\n\n  const toolkitSchemas = yield* Effect.try({\n    try: () =>\n      Object.values(server.toolkit.tools)\n        .map((tool) => {\n          const outputSchema = toolkitOutputSchema(tool);\n\n          return {\n            name: tool.name,\n            inputSchema: flattenTopLevelRef(Tool.getJsonSchema(tool)),\n            ...(outputSchema === undefined ? {} : { outputSchema }),\n          };\n        })\n        .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0)),\n    catch: (cause) =>\n      McpToolkitMismatch.make({\n        cause,\n        serverId: request.serverId,\n        message: \"Could not derive JSON Schema from the native Effect AI Toolkit\",\n      }),\n  });\n\n  const discoveryDigest = yield* digestJson(request.serverId, discoverySchemas);\n  const toolkitDigest = yield* digestJson(request.serverId, toolkitSchemas);\n\n  if (discoveryDigest !== toolkitDigest) {\n    return yield* McpToolkitMismatch.make({\n      serverId: request.serverId,\n      message: \"Native Effect AI Toolkit schemas do not match MCP tool discovery\",\n    });\n  }\n  if (\n    request.expectedToolkitSchemaDigest !== undefined &&\n    request.expectedToolkitSchemaDigest !== toolkitDigest\n  ) {\n    return yield* McpToolkitMismatch.make({\n      serverId: request.serverId,\n      message: `MCP tool discovery digest ${toolkitDigest} does not match the expected ${request.expectedToolkitSchemaDigest}`,\n    });\n  }\n\n  const encoded = yield* Schema.encodeEffect(\n    Schema.Struct({\n      identity: McpServerIdentity,\n      capabilities: McpSchema.ServerCapabilities,\n      tools: Schema.Array(McpSchema.Tool),\n    }),\n  )({\n    identity: server.identity,\n    capabilities: server.capabilities,\n    tools: server.tools,\n  }).pipe(\n    Effect.mapError((error) =>\n      McpConnectionError.make({\n        cause: error,\n        serverId: request.serverId,\n        message: `Could not encode MCP discovery response: ${error.message}`,\n      }),\n    ),\n  );\n\n  const discoveryJson = yield* Schema.decodeEffect(Schema.Json)(encoded).pipe(\n    Effect.mapError((error) =>\n      McpConnectionError.make({\n        cause: error,\n        serverId: request.serverId,\n        message: `Could not normalize MCP discovery response as JSON: ${error.message}`,\n      }),\n    ),\n  );\n\n  const discoveryText = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Json))(\n    discoveryJson,\n  ).pipe(\n    Effect.mapError((error) =>\n      McpConnectionError.make({\n        cause: error,\n        serverId: request.serverId,\n        message: `Could not serialize MCP discovery response: ${error.message}`,\n      }),\n    ),\n  );\n\n  const discoveryBytes = utf8ByteLength(discoveryText);\n\n  if (discoveryBytes > request.maxDiscoveryBytes) {\n    return yield* McpDiscoveryLimitExceeded.make({\n      serverId: request.serverId,\n      limit: \"discovery-bytes\",\n      limitValue: request.maxDiscoveryBytes,\n      observedValue: discoveryBytes,\n    });\n  }\n\n  return McpDiscovery.make({\n    identity: server.identity,\n    capabilities: server.capabilities,\n    tools: server.tools,\n    encodedBytes: discoveryBytes,\n    toolkitSchemaDigest: toolkitDigest,\n  });\n});\n\n/**\n * Acquire a native connection in Scope, enforce a Clock-controlled timeout,\n * then validate discovery before exposing its Toolkit.\n */\nexport const connectMcp = Effect.fn(\"connectMcp\")(function* (request: McpConnectionRequest) {\n  const connector = yield* McpConnector;\n\n  const server = yield* connector.connect(request).pipe(\n    Effect.timeoutOrElse({\n      duration: Duration.millis(request.connectTimeoutMillis),\n      orElse: () =>\n        Effect.fail(\n          McpConnectionError.make({\n            serverId: request.serverId,\n            message: \"MCP connection timed out\",\n          }),\n        ),\n    }),\n  );\n\n  const discovery = yield* validateMcpDiscovery(request, server);\n\n  return {\n    discovery,\n    toolkit: server.toolkit,\n    ...(server.handlers === undefined ? {} : { handlers: server.handlers }),\n  } satisfies McpConnection;\n});\n"],"mappings":"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"}

package/dist/capabilities/McpClient.d.mts

@@ -0,0 +1,115 @@
+import { McpConnectionError, McpConnector } from "./Mcp.mjs";
+import { Tool, Toolkit } from "effect/unstable/ai";
+import { Cause, Effect, Layer, Schema, Scope } from "effect";
+import * as McpSchema from "effect/unstable/ai/McpSchema";
+import { Headers, HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { RpcClient } from "effect/unstable/rpc";
+declare namespace McpClient_d_exports {
+  export { McpClientProtocolVersion, McpHttpTransport, McpHttpTransportOptions, McpServerTransport, McpStdioTransport, McpStdioTransportOptions, McpTool, McpToolCallFailed, McpToolResult, McpToolkit, McpTransportRequirements, defaultMcpClientInfo, layer };
+}
+/**
+ * The protocol revisions this client negotiates, as implemented by Effect AI's
+ * native MCP protocol adapters. The newest revision is offered first; a server
+ * answering with any other listed revision is accepted, anything else fails.
+ */
+declare const McpClientProtocolVersion: Schema.Literals<readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"]>;
+type McpClientProtocolVersion = typeof McpClientProtocolVersion.Type;
+/** Identity this client presents to servers during `initialize`. */
+declare const defaultMcpClientInfo: McpSchema.Implementation;
+declare const McpToolResult_base: Schema.Class<McpToolResult, Schema.Struct<{
+  readonly content: Schema.$Array<Schema.Union<readonly [typeof McpSchema.TextContent, typeof McpSchema.ImageContent, typeof McpSchema.AudioContent, typeof McpSchema.EmbeddedResource, typeof McpSchema.ResourceLink]>>;
+  readonly structuredContent: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, {}>;
+/**
+ * The model-visible result of a remote MCP tool call: the server's content
+ * blocks and, when the tool declares an `outputSchema`, its structured result.
+ * A result with `isError` never becomes this value; it fails the Tool Call.
+ */
+declare class McpToolResult extends McpToolResult_base {}
+declare const McpToolCallFailed_base: Schema.Class<McpToolCallFailed, Schema.TaggedStruct<"McpToolCallFailed", {
+  readonly serverId: Schema.NonEmptyString;
+  readonly tool: Schema.NonEmptyString;
+  readonly reason: Schema.Literals<readonly ["tool-error", "invalid-arguments", "protocol-error", "transport"]>;
+  readonly message: Schema.String;
+  readonly content: Schema.optionalKey<Schema.$Array<Schema.Union<readonly [typeof McpSchema.TextContent, typeof McpSchema.ImageContent, typeof McpSchema.AudioContent, typeof McpSchema.EmbeddedResource, typeof McpSchema.ResourceLink]>>>;
+}>, Cause.YieldableError>;
+/**
+ * Typed failure of one remote MCP tool call. `tool-error` carries the server's
+ * error content; the other reasons describe why no trustworthy result exists.
+ * None of them claims the remote effect did not happen.
+ */
+declare class McpToolCallFailed extends McpToolCallFailed_base {}
+/**
+ * One reachable MCP server. `protocol` acquires a JSON-RPC transport in the
+ * caller's Scope; `R` names the platform services that transport needs so the
+ * connector Layer keeps them in its requirements.
+ */
+interface McpServerTransport<R = never> {
+  readonly serverId: string;
+  /**
+   * Whether the server's `readOnlyHint`, `idempotentHint`, and
+   * `destructiveHint` may set the framework execution class of its tools.
+   * Hints are server-declared and untrusted, so the default leaves every
+   * remote tool `uncertain`.
+   */
+  readonly trustToolAnnotations: boolean;
+  readonly protocol: Effect.Effect<RpcClient.Protocol["Service"], McpConnectionError, Scope.Scope | R>;
+}
+/** Streamable HTTP server address. Header values may carry credentials the application owns. */
+interface McpHttpTransportOptions {
+  readonly serverId: string;
+  readonly url: string;
+  readonly headers?: Headers.Input | undefined;
+  /** Largest accepted response message. Defaults to 4 MiB. */
+  readonly maxMessageBytes?: number | undefined;
+  readonly trustToolAnnotations?: boolean | undefined;
+}
+/** A local MCP server process speaking newline-delimited JSON-RPC on stdio. */
+interface McpStdioTransportOptions {
+  readonly serverId: string;
+  readonly command: string;
+  readonly args?: ReadonlyArray<string> | undefined;
+  readonly cwd?: string | undefined;
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  /** Largest accepted stdout frame. Defaults to 4 MiB. */
+  readonly maxMessageBytes?: number | undefined;
+  readonly trustToolAnnotations?: boolean | undefined;
+}
+/** Streamable HTTP transport for one remote MCP server; requires `HttpClient`. */
+declare const McpHttpTransport: {
+  readonly make: (options: McpHttpTransportOptions) => McpServerTransport<HttpClient.HttpClient>;
+};
+/** stdio transport for one local MCP server process; requires `ChildProcessSpawner`. */
+declare const McpStdioTransport: {
+  readonly make: (options: McpStdioTransportOptions) => McpServerTransport<ChildProcessSpawner.ChildProcessSpawner>;
+};
+/**
+ * Effect AI Tool derived from one discovered MCP tool. Its parameters are the
+ * server's JSON Schema, so handlers receive `unknown` and the server validates
+ * arguments; `Tool.getJsonSchema` still advertises the discovered schema. A
+ * failed call returns `McpToolCallFailed` to the model as a failed tool result.
+ */
+type McpTool = Tool.Tool<string, {
+  readonly parameters: typeof Schema.Unknown;
+  readonly success: typeof McpToolResult;
+  readonly failure: typeof McpToolCallFailed;
+  readonly failureMode: "return";
+}>;
+/** Toolkit of discovered MCP tools; every member forwards `tools/call` to its server. */
+type McpToolkit = Toolkit.Toolkit<Record<string, McpTool>>;
+/** Platform services one transport needs, as declared by `McpServerTransport<R>`. */
+type McpTransportRequirements<Transport> = Transport extends McpServerTransport<infer R> ? R : never;
+/**
+ * `McpConnector` over real transports. Each `connect` acquires the transport
+ * in the caller's Scope, negotiates a protocol revision, lists tools within the
+ * request bounds, and returns dynamic Effect AI Tools plus the handler Layer
+ * that forwards their calls. The Layer requires the union of every
+ * transport's platform services.
+ */
+declare const layer: <const Transports extends ReadonlyArray<McpServerTransport<unknown>>>(transports: Transports, options?: {
+  readonly clientInfo?: McpSchema.Implementation | undefined;
+}) => Layer.Layer<McpConnector, never, McpTransportRequirements<Transports[number]>>;
+//#endregion
+export { McpClientProtocolVersion, McpHttpTransport, McpHttpTransportOptions, McpServerTransport, McpStdioTransport, McpStdioTransportOptions, McpTool, McpToolCallFailed, McpToolResult, McpToolkit, McpTransportRequirements, defaultMcpClientInfo, layer, McpClient_d_exports as t };
+//# sourceMappingURL=McpClient.d.mts.map