@sema-agent/core/dist/core/runner/tool-face-overlay.d.ts

Stateless, task-oriented AI agent core

/**
 * The MCP `toolFaces` OVERLAY: a deployment's per-tool face declaration for a
 * protocol tool that has no `ToolSpec` of its own (`McpServerSpec.toolFaces`, keyed by the server's RAW
 * tool name like `allowTools` / `toolAxes`). Validated against the MATERIALIZED schema at every listing
 * (the first mount and every RefreshMcpTools): `pathTarget.param` must be a top-level property; an
 * `approvalCard` must find the keys the card needs; a `ruleFace` may only name scalar keys; `family`
 * must be a member of the closed set. A failing overlay does NOT mount — the tool mounts BARE (no
 * face) and the leg announces `config.tool_face_invalid` once per tool; a `toolFaces` key naming a
 * tool the listing does not carry announces `config.tool_face_undeclared` once per name. Never a
 * silent partial application: an overlay is one declaration, applied whole or not at all.
 *
 * Prepare-path machinery (layer 1): pure over the tool objects and the server specs; the notice sink
 * is a parameter.
 */
import type { AgentTool } from "../../internal/harness-types.js";
import type { McpServerSpec } from "../mcp-server-spec.js";
import { type ToolApprovalCard } from "../tool-face.js";
import { type EngineNotice } from "../engine-notice.js";
/** The keys each specialised approval card needs on the call (the SHELL owns the
 *  card's full schema; this is the pre-filter the overlay is validated against). */
export declare const APPROVAL_CARD_REQUIRED_KEYS: Readonly<Record<ToolApprovalCard, readonly string[]>>;
export type McpToolFace = NonNullable<McpServerSpec["toolFaces"]>[string];
/** Why an overlay is refused — a closed reason list, each a distinct declaration mistake. */
export declare function toolFaceProblem(face: McpToolFace, schema: AgentTool["parameters"]): string | undefined;
export interface ApplyToolFacesInput {
    /** The materialized tools of ONE server (namespaced names). */
    tools: readonly AgentTool[];
    server: Pick<McpServerSpec, "name" | "toolFaces">;
    /** The leg's notice sink and its once-per-leg ledger (keys: `invalid:<name>` / `undeclared:<server>/<raw>`). */
    onNotice: ((notice: EngineNotice) => void) | undefined;
    announced: Set<string>;
    sessionId: string;
    runId: string;
}
/** Apply the server's overlay to its tools: a validated face is stamped on a COPY of the tool object (the same
 *  untyped carry `defineTool` uses, so the roster reads it off the instance). A face that does NOT fit the materialized
 *  schema is a bad declaration: the tool is NOT mounted on this leg (announced once, `config.tool_face_invalid`) —
 *  mounting it bare would silently drop the write protection the operator declared for it (an MCP name has no catalog
 *  floor), and a schema refresh that invalidates only a display hint must fail loud, never open. */
export declare function applyMcpToolFaces(input: ApplyToolFacesInput): AgentTool[];