@gjermundgaraba/effect-actions 0.9.0 → 0.10.0

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 as a defect,
+* the empty 500 of any other server bug.
+*/
+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) => responseKinds.has(failure.kind) ? Effect.die(failure.cause) : Effect.fail(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 };