import { Usage } from './usage';
import { StreamEvent } from './types/protocol';
import { HostedTool, ComputerTool, FunctionTool, ShellTool, ApplyPatchTool } from './tool';
import { Computer } from './computer';
import { Handoff } from './handoff';
import { AgentInputItem, AgentOutputItem, JsonSchemaDefinition, TextOutput, InputText, InputImage, InputFile } from './types';
export type ModelSettingsToolChoice = 'auto' | 'required' | 'none' | (string & {});
/**
 * Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
 * Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
 * Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
 */
export type ModelSettingsReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null;
/**
 * Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
 */
export type ModelSettingsReasoning = {
    /**
     * Controls which reasoning items are rendered back to the model on later turns.
     */
    context?: 'auto' | 'current_turn' | 'all_turns' | null;
    /**
     * Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
     * Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
     * Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
     */
    effort?: ModelSettingsReasoningEffort | null;
    /**
     * Controls the reasoning execution mode for the request.
     */
    mode?: 'standard' | 'pro' | (string & {});
    /**
     * A summary of the reasoning performed by the model.
     * This can be useful for debugging and understanding the model's reasoning process.
     * One of `auto`, `concise`, or `detailed`.
     */
    summary?: 'auto' | 'concise' | 'detailed' | null;
};
/**
 * Prompt-cache configuration for supported model providers.
 */
export type ModelSettingsPromptCacheOptions = {
    /**
     * Controls whether the provider creates an implicit cache breakpoint.
     */
    mode?: 'implicit' | 'explicit';
    /**
     * The minimum lifetime applied to cache breakpoints written by the request.
     */
    ttl?: '30m';
};
export interface ModelSettingsText {
    /**
     * Constrains the verbosity of the model's response.
     * Lower values will result in more concise responses, while higher values will result in more verbose responses.
     * Currently supported values are `low`, `medium`, and `high`.
     */
    verbosity?: 'low' | 'medium' | 'high' | null;
}
export type ModelSettingsContextManagement = Array<{
    /**
     * The context-management strategy to apply.
     */
    type: 'compaction' | (string & {});
    /**
     * Rendered-token threshold that triggers server-side compaction.
     */
    compactThreshold?: number;
    /**
     * Rendered-token threshold that triggers server-side compaction.
     */
    compact_threshold?: number;
    [key: string]: unknown;
}>;
export type RetryDecision = boolean | {
    /**
     * Whether the failed request should be retried.
     */
    retry: boolean;
    /**
     * Optional delay override in milliseconds before the next retry attempt.
     */
    delayMs?: number;
    /**
     * Optional explanation for logging or debugging.
     */
    reason?: string;
    /**
     * Explicit application approval to repeat provider-side work that may
     * already have happened. This is required when replay safety is unknown
     * or unsafe, including timed-out requests. Streamed requests remain
     * non-retryable after any output event is emitted.
     */
    approveUnsafeReplay?: boolean;
};
export type ModelRetryNormalizedError = {
    /**
     * HTTP status code when the provider exposes one.
     */
    statusCode?: number;
    /**
     * Suggested delay in milliseconds derived from retry-after style headers.
     */
    retryAfterMs?: number;
    /**
     * Provider or transport-specific error code when exposed.
     */
    errorCode?: string;
    /**
     * Whether the error appears to come from a transient transport or connectivity problem.
     */
    isNetworkError: boolean;
    /**
     * Whether the error was caused by an abort signal or abort exception.
     */
    isAbort: boolean;
};
export type ModelRetryAdvice = {
    /**
     * Optional provider recommendation for whether this error is retryable.
     * The runner still applies safety vetoes first and user policy remains the final authority.
     */
    suggested?: boolean;
    /**
     * Optional delay hint in milliseconds from the provider or transport layer.
     */
    retryAfterMs?: number;
    /**
     * Optional explanation for why the provider suggested or vetoed a retry.
     */
    reason?: string;
    /**
     * Provider confidence about whether replaying the request is safe.
     * Omit this field when replay safety is unknown.
     */
    replaySafety?: 'unsafe' | 'safe';
    /**
     * Whether the provider had begun emitting the response when the failure occurred.
     */
    responseStarted?: boolean;
    /**
     * Provider-supplied normalized facts that should override generic extraction when present.
     */
    normalized?: Partial<ModelRetryNormalizedError>;
};
export type RetryPolicyContext = {
    /**
     * The error thrown by the failed model attempt.
     */
    error: unknown;
    /**
     * The 1-based number of the failed attempt.
     */
    attempt: number;
    /**
     * The configured number of retries allowed after the initial attempt.
     */
    maxRetries: number;
    /**
     * Whether the failed request was streaming.
     */
    stream: boolean;
    /**
     * Optional provider guidance for the failure.
     */
    providerAdvice?: ModelRetryAdvice;
    /**
     * Generic normalized facts extracted from the error and provider advice.
     */
    normalized: ModelRetryNormalizedError;
    /**
     * The previous response identifier carried by the failed request, when present.
     */
    readonly previousResponseId?: string;
    /**
     * The conversation identifier carried by the failed request, when present.
     */
    readonly conversationId?: string;
    /**
     * Stable provider replay classification captured before the policy runs.
     * The runner always supplies this field; it is optional for compatibility
     * with code that constructs policy contexts directly.
     */
    readonly replaySafety?: 'safe' | 'unsafe' | 'unknown';
    /**
     * Stable response-start evidence captured before the policy runs.
     * The runner preserves `undefined` when the provider supplies no evidence.
     * The field is optional for compatibility with code that constructs policy
     * contexts directly.
     */
    readonly responseStarted?: boolean;
    /**
     * Whether the failed request carried a previous response or conversation identifier.
     * The runner always supplies this field; it is optional for compatibility
     * with code that constructs policy contexts directly.
     */
    readonly statefulRequest?: boolean;
};
export type RetryPolicy = (context: RetryPolicyContext) => RetryDecision | Promise<RetryDecision>;
export type ModelRetryBackoffSettings = {
    /**
     * Delay for the first retry in milliseconds.
     */
    initialDelayMs?: number;
    /**
     * Maximum delay between retries in milliseconds.
     */
    maxDelayMs?: number;
    /**
     * Multiplier applied after each retry attempt.
     */
    multiplier?: number;
    /**
     * Whether to apply jitter to the computed backoff delay.
     */
    jitter?: boolean;
};
export type ModelRetrySettings = {
    /**
     * Number of retries allowed after the initial model request.
     * Retries remain opt-in; no retries occur unless `policy` returns `true`.
     */
    maxRetries?: number;
    /**
     * Backoff configuration used when the retry policy requests a retry without returning an explicit delay.
     */
    backoff?: ModelRetryBackoffSettings;
    /**
     * Runtime-only retry policy. This callback is not serialized into persisted run state.
     */
    policy?: RetryPolicy;
};
/**
 * Settings to use when calling an LLM.
 *
 * This class holds optional model configuration parameters (e.g. temperature,
 * topP, penalties, truncation, etc.).
 *
 * Not all models/providers support all of these parameters, so please check the API documentation
 * for the specific model and provider you are using.
 */
export type ModelSettings = {
    /**
     * Cooperative timeout in milliseconds for each model call.
     * The timeout aborts only the current model call; a run-level abort signal
     * still cancels the entire run. Must be greater than 0 and less than or
     * equal to 2147483647 when provided.
     */
    timeoutMs?: number;
    /**
     * The temperature to use when calling the model.
     */
    temperature?: number;
    /**
     * The topP to use when calling the model.
     */
    topP?: number;
    /**
     * The frequency penalty to use when calling the model.
     */
    frequencyPenalty?: number;
    /**
     * The presence penalty to use when calling the model.
     */
    presencePenalty?: number;
    /**
     * The tool choice to use when calling the model.
     */
    toolChoice?: ModelSettingsToolChoice;
    /**
     * Whether to use parallel tool calls when calling the model.
     * Defaults to false if not provided.
     */
    parallelToolCalls?: boolean;
    /**
     * The truncation strategy to use when calling the model.
     */
    truncation?: 'auto' | 'disabled';
    /**
     * The maximum number of output tokens to generate.
     */
    maxTokens?: number;
    /**
     * Whether to store the generated model response for later retrieval.
     * Defaults to true if not provided.
     */
    store?: boolean;
    /**
     * Enables prompt caching and controls how long cached content should be retained by the model provider.
     * See https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention for the available options.
     */
    promptCacheRetention?: 'in-memory' | '24h' | null;
    /**
     * Controls implicit and explicit prompt caching for supported model providers.
     */
    promptCacheOptions?: ModelSettingsPromptCacheOptions;
    /**
     * Context-management strategies to apply when calling the model.
     * This setting is available on OpenAI Responses requests, including server-side compaction.
     * See https://developers.openai.com/api/docs/guides/compaction.
     */
    contextManagement?: ModelSettingsContextManagement;
    /**
     * The reasoning settings to use when calling the model.
     */
    reasoning?: ModelSettingsReasoning;
    /**
     * The text settings to use when calling the model.
     */
    text?: ModelSettingsText;
    /**
     * Additional provider specific settings to be passed directly to the model
     * request.
     */
    providerData?: Record<string, any>;
    /**
     * Runtime-only retry configuration for the model request.
     */
    retry?: ModelRetrySettings;
    /**
     * Whether to preserve a JSON-compatible snapshot of provider usage before
     * the Agents SDK normalizes it. Defaults to false if not provided.
     */
    preserveRawUsage?: boolean;
};
export type ModelTracing = boolean | 'enabled_without_data';
export type SerializedFunctionTool = {
    /**
     * The type of the tool.
     */
    type: FunctionTool['type'];
    /**
     * The name of the tool.
     */
    name: FunctionTool['name'];
    /**
     * The description of the tool that helps the model to understand when to use the tool
     */
    description: FunctionTool['description'];
    /**
     * A JSON schema describing the parameters of the tool.
     */
    parameters: FunctionTool['parameters'];
    /**
     * Whether the tool is strict. If true, the model must try to strictly follow the schema
     * (might result in slower response times).
     */
    strict: FunctionTool['strict'];
    /**
     * Responses API only. Whether a top-level function tool stays hidden until tool search loads it.
     */
    deferLoading?: FunctionTool['deferLoading'];
    /**
     * Additional provider-specific metadata forwarded with the function tool definition.
     */
    providerData?: FunctionTool['providerData'];
    /**
     * Responses API only. Execution contexts allowed to invoke the function.
     */
    allowedCallers?: FunctionTool['allowedCallers'];
    /**
     * Responses API only. Schema for the JSON value encoded in string outputs.
     */
    outputSchema?: FunctionTool['outputSchema'];
    /**
     * Responses API only. Explicit namespace used to group related function tools.
     */
    namespace?: string;
    /**
     * Responses API only. Description shared by all tools in the namespace. Required when namespace is set.
     */
    namespaceDescription?: string;
};
export type SerializedComputerTool = {
    type: ComputerTool['type'];
    name: ComputerTool['name'];
    environment?: Computer['environment'];
    dimensions?: Computer['dimensions'];
};
export type SerializedShellTool = {
    type: ShellTool['type'];
    name: ShellTool['name'];
    environment?: ShellTool['environment'];
    allowedCallers?: ShellTool['allowedCallers'];
};
export type SerializedApplyPatchTool = {
    type: ApplyPatchTool['type'];
    name: ApplyPatchTool['name'];
    allowedCallers?: ApplyPatchTool['allowedCallers'];
};
export type SerializedHostedTool = {
    type: HostedTool['type'];
    name: HostedTool['name'];
    providerData?: HostedTool['providerData'];
};
export type SerializedTool = SerializedFunctionTool | SerializedComputerTool | SerializedShellTool | SerializedApplyPatchTool | SerializedHostedTool;
export type SerializedHandoff = {
    /**
     * The name of the tool that represents the handoff.
     */
    toolName: Handoff['toolName'];
    /**
     * The tool description for the handoff
     */
    toolDescription: Handoff['toolDescription'];
    /**
     * The JSON schema for the handoff input. Can be empty if the handoff does not take an input
     */
    inputJsonSchema: Handoff['inputJsonSchema'];
    /**
     * Whether the input JSON schema is in strict mode. We strongly recommend setting this to true,
     * as it increases the likelihood of correct JSON input.
     */
    strictJsonSchema: Handoff['strictJsonSchema'];
};
/**
 * The output type passed to the model. Has any Zod types serialized to JSON Schema
 */
export type SerializedOutputType = JsonSchemaDefinition | TextOutput;
/**
 * A request to a large language model.
 */
export type ModelRequest = {
    /**
     * The system instructions to use for the model.
     */
    systemInstructions?: string;
    /**
     * The input to the model.
     */
    input: string | AgentInputItem[];
    /**
     * The ID of the previous response to use for the model.
     */
    previousResponseId?: string;
    /**
     * The ID of stored conversation to use for the model.
     *
     * see https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#openai-apis-for-conversation-state
     * see https://platform.openai.com/docs/api-reference/conversations/create
     */
    conversationId?: string;
    /**
     * The model settings to use for the model.
     */
    modelSettings: ModelSettings;
    /**
     * The tools to use for the model.
     */
    tools: SerializedTool[];
    /**
     * When true, the caller explicitly configured the tools list (even if empty).
     * Providers can use this to avoid overwriting prompt-defined tools when an agent
     * does not specify its own tools.
     */
    toolsExplicitlyProvided?: boolean;
    /**
     * The type of the output to use for the model.
     */
    outputType: SerializedOutputType;
    /**
     * The handoffs to use for the model.
     */
    handoffs: SerializedHandoff[];
    /**
     * Whether to enable tracing for the model.
     */
    tracing: ModelTracing;
    /**
     * An optional signal to abort the model request.
     */
    signal?: AbortSignal;
    /**
     * The prompt template to use for the model, if any.
     */
    prompt?: Prompt;
    /**
     * When true, the resolved model should override the model configured in the prompt template.
     * Providers that support prompt templates should include the explicit model name in the request
     * even when a prompt is supplied.
     */
    overridePromptModel?: boolean;
};
export type ModelRetryAdviceRequest = {
    /**
     * The failed request that is being evaluated for replay.
     */
    request: ModelRequest;
    /**
     * The error thrown by the failed attempt.
     */
    error: unknown;
    /**
     * Whether the failed request used streaming.
     */
    stream: boolean;
    /**
     * The 1-based number of the failed attempt.
     */
    attempt: number;
};
export type ModelResponse = {
    /**
     * The usage information for response.
     */
    usage: Usage;
    /**
     * A list of outputs (messages, tool calls, etc.) generated by the model.
     */
    output: AgentOutputItem[];
    /**
     * An ID for the response which can be used to refer to the response in subsequent calls to the
     * model. Not supported by all model providers.
     */
    responseId?: string;
    /**
     * The transport request ID for this model call, if provided by the model SDK or transport.
     */
    requestId?: string;
    /**
     * Raw response data from the underlying model provider.
     */
    providerData?: Record<string, any>;
    /**
     * A detached JSON-compatible snapshot of provider usage captured before
     * the Agents SDK normalizes missing values. Only populated when requested.
     */
    rawUsage?: Record<string, unknown>;
};
/**
 * The base interface for calling an LLM.
 */
export interface Model {
    /**
     * Whether this adapter lets a supplied prompt select the model unless
     * `overridePromptModel` is true. Defaults to false when omitted.
     * The Runner omits implicit model settings when such a prompt owns selection.
     */
    readonly supportsPromptModelSelection?: boolean;
    /**
     * Get a response from the model.
     *
     * @param request - The request to get a response for.
     */
    getResponse(request: ModelRequest): Promise<ModelResponse>;
    /**
     * Get a streamed response from the model.
     *
     */
    getStreamedResponse(request: ModelRequest): AsyncIterable<StreamEvent>;
    /**
     * Provide optional retry advice for a failed request.
     */
    getRetryAdvice?(args: ModelRetryAdviceRequest): Promise<ModelRetryAdvice | undefined> | ModelRetryAdvice | undefined;
}
/**
 * The base interface for a model provider.
 *
 * The model provider is responsible for looking up `Model` instances by name.
 */
export interface ModelProvider {
    /**
     * Get a model by name
     *
     * @param modelName - The name of the model to get.
     */
    getModel(modelName?: string): Promise<Model> | Model;
}
/**
 * Reference to a prompt template and its variables.
 */
export type Prompt = {
    /**
     * The unique identifier of the prompt template to use.
     */
    promptId: string;
    /**
     * Optional version of the prompt template.
     */
    version?: string;
    /**
     * Optional variables to substitute into the prompt template.
     * Can be a string, or an object with string keys and values that are string,
     * InputText, InputImage, or InputFile.
     */
    variables?: {
        [key: string]: string | InputText | InputImage | InputFile;
    };
};