/**
 * @license
 * Copyright 2026 Steven Roussey <sroussey@gmail.com>
 * SPDX-License-Identifier: Apache-2.0
 */
import type { SchemaNode } from "@workglow/util/schema";
import type { JsonSchema } from "@workglow/util/worker";
/**
 * A tool definition that can be passed to an LLM for tool calling.
 * Can be created manually or generated from TaskRegistry entries via `taskTypesToTools` in ToolCallingTask.
 *
 * The `name` is used both as the tool name presented to the LLM and as a
 * lookup key for the backing Task in the TaskRegistry. When a tool is
 * backed by a configurable task (e.g. `McpToolCallTask`, `JavaScriptTask`),
 * `configSchema` describes what configuration the task accepts and `config`
 * provides the concrete values. The LLM never sees `configSchema` or
 * `config` — they are setup-time concerns used when instantiating the task.
 */
export interface ToolDefinition {
    name: string;
    description: string;
    inputSchema: JsonSchema;
    outputSchema?: JsonSchema;
    /**
     * Optional discriminator for tool resolution. When specified, skips
     * duck-typing heuristics:
     * - `"function"` — uses the `execute` function directly
     * - `"task"` — looks up the task by `name` in the TaskRegistry
     *
     * When omitted, resolution falls back to the existing heuristic
     * (check `execute`, then registry lookup, then stub).
     */
    type?: "function" | "task";
    /** JSON Schema describing the task's configuration options. */
    configSchema?: JsonSchema;
    /** Concrete configuration values matching {@link configSchema}. */
    config?: Record<string, unknown>;
    /**
     * Optional custom executor function. When provided, the tool is executed
     * by calling this function directly instead of instantiating a Task.
     */
    execute?: (input: Record<string, unknown>) => Promise<Record<string, unknown>>;
}
/**
 * A tool call returned by the LLM, requesting invocation of a specific tool.
 */
export interface ToolCall {
    id: string;
    name: string;
    input: Record<string, unknown>;
}
export type ToolCalls = Array<ToolCall>;
/**
 * Controls which tools the model may call.
 * - `"auto"` — model decides whether to call tools
 * - `"none"` — model must not call any tools
 * - `"required"` — model must call at least one tool
 * - any other string — model must call the tool with that name
 */
export type ToolChoiceOption = "auto" | "none" | "required" | (string & {});
/**
 * Builds a tool description string for provider APIs, appending the output
 * schema when present. Shared across all provider implementations.
 */
export declare function buildToolDescription(tool: ToolDefinition): string;
/**
 * Validates that a tool call name returned by the LLM matches one of the
 * allowed tool definitions. Returns true if valid, false otherwise.
 */
export declare function isAllowedToolName(name: string, allowedTools: ReadonlyArray<ToolDefinition>): boolean;
/**
 * Filters an array of tool calls, removing any whose name does not appear
 * in the provided tools list. Returns the filtered array.
 */
export declare function filterValidToolCalls(toolCalls: ToolCalls, allowedTools: ReadonlyArray<ToolDefinition>): ToolCalls;
/**
 * Recursively rebuild a model-supplied JSON value, dropping any
 * `__proto__`, `constructor`, or `prototype` keys at every depth.
 * Returns a plain object (Object.prototype), never inheriting from a
 * tainted source. Use this on tool-call arguments captured from any LLM
 * before validation and propagation.
 *
 * Tool input schemas frequently set `additionalProperties: true` (or
 * omit it entirely), so a hallucinated `__proto__` key would otherwise
 * pass JSON-schema validation and leak into downstream consumers — a
 * classic prototype-pollution vector. Sanitization must happen BEFORE
 * validation so the validator sees the clean object.
 */
export declare function sanitizeToolArgs(value: unknown): unknown;
/**
 * Compiles each tool's `inputSchema` into a validator. A tool whose schema
 * fails to compile maps to `null`, signalling that downstream code should
 * fall back to name-only validation rather than failing the whole run.
 */
export declare function compileToolValidators(tools: ReadonlyArray<ToolDefinition>): Map<string, SchemaNode | null>;
/**
 * Filter tool calls whose `input` doesn't match the tool's compiled
 * `inputSchema`. Tools without a compiled validator (compile failed,
 * or absent from the map) pass through — callers should still apply
 * {@link filterValidToolCalls} for name-only defence in depth.
 */
export declare function validateToolCallArgs(toolCalls: ToolCalls, validators: ReadonlyMap<string, SchemaNode | null>): ToolCalls;
//# sourceMappingURL=ToolCallingUtils.d.ts.map