@procedures/client 0.0.0-stage → 0.1.0

package/dist/procedures/invoke.js

@@ -0,0 +1,277 @@
+/**
+ * Procedure invocation: the one way to run a procedure.
+ *
+ * `Client.exec()`, `Client.route()`, the local transport and `ProcedureServer` run each
+ * procedure through `invokeProcedure()`. The function validates the input, makes the context,
+ * runs the handler and validates each output. Thus every host applies the same rules
+ * (ARCHITECTURE-PROPOSALS-2026-10 P1).
+ *
+ * A handler gives one value, or it is a generator that yields values (a stream). The result
+ * tells which: `{ kind: "value" }` or `{ kind: "stream" }`. A caller that wants one value uses
+ * `outputValue()` (the last item of a stream). A caller that wants each value uses `outputItems()`.
+ *
+ * Interceptors run around each invocation, the nested calls too (roadmap 1.2): policy, tracing,
+ * timeouts and metrics for every host. `interceptors.ts` has a timeout, a tracing and a metrics
+ * interceptor.
+ */
+import { pathToKey } from "./types.js";
+import { validateSchema } from "./schema.js";
+import { PROCEDURE_REGISTRY } from "./registry.js";
+import { nestedCallRefusal } from "./policy.js";
+import { scopeOf, withScope } from "./ref.js";
+import { getGlobalEventBus, withEventBusSignal } from "../events/bus.js";
+/** An error of the invocation itself. An error that the handler throws passes through unchanged. */
+export class InvocationError extends Error {
+    name = "InvocationError";
+    code;
+    path;
+    retryable = false;
+    constructor(code, message, path) {
+        super(message);
+        this.code = code;
+        this.path = path;
+    }
+}
+function abortError(path) {
+    return new InvocationError("ABORTED", `Procedure was aborted: ${pathToKey(path)}`, path);
+}
+// =============================================================================
+// Interceptors
+// =============================================================================
+let invocationCount = 0;
+// =============================================================================
+// Invocation
+// =============================================================================
+/** True for a value that `for await` can read: a generator, a stream. A string is not one. */
+export function isAsyncIterable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value[Symbol.asyncIterator] === "function");
+}
+/** The output (or one stream item), validated by the output schema of the procedure. */
+async function validateOutput(procedure, output) {
+    const result = await validateSchema(procedure.output, output);
+    if (!result.ok) {
+        throw new InvocationError("OUTPUT_VALIDATION_ERROR", `Output validation failed for ${pathToKey(procedure.path)}: ${result.message}`, procedure.path);
+    }
+    return result.value;
+}
+/** The next item, or an abort error when the signal aborts first. */
+function nextOrAbort(iterator, signal, path) {
+    if (signal.aborted)
+        return Promise.reject(abortError(path));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(path));
+        signal.addEventListener("abort", onAbort, { once: true });
+        iterator.next().then((result) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(result);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+/**
+ * The items of a handler's stream, each validated with the output schema. When the reader stops
+ * early or an item is not valid, the handler's generator gets `return()`, so its `finally` runs.
+ */
+async function* validatedItems(procedure, source, signal) {
+    const iterator = source[Symbol.asyncIterator]();
+    let done = false;
+    let aborted = false;
+    try {
+        for (;;) {
+            let step;
+            try {
+                step = signal ? await nextOrAbort(iterator, signal, procedure.path) : await iterator.next();
+            }
+            catch (error) {
+                // The handler threw (its generator is done), or the signal aborted (it is not)
+                if (error instanceof InvocationError && error.code === "ABORTED")
+                    aborted = true;
+                else
+                    done = true;
+                throw error;
+            }
+            if (step.done) {
+                done = true;
+                return;
+            }
+            yield await validateOutput(procedure, step.value);
+        }
+    }
+    finally {
+        if (!done) {
+            // The generator of an aborted handler can wait on an await: do not wait for it
+            const closing = Promise.resolve(iterator.return?.()).catch(() => undefined);
+            if (!aborted)
+                await closing;
+        }
+    }
+}
+/**
+ * This function runs a procedure: it validates the input, makes the context, runs the handler
+ * and validates the output. It throws an `InvocationError` for an invocation that cannot run,
+ * and the handler's own error when the handler throws. The interceptors of the options run
+ * around these steps.
+ */
+export async function invokeProcedure(procedure, input, options = {}) {
+    const { path } = procedure;
+    if (!procedure.handler) {
+        throw new InvocationError("NO_HANDLER", `Procedure has no handler: ${pathToKey(path)}`, path);
+    }
+    if (options.signal?.aborted)
+        throw abortError(path);
+    const invocation = {
+        id: ++invocationCount,
+        procedure,
+        path,
+        input,
+        metadata: options.metadata ?? {},
+        signal: options.signal,
+        parent: options.parent,
+        depth: options.parent ? options.parent.depth + 1 : 0,
+    };
+    const interceptors = options.interceptors ?? [];
+    if (interceptors.length === 0)
+        return runInvocation(invocation, options);
+    const dispatch = (index, current, currentOptions) => {
+        const interceptor = interceptors[index];
+        if (!interceptor)
+            return runInvocation(current, currentOptions);
+        return interceptor(current, (changes) => {
+            if (!changes)
+                return dispatch(index + 1, current, currentOptions);
+            const changed = {
+                ...current,
+                signal: changes.signal ?? current.signal,
+                metadata: changes.metadata ?? current.metadata,
+            };
+            return dispatch(index + 1, changed, { ...currentOptions, signal: changed.signal, metadata: changed.metadata });
+        });
+    };
+    return dispatch(0, invocation, options);
+}
+/** The end of the chain: the validation, the context, the handler and the output. */
+async function runInvocation(invocation, options) {
+    const { procedure, path, input } = invocation;
+    const handler = procedure.handler;
+    if (options.signal?.aborted)
+        throw abortError(path);
+    let data = input;
+    if (!options.inputValidated) {
+        // A synchronous schema gives its result at once, so the handler starts before an await
+        let parsed = validateSchema(procedure.input, input);
+        if (parsed instanceof Promise)
+            parsed = await parsed;
+        if (!parsed.ok) {
+            throw new InvocationError("VALIDATION_ERROR", `Input validation failed for ${pathToKey(path)}: ${parsed.message}`, path);
+        }
+        // A parse makes a new object, without the hidden scope of a raw input (`withScope()`). The
+        // scope goes onto the parsed data, so a runner with a Zod schema can read the names of the
+        // caller (docs review DOC-10: before, each runner needed its own workaround).
+        data = parsed.value === input ? input : withScope(parsed.value, scopeOf(input));
+    }
+    // The handler starts here, before the first await (the site's trace depends on it)
+    const result = await handler(data, createProcedureContext(procedure, options, invocation));
+    if (isAsyncIterable(result)) {
+        return { kind: "stream", items: validatedItems(procedure, result, options.signal) };
+    }
+    return { kind: "value", value: (await validateOutput(procedure, result)) };
+}
+/** This function finds the procedure at a path in the registry of the options, then runs it. */
+export async function invokePath(path, input, options = {}) {
+    const procedure = (options.registry ?? PROCEDURE_REGISTRY).get(path);
+    if (!procedure) {
+        throw new InvocationError("NOT_FOUND", `Procedure not found: ${pathToKey(path)}`, path);
+    }
+    return invokeProcedure(procedure, input, options);
+}
+// =============================================================================
+// Consumption
+// =============================================================================
+/**
+ * One value of an output: the value, or the last item of a stream (the "sponge" mode). An
+ * empty stream is an error.
+ */
+export async function outputValue(output, path = []) {
+    if (output.kind === "value")
+        return output.value;
+    let last;
+    for await (const item of output.items)
+        last = { value: item };
+    if (!last) {
+        throw new InvocationError("NO_OUTPUT", `Procedure gave no output: ${pathToKey(path)}`, path);
+    }
+    return last.value;
+}
+/** Each value of an output: the items of a stream, or the one value. */
+export async function* outputItems(output) {
+    if (output.kind === "value") {
+        yield output.value;
+        return;
+    }
+    yield* output.items;
+}
+/** The items of an output that `start` gives. Nothing runs until the reader asks for the first item. */
+export async function* streamOutput(start) {
+    yield* outputItems(await start());
+}
+// =============================================================================
+// Context
+// =============================================================================
+/**
+ * The context of a procedure. Its `client` calls other procedures through `invokePath()` with
+ * the same options, so the nested calls get the same metadata, signal, rules and interceptors.
+ * With an invocation, the nested calls name it as their parent.
+ */
+export function createProcedureContext(procedure, options = {}, invocation) {
+    const nestedOptions = invocation ? { ...options, parent: invocation } : options;
+    let client;
+    if (typeof options.client === "function") {
+        client = invocation ? options.client(invocation) : registryClient(procedure, nestedOptions);
+    }
+    else {
+        client = options.client ?? registryClient(procedure, nestedOptions);
+    }
+    const context = {
+        metadata: options.metadata ?? {},
+        path: procedure.path,
+        client,
+        registry: options.registry ?? PROCEDURE_REGISTRY,
+    };
+    if (options.signal)
+        context.signal = options.signal;
+    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
+    // 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;
+    return context;
+}
+/** The client of a procedure's context: it runs the nested calls from the registry. */
+function registryClient(caller, options) {
+    const start = (path, input) => {
+        // The call policy of the host, with the immediate caller (BUGS-2026-07 H18, deep dive MCP-3).
+        // It runs before the lookup, so a refused path tells nothing about the procedure.
+        const refusal = nestedCallRefusal(caller, path, options);
+        if (refusal) {
+            return Promise.reject(new InvocationError(refusal.code, refusal.message, path));
+        }
+        return invokePath(path, input, options);
+    };
+    return {
+        async call(path, input) {
+            return outputValue(await start(path, input), path);
+        },
+        stream(path, input) {
+            return streamOutput(() => start(path, input));
+        },
+    };
+}
+//# sourceMappingURL=invoke.js.map

package/dist/procedures/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../../src/procedures/invoke.ts"],"names":[],"mappings":"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"}

package/dist/procedures/module.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Procedure modules and explicit registries (architecture review, roadmap 3.1).
+ *
+ * Importing a package root registers its procedures in the global `PROCEDURE_REGISTRY`
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). That stays. A host that
+ * wants its own registry uses the module of each package instead: the `./module` entry of a
+ * package exports its procedures as data, and importing it registers nothing.
+ *
+ * ```ts
+ * import { createRegistry, Client, LocalTransport } from "@procedures/client";
+ * import gitModule from "@procedures/git/module";
+ *
+ * const registry = createRegistry(gitModule);
+ * const client = new Client(new LocalTransport({ registry })).useRegistry(registry);
+ * ```
+ *
+ * Two registries in one process stay apart: a nested call, `procedure.define` and the expose
+ * rule of a server all use the registry of the invocation (`ctx.registry`).
+ */
+import { ProcedureRegistry } from "./registry.js";
+import type { AnyProcedure, ProcedureModule, RegistrationOptions } from "./types.js";
+/**
+ * The procedures that `@procedures/client` registers in the global registry when it is
+ * imported: the control flow (`client.chain`, `client.map` and the others) and
+ * `procedure.define`/`get`/`list`/`delete`. `createRegistry()` always registers this module, so an
+ * explicit registry has what the global registry has.
+ */
+export declare const clientModule: ProcedureModule;
+/** This function gives a module: its procedures, and the modules whose procedures it calls. */
+export declare function defineModule(name: string, procedures: readonly AnyProcedure[], requires?: readonly ProcedureModule[]): ProcedureModule;
+/**
+ * The modules and their required modules, each one time, with each required module before the
+ * module that requires it.
+ */
+export declare function moduleClosure(modules: readonly ProcedureModule[]): ProcedureModule[];
+/** One module, or a list of modules (a bundle can give a list). */
+export type ModuleInput = ProcedureModule | readonly ProcedureModule[];
+/**
+ * Register the procedures of a module and of its required modules in a registry. A procedure
+ * that the registry has already (the same handler, from a module that two modules require) is
+ * skipped. Another procedure at the same path is an error.
+ */
+export declare function registerModules(registry: ProcedureRegistry, modules: readonly ModuleInput[], options?: RegistrationOptions): ProcedureRegistry;
+/**
+ * A new registry with the procedures of `clientModule` (what the global registry has after
+ * `import "@procedures/client"`) and of each module, with their required modules.
+ */
+export declare function createRegistry(...modules: ModuleInput[]): ProcedureRegistry;
+//# sourceMappingURL=module.d.ts.map

package/dist/procedures/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/procedures/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,iBAAiB,EAAiB,MAAM,eAAe,CAAC;AAGjE,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,eAG1B,CAAC;AAEF,+FAA+F;AAC/F,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,QAAQ,GAAE,SAAS,eAAe,EAAO,GACxC,eAAe,CAEjB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,eAAe,EAAE,CAkBpF;AAED,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,SAAS,eAAe,EAAE,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,iBAAiB,CAiBnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,GAAG,iBAAiB,CAE3E"}

package/dist/procedures/module.js

@@ -0,0 +1,93 @@
+/**
+ * Procedure modules and explicit registries (architecture review, roadmap 3.1).
+ *
+ * Importing a package root registers its procedures in the global `PROCEDURE_REGISTRY`
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). That stays. A host that
+ * wants its own registry uses the module of each package instead: the `./module` entry of a
+ * package exports its procedures as data, and importing it registers nothing.
+ *
+ * ```ts
+ * import { createRegistry, Client, LocalTransport } from "@procedures/client";
+ * import gitModule from "@procedures/git/module";
+ *
+ * const registry = createRegistry(gitModule);
+ * const client = new Client(new LocalTransport({ registry })).useRegistry(registry);
+ * ```
+ *
+ * Two registries in one process stay apart: a nested call, `procedure.define` and the expose
+ * rule of a server all use the registry of the invocation (`ctx.registry`).
+ */
+import { ProcedureRegistry, RegistryError } from "./registry.js";
+import { coreProcedures } from "./core/index.js";
+import { metaProcedures as definitionProcedures } from "./define-procedure.js";
+/**
+ * The procedures that `@procedures/client` registers in the global registry when it is
+ * imported: the control flow (`client.chain`, `client.map` and the others) and
+ * `procedure.define`/`get`/`list`/`delete`. `createRegistry()` always registers this module, so an
+ * explicit registry has what the global registry has.
+ */
+export const clientModule = {
+    name: "@procedures/client",
+    procedures: [...coreProcedures, ...definitionProcedures],
+};
+/** This function gives a module: its procedures, and the modules whose procedures it calls. */
+export function defineModule(name, procedures, requires = []) {
+    return { name, procedures: [...procedures], requires };
+}
+/**
+ * The modules and their required modules, each one time, with each required module before the
+ * module that requires it.
+ */
+export function moduleClosure(modules) {
+    const ordered = [];
+    const seen = new Set();
+    const names = new Set();
+    const visit = (module, trail) => {
+        if (seen.has(module))
+            return;
+        // Two copies of one package (two installs) have one name: the first one counts
+        if (module.name !== undefined && names.has(module.name))
+            return;
+        if (trail.includes(module)) {
+            throw new Error(`Modules require each other in a cycle: ${[...trail, module].map((m) => m.name ?? "?").join(" -> ")}`);
+        }
+        for (const required of module.requires ?? [])
+            visit(required, [...trail, module]);
+        seen.add(module);
+        if (module.name !== undefined)
+            names.add(module.name);
+        ordered.push(module);
+    };
+    for (const module of modules)
+        visit(module, []);
+    return ordered;
+}
+/**
+ * Register the procedures of a module and of its required modules in a registry. A procedure
+ * that the registry has already (the same handler, from a module that two modules require) is
+ * skipped. Another procedure at the same path is an error.
+ */
+export function registerModules(registry, modules, options) {
+    const flat = modules.flatMap((input) => (Array.isArray(input) ? input : [input]));
+    for (const module of moduleClosure(flat)) {
+        for (const procedure of module.procedures) {
+            const path = options?.pathPrefix ? [...options.pathPrefix, ...procedure.path] : procedure.path;
+            const existing = registry.get(path);
+            if (existing && !options?.override) {
+                if (existing.handler === procedure.handler)
+                    continue;
+                throw new RegistryError(`Two modules give the procedure ${path.join(".")}: the second one is ${module.name ?? "a module without a name"}`, path);
+            }
+            registry.register(procedure, options);
+        }
+    }
+    return registry;
+}
+/**
+ * A new registry with the procedures of `clientModule` (what the global registry has after
+ * `import "@procedures/client"`) and of each module, with their required modules.
+ */
+export function createRegistry(...modules) {
+    return registerModules(new ProcedureRegistry(), [clientModule, ...modules]);
+}
+//# sourceMappingURL=module.js.map

package/dist/procedures/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/procedures/module.ts"],"names":[],"mappings":"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"}

package/dist/procedures/policy.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The call policy of a host: which nested calls a procedure can make (deep dive MCP-3).
+ *
+ * A host that serves procedures to an outside caller (the MCP server, a network server) gives an
+ * `expose` rule: the procedures that its callers can reach. A procedure can call other
+ * procedures through `ctx.client`. The policy decides for each nested call, with the immediate
+ * caller:
+ *
+ * - A data-driven caller (control flow, `runs-refs`, a procedure that `procedure.define` made)
+ *   runs refs that its caller chose. It can call only exposed procedures.
+ * - A code caller with `metadata.calls` can call the procedures that it declares, and the
+ *   exposed procedures.
+ * - A code caller without `calls` can call any procedure, unless the host sets `strictCalls`.
+ *   Then it can call only exposed procedures.
+ *
+ * Before, only the first rule existed. An exposed procedure of code could call any procedure, so
+ * a code procedure that turns its input into a call was a confused deputy. The declarations make
+ * the reach of each tool visible: a test of the MCP server pins it.
+ *
+ * A host without `expose` and without `strictCalls` (a library, the local CLI) checks nothing.
+ */
+import type { AnyProcedure, ProcedurePath } from "./types.js";
+/** The call policy of a host. */
+export interface CallPolicy {
+    /** The procedures that the callers of the host can reach. Without it, every procedure is exposed. */
+    expose?: ((path: ProcedurePath) => boolean) | undefined;
+    /**
+     * True: a code procedure without `metadata.calls` can call only exposed procedures. The MCP
+     * server of the dev tools sets it.
+     */
+    strictCalls?: boolean | undefined;
+}
+/** The reason of a refused nested call. */
+export interface CallRefusal {
+    readonly code: "NOT_EXPOSED" | "NOT_DECLARED";
+    readonly message: string;
+}
+/** True when a host has a policy: a nested call is examined only then. */
+export declare function hasCallPolicy(policy: CallPolicy): boolean;
+/**
+ * True when one entry of `calls` allows a procedure key: the same key, or `"ns.*"` for a key
+ * that starts with `"ns."` (at any depth: `"fs.*"` allows `fs.read.json`).
+ */
+export declare function callMatches(entry: string, key: string): boolean;
+/**
+ * This function checks the `calls` of a procedure's metadata and returns it, or undefined when
+ * there is none. It throws for an invalid list. `"*"` alone is refused: a procedure whose
+ * callees come from its input is data-driven and must have the `runs-refs` tag.
+ */
+export declare function validateCalls(calls: unknown, path: ProcedurePath): readonly string[] | undefined;
+/** The `calls` of a procedure, or undefined when it declares none. */
+export declare function declaredCalls(procedure: Pick<AnyProcedure, "path" | "metadata">): readonly string[] | undefined;
+/** One edge of the reach of the exposed procedures: a declared call to a procedure that is not exposed. */
+export interface HiddenCall {
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * The procedures that are not exposed, but that the exposed procedures can reach through their
+ * `metadata.calls`, also through more than one step. A data-driven procedure reaches only
+ * exposed procedures, and under `strictCalls` a procedure without `calls` does too, so neither
+ * adds an edge. The edges are sorted. A test of the MCP server pins them.
+ */
+export declare function hiddenReach(procedures: readonly AnyProcedure[], expose: (path: ProcedurePath) => boolean): HiddenCall[];
+/**
+ * The refusal of a nested call from `caller` to `path` under `policy`, or undefined when the
+ * call is allowed.
+ */
+export declare function nestedCallRefusal(caller: AnyProcedure, path: ProcedurePath, policy: CallPolicy): CallRefusal | undefined;
+//# sourceMappingURL=policy.d.ts.map

package/dist/procedures/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/procedures/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI9D,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB,qGAAqG;IACrG,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAEzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAK/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAsBhG;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAE/G;AAED,2GAA2G;AAC3G,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,GACvC,UAAU,EAAE,CAqBd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAmCxH"}

package/dist/procedures/policy.js

@@ -0,0 +1,138 @@
+/**
+ * The call policy of a host: which nested calls a procedure can make (deep dive MCP-3).
+ *
+ * A host that serves procedures to an outside caller (the MCP server, a network server) gives an
+ * `expose` rule: the procedures that its callers can reach. A procedure can call other
+ * procedures through `ctx.client`. The policy decides for each nested call, with the immediate
+ * caller:
+ *
+ * - A data-driven caller (control flow, `runs-refs`, a procedure that `procedure.define` made)
+ *   runs refs that its caller chose. It can call only exposed procedures.
+ * - A code caller with `metadata.calls` can call the procedures that it declares, and the
+ *   exposed procedures.
+ * - A code caller without `calls` can call any procedure, unless the host sets `strictCalls`.
+ *   Then it can call only exposed procedures.
+ *
+ * Before, only the first rule existed. An exposed procedure of code could call any procedure, so
+ * a code procedure that turns its input into a call was a confused deputy. The declarations make
+ * the reach of each tool visible: a test of the MCP server pins it.
+ *
+ * A host without `expose` and without `strictCalls` (a library, the local CLI) checks nothing.
+ */
+import { pathToKey } from "./types.js";
+import { isDataDriven } from "./ref.js";
+/** True when a host has a policy: a nested call is examined only then. */
+export function hasCallPolicy(policy) {
+    return policy.expose !== undefined || policy.strictCalls === true;
+}
+/**
+ * True when one entry of `calls` allows a procedure key: the same key, or `"ns.*"` for a key
+ * that starts with `"ns."` (at any depth: `"fs.*"` allows `fs.read.json`).
+ */
+export function callMatches(entry, key) {
+    if (entry.endsWith(".*")) {
+        return key.startsWith(entry.slice(0, -1));
+    }
+    return entry === key;
+}
+/**
+ * This function checks the `calls` of a procedure's metadata and returns it, or undefined when
+ * there is none. It throws for an invalid list. `"*"` alone is refused: a procedure whose
+ * callees come from its input is data-driven and must have the `runs-refs` tag.
+ */
+export function validateCalls(calls, path) {
+    if (calls === undefined)
+        return undefined;
+    const where = pathToKey(path);
+    if (!Array.isArray(calls)) {
+        throw new TypeError(`metadata.calls of ${where} must be a list of procedure keys`);
+    }
+    for (const entry of calls) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new TypeError(`metadata.calls of ${where} has an entry that is not a procedure key: ${JSON.stringify(entry)}`);
+        }
+        if (entry === "*") {
+            throw new TypeError(`metadata.calls of ${where} is "*". A procedure whose callees come from its input is data-driven: ` +
+                `give it the "runs-refs" tag instead.`);
+        }
+        const body = entry.endsWith(".*") ? entry.slice(0, -2) : entry;
+        if (body.length === 0 || body.includes("*") || body.split(".").some((segment) => segment.length === 0)) {
+            throw new TypeError(`metadata.calls of ${where} has an invalid entry: "${entry}". Use "ns.name" or "ns.*".`);
+        }
+    }
+    return calls;
+}
+/** The `calls` of a procedure, or undefined when it declares none. */
+export function declaredCalls(procedure) {
+    return validateCalls(procedure.metadata?.calls, procedure.path);
+}
+/**
+ * The procedures that are not exposed, but that the exposed procedures can reach through their
+ * `metadata.calls`, also through more than one step. A data-driven procedure reaches only
+ * exposed procedures, and under `strictCalls` a procedure without `calls` does too, so neither
+ * adds an edge. The edges are sorted. A test of the MCP server pins them.
+ */
+export function hiddenReach(procedures, expose) {
+    const byKey = new Map(procedures.filter((procedure) => procedure.handler).map((procedure) => [pathToKey(procedure.path), procedure]));
+    const edges = new Map();
+    const visited = new Set();
+    const visit = (procedure) => {
+        const from = pathToKey(procedure.path);
+        if (visited.has(from))
+            return;
+        visited.add(from);
+        if (isDataDriven(procedure))
+            return;
+        for (const entry of declaredCalls(procedure) ?? []) {
+            for (const [key, callee] of byKey) {
+                if (!callMatches(entry, key) || expose(callee.path))
+                    continue;
+                edges.set(`${from} -> ${key}`, { from, to: key });
+                visit(callee);
+            }
+        }
+    };
+    for (const procedure of byKey.values()) {
+        if (expose(procedure.path))
+            visit(procedure);
+    }
+    return [...edges.keys()].sort().map((key) => edges.get(key));
+}
+/**
+ * The refusal of a nested call from `caller` to `path` under `policy`, or undefined when the
+ * call is allowed.
+ */
+export function nestedCallRefusal(caller, path, policy) {
+    if (!hasCallPolicy(policy))
+        return undefined;
+    const exposed = policy.expose ? policy.expose(path) : true;
+    const key = pathToKey(path);
+    const from = pathToKey(caller.path);
+    if (isDataDriven(caller)) {
+        return exposed
+            ? undefined
+            : {
+                code: "NOT_EXPOSED",
+                message: `Procedure not exposed: ${key}. ${from} runs procedure refs from its input, so it can call only ` +
+                    `the procedures that this server exposes.`,
+            };
+    }
+    const calls = declaredCalls(caller);
+    if (calls !== undefined) {
+        if (exposed || calls.some((entry) => callMatches(entry, key)))
+            return undefined;
+        return {
+            code: "NOT_DECLARED",
+            message: `Procedure not declared: ${from} calls ${key}, but its metadata.calls does not name it.`,
+        };
+    }
+    if (policy.strictCalls && !exposed) {
+        return {
+            code: "NOT_EXPOSED",
+            message: `Procedure not exposed: ${key}. ${from} declares no metadata.calls, and this server lets such a ` +
+                `procedure call only the procedures that it exposes.`,
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=policy.js.map