@arden-hq/loop 0.0.0-stage → 0.1.0

package/dist/providers/openai-responses/tools.d.ts

@@ -0,0 +1,33 @@
+import type { ToolDeclaration, ToolSearch } from "../../contracts/tools.js";
+export interface FunctionTool {
+    readonly async?: boolean;
+    readonly type: "function";
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+    readonly strict: false;
+    readonly defer_loading?: true;
+}
+export interface ClientToolSearchTool {
+    readonly type: "tool_search";
+    readonly execution: "client";
+    readonly description: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+export interface NamespaceTool {
+    readonly type: "namespace";
+    readonly name: string;
+    readonly description: string;
+    readonly tools: ReadonlyArray<FunctionTool>;
+}
+/** The namespace a group travels under on this wire: its own name, unless OpenAI reserves it. */
+export declare const providerNamespace: (group: string) => string;
+export declare const functionTool: (tool: ToolDeclaration) => FunctionTool;
+export declare const clientToolSearchTool: (search: ToolSearch) => ClientToolSearchTool;
+/**
+ * Found tools grouped into namespaces, in order of first appearance. OpenAI's
+ * models were trained to search namespaces, and a namespaced call comes back
+ * with its `namespace` beside the tool's own name.
+ */
+export declare const namespacedTools: (declarations: ReadonlyArray<ToolDeclaration>) => ReadonlyArray<NamespaceTool>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/providers/openai-responses/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-responses/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAK3E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACtD,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACvD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;CAC5C;AAYD,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,UAAW,MAAM,KAAG,MACS,CAAA;AAE3D,eAAO,MAAM,YAAY,SAAU,eAAe,KAAG,YAcpD,CAAA;AAED,eAAO,MAAM,oBAAoB,WAAY,UAAU,KAAG,oBAKxD,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,iBACZ,aAAa,CAAC,eAAe,CAAC,KAC3C,aAAa,CAAC,aAAa,CAc7B,CAAA"}

package/dist/providers/openai-responses/tools.js

@@ -0,0 +1,53 @@
+import { OpenAiResponsesProviderError } from "./errors.js";
+import { asRecord } from "./items.js";
+import { projectFunctionParameters } from "./parameter-schema.js";
+const DEFAULT_NAMESPACE = "tools";
+/**
+ * Namespaces OpenAI keeps for its own tools. A request that declares or
+ * replays a function inside one is refused with HTTP 400 ("Function
+ * 'browser.browser_screenshot' is not allowed in reserved namespace
+ * 'browser'", seen 2026-09-27).
+ */
+const RESERVED_NAMESPACES = new Set(["browser"]);
+/** The namespace a group travels under on this wire: its own name, unless OpenAI reserves it. */
+export const providerNamespace = (group) => RESERVED_NAMESPACES.has(group) ? `${group}_tools` : group;
+export const functionTool = (tool) => {
+    if (tool.name.trim().length === 0 || asRecord(tool.parameters) === null) {
+        throw new OpenAiResponsesProviderError("The tool catalog contains an unsupported function schema");
+    }
+    return {
+        type: "function",
+        name: tool.name,
+        description: tool.description,
+        parameters: projectFunctionParameters(tool.parameters),
+        strict: false,
+        ...(tool.async === true ? { async: true } : {})
+    };
+};
+export const clientToolSearchTool = (search) => ({
+    type: "tool_search",
+    execution: "client",
+    description: search.description,
+    parameters: search.parameters
+});
+/**
+ * Found tools grouped into namespaces, in order of first appearance. OpenAI's
+ * models were trained to search namespaces, and a namespaced call comes back
+ * with its `namespace` beside the tool's own name.
+ */
+export const namespacedTools = (declarations) => {
+    const groups = new Map();
+    for (const declaration of declarations) {
+        const name = providerNamespace(declaration.group ?? DEFAULT_NAMESPACE);
+        const tools = groups.get(name) ?? [];
+        tools.push({ ...functionTool(declaration), defer_loading: true });
+        groups.set(name, tools);
+    }
+    return [...groups.entries()].map(([name, tools]) => ({
+        type: "namespace",
+        name,
+        description: `Tools in the ${name} namespace.`,
+        tools
+    }));
+};
+//# sourceMappingURL=tools.js.map

package/dist/providers/openai-responses/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/providers/openai-responses/tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAA;AA0BjE,MAAM,iBAAiB,GAAG,OAAO,CAAA;AAEjC;;;;;GAKG;AACH,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;AAErE,iGAAiG;AACjG,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAa,EAAU,EAAE,CACzD,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAA;AAE3D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAqB,EAAgB,EAAE;IAClE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;QACxE,MAAM,IAAI,4BAA4B,CACpC,0DAA0D,CAC3D,CAAA;IACH,CAAC;IACD,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,yBAAyB,CAAC,IAAI,CAAC,UAAU,CAAC;QACtD,MAAM,EAAE,KAAK;QACb,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAkB,EAAwB,EAAE,CAAC,CAAC;IACjF,IAAI,EAAE,aAAa;IACnB,SAAS,EAAE,QAAQ;IACnB,WAAW,EAAE,MAAM,CAAC,WAAW;IAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;CAC9B,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,YAA4C,EACd,EAAE;IAChC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAA;IACrD,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,iBAAiB,CAAC,WAAW,CAAC,KAAK,IAAI,iBAAiB,CAAC,CAAA;QACtE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;QACpC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,YAAY,CAAC,WAAW,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;QACjE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACzB,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACnD,IAAI,EAAE,WAAW;QACjB,IAAI;QACJ,WAAW,EAAE,gBAAgB,IAAI,aAAa;QAC9C,KAAK;KACN,CAAC,CAAC,CAAA;AACL,CAAC,CAAA"}

package/dist/providers/openai-responses/web-search.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue, ProviderToolCall } from "../../contracts/messages.js";
+import { type ResponseShape, type WebSearchOutputItem } from "./items.js";
+export declare const searchArguments: (item: WebSearchOutputItem) => Readonly<Record<string, JsonValue>>;
+export declare const webSearchCalls: (response: ResponseShape) => ReadonlyArray<ProviderToolCall>;
+//# sourceMappingURL=web-search.d.ts.map

package/dist/providers/openai-responses/web-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-responses/web-search.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,SAAS,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAC1F,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAA;AAkEnB,eAAO,MAAM,eAAe,SAAU,mBAAmB,KAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAoB7F,CAAA;AAkBD,eAAO,MAAM,cAAc,aAAc,aAAa,KAAG,aAAa,CAAC,gBAAgB,CAiBtF,CAAA"}

package/dist/providers/openai-responses/web-search.js

@@ -0,0 +1,114 @@
+import { publicWebUrl } from "@arden-hq/std/url";
+import { clipLine, cutText } from "@arden-hq/std/text";
+import { asRecord, WEB_SEARCH_TOOL_NAME } from "./items.js";
+const MAX_WEB_SOURCE_REFS = 20;
+const MAX_PROVIDER_RESULT_CHARS = 20_000;
+const boundedLine = (value, limit) => {
+    if (typeof value !== "string")
+        return null;
+    const text = clipLine(value, limit);
+    return text.length === 0 ? null : text;
+};
+const webUrl = (value) => {
+    if (typeof value !== "string")
+        return null;
+    const page = publicWebUrl(value);
+    return page.kind === "ok" ? page.url.toString() : null;
+};
+const sourceRef = (value) => {
+    const source = asRecord(value);
+    if (source?.type !== "url" && source?.type !== "url_citation")
+        return null;
+    const url = webUrl(source.url);
+    if (url === null)
+        return null;
+    const title = boundedLine(source.title, 256) ?? new URL(url).hostname;
+    return { provider: "web", kind: "page", ref: url, title, url };
+};
+const itemCitations = (item) => {
+    if (item.type !== "message")
+        return [];
+    return item.content.flatMap((part) => {
+        if (part.type !== "output_text")
+            return [];
+        return part.annotations.flatMap((annotation) => {
+            const ref = sourceRef(annotation);
+            return ref === null ? [] : [ref];
+        });
+    });
+};
+const citedSources = (response) => response.output.flatMap(itemCitations);
+const searchSources = (item, citations) => {
+    const actionSources = Array.isArray(item.action?.sources)
+        ? item.action.sources.flatMap((source) => {
+            const ref = sourceRef(source);
+            return ref === null ? [] : [ref];
+        })
+        : [];
+    const unique = new Map();
+    for (const ref of [...citations, ...actionSources]) {
+        if (!unique.has(ref.ref))
+            unique.set(ref.ref, ref);
+        if (unique.size >= MAX_WEB_SOURCE_REFS)
+            break;
+    }
+    return [...unique.values()];
+};
+export const searchArguments = (item) => {
+    const action = item.action;
+    if (action === undefined)
+        return {};
+    const values = {};
+    for (const [key, limit] of [
+        ["type", 64],
+        ["query", 1_000],
+        ["url", 4_096],
+        ["pattern", 1_000]
+    ]) {
+        const value = boundedLine(action[key], limit);
+        if (value !== null)
+            values[key] = value;
+    }
+    if (Array.isArray(action.queries)) {
+        values.queries = action.queries.slice(0, 20).flatMap((query) => {
+            const value = boundedLine(query, 1_000);
+            return value === null ? [] : [value];
+        });
+    }
+    return values;
+};
+const searchAction = (args) => {
+    if (typeof args.query === "string")
+        return `Searched for: ${args.query}`;
+    if (typeof args.url === "string")
+        return `Opened: ${args.url}`;
+    return "Searched the web.";
+};
+const searchResult = (item, sources) => {
+    const args = searchArguments(item);
+    const action = searchAction(args);
+    const result = sources.length === 0
+        ? action
+        : `${action}\n\nSources:\n${sources.map((source) => `- ${source.title}: ${source.url}`).join("\n")}`;
+    return cutText(result, MAX_PROVIDER_RESULT_CHARS, { suffix: "\n[Source summary truncated.]" });
+};
+export const webSearchCalls = (response) => {
+    const citations = citedSources(response);
+    return response.output.flatMap((item) => {
+        if (item.type !== "web_search_call")
+            return [];
+        const sources = searchSources(item, citations);
+        return [
+            {
+                id: item.id,
+                name: WEB_SEARCH_TOOL_NAME,
+                arguments: searchArguments(item),
+                result: searchResult(item, sources),
+                done: true,
+                loaded_tool_names: [],
+                source_refs: sources
+            }
+        ];
+    });
+};
+//# sourceMappingURL=web-search.js.map

package/dist/providers/openai-responses/web-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.js","sourceRoot":"","sources":["../../../src/providers/openai-responses/web-search.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai-responses/websocket.d.ts

@@ -0,0 +1,29 @@
+import type { Metadata } from "../../contracts/messages.js";
+import type { ModelProvider, ModelProviderSession } from "../../contracts/provider.js";
+/** Hosts supply the platform socket and authentication headers; Loop owns the protocol. */
+export interface ResponsesWebSocket {
+    readonly isClosed: () => boolean;
+    readonly events: AsyncIterable<unknown>;
+    readonly send: (event: Metadata) => void;
+    readonly close: () => void;
+}
+export type ConnectResponsesWebSocket = (options: {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+}) => Promise<ResponsesWebSocket>;
+export declare const openResponsesSession: (options: {
+    readonly connect: ConnectResponsesWebSocket;
+    readonly headers: (signal: AbortSignal, forceRefresh: boolean) => Promise<Record<string, string>>;
+    readonly baseUrl: string;
+    readonly modelPrefix: string;
+    readonly defaultInstructions?: string;
+    readonly omitMaxOutputTokens?: boolean;
+    readonly maxAttempts: number;
+    readonly idleTimeoutMs: number;
+    readonly capabilities: NonNullable<ModelProvider["capabilities"]>;
+    readonly transport: (model: string) => "sse" | "websocket";
+    readonly cacheScopeHeader?: string;
+    readonly fallback: ModelProvider["stream"];
+}) => ModelProviderSession;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/providers/openai-responses/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-responses/websocket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAIrB,MAAM,6BAA6B,CAAA;AAoBpC,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IACvC,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAA;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAC3B;AAED,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;AAEjC,eAAO,MAAM,oBAAoB,YAAa;IAC5C,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAA;IAC3C,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAA;IACjE,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,GAAG,WAAW,CAAA;IAC1D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;CAC3C,KAAG,oBAmZH,CAAA"}

package/dist/providers/openai-responses/websocket.js

@@ -0,0 +1,400 @@
+import { raceAbort, backoffSleep, isRetryableFailure, nextRetry, retryDelayMs, RetryableProviderError, HttpStatusError } from "../kit/index.js";
+import { OpenAiResponsesProviderError } from "./errors.js";
+import { asRecord } from "./items.js";
+import { makePayload } from "./request.js";
+import { makeEventMapper, responseCode, responseFailureMessage } from "./response.js";
+import { incrementalInput, responseContinuation } from "./continuation.js";
+export const openResponsesSession = (options) => {
+    const lifetime = new AbortController();
+    let connection;
+    let saved;
+    let next = "create";
+    let responseId;
+    let priorInput = [];
+    let steeredInput = [];
+    let pending;
+    let route;
+    let previous;
+    let socketUnavailable = false;
+    const close = () => {
+        connection?.socket.close();
+        connection = undefined;
+        saved = undefined;
+        pending = undefined;
+        next = "create";
+        responseId = undefined;
+        priorInput = [];
+        steeredInput = [];
+        previous = undefined;
+    };
+    const streamAttempt = async function* (request, recoveredRejections, forceRefresh) {
+        const capabilities = await options.capabilities(request.model);
+        if (route !== undefined &&
+            (route.model !== request.model || route.cacheScope !== request.cacheScope))
+            close();
+        if (capabilities.steering !== "native" &&
+            capabilities.asyncTools !== "native" &&
+            connection?.socket.isClosed())
+            close();
+        route = { model: request.model, cacheScope: request.cacheScope };
+        const signal = AbortSignal.any([
+            lifetime.signal,
+            ...(request.signal === undefined ? [] : [request.signal])
+        ]);
+        const requestPayload = options.omitMaxOutputTokens === true
+            ? (({ maxOutputTokens: _, ...rest }) => rest)(request)
+            : request;
+        const payload = makePayload(requestPayload, options.modelPrefix, options.defaultInstructions);
+        const delta = capabilities.steering === "native" || previous === undefined
+            ? undefined
+            : incrementalInput(payload, previous);
+        const additionalInput = continuationInput(payload.input, priorInput, steeredInput);
+        const automatic = next === "automatic";
+        const carry = automatic ? additionalInput.filter((item) => item.role === "user") : [];
+        const deferredOutputs = automatic && additionalInput.some((item) => item.type === "function_call_output");
+        const onAbort = () => connection?.socket.close();
+        signal.addEventListener("abort", onAbort, { once: true });
+        let polling = false;
+        let pollFailure;
+        let generating = false;
+        let failedSteer = false;
+        let terminal;
+        let terminalRaw;
+        let progressed = false;
+        let refreshHeaders = forceRefresh;
+        const map = makeEventMapper(request.model, request.toolSearch);
+        let pollWork = Promise.resolve();
+        const poll = () => {
+            if (capabilities.steering !== "native" ||
+                !generating ||
+                polling ||
+                pending !== undefined ||
+                responseId === undefined ||
+                signal.aborted)
+                return;
+            polling = true;
+            pollWork = (async () => {
+                const target = responseId;
+                const messages = (await request.steering?.take()) ?? [];
+                if (messages.length === 0 || signal.aborted)
+                    return;
+                if (target === undefined)
+                    return;
+                pending = { kind: "submitted", target };
+                const input = makePayload({ ...request, messages, tools: [], deferredTools: [] }, options.modelPrefix, undefined).input;
+                steeredInput = [...steeredInput, ...input];
+                if (connection === undefined)
+                    throw new Error("Responses socket closed before the steer was sent");
+                connection.socket.send({ type: "response.steer", previous_response_id: target, input });
+            })()
+                .catch((cause) => {
+                pollFailure = { cause };
+                connection?.socket.close();
+            })
+                .finally(() => {
+                polling = false;
+            });
+        };
+        const timer = setInterval(poll, 100);
+        const connect = async () => {
+            const headers = await options.headers(signal, refreshHeaders);
+            refreshHeaders = false;
+            const socket = await options
+                .connect({
+                url: `${options.baseUrl.replace(/^http/, "ws")}/responses`,
+                headers: {
+                    ...headers,
+                    ...(options.cacheScopeHeader === undefined || request.cacheScope === undefined
+                        ? {}
+                        : { [options.cacheScopeHeader]: request.cacheScope })
+                },
+                signal
+            })
+                .catch((cause) => {
+                throw new ConnectionFailure(cause);
+            });
+            return { socket, events: socket.events[Symbol.asyncIterator]() };
+        };
+        try {
+            connection ??= await connect();
+            if (next !== "automatic") {
+                const { stream: _, ...body } = payload;
+                if (next === "required" && responseId !== undefined) {
+                    const input = additionalInput;
+                    if (!input.some((item) => item.type === "function_call_output"))
+                        throw new OpenAiResponsesProviderError("Steering continuation requires tool output");
+                    connection.socket.send({
+                        type: "response.create",
+                        ...body,
+                        previous_response_id: responseId,
+                        input
+                    });
+                }
+                else
+                    connection.socket.send({
+                        type: "response.create",
+                        ...body,
+                        ...(delta === undefined || previous === undefined
+                            ? {}
+                            : {
+                                previous_response_id: previous.responseId,
+                                input: delta
+                            })
+                    });
+            }
+            next = "create";
+            priorInput = payload.input;
+            while (true) {
+                if (pollFailure !== undefined)
+                    throw pollFailure.cause;
+                const deadline = new AbortController();
+                const timer = setTimeout(() => deadline.abort(), options.idleTimeoutMs);
+                const read = await (async () => {
+                    try {
+                        if (saved !== undefined)
+                            return { done: false, value: saved };
+                        return await raceAbort(connection.events.next(), AbortSignal.any([signal, deadline.signal]));
+                    }
+                    catch (cause) {
+                        if (deadline.signal.aborted && !signal.aborted)
+                            throw new RetryableProviderError("OpenAI WebSocket response stream timed out");
+                        throw cause;
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                })();
+                saved = undefined;
+                if (read.done)
+                    throw new RetryableProviderError("OpenAI WebSocket disconnected before response completion");
+                const event = asRecord(read.value);
+                if (event === null || typeof event.type !== "string")
+                    throw new OpenAiResponsesProviderError("Invalid OpenAI WebSocket event");
+                if (event.type.startsWith("response.") && event.type !== "response.created")
+                    progressed = true;
+                if (event.type === "error" &&
+                    responseCode(event) === "native_turn_context_mismatch" &&
+                    capabilities.steering !== "native" &&
+                    capabilities.asyncTools !== "native" &&
+                    !automatic &&
+                    !progressed &&
+                    !recoveredRejections.has("context")) {
+                    recoveredRejections.add("context");
+                    close();
+                    yield { _tag: "ProviderStreamRetry", attempt: 1, maxAttempts: 2, delayMs: 0 };
+                    connection = await connect();
+                    const { stream: _, ...body } = payload;
+                    connection.socket.send({ type: "response.create", ...body });
+                    priorInput = payload.input;
+                    continue;
+                }
+                if (event.type === "error" &&
+                    responseCode(event) === "previous_response_not_found" &&
+                    delta !== undefined &&
+                    !progressed &&
+                    !recoveredRejections.has("missing")) {
+                    recoveredRejections.add("missing");
+                    previous = undefined;
+                    const { stream: _, ...body } = payload;
+                    connection.socket.send({ type: "response.create", ...body });
+                    continue;
+                }
+                if (event.type === "error" &&
+                    ["native_turn_context_mismatch", "previous_response_not_found"].includes(responseCode(event) ?? ""))
+                    throw new OpenAiResponsesProviderError(responseFailureMessage(event));
+                if (event.type === "response.created") {
+                    if (terminal !== undefined) {
+                        saved = event;
+                        next = "automatic";
+                        yield { ...terminal, continuation: true };
+                        return;
+                    }
+                    const response = asRecord(event.response);
+                    if (typeof response?.id !== "string")
+                        throw new OpenAiResponsesProviderError("Missing OpenAI response identity");
+                    responseId = response.id;
+                    if (automatic || pending?.kind === "accepted") {
+                        pending = undefined;
+                        steeredInput = [];
+                    }
+                    generating = true;
+                    if (carry.length > 0) {
+                        pending = { kind: "submitted", target: responseId };
+                        steeredInput = carry;
+                        connection.socket.send({
+                            type: "response.steer",
+                            previous_response_id: responseId,
+                            input: carry
+                        });
+                    }
+                    else
+                        poll();
+                }
+                if (event.type === "response.steer.accepted") {
+                    const steer = asRecord(event.steer);
+                    if (pending === undefined ||
+                        steer?.previous_response_id !== pending.target ||
+                        typeof steer.id !== "string") {
+                        throw new OpenAiResponsesProviderError("Unexpected steering acknowledgement");
+                    }
+                    pending = { kind: "accepted", target: pending.target, id: steer.id };
+                    continue;
+                }
+                if (event.type === "response.steer.failed") {
+                    pending = undefined;
+                    failedSteer = true;
+                    if (terminal !== undefined) {
+                        yield { ...terminal, continuation: true };
+                        return;
+                    }
+                    continue;
+                }
+                if (event.type === "response.steer.pending") {
+                    if (terminal === undefined)
+                        throw new OpenAiResponsesProviderError("Steering pending without a completed response");
+                    next = "required";
+                    yield { ...terminal, continuation: true };
+                    return;
+                }
+                const isTerminal = event.type === "response.completed" || event.type === "response.incomplete";
+                if (isTerminal) {
+                    generating = false;
+                    await pollWork;
+                    terminalRaw = event;
+                }
+                const details = asRecord(asRecord(event.response)?.incomplete_details);
+                const mapped = event.type === "response.incomplete" && details?.reason === "steered"
+                    ? map({ ...event, type: "response.completed" })
+                    : map(event);
+                for (const item of mapped) {
+                    if (item._tag === "Completed")
+                        terminal = item;
+                    else {
+                        yield item;
+                    }
+                }
+                if (terminal !== undefined && pending === undefined) {
+                    if (terminalRaw?.type === "response.incomplete" && details?.reason === "steered") {
+                        throw new OpenAiResponsesProviderError("Steered response has no tracked steering input");
+                    }
+                    const completedId = asRecord(terminalRaw?.response)?.id;
+                    previous =
+                        terminalRaw?.type === "response.completed" &&
+                            typeof completedId === "string" &&
+                            capabilities.steering !== "native"
+                            ? responseContinuation({
+                                payload,
+                                message: terminal.message,
+                                responseId: completedId,
+                                asyncTools: new Set([...request.tools, ...request.deferredTools].flatMap((tool) => tool.async === true ? [tool.name] : []))
+                            })
+                            : undefined;
+                    yield deferredOutputs || failedSteer ? { ...terminal, continuation: true } : terminal;
+                    return;
+                }
+            }
+        }
+        catch (cause) {
+            close();
+            throw cause;
+        }
+        finally {
+            generating = false;
+            clearInterval(timer);
+            await pollWork;
+            signal.removeEventListener("abort", onAbort);
+        }
+    };
+    return {
+        close: () => {
+            lifetime.abort();
+            close();
+        },
+        stream: async function* (request) {
+            if (options.transport(request.model) !== "websocket" || socketUnavailable) {
+                close();
+                yield* await options.fallback(request);
+                return;
+            }
+            const signal = AbortSignal.any([
+                lifetime.signal,
+                ...(request.signal === undefined ? [] : [request.signal])
+            ]);
+            const recoveredRejections = new Set();
+            let authRetried = false;
+            let forceRefresh = false;
+            for (let attempt = 1;; attempt++) {
+                signal.throwIfAborted();
+                const capabilities = await options.capabilities(request.model);
+                const boundary = next === "create" && pending === undefined;
+                const portable = capabilities.steering !== "native" && capabilities.asyncTools !== "native";
+                try {
+                    const refresh = forceRefresh;
+                    forceRefresh = false;
+                    yield* streamAttempt(request, recoveredRejections, refresh);
+                    return;
+                }
+                catch (failure) {
+                    const cause = failure instanceof ConnectionFailure ? failure.cause : failure;
+                    if (signal.aborted || !boundary || (!portable && !(failure instanceof ConnectionFailure)))
+                        throw cause;
+                    if (!authRetried &&
+                        failure instanceof ConnectionFailure &&
+                        cause instanceof HttpStatusError &&
+                        cause.status === 401) {
+                        authRetried = true;
+                        forceRefresh = true;
+                        attempt--;
+                        continue;
+                    }
+                    if (!isRetryableFailure(cause))
+                        throw cause;
+                    const delayMs = nextRetry(attempt, cause, { maxAttempts: options.maxAttempts });
+                    if (delayMs === undefined) {
+                        const fallbackDelayMs = cause instanceof HttpStatusError &&
+                            (cause.retryAfter !== null || cause.retryAfterMs !== null)
+                            ? retryDelayMs(attempt, cause)
+                            : 0;
+                        socketUnavailable = true;
+                        yield {
+                            _tag: "ProviderStreamRetry",
+                            attempt,
+                            maxAttempts: options.maxAttempts + 1,
+                            delayMs: fallbackDelayMs
+                        };
+                        if (fallbackDelayMs > 0)
+                            await backoffSleep(fallbackDelayMs, signal);
+                        signal.throwIfAborted();
+                        yield* await options.fallback(request);
+                        return;
+                    }
+                    yield { _tag: "ProviderStreamRetry", attempt, maxAttempts: options.maxAttempts, delayMs };
+                    await backoffSleep(delayMs, signal);
+                }
+            }
+        }
+    };
+};
+class ConnectionFailure extends Error {
+    constructor(cause) {
+        super("OpenAI WebSocket connection failed", { cause });
+    }
+}
+const continuationInput = (input, previous, steered) => {
+    const seen = new Map();
+    for (const item of [...previous, ...steered]) {
+        const key = JSON.stringify(item);
+        seen.set(key, (seen.get(key) ?? 0) + 1);
+    }
+    return input.filter((item) => {
+        if (item.role !== "user" && item.type !== "function_call_output")
+            return false;
+        const key = JSON.stringify(item);
+        const count = seen.get(key) ?? 0;
+        if (count === 0)
+            return true;
+        seen.set(key, count - 1);
+        return false;
+    });
+};
+//# sourceMappingURL=websocket.js.map