import type { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
import type { ImageSanitizationLimits } from "../image-sanitization.js";
export type AnyAgentTool = AgentTool<any, unknown> & {
    ownerOnly?: boolean;
    /**
     * Optional runtime availability check. If defined and returns `false`,
     * the tool is filtered out of the agent's palette before the LLM ever
     * sees it — preventing wasted turns on tools that can't actually run
     * (e.g., a search tool with no API key configured).
     *
     * **Defensive design rules**:
     * - Default behavior (when not defined) is "always available" — tools
     *   without checkFn are NEVER filtered. Existing tools keep working
     *   exactly as before.
     * - When implementing checkFn, only return `false` if the tool is
     *   CERTAIN to fail. When uncertain, return `true` and let the agent
     *   try — better to surface the real error than to wrongly hide a
     *   working tool.
     * - For multi-credential tools (e.g., web_search has 4 providers),
     *   return `true` if ANY credential path is available.
     * - The user can bypass all checkFn filtering by setting the env var
     *   `SYMI_FORCE_ALL_TOOLS=1` — useful when our check is wrong and
     *   the user knows their setup works.
     */
    checkFn?: () => boolean;
    /**
     * Optional declarative list of env var names this tool may use. Pure
     * metadata — the gateway uses it to answer "Why isn't tool X
     * available?" by listing which env vars would enable it. Not consumed
     * for actual gating (that's checkFn's job). When the tool accepts
     * credentials from multiple sources (env, config, profile store),
     * list every env var name it ever consults.
     */
    requiredEnv?: readonly string[];
};
export type StringParamOptions = {
    required?: boolean;
    trim?: boolean;
    label?: string;
    allowEmpty?: boolean;
};
export type ActionGate<T extends Record<string, boolean | undefined>> = (key: keyof T, defaultValue?: boolean) => boolean;
export declare const OWNER_ONLY_TOOL_ERROR = "Tool restricted to owner senders.";
export declare class ToolInputError extends Error {
    readonly status: number;
    constructor(message: string);
}
export declare class ToolAuthorizationError extends ToolInputError {
    readonly status = 403;
    constructor(message: string);
}
export declare function createActionGate<T extends Record<string, boolean | undefined>>(actions: T | undefined): ActionGate<T>;
export declare function readStringParam(params: Record<string, unknown>, key: string, options: StringParamOptions & {
    required: true;
}): string;
export declare function readStringParam(params: Record<string, unknown>, key: string, options?: StringParamOptions): string | undefined;
export declare function readStringOrNumberParam(params: Record<string, unknown>, key: string, options?: {
    required?: boolean;
    label?: string;
}): string | undefined;
export declare function readNumberParam(params: Record<string, unknown>, key: string, options?: {
    required?: boolean;
    label?: string;
    integer?: boolean;
}): number | undefined;
export declare function readStringArrayParam(params: Record<string, unknown>, key: string, options: StringParamOptions & {
    required: true;
}): string[];
export declare function readStringArrayParam(params: Record<string, unknown>, key: string, options?: StringParamOptions): string[] | undefined;
export type ReactionParams = {
    emoji: string;
    remove: boolean;
    isEmpty: boolean;
};
export declare function readReactionParams(params: Record<string, unknown>, options: {
    emojiKey?: string;
    removeKey?: string;
    removeErrorMessage: string;
}): ReactionParams;
export declare function jsonResult(payload: unknown): AgentToolResult<unknown>;
export declare function wrapOwnerOnlyToolExecution(tool: AnyAgentTool, senderIsOwner: boolean): AnyAgentTool;
export declare function imageResult(params: {
    label: string;
    path: string;
    base64: string;
    mimeType: string;
    extraText?: string;
    details?: Record<string, unknown>;
    imageSanitization?: ImageSanitizationLimits;
}): Promise<AgentToolResult<unknown>>;
export declare function imageResultFromFile(params: {
    label: string;
    path: string;
    extraText?: string;
    details?: Record<string, unknown>;
    imageSanitization?: ImageSanitizationLimits;
}): Promise<AgentToolResult<unknown>>;
export type AvailableTag = {
    id?: string;
    name: string;
    moderated?: boolean;
    emoji_id?: string | null;
    emoji_name?: string | null;
};
/**
 * Validate and parse an `availableTags` parameter from untrusted input.
 * Returns `undefined` when the value is missing or not an array.
 * Entries that lack a string `name` are silently dropped.
 */
export declare function parseAvailableTags(raw: unknown): AvailableTag[] | undefined;
