import { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
import { z } from 'zod';
import { Component } from './component.js';
import { ExecutionContext, JsonValue, ToolAnnotations } from './types.js';
import { GuardConstructor } from './guards/guard.interface.js';
import { MiddlewareConstructor } from './middleware/middleware.interface.js';
import { InterceptorType } from './interceptors/interceptor.interface.js';
import { PipeConstructor } from './pipes/pipe.interface.js';
import { ExceptionFilterConstructor } from './filters/exception-filter.interface.js';
import type { TaskSupportLevel } from './task.js';
/**
 * JSON Schema representation for tool input
 */
export interface JsonSchema {
    type?: string;
    properties?: Record<string, JsonSchema>;
    required?: string[];
    items?: JsonSchema;
    additionalProperties?: boolean | JsonSchema;
    description?: string;
    default?: JsonValue;
    enum?: JsonValue[];
    [key: string]: unknown;
}
/**
 * Tool input schema - can be Zod schema or JSON Schema
 */
export type ToolInputSchema = z.ZodSchema | JsonSchema;
/**
 * Tool handler function type
 */
export type ToolHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: ExecutionContext) => Promise<TOutput>;
/**
 * Tool examples for documentation
 */
export interface ToolExamples {
    request?: JsonValue;
    response?: JsonValue;
}
/**
 * Tool invocation status messages (OpenAI Apps SDK)
 */
export interface ToolInvocation {
    /** Message shown while tool is executing */
    invoking?: string;
    /** Message shown after tool completes */
    invoked?: string;
}
export interface ToolOptions<TInput = unknown, TOutput = unknown> {
    name: string;
    /** Optional human-readable title for display */
    title?: string;
    description: string;
    inputSchema: ToolInputSchema;
    /** Optional JSON Schema for validating tool output */
    outputSchema?: ToolInputSchema;
    /** Optional annotations describing tool behavior */
    annotations?: ToolAnnotations;
    /** Optional invocation status messages for UI feedback */
    invocation?: ToolInvocation;
    handler: ToolHandler<TInput, TOutput>;
    guards?: GuardConstructor[];
    middlewares?: MiddlewareConstructor[];
    interceptors?: InterceptorType[];
    pipes?: PipeConstructor[];
    filters?: ExceptionFilterConstructor[];
    examples?: ToolExamples;
    widget?: {
        route: string;
    };
    outputTemplate?: string;
    isInitial?: boolean;
    /**
     * Task support level for this tool.
     * - 'forbidden' (default): Tool cannot be invoked as a task
     * - 'optional': Tool can be invoked normally or as a task
     * - 'required': Tool MUST be invoked as a task
     */
    taskSupport?: TaskSupportLevel;
    /**
     * Tool visibility (MCP Apps mode / session dynamic visibility).
     * Unset means the tool is not `'hidden'` and is not forced onto the
     * progressive-discovery passthrough list.
     * - `'visible'` and `defaultVisible: true` opt into that passthrough.
     * - `'hidden'` and `defaultVisible: false` hide the tool until `enableTools`.
     */
    visibility?: 'visible' | 'hidden';
    /**
     * Convenience boolean alias for visibility.
     * Setting defaultVisible: false maps directly to visibility: 'hidden'.
     */
    defaultVisible?: boolean;
    /**
     * SEP-2549 cache hint emitted on the 2026-07-28 `tools/list` result.
     * Ignored on the legacy path.
     */
    cacheHint?: {
        ttlMs?: number;
        cacheScope?: 'public' | 'private';
    };
    /**
     * Cache lifetime in seconds, typically propagated from `@Cache({ ttl })`.
     * Used as a fallback cache hint on the 2026-07-28 path.
     */
    cacheTtlSeconds?: number;
}
export declare class Tool<TInput = unknown, TOutput = unknown> {
    name: string;
    title?: string;
    description: string;
    inputSchema: ToolInputSchema;
    outputSchema?: ToolInputSchema;
    annotations?: ToolAnnotations;
    invocation?: ToolInvocation;
    visibility?: 'visible' | 'hidden';
    examples?: ToolExamples;
    widget?: {
        route: string;
    };
    outputTemplate?: string;
    isInitial?: boolean;
    /** Task support level for this tool */
    taskSupport: TaskSupportLevel;
    /** SEP-2549 cache hint (2026-07-28 path only). */
    cacheHint?: {
        ttlMs?: number;
        cacheScope?: 'public' | 'private';
    };
    /** Cache lifetime in seconds (fallback cache hint source). */
    cacheTtlSeconds?: number;
    private handler;
    private guards;
    private middlewares;
    private interceptors;
    private pipes;
    private filters;
    private component?;
    constructor(options: ToolOptions<TInput, TOutput>);
    /**
     * Execute the tool with full pipeline:
     * Exception Filters -> Guards -> Middleware -> Interceptors -> Pipes -> Handler
     */
    execute(input: TInput, context: ExecutionContext): Promise<TOutput>;
    /**
     * Execute with interceptor chain
     */
    private executeWithInterceptors;
    /**
     * Execute pipes and then the handler
     */
    private executeWithPipes;
    /**
     * Attach a UI component to this tool
     */
    setComponent(component: Component): void;
    /**
     * Check if tool has a component
     */
    hasComponent(): boolean;
    /**
     * Get the attached component
     */
    getComponent(): Component | undefined;
    /**
     * Check if schema is a Zod schema
     */
    private isZodSchema;
    /**
     * Convert schema to JSON Schema format
     */
    private convertToJsonSchema;
    /**
     * Convert to MCP tool format
     */
    toMcpTool(): Promise<McpTool>;
}
//# sourceMappingURL=tool.d.ts.map