import type { z } from 'zod';
/** Header Kazzle sets on every dispatched app-tool HTTP request. Source of truth: shared/tools/tool-invocation.types.ts */
export declare const TOOL_CONTEXT_HEADER = "Kazzle-Tool-Context";
export declare const ToolInvocationSource: {
    readonly THREAD: 'thread';
    readonly API: 'api';
};
export type ToolInvocationSource = typeof ToolInvocationSource[keyof typeof ToolInvocationSource];
/** How this tool call was invoked — thread (AI / resume) vs Tools API. */
export type ToolInvocationContext = {
    source: typeof ToolInvocationSource.THREAD;
    threadId: string;
} | {
    source: typeof ToolInvocationSource.API;
};
/**
 * Read `Kazzle-Tool-Context` from an incoming tool handler request.
 * Throws when the header is missing or malformed — only Kazzle dispatch should call the route.
 */
export declare function toolContext(req: Request): ToolInvocationContext;
export declare function isThreadToolInvocation(context: ToolInvocationContext): context is Extract<ToolInvocationContext, {
    source: typeof ToolInvocationSource.THREAD;
}>;
/** Zod schema for a tool's input object. Use .default(), .optional(), .transform(), etc. */
export type KazzleToolInputSchema = z.ZodType<Record<string, unknown>>;
export type ToolRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
export interface ToolRequestSpec {
    method: ToolRequestMethod;
    query?: Record<string, string>;
    headers?: Record<string, string>;
    body?: unknown;
}
/**
 * Native client-device tools that an app may reference.
 *
 * Adding one requires the matching definition in `server/tools/client-device`,
 * this SDK name, and coverage in the native-tool catalog drift test.
 */
export declare const NativeToolName: {
    readonly HEALTH: 'health';
};
export type NativeToolName = typeof NativeToolName[keyof typeof NativeToolName];
export type KazzleTarget = ({
    type: 'app';
    component: string;
    path: string;
} & ToolRequestSpec) | ({
    type: 'url';
    url: string;
} & ToolRequestSpec) | {
    type: 'kazzle';
    name: NativeToolName;
};
export interface ToolActionButtonElement {
    type: 'button';
    id: string;
    label: string;
    input?: Record<string, unknown>;
    target?: KazzleTarget;
    /**
     * Button styling. The single 'primary' button (or the last button when none is
     * marked) is placed rightmost and bound to Cmd/Ctrl+Enter. 'destructive' styles
     * dangerous actions. You never declare a cancel button — the framework adds a
     * default negative (Skip/Cancel, bound to Esc) in the bottom-left automatically.
     */
    variant?: 'primary' | 'secondary' | 'destructive';
}
/**
 * A required-action card element. Only buttons are rendered today; this stays a
 * union so form controls can be added later alongside their renderer.
 */
export type ToolActionElement = ToolActionButtonElement;
export interface ToolActionAssignee {
    computerId?: string;
    userId?: string;
}
export interface ToolActionSpec {
    title: string;
    description?: string;
    elements: ToolActionElement[];
    assignee?: ToolActionAssignee;
    timeoutMs?: number;
}
export interface KazzleRequiredAction {
    type: 'action_required';
    title: string;
    description?: string;
    elements: ToolActionElement[];
    assignee?: ToolActionAssignee;
    timeoutMs?: number;
}
interface KazzleToolBase {
    /** Provider-safe identifier: letters, numbers, underscores, or hyphens. */
    name: string;
    /** Friendly title shown in chat cards, e.g. "Save bookmark". */
    displayName: string;
    /** AI-facing description for when to call this tool. */
    description: string;
}
interface KazzleModeledToolBase extends KazzleToolBase {
    /** Zod schema for tool input. Use .default(), .optional(), .transform(), etc. here. */
    input: KazzleToolInputSchema;
    /** Addressing and HTTP request shape for dispatch. */
    target: KazzleTarget;
}
/** A tool served by one of this app's own components. */
export interface KazzleAppTool extends KazzleModeledToolBase {
    target: Extract<KazzleTarget, {
        type: 'app';
    }>;
}
/** A tool served by an external publisher-hosted HTTP endpoint. */
export interface KazzleUrlTool extends KazzleModeledToolBase {
    target: Extract<KazzleTarget, {
        type: 'url';
    }>;
}
/** A name-only reference to a platform/native tool resolved from the code registry. */
export interface KazzleNativeTool extends KazzleToolBase {
    target: Extract<KazzleTarget, {
        type: 'kazzle';
    }>;
}
export type KazzleTool = KazzleAppTool | KazzleUrlTool | KazzleNativeTool;
/** Type-safe tools helper. Use: export const tools = defineTools([...]) */
export declare function defineTools<T extends readonly KazzleTool[]>(tools: T): T;
export {};