/**
 * Content block returned by tool execution.
 * Compatible with OpenAI / Anthropic content array format.
 */
import type { PermissionRiskLevel } from "../runtime/ports/index.js";
export interface ToolContentBlock {
    type: "text" | "image";
    text?: string;
    /**
     * base64-encoded image data (only when type === "image").
     * Used by browser screenshots and MCP tools where data is already in memory.
     * The tool invoker promotes these to data-URL imageUrls for transport resolution.
     * For file-based images, prefer returning localPath via PortableToolResult.imageUrls.
     */
    data?: string;
    mimeType?: string;
}
export type LocaleCode = "zh-CN" | "en-US" | (string & {});
export interface LocalizedText {
    /**
     * Stable translation key. UI clients decide the final language.
     * Backends must not localize this string.
     */
    key: string;
    /** Safe fallback for clients that do not have the key yet. */
    fallback: string;
    /** Optional bundled values for offline clients. */
    values?: Partial<Record<LocaleCode, string>>;
}
export type CapabilityCategory = "orchestration" | "filesystem" | "web" | "search" | "memory" | "media" | "developer" | "mcp" | "automation" | "system" | "other";
export type ToolRiskLevel = PermissionRiskLevel;
/**
 * Result of executing a portable tool.
 */
export interface PortableToolResult {
    content: ToolContentBlock[];
    /** Arbitrary structured metadata for the calling runtime. */
    details?: Record<string, unknown>;
    /**
     * Local image file paths produced by this tool (e.g. read tool reading an image).
     * Transport layer resolves these via FileUploadAdapter before sending to the LLM.
     * This avoids loading large files into memory as base64.
     */
    imageUrls?: string[];
}
/**
 * A runtime-agnostic tool definition.
 *
 * @typeParam TParams The expected parameter shape (for TypeScript consumers).
 */
export interface PortableTool<TParams = Record<string, unknown>> {
    /** Unique tool name (e.g. "task", "memory"). */
    name: string;
    /** Human-readable label. */
    label: string;
    /**
     * UI category declared by the tool registration.
     * Clients must not infer this from name/description.
     */
    category?: CapabilityCategory;
    /** UI-facing localized name. */
    displayName?: LocalizedText;
    /** UI-facing localized summary. The LLM-only description stays separate. */
    displayDescription?: LocalizedText;
    /** Tool description shown to the LLM. */
    description: string;
    /** JSON Schema object describing the tool's parameters. */
    parameters: Record<string, unknown>;
    /**
     * When true, the tool should NOT appear in the default tool list.
     * The host injects it only for complex tasks (e.g. multi-step reasoning)
     * or when explicitly activated via tool_search.
     * This saves context tokens in simple conversations.
     */
    shouldDefer?: boolean;
    /**
     * Whether the tool can safely run concurrently with other tools.
     * When true, the runtime may execute this tool in parallel with others.
     * Default: false (sequential execution assumed).
     */
    isConcurrencySafe?: boolean;
    /**
     * Whether the tool only reads state and never mutates anything.
     * Read-only tools can skip confirmation prompts in strict permission modes.
     */
    isReadOnly?: boolean;
    /**
     * Unified permission risk class.
     * - read: no mutation, local or remote read-only operation
     * - write: workspace-local mutation
     * - system: shell/process/computer control or host-level mutation
     * - external_egress: sends prompts/files/data to an external service
     */
    riskLevel?: ToolRiskLevel;
    /**
     * Whether the tool is currently available.
     * CC parity: tools that return false are excluded from getTools().
     * Default: true (always enabled).
     */
    isEnabled?: () => boolean;
    /**
     * Whether the tool performs destructive operations (delete, overwrite, etc.).
     * CC parity: Tool.isDestructive field.
     * Used by permission system to require confirmation.
     */
    isDestructive?: boolean;
    /**
     * Whether this tool deletes data (files, records, resources).
     * Distinct from isDestructive (shell-level) — this is a semantic annotation
     * on tools that explicitly delete. Downstream uses separate delete-specific
     * confirmation logic from the general destructive-shell path.
     */
    isDelete?: boolean;
    /**
     * Whether this tool sends data to an external service (egress).
     * When true, the tool is classified as external_egress risk.
     */
    isEgress?: boolean;
    /**
     * Whether egress carries user data (as opposed to read-only queries).
     * Only meaningful when isEgress is true.
     * Examples: file_upload (true), web_search (false).
     */
    egressCarriesData?: boolean;
    /**
     * Tool-specific permission check before execution.
     * CC parity: Tool.checkPermissions — returns allow/deny with reason.
     * Default (via buildTool): always allow, deferring to general permission system.
     */
    checkPermissions?: (params: TParams) => {
        behavior: "allow" | "deny";
        reason?: string;
    };
    /**
     * Brief keyword hint for tool_search to match against
     * (e.g. "return the final response as structured JSON").
     */
    searchHint?: string;
    /**
     * Maximum allowed content size in characters for the tool result.
     * The runtime should truncate/reject results exceeding this.
     */
    maxResultSizeChars?: number;
    /**
     * Execute the tool.
     *
     * @param toolCallId - Unique ID for this tool invocation (for tracing).
     * @param params     - Parsed parameters matching the JSON Schema.
     * @param signal     - Optional abort signal.
     * @returns Tool result with content blocks + optional details.
     */
    execute(toolCallId: string, params: TParams, signal?: AbortSignal): Promise<PortableToolResult>;
}
/**
 * Build a complete PortableTool from a partial definition, filling safe defaults.
 * CC parity: buildTool() factory in Tool.ts.
 *
 * Defaults (fail-closed where it matters):
 * - isEnabled → true
 * - isConcurrencySafe → false
 * - isReadOnly → false
 * - isDestructive → false
 * - checkPermissions → { behavior: "allow" } (defer to general permission system)
 */
export declare function buildTool<TParams = Record<string, unknown>>(partial: PortableTool<TParams>): PortableTool<TParams>;
