/**
 * The tool-execution boundary.
 *
 * The pure loop never runs a tool itself; it emits a `run_tool` effect carrying
 * a {@link ToolCall}, a driver hands that call to a {@link ToolRunner}, and the
 * resulting {@link ToolOutcome} is fed back in as a `tool_settled` signal. A
 * {@link ToolBox} bundles the descriptors the model is told about with the
 * runner that fulfils them.
 */
import type { ToolDescriptor } from "../../llmgateway/contract";
/** A single request to invoke a named tool, as parsed from the model's output. */
export interface ToolCall {
    /** The call id assigned by the model; pairs the outcome back to the request. */
    readonly id: string;
    /** The tool's name, matching a declared {@link ToolDescriptor}. */
    readonly name: string;
    /** The parsed arguments; shape is validated by the runner, not here. */
    readonly input: unknown;
}
/** The result of running one {@link ToolCall}. */
export interface ToolOutcome {
    /** The originating call id. */
    readonly id: string;
    /** The tool's produced value, to be projected back into a tool turn. */
    readonly output: unknown;
    /** True when `output` represents a failure the model should be told about. */
    readonly isError: boolean;
}
/**
 * The injectable side that actually executes tools.
 *
 * Implementations perform real I/O; the loop only describes what to run. The
 * passed `signal` lets a long-running tool observe cancellation (abort or a
 * mid-dispatch interjection).
 */
export interface ToolRunner {
    run(call: ToolCall, signal: AbortSignal): Promise<ToolOutcome>;
}
/** Bundles the tool catalog the model sees with the runner that fulfils it. */
export interface ToolBox {
    /** The descriptors advertised to the model on each invocation. */
    descriptors(): ToolDescriptor[];
    /** The executor for any call the model makes. */
    readonly runner: ToolRunner;
}
