@procedures/client 0.2.3 → 0.3.0

package/src/procedures/interceptors.ts

@@ -8,14 +8,16 @@
 
 import { InvocationError, type Interceptor, type Invocation, type ProcedureOutput } from "./invoke.js";
 import { pathToKey, type ProcedurePath } from "./types.js";
+import { toMs, type Duration } from "../duration.js";
+import { TRACEPARENT_METADATA_KEY, formatTraceparent, newSpanId, newTraceId, parseTraceparent } from "../tracing/traceparent.js";
 
 // =============================================================================
 // Timeout
 // =============================================================================
 
 export interface TimeoutInterceptorOptions {
-  /** The time limit in milliseconds. 0 or less: no limit. */
-  ms: number;
+  /** The time limit, for example `minutes(10)`. 0 or less: no limit. */
+  limit: Duration;
   /**
    * The invocations to limit. The default is the calls of the host (depth 0): a nested call gets
    * the signal of its parent, so the limit of the parent ends it too.
@@ -76,6 +78,14 @@ async function* itemsUntil<T>(
  * result is not used. For a stream, the limit covers the whole stream.
  */
 export function timeoutInterceptor(options: TimeoutInterceptorOptions): Interceptor {
+  return timeoutAfterMs({ ...options, ms: toMs(options.limit, "limit") });
+}
+
+/**
+ * The timeout interceptor with a limit in milliseconds. The invocation uses it for the deadline
+ * of a capability, which is a time in milliseconds.
+ */
+export function timeoutAfterMs(options: Omit<TimeoutInterceptorOptions, "limit"> & { ms: number }): Interceptor {
   const { ms } = options;
   const appliesTo = options.appliesTo ?? ((invocation: Invocation) => invocation.depth === 0);
   return async (invocation, next) => {
@@ -119,9 +129,14 @@ export function timeoutInterceptor(options: TimeoutInterceptorOptions): Intercep
 /** One invocation as a span of a trace. */
 export interface InvocationSpan {
   readonly id: string;
-  /** The span of the invocation whose handler made this call. A call of a host has none. */
+  /**
+   * The span of the invocation whose handler made this call. A call of a host has the span of its
+   * remote caller, when the caller sent a `traceparent` (roadmap R16), or none.
+   */
   readonly parentId: string | undefined;
-  /** The same for every span of one call of a host. */
+  /** True when the parent span is in another process: the caller of a host. */
+  readonly remoteParent?: boolean | undefined;
+  /** The same for every span of one call of a host, and of its caller when it sent a trace. */
   readonly traceId: string;
   readonly path: ProcedurePath;
   readonly key: string;
@@ -149,7 +164,6 @@ export interface TracingInterceptorOptions {
   now?: (() => number) | undefined;
 }
 
-let traceCount = 0;
 
 /**
  * This interceptor makes a span for each invocation, with the span of its parent. A host can
@@ -157,8 +171,6 @@ let traceCount = 0;
  */
 export function tracingInterceptor(options: TracingInterceptorOptions): Interceptor {
   const now = options.now ?? (() => performance.now());
-  const prefix = `t${++traceCount}-${Math.random().toString(36).slice(2, 8)}`;
-  let spanCount = 0;
   /** The open spans, by the id of their invocation */
   const open = new Map<number, InvocationSpan>();
 
@@ -179,11 +191,15 @@ export function tracingInterceptor(options: TracingInterceptorOptions): Intercep
 
   return async (invocation, next) => {
     const parent = invocation.parent ? open.get(invocation.parent.id) : undefined;
-    const id = `${prefix}-${++spanCount}`;
+    // A call of a host continues the trace of its caller (W3C traceparent, roadmap R16)
+    const remote = parent ? undefined : parseTraceparent(invocation.metadata[TRACEPARENT_METADATA_KEY]);
+    // W3C span ids, so a trace backend can join the spans of the client and of the server
+    const id = newSpanId();
     const span: InvocationSpan = {
       id,
-      parentId: parent?.id,
-      traceId: parent?.traceId ?? id,
+      parentId: parent?.id ?? remote?.spanId,
+      ...(remote ? { remoteParent: true } : {}),
+      traceId: parent?.traceId ?? remote?.traceId ?? newTraceId(),
       path: invocation.path,
       key: pathToKey(invocation.path),
       depth: invocation.depth,
@@ -197,7 +213,8 @@ export function tracingInterceptor(options: TracingInterceptorOptions): Intercep
 
     let output: ProcedureOutput<unknown>;
     try {
-      output = await next();
+      // The nested calls (and their remote calls) carry the span of this invocation (R16)
+      output = await next({ metadata: { ...invocation.metadata, [TRACEPARENT_METADATA_KEY]: formatTraceparent(span.traceId, id) } });
     } catch (error) {
       finish(span, invocation.id, error);
       throw error;

package/src/procedures/invoke.ts

@@ -39,7 +39,7 @@ import { PROCEDURE_REGISTRY } from "./registry.js";
 import { nestedCallRefusal } from "./policy.js";
 import { scopeOf, withScope, type HydrationEvent } from "./ref.js";
 import { UNLIMITED_CAPABILITY, capabilityRefusal, examinesNestedCall, narrowCapability, type CapabilityRefusalReason } from "./capability.js";
-import { timeoutInterceptor } from "./interceptors.js";
+import { timeoutAfterMs } from "./interceptors.js";
 import type { EventBus } from "../events/types.js";
 import { getGlobalEventBus, withEventBusSignal } from "../events/bus.js";
 
@@ -61,16 +61,29 @@ export type InvocationErrorCode =
   /** The capability of the call does not permit it (CAPABILITIES-2026-10). `reason` tells why. */
   | "FORBIDDEN";
 
+/**
+ * The reason of a `FORBIDDEN` error. It is a refusal of the capability, or a refusal of a module
+ * that the host configured:
+ * - `outside-root`: the input has a path outside the root of the host (`createFsModule({ root })`
+ *   of `@procedures/fs`).
+ * - `host-not-allowed`: the input has a URL whose host the host does not allow, or a redirect goes
+ *   to such a host (`createHttpModule({ allow })` of `@procedures/http`).
+ */
+export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed";
+
 /** An error of the invocation itself. An error that the handler throws passes through unchanged. */
 export class InvocationError extends Error {
   override readonly name = "InvocationError";
   readonly code: InvocationErrorCode;
   readonly path: ProcedurePath;
   readonly retryable: boolean = false;
-  /** The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded` or `clearance`. */
-  readonly reason: CapabilityRefusalReason | undefined;
+  /**
+   * The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded`, `clearance`,
+   * `deadline`, `outside-root` or `host-not-allowed`.
+   */
+  readonly reason: ForbiddenReason | undefined;
 
-  constructor(code: InvocationErrorCode, message: string, path: ProcedurePath, reason?: CapabilityRefusalReason) {
+  constructor(code: InvocationErrorCode, message: string, path: ProcedurePath, reason?: ForbiddenReason) {
     super(message);
     this.code = code;
     this.path = path;
@@ -304,7 +317,7 @@ export async function invokeProcedure<TOutput = unknown>(
   const deadline = invocation.capability.deadline;
   const ownDeadline = deadline !== undefined && options.parent?.capability.deadline !== deadline;
   const interceptors = ownDeadline
-    ? [timeoutInterceptor({ ms: Math.max(0, deadline - Date.now()), appliesTo: () => true }), ...(options.interceptors ?? [])]
+    ? [timeoutAfterMs({ ms: Math.max(0, deadline - Date.now()), appliesTo: () => true }), ...(options.interceptors ?? [])]
     : (options.interceptors ?? []);
   if (interceptors.length === 0) return runInvocation<TOutput>(invocation, options);
 
@@ -468,6 +481,7 @@ export function createProcedureContext(
     resources: invocation && options.resources ? options.resources(invocation) : (EMPTY_RESOURCES as ResourcesOf),
   };
   if (options.signal) context.signal = options.signal;
+  if (options.expose) context.expose = options.expose;
   if (options.repository) context.repository = options.repository;
   if (options.onRef) context.onRef = options.onRef;
   // Every context has a bus. With a signal, the waits of the handler on the bus end when the

package/src/procedures/manifest.ts

@@ -0,0 +1,158 @@
+/**
+ * One manifest type (roadmap R17).
+ *
+ * Before, ten systems described procedures, with three manifest formats, three version schemes
+ * and no shared type: `procedure.get` gave booleans for the schemas, `manifest.generate` gave
+ * JSON Schemas but no effects, `_discovery.announce` gave no schemas, the MCP tool list gave the
+ * effects as hints, and none of them obeyed the expose rule of the host. This module is the one
+ * description: a function of a procedure, and a function of a registry with the expose rule.
+ * The introspection procedures, the compiler (R20) and the SDK generators read it.
+ */
+
+import { pathToKey, type AnyProcedure, type Effects, type ProcedurePath } from "./types.js";
+import { jsonSchemaOf, type JsonSchema } from "./schema.js";
+import { isDataDriven } from "./ref.js";
+import { isRuntimeDefined } from "./runtime-programs.js";
+
+/** The format of a manifest. A change that is not compatible makes a new format. */
+export const MANIFEST_FORMAT = "procedures.manifest/1";
+
+/** The command-line metadata of a procedure: how `mark` reads its arguments and prints its result. */
+export interface CliDescription {
+  readonly args?: readonly string[] | undefined;
+  readonly shorts?: Readonly<Record<string, string>> | undefined;
+  readonly output?: string | undefined;
+  readonly interactive?: boolean | undefined;
+}
+
+/** The description of one procedure. */
+export interface ProcedureEntry {
+  readonly path: ProcedurePath;
+  readonly key: string;
+  readonly description?: string | undefined;
+  readonly tags?: readonly string[] | undefined;
+  /** The declared effects. Absent: not declared. */
+  readonly effects?: Effects | undefined;
+  /** The JSON Schema of the input (draft-07). */
+  readonly input?: JsonSchema | undefined;
+  /** The JSON Schema of the output (draft-07). */
+  readonly output?: JsonSchema | undefined;
+  /** The procedures that a procedure of code calls (`metadata.calls`). */
+  readonly calls?: readonly string[] | undefined;
+  /** True: the stream of the procedure can run without an end (R15). */
+  readonly unboundedStream?: boolean | undefined;
+  /** True: the procedure runs its input as a program (control flow, a defined procedure). */
+  readonly dataDriven: boolean;
+  /** True: `procedure.define` made it at run time. */
+  readonly runtime: boolean;
+  /** True: the procedure has a handler, so it can run here. */
+  readonly hasHandler: boolean;
+  readonly deprecated?: boolean | undefined;
+  readonly cli?: CliDescription | undefined;
+}
+
+/** The description of the procedures of a registry. */
+export interface ProcedureManifest {
+  readonly format: typeof MANIFEST_FORMAT;
+  /** A hash of the entries: two manifests with the same hash describe the same procedures. */
+  readonly hash: string;
+  readonly procedures: readonly ProcedureEntry[];
+}
+
+/** The options of `describeProcedure` and `describeRegistry`. */
+export interface DescribeOptions {
+  /** False leaves out the JSON Schemas. The default is true. */
+  readonly schemas?: boolean | undefined;
+}
+
+/** The options of `describeRegistry`. */
+export interface DescribeRegistryOptions extends DescribeOptions {
+  /** The expose rule of the host: a procedure outside it is not in the manifest. */
+  readonly expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /** More filtering: a procedure for which it gives false is not in the manifest. */
+  readonly include?: ((procedure: AnyProcedure) => boolean) | undefined;
+  /** True keeps the procedures without a handler (stubs of a remote host). The default is false. */
+  readonly withoutHandler?: boolean | undefined;
+}
+
+/** This function describes one procedure. */
+export function describeProcedure(procedure: AnyProcedure, options: DescribeOptions = {}): ProcedureEntry {
+  const meta = (procedure.metadata ?? {}) as Record<string, unknown>;
+  const schemas = options.schemas !== false;
+  const effects = meta["effects"];
+  const calls = meta["calls"];
+  const cli: CliDescription = {
+    ...(Array.isArray(meta["args"]) ? { args: meta["args"] as string[] } : {}),
+    ...(meta["shorts"] && typeof meta["shorts"] === "object" ? { shorts: meta["shorts"] as Record<string, string> } : {}),
+    ...(typeof meta["output"] === "string" ? { output: meta["output"] } : {}),
+    ...(typeof meta["interactive"] === "boolean" ? { interactive: meta["interactive"] } : {}),
+  };
+  const input = schemas ? jsonSchemaOf(procedure.input, { io: "input" }) : undefined;
+  const output = schemas ? jsonSchemaOf(procedure.output, { io: "output" }) : undefined;
+  return {
+    path: procedure.path,
+    key: pathToKey(procedure.path),
+    ...(typeof meta["description"] === "string" ? { description: meta["description"] } : {}),
+    ...(Array.isArray(meta["tags"]) ? { tags: meta["tags"] as string[] } : {}),
+    ...(effects && typeof effects === "object" ? { effects: effects as Effects } : {}),
+    ...(input ? { input } : {}),
+    ...(output ? { output } : {}),
+    ...(Array.isArray(calls) ? { calls: calls as string[] } : {}),
+    ...((meta["stream"] as { unbounded?: unknown } | undefined)?.unbounded === true ? { unboundedStream: true } : {}),
+    dataDriven: isDataDriven(procedure),
+    runtime: isRuntimeDefined(procedure),
+    hasHandler: typeof procedure.handler === "function",
+    ...(meta["deprecated"] === true ? { deprecated: true } : {}),
+    ...(Object.keys(cli).length > 0 ? { cli } : {}),
+  };
+}
+
+/** The procedures of a registry, as the expose rule of the host shows them. */
+export function exposedProcedures(
+  registry: { getAll(): AnyProcedure[] },
+  options: Pick<DescribeRegistryOptions, "expose" | "include" | "withoutHandler"> = {},
+): AnyProcedure[] {
+  return registry
+    .getAll()
+    .filter(
+      (procedure) =>
+        (options.withoutHandler === true || typeof procedure.handler === "function") &&
+        (!options.expose || options.expose(procedure.path)) &&
+        (!options.include || options.include(procedure)),
+    );
+}
+
+/**
+ * This function describes the procedures of a registry that the expose rule shows, in the order
+ * of their keys, with a hash of the description.
+ */
+export function describeRegistry(registry: { getAll(): AnyProcedure[] }, options: DescribeRegistryOptions = {}): ProcedureManifest {
+  const procedures = exposedProcedures(registry, options)
+    .map((procedure) => describeProcedure(procedure, options))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return { format: MANIFEST_FORMAT, hash: hashOf(procedures), procedures };
+}
+
+/** A stable JSON text: the keys of each object in order. */
+function stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object)
+    .sort()
+    .filter((key) => object[key] !== undefined)
+    .map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`)
+    .join(",")}}`;
+}
+
+/** A 64-bit FNV-1a hash of the stable JSON of a value, as 16 hex digits. */
+export function hashOf(value: unknown): string {
+  const text = stableJson(value);
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (let index = 0; index < text.length; index++) {
+    hash ^= BigInt(text.charCodeAt(index));
+    hash = (hash * prime) & 0xffffffffffffffffn;
+  }
+  return hash.toString(16).padStart(16, "0");
+}

package/src/procedures/runtime-programs.ts

@@ -0,0 +1,27 @@
+/**
+ * The handlers that `procedure.define` made, with the program (the aggregation) of each. The
+ * registry is the only store of the procedures: a procedure is runtime-defined when its handler
+ * is a key here. (Before, a separate map kept them, and `procedure.delete` removed only the map
+ * entry: deep dive CORE-3.) The program is kept here, not only in the metadata: a caller that
+ * gives its own metadata to `procedure.define` replaces the metadata.
+ *
+ * This module imports nothing, so the manifest (R17) and `procedure.define` can both use it
+ * without an import cycle.
+ */
+
+const RUNTIME_PROGRAMS = new WeakMap<object, unknown>();
+
+/** This function records the program of a handler that `procedure.define` made. */
+export function markRuntimeProgram(handler: object, program: unknown): void {
+  RUNTIME_PROGRAMS.set(handler, program);
+}
+
+/** True for a procedure that `procedure.define` made. */
+export function isRuntimeDefined(procedure: { handler?: unknown }): boolean {
+  return typeof procedure.handler === "function" && RUNTIME_PROGRAMS.has(procedure.handler);
+}
+
+/** The program of a handler that `procedure.define` made, or undefined. */
+export function runtimeProgramOfHandler(handler: unknown): unknown {
+  return typeof handler === "function" ? RUNTIME_PROGRAMS.get(handler) : undefined;
+}

package/src/procedures/types.ts

@@ -75,6 +75,14 @@ export interface ProcedureMetadata {
    */
   effects?: Effects;
 
+  /**
+   * The stream of the procedure (roadmap R15). `unbounded: true`: the stream can run without an
+   * end (a `follow` of logs, the output of a server process). A face that collects a stream
+   * refuses such a call or stops it at a limit: HTTP without NDJSON refuses it, and MCP stops it
+   * at its stream limits.
+   */
+  stream?: { readonly unbounded?: boolean } | undefined;
+
   /** Custom metadata fields */
   [key: string]: unknown;
 }
@@ -260,6 +268,14 @@ export interface ProcedureContext {
    */
   registry?: ProcedureRegistryLike;
 
+  /**
+   * The expose rule of the host: the procedures that its callers reach. The introspection
+   * procedures (`procedure.list`, `procedure.get`, `procedure.manifest` and the others) show only
+   * these (roadmap R17: before, a handler could not know the rule, so an MCP tool listed the
+   * procedures that the host does not expose). Absent: every procedure.
+   */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
+
   /**
    * The hydration observer of the program that runs this procedure (`client.exec(ref, input,
    * { onRef })`). A procedure that hydrates refs itself (control flow, a runner) gives it to

package/src/protocol.ts

@@ -0,0 +1,97 @@
+/**
+ * Wire protocol v1 (roadmap R25). `documentation/WIRE-PROTOCOL.md` specifies the formats.
+ *
+ * - The version: a WebSocket connection starts with a `hello` frame of each side, and an HTTP
+ *   request and its response carry the `Procedures-Protocol` header. A side refuses a newer
+ *   version with `PROTOCOL_VERSION`.
+ * - One list of error codes for all faces, with the HTTP status of each.
+ * - A change after v1 adds only optional fields, or it makes v2.
+ */
+
+/** The version of the wire protocol that this package speaks. */
+export const PROTOCOL_VERSION = 1;
+
+/** The HTTP header of the protocol version, on a request and on its response. */
+export const PROTOCOL_HEADER = "Procedures-Protocol";
+
+/** The facts of one error code. */
+export interface ErrorCodeInfo {
+  /** The HTTP status of an error with this code. */
+  readonly http: number;
+  /** True when a retry of the same call can succeed. The error item can say otherwise. */
+  readonly retryable: boolean;
+  /** What the code means. */
+  readonly meaning: string;
+}
+
+/** An error code of the protocol. */
+export type ProtocolErrorCode =
+  | "NOT_FOUND"
+  | "NO_HANDLER"
+  | "NOT_EXPOSED"
+  | "NOT_DECLARED"
+  | "FORBIDDEN"
+  | "UNAUTHORIZED"
+  | "VALIDATION_ERROR"
+  | "INVALID_REQUEST"
+  | "PROTOCOL_VERSION"
+  | "OUTPUT_VALIDATION_ERROR"
+  | "NO_OUTPUT"
+  | "HANDLER_ERROR"
+  | "INTERNAL_ERROR"
+  | "NOT_ACCEPTABLE"
+  | "DUPLICATE"
+  | "DUPLICATE_REQUEST"
+  | "ABORTED"
+  | "TIMEOUT"
+  | "UNAVAILABLE"
+  | "CONNECTION_CLOSED"
+  | "CONNECTION_NOT_FOUND";
+
+/**
+ * The error codes of the protocol, on each face (HTTP, WebSocket, MCP, local). An error that a
+ * handler throws with its own `code` keeps it. Such a code is not in this list, and HTTP gives it
+ * the status 500.
+ */
+export const ERROR_CODES: Readonly<Record<ProtocolErrorCode, ErrorCodeInfo>> = {
+  NOT_FOUND: { http: 404, retryable: false, meaning: "No procedure has the path, or the host does not expose it" },
+  NO_HANDLER: { http: 404, retryable: false, meaning: "The procedure has no handler here (a stub of a remote host)" },
+  NOT_EXPOSED: { http: 403, retryable: false, meaning: "A nested call reached a procedure that the host does not expose" },
+  NOT_DECLARED: { http: 403, retryable: false, meaning: "A nested call is not in the calls that the procedure declares" },
+  FORBIDDEN: { http: 403, retryable: false, meaning: "The capability of the call refuses it. The metadata key reason tells why" },
+  UNAUTHORIZED: { http: 401, retryable: false, meaning: "The request does not present the token of the server" },
+  VALIDATION_ERROR: { http: 400, retryable: false, meaning: "The input does not agree with the input schema" },
+  INVALID_REQUEST: { http: 400, retryable: false, meaning: "The request is not a valid request of the protocol" },
+  PROTOCOL_VERSION: { http: 400, retryable: false, meaning: "The other side speaks a newer version of the protocol" },
+  OUTPUT_VALIDATION_ERROR: { http: 500, retryable: false, meaning: "The output does not agree with the output schema" },
+  NO_OUTPUT: { http: 500, retryable: false, meaning: "The procedure gave no output" },
+  HANDLER_ERROR: { http: 500, retryable: false, meaning: "The handler threw an error without a code" },
+  INTERNAL_ERROR: { http: 500, retryable: false, meaning: "The server failed outside the handler" },
+  NOT_ACCEPTABLE: { http: 406, retryable: false, meaning: "The face cannot give the output: a stream without an end, without NDJSON" },
+  DUPLICATE: { http: 409, retryable: false, meaning: "An idempotency key gave a stream, and a stream cannot be given again" },
+  DUPLICATE_REQUEST: { http: 409, retryable: false, meaning: "A request with this id is still running on the connection" },
+  ABORTED: { http: 499, retryable: false, meaning: "The caller aborted the call" },
+  TIMEOUT: { http: 504, retryable: false, meaning: "The deadline of the call passed" },
+  UNAVAILABLE: { http: 503, retryable: true, meaning: "The server cannot take the call now: it stops, or it is busy" },
+  CONNECTION_CLOSED: { http: 503, retryable: true, meaning: "The connection closed before the call left" },
+  CONNECTION_NOT_FOUND: { http: 404, retryable: false, meaning: "The server has no connection with this id" },
+};
+
+/** True when a code is an error code of the protocol. */
+export function isProtocolErrorCode(code: unknown): code is ProtocolErrorCode {
+  return typeof code === "string" && Object.prototype.hasOwnProperty.call(ERROR_CODES, code);
+}
+
+/** The HTTP status of an error code, or undefined for a code that is not in the list. */
+export function httpStatusOf(code: unknown): number | undefined {
+  return isProtocolErrorCode(code) ? ERROR_CODES[code].http : undefined;
+}
+
+/**
+ * The protocol version that a peer sends, or undefined when it sends none (an older peer, which
+ * speaks the formats of v1 without the version).
+ */
+export function protocolVersionOf(value: unknown): number | undefined {
+  const version = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  return Number.isInteger(version) && version > 0 ? version : undefined;
+}

package/src/server/host-policy.ts

@@ -10,7 +10,7 @@
  *   procedure.
  * - `strictCalls`: a procedure of code that declares no `metadata.calls` calls only exposed
  *   procedures (a host for an outside caller sets it).
- * - `timeoutMs`: the time limit of each call from a caller (not of its nested calls).
+ * - `timeout`: the time limit of each call from a caller (not of its nested calls).
  * - `token`, `browser`: the checks of the network transports (`client-server` applies them).
  * - `capability`, `readOnly`, `clearanceOrder`, `resources`, `admitItem`: the capability of each
  *   call and what the host gives for it (CAPABILITIES-2026-10).
@@ -24,6 +24,7 @@ import { timeoutInterceptor } from "../procedures/interceptors.js";
 import type { BrowserGuardOptions } from "./browser-guard.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { ProcedureServerOptions } from "./procedure-server.js";
+import { toMs, type Duration } from "../duration.js";
 
 /** The procedures of a host that are tools: namespaces (first path segments), less some keys. */
 export interface ToolSurface {
@@ -63,8 +64,8 @@ export interface HostPolicyOptions {
   exclude?: readonly string[] | undefined;
   /** A procedure of code with no `metadata.calls` calls only exposed procedures. */
   strictCalls?: boolean | undefined;
-  /** The time limit of each call from a caller, in milliseconds. 0 or no value: no limit. */
-  timeoutMs?: number | undefined;
+  /** The time limit of each call from a caller, for example `minutes(10)`. 0 or no value: no limit. */
+  timeout?: Duration | undefined;
   /** More interceptors, after the policy's own (tracing, metrics). */
   interceptors?: readonly Interceptor[] | undefined;
   /** The token that each network request must send (HTTP and WebSocket transports). */
@@ -130,8 +131,8 @@ function exposeOf(options: HostPolicyOptions): ((path: ProcedurePath) => boolean
 /** This function builds the policy of a host from its options. */
 export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
   const interceptors: Interceptor[] = [];
-  if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
-    interceptors.push(timeoutInterceptor({ ms: options.timeoutMs }));
+  if (options.timeout !== undefined && toMs(options.timeout, "timeout") > 0) {
+    interceptors.push(timeoutInterceptor({ limit: options.timeout }));
   }
   interceptors.push(...(options.interceptors ?? []));
   return {
@@ -154,6 +155,8 @@ export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureR
     ...(registry ? { registry } : {}),
     ...(policy.expose ? { expose: policy.expose } : {}),
     strictCalls: policy.strictCalls,
+    // The token of the policy: ProcedureServer examines it for each network request (R18)
+    ...(policy.token !== undefined ? { token: policy.token } : {}),
     ...(policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
     ...(policy.capabilityOf ? { capability: policy.capabilityOf } : {}),
     ...(policy.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),

package/src/server/host-procedures.ts

@@ -0,0 +1,102 @@
+/**
+ * The procedures of a host (roadmap R19): `host.health`, `host.info` and `host.metrics`.
+ *
+ * Before, a peer gave its health only as an Express route (`/health`), and the counts of
+ * `metricsInterceptor` had no way out. A host pins these procedures on its `ProcedureServer`
+ * (`registerProcedure`), so they do not change the registry that the host serves. A call needs
+ * the token of the host, as each other call does. The `/health` route stays for the checks
+ * that have no token.
+ */
+
+import { z } from "zod";
+import { createProcedure } from "../procedures/define.js";
+import { PURE_EFFECTS } from "../procedures/effects.js";
+import type { AnyProcedure } from "../procedures/types.js";
+import type { MetricsInterceptor } from "../procedures/interceptors.js";
+import type { ProcedureServer } from "./procedure-server.js";
+
+/** What a host tells about itself. */
+export interface HostSource {
+  /** The id of the host (the peer id). */
+  readonly id: string;
+  /** The time at which the host started, from `Date.now()`. */
+  readonly startedAt: number;
+  /** The server of the host. */
+  readonly server: ProcedureServer;
+  /** The endpoints of the host, when it has network transports. */
+  readonly endpoints?: (() => ReadonlyArray<{ type: string; address: string }>) | undefined;
+  /** The metrics interceptor of the host, when it counts its calls. */
+  readonly metrics?: MetricsInterceptor | undefined;
+}
+
+const healthOutput = z.object({
+  status: z.enum(["ok", "stopping"]).describe("ok, or stopping while the host waits for its calls in flight"),
+  uptimeMs: z.number().describe("The time since the start of the host, in milliseconds"),
+  procedures: z.number().describe("The number of procedures that the host serves"),
+  callsInFlight: z.number().describe("The calls that run now, streams included"),
+  peerId: z.string().describe("The id of the host"),
+});
+
+const infoOutput = z.object({
+  peerId: z.string().describe("The id of the host"),
+  startedAt: z.string().describe("The start time of the host (ISO 8601)"),
+  endpoints: z.array(z.object({ type: z.string(), address: z.string() })).describe("The network endpoints of the host"),
+  runtime: z.string().describe("The runtime of the host, for example node 24.1.0"),
+});
+
+const metricsOutput = z.object({
+  procedures: z
+    .record(
+      z.string(),
+      z.object({ calls: z.number(), errors: z.number(), totalMs: z.number(), maxMs: z.number() }),
+    )
+    .describe("The calls, the errors and the time of each procedure since the start, by key"),
+});
+
+/** The runtime of this process: its name and version. */
+function runtimeOf(): string {
+  const process = (globalThis as { process?: { versions?: { node?: string } } }).process;
+  if (process?.versions?.node) return `node ${process.versions.node}`;
+  const navigator = (globalThis as { navigator?: { userAgent?: string } }).navigator;
+  return navigator?.userAgent ?? "unknown";
+}
+
+/** This function gives the procedures of a host: `host.health`, `host.info` and `host.metrics`. */
+export function hostProcedures(source: HostSource): AnyProcedure[] {
+  const health = createProcedure()
+    .path(["host", "health"])
+    .input(z.object({}))
+    .output(healthOutput)
+    .meta({ description: "The health of the host: its state, its uptime and its calls in flight", effects: PURE_EFFECTS })
+    .handler(async () => ({
+      status: source.server.stopping ? ("stopping" as const) : ("ok" as const),
+      uptimeMs: Date.now() - source.startedAt,
+      procedures: source.server.procedureCount,
+      callsInFlight: source.server.callsInFlight,
+      peerId: source.id,
+    }))
+    .build();
+
+  const info = createProcedure()
+    .path(["host", "info"])
+    .input(z.object({}))
+    .output(infoOutput)
+    .meta({ description: "The identity of the host: its id, its start time, its endpoints and its runtime", effects: PURE_EFFECTS })
+    .handler(async () => ({
+      peerId: source.id,
+      startedAt: new Date(source.startedAt).toISOString(),
+      endpoints: [...(source.endpoints?.() ?? [])],
+      runtime: runtimeOf(),
+    }))
+    .build();
+
+  const metrics = createProcedure()
+    .path(["host", "metrics"])
+    .input(z.object({}))
+    .output(metricsOutput)
+    .meta({ description: "The calls, the errors and the time of each procedure since the start of the host", effects: PURE_EFFECTS })
+    .handler(async () => ({ procedures: source.metrics?.snapshot() ?? {} }))
+    .build();
+
+  return [health, info, metrics] as AnyProcedure[];
+}

package/src/server/index.ts

@@ -37,14 +37,17 @@
 export { Server } from "./server.js";
 export type { ServerOptions } from "./server.js";
 
-export { ProcedureServer, createProcedureServer } from "./procedure-server.js";
-export type { ProcedureServerOptions, StorageConfig } from "./procedure-server.js";
+export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
+export type { ProcedureServerOptions, StorageConfig, StopOptions, UseStorageOptions } from "./procedure-server.js";
 export { pathToMethod, methodToPath } from "./method.js";
 export {
   HandlerNotFoundError,
   ServerError,
   type ServerRequest,
   type ServerResponse,
+  type RequestHandler,
+  type Credentials,
+  type Principal,
   type ServerHandler,
   type ServerMiddleware,
   type ServerContext,