import * as z from 'zod';
/**
 * Schema-only tool definition that can be shared between server and clients.
 * Contains all the type information but no implementation.
 */
export interface ToolDefinition<ToolName extends string = string, ArgumentsSchema extends z.ZodType = z.ZodType, ServerPrepareResultSchema extends z.ZodType | undefined = undefined, ResponseSchema extends z.ZodType | undefined = undefined> {
    /** Unique name of the tool (used by the model to call it) */
    name: ToolName;
    /** Clear description of the tool's purpose and usage */
    description: string;
    /** Zod schema for the tool's arguments that the model should generate */
    argumentsSchema: ArgumentsSchema;
    /** Zod schema for server-side preparation result (for client tools that need server augmentation) */
    serverPrepareResultSchema?: ServerPrepareResultSchema;
    /** Zod schema for the tool's response */
    responseSchema?: ResponseSchema;
    /**
     * When set, the server intercepts the first call to this tool and returns
     * this string as a warning instead of forwarding to the client. The agent
     * must call the tool a second time to actually execute it.
     * Use this for irreversible/terminal tools that need a confirmation gate.
     */
    terminalConfirmation?: string;
    /**
     * When set, the server clips this tool's output to at most this many
     * characters before sending it to the model on the next turn, replacing
     * anything over the cap with a text variant plus an explanatory marker.
     * Use this for tools whose response size is not bounded by the schema —
     * e.g. arbitrary client-executed JavaScript that could return raw DOM.
     * Omit (undefined) to leave the tool's output untouched.
     */
    maxOutputChars?: number;
}
export type AnyToolDefinition = ToolDefinition<string, z.ZodType, z.ZodType | undefined, z.ZodType | undefined>;
/**
 * Type helper for tool execute functions.
 * For tools with serverPrepareResultSchema, combines argumentsSchema with serverPrepareResultSchema.
 * For tools without serverPrepareResultSchema, just uses argumentsSchema.
 */
export type ExecuteInput<T extends AnyToolDefinition> = Extract<T['serverPrepareResultSchema'], z.ZodType> extends never ? z.infer<T['argumentsSchema']> : z.infer<T['argumentsSchema']> & z.infer<Extract<T['serverPrepareResultSchema'], z.ZodType>>;
/**
 * Extract the tool name literal type from a ToolDefinition.
 */
export type ToolName<T extends AnyToolDefinition> = T['name'];
/**
 * Extract the arguments type (z.infer of argumentsSchema).
 */
export type ToolArguments<T extends AnyToolDefinition> = z.infer<T['argumentsSchema']>;
/**
 * Extract the server prepare result type (z.infer of serverPrepareResultSchema, or never if not present).
 * Uses Extract to defeat TypeScript's type narrowing with optional schema properties.
 */
export type ToolServerPrepareResult<T extends AnyToolDefinition> = Extract<T['serverPrepareResultSchema'], z.ZodType> extends never ? never : z.infer<Extract<T['serverPrepareResultSchema'], z.ZodType>>;
/**
 * Extract the response/output type (z.infer of responseSchema, or unknown if not present).
 * Uses Extract to defeat TypeScript's type narrowing with optional schema properties.
 */
export type ExecuteOutput<T extends AnyToolDefinition> = Extract<T['responseSchema'], z.ZodType> extends never ? unknown : z.infer<Extract<T['responseSchema'], z.ZodType>>;
/**
 * Factory function to create a type-safe ToolDefinition.
 */
export declare function defineTool<ToolName extends string, ArgumentsSchema extends z.ZodType, ServerPrepareResultSchema extends z.ZodType | undefined = undefined, ResponseSchema extends z.ZodType | undefined = undefined>(definition: ToolDefinition<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema>): ToolDefinition<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema>;
/**
 * The result returned by a tool's execute function.
 * Supports both simple JSON/text responses and rich content items (e.g., images).
 */
export interface ToolResult<ResponseSchema extends z.ZodType | undefined = undefined> {
    /**
     * The primary tool response (JSON or text)
     * If a response schema is provided, the tool response is expected to match the schema.
     * If a response schema is not provided, any response is allowed.
     */
    toolResponse: ResponseSchema extends z.ZodType ? z.infer<ResponseSchema> : unknown;
    /** Optional images to include in the tool output (separate from the JSON response) */
    imageContentItems?: ImageContent[];
}
/**
 * A tool that executes on the client. This is a base type for all client-side tools.
 */
export interface ClientTool<ToolName extends string = string, ArgumentsSchema extends z.ZodType = z.ZodType, ServerPrepareResultSchema extends z.ZodType | undefined = undefined, ResponseSchema extends z.ZodType | undefined = undefined> {
    definition: ToolDefinition<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema>;
    executor: 'client';
}
/**
 * A tool that executes entirely on the server.
 */
export interface ServerTool<ToolName extends string = string, ArgumentsSchema extends z.ZodType = z.ZodType, ResponseSchema extends z.ZodType | undefined = undefined> {
    definition: ToolDefinition<ToolName, ArgumentsSchema, undefined, ResponseSchema>;
    executor: 'server';
}
/**
 * A tool that executes entirely on the server.
 */
export interface ImplementedServerTool<ToolName extends string = string, ArgumentsSchema extends z.ZodType = z.ZodType, ToolContext = unknown, ResponseSchema extends z.ZodType | undefined = undefined> extends ServerTool<ToolName, ArgumentsSchema, ResponseSchema> {
    execute: (params: z.infer<ArgumentsSchema>, context: ToolContext) => Promise<ToolResult<ResponseSchema>>;
}
/**
 * A tool that executes entirely on the client. These won't be created in
 * server-agents, but rather in client code like the mabl-cli. server-agents just needs
 * to know the schema, executor, and optionally a serverPrepare function, so it should
 * use {@link PreparedClientTool} or {@link ClientTool}.
 */
export interface ImplementedClientTool<ToolName extends string = string, ArgumentsSchema extends z.ZodType = z.ZodType, ServerPrepareResultSchema extends z.ZodType | undefined = undefined, ResponseSchema extends z.ZodType | undefined = undefined, ToolContext = unknown> extends ClientTool<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema> {
    execute: (params: ExecuteInput<ToolDefinition<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema>>, context: ToolContext) => Promise<ToolResult<ResponseSchema>>;
}
/**
 * A client-side tool that requires server-side preparation before client execution.
 * The serverPrepare function augments the model's arguments with server-computed data.
 */
export interface PreparedClientTool<ToolName extends string = string, ArgumentsSchema extends z.ZodType = z.ZodType, ServerPrepareResultSchema extends z.ZodType = z.ZodType, ServerContext = unknown, ResponseSchema extends z.ZodType | undefined = undefined> extends ClientTool<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema> {
    serverPrepare: (params: z.infer<ArgumentsSchema>, context: ServerContext) => Promise<{
        success: true;
        serverResult: z.infer<ServerPrepareResultSchema>;
    } | {
        success: false;
        errorMessage: string;
    }>;
}
/**
 * A pure client-side tool with no server-side logic.
 * The server just passes the tool call to the client for execution.
 */
export interface PureClientTool<ToolName extends string = string, ArgumentsSchema extends z.ZodType = z.ZodType, ResponseSchema extends z.ZodType | undefined = undefined> extends ClientTool<ToolName, ArgumentsSchema, undefined, ResponseSchema> {
    serverPrepare?: undefined;
}
/**
 * Union type of all tool definitions that can be used in server-agents.
 * Uses `any` for context types to allow flexible tool registration while maintaining
 * type safety for the tool-specific properties.
 *
 * In server-agents, when we call an LLM and execute the function calling loop, the only tool types
 * we should be passing are
 * - server tools that should always have their execute() function, and
 * - pure client tools, no execute() function because that exists on the client side.
 * - prepared client tools, no execute() function, but they have a serverPrepare() function that should be called before the server returns its response
 */
export type ServerAgentsTool = ImplementedServerTool<string, z.ZodType, any, z.ZodType | undefined> | PureClientTool<string, z.ZodType, z.ZodType | undefined> | PreparedClientTool<string, z.ZodType, z.ZodType, any, z.ZodType | undefined>;
/**
 * Creates a server-side tool from a definition and execute function.
 */
export declare function implementServerTool<ToolName extends string, ArgumentsSchema extends z.ZodType, ToolContext, ResponseSchema extends z.ZodType | undefined = undefined>(definition: ToolDefinition<ToolName, ArgumentsSchema, undefined, ResponseSchema>, execute: (params: z.infer<ArgumentsSchema>, context: ToolContext) => Promise<ToolResult<ResponseSchema>>): ImplementedServerTool<ToolName, ArgumentsSchema, ToolContext, ResponseSchema>;
/**
 * Creates a client-side tool from a definition and execute function.
 */
export declare function implementClientTool<ToolName extends string, ArgumentsSchema extends z.ZodType, ServerPrepareResultSchema extends z.ZodType | undefined, ToolContext, ResponseSchema extends z.ZodType | undefined = undefined>(definition: ToolDefinition<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema>, execute: (params: ExecuteInput<ToolDefinition<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema>>, context: ToolContext) => Promise<ToolResult<ResponseSchema>>): ImplementedClientTool<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema, ToolContext>;
/**
 * Creates a client-side tool with server preparation from a definition and serverPrepare function.
 */
export declare function prepareClientTool<ToolName extends string, ArgumentsSchema extends z.ZodType, ServerPrepareResultSchema extends z.ZodType, ServerContext, ResponseSchema extends z.ZodType | undefined = undefined>(definition: ToolDefinition<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ResponseSchema>, serverPrepare: (params: z.infer<ArgumentsSchema>, context: ServerContext) => Promise<{
    success: true;
    serverResult: z.infer<ServerPrepareResultSchema>;
} | {
    success: false;
    errorMessage: string;
}>): PreparedClientTool<ToolName, ArgumentsSchema, ServerPrepareResultSchema, ServerContext, ResponseSchema>;
/**
 * Creates a client-side tool from a definition. This has no server-side preparation and no
 * execution logic. It's only used in the tool looping code so that the client tool definitions
 * are available to the models.
 */
export declare function createClientTool<ToolName extends string, ArgumentsSchema extends z.ZodType, ResponseSchema extends z.ZodType | undefined = undefined>(definition: ToolDefinition<ToolName, ArgumentsSchema, undefined, ResponseSchema>): ClientTool<ToolName, ArgumentsSchema, undefined, ResponseSchema>;
/**
 * Type guard to check if a tool is a server-side tool.
 */
export declare function isServerTool(tool: ServerAgentsTool): tool is ImplementedServerTool;
/**
 * Type guard to check if a tool is a client-side tool with server preparation.
 */
export declare function isPreparedClientTool(tool: ServerAgentsTool): tool is PreparedClientTool;
/**
 * Type guard to check if a tool is a pure client-side tool without server preparation.
 */
export declare function isPureClientSideTool(tool: ServerAgentsTool): tool is PureClientTool;
/** Base64-encoded image data */
export interface ImageDataContent {
    type: 'image-data';
    image_data: string;
    media_type: string;
}
/** Image referenced by URL */
export interface ImageUrlContent {
    type: 'image-url';
    image_url: string;
    media_type?: string;
}
/** Image content that can be returned by tools */
export type ImageContent = ImageDataContent | ImageUrlContent;
//# sourceMappingURL=toolDefinition.d.ts.map