import { type FrontendToolDescriptorV1, type FrontendToolManifestV1, type JsonSchemaV1, type SpotlightToolResultEnvelope, type ToolReplayPolicyV1, type ToolRiskLevelV1, type ToolSideEffectV1, type ToolTierV1 } from "@inupedia/spotlight-protocol";
export declare const CLIENT_TOOL_META: unique symbol;
export interface ClientToolSchemaOverride {
    input: JsonSchemaV1;
    output?: JsonSchemaV1;
}
export interface ClientToolOptions {
    /** Escape hatch for types the build plugin cannot safely infer. */
    schema?: ClientToolSchemaOverride;
    version?: string;
    /**
     * What the runtime must guarantee before dispatching this tool. Declare it
     * directly; the legacy fields below only exist to keep older call sites
     * working and are derived from each other when `tier` is omitted.
     */
    tier?: ToolTierV1;
    sideEffect?: ToolSideEffectV1;
    replayPolicy?: ToolReplayPolicyV1;
    riskLevel?: ToolRiskLevelV1;
    requiresConfirmation?: boolean;
    maxOutputBytes?: number;
    namespace?: string;
    deferLoading?: boolean;
    resource?: FrontendToolDescriptorV1["resource"];
}
export interface GeneratedClientToolMeta extends ClientToolOptions {
    name: string;
    description: string;
    schema: ClientToolSchemaOverride;
}
export type ClientToolHandler<TInput, TOutput> = (input: TInput) => TOutput | Promise<TOutput>;
export type ClientTool<TInput = never, TOutput = unknown> = ClientToolHandler<TInput, TOutput> & {
    readonly [CLIENT_TOOL_META]: GeneratedClientToolMeta;
};
export interface DefineToolOptions<TInput, TOutput> extends ClientToolOptions {
    name: string;
    description: string;
    schema: ClientToolSchemaOverride;
    handler: ClientToolHandler<TInput, TOutput>;
}
export declare class SpotlightToolValidationError extends Error {
    readonly code: "TOOL_INPUT_INVALID" | "TOOL_OUTPUT_INVALID";
    readonly issues: Array<{
        path: string;
        message: string;
    }>;
    constructor(code: "TOOL_INPUT_INVALID" | "TOOL_OUTPUT_INVALID", message: string, issues: Array<{
        path: string;
        message: string;
    }>);
}
/**
 * Define a browser-side tool. Name, JSDoc and schemas are injected by the
 * Spotlight Vite plugin. Pass `schema` only as an explicit inference escape hatch.
 */
export declare function defineClientTool<TInput = void, TOutput = void>(handler: ClientToolHandler<TInput, TOutput>, options?: ClientToolOptions | GeneratedClientToolMeta): ClientTool<TInput, TOutput>;
/** Framework/build-tool neutral Tool definition for non-Vite and generated capabilities. */
export declare function defineTool<TInput = void, TOutput = void>(options: DefineToolOptions<TInput, TOutput>): ClientTool<TInput, TOutput>;
export declare function getClientToolDescriptor(tool: ClientTool): FrontendToolDescriptorV1;
export declare function createClientToolRegistry(tools: readonly ClientTool[]): {
    descriptors: FrontendToolDescriptorV1[];
    has(name: string): boolean;
    execute(name: string, input: unknown): Promise<unknown>;
    executeResult(name: string, input: unknown): Promise<SpotlightToolResultEnvelope>;
};
export declare function createClientToolManifest(options: {
    projectId: string;
    frontendBuildId: string;
    tools: readonly ClientTool[];
}): Promise<FrontendToolManifestV1>;
//# sourceMappingURL=clientTool.d.ts.map