/**
 * Generic host-side agent tool registry (registerTool / listTools / schemas).
 */
import type { AgentToolErrorCode, AgentUiContext, HostToolEffect, ToolExecutionTarget } from "@inupedia/spotlight-protocol";
export type { AgentToolErrorCode, HostToolEffect, ToolExecutionTarget };
export interface ToolContextHint {
    ensureSceneLevel?: number;
    ensureMainTab?: string;
    ensureSmallTab?: string;
}
export type ToolExecutionMode = "serial" | "parallel-safe";
export interface ToolInputSchemaSuccess<TInput> {
    success: true;
    data: TInput;
}
export interface ToolInputSchemaFailure {
    success: false;
    error: string;
}
export type ToolInputSchemaResult<TInput> = ToolInputSchemaSuccess<TInput> | ToolInputSchemaFailure;
export interface ToolInputSchema<TInput = unknown> {
    safeParse(input: unknown): ToolInputSchemaResult<TInput>;
    describe?: string;
}
type ToolInputFieldDescriptor = {
    type: "string" | "number" | "boolean";
    enum?: readonly (string | number | boolean)[];
    optional?: boolean;
    description?: string;
};
export declare function createToolInputSchema<TInput extends Record<string, unknown>>(fields: Record<string, ToolInputFieldDescriptor>): ToolInputSchema<TInput>;
export declare function createLooseObjectSchema<TInput extends Record<string, unknown> = Record<string, unknown>>(description?: string): ToolInputSchema<TInput>;
export interface ToolRecoveryConfig<TInput = unknown> {
    maxRetries?: number;
    retryOn?: AgentToolErrorCode[];
    beforeRetry?: (input: TInput) => Promise<void> | void;
    rollback?: (input: TInput) => Promise<void> | void;
}
export interface ToolPreflightContext<TContext extends AgentUiContext = AgentUiContext> {
    uiContext: TContext;
}
export type ToolPreflightResult = {
    ok: true;
} | {
    ok: false;
    reason: string;
};
export interface ToolAvailability<TInput = unknown, TContext extends AgentUiContext = AgentUiContext> {
    isAvailable?: (ctx: TContext) => boolean;
    requirements?: string[];
    contextHint?: ToolContextHint;
    preflight?: (input: TInput, context: ToolPreflightContext<TContext>) => Promise<ToolPreflightResult> | ToolPreflightResult;
}
export interface ToolExecution<TInput = unknown, TOutput = unknown> {
    invoke: (input: TInput) => Promise<TOutput>;
    summarizeResult?: (result: TOutput) => string;
    executionMode?: ToolExecutionMode;
    executionTarget?: ToolExecutionTarget;
    timeoutMs?: number;
    recovery?: ToolRecoveryConfig<TInput>;
    exposeToLoop?: boolean;
    buildHostEffect?: (input: TInput, output: TOutput) => HostToolEffect | undefined;
}
export interface AgentTool<TInput = unknown, TOutput = unknown, TContext extends AgentUiContext = AgentUiContext> {
    name: string;
    title?: string;
    displayName?: string;
    description: string;
    category?: string;
    tags?: string[];
    inputSchema?: ToolInputSchema<TInput>;
    isAvailable?: (ctx: TContext) => boolean;
    invoke: (input: TInput) => Promise<TOutput>;
    executionMode?: ToolExecutionMode;
    executionTarget?: ToolExecutionTarget;
    timeoutMs?: number;
    summarizeResult?: (result: TOutput) => string;
    exposeToLoop?: boolean;
    buildHostEffect?: (input: TInput, output: TOutput) => HostToolEffect | undefined;
    requires?: string[];
    contextHint?: ToolContextHint;
    preflight?: (input: TInput, context: ToolPreflightContext<TContext>) => Promise<ToolPreflightResult> | ToolPreflightResult;
    recovery?: ToolRecoveryConfig<TInput>;
}
type AgentToolLegacyCompat<TInput = unknown, TOutput = unknown, TContext extends AgentUiContext = AgentUiContext> = Omit<Partial<AgentTool<TInput, TOutput, TContext>>, "invoke" | "isAvailable"> & {
    availability?: ToolAvailability<TInput, TContext>;
    execution?: ToolExecution<TInput, TOutput>;
    canRun?: (ctx: TContext) => boolean;
    run?: (input: TInput) => Promise<TOutput>;
};
export declare function registerTool<TInput = unknown, TOutput = unknown, TContext extends AgentUiContext = AgentUiContext>(tool: AgentTool<TInput, TOutput, TContext> | AgentToolLegacyCompat<TInput, TOutput, TContext>): void;
export declare function getTool(name: string): AgentTool<unknown, unknown> | undefined;
export declare function listTools(): AgentTool<unknown, unknown>[];
export declare function listLoopTools(): AgentTool<unknown, unknown>[];
export declare function getToolsByPrefix(prefix: string): AgentTool<unknown, unknown>[];
export declare function clearTools(): void;
export declare function getToolTitle(tool: AgentTool<unknown, unknown>): string;
export declare function getToolAvailabilityCheck<TInput = unknown>(tool: AgentTool<TInput, unknown>): (ctx: AgentUiContext) => boolean;
export declare function getToolRequirements(tool: AgentTool<unknown, unknown>): string[];
export declare function getToolContextHint(tool: AgentTool<unknown, unknown>): ToolContextHint | undefined;
export declare function getToolPreflight<TInput = unknown>(tool: AgentTool<TInput, unknown>): ((input: TInput, context: ToolPreflightContext<AgentUiContext>) => Promise<ToolPreflightResult> | ToolPreflightResult) | undefined;
export declare function getToolInvoker<TInput = unknown, TOutput = unknown>(tool: AgentTool<TInput, TOutput>): (input: TInput) => Promise<TOutput>;
export declare function getToolExecutionMode(tool: AgentTool<unknown, unknown>): ToolExecutionMode | undefined;
export declare function getToolExecutionTarget(tool: AgentTool<unknown, unknown>): ToolExecutionTarget;
export declare function getToolExposeToLoop(tool: AgentTool<unknown, unknown>): boolean;
export declare function getToolTimeoutMs(tool: AgentTool<unknown, unknown>): number | undefined;
export declare function getToolRecovery<TInput = unknown>(tool: AgentTool<TInput, unknown>): ToolRecoveryConfig<TInput> | undefined;
export declare function getToolResultSummarizer<TOutput = unknown>(tool: AgentTool<unknown, TOutput>): ((result: TOutput) => string) | undefined;
export declare function getToolHostEffectBuilder<TInput = unknown, TOutput = unknown>(tool: AgentTool<TInput, TOutput>): ((input: TInput, output: TOutput) => HostToolEffect | undefined) | undefined;
//# sourceMappingURL=agentRegistry.d.ts.map