@procedures/client 0.44.0 → 0.46.0

package/src/procedures/core/operands.ts

@@ -15,7 +15,7 @@ import {
   type AnyProcedureRef,
   type RefScope,
 } from "../ref.js";
-import { hydrateInput, runControl, runOperand } from "../program.js";
+import { hydrateInput, runControl, runOperand, type RunControlOptions } from "../program.js";
 
 /**
  * The operands of a control-flow procedure arrive raw: the procedure runs them itself. Its logic
@@ -37,10 +37,11 @@ function executorOf(ctx: ProcedureContext): <TIn, TOut>(path: ProcedurePath, inp
 
 /**
  * This function runs a control-flow procedure on the kernel: the runner of its kind runs the
- * operands of the input, in the scope of the caller.
+ * operands of the input, in the scope of the caller. The observer in `options` gets the result of
+ * each step of a chain (`client.trace`).
  */
-export function runControlFlow(name: string, input: unknown, ctx: ProcedureContext): Promise<unknown> {
-  return runControl(name, input, { executor: executorOf(ctx), rawInput: rawRule(ctx), onRef: ctx.onRef, scope: scopeOf(input) });
+export function runControlFlow(name: string, input: unknown, ctx: ProcedureContext, options: Pick<RunControlOptions, "onStep"> = {}): Promise<unknown> {
+  return runControl(name, input, { executor: executorOf(ctx), rawInput: rawRule(ctx), onRef: ctx.onRef, scope: scopeOf(input), onStep: options.onStep });
 }
 
 /**

package/src/procedures/index.ts

@@ -323,6 +323,8 @@ export type {
   RunDocumentOptions,
   RunProgramOptions,
   RunOperandOptions,
+  RunControlOptions,
+  StepObserver,
 } from "./program.js";
 
 // The envelope form of a program (coeval D6, D9 and D10, roadmap item M7)
@@ -337,6 +339,9 @@ export {
   allCoreProcedures,
   allCoreModules,
   chainProcedure,
+  traceProcedure,
+  type TraceRow,
+  type TraceReason,
   parallelProcedure,
   conditionalProcedure,
   andProcedure,

package/src/procedures/program.ts

@@ -995,6 +995,8 @@ export function programMachine(host: ProgramHost): Machine {
       setOwn(names, LAST, result.value);
       passed = result.value;
       results.push(result.value);
+      // The observer of this run (`RunControlOptions.onStep`) gets the result of each step
+      STEP_OBSERVERS.get(input.doc)?.(index, result.value);
     }
     return ok({ results, final: results[results.length - 1] });
   }
@@ -1377,15 +1379,35 @@ export async function runOperand(value: unknown, options: RunOperandOptions): Pr
   return runDocument(doc, { ...options, self: isAnyProcedureRef(value) ? frame : null });
 }
 
+/**
+ * The observer of the steps of one `client.chain` run. It gets the index and the result of each
+ * step that ends without an error, in the order of the steps.
+ */
+export type StepObserver = (index: number, value: unknown) => void;
+
+/** The options of `runControl()`. */
+export interface RunControlOptions extends RunDocumentOptions {
+  /**
+   * The observer of the steps of `client.chain` (`client.trace` uses it). Only the steps of this
+   * chain go to it: a nested chain does not tell it. The other procedures ignore it.
+   */
+  readonly onStep?: StepObserver | undefined;
+}
+
+/** The step observers, by the document of their `client.chain` run (`runControl()`). */
+const STEP_OBSERVERS = new WeakMap<object, StepObserver>();
+
 /**
  * This function runs a control-flow procedure on the kernel: its input becomes a document of its
  * kind, and the runner of the kind runs the operands. The input is raw: its scope (`scopeOf()`)
  * gives the names of the caller.
  */
-export async function runControl(name: string, input: unknown, options: RunDocumentOptions): Promise<unknown> {
+export async function runControl(name: string, input: unknown, options: RunControlOptions): Promise<unknown> {
   const value = desugarControlValue(name, input, { rawInput: options.rawInput, scoped: options.scope !== undefined });
   if (value === undefined) throw new TypeError(`client.${name}: the input does not have the shape of the procedure`);
-  return runDocument(controlDocument(name, value, input, options.scope !== undefined), options);
+  const doc = controlDocument(name, value, input, options.scope !== undefined);
+  if (options.onStep) STEP_OBSERVERS.set(doc, options.onStep);
+  return runDocument(doc, options);
 }
 
 /** The document of the run of a control-flow procedure: its own entry names the runner of the procedure. */

package/src/server/face-rules.ts

@@ -0,0 +1,115 @@
+/**
+ * The rules of one face of a host (CLI-43, AG1-B): a narrowing and an expose rule for each call of
+ * the face.
+ *
+ * A host can serve one server through more than one face, for example a full face and a read-only
+ * face for a browser. `faceRules()` reads the rules of one face one time, and `apply()` adds them to
+ * each request of that face:
+ *
+ * - The narrowing becomes one more source of the narrowing key (`procedure-narrowing`, CLI-30). Thus
+ *   the server applies the meet of all the sources: the capability of the policy, the request hook
+ *   and the key of the caller. A narrowing can only narrow.
+ * - The expose rule goes to `ServerRequest.expose`. The server meets it with its own rule, for the
+ *   call of the face and for each nested call. An expose rule can only narrow.
+ *
+ * The MCP face of `@procedures/mcp-server` and the HTTP and WebSocket faces of `@procedures/peer`
+ * use this module. It imports no Node code.
+ */
+
+import { NARROWING_METADATA_KEY, addNarrowing, narrowWithin, narrowingOf } from "../procedures/narrowing.js";
+import type { Capability, CapabilityRequest, ProcedurePath } from "../procedures/types.js";
+import { exposePatterns, surfaceRule, type HostPolicy, type ToolSurface } from "./host-policy.js";
+import type { ServerRequest } from "./types.js";
+
+/** The rules of one face, as options of the face. */
+export interface FaceRulesOptions {
+  /**
+   * A narrower capability for each call of the face, for example the read-only mode
+   * `{ effects: { writes: [] } }`. A narrowing that is not valid stops `faceRules()` with an error.
+   */
+  readonly narrowing?: CapabilityRequest<unknown> | readonly CapabilityRequest<unknown>[] | undefined;
+  /**
+   * The procedures that the callers of the face reach: the patterns of `hostPolicy({ expose })`, a
+   * tool surface or a function. The server meets this rule with the rule of the host.
+   */
+  readonly expose?: readonly string[] | ToolSurface | ((path: ProcedurePath) => boolean) | undefined;
+}
+
+/** The rules of one face, read one time. */
+export interface FaceRules {
+  /** The sources of the narrowing as the decoder read them, frozen. The list is empty without a narrowing. */
+  readonly narrowings: readonly CapabilityRequest<unknown>[];
+  /** The expose rule of the face, or undefined without one. */
+  readonly expose: ((path: ProcedurePath) => boolean) | undefined;
+  /**
+   * The capability of the policy, narrowed by the narrowing of the face, without the time. A face
+   * lists its procedures with it: the time limits each call, not the list.
+   */
+  readonly capability: Capability | undefined;
+  /** This function gives the request with the rules of the face. It does not change the request that it gets. */
+  apply<T>(request: ServerRequest<T>): ServerRequest<T>;
+}
+
+/** This function gives the meet of two expose rules: a path passes when it passes each rule. */
+export function meetExpose(
+  first: ((path: ProcedurePath) => boolean) | undefined,
+  second: ((path: ProcedurePath) => boolean) | undefined,
+): ((path: ProcedurePath) => boolean) | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  return (path) => first(path) && second(path);
+}
+
+/** This function gives the rule of the expose option of a face. */
+function exposeRule(expose: NonNullable<FaceRulesOptions["expose"]>): (path: ProcedurePath) => boolean {
+  if (typeof expose === "function") return expose;
+  return Array.isArray(expose) ? exposePatterns(expose as readonly string[]) : surfaceRule(expose as ToolSurface);
+}
+
+/**
+ * This function reads the rules of one face with the decoder and the meet of the wire (CLI-30).
+ * It throws for a part of the narrowing that is not valid, because each call of the face then gets
+ * a refusal. The argument `face` names the face in the message of the error, for example `MCP`.
+ *
+ * @example
+ * ```typescript
+ * const rules = faceRules({ narrowing: { effects: { writes: [] } }, expose: ["graphapi.*"] }, policy, "read");
+ * const handler = { ...inner, handle: (request) => inner.handle(rules.apply(request)) };
+ * ```
+ */
+export function faceRules(
+  options: FaceRulesOptions,
+  policy: Pick<HostPolicy, "capabilityOf" | "clearanceOrder">,
+  face?: string,
+): FaceRules {
+  let narrowings: readonly CapabilityRequest<unknown>[] = [];
+  let capability = policy.capabilityOf?.();
+  if (options.narrowing !== undefined) {
+    const wire = narrowingOf(options.narrowing);
+    // The sources as the decoder read them, frozen: a change of the options or of the metadata of a call does not change them
+    narrowings = Object.freeze(wire.narrowings.map((source) => Object.freeze({ ...source })));
+    const untimed = narrowings.map((source): CapabilityRequest<unknown> => ({
+      ...(source.clearance !== undefined ? { clearance: source.clearance } : {}),
+      ...(source.effects !== undefined ? { effects: source.effects } : {}),
+    }));
+    const listed = narrowWithin(capability, untimed, policy.clearanceOrder);
+    const refusal = [...wire.notes, ...listed.notes].find((note) => note.kind === "refused");
+    if (refusal) throw new Error(`The narrowing of ${face === undefined ? "the face" : `the ${face} face`} is not valid: ${refusal.message}`);
+    capability = listed.capability;
+  }
+  const expose = options.expose !== undefined ? exposeRule(options.expose) : undefined;
+  const sources = narrowings;
+  return {
+    narrowings,
+    expose,
+    capability,
+    apply: (request) => {
+      if (sources.length === 0 && !expose) return request;
+      return {
+        ...request,
+        ...(sources.length > 0 ? { metadata: { ...request.metadata, [NARROWING_METADATA_KEY]: addNarrowing(request.metadata[NARROWING_METADATA_KEY], sources) } } : {}),
+        ...(expose ? { expose: meetExpose(request.expose, expose) } : {}),
+      };
+    },
+  };
+}

package/src/server/procedure-server.ts

@@ -40,6 +40,7 @@ import type { ServerDebugReport } from "./types.js";
 import type { KeyedLimiter, LimiterStore } from "@mark1russell7/service/limiter";
 import { callLimiter, limitedCall, rateLimitedResponse, type CallLimit, type CallLimiter } from "./limits.js";
 import { writeLog } from "../logger.js";
+import { meetExpose } from "./face-rules.js";
 
 // =============================================================================
 // Types
@@ -818,8 +819,16 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   /**
    * The handlers that `register()` added come first (exact or pattern matches). Then the server
    * looks up the procedure of the method.
+   *
+   * The expose rule of the face of the request (`request.expose`, AG1-B) comes before both. A path
+   * outside it has no handler, also a handler of `register()` and an `alwaysOn` pin. A rule that is
+   * not a function admits no path, so a face that sets a wrong value does not open the server.
    */
-  protected override findHandler(method: Method): ServerHandler | null {
+  protected override findHandler(method: Method, request?: ServerRequest<unknown>): ServerHandler | null {
+    if (request?.expose !== undefined) {
+      const rule: unknown = request.expose;
+      if (typeof rule !== "function" || rule(methodToPath(method)) !== true) return null;
+    }
     const handler = super.findHandler(method);
     if (handler) return handler;
     const procedure = this.resolveProcedure(method);
@@ -1115,7 +1124,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         ...(request.elicit ? { elicit: request.elicit } : {}),
         ...(request.progress ? { progress: request.progress } : {}),
         repository,
-        expose: this.expose,
+        // The rule of the face of the request meets the rule of the server, also for each nested call (AG1-B)
+        expose: request.expose !== undefined ? meetExpose(this.expose, request.expose) : this.expose,
         strictCalls: this.strictCalls,
         interceptors: this.interceptors,
         capability,

package/src/server/server.ts

@@ -309,7 +309,7 @@ export class Server {
 
     try {
       // Find handler
-      const handler = this.findHandler(request.method);
+      const handler = this.findHandler(request.method, request);
       if (!handler) {
         throw new HandlerNotFoundError(request.method);
       }
@@ -351,9 +351,10 @@ export class Server {
 
   /**
    * Find handler for a method. A subclass can add handlers that it finds at request time
-   * (`ProcedureServer` looks up its registry).
+   * (`ProcedureServer` looks up its registry). The request is absent for a lookup outside a call.
+   * `ProcedureServer` reads the expose rule of its face from it (AG1-B).
    */
-  protected findHandler(method: Method): ServerHandler | null {
+  protected findHandler(method: Method, _request?: ServerRequest<unknown>): ServerHandler | null {
     for (const entry of this.handlers) {
       if (this.matchesMethod(entry.matcher, method)) {
         return entry.handler;

package/src/server/types.ts

@@ -8,7 +8,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 { CapabilityRequest, ProcedurePath } from "../procedures/types.js";
 import type { ExposedError } from "./error-policy.js";
 import type { Logger } from "../logger.js";
 import { methodName } from "./method.js";
@@ -76,6 +76,14 @@ export interface ServerRequest<TReq = unknown> {
    * capability does not become wider.
    */
   narrowing?: CapabilityRequest | undefined;
+
+  /**
+   * The expose rule of the face that took the request (AG1-B), for example a read-only face of a
+   * browser. The face sets it, not the caller: it is a function, so JSON cannot carry it.
+   * `ProcedureServer` meets it with its own expose rule, for the call and for each nested call.
+   * Thus it can only narrow. A path outside it gets `NOT_FOUND`, as a path outside the rule of the server.
+   */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
 }
 
 /**