@x12i/openrouter-runtime 1.0.6 → 1.4.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 x12i
-
-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.
+MIT License
+
+Copyright (c) 2026 x12i
+
+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

@@ -1,140 +1,160 @@
-# @x12i/openrouter-runtime
-
-TypeScript runtime for executing OpenRouter calls with normalized request and response objects.
-
-It supports Chat Completions, Responses, OpenRouter server tools, local function tools, citation extraction, usage normalization, generated image extraction, patch proposal extraction, retries, and policy validation.
-
-## Install
-
-```bash
-npm install @x12i/openrouter-runtime
-```
-
-## Usage
-
-```ts
-import { createOpenRouterRuntime } from "@x12i/openrouter-runtime";
-
-const runtime = createOpenRouterRuntime({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  defaults: {
-    serverTools: {
-      datetime: { mode: "allowed", timezone: "Asia/Jerusalem" }
-    }
-  }
-});
-
-const response = await runtime.run({
-  model: "openai/gpt-5.2",
-  messages: [{ role: "user", content: "What time is it?" }]
-});
-
-console.log(response.text);
-```
-
-## Console logging
-
-Turn on runtime console logs with:
-
-```bash
-OPENROUTER_RUNTIME_LOGS=true
-```
-
-When that env var is `true` / `1` / `yes` / `on`, and you do not pass a custom `logger`, the runtime logs to the console:
-
-- `runtime.request.started` — includes `streaming: false` and `entrypoint: "run"`
-- `runtime.request.compiled` — includes `bodyStream: false` and any streaming-related warning codes
-- `runtime.response.normalized`
-- `runtime.executeStreamingChat.called` — if someone hits the reserved streaming method
-- provider retry / function-tool events
-
-This package does **not** auto-load `.env`. Put the vars in your environment (shell export, process manager, or host `dotenv`) before calling `createOpenRouterRuntime()`. See `.env.example`.
-
-Example:
-
-```bash
-OPEN_ROUTER_KEY=sk-or-...
-OPENROUTER_RUNTIME_LOGS=true
-```
-
-You can still pass an explicit `logger` to override the console logger.
-
-## Server Tools
-
-Enable OpenRouter server tools through `serverTools`:
-
-```ts
-await runtime.run({
-  model: "anthropic/claude-sonnet-4",
-  messages: [{ role: "user", content: "Research recent OpenRouter web search changes." }],
-  serverTools: {
-    webSearch: { mode: "required", maxResults: 5 },
-    webFetch: { mode: "allowed", maxContentTokens: 50000 }
-  }
-});
-```
-
-### Citation Policy
-
-`defaults.requireCitationsWhenSearchUsed` controls the package-wide default for web-search citation enforcement. A request-level `serverTools.webSearch.requireCitations` value overrides that default:
-
-- `requireCitations: true`: if web search is used and no citations are extracted, the runtime emits `CITATIONS_REQUIRED_BUT_MISSING`.
-- `requireCitations: false`: disables citation enforcement for that request, even if the global default is `true`.
-
-When `defaults.onPolicyViolation` is `"throw"`, citation policy failures are returned as `errors[]` with `source: "policy"` and `status: "policy_violation"`. When it is `"return_error"`, they remain in `warnings[]`.
-
-`applyPatch` automatically selects the Responses API. The runtime returns patch proposals and never mutates files unless an explicit `patchApplier` is supplied.
-
-## Function Tools
-
-```ts
-const runtime = createOpenRouterRuntime({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  tools: {
-    getCustomerRisk: async (args) => ({ score: 82, args })
-  }
-});
-```
-
-Function calls are executed locally and looped back to OpenRouter until a final response is produced or `maxToolIterations` is reached.
-
-## Streaming
-
-### `run()` is non-streaming — always
-
-`runtime.run(request)` never streams. It is the only supported execution path today.
-
-Use it for background tasks, graph nodes, tool calls, structured output, research jobs, classification, extraction, patch generation, and automation.
-
-```ts
-const response = await runtime.run({
-  model: "openai/gpt-5.2",
-  prompt: "Summarize this document."
-});
-```
-
-This sends a normal non-streaming OpenRouter request and returns a completed `RuntimeResponse`.
-
-`run()` always sends `stream: false` on the OpenRouter body. Any truthy `rawOpenRouterOverrides.stream` is overwritten and reported as `STREAMING_OVERRIDE_IGNORED_FOR_RUN`. Nested `serverTools.advisor.stream` is also forced off with `ADVISOR_STREAMING_IGNORED_FOR_RUN`.
-
-### Streaming lives on a separate method: `executeStreamingChat()`
-
-Streaming is **not** available through `run()`, and the old `runtime.stream()` name was **removed on purpose**.
-
-Clients that still call `runtime.stream(...)` will break. That is intentional — so mistaken streaming usage is caught immediately.
-
-The reserved streaming entrypoint is:
-
-```ts
-for await (const event of runtime.executeStreamingChat(request)) {
-  // token deltas / stream events (not implemented yet)
-}
-```
-
-Today, `executeStreamingChat()` throws `STREAMING_NOT_IMPLEMENTED`. Treat this package as a non-streaming runtime until that method is implemented.
-
-| Method | Streaming? | Status |
-| --- | --- | --- |
-| `runtime.run(request)` | No | Supported |
-| `runtime.executeStreamingChat(request)` | Yes (future) | Throws `STREAMING_NOT_IMPLEMENTED` |
-| `runtime.stream(request)` | — | **Removed** — breaks by design |
+# @x12i/openrouter-runtime
+
+TypeScript runtime for executing OpenRouter calls with normalized request and response objects.
+
+It supports Chat Completions, Responses, OpenRouter server tools, local function tools, citation extraction, usage normalization, generated image extraction, patch proposal extraction, retries, and policy validation.
+
+## Install
+
+```bash
+npm install @x12i/openrouter-runtime
+```
+
+## Usage
+
+```ts
+import { createOpenRouterRuntime } from "@x12i/openrouter-runtime";
+
+const runtime = createOpenRouterRuntime({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  defaults: {
+    serverTools: {
+      datetime: { mode: "allowed", timezone: "Asia/Jerusalem" }
+    }
+  }
+});
+
+const response = await runtime.run({
+  model: "openai/gpt-5.2",
+  messages: [{ role: "user", content: "What time is it?" }]
+});
+
+console.log(response.text);
+```
+
+## Console logging
+
+Turn on runtime console logs with:
+
+```bash
+OPENROUTER_RUNTIME_LOGS=true
+```
+
+When that env var is `true` / `1` / `yes` / `on`, and you do not pass a custom `logger`, the runtime logs to the console:
+
+- `runtime.request.started` — includes `streaming: false` and `entrypoint: "run"`
+- `runtime.request.compiled` — includes `bodyStream: false` and any streaming-related warning codes
+- `runtime.response.normalized`
+- `runtime.executeStreamingChat.called` — if someone hits the reserved streaming method
+- provider retry / function-tool events
+
+This package does **not** auto-load `.env`. Put the vars in your environment (shell export, process manager, or host `dotenv`) before calling `createOpenRouterRuntime()`. See `.env.example`.
+
+Example:
+
+```bash
+OPEN_ROUTER_KEY=sk-or-...
+OPENROUTER_RUNTIME_LOGS=true
+```
+
+You can still pass an explicit `logger` to override the console logger.
+
+## App name and metadata
+
+`agentId` is optional. When it is set, OpenRouter's activity log shows it in the **App** column. The runtime sends that value as `X-Title` and `X-OpenRouter-Title`, after `defaultHeaders`, so it wins over `appAttribution.appName` for that call. `appAttribution.siteUrl` is still sent as `HTTP-Referer` when set. Omit `agentId` when you do not have one.
+
+`metadata` is optional. String, number, and boolean values, plus `agentId`, are stored as one record on the request `metadata` object: `m.0`, `m.1`, and so on. Read it back with `decodeProviderMetadata`. The original `metadata` object is still copied onto the normalized response. Objects and arrays are not stored in the record. The record must fit in 16 pieces of 256 characters.
+
+```ts
+await runtime.run({
+  model: "openai/gpt-5.2",
+  prompt: "Explain the tradeoff in one paragraph.",
+  agentId: "agent-42",
+  metadata: { sessionId: "s-1" }
+});
+```
+
+## Server Tools
+
+Enable OpenRouter server tools through `serverTools`:
+
+```ts
+await runtime.run({
+  model: "anthropic/claude-sonnet-4",
+  messages: [{ role: "user", content: "Research recent OpenRouter web search changes." }],
+  serverTools: {
+    webSearch: { mode: "required", maxResults: 5 },
+    webFetch: { mode: "allowed", maxContentTokens: 50000 }
+  }
+});
+```
+
+### Citation Policy
+
+`defaults.requireCitationsWhenSearchUsed` controls the package-wide default for web-search citation enforcement. A request-level `serverTools.webSearch.requireCitations` value overrides that default:
+
+- `requireCitations: true`: if web search is used and no citations are extracted, the runtime emits `CITATIONS_REQUIRED_BUT_MISSING`.
+- `requireCitations: false`: disables citation enforcement for that request, even if the global default is `true`.
+
+When `defaults.onPolicyViolation` is `"throw"`, citation policy failures are returned as `errors[]` with `source: "policy"` and `status: "policy_violation"`. When it is `"return_error"`, they remain in `warnings[]`.
+
+`applyPatch` automatically selects the Responses API. The runtime returns patch proposals and never mutates files unless an explicit `patchApplier` is supplied.
+
+## Function Tools
+
+```ts
+const runtime = createOpenRouterRuntime({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  tools: {
+    getCustomerRisk: async (args) => ({ score: 82, args })
+  }
+});
+```
+
+Function calls are executed locally and looped back to OpenRouter until a final response is produced or `maxToolIterations` is reached.
+
+## Streaming
+
+Streaming is a **separate API**. It is never an argument on `run()`, never the default, and never available through the removed `stream()` name.
+
+### `run()` — non-streaming only
+
+```ts
+const response = await runtime.run({
+  model: "openai/gpt-5.2",
+  prompt: "Summarize this document."
+});
+```
+
+- Always sends `stream: false`
+- Returns a completed `RuntimeResponse`
+- Use for tools, research, extraction, patches, automation
+
+Any truthy `rawOpenRouterOverrides.stream` is overwritten (`STREAMING_OVERRIDE_IGNORED_FOR_RUN`). Nested `advisor.stream` is forced off (`ADVISOR_STREAMING_IGNORED_FOR_RUN`).
+
+### `executeStreamingChat()` — streaming only
+
+```ts
+for await (const event of runtime.executeStreamingChat({
+  model: "openai/gpt-5.2",
+  prompt: "Say hello"
+})) {
+  if (event.type === "stream.text.delta") {
+    process.stdout.write(event.data.text);
+  }
+  if (event.type === "stream.done") {
+    console.log("\nfinal:", event.data.text);
+  }
+}
+```
+
+- Always sends `stream: true` (Chat Completions SSE)
+- Yields typed events: `stream.start`, `stream.text.delta`, `stream.tool_call.delta`, `stream.usage`, `stream.warning`, `stream.error`, `stream.done`
+- Chat Completions only — Responses / `applyPatch` must use `run()`
+- Local function-tool loops are not run here; use `run()` for tool iteration
+
+| Method | Streaming? | Notes |
+| --- | --- | --- |
+| `runtime.run(request)` | No | Default execution path |
+| `runtime.executeStreamingChat(request)` | Yes | Explicit streaming API |
+| `runtime.stream(request)` | — | **Removed** — breaks by design |