@rarebit-one/harness-kernel 0.10.0 → 0.11.0-next.0

package/dist/providers/mock.d.ts

@@ -1,9 +1,10 @@
 import type { CompletionRequest, ConverseOptions, ConverseRequest, ConverseResult, Provider } from "./types.js";
 import type { ProviderSelection } from "./index.js";
 /**
- * Deterministic, offline provider. Used when no API key is configured — or when a
- * workflow explicitly asks for `preferred: mock` — so the end-to-end loop (and
- * tests) run without network access or credentials.
+ * Deterministic, offline provider. Used when a workflow explicitly asks for
+ * `preferred: mock`, or when a caller opts into `allowMockFallback` and no key
+ * is configured, so the end-to-end loop (and tests) run without network access
+ * or credentials. It accepts and ignores `providerOptions`: it is the dry run.
  *
  * It cannot call a model, but it is handed the SAME provider selection a real
  * provider would receive (the resolved per-run model + per-org BYO keys) and
@@ -14,6 +15,8 @@ import type { ProviderSelection } from "./index.js";
  */
 export declare class MockProvider implements Provider {
     readonly name = "mock";
+    /** The model the caller resolved, when it resolved one; the mock calls nothing. */
+    readonly model?: string;
     private readonly selection;
     constructor(selection?: ProviderSelection);
     private resolvedModel;

package/dist/providers/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,QAAQ,CAAC,IAAI,UAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,SAAS,GAAE,iBAAsB;IAS7C,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,cAAc;IAWtB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B3C,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAWtF"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,QAAQ,CAAC,IAAI,UAAS;IACtB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,SAAS,GAAE,iBAAsB;IAU7C,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,cAAc;IAWtB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B3C,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAWtF"}

package/dist/providers/mock.js

@@ -1,7 +1,8 @@
 /**
- * Deterministic, offline provider. Used when no API key is configured — or when a
- * workflow explicitly asks for `preferred: mock` — so the end-to-end loop (and
- * tests) run without network access or credentials.
+ * Deterministic, offline provider. Used when a workflow explicitly asks for
+ * `preferred: mock`, or when a caller opts into `allowMockFallback` and no key
+ * is configured, so the end-to-end loop (and tests) run without network access
+ * or credentials. It accepts and ignores `providerOptions`: it is the dry run.
  *
  * It cannot call a model, but it is handed the SAME provider selection a real
  * provider would receive (the resolved per-run model + per-org BYO keys) and
@@ -12,9 +13,13 @@
  */
 export class MockProvider {
     name = "mock";
+    /** The model the caller resolved, when it resolved one; the mock calls nothing. */
+    model;
     selection;
     constructor(selection = {}) {
         this.selection = selection;
+        if (selection.model)
+            this.model = selection.model;
     }
     // "What a real provider would have used" for the model: the model the caller
     // resolved (workflow YAML → org default), else the host's

package/dist/providers/mock.js.map

@@ -1 +1 @@
-{"version":3,"file":"mock.js","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAY;IACd,IAAI,GAAG,MAAM,CAAA;IACL,SAAS,CAAmB;IAE7C,YAAY,YAA+B,EAAE;QAC3C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;IAED,6EAA6E;IAC7E,0DAA0D;IAC1D,sEAAsE;IACtE,+EAA+E;IAC/E,gFAAgF;IACxE,aAAa;QACnB,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;QACpF,MAAM,QAAQ,GACZ,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAA;QACzF,IAAI,QAAQ;YAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAA;QACtE,OAAO,EAAE,KAAK,EAAE,6BAA6B,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAA;IACtF,CAAC;IAED,gFAAgF;IAChF,gFAAgF;IAChF,sCAAsC;IAC9B,YAAY;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,IAAI,EAAE,CAAA;QAC9C,MAAM,OAAO,GAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,YAAY,CAAW;aAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC7C,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,uCAAuC,CAAA;IACtF,CAAC;IAED,gFAAgF;IACxE,cAAc;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAA;QAClC,OAAO;YACL,wCAAwC;YACxC,EAAE;YACF,UAAU,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,kBAAkB;YACxD,gBAAgB,IAAI,CAAC,YAAY,EAAE,EAAE;YACrC,EAAE;SACH,CAAA;IACH,CAAC;IAED,QAAQ,CAAC,GAAsB;QAC7B,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;QACxC,OAAO,OAAO,CAAC,OAAO,CACpB;YACE,mCAAmC;YACnC,EAAE;YACF,+EAA+E;YAC/E,yCAAyC;YACzC,EAAE;YACF,GAAG,IAAI,CAAC,cAAc,EAAE;YACxB,WAAW;YACX,EAAE;YACF,GAAG,CAAC,MAAM;YACV,EAAE;YACF,+BAA+B;YAC/B,EAAE;YACF,KAAK;YACL,OAAO;YACP,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAA;IACH,CAAC;IAED,8EAA8E;IAC9E,0EAA0E;IAC1E,2EAA2E;IAC3E,wDAAwD;IACxD,KAAK,CAAC,QAAQ,CAAC,GAAoB,EAAE,IAAsB;QACzD,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;QAC9B,MAAM,QAAQ,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAA;QAC3E,MAAM,MAAM,GAAG,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;QACxE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;YAC/B,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE;YAClG,MAAM;SACP,CAAC,CAAA;QACF,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;QAC9B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;IAChC,CAAC;CACF"}
+{"version":3,"file":"mock.js","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai.d.ts

@@ -1,15 +1,31 @@
 import OpenAI from "openai";
 import type { TokenUsage } from "../models/types.js";
+import { type CacheTtl } from "./options.js";
 import type { AgentMessage, CompletionRequest, ConverseOptions, ConverseRequest, ConverseResult, Provider } from "./types.js";
-/** Map provider-neutral messages to OpenAI chat messages (pure; tested). */
-export declare function toOpenAIMessages(messages: AgentMessage[]): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+/** Where to put message breakpoints: how many trailing messages, and the lifetime. */
+export interface OpenAIMessageCache {
+    trailingMessages: number;
+    ttl?: CacheTtl;
+}
+/**
+ * Map provider-neutral messages to OpenAI chat messages (pure; tested).
+ *
+ * With `cache` set (OpenRouter), the trailing N messages are sent as content
+ * parts with a `cache_control` breakpoint on their text. An assistant message
+ * with no prose has nowhere to put one and is left as it was; a tool message
+ * puts it on its last result. Messages outside the window keep the plain
+ * string form.
+ */
+export declare function toOpenAIMessages(messages: AgentMessage[], cache?: OpenAIMessageCache): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
 /** Reduce an OpenAI response message to text + tool calls (pure; tested). */
 export declare function parseOpenAIMessage(message: OpenAI.Chat.Completions.ChatCompletionMessage): ConverseResult;
 /**
- * Map an OpenAI `usage` block to the kernel's token accounting (pure; tested).
- * `prompt_tokens` already includes cached input, so it maps to `inputTokens`
- * as-is and `cached_tokens` is the cache-read breakdown. OpenAI's automatic
- * caching reports no separate write count.
+ * Map an OpenAI-dialect `usage` block to the kernel's token accounting (pure;
+ * tested). `prompt_tokens` already includes cached input, so it maps to
+ * `inputTokens` as-is and `cached_tokens` is the cache-read breakdown. OpenAI
+ * reports no write count; OpenRouter does (`cache_write_tokens`), and prices
+ * the call (`cost`), so both are carried when present. Reasoning tokens are
+ * the `completion_tokens_details` breakdown either side reports.
  */
 export declare function openAIUsage(usage: OpenAI.Completions.CompletionUsage | null | undefined): TokenUsage | undefined;
 /** Constructor options for an OpenAI-compatible (chat.completions) provider. */
@@ -25,6 +41,34 @@ export interface OpenAICompatibleOptions {
      */
     defaultHeaders?: Record<string, string | null>;
 }
+/** The adapter names whose dialect differences this core knows about. */
+export declare const OPENAI_ADAPTER = "openai";
+export declare const OPENROUTER_ADAPTER = "openrouter";
+/**
+ * The chat.completions request body plus the fields OpenRouter adds to the
+ * dialect (`models`, `provider`, `usage`, `transforms`). The SDK forwards
+ * unknown body fields untouched, so they are typed here as an extension rather
+ * than cast away at the call site.
+ */
+export type OpenAICompatibleBody = OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming & {
+    models?: string[];
+    provider?: Record<string, unknown>;
+    usage?: {
+        include: boolean;
+    };
+    transforms?: string[];
+};
+/**
+ * Build the chat.completions request for one conversation step (pure; tested).
+ *
+ * `name` selects the dialect: `openrouter` accepts the `openrouter` options
+ * block and places prompt-cache breakpoints as content parts; `openai` maps
+ * `promptCache.key` onto `prompt_cache_key` (its caching is otherwise
+ * automatic, so breakpoints have nothing to attach to); any other name (local
+ * servers, custom endpoints) gets the plain dialect and rejects the
+ * OpenRouter block.
+ */
+export declare function openAICompatibleRequestBody(name: string, model: string, req: ConverseRequest, fallbackMaxTokens?: number): OpenAICompatibleBody;
 /**
  * Shared core for providers speaking the OpenAI chat.completions dialect
  * (including tools). OpenAI proper and OpenRouter both instantiate this —
@@ -33,8 +77,8 @@ export interface OpenAICompatibleOptions {
 export declare class OpenAICompatibleProvider implements Provider {
     readonly name: string;
     readonly reportsUsage = true;
+    readonly model: string;
     private client;
-    private model;
     constructor(name: string, opts: OpenAICompatibleOptions);
     complete(req: CompletionRequest): Promise<string>;
     converse(req: ConverseRequest, opts?: ConverseOptions): Promise<ConverseResult>;

package/dist/providers/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACd,QAAQ,EAET,MAAM,YAAY,CAAA;AAEnB,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,GACvB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,0BAA0B,EAAE,CA0BtD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,qBAAqB,GACrD,cAAc,CAchB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe,GAAG,IAAI,GAAG,SAAS,GAC3D,UAAU,GAAG,SAAS,CASxB;AAaD,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAC/C;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,QAAQ;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,YAAY,QAAO;IAC5B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,KAAK,CAAQ;gBAET,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB;IAejD,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAajD,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAsBtF;AAED,qBAAa,cAAe,SAAQ,wBAAwB;gBAC9C,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwC;CAG1E"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD,OAAO,EAKL,KAAK,QAAQ,EAEd,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACd,QAAQ,EAET,MAAM,YAAY,CAAA;AAgBnB,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,MAAM,CAAA;IACxB,GAAG,CAAC,EAAE,QAAQ,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,CAAC,EAAE,kBAAkB,GACzB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,0BAA0B,EAAE,CAkCtD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,qBAAqB,GACrD,cAAc,CAchB;AAcD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe,GAAG,IAAI,GAAG,SAAS,GAC3D,UAAU,GAAG,SAAS,CAkBxB;AAaD,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAC/C;AAED,yEAAyE;AACzE,eAAO,MAAM,cAAc,WAAW,CAAA;AACtC,eAAO,MAAM,kBAAkB,eAAe,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC9B,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,sCAAsC,GAAG;IAC/D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB,CAAA;AAEH;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,eAAe,EACpB,iBAAiB,GAAE,MAAoB,GACtC,oBAAoB,CA2CtB;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,QAAQ;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,YAAY,QAAO;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,MAAM,CAAQ;gBAEV,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB;IAejD,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBjD,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CA6BtF;AAED,qBAAa,cAAe,SAAQ,wBAAwB;gBAC9C,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwC;CAG1E"}

package/dist/providers/openai.js

@@ -1,16 +1,30 @@
 import OpenAI from "openai";
 import { maxTokens, providerMaxRetries, providerTimeoutMs } from "./clientOptions.js";
-/** Map provider-neutral messages to OpenAI chat messages (pure; tested). */
-export function toOpenAIMessages(messages) {
+import { rejectOption, resolveMaxRetries, resolveMaxTokens, resolvePromptCache, } from "./options.js";
+function cachedPart(text, ttl) {
+    return { type: "text", text, cache_control: { type: "ephemeral", ...(ttl ? { ttl } : {}) } };
+}
+/**
+ * Map provider-neutral messages to OpenAI chat messages (pure; tested).
+ *
+ * With `cache` set (OpenRouter), the trailing N messages are sent as content
+ * parts with a `cache_control` breakpoint on their text. An assistant message
+ * with no prose has nowhere to put one and is left as it was; a tool message
+ * puts it on its last result. Messages outside the window keep the plain
+ * string form.
+ */
+export function toOpenAIMessages(messages, cache) {
     const out = [];
-    for (const m of messages) {
+    const firstCached = cache ? Math.max(0, messages.length - cache.trailingMessages) : Infinity;
+    messages.forEach((m, index) => {
+        const mark = cache !== undefined && index >= firstCached;
         if (m.role === "user") {
-            out.push({ role: "user", content: m.text });
+            out.push({ role: "user", content: mark ? [cachedPart(m.text, cache.ttl)] : m.text });
         }
         else if (m.role === "assistant") {
             const msg = {
                 role: "assistant",
-                content: m.text,
+                content: mark && m.text ? [cachedPart(m.text, cache.ttl)] : m.text,
             };
             if (m.toolCalls.length > 0) {
                 msg.tool_calls = m.toolCalls.map((tc) => ({
@@ -22,12 +36,18 @@ export function toOpenAIMessages(messages) {
             out.push(msg);
         }
         else {
-            // Each tool result becomes its own `tool` message keyed by the call id.
-            for (const r of m.results) {
-                out.push({ role: "tool", tool_call_id: r.toolCallId, content: r.content });
-            }
+            // Each tool result becomes its own `tool` message keyed by the call id;
+            // the breakpoint goes on the last one so the whole batch sits inside it.
+            m.results.forEach((r, i) => {
+                const last = i === m.results.length - 1;
+                out.push({
+                    role: "tool",
+                    tool_call_id: r.toolCallId,
+                    content: mark && last ? [cachedPart(r.content, cache.ttl)] : r.content,
+                });
+            });
         }
-    }
+    });
     return out;
 }
 /** Reduce an OpenAI response message to text + tool calls (pure; tested). */
@@ -48,20 +68,31 @@ export function parseOpenAIMessage(message) {
     return { text, toolCalls };
 }
 /**
- * Map an OpenAI `usage` block to the kernel's token accounting (pure; tested).
- * `prompt_tokens` already includes cached input, so it maps to `inputTokens`
- * as-is and `cached_tokens` is the cache-read breakdown. OpenAI's automatic
- * caching reports no separate write count.
+ * Map an OpenAI-dialect `usage` block to the kernel's token accounting (pure;
+ * tested). `prompt_tokens` already includes cached input, so it maps to
+ * `inputTokens` as-is and `cached_tokens` is the cache-read breakdown. OpenAI
+ * reports no write count; OpenRouter does (`cache_write_tokens`), and prices
+ * the call (`cost`), so both are carried when present. Reasoning tokens are
+ * the `completion_tokens_details` breakdown either side reports.
  */
 export function openAIUsage(usage) {
     if (!usage)
         return undefined;
+    const extended = usage;
     const cached = usage.prompt_tokens_details?.cached_tokens ?? 0;
+    const written = extended.prompt_tokens_details?.cache_write_tokens ?? 0;
+    const reasoning = usage.completion_tokens_details?.reasoning_tokens ?? 0;
+    const cost = extended.cost;
     return {
         inputTokens: usage.prompt_tokens,
         outputTokens: usage.completion_tokens,
         totalTokens: usage.total_tokens,
         ...(cached > 0 ? { cacheReadTokens: cached } : {}),
+        ...(written > 0 ? { cacheWriteTokens: written } : {}),
+        ...(reasoning > 0 ? { reasoningTokens: reasoning } : {}),
+        ...(typeof cost === "number" && Number.isFinite(cost)
+            ? { reportedCost: { amount: cost, currency: "USD" } }
+            : {}),
     };
 }
 /** Parse a tool-call arguments JSON string, tolerating empty/invalid input. */
@@ -76,6 +107,64 @@ function parseArguments(raw) {
         return {};
     }
 }
+/** The adapter names whose dialect differences this core knows about. */
+export const OPENAI_ADAPTER = "openai";
+export const OPENROUTER_ADAPTER = "openrouter";
+/**
+ * Build the chat.completions request for one conversation step (pure; tested).
+ *
+ * `name` selects the dialect: `openrouter` accepts the `openrouter` options
+ * block and places prompt-cache breakpoints as content parts; `openai` maps
+ * `promptCache.key` onto `prompt_cache_key` (its caching is otherwise
+ * automatic, so breakpoints have nothing to attach to); any other name (local
+ * servers, custom endpoints) gets the plain dialect and rejects the
+ * OpenRouter block.
+ */
+export function openAICompatibleRequestBody(name, model, req, fallbackMaxTokens = maxTokens()) {
+    const options = req.providerOptions;
+    const isOpenRouter = name === OPENROUTER_ADAPTER;
+    if (!isOpenRouter)
+        rejectOption(name, options, "openrouter");
+    const cache = options?.promptCache
+        ? resolvePromptCache(options.promptCache)
+        : undefined;
+    const ttl = cache?.ttl;
+    const tools = req.tools.map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.inputSchema },
+    }));
+    const system = isOpenRouter && cache?.system && req.system
+        ? { role: "system", content: [cachedPart(req.system, ttl)] }
+        : { role: "system", content: req.system };
+    const messageCache = isOpenRouter && cache && cache.trailingMessages > 0
+        ? { trailingMessages: cache.trailingMessages, ...(ttl ? { ttl } : {}) }
+        : undefined;
+    // OpenAI retired `max_tokens` in favour of `max_completion_tokens` (its
+    // reasoning models reject the old name); OpenRouter and the local servers
+    // document `max_tokens`, so each dialect gets the field it names.
+    const cap = resolveMaxTokens(options, fallbackMaxTokens);
+    const body = {
+        model,
+        ...(name === OPENAI_ADAPTER ? { max_completion_tokens: cap } : { max_tokens: cap }),
+        messages: [system, ...toOpenAIMessages(req.messages, messageCache)],
+        ...(tools.length > 0 ? { tools } : {}),
+        ...(options?.responseFormat ? { response_format: options.responseFormat } : {}),
+    };
+    if (name === OPENAI_ADAPTER && cache?.key)
+        body.prompt_cache_key = cache.key;
+    if (isOpenRouter && options?.openrouter) {
+        const or = options.openrouter;
+        if (or.models)
+            body.models = or.models;
+        if (or.provider)
+            body.provider = { ...or.provider };
+        if (or.usage)
+            body.usage = or.usage;
+        if (or.transforms)
+            body.transforms = or.transforms;
+    }
+    return body;
+}
 /**
  * Shared core for providers speaking the OpenAI chat.completions dialect
  * (including tools). OpenAI proper and OpenRouter both instantiate this —
@@ -84,8 +173,8 @@ function parseArguments(raw) {
 export class OpenAICompatibleProvider {
     name;
     reportsUsage = true;
-    client;
     model;
+    client;
     constructor(name, opts) {
         // The SDK retries transient 429/5xx/network errors with exponential backoff
         // internally, so a blip doesn't fail the whole run; `timeout` bounds each
@@ -103,7 +192,10 @@ export class OpenAICompatibleProvider {
     async complete(req) {
         const completion = await this.client.chat.completions.create({
             model: this.model,
-            max_tokens: maxTokens(), // match AnthropicProvider rather than the model default
+            // Same field rule as `converse`: OpenAI's current name, the documented one elsewhere.
+            ...(this.name === OPENAI_ADAPTER
+                ? { max_completion_tokens: maxTokens() }
+                : { max_tokens: maxTokens() }),
             messages: [
                 { role: "system", content: req.system },
                 { role: "user", content: req.prompt },
@@ -112,27 +204,33 @@ export class OpenAICompatibleProvider {
         return completion.choices[0]?.message?.content ?? "";
     }
     async converse(req, opts) {
-        const tools = req.tools.map((t) => ({
-            type: "function",
-            function: { name: t.name, description: t.description, parameters: t.inputSchema },
-        }));
-        const completion = await this.client.chat.completions.create({
-            model: this.model,
-            max_tokens: maxTokens(), // match AnthropicProvider rather than the model default
-            messages: [{ role: "system", content: req.system }, ...toOpenAIMessages(req.messages)],
-            ...(tools.length > 0 ? { tools } : {}),
-        }, 
-        // Per-request, so an abort cancels THIS call (retries included).
-        opts?.signal ? { signal: opts.signal } : undefined);
+        // Per-request options, so an abort cancels THIS call (retries included)
+        // and a per-call retry count leaves the shared client untouched.
+        const retries = resolveMaxRetries(req.providerOptions);
+        const completion = await this.client.chat.completions.create(openAICompatibleRequestBody(this.name, this.model, req), {
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...(retries !== undefined ? { maxRetries: retries } : {}),
+        });
         const usage = openAIUsage(completion.usage);
         const message = completion.choices[0]?.message;
         const parsed = message ? parseOpenAIMessage(message) : { text: "", toolCalls: [] };
-        return { ...parsed, ...(usage ? { usage } : {}) };
+        // OpenRouter adds a top-level `provider` naming the upstream that served
+        // the request; the SDK's response type does not know it, so read it loosely.
+        const upstream = this.name === OPENROUTER_ADAPTER ? completion.provider : undefined;
+        return {
+            ...parsed,
+            ...(usage ? { usage } : {}),
+            ...(typeof completion.model === "string" && completion.model
+                ? { model: completion.model }
+                : {}),
+            ...(typeof completion.id === "string" && completion.id ? { responseId: completion.id } : {}),
+            ...(typeof upstream === "string" && upstream ? { upstream } : {}),
+        };
     }
 }
 export class OpenAIProvider extends OpenAICompatibleProvider {
     constructor(apiKey, model = process.env.OPENAI_MODEL ?? "gpt-4.1") {
-        super("openai", { apiKey, model });
+        super(OPENAI_ADAPTER, { apiKey, model });
     }
 }
 //# sourceMappingURL=openai.js.map

package/dist/providers/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAE3B,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACrF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GAGnB,MAAM,cAAc,CAAA;AAqBrB,SAAS,UAAU,CAAC,IAAY,EAAE,GAAyB;IACzD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAA;AAC9F,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAwB,EACxB,KAA0B;IAE1B,MAAM,GAAG,GAAyD,EAAE,CAAA;IACpE,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;IAC5F,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,WAAW,CAAA;QACxD,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACtB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;QACtF,CAAC;aAAM,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,GAAG,GAAgE;gBACvE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;aACnE,CAAA;YACD,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBACxC,EAAE,EAAE,EAAE,CAAC,EAAE;oBACT,IAAI,EAAE,UAAU;oBAChB,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE;iBACjE,CAAC,CAAC,CAAA;YACL,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACf,CAAC;aAAM,CAAC;YACN,wEAAwE;YACxE,yEAAyE;YACzE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBACzB,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAA;gBACvC,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,MAAM;oBACZ,YAAY,EAAE,CAAC,CAAC,UAAU;oBAC1B,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;iBACvE,CAAC,CAAA;YACJ,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CAAC,CAAA;IACF,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB,CAChC,OAAsD;IAEtD,+EAA+E;IAC/E,+EAA+E;IAC/E,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACtF,MAAM,SAAS,GAAe,EAAE,CAAA;IAChC,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC1C,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU;YAAE,SAAQ;QACpC,SAAS,CAAC,IAAI,CAAC;YACb,EAAE,EAAE,EAAE,CAAC,EAAE;YACT,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI;YACtB,KAAK,EAAE,cAAc,CAAC,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;SAC7C,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;AAC5B,CAAC;AAcD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,KAA4D;IAE5D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,MAAM,QAAQ,GAAG,KAAsB,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,CAAC,qBAAqB,EAAE,aAAa,IAAI,CAAC,CAAA;IAC9D,MAAM,OAAO,GAAG,QAAQ,CAAC,qBAAqB,EAAE,kBAAkB,IAAI,CAAC,CAAA;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,yBAAyB,EAAE,gBAAgB,IAAI,CAAC,CAAA;IACxE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAA;IAC1B,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,aAAa;QAChC,YAAY,EAAE,KAAK,CAAC,iBAAiB;QACrC,WAAW,EAAE,KAAK,CAAC,YAAY;QAC/B,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YACnD,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;YACrD,CAAC,CAAC,EAAE,CAAC;KACR,CAAA;AACH,CAAC;AAED,+EAA+E;AAC/E,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACvC,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,EAAE,CAAA;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC;AAgBD,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAA;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAA;AAgB9C;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAY,EACZ,KAAa,EACb,GAAoB,EACpB,oBAA4B,SAAS,EAAE;IAEvC,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,CAAA;IACnC,MAAM,YAAY,GAAG,IAAI,KAAK,kBAAkB,CAAA;IAChD,IAAI,CAAC,YAAY;QAAE,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,CAAA;IAC5D,MAAM,KAAK,GAAoC,OAAO,EAAE,WAAW;QACjE,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,WAAW,CAAC;QACzC,CAAC,CAAC,SAAS,CAAA;IACb,MAAM,GAAG,GAAG,KAAK,EAAE,GAAG,CAAA;IAEtB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAA8C,EAAE,CAAC,CAAC;QAC9E,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,WAAW,EAAE;KAClF,CAAC,CAAC,CAAA;IAEH,MAAM,MAAM,GACV,YAAY,IAAI,KAAK,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM;QACzC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE;QAC5D,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAA;IAC7C,MAAM,YAAY,GAChB,YAAY,IAAI,KAAK,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC;QACjD,CAAC,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;QACvE,CAAC,CAAC,SAAS,CAAA;IAEf,wEAAwE;IACxE,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;IACxD,MAAM,IAAI,GAAyB;QACjC,KAAK;QACL,GAAG,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QACnF,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QACnE,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAA;IACD,IAAI,IAAI,KAAK,cAAc,IAAI,KAAK,EAAE,GAAG;QAAE,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC,GAAG,CAAA;IAC5E,IAAI,YAAY,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;QACxC,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAA;QAC7B,IAAI,EAAE,CAAC,MAAM;YAAE,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAA;QACtC,IAAI,EAAE,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAA;QACnD,IAAI,EAAE,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAA;QACnC,IAAI,EAAE,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAAA;IACpD,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,wBAAwB;IAC1B,IAAI,CAAQ;IACZ,YAAY,GAAG,IAAI,CAAA;IACnB,KAAK,CAAQ;IACd,MAAM,CAAQ;IAEtB,YAAY,IAAY,EAAE,IAA6B;QACrD,4EAA4E;QAC5E,0EAA0E;QAC1E,qCAAqC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,iBAAiB,EAAE;YAC5B,UAAU,EAAE,kBAAkB,EAAE;YAChC,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,IAAI,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtF,CAAC,CAAA;QACF,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,GAAsB;QACnC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;YAC3D,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,sFAAsF;YACtF,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc;gBAC9B,CAAC,CAAC,EAAE,qBAAqB,EAAE,SAAS,EAAE,EAAE;gBACxC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,CAAC;YAChC,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;gBACvC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;aACtC;SACF,CAAC,CAAA;QAEF,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAA;IACtD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,GAAoB,EAAE,IAAsB;QACzD,wEAAwE;QACxE,iEAAiE;QACjE,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;QACtD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAC1D,2BAA2B,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,EACvD;YACE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1D,CACF,CAAA;QAED,MAAM,KAAK,GAAG,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;QAC3C,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAA;QAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;QAClF,yEAAyE;QACzE,6EAA6E;QAC7E,MAAM,QAAQ,GACZ,IAAI,CAAC,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAE,UAAqC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;QAChG,OAAO;YACL,GAAG,MAAM;YACT,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK;gBAC1D,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE;gBAC7B,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,UAAU,CAAC,EAAE,KAAK,QAAQ,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5F,GAAG,CAAC,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE,CAAA;IACH,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,wBAAwB;IAC1D,YAAY,MAAc,EAAE,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,SAAS;QACvE,KAAK,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1C,CAAC;CACF"}

package/dist/providers/options.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Per-call provider options: the typed passthrough from a caller to the adapter
+ * that makes the HTTP request.
+ *
+ * Two kinds of thing live here, and the split is deliberate:
+ *
+ *   - **Neutral options** (`maxTokens`, `promptCache`, `responseFormat`) name an
+ *     intent, and each adapter maps it onto its own wire format as well as it
+ *     can. Prompt caching is the clearest case: Anthropic wants explicit
+ *     `cache_control` breakpoints, OpenRouter wants them inside content parts,
+ *     OpenAI caches prefixes automatically and only takes a routing key.
+ *   - **Adapter-addressed options** (`openrouter`) carry one API's own
+ *     vocabulary verbatim, snake_case and all, because translating them would
+ *     only add a place for the two to drift.
+ *
+ * Either way, an option an adapter cannot honour is an error, never a silent
+ * drop: a caller that asked for zero-data-retention routing and got a request
+ * that said nothing about it would have no way to notice.
+ */
+/** How long a cache breakpoint keeps its entry alive (Anthropic and OpenRouter). */
+export type CacheTtl = "5m" | "1h";
+/**
+ * Where to place prompt-cache breakpoints. Every field is optional; passing
+ * `promptCache: {}` means "cache this prompt the usual way": the system prompt,
+ * the tool definitions and the last message, so the next call in the same
+ * conversation reads the whole prefix from cache.
+ *
+ * Breakpoints exist on Anthropic (`cache_control`) and OpenRouter (content
+ * parts). The `openai` adapter has no breakpoints to place (its caching is
+ * automatic over the prefix) and honours only `key`; the `local` adapter and
+ * any custom OpenAI-compatible endpoint accept the option and leave caching to
+ * the server's own prefix cache. Those two are best effort by design rather
+ * than an error: "cache this prompt" is an intent every adapter can honour as
+ * well as its API allows, unlike an option addressed to a different API.
+ */
+export interface PromptCacheOptions {
+    /** Breakpoint after the system prompt. Default `true`. */
+    system?: boolean;
+    /** Breakpoint after the tool definitions (Anthropic only). Default `true`. */
+    tools?: boolean;
+    /**
+     * How many trailing messages get a breakpoint on their last content block.
+     * Default 1; clamped to {@link MAX_TRAILING_CACHE_MESSAGES} because Anthropic
+     * allows four breakpoints per request and two are spent on system and tools.
+     */
+    trailingMessages?: number;
+    /** Cache lifetime for every breakpoint this call places. Default is the provider's (`5m`). */
+    ttl?: CacheTtl;
+    /** OpenAI `prompt_cache_key`: routes requests sharing a prefix to the same cache. */
+    key?: string;
+}
+/** Anthropic's breakpoint ceiling is four; two go to system and tools. */
+export declare const MAX_TRAILING_CACHE_MESSAGES = 2;
+/** The resolved form of {@link PromptCacheOptions}: every default applied. */
+export interface ResolvedPromptCache {
+    system: boolean;
+    tools: boolean;
+    trailingMessages: number;
+    ttl?: CacheTtl;
+    key?: string;
+}
+/** Apply the defaults and the clamp. */
+export declare function resolvePromptCache(options: PromptCacheOptions): ResolvedPromptCache;
+/**
+ * The OpenAI chat.completions `response_format` shape, which OpenRouter and most
+ * OpenAI-compatible servers accept as-is. The Anthropic adapter rejects it: the
+ * Messages API has no equivalent field, and a structured answer there is a
+ * terminal tool with a schema.
+ */
+export type ResponseFormat = {
+    type: "text";
+} | {
+    type: "json_object";
+} | {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        description?: string;
+        schema?: Record<string, unknown>;
+        strict?: boolean | null;
+    };
+};
+/**
+ * OpenRouter's `provider` routing preferences, passed through verbatim (hence
+ * snake_case: these are OpenRouter's own field names). `data_collection: "deny"`
+ * and `zdr: true` are the data-policy knobs: the first excludes upstreams that
+ * may store or train on prompts, the second restricts routing to upstreams
+ * with a zero-data-retention policy.
+ */
+export interface OpenRouterProviderPreferences {
+    /** Upstreams to try, in order. */
+    order?: string[];
+    /** Only these upstreams may serve the request. */
+    only?: string[];
+    /** Never route to these upstreams. */
+    ignore?: string[];
+    /** Whether to fall back past `order` when those upstreams fail. */
+    allow_fallbacks?: boolean;
+    /** Only route to upstreams that support every parameter in the request. */
+    require_parameters?: boolean;
+    /** `deny` excludes upstreams that may store or train on the prompt. */
+    data_collection?: "allow" | "deny";
+    /** Restrict routing to upstreams with a zero-data-retention policy. */
+    zdr?: boolean;
+    /** Routing priority when several upstreams qualify. */
+    sort?: "price" | "throughput" | "latency" | (string & {});
+    /** Acceptable quantization levels, e.g. `["fp16", "bf16"]`. */
+    quantizations?: string[];
+    /** Price ceilings per million tokens, in OpenRouter's own keys (`prompt`, `completion`, …). */
+    max_price?: Record<string, number>;
+}
+/** Options only the OpenRouter adapter can honour. */
+export interface OpenRouterOptions {
+    /** Fallback model ids, tried in order when the primary model fails or is unavailable. */
+    models?: string[];
+    /** Upstream routing and data-policy preferences. */
+    provider?: OpenRouterProviderPreferences;
+    /** `{ include: true }` asks for token accounting (incl. cache reads) in the response. */
+    usage?: {
+        include: boolean;
+    };
+    /** OpenRouter prompt transforms, e.g. `["middle-out"]`. */
+    transforms?: string[];
+}
+/** Everything a caller may hand an adapter for one request. */
+export interface ProviderOptions {
+    /** Completion token cap for this call; overrides `RUNNER_MAX_TOKENS`. */
+    maxTokens?: number;
+    /**
+     * SDK retry count for this call; overrides `RUNNER_PROVIDER_MAX_RETRIES`.
+     * Set `0` when the request carries its own fallback chain (OpenRouter
+     * `models`), so a transient upstream failure is not retried by the SDK and
+     * then again by the router.
+     */
+    maxRetries?: number;
+    /** Prompt caching. Each adapter maps it onto its own mechanism. */
+    promptCache?: PromptCacheOptions;
+    /** Structured-output format (OpenAI-compatible adapters only). */
+    responseFormat?: ResponseFormat;
+    /** OpenRouter-only routing options; any other adapter rejects them. */
+    openrouter?: OpenRouterOptions;
+}
+/**
+ * Thrown when an option is addressed to an adapter that cannot honour it. The
+ * kernel never drops an option on the floor: silence here is how a request
+ * meant for a zero-data-retention route ends up somewhere else.
+ */
+export declare class ProviderOptionsError extends Error {
+    readonly adapter: string;
+    readonly option: keyof ProviderOptions;
+    constructor(adapter: string, option: keyof ProviderOptions, detail?: string);
+}
+/** Throw if `options` carries `option`, for an adapter that cannot honour it. */
+export declare function rejectOption(adapter: string, options: ProviderOptions | undefined, option: keyof ProviderOptions, detail?: string): void;
+/** The per-call retry count when given and non-negative, else undefined (the client's default). */
+export declare function resolveMaxRetries(options: ProviderOptions | undefined): number | undefined;
+/**
+ * The per-call completion cap: the option when given and positive, else the
+ * caller's fallback (normally the env-resolved `RUNNER_MAX_TOKENS`).
+ */
+export declare function resolveMaxTokens(options: ProviderOptions | undefined, fallback: number): number;
+//# sourceMappingURL=options.d.ts.map

package/dist/providers/options.d.ts.map

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