purra-openai 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lybrands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# purra-openai · TypeScript
+
+English | [简体中文](README.zh-CN.md)
+
+OpenAI model gateways for PurrA using the official SDK. Supports text, function
+tools, streaming, cancellation, and token usage. Requires Node.js 22+ (ESM).
+
+## Install
+
+Follow [source installation](../../README.md#source-installation), selecting
+`integrations/openai/typescript`.
+
+## Configure
+
+Supply the selected model ID and its verified capability snapshot:
+
+```ts
+import { Agent, type ModelCapabilitySnapshot } from "purra";
+import { OpenAIResponsesGateway } from "purra-openai";
+
+function createAgent(model: string, capabilities: ModelCapabilitySnapshot) {
+  const gateway = new OpenAIResponsesGateway({
+    model,
+    capabilities,
+    timeoutMs: 60_000,
+  });
+  return new Agent({ model: gateway });
+}
+```
+
+Pass an SDK client through `client` to configure credentials or transport.
+Without one, the gateway creates a client using the SDK's environment configuration.
+
+| Gateway | API | Model-specific options |
+| --- | --- | --- |
+| `OpenAIResponsesGateway` | Responses | `reasoning` |
+| `OpenAIChatCompletionsGateway` | Chat Completions | `reasoningEffort`, `temperature`, `topP` |
+
+Both gateways accept `model`, `capabilities`, `client`, and `timeoutMs`.
+To use Chat Completions, import `OpenAIChatCompletionsGateway` and construct it
+with those options. Select parameters supported by the chosen model.
+
+## Behavior
+
+Core resolves the total-generation limit; the gateway applies it to the selected API.
+SDK retries are disabled so Core controls retry and budget accounting.
+Server-side response storage is disabled.
+
+Responses reasoning continuation is kept in private message data; preserve it
+with the conversation when resuming. Tool choice is automatic when tools are
+available. Images, audio, and hosted tools are not supported.
+Other vendors require application adapters.

package/README.zh-CN.md

@@ -0,0 +1,49 @@
+# purra-openai · TypeScript
+
+[English](README.md) | 简体中文
+
+使用官方 SDK 将 OpenAI 接入 PurrA，支持文本、函数工具、流式输出、取消和 Token 用量。
+要求 Node.js 22+（ESM）。
+
+## 安装
+
+按照[源码安装说明](../../README.zh-CN.md#从源码安装)操作，选择
+`integrations/openai/typescript`。
+
+## 配置
+
+传入所选模型 ID 和已核实的模型能力快照：
+
+```ts
+import { Agent, type ModelCapabilitySnapshot } from "purra";
+import { OpenAIResponsesGateway } from "purra-openai";
+
+function createAgent(model: string, capabilities: ModelCapabilitySnapshot) {
+  const gateway = new OpenAIResponsesGateway({
+    model,
+    capabilities,
+    timeoutMs: 60_000,
+  });
+  return new Agent({ model: gateway });
+}
+```
+
+通过 `client` 传入 SDK 客户端，可自定义凭据与传输配置。
+省略时，网关使用 SDK 的环境配置创建客户端。
+
+| 网关 | API | 模型参数 |
+| --- | --- | --- |
+| `OpenAIResponsesGateway` | Responses | `reasoning` |
+| `OpenAIChatCompletionsGateway` | Chat Completions | `reasoningEffort`、`temperature`、`topP` |
+
+两个网关均接受 `model`、`capabilities`、`client` 和 `timeoutMs`。
+使用 Chat Completions 时，导入 `OpenAIChatCompletionsGateway` 并使用这些参数构造。
+模型参数应按所选模型支持的能力设置。
+
+## 行为
+
+Core 计算输出上限，网关将其应用到对应 API。SDK 自动重试已关闭，重试和预算核算由 Core 控制。
+服务端响应存储已关闭。
+
+Responses 的推理续接信息保存在私有消息数据中，恢复时应与对话一同保留。
+有工具可用时采用自动工具选择。不支持图片、音频及服务端托管工具，其他厂商由应用提供适配。

package/dist/chat.d.ts

@@ -0,0 +1,19 @@
+import OpenAI from "openai";
+import type { ChatCompletionCreateParamsNonStreaming } from "openai/resources/chat/completions";
+import type { ModelCapabilitySnapshot, ModelGateway, ModelRequest, ModelStream, ModelTurn } from "purra";
+export interface OpenAIChatCompletionsOptions {
+    readonly client?: OpenAI;
+    readonly model: string;
+    readonly capabilities: ModelCapabilitySnapshot;
+    readonly timeoutMs?: number;
+    readonly reasoningEffort?: ChatCompletionCreateParamsNonStreaming["reasoning_effort"];
+    readonly temperature?: number;
+    readonly topP?: number;
+}
+export declare class OpenAIChatCompletionsGateway implements ModelGateway {
+    #private;
+    readonly capabilities: ModelCapabilitySnapshot;
+    constructor(options: OpenAIChatCompletionsOptions);
+    invoke(request: ModelRequest, signal?: AbortSignal): Promise<ModelTurn>;
+    stream(request: ModelRequest, signal?: AbortSignal): Promise<ModelStream>;
+}

package/dist/chat.js

@@ -0,0 +1,151 @@
+import OpenAI from "openai";
+import { AgentCanceledError, AgentError } from "purra";
+function text(value) {
+    if (value === null)
+        return "";
+    if (typeof value !== "string")
+        throw new TypeError("OpenAI Chat Completions accepts text content only");
+    return value;
+}
+function messages(input) {
+    return input.map(m => {
+        if (m.toolCalls?.length && m.role !== "assistant")
+            throw new TypeError("Only assistant messages may carry tool calls");
+        const content = text(m.content);
+        if (m.role === "tool") {
+            if (!m.toolCallId)
+                throw new TypeError("Tool output requires a call id");
+            return { role: "tool", content, tool_call_id: m.toolCallId };
+        }
+        if (m.role === "assistant")
+            return { role: "assistant", content,
+                ...(m.toolCalls?.length ? { tool_calls: m.toolCalls.map(c => ({ id: c.id, type: "function",
+                        function: { name: c.name, arguments: JSON.stringify(c.arguments) } })) } : {}),
+            };
+        return { role: m.role, content };
+    });
+}
+function usage(u) {
+    if (u?.prompt_tokens == null || u.completion_tokens == null)
+        return undefined;
+    const reasoningTokens = u.completion_tokens_details?.reasoning_tokens;
+    return { inputTokens: u.prompt_tokens, generationTokens: u.completion_tokens, totalTokens: u.total_tokens,
+        cachedInputTokens: u.prompt_tokens_details?.cached_tokens ?? 0,
+        ...(reasoningTokens === undefined ? {} : { reasoningTokens }) };
+}
+function finish(reason) {
+    if (reason === "stop" || reason === "tool_calls")
+        return reason;
+    if (reason === "length")
+        return "length";
+    if (reason === "content_filter")
+        return "filtered";
+    throw new AgentError("invalid_model_response", "Unknown OpenAI finish reason");
+}
+function failed(error, signal) {
+    if (signal?.aborted)
+        throw new AgentCanceledError();
+    if (error instanceof OpenAI.APIError)
+        throw new AgentError(error.status === undefined ? "openai_transport_error" : `openai_http_${error.status}`, "OpenAI request failed");
+    if (error instanceof AgentError)
+        throw error;
+    throw new AgentError("invalid_model_response", "Invalid OpenAI Chat Completions response");
+}
+export class OpenAIChatCompletionsGateway {
+    capabilities;
+    #client;
+    #options;
+    constructor(options) {
+        if (!options.model.trim())
+            throw new TypeError("Model name is required");
+        if (!Number.isFinite(options.timeoutMs ?? 60000) || (options.timeoutMs ?? 60000) <= 0)
+            throw new TypeError("Timeout must be positive and finite");
+        this.capabilities = options.capabilities;
+        this.#options = { ...options };
+        this.#client = (options.client ?? new OpenAI()).withOptions({ maxRetries: 0, timeout: options.timeoutMs ?? 60000 });
+    }
+    #request(request) {
+        if (!request.outputBudget)
+            throw new TypeError("OpenAI gateway requires a resolved generation budget");
+        const o = this.#options;
+        return { model: o.model, messages: messages(request.messages), store: false, max_completion_tokens: request.outputBudget.maxGenerationTokens,
+            ...(o.reasoningEffort === undefined ? {} : { reasoning_effort: o.reasoningEffort }),
+            ...(o.temperature === undefined ? {} : { temperature: o.temperature }),
+            ...(o.topP === undefined ? {} : { top_p: o.topP }),
+            ...(request.tools.length ? { tools: request.tools.map(t => ({ type: "function",
+                    function: { name: t.name, description: t.description, parameters: JSON.parse(JSON.stringify(t.inputSchema)), strict: false } })), tool_choice: "auto" } : {}),
+        };
+    }
+    async invoke(request, signal) {
+        const params = this.#request(request);
+        if (signal?.aborted)
+            throw new AgentCanceledError();
+        try {
+            const response = await this.#client.chat.completions.create(params, { signal });
+            const c = response.choices[0];
+            if (response.choices.length !== 1 || c?.index !== 0 || c.message.role !== "assistant")
+                throw new Error("Invalid completion");
+            const tokenUsage = usage(response.usage);
+            return { message: { role: "assistant", content: text(c.message.content), toolCalls: (c.message.tool_calls ?? []).map(call => {
+                        if (call.type !== "function")
+                            throw new Error("Unsupported tool type");
+                        return { id: call.id, name: call.function.name, arguments: JSON.parse(call.function.arguments) };
+                    }) }, finishReason: c.message.refusal ? "filtered" : finish(c.finish_reason),
+                appliedGenerationLimit: request.outputBudget.maxGenerationTokens, ...(tokenUsage === undefined ? {} : { usage: tokenUsage }) };
+        }
+        catch (error) {
+            return failed(error, signal);
+        }
+    }
+    async stream(request, signal) {
+        const params = this.#request(request);
+        const client = this.#client;
+        let consumed = false;
+        async function* chunks() {
+            if (consumed)
+                throw new AgentError("invalid_model_response", "OpenAI stream has already been consumed");
+            consumed = true;
+            if (signal?.aborted)
+                throw new AgentCanceledError();
+            let stream;
+            let terminal;
+            let tokenUsage;
+            let refused = false;
+            try {
+                stream = await client.chat.completions.create({ ...params, stream: true, stream_options: { include_usage: true } }, { signal });
+                for await (const chunk of stream) {
+                    if (chunk.usage != null)
+                        tokenUsage = usage(chunk.usage);
+                    if (!chunk.choices.length) {
+                        yield { type: "activity", kind: "transport" };
+                        continue;
+                    }
+                    const c = chunk.choices[0];
+                    if (chunk.choices.length !== 1 || c?.index !== 0 || terminal !== undefined)
+                        throw new Error("Invalid completion sequence");
+                    refused ||= Boolean(c.delta.refusal);
+                    const content = text(c.delta.content ?? null);
+                    const calls = (c.delta.tool_calls ?? []).map(call => ({ index: call.index,
+                        ...(call.id === undefined ? {} : { id: call.id }), ...(call.type === undefined ? {} : { type: call.type }),
+                        ...(call.function?.name === undefined ? {} : { name: call.function.name }), argumentsFragment: call.function?.arguments ?? "" }));
+                    if (content || calls.length)
+                        yield { contentDelta: content, toolCallDeltas: calls };
+                    else
+                        yield { type: "activity", kind: "transport" };
+                    if (c.finish_reason !== null)
+                        terminal = finish(c.finish_reason);
+                }
+                if (terminal === undefined)
+                    throw new AgentError("upstream_stream_interrupted", "OpenAI stream ended without a finish reason");
+                yield { finishReason: refused ? "filtered" : terminal, ...(tokenUsage === undefined ? {} : { usage: tokenUsage }) };
+            }
+            catch (error) {
+                failed(error, signal);
+            }
+            finally {
+                stream?.controller.abort();
+            }
+        }
+        return { appliedGenerationLimit: request.outputBudget.maxGenerationTokens, activitySupport: "transport", [Symbol.asyncIterator]: chunks };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import OpenAI from "openai";
+export { OpenAIChatCompletionsGateway } from "./chat.js";
+export type { OpenAIChatCompletionsOptions } from "./chat.js";
+import type { ResponseCreateParamsNonStreaming } from "openai/resources/responses/responses";
+import type { ModelCapabilitySnapshot, ModelGateway, ModelRequest, ModelStream, ModelTurn } from "purra";
+export interface OpenAIResponsesOptions {
+    readonly client?: OpenAI;
+    readonly model: string;
+    /** Host-selected model facts; the adapter never guesses model token limits. */
+    readonly capabilities: ModelCapabilitySnapshot;
+    readonly timeoutMs?: number;
+    readonly reasoning?: ResponseCreateParamsNonStreaming["reasoning"];
+}
+/** Official SDK transport with one HTTP attempt per managed invocation. */
+export declare class OpenAIResponsesGateway implements ModelGateway {
+    #private;
+    readonly capabilities: ModelCapabilitySnapshot;
+    constructor(options: OpenAIResponsesOptions);
+    invoke(request: ModelRequest, signal?: AbortSignal): Promise<ModelTurn>;
+    stream(request: ModelRequest, signal?: AbortSignal): Promise<ModelStream>;
+}

package/dist/index.js

@@ -0,0 +1,156 @@
+import OpenAI from "openai";
+export { OpenAIChatCompletionsGateway } from "./chat.js";
+import { AgentCanceledError, AgentError } from "purra";
+const replayKey = "openai_reasoning_items";
+function text(value) {
+    if (value === null)
+        return "";
+    if (typeof value !== "string")
+        throw new TypeError("OpenAI adapter currently accepts text messages only");
+    return value;
+}
+function input(messages) {
+    const rows = [];
+    for (const m of messages) {
+        if (m.toolCalls?.length && m.role !== "assistant")
+            throw new TypeError("Only assistant messages may carry function calls");
+        if (m.role === "assistant") {
+            const replay = m.providerData?.[replayKey] ?? [];
+            if (!Array.isArray(replay) || replay.some(r => !r || typeof r !== "object" || Array.isArray(r) || r.type !== "reasoning"))
+                throw new TypeError("Invalid OpenAI reasoning continuation");
+            rows.push(...JSON.parse(JSON.stringify(replay)));
+        }
+        const content = text(m.content);
+        if (m.role === "tool") {
+            if (!m.toolCallId)
+                throw new TypeError("Tool output requires a call id");
+            rows.push({ type: "function_call_output", call_id: m.toolCallId, output: content });
+            continue;
+        }
+        if (content || !m.toolCalls?.length)
+            rows.push({ role: m.role, content });
+        for (const call of m.toolCalls ?? [])
+            rows.push({ type: "function_call", call_id: call.id, name: call.name, arguments: JSON.stringify(call.arguments) });
+    }
+    return rows;
+}
+function usage(response) {
+    const u = response.usage;
+    return u == null ? undefined : { inputTokens: u.input_tokens, generationTokens: u.output_tokens, totalTokens: u.total_tokens,
+        cachedInputTokens: u.input_tokens_details.cached_tokens, reasoningTokens: u.output_tokens_details.reasoning_tokens };
+}
+function finish(response) {
+    if (response.status === "incomplete")
+        return response.incomplete_details?.reason === "max_output_tokens" ? "length" : response.incomplete_details?.reason === "content_filter" ? "filtered" : "other";
+    if (response.status !== "completed")
+        throw new AgentError("openai_response_failed", "OpenAI response failed");
+    if (response.output.some(i => i.type === "function_call"))
+        return "tool_calls";
+    if (response.output.some(i => i.type === "message" && i.content.some(p => p.type === "refusal")))
+        return "filtered";
+    return "stop";
+}
+function attributes(response) {
+    const items = response.output.filter(i => i.type === "reasoning");
+    return items.length ? { [replayKey]: JSON.parse(JSON.stringify(items)) } : {};
+}
+function failed(error, signal) {
+    if (signal?.aborted)
+        throw new AgentCanceledError();
+    if (error instanceof OpenAI.APIError)
+        throw new AgentError(error.status === undefined ? "openai_transport_error" : `openai_http_${error.status}`, "OpenAI request failed");
+    throw error;
+}
+/** Official SDK transport with one HTTP attempt per managed invocation. */
+export class OpenAIResponsesGateway {
+    capabilities;
+    #client;
+    #model;
+    #reasoning;
+    constructor(options) {
+        if (!options.model.trim())
+            throw new TypeError("Model name is required");
+        if (!Number.isFinite(options.timeoutMs ?? 60000) || (options.timeoutMs ?? 60000) <= 0)
+            throw new TypeError("Timeout must be positive");
+        this.capabilities = options.capabilities;
+        this.#model = options.model;
+        this.#reasoning = options.reasoning;
+        this.#client = (options.client ?? new OpenAI()).withOptions({ maxRetries: 0, timeout: options.timeoutMs ?? 60000 });
+    }
+    #request(request) {
+        if (!request.outputBudget)
+            throw new TypeError("OpenAI gateway requires a resolved generation budget");
+        return { model: this.#model, input: input(request.messages), store: false, include: ["reasoning.encrypted_content"],
+            max_output_tokens: request.outputBudget.maxGenerationTokens,
+            tools: request.tools.map(t => ({ type: "function", name: t.name, description: t.description,
+                parameters: JSON.parse(JSON.stringify(t.inputSchema)), strict: false })),
+            tool_choice: request.tools.length ? "auto" : "none",
+            ...(this.#reasoning === undefined ? {} : { reasoning: this.#reasoning }), };
+    }
+    async invoke(request, signal) {
+        const params = this.#request(request);
+        try {
+            const response = await this.#client.responses.create(params, { signal });
+            const tokenUsage = usage(response);
+            return { message: { role: "assistant", content: response.output_text, providerData: attributes(response),
+                    toolCalls: response.output.filter(i => i.type === "function_call").map(i => ({ id: i.call_id, name: i.name, arguments: JSON.parse(i.arguments) })) },
+                finishReason: finish(response), appliedGenerationLimit: request.outputBudget.maxGenerationTokens,
+                ...(tokenUsage === undefined ? {} : { usage: tokenUsage }), };
+        }
+        catch (error) {
+            return failed(error, signal);
+        }
+    }
+    async stream(request, signal) {
+        const params = this.#request(request);
+        const client = this.#client;
+        let consumed = false;
+        async function* chunks() {
+            if (consumed)
+                throw new AgentError("invalid_model_response", "OpenAI stream has already been consumed");
+            consumed = true;
+            let stream;
+            let terminal = false;
+            try {
+                stream = await client.responses.create({ ...params, stream: true }, { signal });
+                for await (const event of stream) {
+                    const item = project(event);
+                    if (item)
+                        yield item;
+                    if (event.type === "response.completed" || event.type === "response.incomplete" || event.type === "response.failed") {
+                        terminal = true;
+                        break;
+                    }
+                }
+                if (!terminal)
+                    throw new AgentError("upstream_stream_interrupted", "OpenAI stream ended without a terminal response");
+            }
+            catch (error) {
+                failed(error, signal);
+            }
+            finally {
+                stream?.controller.abort();
+            }
+        }
+        return { appliedGenerationLimit: request.outputBudget.maxGenerationTokens, activitySupport: "working", [Symbol.asyncIterator]: chunks };
+    }
+}
+function project(event) {
+    if (event.type === "response.output_text.delta")
+        return { contentDelta: event.delta };
+    if (event.type === "response.reasoning_text.delta" || event.type === "response.reasoning_summary_text.delta")
+        return { type: "activity", kind: "working" };
+    if (event.type === "response.output_item.added" && event.item.type === "function_call")
+        return {
+            toolCallDeltas: [{ index: event.output_index, id: event.item.call_id, name: event.item.name, type: "function", argumentsFragment: event.item.arguments }],
+        };
+    if (event.type === "response.function_call_arguments.delta")
+        return { toolCallDeltas: [{ index: event.output_index, argumentsFragment: event.delta }] };
+    if (event.type === "response.completed" || event.type === "response.incomplete" || event.type === "response.failed") {
+        const tokenUsage = usage(event.response);
+        return { finishReason: finish(event.response), providerData: attributes(event.response), ...(tokenUsage === undefined ? {} : { usage: tokenUsage }) };
+    }
+    if (event.type === "error")
+        throw new AgentError("openai_stream_error", "OpenAI stream failed");
+    return { type: "activity", kind: "transport" };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "purra-openai",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Official OpenAI Responses and Chat Completions SDK adapter for PurrA",
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "openai": "7.9.0"
+  },
+  "peerDependencies": {
+    "purra": "0.5.0"
+  },
+  "devDependencies": {
+    "purra": "file:../../../typescript",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "check": "npm run build && npm test",
+    "prepack": "npm run build"
+  }
+}