@procedures/client 0.35.0 → 0.35.1

package/src/server/error-policy.ts

@@ -0,0 +1,263 @@
+/**
+ * The error policy of a server (roadmap CLI-80): what an error tells the caller when it leaves
+ * the process.
+ *
+ * `Server.handle()` applies the policy to each response, so each face of the server (HTTP,
+ * WebSocket, MCP, a message port, the local face of a host) sends the same error. When
+ * `handle()` throws, or a face fails after it (for example, a value that JSON cannot encode), the
+ * last-resort catch of the face applies the same policy through `lastResortError`. A nested call
+ * of `ctx.client` does not go through `handle()`, so it keeps the real error.
+ *
+ * - `expose: "all"` (the default): each error goes to the caller as before.
+ * - `expose: "coded"`: an error with a known code (`isKnownErrorCode`, or a code of `codes`) goes
+ *   to the caller as it is. Each other error goes to the caller as `INTERNAL_ERROR` with the
+ *   message `"internal error"`, and the server logs it one time.
+ * - `map` runs first. Its result goes to the caller as it is. `undefined` gives the error to
+ *   `expose`.
+ *
+ * The policy reads the real error of a response through the links of `error-response.ts`: the
+ * status object, and the request object with the code and the message of the status. A copy of
+ * the response or of its status keeps a link.
+ */
+
+import type { ProcedurePath } from "../procedures/types.js";
+import { closableUnread } from "../procedures/invoke.js";
+import { isKnownErrorCode } from "../client/errors/registry.js";
+import { errorCodeOf } from "../protocol.js";
+import { errorResponse, realErrorOf } from "./error-response.js";
+import { methodToPath } from "./method.js";
+import { rawErrorOf } from "./last-resort.js";
+export { lastResortError } from "./last-resort.js";
+import { ServerError, type ServerRequest, type ServerResponse } from "./types.js";
+
+/** The error that the caller gets: its code, its message and its retryable flag. A `ServerError` is one. */
+export interface ExposedError {
+  /** The error code, for example `NOT_FOUND`, or a code of the application. */
+  readonly code: string;
+  /** The message that the caller gets. */
+  readonly message: string;
+  /**
+   * True when a retry of the same call can succeed. Without it, the error gets the flag of its
+   * code before the first item of a stream, and false after it (`retryableOf`).
+   */
+  readonly retryable?: boolean | undefined;
+  /** The wait before a retry, in milliseconds, as on an error of a handler (`Retry-After` on HTTP). */
+  readonly retryAfterMs?: number | undefined;
+}
+
+/** The call of an error that leaves the server. */
+export interface ErrorCall {
+  /** The path of the procedure. Empty when the face failed before it knew the call. */
+  readonly path: ProcedurePath;
+  /** The face that took the request (`http`, `websocket`, `port`, `mcp`), when the face tells it. */
+  readonly transport?: string | undefined;
+}
+
+/** The error policy of a server: the option `errors` (roadmap CLI-80). */
+export interface ServerErrorPolicy {
+  /**
+   * Which errors go to the caller as they are:
+   * - `"all"` (the default): each error, with its code and its message, as before.
+   * - `"coded"`: only an error with a known code (`isKnownErrorCode`: `NOT_FOUND`, `FORBIDDEN`,
+   *   `VALIDATION_ERROR`, `CONFLICT` and so on, or a code of `codes`), with its code, its
+   *   message, its retryable flag and its metadata. Each other error goes to the caller as
+   *   `INTERNAL_ERROR` with the message `"internal error"` and its real retryable flag, with
+   *   only the metadata keys of `keepMetadata`. The codes `INTERNAL_ERROR`, `HANDLER_ERROR`, `UNKNOWN`,
+   *   `OUTPUT_VALIDATION_ERROR` and `NO_OUTPUT` tell of a failure of the server, not of a
+   *   refusal, so their message is hidden too. The server gives the real error to its `onError`
+   *   logger one time, or to `console.error` without a logger.
+   */
+  readonly expose?: "all" | "coded" | undefined;
+  /**
+   * The codes of the application that also go to the caller as they are under `"coded"`, for
+   * example `["QUOTA_EXCEEDED"]`.
+   */
+  readonly codes?: readonly string[] | undefined;
+  /**
+   * The metadata keys that a hidden error response or a `map` result keeps from the response: an
+   * allowlist. Each other key goes, also a key that the server does not know (`issues`, a key of
+   * the application). The default is `DEFAULT_KEPT_METADATA`: the trace keys `traceparent` and
+   * `tracestate`.
+   */
+  readonly keepMetadata?: readonly string[] | undefined;
+  /**
+   * This function runs first, for each error that leaves the server. Its result goes to the
+   * caller as it is, also with a code of the application, and with the metadata of an error of a
+   * handler (`retryAfterMs`, the conflicts of a `VERSION_CONFLICT` error). `undefined` gives the
+   * error to `expose`. A function that throws gives `INTERNAL_ERROR`.
+   */
+  readonly map?: ((error: unknown, call: ErrorCall) => ExposedError | undefined) | undefined;
+}
+
+/** The message of a hidden error. */
+export const HIDDEN_ERROR_MESSAGE = "internal error";
+
+/** The codes that tell of a failure of the server, not of a refusal: `"coded"` hides their message. */
+const FAILURE_CODES: ReadonlySet<string> = new Set(["INTERNAL_ERROR", "HANDLER_ERROR", "UNKNOWN", "OUTPUT_VALIDATION_ERROR", "NO_OUTPUT"]);
+
+/** The errors that a logger got: each path logs an error one time. */
+const LOGGED = new WeakSet<object>();
+
+/**
+ * This function records that the logger of the server got this error, so the error policy does
+ * not log it again.
+ *
+ * @internal
+ */
+export function markLogged(error: unknown): void {
+  if (typeof error === "object" && error !== null) LOGGED.add(error);
+}
+
+/** The logger of the hidden errors: the hook `onError` of the server, or `console.error`. */
+export type HiddenErrorLog = (error: unknown, request: ServerRequest<unknown> | undefined) => void;
+
+/** This function gives an error to the logger, when the logger did not get it before. */
+function logOnce(log: HiddenErrorLog, error: unknown, request: ServerRequest<unknown> | undefined): void {
+  if (typeof error === "object" && error !== null && LOGGED.has(error)) return;
+  markLogged(error);
+  log(error, request);
+}
+
+/** True when the policy can change a response: `"coded"`, or a `map` function. */
+export function policyActs(policy: ServerErrorPolicy | undefined): policy is ServerErrorPolicy {
+  return policy !== undefined && (policy.expose === "coded" || policy.map !== undefined);
+}
+
+/**
+ * The call of a request, for `map`.
+ *
+ * @internal
+ */
+export function callOf(request: ServerRequest<unknown> | undefined): ErrorCall {
+  if (request === undefined) return { path: [] };
+  let path: ProcedurePath;
+  try {
+    path = methodToPath(request.method);
+  } catch {
+    path = [];
+  }
+  return request.transport !== undefined ? { path, transport: request.transport } : { path };
+}
+
+/** The decision of the policy for one error. */
+type Decision =
+  | { readonly kind: "keep" }
+  | { readonly kind: "replace"; readonly error: ExposedError }
+  | { readonly kind: "hide" };
+
+/**
+ * The decision of the policy for one error. `code` is the code that the error has on the wire. A
+ * `map` result is final. `"coded"` keeps an error with a code of `codes`, or with a known code
+ * that is not a failure code.
+ */
+function decide(policy: ServerErrorPolicy, error: unknown, code: string, call: ErrorCall, logMapError: (error: unknown) => void): Decision {
+  if (policy.map) {
+    let mapped: ExposedError | undefined;
+    try {
+      mapped = policy.map(error, call);
+    } catch (mapError) {
+      logMapError(mapError);
+      return { kind: "hide" };
+    }
+    if (mapped !== undefined) return { kind: "replace", error: mapped };
+  }
+  if (policy.expose !== "coded") return { kind: "keep" };
+  if (policy.codes?.includes(code) === true) return { kind: "keep" };
+  if (isKnownErrorCode(code) && !FAILURE_CODES.has(code)) return { kind: "keep" };
+  return { kind: "hide" };
+}
+
+/** A `map` result as an error: a result that is not an `Error` becomes one, with its fields. */
+function errorOfResult(result: ExposedError): Error {
+  return result instanceof Error ? result : Object.assign(new Error(result.message), result);
+}
+
+/** The metadata keys that a hidden error response keeps by default: the trace keys (CLI-80). */
+export const DEFAULT_KEPT_METADATA: readonly string[] = ["traceparent", "tracestate"];
+
+/** The metadata of a response with only the keys of the allowlist `keepMetadata` of the policy. */
+function keptMetadata(policy: ServerErrorPolicy, metadata: ServerResponse<unknown>["metadata"]): ServerResponse<unknown>["metadata"] {
+  const keys = policy.keepMetadata ?? DEFAULT_KEPT_METADATA;
+  const kept: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(metadata ?? {})) if (keys.includes(key)) kept[key] = value;
+  return kept as ServerResponse<unknown>["metadata"];
+}
+
+/**
+ * This function applies the error policy to a response that leaves the server: to an error
+ * status, and to the error that ends a stream.
+ *
+ * @internal
+ */
+export function exposedResponse<T>(policy: ServerErrorPolicy, request: ServerRequest<unknown>, response: ServerResponse<T>, log: HiddenErrorLog): ServerResponse<T> {
+  const status = response.status;
+  if (status.type === "error") {
+    // A response that the server made without an error (a refusal of the token, a duplicate
+    // stream), or a status without the link, gives `map` a ServerError of its status
+    const link = realErrorOf(response, request);
+    const real = link.found ? link.error : new ServerError(status.message, status.code, status.retryable);
+    const decision = decide(policy, real, status.code, callOf(request), (mapError) => logOnce(log, mapError, request));
+    if (decision.kind === "keep") return response;
+    const { stream: _stream, payload: _payload, ...rest } = response;
+    // Only the keys of the allowlist stay (the trace keys): an unknown key can tell of the error
+    const kept = keptMetadata(policy, response.metadata);
+    if (decision.kind === "replace") {
+      // The usual error response of the result: its wait and its conflicts go out too
+      const built = errorResponse(response.id, errorOfResult(decision.error));
+      return { ...rest, status: built.status, metadata: { ...kept, ...built.metadata } };
+    }
+    logOnce(log, real, request);
+    return {
+      ...rest,
+      // The retryable flag tells nothing private: a transient failure stays retryable
+      status: { type: "error", code: "INTERNAL_ERROR", message: HIDDEN_ERROR_MESSAGE, retryable: status.retryable },
+      metadata: kept,
+    };
+  }
+  if (response.stream === undefined) return response;
+  return { ...response, stream: exposedStream(policy, request, response.stream, log) };
+}
+
+/**
+ * The items of a stream, with the error policy for the error that ends it. A kept error goes on
+ * unchanged. Another error goes on as an error of its exposed code and message.
+ */
+function exposedStream<T>(policy: ServerErrorPolicy, request: ServerRequest<unknown>, items: AsyncIterable<T>, log: HiddenErrorLog): AsyncGenerator<T, void, undefined> {
+  const exposed = (async function* () {
+    try {
+      yield* items;
+    } catch (error) {
+      const decision = decide(policy, error, errorCodeOf(error), callOf(request), (mapError) => logOnce(log, mapError, request));
+      if (decision.kind === "keep") throw error;
+      if (decision.kind === "hide") {
+        logOnce(log, error, request);
+        // The real retryable flag of the error goes on. A last-resort catch that gets this error
+        // does not log it again.
+        const hidden = new ServerError(HIDDEN_ERROR_MESSAGE, "INTERNAL_ERROR", (error as { retryable?: unknown } | null)?.retryable === true);
+        markLogged(hidden);
+        throw hidden;
+      }
+      // Without a flag, the face gives the flag of the code (before the first item) or false
+      throw errorOfResult(decision.error);
+    }
+  })();
+  return closableUnread(exposed, items);
+}
+
+
+/**
+ * The error that a last-resort catch sends under a policy: when `handle()` throws, or when a face
+ * fails after it. `raw` is the error that the face sends without a policy. `map` runs first. Under
+ * `"coded"`, the code of `raw` decides, so `INTERNAL_ERROR` gives `"internal error"`, and the
+ * logger gets the real error one time.
+ */
+export function exposeError(policy: ServerErrorPolicy | undefined, error: unknown, call: ErrorCall, log: (error: unknown) => void, raw: ExposedError = rawErrorOf(error)): ExposedError {
+  if (!policyActs(policy)) return raw;
+  const once: HiddenErrorLog = (logged) => log(logged);
+  const decision = decide(policy, error, raw.code, call, (mapError) => logOnce(once, mapError, undefined));
+  if (decision.kind === "keep") return raw;
+  if (decision.kind === "replace") return decision.error;
+  logOnce(once, error, undefined);
+  return { code: "INTERNAL_ERROR", message: HIDDEN_ERROR_MESSAGE, retryable: raw.retryable === true };
+}
+

package/src/server/error-response.ts

@@ -0,0 +1,91 @@
+/**
+ * The error response of the server, and the link from an error status to its real error (roadmap
+ * CLI-80).
+ *
+ * The error policy of a server (`error-policy.ts`) reads the real error of a response: the error
+ * object that a handler threw, of its own class. Two links lead to it, and neither is a field of
+ * the response, so the wire, a log of the response and a deep comparison never see them:
+ * - The status object of the error response. A copy of the response (`{ ...response, id }`) keeps
+ *   the same status.
+ * - The request object of the call, with the code and the message of the status. A copy of the
+ *   status (`{ ...response.status }`, for example in a middleware or a wrapper) keeps the code
+ *   and the message, so the link holds. A status with another code or message is another error,
+ *   and has no link.
+ * - Without a link (a middleware copied both the request and the status, or made a new error),
+ *   the policy gives `map` a `ServerError` of the code, the message and the retryable flag of the
+ *   status.
+ */
+
+import { InvocationError } from "../procedures/invoke.js";
+import { VERSION_CONFLICTS_METADATA_KEY, versionConflictsOf } from "../procedures/collection/precondition.js";
+import { errorCodeOf, retryableOf } from "../protocol.js";
+import type { ServerResponse } from "./types.js";
+
+/** The real error of each error status that the server made from an error. */
+const ERRORS_OF_STATUSES = new WeakMap<object, unknown>();
+
+/** The last real error of each request, with the code and the message of its status. */
+const ERRORS_OF_REQUESTS = new WeakMap<object, { readonly code: string; readonly message: string; readonly error: unknown }>();
+
+/**
+ * This function records the real error of an error response, for the error policy: by its status
+ * object, and by the request object of the call. The response does not change.
+ *
+ * @internal
+ */
+export function withRealError<T extends ServerResponse<unknown>>(response: T, error: unknown, request?: object): T {
+  ERRORS_OF_STATUSES.set(response.status, error);
+  const status = response.status;
+  if (request !== undefined && status.type === "error") ERRORS_OF_REQUESTS.set(request, { code: String(status.code), message: status.message, error });
+  return response;
+}
+
+/**
+ * The real error of an error status of a request, or `{ found: false }` when no link leads to it.
+ *
+ * @internal
+ */
+export function realErrorOf(response: ServerResponse<unknown>, request?: object): { readonly found: true; readonly error: unknown } | { readonly found: false } {
+  const status = response.status;
+  if (ERRORS_OF_STATUSES.has(status)) return { found: true, error: ERRORS_OF_STATUSES.get(status) };
+  const recorded = request !== undefined ? ERRORS_OF_REQUESTS.get(request) : undefined;
+  if (recorded !== undefined && status.type === "error" && recorded.code === String(status.code) && recorded.message === status.message) return { found: true, error: recorded.error };
+  return { found: false };
+}
+
+/**
+ * The error response of a failed invocation. An invocation error keeps its code
+ * (VALIDATION_ERROR, NOT_EXPOSED, ABORTED and so on). An error of the handler keeps its own code
+ * when it is a string, as for a stream (`WIRE-PROTOCOL.md`). Without a code, it is HANDLER_ERROR.
+ * An error without a retryable flag gets the flag of its code in `ERROR_CODES`, or false (CLI-48).
+ * An in-band end before the first item of a stream gets the same default. After the first item,
+ * an in-band end without a flag gets false (`retryableOf`, CLI-58, CLI-68, `WIRE-PROTOCOL.md`,
+ * section "Error codes"). `request` is the request of the call: the link of the error policy to the
+ * real error (CLI-80).
+ */
+export function errorResponse(id: string, error: unknown, request?: object): ServerResponse<unknown> {
+  // A refusal of the capability says why (CAPABILITIES-2026-10)
+  const reason = error instanceof InvocationError ? error.reason : undefined;
+  // An error can ask the client to wait before a retry: retryAfterMs, in milliseconds (R12)
+  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)?.retryAfterMs;
+  const metadata: Record<string, unknown> = reason ? { reason } : {};
+  if (typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) metadata["retry-after"] = retryAfterMs;
+  // A VERSION_CONFLICT error tells the current item of each conflict (roadmap CLI-16)
+  const conflicts = versionConflictsOf(error);
+  if (conflicts !== undefined) metadata[VERSION_CONFLICTS_METADATA_KEY] = conflicts;
+  const code = errorCodeOf(error);
+  // The error policy of the server (CLI-80) reads the real error of the response
+  return withRealError({
+    id,
+    status: {
+      type: "error",
+      code,
+      message: error instanceof Error ? error.message : String(error),
+      // An error that says it is retryable stays retryable: before, every error lost the flag (deep
+      // dive TRN-7). Without a flag, the default of the code: UNAVAILABLE stays retryable, and
+      // keeps HTTP 503 (CLI-48). No item went out before this response.
+      retryable: retryableOf(error, 0),
+    },
+    metadata,
+  }, error, request);
+}

package/src/server/index.ts

@@ -40,6 +40,8 @@
 
 export { Server } from "./server.js";
 export type { ServerOptions } from "./server.js";
+export type { ServerErrorPolicy, ExposedError, ErrorCall } from "./error-policy.js";
+export { exposeError, lastResortError, HIDDEN_ERROR_MESSAGE, DEFAULT_KEPT_METADATA } from "./error-policy.js";
 
 export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
 export type { ProcedureServerOptions, RegisterProcedureOptions, StorageConfig, StopOptions, StopParts, StorageHandle, UseStorageOptions } from "./procedure-server.js";

package/src/server/last-resort.ts

@@ -0,0 +1,23 @@
+/**
+ * The last-resort catch of a face (roadmap CLI-80): when `handle()` throws, or the face fails after
+ * it. This module has no runtime import, so a face in a browser bundle (for example
+ * `PortTransport`) does not load the error policy and its imports. The policy itself runs in the
+ * server, through `RequestHandler.exposeError`.
+ */
+
+import type { ExposedError } from "./error-policy.js";
+import type { RequestHandler, ServerRequest } from "./types.js";
+
+/** The error that a last-resort catch sends without a policy: `INTERNAL_ERROR` with the message of the error. */
+export function rawErrorOf(error: unknown): ExposedError {
+  return { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message || "Internal server error" : String(error), retryable: false };
+}
+
+/**
+ * The error that the last-resort catch of a face sends: the error policy of the handler
+ * (`RequestHandler.exposeError`, which `Server` has), or `raw` for a handler without one. `raw`
+ * is the error that the face sends without a policy.
+ */
+export function lastResortError(handler: RequestHandler, error: unknown, request: ServerRequest<unknown> | undefined, raw: ExposedError = rawErrorOf(error)): ExposedError {
+  return handler.exposeError ? handler.exposeError(error, request, raw) : raw;
+}

package/src/server/procedure-server.ts

@@ -6,6 +6,9 @@
  */
 
 import { Server, type ServerOptions } from "./server.js";
+import { errorResponse } from "./error-response.js";
+
+export { errorResponse };
 import type { Admission, AmbientCredentials, Credentials, Method, Principal, PrincipalOf, RequestIdentity, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
 import { methodToPath, pathToMethod } from "./method.js";
 import { isLocalCredentials } from "./request-auth.js";
@@ -21,14 +24,13 @@ import { createCollectionProcedures } from "../procedures/collection/procedures.
 import { InvocationError, closableUnread, invokeProcedure, type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
 import type { Capability, ClearanceOrder, ProcedureContext, ResourcesOf } from "../procedures/types.js";
 import type { CollectionPartitions } from "../procedures/collection/partition.js";
-import { VERSION_CONFLICTS_METADATA_KEY, versionConflictsOf } from "../procedures/collection/precondition.js";
 import { TIMEOUT_METADATA_KEY, effectsOf, joinNarrowing, narrowCapability } from "../procedures/capability.js";
 import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptions } from "../procedures/idempotency.js";
 import { optionalMs, type Duration } from "../duration.js";
 import type { CollectionStorage } from "../procedures/collection/storage.js";
 import { TIMER_DEFAULTS } from "../timers.js";
 import { realClock, type Clock } from "../clock.js";
-import { errorCodeOf, retryableOf } from "../protocol.js";
+import { retryableOf } from "../protocol.js";
 import { EventPublisher, type EventPublisherOptions } from "../events/publisher.js";
 import { getGlobalEventBus } from "../events/bus.js";
 import type { CollectionProceduresOptions } from "../procedures/collection/procedures.js";
@@ -382,41 +384,6 @@ function withRequestTimeout(
   return narrowCapability(capability, { timeoutMs }, order);
 }
 
-/**
- * The error response of a failed invocation. An invocation error keeps its code
- * (VALIDATION_ERROR, NOT_EXPOSED, ABORTED and so on). An error of the handler keeps its own code
- * when it is a string, as for a stream (`WIRE-PROTOCOL.md`). Without a code, it is HANDLER_ERROR.
- * An error without a retryable flag gets the flag of its code in `ERROR_CODES`, or false (CLI-48).
- * An in-band end before the first item of a stream gets the same default. After the first item,
- * an in-band end without a flag gets false (`retryableOf`, CLI-58, CLI-68, `WIRE-PROTOCOL.md`,
- * section "Error codes").
- */
-export function errorResponse(id: string, error: unknown): ServerResponse<unknown> {
-  // A refusal of the capability says why (CAPABILITIES-2026-10)
-  const reason = error instanceof InvocationError ? error.reason : undefined;
-  // An error can ask the client to wait before a retry: retryAfterMs, in milliseconds (R12)
-  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)?.retryAfterMs;
-  const metadata: Record<string, unknown> = reason ? { reason } : {};
-  if (typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) metadata["retry-after"] = retryAfterMs;
-  // A VERSION_CONFLICT error tells the current item of each conflict (roadmap CLI-16)
-  const conflicts = versionConflictsOf(error);
-  if (conflicts !== undefined) metadata[VERSION_CONFLICTS_METADATA_KEY] = conflicts;
-  const code = errorCodeOf(error);
-  return {
-    id,
-    status: {
-      type: "error",
-      code,
-      message: error instanceof Error ? error.message : String(error),
-      // An error that says it is retryable stays retryable: before, every error lost the flag (deep
-      // dive TRN-7). Without a flag, the default of the code: UNAVAILABLE stays retryable, and
-      // keeps HTTP 503 (CLI-48). No item went out before this response.
-      retryable: retryableOf(error, 0),
-    },
-    metadata,
-  };
-}
-
 // =============================================================================
 // Procedure Server
 // =============================================================================
@@ -977,7 +944,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       return refused ? rateLimitedResponse(request.id, refused) : undefined;
     } catch (error) {
       const message = `The limits of the server cannot admit the call: ${error instanceof Error ? error.message : String(error)}`;
-      return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }));
+      return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }), request);
     }
   }
 
@@ -1083,7 +1050,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       );
     }
     const response = await untilAborted(result, request.signal);
-    if (response === undefined) return errorResponse(request.id, new InvocationError("ABORTED", "The request was aborted", procedure.path));
+    if (response === undefined) return errorResponse(request.id, new InvocationError("ABORTED", "The request was aborted", procedure.path), request);
     if (response.stream) {
       return {
         id: request.id,
@@ -1138,7 +1105,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         capability = this.capabilityOf(request);
       } catch (error) {
         const message = `The server cannot narrow the capability of the request: ${error instanceof Error ? error.message : String(error)}`;
-        return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }));
+        return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }), request);
       }
       const output = await invokeProcedure(procedure, request.payload, {
         registry: this.procedureRegistry,
@@ -1175,7 +1142,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       }
       return { id: request.id, status: { type: "success", code: 200 }, payload: output.value, metadata: {} };
     } catch (error) {
-      return errorResponse(request.id, error);
+      return errorResponse(request.id, error, request);
     } finally {
       if (!streams) release();
     }

package/src/server/server.ts

@@ -17,6 +17,8 @@ import type {
 } from "./types.js";
 import { HandlerNotFoundError, ServerError } from "./types.js";
 import { compose } from "../middleware/index.js";
+import { callOf, exposeError, exposedResponse, markLogged, policyActs, type ExposedError, type HiddenErrorLog, type ServerErrorPolicy } from "./error-policy.js";
+import { withRealError } from "./error-response.js";
 
 /**
  * Server configuration options.
@@ -30,7 +32,9 @@ export interface ServerOptions {
 
   /**
    * Global error handler.
-   * Called when a handler throws an error.
+   * Called when a handler throws an error. The error policy (`errors`) also gives it each hidden
+   * error one time. A last-resort error of a face that failed before it knew the call comes with
+   * `UNKNOWN_REQUEST`: a request with the id `"unknown"`.
    */
   onError?: (error: Error, request: ServerRequest) => void;
 
@@ -43,6 +47,33 @@ export interface ServerOptions {
    * Response logger.
    */
   onResponse?: (response: ServerResponse) => void;
+
+  /**
+   * The error policy (roadmap CLI-80): what an error tells the caller when it leaves the server.
+   * `handle()` applies it, so each face (HTTP, WebSocket, MCP, a message port) sends the same
+   * error. A nested call of `ctx.client` keeps the real error.
+   *
+   * - `expose: "all"` (the default): each error goes to the caller as before.
+   * - `expose: "coded"`: an error with a known code (`isKnownErrorCode`) goes to the caller as it
+   *   is, and so does an error with a code of `codes`. Each other error goes as `INTERNAL_ERROR`
+   *   with the message `"internal error"` and its real retryable flag. The server gives the real
+   *   error to `onError` one time, or to `console.error` without `onError`.
+   * - `map` runs first, with the real error of its own class. Its result goes to the caller as it
+   *   is, with its `retryAfterMs`. `undefined` gives the error to `expose`.
+   * - The last-resort catch of each face applies the same policy (`exposeError`).
+   *
+   * @example
+   * ```typescript
+   * new ProcedureServer({
+   *   errors: {
+   *     expose: "coded",
+   *     map: (error) => (isDuplicateKey(error) ? new ServerError("The item exists", "CONFLICT") : undefined),
+   *   },
+   *   onError: (error, request) => logger.error({ err: error, id: request.id }),
+   * });
+   * ```
+   */
+  errors?: ServerErrorPolicy | undefined;
 }
 
 /**
@@ -63,6 +94,9 @@ interface HandlerEntry {
   handler: ServerHandler;
 }
 
+/** The request that `onError` gets for an error of a face that failed before it knew the call (CLI-80). */
+const UNKNOWN_REQUEST: ServerRequest = { id: "unknown", method: { service: "", operation: "" }, payload: undefined, metadata: {} };
+
 /**
  * Universal RPC server.
  *
@@ -196,6 +230,35 @@ export class Server {
    */
   async handle<TReq, TRes>(
     request: ServerRequest<TReq>
+  ): Promise<ServerResponse<TRes>> {
+    const policy = this.options.errors;
+    if (!policyActs(policy)) return this.handleRaw(request);
+    const response = await this.handleRaw<TReq, TRes>(request);
+    return exposedResponse(policy, request, response, this.hiddenErrorLog);
+  }
+
+  /**
+   * The error that the last-resort catch of a face sends (roadmap CLI-80): when `handle()` throws,
+   * or the face fails after it. `raw` is the error that the face sends without a policy. Under the
+   * option `errors`, `map` runs first, and `"coded"` hides the message of `INTERNAL_ERROR`. The
+   * logger gets each hidden error one time. A face calls it through `lastResortError`.
+   */
+  exposeError(error: unknown, request: ServerRequest | undefined, raw: ExposedError): ExposedError {
+    return exposeError(this.options.errors, error, callOf(request), (real) => this.hiddenErrorLog(real, request), raw);
+  }
+
+  /** The logger of the errors that the error policy hides: `onError`, or `console.error`. */
+  private readonly hiddenErrorLog: HiddenErrorLog = (error, request) => {
+    const real = error instanceof Error ? error : new Error(String(error));
+    // A face that failed before it knew the call gives no request: onError gets a request of no call
+    if (this.options.onError) this.options.onError(real, request ?? UNKNOWN_REQUEST);
+    // A constant format: the request id comes from the caller (CodeQL js/tainted-format-string)
+    else console.error("[Server] hidden error of %s: %o", request?.id ?? "a request", real);
+  };
+
+  /** The response of a request, before the error policy. */
+  private async handleRaw<TReq, TRes>(
+    request: ServerRequest<TReq>
   ): Promise<ServerResponse<TRes>> {
     // Log request
     if (this.options.onRequest) {
@@ -235,10 +298,12 @@ export class Server {
       // Log error
       if (this.options.onError) {
         this.options.onError(error as Error, request);
+        // The error policy does not log this error again (CLI-80)
+        markLogged(error);
       }
 
       // Convert error to response
-      return this.errorToResponse<TRes>(request.id, error as Error);
+      return this.errorToResponse<TRes>(request, error as Error);
     }
   }
 
@@ -320,7 +385,12 @@ export class Server {
   /**
    * Convert error to response.
    */
-  private errorToResponse<TRes>(id: string, error: Error): ServerResponse<TRes> {
+  private errorToResponse<TRes>(request: ServerRequest<unknown>, error: Error): ServerResponse<TRes> {
+    return withRealError(this.errorToStatus<TRes>(request.id, error), error, request);
+  }
+
+  /** The response of an error, without its record for the error policy. */
+  private errorToStatus<TRes>(id: string, error: Error): ServerResponse<TRes> {
     if (error instanceof HandlerNotFoundError) {
       return {
         id,

package/src/server/types.ts

@@ -9,6 +9,7 @@ import type { Elicit } from "../procedures/elicit.js";
 import type { ReportProgress } from "../procedures/progress.js";
 import type { Metadata, Status, Method } from "../client/types.js";
 import type { CapabilityRequest } from "../procedures/types.js";
+import type { ExposedError } from "./error-policy.js";
 import { methodName } from "./method.js";
 
 // Re-export Method from client types
@@ -47,6 +48,12 @@ export interface ServerRequest<TReq = unknown> {
   /** Abort signal for cancellation */
   signal?: AbortSignal;
 
+  /**
+   * The face that took the request: `"http"`, `"websocket"`, `"port"` or `"mcp"` (roadmap CLI-80). The face
+   * sets it, not the caller. The `map` function of the error policy (`errors`) gets it.
+   */
+  transport?: string | undefined;
+
   /**
    * The credentials of the request (roadmap R18). A network face reads them from the request: the
    * bearer token of an `Authorization` header or of the `token` query of a WebSocket connection,
@@ -213,6 +220,12 @@ export interface ServerDebugReport {
  */
 export interface RequestHandler {
   handle(request: ServerRequest): Promise<ServerResponse>;
+  /**
+   * The error that the last-resort catch of a face sends, when `handle()` throws or the face fails
+   * after it (roadmap CLI-80): `raw` under the error policy of the handler. `Server` has it, and
+   * a face calls it through `lastResortError`. Absent: the face sends `raw`.
+   */
+  exposeError?(error: unknown, request: ServerRequest | undefined, raw: ExposedError): ExposedError;
   /**
    * How the handler can authenticate a network request with ambient credentials: the cookies that
    * a browser sends by itself, also for a request of another site (CSRF). A network face then