nanoharness-openai 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # nanoharness-openai
 
-An OpenAI-compatible chat model adapter for [nanoharness](https://www.npmjs.com/package/nanoharness). One adapter covers OpenAI and every server that speaks the Chat Completions format: Ollama, vLLM, OpenRouter, LM Studio, Groq, Together and more. It is a separate package so the core `nanoharness` package contains no network code.
+An OpenAI-compatible chat model adapter for [nanoharness](https://www.npmjs.com/package/nanoharness). One adapter covers OpenAI and every server that speaks the Chat Completions format: Ollama, vLLM, OpenRouter, LM Studio, Groq, Together and more. It is `openaiCompatible` from the core with the official URL and the global `fetch` filled in, kept separate so the core never uses the network by itself. If you would rather not install it, `openaiCompatible` from `nanoharness` does the same with the `fetch` and `baseUrl` you pass.
 
 ```sh
 npm install nanoharness nanoharness-openai
@@ -25,13 +25,30 @@ const { finalText } = await run({ adapter, prompt: "Say hi in one word." });
 | `apiKey` | Sent as a Bearer token. Optional for local servers. |
 | `baseUrl` | Default `https://api.openai.com/v1`. Must be `https`, or `http` on `localhost`, and must not contain credentials. |
 | `allowInsecureHttp` | Allows plain `http` to a non-localhost host, such as a server on your LAN or in Docker. Off by default. |
-| `maxTokens`, `maxTokensParam` | `maxTokensParam` is `"max_tokens"` (default) or `"max_completion_tokens"`, which OpenAI's newer models require. |
+| `maxTokens`, `maxTokensParam` | `maxTokensParam` is `"max_completion_tokens"` by default for OpenAI (reasoning models reject the deprecated `"max_tokens"`), and `"max_tokens"` when you set `baseUrl`, since most compatible servers expect it. Set it to override. |
 | `temperature` | Sent only when set. |
+| `headers` | Extra headers on every request, such as a gateway header. They can replace the default ones. |
 | `maxRetries` | Retries for HTTP 408, 429, 500, 502, 503 and 504, with backoff that honours `retry-after` (seconds or an HTTP date). Default `2`. |
+| `streamUsage` | When streaming, ask for token usage in the last chunk (`stream_options.include_usage`). Turn off for servers that reject it. Default `true`. |
 | `fetch` | A custom `fetch`, for proxies or tests. |
 
 Tool calls work through the standard `tools` and `tool_calls` fields, so the model must support tool calling. If a model returns tool arguments that are not valid JSON (or are not a JSON object), the call is **not run**: the harness tells the model its arguments were invalid. A reply cut off by the token limit (`finish_reason: "length"`) is reported as `max_tokens`, and any tool call in it is not run either.
 
+## Streaming and errors
+
+Both `complete` and `stream` are supported. Pass `streaming: true` to `run`, `stream` or `defineAgent` to receive `text_delta` events as text arrives.
+
+A failed request throws an `AdapterError` (from `nanoharness`) with the HTTP `status`, `retryable`, and `retryAfterMs` when the server sent one. The adapter retries on its own (`maxRetries`). To use jittered backoff or share a rate limit across agents instead, turn that off and wrap it, with `withRetry` outside:
+
+```ts
+import { limitConcurrency, withRetry } from "nanoharness";
+import { openai } from "nanoharness-openai";
+
+const adapter = withRetry(limitConcurrency(openai({ model: "gpt-4.1", apiKey: process.env.OPENAI_API_KEY, maxRetries: 0 }), 4));
+```
+
+Needs `nanoharness` 2.1 or later.
+
 Requests never follow redirects, so a misconfigured `baseUrl` cannot forward your key or the conversation to another host. If you pass your own `fetch`, make sure it does the same.
 
 Zero dependencies. Node 18 or later. MIT.

package/dist/index.cjs

@@ -23,166 +23,16 @@ __export(src_exports, {
   openai: () => openai
 });
 module.exports = __toCommonJS(src_exports);
-var RETRYABLE = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
-var STOP = {
-  stop: "end_turn",
-  tool_calls: "tool_use",
-  function_call: "tool_use",
-  length: "max_tokens"
-};
-function retryDelayMs(header, attempt) {
-  if (header) {
-    const seconds = Number(header);
-    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
-    const at = Date.parse(header);
-    if (!Number.isNaN(at)) return Math.max(0, at - Date.now());
-  }
-  return 500 * 2 ** attempt;
-}
-var ERROR_BODY_LIMIT = 1e3;
-async function errorBody(res) {
-  if (!res.body) return "";
-  const reader = res.body.getReader();
-  const decoder = new TextDecoder();
-  let text = "";
-  try {
-    while (text.length <= ERROR_BODY_LIMIT) {
-      const { done, value } = await reader.read();
-      if (done) return text + decoder.decode();
-      text += decoder.decode(value, { stream: true });
-    }
-  } catch {
-    return text;
-  } finally {
-    reader.cancel().catch(() => {
-    });
-  }
-  return `${text.slice(0, ERROR_BODY_LIMIT)}... [truncated]`;
-}
-async function send(doFetch, url, init) {
-  try {
-    return await doFetch(url, init);
-  } catch (e) {
-    const cause = e.cause?.message ?? "";
-    if (!init.signal?.aborted && /redirect/i.test(cause)) {
-      throw new Error("OpenAI API: the server answered with a redirect, which is never followed so your API key and conversation stay with baseUrl", { cause: e });
-    }
-    throw e;
-  }
-}
-function sleep(ms, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(signal.reason);
-    const t = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(t);
-      reject(signal.reason);
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-function chatUrl(baseUrl, allowInsecureHttp) {
-  let u;
-  try {
-    u = new URL(baseUrl);
-  } catch {
-    throw new Error(`openai(): invalid baseUrl "${baseUrl}"`);
-  }
-  const local = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
-  if (u.protocol !== "https:" && !(u.protocol === "http:" && (local || allowInsecureHttp))) {
-    throw new Error("openai(): baseUrl must use https (http is only allowed for localhost, or with allowInsecureHttp)");
-  }
-  if (u.username || u.password) throw new Error("openai(): baseUrl must not contain credentials");
-  return `${u.origin}${u.pathname.replace(/\/+$/, "")}/chat/completions`;
-}
-function toOpenAIMessages(system, messages) {
-  const out = [];
-  if (system) out.push({ role: "system", content: system });
-  for (const m of messages) {
-    if (typeof m.content === "string") {
-      out.push({ role: m.role, content: m.content });
-      continue;
-    }
-    const blocks = m.content;
-    const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("");
-    if (m.role === "assistant") {
-      const toolCalls = blocks.filter((b) => b.type === "tool_use").map((b) => ({ id: b.id, type: "function", function: { name: b.name, arguments: JSON.stringify(b.input) } }));
-      if (!text && toolCalls.length === 0) continue;
-      out.push({ role: "assistant", content: text || null, ...toolCalls.length ? { tool_calls: toolCalls } : {} });
-    } else {
-      for (const b of blocks) {
-        if (b.type === "tool_result") {
-          out.push({ role: "tool", tool_call_id: b.tool_use_id, content: b.is_error ? `Error: ${b.content}` : b.content });
-        }
-      }
-      if (text) out.push({ role: "user", content: text });
-    }
-  }
-  return out;
-}
+var import_nanoharness = require("nanoharness");
 function openai(opts) {
   if (!opts.model) throw new Error("openai(): model is required");
-  const doFetch = opts.fetch ?? fetch;
-  const url = chatUrl(opts.baseUrl ?? "https://api.openai.com/v1", opts.allowInsecureHttp ?? false);
-  const maxRetries = opts.maxRetries ?? 2;
-  return {
-    async complete(req) {
-      const body = JSON.stringify({
-        model: opts.model,
-        messages: toOpenAIMessages(req.system, req.messages),
-        ...opts.maxTokens !== void 0 ? { [opts.maxTokensParam ?? "max_tokens"]: opts.maxTokens } : {},
-        ...opts.temperature !== void 0 ? { temperature: opts.temperature } : {},
-        ...req.tools.length ? { tools: req.tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.input_schema } })) } : {}
-      });
-      let res;
-      for (let attempt = 0; ; attempt++) {
-        res = await send(doFetch, url, {
-          method: "POST",
-          signal: req.signal,
-          // Never follow a redirect: the request carries your API key and the whole conversation.
-          redirect: "error",
-          headers: { "content-type": "application/json", ...opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {} },
-          body
-        });
-        if (res.ok || !RETRYABLE.has(res.status) || attempt >= maxRetries) break;
-        await res.body?.cancel().catch(() => {
-        });
-        await sleep(Math.min(retryDelayMs(res.headers.get("retry-after"), attempt), 3e4), req.signal);
-      }
-      if (!res.ok) throw new Error(`OpenAI API error ${res.status}: ${await errorBody(res)}`);
-      let data;
-      try {
-        data = await res.json();
-      } catch {
-        throw new Error("OpenAI API returned invalid JSON");
-      }
-      const choice = data.choices?.[0];
-      if (!choice?.message) throw new Error("OpenAI API returned no choices");
-      const content = [];
-      if (choice.message.content) content.push({ type: "text", text: choice.message.content });
-      for (const tc of choice.message.tool_calls ?? []) {
-        let input = {};
-        let error;
-        try {
-          const parsed = JSON.parse(tc.function.arguments || "{}");
-          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) input = parsed;
-          else error = "arguments must be a JSON object";
-        } catch {
-          error = "arguments were not valid JSON";
-        }
-        content.push({ type: "tool_use", id: tc.id, name: tc.function.name, input, ...error ? { error } : {} });
-      }
-      return {
-        content,
-        // "length" wins over tool calls: arguments cut off by the token limit are incomplete and must not run.
-        stopReason: choice.finish_reason === "length" ? "max_tokens" : content.some((b) => b.type === "tool_use") ? "tool_use" : STOP[choice.finish_reason ?? ""] ?? "other",
-        usage: data.usage && { inputTokens: data.usage.prompt_tokens, outputTokens: data.usage.completion_tokens }
-      };
-    }
-  };
+  return (0, import_nanoharness.openaiCompatible)({
+    ...opts,
+    baseUrl: opts.baseUrl ?? "https://api.openai.com/v1",
+    maxTokensParam: opts.maxTokensParam ?? (opts.baseUrl ? "max_tokens" : "max_completion_tokens"),
+    fetch: opts.fetch ?? fetch,
+    name: "OpenAI API"
+  });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -10,14 +10,22 @@ interface OpenAIOptions {
     /** Permits plain http to a non-localhost host, e.g. a server on your LAN or in Docker. Off by default. */
     allowInsecureHttp?: boolean;
     maxTokens?: number;
-    /** Which field carries `maxTokens`. Default "max_tokens"; OpenAI's newer models want "max_completion_tokens". */
+    /**
+     * Which field carries `maxTokens`. Default "max_completion_tokens" for OpenAI (the older "max_tokens" is deprecated
+     * and rejected by reasoning models), and "max_tokens" when `baseUrl` is set, since most compatible servers expect it.
+     */
     maxTokensParam?: "max_tokens" | "max_completion_tokens";
     temperature?: number;
     /** A custom `fetch`, for proxies or tests. Defaults to the global `fetch`. */
     fetch?: typeof fetch;
-    /** Retries for 408, 429 and 5xx responses, with backoff. Default 2. */
+    /** Retries for 408, 429, 500, 502, 503 and 504 responses, with backoff. Default 2. */
     maxRetries?: number;
+    /** When streaming, ask the server for token usage in the last chunk (`stream_options.include_usage`). Turn off for servers that reject it. Default true. */
+    streamUsage?: boolean;
+    /** Extra headers on every request, e.g. for a gateway. */
+    headers?: Record<string, string>;
 }
+/** `openaiCompatible` from nanoharness, with OpenAI's URL and the global `fetch` as defaults. */
 declare function openai(opts: OpenAIOptions): Adapter;
 
 export { openai };

package/dist/index.d.ts

@@ -10,14 +10,22 @@ interface OpenAIOptions {
     /** Permits plain http to a non-localhost host, e.g. a server on your LAN or in Docker. Off by default. */
     allowInsecureHttp?: boolean;
     maxTokens?: number;
-    /** Which field carries `maxTokens`. Default "max_tokens"; OpenAI's newer models want "max_completion_tokens". */
+    /**
+     * Which field carries `maxTokens`. Default "max_completion_tokens" for OpenAI (the older "max_tokens" is deprecated
+     * and rejected by reasoning models), and "max_tokens" when `baseUrl` is set, since most compatible servers expect it.
+     */
     maxTokensParam?: "max_tokens" | "max_completion_tokens";
     temperature?: number;
     /** A custom `fetch`, for proxies or tests. Defaults to the global `fetch`. */
     fetch?: typeof fetch;
-    /** Retries for 408, 429 and 5xx responses, with backoff. Default 2. */
+    /** Retries for 408, 429, 500, 502, 503 and 504 responses, with backoff. Default 2. */
     maxRetries?: number;
+    /** When streaming, ask the server for token usage in the last chunk (`stream_options.include_usage`). Turn off for servers that reject it. Default true. */
+    streamUsage?: boolean;
+    /** Extra headers on every request, e.g. for a gateway. */
+    headers?: Record<string, string>;
 }
+/** `openaiCompatible` from nanoharness, with OpenAI's URL and the global `fetch` as defaults. */
 declare function openai(opts: OpenAIOptions): Adapter;
 
 export { openai };

package/dist/index.js

@@ -1,164 +1,14 @@
 // src/index.ts
-var RETRYABLE = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
-var STOP = {
-  stop: "end_turn",
-  tool_calls: "tool_use",
-  function_call: "tool_use",
-  length: "max_tokens"
-};
-function retryDelayMs(header, attempt) {
-  if (header) {
-    const seconds = Number(header);
-    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
-    const at = Date.parse(header);
-    if (!Number.isNaN(at)) return Math.max(0, at - Date.now());
-  }
-  return 500 * 2 ** attempt;
-}
-var ERROR_BODY_LIMIT = 1e3;
-async function errorBody(res) {
-  if (!res.body) return "";
-  const reader = res.body.getReader();
-  const decoder = new TextDecoder();
-  let text = "";
-  try {
-    while (text.length <= ERROR_BODY_LIMIT) {
-      const { done, value } = await reader.read();
-      if (done) return text + decoder.decode();
-      text += decoder.decode(value, { stream: true });
-    }
-  } catch {
-    return text;
-  } finally {
-    reader.cancel().catch(() => {
-    });
-  }
-  return `${text.slice(0, ERROR_BODY_LIMIT)}... [truncated]`;
-}
-async function send(doFetch, url, init) {
-  try {
-    return await doFetch(url, init);
-  } catch (e) {
-    const cause = e.cause?.message ?? "";
-    if (!init.signal?.aborted && /redirect/i.test(cause)) {
-      throw new Error("OpenAI API: the server answered with a redirect, which is never followed so your API key and conversation stay with baseUrl", { cause: e });
-    }
-    throw e;
-  }
-}
-function sleep(ms, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(signal.reason);
-    const t = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(t);
-      reject(signal.reason);
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-function chatUrl(baseUrl, allowInsecureHttp) {
-  let u;
-  try {
-    u = new URL(baseUrl);
-  } catch {
-    throw new Error(`openai(): invalid baseUrl "${baseUrl}"`);
-  }
-  const local = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
-  if (u.protocol !== "https:" && !(u.protocol === "http:" && (local || allowInsecureHttp))) {
-    throw new Error("openai(): baseUrl must use https (http is only allowed for localhost, or with allowInsecureHttp)");
-  }
-  if (u.username || u.password) throw new Error("openai(): baseUrl must not contain credentials");
-  return `${u.origin}${u.pathname.replace(/\/+$/, "")}/chat/completions`;
-}
-function toOpenAIMessages(system, messages) {
-  const out = [];
-  if (system) out.push({ role: "system", content: system });
-  for (const m of messages) {
-    if (typeof m.content === "string") {
-      out.push({ role: m.role, content: m.content });
-      continue;
-    }
-    const blocks = m.content;
-    const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("");
-    if (m.role === "assistant") {
-      const toolCalls = blocks.filter((b) => b.type === "tool_use").map((b) => ({ id: b.id, type: "function", function: { name: b.name, arguments: JSON.stringify(b.input) } }));
-      if (!text && toolCalls.length === 0) continue;
-      out.push({ role: "assistant", content: text || null, ...toolCalls.length ? { tool_calls: toolCalls } : {} });
-    } else {
-      for (const b of blocks) {
-        if (b.type === "tool_result") {
-          out.push({ role: "tool", tool_call_id: b.tool_use_id, content: b.is_error ? `Error: ${b.content}` : b.content });
-        }
-      }
-      if (text) out.push({ role: "user", content: text });
-    }
-  }
-  return out;
-}
+import { openaiCompatible } from "nanoharness";
 function openai(opts) {
   if (!opts.model) throw new Error("openai(): model is required");
-  const doFetch = opts.fetch ?? fetch;
-  const url = chatUrl(opts.baseUrl ?? "https://api.openai.com/v1", opts.allowInsecureHttp ?? false);
-  const maxRetries = opts.maxRetries ?? 2;
-  return {
-    async complete(req) {
-      const body = JSON.stringify({
-        model: opts.model,
-        messages: toOpenAIMessages(req.system, req.messages),
-        ...opts.maxTokens !== void 0 ? { [opts.maxTokensParam ?? "max_tokens"]: opts.maxTokens } : {},
-        ...opts.temperature !== void 0 ? { temperature: opts.temperature } : {},
-        ...req.tools.length ? { tools: req.tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.input_schema } })) } : {}
-      });
-      let res;
-      for (let attempt = 0; ; attempt++) {
-        res = await send(doFetch, url, {
-          method: "POST",
-          signal: req.signal,
-          // Never follow a redirect: the request carries your API key and the whole conversation.
-          redirect: "error",
-          headers: { "content-type": "application/json", ...opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {} },
-          body
-        });
-        if (res.ok || !RETRYABLE.has(res.status) || attempt >= maxRetries) break;
-        await res.body?.cancel().catch(() => {
-        });
-        await sleep(Math.min(retryDelayMs(res.headers.get("retry-after"), attempt), 3e4), req.signal);
-      }
-      if (!res.ok) throw new Error(`OpenAI API error ${res.status}: ${await errorBody(res)}`);
-      let data;
-      try {
-        data = await res.json();
-      } catch {
-        throw new Error("OpenAI API returned invalid JSON");
-      }
-      const choice = data.choices?.[0];
-      if (!choice?.message) throw new Error("OpenAI API returned no choices");
-      const content = [];
-      if (choice.message.content) content.push({ type: "text", text: choice.message.content });
-      for (const tc of choice.message.tool_calls ?? []) {
-        let input = {};
-        let error;
-        try {
-          const parsed = JSON.parse(tc.function.arguments || "{}");
-          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) input = parsed;
-          else error = "arguments must be a JSON object";
-        } catch {
-          error = "arguments were not valid JSON";
-        }
-        content.push({ type: "tool_use", id: tc.id, name: tc.function.name, input, ...error ? { error } : {} });
-      }
-      return {
-        content,
-        // "length" wins over tool calls: arguments cut off by the token limit are incomplete and must not run.
-        stopReason: choice.finish_reason === "length" ? "max_tokens" : content.some((b) => b.type === "tool_use") ? "tool_use" : STOP[choice.finish_reason ?? ""] ?? "other",
-        usage: data.usage && { inputTokens: data.usage.prompt_tokens, outputTokens: data.usage.completion_tokens }
-      };
-    }
-  };
+  return openaiCompatible({
+    ...opts,
+    baseUrl: opts.baseUrl ?? "https://api.openai.com/v1",
+    maxTokensParam: opts.maxTokensParam ?? (opts.baseUrl ? "max_tokens" : "max_completion_tokens"),
+    fetch: opts.fetch ?? fetch,
+    name: "OpenAI API"
+  });
 }
 export {
   openai

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nanoharness-openai",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "OpenAI-compatible chat model adapter for nanoharness: OpenAI, Ollama, vLLM, OpenRouter, LM Studio and more. Zero dependencies.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -60,7 +60,7 @@
     "provenance": true
   },
   "peerDependencies": {
-    "nanoharness": ">=2.0.0 <3"
+    "nanoharness": ">=2.1.0 <3"
   },
   "devDependencies": {
     "nanoharness": "file:../.."