import { z } from 'zod';
import { ServerToolBuilder } from './tool.js';
import type { ToolCallContext, ToolNeedsApproval } from './types.js';
/**
 * One capability branch of a scoped tool: a named sub-tool with its own
 * input shape + handler. Authored either inline in {@link scopedTool}'s
 * `capabilities` map or via the {@link capability} helper (which preserves
 * per-branch input inference for the handler signature).
 */
export interface ScopedCapability<TInput extends z.ZodType = z.ZodType, TOutput = unknown, TUpdate = unknown> {
    /** Optional per-capability description, surfaced in the discriminator enum note. */
    description?: string;
    /** This branch's input schema. Validated in code before the handler runs. */
    input: TInput;
    /**
     * Branch handler. May be a plain async function (single return value) or
     * an `async function*` (yields `tool-update` chunks, returns the result) —
     * the same dual protocol `ToolBuilder.server` accepts.
     */
    handler: (input: z.infer<TInput>, ctx?: ToolCallContext) => TOutput | Promise<TOutput> | AsyncGenerator<TUpdate, TOutput, void>;
}
/**
 * Identity helper that infers a capability's input type at the definition
 * site, so its `handler` parameter is typed without an explicit annotation.
 *
 * @example
 * const web = capability({
 *   input: z.object({ query: z.string() }),
 *   handler: async ({ query }) => search(query), // `query` is `string`
 * })
 */
export declare function capability<TInput extends z.ZodType, TOutput, TUpdate = unknown>(spec: ScopedCapability<TInput, TOutput, TUpdate>): ScopedCapability<TInput, TOutput, TUpdate>;
export interface ScopedToolOptions {
    name: string;
    description: string;
    /** Discriminator field name added to the flat schema. Default `'sub_tool'`. */
    discriminator?: string;
    /** Named capability branches. Keys become the discriminator enum values. */
    capabilities: Record<string, ScopedCapability>;
    /**
     * Runtime allowlist — restrict callable capabilities to a subset of
     * `capabilities` keys (e.g. per-plan gating). Both the discriminator enum
     * and the runtime dispatch honor it. Defaults to every capability key.
     * Entries not present in `capabilities` throw at build time.
     */
    allow?: string[];
    /** Forwarded to the generated tool definition. */
    needsApproval?: ToolNeedsApproval | undefined;
}
/**
 * The shared flattening plan, computed once so the JSON-Schema render and the
 * runtime dispatch/validation cannot drift. Exported for adapters and tests.
 */
export interface FlatPlan {
    discriminator: string;
    /** Allowed discriminator values, in declaration order. */
    values: string[];
    /** Merged JSON-Schema properties (discriminator included). */
    properties: Record<string, unknown>;
    /** Top-level required = discriminator + fields required by EVERY branch. */
    required: string[];
    /** Per-capability required field names, for in-code validation before dispatch. */
    requiredByCapability: Record<string, string[]>;
    /** For each non-discriminator field, which capabilities reference it. */
    owners: Record<string, string[]>;
}
/** Error thrown by a scoped tool's dispatch before any handler runs. */
export declare class ScopedToolError extends Error {
    readonly name = "ScopedToolError";
    constructor(message: string);
}
/**
 * Collapse N capability branches into one flat function-call plan with a
 * discriminator enum. Function-calling APIs do not reliably honor a top-level
 * `oneOf`, so a discriminated union must flatten to a single object schema:
 * the union of all branches' fields, a top-level `required` containing only
 * fields required by EVERY branch, and per-branch requireds enforced in code.
 */
export declare function flattenCapabilities(capabilities: Record<string, ScopedCapability>, discriminator?: string, allow?: string[]): FlatPlan;
/**
 * Build a single function-call tool from a discriminated union of capability
 * branches. The branches collapse into one flat schema with a discriminator
 * enum (see {@link flattenCapabilities}); at call time the dispatch validates
 * the discriminator against the allowlist, validates the chosen branch's input
 * (enforcing its required fields), and runs that branch's handler.
 *
 * @example
 * const search = scopedTool({
 *   name: 'search',
 *   description: 'Run a search across one of several engines.',
 *   capabilities: {
 *     web:    capability({ input: z.object({ query: z.string() }),               handler: webSearch }),
 *     images: capability({ input: z.object({ query: z.string(), safe: z.boolean() }), handler: imageSearch }),
 *   },
 * })
 */
export declare function scopedTool(options: ScopedToolOptions): ServerToolBuilder<Record<string, unknown>, unknown>;
//# sourceMappingURL=scoped-tool.d.ts.map