@gjermundgaraba/effect-actions 0.9.0 → 0.11.0

package/dist/internal/mcp.mjs

@@ -0,0 +1,182 @@
+import { Media, isMarked, kindOf } from "./media.mjs";
+import { Predicate, Schema, SchemaAST } from "effect";
+import { McpProtocol } from "effect/ai";
+//#region src/internal/mcp.ts
+/**
+* The one protocol revision served over HTTP. 2026-07-28 is stateless: every request
+* stands alone. The stateful revisions keep a session per `initialize`, which the native
+* HTTP runtime never expires and which no identity owns. A mixed endpoint's gate relies on it
+* too: it decides from the routing headers, which the native runtime checks against the body
+* of a stateless request alone, so serving a stateful revision over HTTP would open the gate.
+*/
+const httpProtocol = McpProtocol.v2026_07_28;
+/** Where `ActionMcp.layerHttp` serves, and `Testing.mcpClient` calls, by default. */
+const defaultPath = "/mcp";
+/** The parameter a method's `mcp-name` header repeats, as the native runtime routes it. */
+const routed = (method, params) => method === "resources/read" ? params.uri : params.name;
+/**
+* One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it:
+* the headers routing it, which repeat what its body says, and its JSON-RPC body. The client
+* metadata goes in `_meta`, under any given, such as a `progressToken`; the protocol version
+* is always the request's own.
+*/
+const statelessRequest = (method, params) => {
+	const { protocolVersion } = httpProtocol;
+	const name = routed(method, params);
+	return {
+		headers: {
+			accept: "application/json, text/event-stream",
+			"mcp-protocol-version": protocolVersion,
+			"mcp-method": method,
+			...Predicate.isString(name) ? { "mcp-name": name } : {}
+		},
+		body: {
+			jsonrpc: "2.0",
+			id: 1,
+			method,
+			params: {
+				...params,
+				_meta: {
+					"io.modelcontextprotocol/clientCapabilities": {},
+					"io.modelcontextprotocol/clientInfo": {
+						name: "effect-actions",
+						version: "0"
+					},
+					...params._meta,
+					"io.modelcontextprotocol/protocolVersion": protocolVersion
+				}
+			}
+		}
+	};
+};
+/** The `_meta` key of a lifted block naming its field. */
+const fieldKey = "effect-actions/field";
+const isMedia = Schema.is(Media);
+const isMediaArray = Schema.is(Schema.Array(Media));
+/** The schema `ast` stands for, a `Schema.suspend` resolved, which only delays its definition. */
+const resolved = (ast) => SchemaAST.isSuspend(ast) ? resolved(ast.thunk()) : ast;
+/** The kind `ast` is, suspended or not. */
+const kindIn = (ast) => kindOf(resolved(ast));
+/**
+* The media `ast` is, one value or an array of them, as a whole success may be: an array without
+* an encoding of its own whose every element is media of one kind, such as `Schema.Array` or
+* `Schema.NonEmptyArray` of it.
+*/
+const wholeOf = (suspended) => {
+	const ast = resolved(suspended);
+	const one = kindOf(ast);
+	if (one !== void 0) return {
+		kind: one,
+		many: false
+	};
+	if (!SchemaAST.isArrays(ast) || ast.encoding !== void 0) return void 0;
+	const [kind, ...others] = new Set([...ast.elements, ...ast.rest].map(kindIn));
+	return kind === void 0 || others.length > 0 ? void 0 : {
+		kind,
+		many: true
+	};
+};
+/**
+* The media a field's `ast` is: one value, which `Schema.optional` or `Schema.optionalKey` may
+* make absent, or an array, which they may not, as no block would tell an absent one from an
+* empty one.
+*/
+const fieldOf = (field) => {
+	const optional = field.context?.isOptional === true;
+	const ast = resolved(field);
+	if (optional && SchemaAST.isUnion(ast) && ast.types.length === 2) {
+		const [value, ...more] = ast.types.filter((member) => !SchemaAST.isUndefined(member));
+		const kind = value === void 0 || more.length > 0 ? void 0 : kindIn(value);
+		return kind === void 0 ? void 0 : {
+			kind,
+			many: false
+		};
+	}
+	const whole = wholeOf(ast);
+	return whole === void 0 || optional && whole.many ? void 0 : whole;
+};
+/**
+* How an MCP tool sends `success`: it lifts the success itself, one value or an array, or the
+* top-level media fields of a struct without an encoding of its own, keyed by strings, and
+* sends the rest of the struct, if any is left.
+*/
+const liftOf = (success) => {
+	const ast = resolved(success.ast);
+	const whole = wholeOf(ast);
+	if (whole !== void 0) return {
+		fields: [{
+			name: void 0,
+			...whole
+		}],
+		rest: void 0
+	};
+	if (!SchemaAST.isObjects(ast) || ast.encoding !== void 0) return {
+		fields: [],
+		rest: success
+	};
+	const fields = ast.propertySignatures.flatMap(({ name, type }) => {
+		const field = fieldOf(type);
+		return field === void 0 ? [] : [{
+			name: String(name),
+			...field
+		}];
+	});
+	if (fields.length === 0) return {
+		fields,
+		rest: success
+	};
+	const names = new Set(fields.map(({ name }) => name));
+	const rest = ast.propertySignatures.filter(({ name }) => !names.has(name));
+	const { identifier: _identifier, ...annotations } = ast.annotations ?? {};
+	return {
+		fields,
+		rest: rest.length === 0 && ast.indexSignatures.length === 0 ? void 0 : Schema.make(new SchemaAST.Objects(rest, ast.indexSignatures, annotations))
+	};
+};
+/** The schemas `ast` is made of, its encoded side included. */
+const partsOf = (ast) => [
+	...SchemaAST.isDeclaration(ast) ? ast.typeParameters : [],
+	...SchemaAST.isArrays(ast) ? [...ast.elements, ...ast.rest] : [],
+	...SchemaAST.isObjects(ast) ? [...ast.propertySignatures, ...ast.indexSignatures].map(({ type }) => type) : [],
+	...SchemaAST.isUnion(ast) ? ast.types : [],
+	...SchemaAST.isSuspend(ast) ? [ast.thunk()] : [],
+	...(ast.encoding ?? []).map(({ to }) => to)
+];
+/** Whether `ast` holds media anywhere, each schema visited once, so a recursive one ends. */
+const holdsMedia = (ast) => {
+	const seen = /* @__PURE__ */ new Set();
+	const pending = [ast];
+	for (let next = pending.pop(); next !== void 0; next = pending.pop()) {
+		if (seen.has(next)) continue;
+		seen.add(next);
+		if (isMarked(next)) return true;
+		pending.push(...partsOf(next));
+	}
+	return false;
+};
+/**
+* Whether `action`, whose success an MCP tool lifts as `lift` says, holds media where no tool
+* lifts it: in its input, in a declared error, or in the rest of its success, such as nested in
+* a field or in a union.
+*/
+const isMisplaced = (action, { rest }) => {
+	return [
+		action.input,
+		...action.error,
+		...rest === void 0 ? [] : [rest]
+	].some(({ ast }) => holdsMedia(ast));
+};
+/**
+* The media `lift` finds in `success`, a decoded value its schema has validated: the whole
+* success's, or each field's, in field order, an array's in its order, none for an absent field.
+*/
+const liftedFrom = (lift, success) => lift.fields.flatMap(({ name, kind, many }) => {
+	const value = name === void 0 ? success : Predicate.hasProperty(success, name) ? success[name] : void 0;
+	return (many ? isMediaArray(value) ? value : [] : isMedia(value) ? [value] : []).map((media) => ({
+		kind,
+		field: name,
+		value: media
+	}));
+});
+//#endregion
+export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, statelessRequest };

package/dist/internal/media.d.mts

@@ -0,0 +1,8 @@
+import { Schema, SchemaAST } from "effect";
+//#region src/internal/media.d.ts
+/** An image, a media field's schema, as `Action.Image` exports it. */
+export declare const Image: Schema.Struct<{
+  readonly data: Schema.Uint8Array;
+  readonly mimeType: Schema.String;
+}>;
+//#endregion

package/dist/internal/media.mjs

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+//#region src/internal/media.ts
+/**
+* The annotation marking a media kind's schema, naming the MCP content block a value of it is
+* lifted into: `Action.Image`'s is `"image"`.
+*/
+const mediaKey = "effect-actions/media";
+/** What every media kind holds: bytes, and their MIME type. */
+const Media = Schema.Struct({
+	data: Schema.Uint8Array,
+	mimeType: Schema.String
+});
+/** An image, a media field's schema, as `Action.Image` exports it. */
+const Image = Media.annotate({ [mediaKey]: "image" });
+/**
+* Whether `ast` is marked as media, read from its own annotations: a copy, such as an optional
+* key or one with checks added, keeps them, and so does one with an encoding of its own.
+*/
+const isMarked = (ast) => ast.annotations?.[mediaKey] === "image";
+/**
+* The kind `ast` is, when its values are the media they encode to: marked, without an encoding
+* of its own, which would send its values as something else.
+*/
+const kindOf = (ast) => isMarked(ast) && ast.encoding === void 0 ? "image" : void 0;
+//#endregion
+export { Image, Media, isMarked, kindOf };

package/dist/internal/memory.d.mts

@@ -0,0 +1,6 @@
+import { Layer } from "effect";
+import { HttpClient, HttpRouter, HttpServer } from "effect/http";
+//#region src/internal/memory.d.ts
+/** What in-memory routes may leave to the host: the router, the platform, nothing per request. */
+export type Served = HttpRouter.HttpRouter | HttpRouter.Request<"Requires", never> | HttpRouter.Request<"GlobalRequires", never> | HttpRouter.Request<"Error", any> | HttpRouter.Request<"GlobalError", any> | Layer.Success<typeof HttpServer.layerServices>;
+//#endregion

package/dist/internal/memory.mjs

@@ -0,0 +1,38 @@
+import { Effect, Layer, Predicate, Stream } from "effect";
+import { FetchHttpClient, HttpBody, HttpClient, HttpClientRequest } from "effect/http";
+//#region src/internal/memory.ts
+/** Where relative request URLs resolve, so a client needs no `baseUrl`. */
+const origin = "http://localhost/";
+/**
+* `request`, a streamed body turned into a web stream in the current context. The native client
+* turns it in its send, under the in-memory `fetch`, where another client the stream calls
+* would send to the routes too.
+*/
+const pulled = (request) => {
+	const body = request.body;
+	if (!Predicate.isTagged(body, "Stream")) return Effect.succeed(request);
+	return Effect.map(Stream.toReadableStreamEffect(body.stream), (readable) => HttpClientRequest.setBody(request, HttpBody.raw(readable, {
+		contentType: body.contentType,
+		contentLength: body.contentLength
+	})).pipe(HttpClientRequest.updateHeaders(() => request.headers)));
+};
+/**
+* The native `HttpClient`, sending every request to `handler` instead of the network. A
+* relative URL resolves against `http://localhost/`, as a page there would resolve it, and a
+* request carries the `Host` header of its URL, as one over the network does. The client is
+* its own: the program's other clients keep their `fetch`, and get none of its requests.
+*/
+const clientOf = (handler) => {
+	const fetch = (input, init) => {
+		const request = new Request(input, init);
+		if (!request.headers.has("host")) request.headers.set("host", new URL(request.url).host);
+		return handler(request);
+	};
+	return Layer.effect(HttpClient.HttpClient, Effect.map(HttpClient.HttpClient, (native) => HttpClient.makeWith((request) => Effect.flatMap(request, (mapped) => {
+		const resolved = URL.canParse(mapped.url) ? null : URL.parse(mapped.url, origin);
+		const sent = resolved === null ? mapped : HttpClientRequest.setUrl(mapped, resolved.href);
+		return Effect.flatMap(pulled(sent), (ready) => native.postprocess(Effect.succeed(ready)).pipe(Effect.provideService(FetchHttpClient.Fetch, fetch)));
+	}), native.preprocess))).pipe(Layer.provide(Layer.fresh(FetchHttpClient.layer)));
+};
+//#endregion
+export { clientOf };

package/dist/internal/refusal.mjs

@@ -0,0 +1,67 @@
+import { Refusal, statuses } from "./errors.mjs";
+import { Cause, Context, Effect, Exit, Option, Predicate, Ref, Schema } from "effect";
+import { HttpServerResponse } from "effect/http";
+//#region src/internal/refusal.ts
+/** An RFC 6750 error description: printable ASCII but `"` and `\`. */
+const description = /^[\x20\x21\x23-\x5B\x5D-\x7E]+$/;
+/**
+* An RFC 9110 challenge of `scheme` and the parameters given, each a quoted string whose `"`
+* and `\` are escaped: a metadata URL's query may hold a `\`.
+*/
+const challenge = (scheme, parameters) => {
+	const given = parameters.flatMap(([name, value]) => value === void 0 ? [] : [`${name}="${value.replace(/["\\]/g, "\\$&")}"`]);
+	return given.length === 0 ? scheme : `${scheme} ${given.join(", ")}`;
+};
+/** An RFC 6750 `Bearer` challenge of the parameters given. */
+const bearer = (parameters) => challenge("Bearer", parameters);
+const encode = Schema.encodeSync(Refusal);
+/** Whether `error` is a built-in refusal, `Unauthenticated` or `Forbidden`. */
+const isRefusal = Schema.is(Refusal);
+/**
+* The RFC 6750 `insufficient_scope` challenge an OAuth client steps up on, for a `Forbidden`
+* naming scopes, naming the resource's metadata URL when there is one.
+*/
+const insufficientScope = (error, metadataUrl) => Predicate.isTagged(error, "Forbidden") && error.scopes !== void 0 ? bearer([
+	["error", "insufficient_scope"],
+	["scope", error.scopes.join(" ")],
+	["resource_metadata", metadataUrl],
+	["error_description", description.test(error.message) ? error.message : void 0]
+]) : void 0;
+/** A refusal as its JSON with its status alone, as a scheme no OAuth client acts on answers it. */
+const plain = (error) => HttpServerResponse.jsonUnsafe(encode(error), { status: statuses[error._tag] });
+/**
+* A refusal as its JSON with its status, as every endpoint declares it, and its
+* `insufficient_scope` challenge if it has one.
+*/
+const answer = (error, metadataUrl) => {
+	const response = plain(error);
+	const scoped = insufficientScope(error, metadataUrl);
+	return scoped === void 0 ? response : HttpServerResponse.setHeader(response, "www-authenticate", scoped);
+};
+/** The step-up refusal a tool's call under `answerStepUp` failed with, which answers its request. */
+var SteppedUp = class extends Context.Service()("effect-actions/SteppedUp") {};
+/**
+* Whether `error` is a refusal an OAuth client acts on: `Unauthenticated`, or `Forbidden`
+* naming scopes.
+*/
+const isStepUp = (error) => isRefusal(error) && (!Predicate.isTagged(error, "Forbidden") || error.scopes !== void 0);
+/**
+* A protected MCP tool's `call`, whose step-up refusal answers the request under a Bearer
+* descriptor's `answerStepUp`. Elsewhere it is `call` as it is.
+*/
+const recordStepUp = (call) => Effect.tapError(call, (error) => isStepUp(error) ? Effect.flatMap(Effect.serviceOption(SteppedUp), (slot) => Option.isSome(slot) ? Ref.set(slot.value, Option.some(error)) : Effect.void) : Effect.void);
+/**
+* An MCP request, answered with the step-up refusal a tool's call in it failed with, its
+* status, JSON and challenge naming `metadataUrl`, however the request ended short of a defect
+* or an interruption: a tool's failure is a successful result, and MCP authorization requires
+* 401 or 403.
+*/
+const answerStepUp = (route, metadataUrl) => Effect.gen(function* () {
+	const slot = yield* Ref.make(Option.none());
+	const exit = yield* Effect.exit(Effect.provideService(route, SteppedUp, slot));
+	const refused = yield* Ref.get(slot);
+	const broken = Exit.isFailure(exit) && (Cause.hasDies(exit.cause) || Cause.hasInterrupts(exit.cause));
+	return Option.isSome(refused) && !broken ? answer(refused.value, metadataUrl) : yield* exit;
+});
+//#endregion
+export { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain, recordStepUp };

package/dist/internal/schema-errors.mjs

@@ -0,0 +1,20 @@
+import { InvalidInput } from "./errors.mjs";
+import { Effect } from "effect";
+import { HttpApiMiddleware } from "effect/http-api";
+//#region src/internal/schema-errors.ts
+/**
+* `HttpApiBuilder` reports these kinds while encoding the handler's answer, after the
+* handler ran; every other kind (`Payload`, `Params`, `Headers`, `Query`) comes from
+* decoding the request before it.
+*/
+const responseKinds = /* @__PURE__ */ new Set(["Body", "ResponseHeaders"]);
+/**
+* The native middleware answering schema failures: a request that does not decode with
+* `InvalidInput`, the schema's own message and issues. A result that does not encode stays the
+* native failure, which Effect answers with an empty 500 and reports.
+*/
+var SchemaErrors = class extends HttpApiMiddleware.Service()("effect-actions/http/SchemaErrors", { error: [InvalidInput] }) {};
+/** `SchemaErrors`' server side, built by `ActionHttp.layer` alone, so a client's bundle leaves it out. */
+const schemaErrors = () => HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(responseKinds.has(failure.kind) ? failure : InvalidInput.fromSchemaError(failure.cause)));
+//#endregion
+export { SchemaErrors, schemaErrors };

package/dist/internal/tools.mjs

@@ -1,74 +1,44 @@
-import { assertDistinct, projectedErrors } from "./actions.mjs";
-import { dispatch } from "./implementation.mjs";
-import { Context, Effect, Schema } from "effect";
+import { assertOnce, projectedErrors } from "./actions.mjs";
+import { acquire } from "./implementation.mjs";
+import { Effect, Schema } from "effect";
 import { Tool, Toolkit } from "effect/ai";
 //#region src/internal/tools.ts
+/** `tool` annotated with `value` under `key`, or as it is where `value` is not given. */
+const annotateIf = (tool, key, value) => value === void 0 ? tool : tool.annotate(key, value);
 /**
-* The success field an MCP tool sends as a raw text block, from `mcp.text`. The native
-* server reads a tool's annotations when it registers the tool, so `ActionMcp` finds
-* it there.
+* A tool's annotations: read-only exactly when its action is, and the contract's `mcp` ones
+* where given, so the native defaults, MCP's, stand for the others. A read-only tool is not
+* destructive unless it says so, where the native default calls every tool destructive.
 */
-const TextField = Context.Reference("@gjermundgaraba/effect-actions/TextField", { defaultValue: () => void 0 });
-const isToolAction = (action) => action.mcp !== false;
-/** Only tool-enabled groups are acquired; each implementation appears once. */
-const toolApps = (apps) => apps.flatMap((app) => {
-	const actions = app.group.actions.filter(isToolAction);
-	return actions.length === 0 ? [] : [{
-		app,
-		actions
-	}];
-});
-/** Flatten the projected contracts only after deciding which groups are served. */
-const entries = (apps) => apps.flatMap(({ app, actions }) => actions.map((action) => ({
-	app,
-	action
-})));
-const annotate = (tool, mcp) => tool.annotate(Tool.Readonly, mcp.readOnly).annotate(Tool.Destructive, mcp.destructive).annotate(Tool.Idempotent, mcp.idempotent).annotate(Tool.OpenWorld, mcp.openWorld);
-/**
-* A native Effect AI tool. Its schemas retain action transforms and its result
-* is the action result itself, rather than an MCP response envelope.
-*/
-const nativeTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
-	description: action.description,
-	parameters: action.input,
-	success: action.success,
-	failure: Schema.Union(errors),
-	failureMode: "return"
-}), action.mcp);
+const annotate = (tool, { readOnly, mcp }) => {
+	const destructive = mcp.destructiveHint ?? (readOnly ? false : void 0);
+	const meta = mcp._meta === void 0 ? void 0 : { ...mcp._meta };
+	const hinted = annotateIf(annotateIf(annotateIf(tool.annotate(Tool.Readonly, readOnly), Tool.Destructive, destructive), Tool.Idempotent, mcp.idempotentHint), Tool.OpenWorld, mcp.openWorldHint);
+	return annotateIf(annotateIf(hinted, Tool.Title, mcp.title), Tool.Meta, meta);
+};
 /**
-* MCP has a JSON-only wire contract. Success is the encoded success as structured
-* content; declared failures are returned as JSON text.
+* The native tool of `action`. A model and an MCP client speak JSON, so it takes and gives
+* the JSON encoding its schemas advertise, the whole success; handlers and callers see decoded
+* values. A refusal by authentication or `authorize`, or a handler's built-in failure, is the implementation's failure, so
+* it declares the built-in errors alongside the action's own, and returns them as its result.
 */
-const mcpTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
+const toolOf = (action) => Tool.make(action.name, {
 	description: action.description,
 	parameters: Schema.toCodecJson(action.input),
 	success: Schema.toCodecJson(action.success),
-	failure: Schema.toCodecJson(Schema.Union(errors)),
+	failure: Schema.toCodecJson(Schema.Union(projectedErrors(action))),
 	failureMode: "return"
-}), action.mcp).annotate(TextField, action.mcp.text);
-const project = (projection, entry, options) => {
-	const errors = projectedErrors(entry.action, options.errors);
-	const tool = projection === "native" ? nativeTool(entry.action, errors) : mcpTool(entry.action, errors);
-	if (projection === "native") return tool;
-	return tool.annotate(Tool.Strict, true);
-};
+});
 /**
-* Project MCP-enabled actions and acquire their handlers exactly once per adapter layer.
-* Native and MCP differ only in tool codecs; selection, scoped acquisition, dispatch
-* and native Toolkit binding stay identical.
+* Project actions as tools named after them, sharing each implementation's built handlers.
 */
-const bindTools = (apps, projection, options) => {
-	const served = toolApps(apps);
-	const selected = entries(served);
-	assertDistinct("MCP tool", selected.map(({ action }) => action.mcp.name));
-	const toolkit = Toolkit.make(...selected.map((entry) => project(projection, entry, options)));
+const bindTools = (apps, projection) => {
+	assertOnce(projection.label, apps.flatMap((app) => app.actions));
+	const toolkit = Toolkit.make(...apps.flatMap((app) => app.actions.map((action) => annotate(projection.tool(toolOf(action), action, app), action))));
 	return {
 		toolkit,
-		layer: toolkit.toLayer(Effect.map(Effect.forEach(served, ({ app, actions }) => Effect.map(app.build, (handlers) => {
-			const record = handlers;
-			return actions.map((action) => [action.mcp.name, dispatch(app.group, action, record, options.before)]);
-		})), (built) => Object.fromEntries(built.flat())))
+		layer: toolkit.toLayer(Effect.map(acquire(apps), (bound) => Object.fromEntries(bound.map(([action, run]) => [action.name, projection.handler?.(run, action) ?? run]))))
 	};
 };
 //#endregion
-export { TextField, bindTools };
+export { bindTools };