@procedures/client 0.7.0 → 0.8.1

package/src/procedures/elicit.ts

@@ -0,0 +1,320 @@
+/**
+ * The questions of a procedure to the person at the caller (CLI-12).
+ *
+ * A face of a host (MCP, a terminal) can ask the person at the caller for input or for a
+ * confirmation during a call. The face puts an `Elicit` function on the request, and the
+ * procedure gets it as `ctx.elicit`. A face that cannot ask gives no function. Then the helpers
+ * `elicitInput` and `elicitConfirmation` give the action `unavailable` with a reason, so a
+ * procedure always gets a clear answer.
+ *
+ * The operator can answer some questions before the calls (`ElicitationPolicy.operatorConsent`):
+ * a consent that the operator gives when the server starts. The person comes first: the operator
+ * answers only when the face cannot ask the person. When the face can ask, and the question
+ * fails (a timeout, a lost connection), the answer is `unavailable`: the silence of a person is
+ * not a consent.
+ */
+
+import type { Duration } from "../duration.js";
+import type { ProcedureContext } from "./types.js";
+
+// =============================================================================
+// The fields of a form
+// =============================================================================
+
+/** The texts of a field that the face shows to the person. */
+export interface ElicitFieldBase {
+  /** The short name of the field. */
+  readonly title?: string | undefined;
+  /** The text that tells what the field is for. */
+  readonly description?: string | undefined;
+}
+
+/** A field of free text. */
+export interface ElicitTextField extends ElicitFieldBase {
+  readonly type: "string";
+  readonly enum?: undefined;
+  readonly minLength?: number | undefined;
+  readonly maxLength?: number | undefined;
+  readonly format?: "email" | "uri" | "date" | "date-time" | undefined;
+  readonly default?: string | undefined;
+}
+
+/** A field of a number. */
+export interface ElicitNumberField extends ElicitFieldBase {
+  readonly type: "number" | "integer";
+  readonly minimum?: number | undefined;
+  readonly maximum?: number | undefined;
+  readonly default?: number | undefined;
+}
+
+/** A field of yes or no. */
+export interface ElicitBooleanField extends ElicitFieldBase {
+  readonly type: "boolean";
+  readonly default?: boolean | undefined;
+}
+
+/** A field of one choice from a list. `enumNames` gives the text of each choice. */
+export interface ElicitChoiceField extends ElicitFieldBase {
+  readonly type: "string";
+  readonly enum: readonly string[];
+  readonly enumNames?: readonly string[] | undefined;
+  readonly default?: string | undefined;
+}
+
+/** A field of some choices from a list. */
+export interface ElicitChoicesField extends ElicitFieldBase {
+  readonly type: "array";
+  readonly items: { readonly type: "string"; readonly enum: readonly string[] };
+  readonly minItems?: number | undefined;
+  readonly maxItems?: number | undefined;
+  readonly default?: readonly string[] | undefined;
+}
+
+/** A field of a form: the primitive fields of MCP elicitation. A form has no nested fields. */
+export type ElicitField = ElicitTextField | ElicitNumberField | ElicitBooleanField | ElicitChoiceField | ElicitChoicesField;
+
+/** The value of a field in an answer. */
+export type ElicitValue = string | number | boolean | readonly string[];
+
+// =============================================================================
+// Questions and answers
+// =============================================================================
+
+/** A question with a form: the person fills in the fields. */
+export interface ElicitFormRequest {
+  readonly mode?: "form" | undefined;
+  /** The question, as the face shows it to the person. */
+  readonly message: string;
+  /** The fields of the answer, by name. */
+  readonly fields: Readonly<Record<string, ElicitField>>;
+  /** The names of the fields that an accepted answer must have. */
+  readonly required?: readonly string[] | undefined;
+  /**
+   * The key of the consent that the question asks for, for example `"user-provided"`. With a
+   * key, the operator can give the consent before the calls (`ElicitationPolicy.operatorConsent`).
+   * Without a key, only the person can answer.
+   */
+  readonly consent?: string | undefined;
+}
+
+/**
+ * A question with a URL: the person opens the URL and completes a step outside the face (a
+ * sign-in, a payment). The answer tells only if the person agreed to open it.
+ */
+export interface ElicitUrlRequest {
+  readonly mode: "url";
+  readonly message: string;
+  readonly url: string;
+  /** The id of the question. The default is a random id. */
+  readonly id?: string | undefined;
+}
+
+/** A question to the person at the caller. */
+export type ElicitRequest = ElicitFormRequest | ElicitUrlRequest;
+
+/** The kind of a question: a form, or a URL. */
+export type ElicitMode = "form" | "url";
+
+/**
+ * What the answer of a question is:
+ * - `accept`: the person, or the operator, gave the answer.
+ * - `decline`: the person said no.
+ * - `cancel`: the person closed the question without a choice.
+ * - `unavailable`: no one can answer. The face cannot ask the person, and no consent of the
+ *   operator applies. `reason` tells why.
+ */
+export type ElicitAction = "accept" | "decline" | "cancel" | "unavailable";
+
+/** The answer of a question. */
+export interface ElicitResult {
+  readonly action: ElicitAction;
+  /** The values of the fields, for `accept`. */
+  readonly content?: Readonly<Record<string, ElicitValue>> | undefined;
+  /** Who answered: the person, or the operator (a consent of the start). Absent for `unavailable`. */
+  readonly by?: "person" | "operator" | undefined;
+  /** Why no one answered, for `unavailable`. */
+  readonly reason?: string | undefined;
+}
+
+/** The options of one question. */
+export interface ElicitOptions {
+  /** When the signal aborts, the question stops. The default is the signal of the call. */
+  readonly signal?: AbortSignal | undefined;
+  /** The time that the face waits for the answer. The face has a default (MCP: 5 minutes). */
+  readonly timeout?: Duration | undefined;
+}
+
+/**
+ * The function that asks the person at the caller (`ctx.elicit`). `modes` tells which kinds of
+ * question the face can ask the person. An empty list: only the operator answers.
+ */
+export interface Elicit {
+  (request: ElicitRequest, options?: ElicitOptions): Promise<ElicitResult>;
+  readonly modes: readonly ElicitMode[];
+}
+
+/** This function makes an `Elicit` function from the modes of a face and its ask function. */
+export function createElicit(
+  modes: readonly ElicitMode[],
+  ask: (request: ElicitRequest, options: ElicitOptions) => Promise<ElicitResult>,
+): Elicit {
+  const elicit = (request: ElicitRequest, options?: ElicitOptions): Promise<ElicitResult> => ask(request, options ?? {});
+  return Object.assign(elicit, { modes: Object.freeze([...modes]) });
+}
+
+// =============================================================================
+// The policy of the host
+// =============================================================================
+
+/** The rules of a host for the questions of its procedures. */
+export interface ElicitationPolicy {
+  /** False: the face does not ask the person, also when it can. The default is true. */
+  readonly ask?: boolean | undefined;
+  /**
+   * The consents that the operator gives when the server starts: `true` for each question with a
+   * consent key, or a list of consent keys. The operator answers only when the face cannot ask
+   * the person, not when a question of the face fails. The default is no consent. Example:
+   * `["user-provided"]` for the flag `--allow-user-provided` of polite-crawler.
+   */
+  readonly operatorConsent?: boolean | readonly string[] | undefined;
+  /** The time that the face waits for an answer, when the question gives no time. */
+  readonly timeout?: Duration | undefined;
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** True when an error is the abort of a signal, or the signal aborted. */
+function isAbort(error: unknown, signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true || (error instanceof Error && error.name === "AbortError");
+}
+
+/**
+ * The answer when a question of the face fails: `cancel` for an abort, else `unavailable`. The
+ * operator does not answer here: the person can see the question.
+ */
+function failedAnswer(error: unknown, signal: AbortSignal | undefined): ElicitResult {
+  const reason = `The face could not get the answer of the person: ${messageOf(error)}`;
+  return { action: isAbort(error, signal) ? "cancel" : "unavailable", reason };
+}
+
+/**
+ * The answer of the operator to a question, or undefined. The operator answers a form question
+ * with a consent key that the operator gave. Each field of yes or no gets `true`, and another
+ * field gets its default. The operator gives no answer when a necessary field has no default.
+ */
+export function operatorAnswer(
+  request: ElicitRequest,
+  consent: boolean | readonly string[] | undefined,
+): ElicitResult | undefined {
+  if (consent === undefined || consent === false || request.mode === "url" || request.consent === undefined) return undefined;
+  if (consent !== true && !consent.includes(request.consent)) return undefined;
+  const content: Record<string, ElicitValue> = {};
+  for (const [name, field] of Object.entries(request.fields)) {
+    if (field.type === "boolean") content[name] = true;
+    else if (field.default !== undefined) content[name] = field.default;
+    else if (request.required?.includes(name)) return undefined;
+  }
+  return { action: "accept", content, by: "operator" };
+}
+
+/**
+ * This function applies the policy of a host to the `Elicit` function of a face. The result
+ * asks the person when the face can. A failed question gives `unavailable` (`cancel` for an
+ * abort). When the face cannot ask, the consent of the operator answers, or the answer is
+ * `unavailable`. The function gives undefined when no one can answer: no face and no consent.
+ */
+export function elicitWithPolicy(face: Elicit | undefined, policy: ElicitationPolicy = {}): Elicit | undefined {
+  const asker = policy.ask === false ? undefined : face;
+  const consent = policy.operatorConsent;
+  const operator = consent === true || (Array.isArray(consent) && consent.length > 0);
+  if (!asker && !operator) return undefined;
+  return createElicit(asker?.modes ?? [], async (request, options) => {
+    const timed: ElicitOptions =
+      options.timeout === undefined && policy.timeout !== undefined ? { ...options, timeout: policy.timeout } : options;
+    const mode: ElicitMode = request.mode ?? "form";
+    let reason: string;
+    if (asker && asker.modes.includes(mode)) {
+      // The person can see the question: a timeout or a lost connection is not a consent
+      try {
+        return await asker(request, timed);
+      } catch (error) {
+        return failedAnswer(error, options.signal);
+      }
+    } else if (asker) {
+      reason = `The face cannot ask a question of the mode "${mode}"`;
+    } else {
+      reason = policy.ask === false ? "The host does not ask the person" : "The face of the call cannot ask the person";
+    }
+    return operatorAnswer(request, consent) ?? { action: "unavailable", reason };
+  });
+}
+
+// =============================================================================
+// The helpers of a procedure
+// =============================================================================
+
+/** The reason of an answer when the context has no `elicit` function. */
+export const NO_ELICITATION_REASON =
+  "The face of the call cannot ask the person, and the operator gave no consent for this question";
+
+/**
+ * This function asks the person at the caller through `ctx.elicit`. It always gives an answer,
+ * and it does not throw. The answer is `unavailable` with a reason when the face cannot ask, or
+ * when the question fails. An abort of the call gives `cancel`.
+ */
+export async function elicitInput(
+  ctx: Pick<ProcedureContext, "elicit" | "signal">,
+  request: ElicitRequest,
+  options: ElicitOptions = {},
+): Promise<ElicitResult> {
+  if (!ctx.elicit) return { action: "unavailable", reason: NO_ELICITATION_REASON };
+  const signal = options.signal ?? ctx.signal;
+  try {
+    return await ctx.elicit(request, signal ? { ...options, signal } : options);
+  } catch (error) {
+    return failedAnswer(error, signal);
+  }
+}
+
+/** The options of `elicitConfirmation`. */
+export interface ConfirmationOptions extends ElicitOptions {
+  /** The key of the consent, so the operator can give it before the calls. */
+  readonly consent?: string | undefined;
+  /** The name of the field of yes or no. The default is `"confirm"`. */
+  readonly field?: string | undefined;
+  /** The text of the field. The default is `"Yes"`. */
+  readonly title?: string | undefined;
+  /** The text that tells what a yes does. */
+  readonly description?: string | undefined;
+}
+
+/** The answer of a confirmation. `confirmed` is true only for an accepted answer of yes. */
+export interface ConfirmationResult extends ElicitResult {
+  readonly confirmed: boolean;
+}
+
+/**
+ * This function asks the person at the caller a question of yes or no. `confirmed` is true only
+ * when the person, or the consent of the operator, says yes.
+ */
+export async function elicitConfirmation(
+  ctx: Pick<ProcedureContext, "elicit" | "signal">,
+  question: string,
+  options: ConfirmationOptions = {},
+): Promise<ConfirmationResult> {
+  const { consent, field: fieldOption, title, description, ...elicitOptions } = options;
+  const field = fieldOption ?? "confirm";
+  const result = await elicitInput(
+    ctx,
+    {
+      message: question,
+      fields: { [field]: { type: "boolean", title: title ?? "Yes", ...(description !== undefined ? { description } : {}) } },
+      required: [field],
+      ...(consent !== undefined ? { consent } : {}),
+    },
+    elicitOptions,
+  );
+  return { ...result, confirmed: result.action === "accept" && result.content?.[field] === true };
+}

package/src/procedures/hints.ts

@@ -0,0 +1,91 @@
+/**
+ * The tool hints of a procedure with its override (CLI-10).
+ *
+ * The declared effects give the hints of a tool (`toolHints()`). A procedure can make its tool
+ * look more dangerous with `metadata.toolHints`, for example `openWorldHint: true` for a store
+ * that other people can read. An override cannot make a tool look safer than its effects:
+ * the effects stay the truth, and the host enforces the effects, not the hints.
+ *
+ * The cautious value of each hint:
+ * - `readOnlyHint: false`: the tool can change something.
+ * - `destructiveHint: true`: the tool can delete or overwrite data.
+ * - `idempotentHint: false`: a second call can change more.
+ * - `openWorldHint: true`: the tool can reach systems outside the host.
+ *
+ * An override cannot give the other value, also when the effects give it. The registry refuses
+ * such an override when the procedure registers.
+ */
+
+import type { AnyProcedure } from "./types.js";
+import { toolHints, type ToolHints } from "./capability.js";
+
+/**
+ * The override of the hints of a tool. Each hint has only its cautious value, so the type refuses
+ * the other value before the registry does.
+ */
+export interface ToolHintOverride {
+  readonly readOnlyHint?: false | undefined;
+  readonly destructiveHint?: true | undefined;
+  readonly idempotentHint?: false | undefined;
+  readonly openWorldHint?: true | undefined;
+}
+
+type HintName = keyof ToolHints;
+
+/** The cautious value of each hint: the only value that an override can give. */
+const CAUTIOUS: Readonly<Record<HintName, boolean>> = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true,
+};
+
+const HINT_NAMES = Object.keys(CAUTIOUS) as HintName[];
+
+/** The override of a procedure (`metadata.toolHints`), or undefined. */
+export function toolHintOverrideOf(procedure: AnyProcedure): ToolHintOverride | undefined {
+  const value = (procedure.metadata as { toolHints?: unknown } | undefined)?.toolHints;
+  return value !== null && typeof value === "object" ? (value as ToolHintOverride) : undefined;
+}
+
+/**
+ * The refusal of the override of a procedure, or undefined when the override is correct. An
+ * override can give only the cautious value of a hint.
+ */
+export function toolHintOverrideRefusal(procedure: AnyProcedure): string | undefined {
+  const value = (procedure.metadata as { toolHints?: unknown } | undefined)?.toolHints;
+  if (value === undefined) return undefined;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return "metadata.toolHints must be an object of hints";
+  }
+  for (const [name, hint] of Object.entries(value as Record<string, unknown>)) {
+    if (hint === undefined) continue;
+    if (!HINT_NAMES.includes(name as HintName)) {
+      return `metadata.toolHints has an unknown hint "${name}". The hints are ${HINT_NAMES.join(", ")}`;
+    }
+    const cautious = CAUTIOUS[name as HintName];
+    if (hint !== cautious) {
+      return (
+        `metadata.toolHints.${name} can only be ${String(cautious)}: an override can only make a tool look more ` +
+        `dangerous than its effects. The declared effects give the other hints`
+      );
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The hints of the tool of a procedure: the hints of its effects, with the cautious values of
+ * its override. A value of the override that is not cautious has no effect (the registry refuses
+ * it at registration).
+ */
+export function toolHintsOf(procedure: AnyProcedure): ToolHints {
+  const derived = toolHints(procedure);
+  const override = toolHintOverrideOf(procedure);
+  if (!override) return derived;
+  const hints: { -readonly [name in HintName]?: boolean } = { ...derived };
+  for (const name of HINT_NAMES) {
+    if (override[name] === CAUTIOUS[name]) hints[name] = CAUTIOUS[name];
+  }
+  return hints;
+}

package/src/procedures/index.ts

@@ -25,6 +25,7 @@ export type {
   RegistrationOptions,
   ProcedureRegistryLike,
   Effects,
+  FsRootRules,
   PermittedEffects,
   Register,
   ClearanceOf,
@@ -70,6 +71,41 @@ export {
   newIdempotencyKey,
 } from "./idempotency.js";
 export type { IdempotencyOptions } from "./idempotency.js";
+// What the face of a call offers the procedure (CLI-10, CLI-12)
+export {
+  createElicit,
+  elicitWithPolicy,
+  operatorAnswer,
+  elicitInput,
+  elicitConfirmation,
+  NO_ELICITATION_REASON,
+} from "./elicit.js";
+export type {
+  Elicit,
+  ElicitRequest,
+  ElicitFormRequest,
+  ElicitUrlRequest,
+  ElicitMode,
+  ElicitAction,
+  ElicitResult,
+  ElicitOptions,
+  ElicitField,
+  ElicitFieldBase,
+  ElicitTextField,
+  ElicitNumberField,
+  ElicitBooleanField,
+  ElicitChoiceField,
+  ElicitChoicesField,
+  ElicitValue,
+  ElicitationPolicy,
+  ConfirmationOptions,
+  ConfirmationResult,
+} from "./elicit.js";
+export type { ProgressUpdate, ReportProgress } from "./progress.js";
+export { toolHintsOf, toolHintOverrideOf, toolHintOverrideRefusal } from "./hints.js";
+export type { ToolHintOverride } from "./hints.js";
+export { untrustedText, untrustedFieldsOf, untrustedTextsOf } from "./untrusted.js";
+export type { UntrustedText, UntrustedSource, UntrustedValue } from "./untrusted.js";
 export type { ToolHints, CapabilityRefusal, CapabilityRefusalReason, InvocationExplanation, EffectsViolation } from "./capability.js";
 
 // Registry
@@ -87,8 +123,49 @@ export {
 export type { ProcedureDefinition, ProcedureStub } from "./define.js";
 
 // Collection procedures
-export { createCollectionProcedures } from "./collection/index.js";
-export type { CollectionStorage, StorageChanges, StorageMetadata } from "./collection/index.js";
+export {
+  createCollectionProcedures,
+  collectionChangeTopic,
+  collectionTopicReads,
+  DEFAULT_FIND_LIMIT,
+  DEFAULT_QUERY_OPERATORS,
+  DEFAULT_QUERY_POLICY,
+  QUERY_OPERATORS,
+  applyPatch,
+  compareStorageValues,
+  compileSelector,
+  isPatchOperations,
+  matchesSelector,
+  mergePatch,
+  patchProblems,
+  queryEntries,
+  queryOptionsProblems,
+  selectorProblems,
+} from "./collection/index.js";
+export type {
+  CollectionProceduresOptions,
+  CollectionChangeEventsOptions,
+  CollectionChangeEvent,
+  StoragePatchOperations,
+  StorageQueryOperator,
+  StorageQueryPolicy,
+  CollectionStorage,
+  StorageChanges,
+  StorageMetadata,
+  StorageWriteOptions,
+  StorageSetChange,
+  StorageDeleteChange,
+  StorageClearChange,
+  StorageChangeEvent,
+  StorageChangeBatch,
+  StorageObserver,
+  StorageFieldOperators,
+  StoragePatch,
+  StorageQueryOptions,
+  StorageSelector,
+  StorageSort,
+  StorageSortDirection,
+} from "./collection/index.js";
 
 // Manual registration helpers
 export {
@@ -107,6 +184,9 @@ export {
   registerClientProcedures,
 } from "./module.js";
 export type { ModuleInput } from "./module.js";
+// One call for a registry of some modules, `invokePath` and `outputValue`
+export { callerOf } from "./caller.js";
+export type { Caller, CallerOptions } from "./caller.js";
 
 // Procedure reference system (procedure-as-data)
 export {

package/src/procedures/invoke.ts

@@ -40,7 +40,10 @@ 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 { timeoutAfterMs } from "./interceptors.js";
+import type { Elicit } from "./elicit.js";
+import type { ReportProgress } from "./progress.js";
 import type { EventBus } from "../events/types.js";
+import type { Principal } from "../server/types.js";
 import { getGlobalEventBus, withEventBusSignal } from "../events/bus.js";
 
 // =============================================================================
@@ -120,6 +123,16 @@ export interface InvokeOptions {
   repository?: RepositoryProvider | undefined;
   /** The bus of `ctx.bus`. The default is the global bus of `getGlobalEventBus()`. */
   bus?: EventBus | undefined;
+  /**
+   * The function that asks the person at the caller (`ctx.elicit`, CLI-12). A face of the host
+   * gives it. The nested calls get the same function.
+   */
+  elicit?: Elicit | undefined;
+  /**
+   * The function that tells the caller the progress of the call (`ctx.progress`). Only the call
+   * of the host gets it in its context, not its nested calls.
+   */
+  progress?: ReportProgress | undefined;
   /** The input is valid already (for example, the route resolver validated it). */
   inputValidated?: boolean | undefined;
   /**
@@ -154,6 +167,11 @@ export interface InvokeOptions {
    * It drops a refused stream item. A refused value gives `FORBIDDEN` (reason `clearance`).
    */
   admitItem?: AdmitItem | undefined;
+  /**
+   * The principal of the call, from the authentication of the host. It goes to `ctx.principal`,
+   * to the invocation and to the nested calls.
+   */
+  principal?: Principal | undefined;
 }
 
 /**
@@ -184,6 +202,8 @@ export interface Invocation {
   readonly depth: number;
   /** The capability of the invocation (frozen). */
   readonly capability: Capability;
+  /** The principal of the call: who sends it. A call from this process has none. */
+  readonly principal?: Principal | undefined;
 }
 
 /** The changes that an interceptor gives to the next step: the handler and the nested calls get them. */
@@ -313,6 +333,7 @@ export async function invokeProcedure<TOutput = unknown>(
     parent: options.parent,
     depth: options.parent ? options.parent.depth + 1 : 0,
     capability: options.capability ?? UNLIMITED_CAPABILITY,
+    ...(options.principal !== undefined ? { principal: options.principal } : {}),
   };
   // A deadline that the parent does not have (from a host, a request or a narrowed nested call)
   // ends the invocation at that time, as the timeout interceptor does
@@ -486,11 +507,21 @@ export function createProcedureContext(
   if (options.expose) context.expose = options.expose;
   if (options.repository) context.repository = options.repository;
   if (options.onRef) context.onRef = options.onRef;
+  if (options.principal !== undefined) context.principal = options.principal;
+  // The procedure of the parent invocation made this call (roadmap R33: the root of the files)
+  if (invocation?.parent) context.caller = invocation.parent.procedure;
+  // The output filter of the host, for the data that a handler sends later (roadmap CLI-15)
+  const admitItem = options.admitItem;
+  if (invocation && invocation.depth === 0 && admitItem) context.admit = async (item) => admitItem(item, invocation);
   // Every context has a bus. With a signal, the waits of the handler on the bus end when the
   // invocation aborts, so a stream handler that waits on ctx.bus.stream() can finish. (Before,
   // no host set ctx.bus: deep dive CORE-15.)
   const bus = options.bus ?? getGlobalEventBus();
   context.bus = options.signal ? withEventBusSignal(bus, options.signal) : bus;
+  // What the face of the call offers (CLI-12): the nested calls ask the same person, and only
+  // the call of the host reports its progress, so the values of one call stay in order
+  if (options.elicit) context.elicit = options.elicit;
+  if (options.progress && !invocation?.parent && !options.parent) context.progress = options.progress;
   return context;
 }
 

package/src/procedures/progress.ts

@@ -0,0 +1,25 @@
+/**
+ * The progress of a call, from the procedure to the caller (CLI-10).
+ *
+ * A face of a host (MCP) can show the progress of a long call while it operates. The face puts a
+ * `ReportProgress` function on the request when the caller asked for progress, and the procedure
+ * gets it as `ctx.progress`. A stream does not need it: a face that collects a stream shows each
+ * item as progress. Only the call of the host gets the function, not its nested calls, so the
+ * values of one call stay in order.
+ */
+
+/** One step of the progress of a call. */
+export interface ProgressUpdate {
+  /** The work that is done. It must increase with each update of a call. */
+  readonly progress: number;
+  /** The work of the whole call, when the procedure knows it. */
+  readonly total?: number | undefined;
+  /** A short text about the step, for example the URL that a crawler fetched. */
+  readonly message?: string | undefined;
+}
+
+/**
+ * The function that tells the caller the progress of the call (`ctx.progress`). It does not
+ * reject: a caller that is gone does not stop the call.
+ */
+export type ReportProgress = (update: ProgressUpdate) => Promise<void>;

package/src/procedures/registry.ts

@@ -15,6 +15,7 @@ import type {
 } from "./types.js";
 import { pathToKey } from "./types.js";
 import { validateCalls } from "./policy.js";
+import { toolHintOverrideRefusal } from "./hints.js";
 
 // =============================================================================
 // Registry Errors
@@ -135,6 +136,9 @@ export class ProcedureRegistry {
     } catch (error) {
       throw new RegistryError((error as Error).message, path);
     }
+    // An override of the tool hints can only make the tool look more dangerous than its effects
+    const hintRefusal = toolHintOverrideRefusal(procedure);
+    if (hintRefusal) throw new RegistryError(`${hintRefusal} (${key})`, path);
 
     const replaced = this.procedures.get(key);
     // The key joins the segments with dots: ["a.b", "c"] and ["a", "b.c"] have one key