import type { Static, TSchema } from "typebox";
export interface StructuredOutputCapture<T = unknown> {
    value: T | undefined;
    called: boolean;
}
export interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {
    schema: TSchemaDef;
    capture: StructuredOutputCapture<Static<TSchemaDef>>;
    name?: string;
}
/**
 * Structural tool shape understood by Pi's custom-tool API.
 *
 * Keeping this tiny contract local is intentional: `defineTool()` is an identity
 * helper, and importing it here made the Claude/Codex-only CLI load the entire Pi
 * SDK before it could even print `--help`.
 */
export interface StructuredOutputTool<TSchemaDef extends TSchema> {
    name: string;
    label: string;
    description: string;
    promptSnippet: string;
    promptGuidelines: string[];
    parameters: TSchemaDef;
    execute(toolCallId: string, params: Static<TSchemaDef>): Promise<{
        content: Array<{
            type: "text";
            text: string;
        }>;
        details: Static<TSchemaDef>;
        terminate: true;
    }>;
}
/**
 * Create a terminating tool that captures validated params as the subagent result.
 *
 * Pi validates `params` against `schema` before execute() is called. Returning
 * `terminate: true` lets the subagent finish on this tool call without paying for
 * an extra assistant follow-up turn.
 */
export declare function createStructuredOutputTool<TSchemaDef extends TSchema>({ schema, capture, name, }: StructuredOutputToolOptions<TSchemaDef>): StructuredOutputTool<TSchemaDef>;
/** A schema accepted by the CLI providers (JSON Schema/TypeBox compatible). */
export type StructuredOutputSchema = TSchema & {
    type?: string;
};
/** Ensure provider structured-output schemas are transport-safe top-level objects. */
export declare function assertTopLevelObjectSchema(schema: unknown, context?: string): asserts schema is StructuredOutputSchema;
/** Validate and TypeBox-convert a value, throwing a non-recoverable schema error. */
export declare function validateStructuredOutput<T = unknown>(value: unknown, schema: TSchema, context?: string): T;
/** Parse exactly one JSON value and validate it against a top-level object schema. */
export declare function parseStructuredOutput<T = unknown>(text: string, schema: TSchema, context?: string): T;
/**
 * Locate a JSON object in a model response. Fenced JSON is preferred, then the
 * first balanced object is considered. Strings and escapes are handled so braces
 * in prose or string values do not terminate extraction early.
 */
export declare function extractJsonObject(text: string): string | undefined;
/** Strictly extract and validate an object embedded in model prose. */
export declare function extractStructuredOutput<T = unknown>(text: string, schema: TSchema, context?: string): T;
/** Parse a provider result that may already be an object or may be JSON text. */
export declare function resolveStructuredOutput<T = unknown>(value: unknown, schema: TSchema, context?: string): T;