agentfootprint/dist/types/tools/mcpClientUse.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * mcpClientUse — the door an MCP client pool's use of a client enters the run by.
 *
 * Pattern: a per-dispatch port (the `requestEvidence.ts` precedent) for a call,
 *          and a per-context ledger for a listing, behind one allow-list.
 * Role:    `mcpClientPool` (`mcp/pool/`, layer L12) runs below the agent (L9):
 *          it cannot reach a scope, and the agent cannot import it. Both reach
 *          this module, which sits under both:
 *
 *   - a CALL: the dispatch loop puts a port on each call's context
 *     (`mcpClientUseFor`), stamped with that call's id; a pooled tool files its
 *     use through it once, as its `execute` settles;
 *   - a LISTING: the pool files its use against the `ToolDispatchContext`
 *     object it was handed (`fileListUse`); the tools slot takes the uses filed
 *     against the context it passed (`takeListUses`) after `list(ctx)`, and
 *     emits them.
 *
 * Either way the event is `agentfootprint.tools.mcp_client`, emitted by the
 * library stage that called the pool, mid-stage, through `typedEmit` — so the
 * run's redaction rule serves it and its meta carries the real stage.
 *
 * THE ALLOW-LIST is the whole record: the fields of `ToolsMcpClientPayload`,
 * the library's own words for each, numbers, and two ids of the pool's own
 * making (`keyHash`, `clientId`) under a fixed shape. A filing with anything
 * else — a field nobody listed, a word outside its set, a non-plain value — is
 * refused whole, never trimmed into something it did not say.
 */
import type { ToolsMcpClientPayload } from '../events/payloads.js';
import { type EmitableScope } from '../recorders/core/typedEmit.js';
/** What a pool use files: the payload, less the call id the dispatch stamps. */
export type McpClientUse = Omit<ToolsMcpClientPayload, 'toolCallId'>;
/** Where one dispatched call's pool use goes. */
export interface McpClientUseSink {
    /** File the use. Never throws; a filing outside the allow-list is refused whole. */
    file(use: McpClientUse): void;
}
/** @internal The context key the dispatcher puts a call's sink under. */
export declare const MCP_CLIENT_USE: unique symbol;
/** What the dispatcher spreads into a call's context. */
export interface McpClientUsePort {
    readonly [MCP_CLIENT_USE]: McpClientUseSink;
}
/**
 * The port for one dispatch: files `agentfootprint.tools.mcp_client` at
 * `'call'`, stamped with the call's id, at most once.
 */
export declare function mcpClientUseFor(scope: EmitableScope, call: {
    readonly toolCallId: string;
}): McpClientUsePort;
/** The sink a call's context carries, or `undefined`. Never throws, whatever `ctx` is. */
export declare function mcpClientUseOf(ctx: unknown): McpClientUseSink | undefined;
/** File a listing's use against the `ToolDispatchContext` it was asked with. Never throws. */
export declare function fileListUse(ctx: unknown, use: McpClientUse): void;
/** Take (and forget) every listing use filed against `ctx`. */
export declare function takeListUses(ctx: object): readonly McpClientUse[];
/** Emit the listing uses filed against `ctx`, as the tools slot does after `list(ctx)`. */
export declare function emitListUses(scope: EmitableScope, ctx: object): void;
/** The use as the record may carry it, or `undefined` when it is outside the allow-list. */
export declare function servedUse(use: McpClientUse): McpClientUse | undefined;
//# sourceMappingURL=mcpClientUse.d.ts.map