import type { Files } from "../index.js";
import type { ApprovalConfig } from "../internal/ai-tools/approval.js";
import type { FileReadToolName, FileToolName, FileWriteToolName } from "../internal/ai-tools/schemas.js";
import type { ResponsesToolOverrides } from "./types.js";
/**
 * A function-tool definition shaped for OpenAI's Responses API. Pass an
 * array of these to `openai.responses.create({ tools })`.
 */
export interface ResponsesFunctionTool {
    type: "function";
    name: string;
    description: string;
    parameters: Record<string, unknown>;
    strict: boolean;
}
/**
 * A function call emitted by the Responses API in `response.output[]`.
 */
export interface FunctionCallItem {
    type: "function_call";
    call_id: string;
    name: string;
    arguments: string;
}
/**
 * A function-call output item to append to the next `responses.create`
 * input alongside the original `function_call` item.
 */
export interface FunctionCallOutputItem {
    type: "function_call_output";
    call_id: string;
    output: string;
}
export interface ResponsesFileTools {
    /**
     * Function tool definitions. Pass directly to
     * `openai.responses.create({ tools })`.
     */
    definitions: ResponsesFunctionTool[];
    /**
     * Execute a `function_call` item from the model's `response.output[]`.
     * Looks up the matching tool by name, parses and validates `arguments`,
     * runs the underlying `Files` operation, and returns a
     * `function_call_output` item ready to push into the next turn's input.
     *
     * `JSON.parse` failures and Zod validation errors are returned **as the
     * tool's output** so the model can self-correct on the next turn.
     * `FilesError` from the underlying SDK is rethrown — the caller decides
     * how to surface it.
     *
     * Approval is **not** enforced. Check {@link needsApproval} first if you
     * want a human-in-the-loop gate.
     */
    execute(call: FunctionCallItem): Promise<FunctionCallOutputItem>;
    /**
     * Returns whether the named tool is approval-gated under this config.
     * Read tools always return `false`. Unknown names return `false`.
     */
    needsApproval(name: string): boolean;
}
export interface ResponsesFileToolsOptions {
    /**
     * The configured `Files` instance the tools will operate against.
     */
    files: Files;
    /**
     * When `true`, write tools (`uploadFile`, `deleteFile`, `copyFile`,
     * `signUploadUrl`) are omitted from `definitions` and rejected by
     * `execute`. The model cannot mutate the bucket regardless of approval
     * configuration.
     */
    readOnly?: boolean;
    /**
     * Approval gating reflected by {@link ResponsesFileTools.needsApproval}.
     * Defaults to `true` (every write reports as approval-required). Pass
     * `false` to disable, or an object keyed by write-tool name for
     * fine-grained control. Unspecified entries in the object form default
     * to `true`.
     */
    requireApproval?: ApprovalConfig;
    /**
     * Per-tool overrides for the OpenAI tool definition (`description`,
     * `strict`). `name`, `parameters`, and `type` cannot be overridden.
     */
    overrides?: Partial<Record<FileToolName, ResponsesToolOverrides>>;
}
/**
 * Create a set of files-sdk tools shaped for OpenAI's Responses API
 * (`openai.responses.create`).
 *
 * @example
 * ```ts
 * import OpenAI from "openai";
 * import { Files } from "files-sdk";
 * import { s3 } from "files-sdk/s3";
 * import { createResponsesFileTools } from "files-sdk/openai";
 *
 * const client = new OpenAI();
 * const files = new Files({ adapter: s3({ bucket: "uploads" }) });
 * const ft = createResponsesFileTools({ files });
 *
 * const input: any[] = [{ role: "user", content: "List my files." }];
 * while (true) {
 *   const res = await client.responses.create({
 *     model: "gpt-4.1",
 *     input,
 *     tools: ft.definitions,
 *   });
 *   const calls = res.output.filter((o) => o.type === "function_call");
 *   if (calls.length === 0) break;
 *   for (const call of calls) {
 *     if (ft.needsApproval(call.name)) {
 *       // surface approval UX, then continue or break
 *     }
 *     input.push(call, await ft.execute(call));
 *   }
 * }
 * ```
 */
export declare const createResponsesFileTools: ({ files, readOnly, requireApproval, overrides, }: ResponsesFileToolsOptions) => ResponsesFileTools;
export type { FileReadToolName, FileToolName, FileWriteToolName };
//# sourceMappingURL=responses.d.ts.map