@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

package/dist/ActionToolkit.d.mts

@@ -1,20 +1,15 @@
-import { BuiltIns } from "./internal/errors.mjs";
-import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, Served, Serving } from "./internal/implementation.mjs";
+import { BuiltIns } from "./contract/errors.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, Served, Serving } from "./contract/implementation.mjs";
 import { Action_d_exports, Any } from "./Action.mjs";
 import { Effect, Layer, Schema } from "effect";
 import { Tool, Toolkit } from "effect/ai";
-//#region src/ActionToolkit.d.ts
-/** A native tool named after its action, taking and giving JSON. */
+//#region src/toolkit/ActionToolkit.d.ts
 type NativeTool<A extends Any, R> = Tool.Tool<A["name"], {
   readonly parameters: Schema.toCodecJson<A["input"]>;
   readonly success: Schema.toCodecJson<A["success"]>;
   readonly failure: Schema.toCodecJson<Schema.Union<ReadonlyArray<A["error"][number] | BuiltIns>>>;
   readonly failureMode: "return";
 }, R>;
-/**
- * The tool of each action of `App` among `Listed`. A tool needs what its handler and its
- * implementation's authorization need.
- */
 type ToolFor<App, Listed extends Any> = App extends unknown ? Serving<App, Listed> extends (infer A extends Any) ? A extends Any ? NativeTool<A, RequestOf<App, A>> : never : never : never;
 /**
  * Native tools bound to their action implementations: a native `Toolkit` and the layer of
@@ -64,6 +59,8 @@ export interface Options<A extends Any> {
  * when the resulting toolkit handles a call, the identity an implementation's `authorize`
  * reads included: the caller provides it. `needsApproval` marks the calls a model must have
  * approved; it authorizes nothing, which stays `authorize`'s.
+ * Guide: `docs/ActionToolkit.md` in this package; a loop served behind a route, with approval:
+ * `examples/kitchen-sink/src/assistant/`.
  */
 export declare function make<const Apps extends Served, const O extends Options<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, Options<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<Any>>>>): Tools<{ readonly [T in ToolFor<Member<Apps>, Offered<O, ActionOf<Member<Apps>>>> as T["name"]]: T; }, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>;
 //#endregion

package/dist/ActionToolkit.mjs

@@ -1,6 +1,6 @@
-import { Implementation, provideHandlers, select, toList } from "./internal/implementation.mjs";
-import { bindTools } from "./internal/tools.mjs";
-//#region src/ActionToolkit.ts
+import { Implementation, provideHandlers, select, toList } from "./contract/implementation.mjs";
+import { bindTools } from "./toolkit/tools.mjs";
+//#region src/toolkit/ActionToolkit.ts
 function make(apps, options) {
 	const served = select(toList(apps), options?.actions);
 	const needsApproval = options?.needsApproval;

package/dist/Authentication.d.mts

@@ -1,12 +1,12 @@
-import { Refusal } from "./internal/errors.mjs";
-import { Known, OptionalUnless } from "./internal/implementation.mjs";
+import { ErrorsOf } from "./contract/rules.mjs";
+import { Refusal } from "./contract/errors.mjs";
+import { Known, OptionalUnless } from "./contract/implementation.mjs";
 import { Errors } from "./Action.mjs";
-import { Any, Descriptor, Provider, Security } from "./internal/authentication.mjs";
-import { ErrorsOf } from "./internal/declared.mjs";
+import { Any, Descriptor, Provider, Security } from "./authentication/provider.mjs";
 import { Array, Context, Effect, Layer, Option, Redacted, Scope } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { HttpApiSecurity } from "effect/http-api";
-//#region src/Authentication.d.ts
+//#region src/authentication/Authentication.d.ts
 /**
  * The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
  * `HttpApiSecurity.bearer` reads it for routes and MCP, which a test holds equal. It is for a
@@ -17,7 +17,10 @@ import { HttpApiSecurity } from "effect/http-api";
 export declare const bearerTokenOf: (authorization: string | null | undefined) => Option.Option<Redacted.Redacted<string>>;
 /** An OAuth protected resource (RFC 9728), as `layer` publishes it. */
 export interface ProtectedResource {
-  /** Exact OAuth resource identifier; its path and query select the discovery path. */
+  /**
+   * Exact OAuth resource identifier; its path and query select the discovery path. It has no
+   * fragment, which no request URL carries, so its discovery would never answer (RFC 9728).
+   */
   readonly resource: string;
   /** Where clients get tokens: nonempty. */
   readonly authorizationServers: Array.NonEmptyReadonlyArray<string>;
@@ -50,7 +53,6 @@ export interface RefusalResponseOptions<D extends Any = Any> {
    */
   readonly authorization?: string | null | undefined;
 }
-/** What the descriptor `D` declares its verifier fails with besides a refusal. */
 type DeclaredOf<D> = D extends {
   readonly error: infer E extends Errors;
 } ? E[number]["Type"] : never;
@@ -76,7 +78,6 @@ export interface Options {
    */
   readonly error?: Errors | Errors[number];
 }
-/** The scheme options `O` give: Bearer too wherever they may leave it out, as at run time. */
 type SecurityOf<O> = O extends {
   readonly security: infer S extends Security;
 } ? S : "security" extends keyof O ? NonNullable<O["security" & keyof O]> | HttpApiSecurity.Http : HttpApiSecurity.Http;
@@ -86,6 +87,7 @@ type SecurityOf<O> = O extends {
  * as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`. The literal name
  * identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key, so it
  * holds only letters, digits, `_`, `.` and `-`; reuse one name only for one declaration.
+ * Guide: `docs/Authentication.md` in this package; in an application: `examples/notes-service/src/identity/`.
  */
 export declare const make: <const Name extends string, I, A, const O extends Options = {}>(name: Name, identity: Context.Key<I, A>, ...options: OptionalUnless<O, O & NoInfer<Known<O, Options>>>) => Descriptor<I, A, SecurityOf<O>, Name, ErrorsOf<O>>;
 /**
@@ -97,21 +99,19 @@ export type Verify<A, S extends Security, R, E = never> = (credential: HttpApiSe
 export interface LayerOptions<EP = never, RP = never> {
   readonly protectedResource?: ProtectedResource | Effect.Effect<ProtectedResource | undefined, EP, RP>;
 }
-/**
- * Only a Bearer scheme publishes an OAuth protected resource. The types tell only an `Http`
- * scheme from the others, as its scheme is a `string`: `layer` refuses another `Http` one.
- */
 type ResourceOf<S> = [S] extends [HttpApiSecurity.Http] ? unknown : {
   readonly protectedResource?: undefined;
 };
+type Resource = ProtectedResource | Effect.Effect<ProtectedResource | undefined, unknown, unknown> | undefined;
 /**
  * The provider of `authentication`: `verify`, or an Effect building it once per layer graph, run on
  * each remote request a protected action receives, with the credential the descriptor's
  * scheme decodes. A Bearer scheme answers each 401 with its challenge, and may publish the
- * OAuth protected resource `protectedResource`.
+ * OAuth protected resource `protectedResource`, on the `HttpRouter` it then requires.
  */
-export declare function layer<const Name extends string, I, A, const S extends Security, E extends Errors, R, EX = never, RX = never, EP = never, RP = never>(authentication: Descriptor<I, A, S, Name, E>, verify: Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>> | Effect.Effect<Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>>, EX, RX>, options?: LayerOptions<EP, RP> & ResourceOf<S>): Layer.Layer<Provider<I, Name>, EX | EP, HttpRouter.HttpRouter | Exclude<RX | RP, Scope.Scope> | HttpRouter.Request.From<"Requires", Exclude<R, HttpRouter.Provided>>>;
-/** The identity `I`, or none where it is erased to `unknown`. */
+export declare function layer<const Name extends string, I, A, const S extends Security, E extends Errors, R, EX = never, RX = never, P extends Resource = undefined>(authentication: Descriptor<I, A, S, Name, E>, verify: Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>> | Effect.Effect<Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>>, EX, RX>, options?: {
+  readonly protectedResource?: P;
+} & ResourceOf<S>): Layer.Layer<Provider<I, Name>, EX | Effect.Error<P>, ([P] extends [undefined] ? never : HttpRouter.HttpRouter) | Exclude<RX | Effect.Services<P>, Scope.Scope> | HttpRouter.Request.From<"Requires", Exclude<R, HttpRouter.Provided>>>;
 type Provides<I> = unknown extends I ? never : I;
 /**
  * What `protect` returns for a descriptor named `Name` authenticating the identity `I`: router

package/dist/Authentication.mjs

@@ -1,18 +1,13 @@
-import { Unauthenticated, scopeToken } from "./internal/errors.mjs";
-import { assertOwnTags, errorList } from "./internal/actions.mjs";
-import { declaredResponse } from "./internal/declared.mjs";
-import { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain } from "./internal/refusal.mjs";
+import { Unauthenticated, scopeToken } from "./contract/errors.mjs";
+import { assertOwnTags, errorList } from "./contract/rules.mjs";
+import { providerOf } from "./authentication/provider.mjs";
+import { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain } from "./authentication/refusal.mjs";
+import { declaredResponse } from "./http/declared.mjs";
 import { Context, Effect, Layer, Match, Option, Predicate, Redacted } from "effect";
 import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 import { HttpApiBuilder, HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
-//#region src/Authentication.ts
-/**
-* An `Authorization` header of the `Bearer` scheme, and its token, as Effect's own
-* `HttpApiSecurity.bearer` decodes a request's: the scheme, matched case-insensitively, one or
-* more spaces, then the rest of the header, whatever it holds, a tab included. The whitespace
-* around a header value is no part of it, and an HTTP parser strips it before any route reads it.
-*/
-const bearerScheme = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
+//#region src/authentication/Authentication.ts
+const bearerAuthorizationHeader = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 /**
 * The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
 * `HttpApiSecurity.bearer` reads it for routes and MCP, which a test holds equal. It is for a
@@ -20,44 +15,24 @@ const bearerScheme = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 * own is authenticated by `protect`. The scheme is matched case-insensitively, as RFC 9110
 * requires, and the token is `Redacted`, as Effect's own decoder gives it.
 */
-const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerScheme.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
-/**
-* The RFC 9728 metadata URL of `options`: `/.well-known/oauth-protected-resource` followed
-* by the resource's path, where MCP clients look when a 401 names no metadata URL.
-*/
-const metadataUrl = (options) => {
+const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerAuthorizationHeader.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
+const metadataUrlOf = (options) => {
 	const resource = new URL(options.resource);
 	const url = new URL(resource);
 	url.pathname = `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}`;
 	return url;
 };
-/** What challenges about `options` name. */
 const namedOf = (options) => ({
 	scope: options?.scopesRequired?.join(" "),
-	metadataUrl: options === void 0 ? void 0 : metadataUrl(options).href
+	metadataUrl: options === void 0 ? void 0 : metadataUrlOf(options).href
 });
-/** Whether a request whose `Authorization` header is `authorization` presented a bearer token. */
-const tokenPresented = (authorization) => Option.isSome(bearerTokenOf(authorization));
-/**
-* The challenge of a 401: `Bearer`, naming the scopes a client requests and the metadata URL
-* where it finds its authorization server. A request that presented a bearer token is told
-* it is invalid, RFC 6750's `invalid_token`, on which a client may refresh its token before
-* it signs in again; one that presented none names no error code.
-*/
-const challengeOf = (named, presented) => bearer([
+const presentsBearerToken = (authorization) => Option.isSome(bearerTokenOf(authorization));
+const bearerChallengeOf = (named, presented) => bearer([
 	["error", presented ? "invalid_token" : void 0],
 	["scope", named.scope],
 	["resource_metadata", named.metadataUrl]
 ]);
-/**
-* Refuse a protected resource that cannot be published, as `layer` and `refusalResponse` both
-* do: one under a scheme other than Bearer (`oauth` false), a `scopesSupported` or
-* `scopesRequired` that is no list of OAuth scope tokens, as `Forbidden` refuses, and a
-* resource with a fragment, which no request URL carries, so its discovery would never answer
-* (RFC 9728). A resource an Effect builds is checked for its scheme alone, and for the rest
-* once built.
-*/
-const assertResource = (oauth, options) => {
+const assertPublishableResource = (oauth, options) => {
 	if (options === void 0) return;
 	if (!oauth) throw new Error("A protected resource is published only for a Bearer scheme");
 	if (Effect.isEffect(options)) return;
@@ -67,11 +42,7 @@ const assertResource = (oauth, options) => {
 	}
 	if (new URL(options.resource).href.includes("#")) throw new Error(`A protected resource has no fragment: ${options.resource}`);
 };
-/**
-* `response` as the routes of the authentication answer: `no-store` unless it states its
-* own caching, and a 401 challenged with `challenge` unless it names its own.
-*/
-const settle = (response, challenge) => HttpServerResponse.setHeaders(response, {
+const withNoStoreAndChallenge = (response, challenge) => HttpServerResponse.setHeaders(response, {
 	...response.headers["cache-control"] === void 0 ? { "cache-control": "no-store" } : {},
 	...challenge !== void 0 && response.status === 401 && response.headers["www-authenticate"] === void 0 ? { "www-authenticate": challenge } : {}
 });
@@ -89,32 +60,19 @@ const settle = (response, challenge) => HttpServerResponse.setHeaders(response,
 const refusalResponse = (error, options) => {
 	const authentication = options?.authentication;
 	const oauth = authentication === void 0 || isBearer(authentication.security);
-	assertResource(oauth, options?.protectedResource);
+	assertPublishableResource(oauth, options?.protectedResource);
 	const named = namedOf(options?.protectedResource);
-	const challenge = authentication !== void 0 && !oauth ? schemeChallenge(authentication.security, authentication.name) : challengeOf(named, tokenPresented(options?.authorization));
+	const challenge = authentication !== void 0 && !oauth ? nonBearerChallengeOf(authentication.security, authentication.name) : bearerChallengeOf(named, presentsBearerToken(options?.authorization));
 	if (!isRefusal(error)) {
 		const response = declaredResponse(authentication?.error ?? [], error);
 		if (response === void 0) throw new Error("Not a refusal, nor an error the authentication declares");
-		return settle(response, challenge);
+		return withNoStoreAndChallenge(response, challenge);
 	}
-	return settle(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
+	return withNoStoreAndChallenge(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
 };
-/**
-* Whether a request URL may resolve to a discovery path, which every other request skips
-* parsing: the URL parser copies `.well-known` as it is, removing only a tab or a newline. Node
-* refuses a target holding those before routing; a platform passing one through still parses.
-*/
-const mayDiscover = /\.well-known|[\t\n\r]/;
-/**
-* RFC 9728 discovery of `options` at its metadata URL, as global router middleware: it
-* answers before routing, so no route middleware, authentication included, ever covers it.
-* The metadata is public to every origin, as a browser client needs it after a 401: it
-* carries `Access-Control-Allow-Origin: *`, and discovery answers its own CORS preflight.
-* Where the host's CORS middleware runs before it, that policy answers the preflight and
-* adds its headers to reads, which keep the `*` where it sets no origin.
-*/
-const discovery = (options) => {
-	const discoveryUrl = metadataUrl(options);
+const mayResolveToDiscoveryPath = /\.well-known|[\t\n\r]/;
+const discoveryMiddleware = (options) => {
+	const discoveryUrl = metadataUrlOf(options);
 	const target = discoveryUrl.href.slice(discoveryUrl.origin.length);
 	const metadata = HttpServerResponse.jsonUnsafe({
 		resource: options.resource,
@@ -123,8 +81,7 @@ const discovery = (options) => {
 		scopes_supported: options.scopesSupported,
 		resource_name: options.resourceName
 	}, { headers: { "access-control-allow-origin": "*" } });
-	/** The preflight of a cross-origin read, allowing the headers it asks for. */
-	const preflight = (request) => {
+	const corsPreflight = (request) => {
 		const requested = request.headers["access-control-request-headers"];
 		return HttpServerResponse.empty({
 			status: 204,
@@ -139,46 +96,36 @@ const discovery = (options) => {
 		});
 	};
 	return (next) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => {
-		const targeted = mayDiscover.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
+		const targeted = mayResolveToDiscoveryPath.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
 		if (targeted && (request.method === "GET" || request.method === "HEAD")) return Effect.succeed(metadata);
-		if (targeted && request.method === "OPTIONS") return Effect.succeed(preflight(request));
+		if (targeted && request.method === "OPTIONS") return Effect.succeed(corsPreflight(request));
 		return next;
 	});
 };
-/**
-* What `layer` answers about the protected resource `options`, written once: its metadata
-* URL, each 401's challenge, to a request that presented a bearer token and to one that did
-* not, and its discovery, none without a resource.
-*/
-const answersOf = (options) => {
+const resourceAnswersOf = (options) => {
 	const named = namedOf(options);
 	return {
 		metadataUrl: named.metadataUrl,
-		invalid: challengeOf(named, true),
-		anonymous: challengeOf(named, false),
-		published: options === void 0 ? void 0 : discovery(options)
+		invalid: bearerChallengeOf(named, true),
+		anonymous: bearerChallengeOf(named, false),
+		published: options === void 0 ? void 0 : discoveryMiddleware(options)
 	};
 };
-/** Whether `security` is the Bearer scheme, the one OAuth challenges and discovery name. */
 const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
-/** What an OpenAPI component key may hold, and so a descriptor's name, which is its key. */
-const componentKey = /^[\w.-]+$/;
-/**
-* The challenge of a 401 under a scheme other than Bearer: the scheme an `Http` one names,
-* Basic with its realm, the descriptor's name; an API key has no scheme to name.
-*/
-const schemeChallenge = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", () => void 0), Match.exhaustive);
+const openApiComponentKey = /^[\w.-]+$/;
+const nonBearerChallengeOf = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", () => void 0), Match.exhaustive);
 /**
 * Browser-safe declaration shared by clients and remote surfaces: the `identity` it
 * authenticates, by the one native scheme `security`, Bearer unless it names another, such
 * as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`. The literal name
 * identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key, so it
 * holds only letters, digits, `_`, `.` and `-`; reuse one name only for one declaration.
+* Guide: `docs/Authentication.md` in this package; in an application: `examples/notes-service/src/identity/`.
 */
 const make = (name, identity, ...options) => {
 	const security = options[0]?.security ?? HttpApiSecurity.bearer;
 	const error = errorList(options[0]?.error);
-	if (!componentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key`);
+	if (!openApiComponentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key`);
 	assertOwnTags(`Authentication "${name}"`, error);
 	if (!Predicate.isTagged(security, "Http") && !Predicate.isTagged(security, "ApiKey") && !Predicate.isTagged(security, "Basic")) throw new Error("Authentication takes one native HttpApiSecurity scheme");
 	return {
@@ -191,27 +138,25 @@ const make = (name, identity, ...options) => {
 		"~verified": Context.Service(`effect-actions/Authentication/Verified/${name}`)
 	};
 };
-/** Whether `credential`, as a native scheme decodes it, holds anything: an absent one is empty. */
 const presented = (credential) => Redacted.isRedacted(credential) ? Redacted.value(credential) !== "" : credential.username !== "" || Redacted.value(credential.password) !== "";
 function layer(authentication, verify, options = {}) {
 	const { security } = authentication;
 	const oauth = isBearer(security);
 	const protectedResource = options.protectedResource;
-	assertResource(oauth, protectedResource);
+	assertPublishableResource(oauth, protectedResource);
 	const resource = Effect.isEffect(protectedResource) ? Effect.map(protectedResource, (built) => {
-		assertResource(oauth, built);
-		return answersOf(built);
-	}) : Effect.succeed(answersOf(protectedResource));
+		assertPublishableResource(oauth, built);
+		return resourceAnswersOf(built);
+	}) : Effect.succeed(resourceAnswersOf(protectedResource));
 	const missing = new Unauthenticated({ message: oauth ? "A bearer token is required." : "A credential is required." });
 	return Layer.effect(authentication["~provider"], Effect.gen(function* () {
-		const router = yield* HttpRouter.HttpRouter;
 		const { metadataUrl, invalid, anonymous, published } = yield* resource;
-		if (published !== void 0) yield* router.addGlobalMiddleware(published);
+		if (published !== void 0) yield* (yield* HttpRouter.HttpRouter).addGlobalMiddleware(published);
 		const verifier = Effect.isEffect(verify) ? yield* verify : verify;
 		if (!Predicate.isFunction(verifier)) return yield* Effect.die(/* @__PURE__ */ new Error("Missing verify: pass a verify function, or an Effect building one"));
 		const authenticate = (credential) => presented(credential) ? verifier(credential) : Effect.fail(missing);
-		const failed = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
-		const challengeOf = (credential) => !oauth ? schemeChallenge(security, authentication.name) : presented(credential) ? invalid : anonymous;
+		const noStoreOnFailure = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
+		const challengeOf = (credential) => !oauth ? nonBearerChallengeOf(security, authentication.name) : presented(credential) ? invalid : anonymous;
 		const refuse = (error) => isRefusal(error) ? Effect.succeed(oauth ? answer(error, metadataUrl) : plain(error)) : Effect.suspend(() => {
 			const response = declaredResponse(authentication.error, error);
 			return response === void 0 ? Effect.die(error) : Effect.succeed(response);
@@ -221,10 +166,11 @@ function layer(authentication, verify, options = {}) {
 			return Effect.matchEffect(authenticate(credential), {
 				onFailure: refuse,
 				onSuccess: (actor) => Effect.provideService(route, slot, actor)
-			}).pipe(Effect.onError(() => failed), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(settle(response, challenge))));
+			}).pipe(Effect.onError(() => noStoreOnFailure), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(withNoStoreAndChallenge(response, challenge))));
 		};
 		return {
 			descriptor: authentication,
+			authenticate,
 			middleware: { [authentication.name]: (route, { credential }) => verified(credential, route, authentication.identity) },
 			stepUp: (route) => oauth ? Effect.catchIf(route, isStepUp, (error) => Effect.succeed(answer(error, metadataUrl))) : route,
 			http: ((route, optional) => Effect.flatMap(HttpApiBuilder.securityDecode(security), (credential) => optional && !presented(credential) ? route : verified(credential, oauth ? answerStepUp(route, metadataUrl) : route, authentication["~verified"]))),
@@ -243,6 +189,6 @@ function layer(authentication, verify, options = {}) {
 * `layer(authentication, ...)`. An erased descriptor, `Any`, provides no service the types can
 * name: its identity is `unknown`, which would discharge every request service the route owes.
 */
-const protect = (authentication) => HttpRouter.middleware()(Effect.map(Effect.service(authentication["~provider"]), (runtime) => (route) => runtime.route(route)));
+const protect = (authentication) => HttpRouter.middleware()(Effect.map(providerOf(authentication), (runtime) => (route) => runtime.route(route)));
 //#endregion
 export { bearerTokenOf, layer, make, protect, refusalResponse };

package/dist/Testing.d.mts

@@ -1,14 +1,15 @@
-import { BuiltIn } from "./internal/errors.mjs";
-import { Call } from "./internal/call.mjs";
+import { BuiltIn } from "./contract/errors.mjs";
+import { Call } from "./contract/call.mjs";
 import { Action_d_exports, Any } from "./Action.mjs";
-import { Params } from "./internal/mcp.mjs";
-import { Served } from "./internal/memory.mjs";
-import { Effect, Layer, Schema } from "effect";
+import { Params } from "./mcp/protocol.mjs";
+import { Served } from "./testing/memory.mjs";
+import { Cause, Effect, Layer, Schema } from "effect";
 import { Headers, HttpClient, HttpClientError, HttpClientRequest, HttpRouter } from "effect/http";
-//#region src/Testing.d.ts
+//#region src/testing/Testing.d.ts
 /**
- * The native `HttpClient`, answered by `handler` instead of the network: a web handler the
- * test serves, which other tests may share, such as
+ * For a web handler the test already owns; most tests want `layer(routes)`, below, with
+ * `ActionHttp.client` and `mcpClient`. The native `HttpClient`, answered by `handler` instead of
+ * the network: a web handler the test serves, which other tests may share, such as
  * `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler`,
  * the routes' platform services provided, as `layer(routes)` provides them itself. It is the
  * client `layer(routes)` gives, without building anything: the test owns the handler, and
@@ -18,7 +19,9 @@ export declare function layer(handler: (request: Request) => Promise<Response>):
 /**
  * The native `HttpClient`, answered in memory by `routes` instead of the network: provide
  * it to `ActionHttp.client` and to `mcpClient`. The routes are built with this layer and
- * released with its scope, without request logs. What they still require is this layer's, as
+ * released with its scope, without request logs: only the cause of a defect, of a result that
+ * does not encode or of a failure a route of your own leaves unhandled is logged, as an error,
+ * where a server's request logger would show it. What they still require is this layer's, as
  * under `HttpRouter.serve`: a builder's services, and a per-request service no middleware of
  * theirs provides, including one a global middleware reads. The routes keep their real
  * authentication: a client sends its caller's credential. Provided around it, the test
@@ -28,6 +31,7 @@ export declare function layer(handler: (request: Request) => Promise<Response>):
  * the rest, whose `FileSystem` is a no-op. A relative URL resolves against `http://localhost`.
  * The client is the layer's own: the program's other HTTP clients get none of its requests,
  * and it none of theirs.
+ * Guide: `docs/Testing.md` in this package; in an application: `examples/notes-service/test/`.
  */
 export declare function layer<A, E, R>(routes: Layer.Layer<A, E, R>): Layer.Layer<HttpClient.HttpClient, E, Exclude<HttpRouter.Request.Without<R> | HttpRouter.Request.Only<"Requires", R> | HttpRouter.Request.Only<"GlobalRequires", R>, Served>>;
 /** Where `mcpClient` sends, and through what client. */
@@ -37,7 +41,10 @@ export interface McpClientOptions {
    * the default `ActionMcp.layerHttp` path.
    */
   readonly url?: string;
-  /** Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token, say. */
+  /**
+   * Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token is
+   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.
+   */
   readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
 }
 /** Where an `mcpRequest` goes, and with what headers. */
@@ -52,34 +59,34 @@ export interface McpRequestOptions {
 }
 declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
   readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
+}>, Cause.YieldableError>;
 /**
- * An answer a client method cannot decode as the action's success or a declared error,
- * such as the native server's message for invalid arguments or an unknown tool. Its message
- * holds the answer.
+ * An answer a client method cannot read as the action's success or a declared error, such as
+ * the native server's message for invalid arguments or an unknown tool, or a result without
+ * its structured content. Its message holds the answer. Structured content that does not
+ * decode as the success is a `SchemaError` instead, and a request that fails an
+ * `HttpClientError`.
  */
 export declare class McpCallError extends McpCallError_base {}
-/**
- * What one call of `A` fails with: a declared error value (the action's own or a built-in one
- * from the tool, or a refusal from the endpoint's authentication), a `SchemaError` when the
- * input does not encode or the success does not decode, an `HttpClientError` when the
- * endpoint could not be reached, or an `McpCallError` for any other answer.
- */
 type CallError<A extends Any> = A["error"][number]["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
 /** Every action of `Actions` as `client.<action>(input)`, calling its tool. */
 export type McpClient<Actions extends ReadonlyArray<Any>> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A>>>; };
 /**
  * A client of an MCP endpoint served by `ActionMcp.layerHttp`, one method per action calling
  * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
- * encoded with the action's schema, and the success decoded from its structured content. A
- * declared error the tool returns, the action's own or a refusal, is its decoded value, and so
- * is a refusal the endpoint's authentication answers with. The argument may be omitted when
- * `{}` is a valid input. Requires the native `HttpClient`, such as the one `layer` provides.
+ * encoded with the action's schema, and the success decoded from its structured content, each
+ * media field from the blocks whose `_meta` names it, and a success that is media, or whose
+ * every field is, from its blocks alone. A declared error the tool returns, the action's own
+ * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication
+ * answers with: a test telling a 401 or 403 from a tool result asserts the status of a request
+ * `mcpRequest` builds. The argument may be omitted when `{}` is a valid input. Requires the
+ * native `HttpClient`, such as the one `layer` provides.
  */
 export declare function mcpClient<const Actions extends ReadonlyArray<Any>>(actions: Actions, options?: McpClientOptions): Effect.Effect<McpClient<Actions>, never, HttpClient.HttpClient>;
 /**
  * One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
- * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+ * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
+ * `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
  * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
  * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
  * version is always the request's own. The test sends it: `HttpClient.execute` answers the

package/dist/Testing.mjs

@@ -1,13 +1,13 @@
-import { Refusal } from "./internal/errors.mjs";
-import { assertOnce, projectedErrors } from "./internal/actions.mjs";
-import { inputOf } from "./internal/call.mjs";
-import { defaultPath, statelessRequest } from "./internal/mcp.mjs";
-import { clientOf } from "./internal/memory.mjs";
-import { Context, Effect, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
-import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
+import { Refusal } from "./contract/errors.mjs";
+import { assertOnce, projectedErrors } from "./contract/rules.mjs";
+import { checked } from "./contract/call.mjs";
+import { defaultPath, liftOf, statelessRequest } from "./mcp/protocol.mjs";
+import { clientOf } from "./testing/memory.mjs";
+import { Cause, Context, Effect, ErrorReporter, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
 import { McpSchema } from "effect/ai";
-import { Sse } from "effect/encoding";
-//#region src/Testing.ts
+import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
+import { Base64, Sse } from "effect/encoding";
+//#region src/testing/Testing.ts
 function layer(routes) {
 	if (!Layer.isLayer(routes)) return clientOf(routes);
 	return Layer.unwrap(Effect.gen(function* () {
@@ -15,27 +15,24 @@ function layer(routes) {
 		const platform = yield* Layer.build(Layer.fresh(Layer.mergeAll(HttpPlatform.layer, Path.layer, Etag.layerWeak).pipe(Layer.provideMerge(Layer.succeed(FileSystem.FileSystem, fileSystem)))));
 		const context = Context.merge(platform, yield* Effect.context());
 		const app = yield* HttpRouter.toHttpEffect(routes).pipe(Effect.provideContext(context));
-		return clientOf(HttpEffect.toWebHandlerWith(context)(app));
+		return clientOf(HttpEffect.toWebHandlerWith(context)(Effect.tapCause(app, (cause) => isReported(cause) ? Effect.logError(cause) : Effect.void)));
 	}));
 }
+const isReported = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && !ErrorReporter.isIgnored(reason.error) || Cause.isDieReason(reason) && !ErrorReporter.isIgnored(reason.defect));
 /**
-* An answer a client method cannot decode as the action's success or a declared error,
-* such as the native server's message for invalid arguments or an unknown tool. Its message
-* holds the answer.
+* An answer a client method cannot read as the action's success or a declared error, such as
+* the native server's message for invalid arguments or an unknown tool, or a result without
+* its structured content. Its message holds the answer. Structured content that does not
+* decode as the success is a `SchemaError` instead, and a request that fails an
+* `HttpClientError`.
 */
 var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
-/** The text of a block, none of a block of another kind. */
 const textOf = (block) => block?.type === "text" ? block.text : void 0;
-/** The JSON-RPC response to a `tools/call`: the native tool result, or a protocol error. */
-const ToolReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
+const ToolCallReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
 	code: Schema.Finite,
 	message: Schema.String
 }) })]);
-const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolReply));
-/**
-* The reply in a response: its body when it is one JSON message, or the last reply among an
-* event stream's events, which notifications may precede.
-*/
+const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolCallReply));
 const replyOf = (response, text) => {
 	if (!(response.headers["content-type"] ?? "").startsWith("text/event-stream")) return decodeReply(text);
 	const data = [];
@@ -44,10 +41,26 @@ const replyOf = (response, text) => {
 	}).feed(text);
 	return Option.fromNullishOr(data.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
 };
-/** Fail with the value of one of `errors` that `text` holds, or else with `otherwise`. */
+const mediaFromBlocks = ({ name, kind, many }, result) => {
+	const values = result.content.flatMap((block) => block.type === kind && block._meta?.["effect-actions/field"] === name ? [{
+		data: Base64.encode(block.data),
+		mimeType: block.mimeType
+	}] : []);
+	return many || values.length > 1 ? values : values[0];
+};
+const encodedSuccessOf = (lift, result) => {
+	const [whole] = lift.fields;
+	if (whole !== void 0 && whole.name === void 0) return mediaFromBlocks(whole, result);
+	const { structuredContent = {} } = result;
+	if (!Predicate.isObject(structuredContent)) return structuredContent;
+	const lifted = new Set(lift.fields.map(({ name }) => name));
+	return Object.fromEntries([...Object.entries(structuredContent).filter(([key]) => !lifted.has(key)), ...lift.fields.flatMap((field) => {
+		const value = mediaFromBlocks(field, result);
+		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
+	})]);
+};
 const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
-/** The tool call of `action` with `input` on `client`, sending to `url`. */
-const callTool = (client, url, action, input) => {
+const callTool = (client, url, action, lift, input) => {
 	const { name } = action;
 	const other = (answer) => new McpCallError({ message: `MCP tools/call "${name}" ${answer}` });
 	return Effect.gen(function* () {
@@ -69,8 +82,8 @@ const callTool = (client, url, action, input) => {
 			const error = textOf(result.content.find((block) => block.type === "text")) ?? "";
 			return yield* failWith(projectedErrors(action), error, other(`returned an error: ${error}`));
 		}
-		if (result.structuredContent === void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
-		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(result.structuredContent);
+		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
+		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(encodedSuccessOf(lift, result));
 	});
 };
 function mcpClient(actions, { url = defaultPath, transformClient = identity } = {}) {
@@ -78,13 +91,15 @@ function mcpClient(actions, { url = defaultPath, transformClient = identity } =
 	return Effect.map(HttpClient.HttpClient, (native) => {
 		const client = transformClient(native);
 		return Object.fromEntries(actions.map((action) => {
-			return [action.name, (...args) => Effect.flatMap(inputOf(action, args), (input) => callTool(client, url, action, input))];
+			const lift = liftOf(action.success);
+			return [action.name, checked(action, (input) => callTool(client, url, action, lift, input))];
 		}));
 	});
 }
 /**
 * One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
-* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
+* `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
 * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
 * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
 * version is always the request's own. The test sends it: `HttpClient.execute` answers the
@@ -94,8 +109,8 @@ function mcpClient(actions, { url = defaultPath, transformClient = identity } =
 * a call its types would not send.
 */
 const mcpRequest = (method, params = {}, { headers = {}, url = defaultPath } = {}) => {
-	const { headers: routing, body } = statelessRequest(method, params);
-	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routing), HttpClientRequest.bodyJsonUnsafe(body));
+	const { headers: routingHeaders, body } = statelessRequest(method, params);
+	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routingHeaders), HttpClientRequest.bodyJsonUnsafe(body));
 };
 //#endregion
 export { McpCallError, layer, mcpClient, mcpRequest };