@velum-labs/routekit-gateway 0.9.0

package/dist/adapters/responses.d.ts

@@ -0,0 +1,174 @@
+/**
+ * OpenAI Responses adapter. Codex speaks the Responses API exclusively
+ * (`wire_api="responses"`; Chat Completions support was removed), so to back it
+ * with a local model we translate `/v1/responses` to and from the gateway's
+ * OpenAI Chat Completions core. The pure translation functions are exported for
+ * testing; the handler returns a `Response` the server pipes (JSON or SSE).
+ *
+ * This is the highest-fidelity adapter: it maps Responses `input` items
+ * (messages, function calls, function-call outputs) into chat messages, and
+ * emits the Responses streaming event sequence (`response.created`,
+ * `response.output_item.added`, `response.output_text.delta`,
+ * `response.function_call_arguments.delta`, `response.completed`, …) from chat
+ * completion chunks.
+ */
+import type { Backend, BackendRequestOptions } from "../backend.js";
+import { type OpenAiChoice } from "./openai-chat-wire.js";
+import type { ExecutedSearch } from "./server-tool-loop.js";
+export { openAiSseToResponses } from "./responses-stream.js";
+type ResponsesContentPart = {
+    type: string;
+    text?: string;
+    image_url?: string;
+    [key: string]: unknown;
+};
+type ResponsesInputItem = {
+    type?: "message";
+    role: "user" | "assistant" | "system" | "developer";
+    content: string | ResponsesContentPart[];
+} | {
+    type: "function_call";
+    call_id?: string;
+    id?: string;
+    name: string;
+    arguments: string;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    output: unknown;
+} | {
+    type: "custom_tool_call";
+    call_id?: string;
+    id?: string;
+    name: string;
+    input?: string;
+} | {
+    type: "custom_tool_call_output";
+    call_id: string;
+    output: unknown;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+/** A tool declaration on a Responses request: a function tool (JSON-schema
+ *  `parameters`), a freeform "custom" tool (a grammar/text `format` and raw
+ *  string input — e.g. Codex's `apply_patch` for GPT-5-family models), or a
+ *  *typed* tool identified only by its `type` (e.g. Codex's `tool_search` /
+ *  `web_search` entries, which carry no `name`). */
+type ResponsesTool = {
+    type?: string;
+    name?: string;
+    description?: string;
+    parameters?: unknown;
+    strict?: boolean;
+    format?: {
+        type?: string;
+        syntax?: string;
+        definition?: string;
+    };
+    /** Typed tools declare who executes them ("client" for CLI-side tools). */
+    execution?: string;
+};
+/**
+ * Codex encodes "unset" as an explicit JSON `null` for several optional fields
+ * (e.g. `"reasoning": null` whenever the selected model's metadata advertises
+ * no reasoning levels — the default for many custom-provider models). Every
+ * nullable field below must be read with a null-tolerant guard; reading
+ * `.effort` off a null `reasoning` previously failed every such Codex turn.
+ */
+export type ResponsesRequest = {
+    model?: string;
+    instructions?: string;
+    input?: string | ResponsesInputItem[];
+    tools?: ResponsesTool[];
+    tool_choice?: "auto" | "none" | "required" | {
+        type: string;
+        name?: string;
+    } | null;
+    max_output_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    parallel_tool_calls?: boolean;
+    /**
+     * Codex serializes `reasoning: null` (not an absent key) for models whose
+     * catalog metadata carries no reasoning level — every custom provider
+     * member slug (e.g. `grok-4`, `deepseek`) resolves to Codex's fallback model
+     * info, which has none. Null must translate as "no reasoning", never throw.
+     */
+    reasoning?: {
+        effort?: string | null;
+        [key: string]: unknown;
+    } | null;
+    text?: {
+        format?: {
+            type?: string;
+            name?: string;
+            schema?: unknown;
+            strict?: boolean;
+            [key: string]: unknown;
+        };
+    } | null;
+    previous_response_id?: string | null;
+    truncation?: string | unknown;
+    metadata?: Record<string, unknown> | null;
+    include?: unknown[] | null;
+    stream?: boolean;
+};
+type OpenAiUsage = {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+};
+type OpenAiResponse = {
+    id?: string;
+    choices?: OpenAiChoice[];
+    usage?: OpenAiUsage;
+    provider_cost?: unknown;
+};
+/**
+ * How a declared tool must be emitted when the model calls it:
+ * - `function`: a plain `function_call` item (JSON-schema function tools, and
+ *   tools discovered mid-conversation via `tool_search_output`).
+ * - `custom`: a `custom_tool_call` item carrying raw string input (freeform
+ *   tools like Codex's `apply_patch`).
+ * - `typed`: the tool's own native item type (`<type>_call`, e.g.
+ *   `tool_search_call`) — Codex dispatches these by payload shape, and a
+ *   `function_call` under the same name fails with "handler received
+ *   unsupported payload".
+ * - `server`: a server-executed tool (`web_search`) the *gateway* runs via the
+ *   server-tool loop. Its calls never surface as callable items — the loop
+ *   intercepts them and the egress renders native `web_search_call` items.
+ */
+export type ResponsesToolKind = "function" | "custom" | "typed" | "server";
+export type ResponsesToolEntry = {
+    kind: ResponsesToolKind;
+    /**
+     * The tool's namespace, for tools *discovered* through a `tool_search`
+     * execution (e.g. `spawn_agent` under `multi_agent_v1`). Codex routes a
+     * discovered tool's `function_call` by name **and** namespace — without the
+     * namespace the call fails with "unsupported call".
+     */
+    namespace?: string;
+};
+export type ResponsesToolRegistry = ReadonlyMap<string, ResponsesToolEntry>;
+/** The name the gateway-executed web search tool is projected under chat-side. */
+export declare const WEB_SEARCH_TOOL_NAME = "web_search";
+/** Options gating server-executed tool projection (on iff an executor exists). */
+export type ResponsesTranslationOptions = {
+    serverTools?: boolean;
+};
+/**
+ * The per-request tool registry: every callable tool the request declares or
+ * has discovered, keyed by the name the chat-side model calls it under, mapped
+ * to how its calls must be emitted. Typed tools are keyed by their `type`;
+ * discovered tools carry their namespace for egress dispatch.
+ */
+export declare function responsesToolRegistry(body: ResponsesRequest, options?: ResponsesTranslationOptions): ResponsesToolRegistry;
+/**
+ * Back-compat helper: the names of the freeform ("custom") tools a Responses
+ * request declares (see {@link responsesToolRegistry}).
+ */
+export declare function customToolNames(body: ResponsesRequest): ReadonlySet<string>;
+/** Translate a Responses request to an OpenAI Chat Completions body. */
+export declare function responsesToChat(body: ResponsesRequest, backendModel: string | undefined, options?: ResponsesTranslationOptions): Record<string, unknown>;
+export declare function chatToResponses(openai: OpenAiResponse, model: string, toolRegistry?: ResponsesToolRegistry, searches?: readonly ExecutedSearch[]): Record<string, unknown>;
+export declare function handleResponses(backend: Backend, body: ResponsesRequest, modelCallId?: string, signal?: AbortSignal, backendOptions?: BackendRequestOptions): Promise<Response>;