agentfootprint/dist/esm/tools/toolContract.d.ts

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

/**
 * Agent ↔ tool-server contract check (proposal 009, the server-boundary extension).
 *
 * When an agent's tools call a remote tool-server (an MCP-ish sidecar, a function
 * gateway), the agent's `inputSchema` and the server's real contract can drift —
 * and the model then calls a tool that 404s, or omits an arg the server REQUIRES and
 * gets a 501/400 "doesn't work." The server usually publishes its own catalog
 * (e.g. `GET /tools` → `[{ name, inputSchema }]`), so the drift is checkable.
 *
 * `toolContractCheckup(agentTools, serverCatalog)` is a PURE diff (no I/O — the
 * consumer fetches the catalog and passes it). It mirrors the `graph.checkup()`
 * shape so both feed the same reporting.
 */
import type { Tool } from './tools.js';
export type ToolContractCode = 'missing-on-server' | 'dead-endpoint' | 'required-divergence' | 'arg-divergence' | 'optional-drift';
/** One contract issue. `kind: 'error'` fails `ok`. */
export interface ToolContractProblem {
    readonly kind: 'error' | 'warning';
    readonly code: ToolContractCode;
    readonly tool: string;
    readonly message: string;
}
export interface ToolContractCheckup {
    readonly ok: boolean;
    readonly problems: readonly ToolContractProblem[];
}
/** A server-catalog entry — the shape of one item from `GET /tools`. */
export interface ServerToolEntry {
    readonly name: string;
    readonly inputSchema?: {
        readonly required?: readonly string[];
        readonly properties?: Readonly<Record<string, unknown>>;
    };
}
/**
 * Diff an agent's tools against a server's tool catalog. Pure + deterministic.
 *
 * @param agentTools     the agent's tools (`Tool[]` or `{name, inputSchema}[]`)
 * @param serverCatalog  the server's catalog (e.g. `await (await fetch('/tools')).json()`)
 */
export declare function toolContractCheckup(agentTools: ReadonlyArray<Tool | ServerToolEntry>, serverCatalog: ReadonlyArray<ServerToolEntry>): ToolContractCheckup;
/** Format a contract check-up for a thrown error / console warning. */
export declare function formatToolContractCheckup(checkup: ToolContractCheckup): string;