@agentionai/agents 1.10.3 → 1.11.0

package/dist/agents/AgentConfig.d.ts

@@ -228,6 +228,29 @@ export interface OpenRouterSpecificConfig {
      * Also groups the requests in OpenRouter's observability views.
      */
     sessionId?: string;
+    /**
+     * Mark the system prompt and the last tool definition with an Anthropic
+     * `cache_control: { type: "ephemeral" }` breakpoint, so the stable prefix of
+     * a request — system prompt plus tool schemas — is billed once and read
+     * from cache on later requests in the same conversation instead of paid in
+     * full every time.
+     *
+     * Worth it for an agent whose system prompt and tools are reused across
+     * several calls in a session. Not worth it for a one-shot or few-call
+     * agent: a cache write costs more than a plain input token, and there are
+     * too few reads after it to recoup that. Pair with {@link sessionId} — a
+     * cache breakpoint with no sticky routing key can land on a different
+     * upstream instance on the very next request, with nothing to hit.
+     *
+     * Written in Anthropic's `cache_control` shape, but not Anthropic-only:
+     * OpenRouter translates it for other providers it fronts (e.g. into
+     * OpenAI's `prompt_cache_breakpoint`), rather than passing it through
+     * as-is or dropping it. Some of those providers (OpenAI, DeepSeek,
+     * Gemini 2.5) already cache automatically with no marker needed, so the
+     * translated breakpoint is redundant there rather than load-bearing.
+     * `ttl` on `cache_control` does not survive translation to OpenAI.
+     */
+    promptCaching?: boolean;
     /** Stable per-end-user identifier used for abuse isolation. Never forwarded raw. */
     user?: string;
     /** Processing tier; `"fast"` is an accepted alias for `"priority"`. */

package/dist/agents/BaseAgent.d.ts

@@ -41,6 +41,12 @@ export type TokenUsage = {
      * for instance, folds thinking tokens into `output_tokens`.
      */
     reasoning_tokens?: number;
+    /**
+     * USD billed for this usage, straight from the provider's own accounting —
+     * not derived from a local price table. Undefined where the provider
+     * doesn't report it (most do not; OpenRouter does, per response).
+     */
+    cost_usd?: number;
     /**
      * Milliseconds from sending the request to the first token of the response —
      * prompt upload plus prompt processing.

package/dist/agents/BaseAgent.js

@@ -197,6 +197,7 @@ class BaseAgent extends events_1.default {
                 output_tokens: previous.output_tokens + timed.output_tokens,
                 total_tokens: previous.total_tokens + timed.total_tokens,
                 reasoning_tokens: sumOptional(previous.reasoning_tokens, timed.reasoning_tokens),
+                cost_usd: sumOptional(previous.cost_usd, timed.cost_usd),
                 timeToFirstTokenMs: sumOptional(previous.timeToFirstTokenMs, timed.timeToFirstTokenMs),
                 generationMs: sumOptional(previous.generationMs, timed.generationMs),
                 totalMs: sumOptional(previous.totalMs, timed.totalMs),

package/dist/agents/openrouter/OpenRouterAgent.js

@@ -392,9 +392,24 @@ class OpenRouterAgent extends BaseAgent_1.BaseAgent {
     }
     /** The `ChatRequest` body, identical for the streaming and buffered paths. */
     buildRequest(stream) {
-        const messages = transformers_1.openRouterTransformer.toProvider(this.history.getEntries());
+        const cachePrompt = this.config.promptCaching === true;
+        const messages = transformers_1.openRouterTransformer.toProvider(this.history.getEntries(), {
+            cacheSystemPrompt: cachePrompt,
+        });
         const allTools = this.getAllToolDefinitions();
-        const tools = allTools.length > 0 ? allTools : undefined;
+        // The breakpoint goes on the *last* tool: Anthropic (and OpenRouter's
+        // translation of this marker for other providers, see
+        // OpenRouterSpecificConfig.promptCaching) caches everything up through a
+        // marked block, so one marker at the end of the array covers the whole
+        // tool list in one cached segment. Marking every tool would just spend
+        // more cache-write budget for the same coverage.
+        const cacheableTools = cachePrompt && allTools.length > 0
+            ? [
+                ...allTools.slice(0, -1),
+                { ...allTools[allTools.length - 1], cacheControl: { type: "ephemeral" } },
+            ]
+            : allTools;
+        const tools = cacheableTools.length > 0 ? cacheableTools : undefined;
         return {
             model: this.config.model,
             messages,
@@ -656,6 +671,7 @@ class OpenRouterAgent extends BaseAgent_1.BaseAgent {
             output_tokens: usage?.completionTokens ?? 0,
             total_tokens: usage?.totalTokens ?? 0,
             reasoning_tokens: usage?.completionTokensDetails?.reasoningTokens ?? undefined,
+            cost_usd: typeof usage?.cost === "number" ? usage.cost : undefined,
         };
     }
     completeViz(textContent) {

package/dist/history/transformers.d.ts

@@ -163,24 +163,20 @@ export declare const chatCompletionsTransformer: {
      */
     toolResultEntry(tool_call_id: string, output: string): HistoryEntry;
 };
-/**
- * Convert normalized entries to/from the message format `@openrouter/sdk`
- * accepts.
- *
- * The wire format is OpenAI Chat Completions, but the SDK's TypeScript surface
- * is camelCase (`toolCalls`, `toolCallId`, `reasoningDetails`) and it
- * zod-serializes to snake_case on the way out — so this cannot reuse
- * {@link chatCompletionsTransformer}, whose output is already snake_case.
- *
- * Beyond the casing it also carries `reasoning_details` through the round trip,
- * which the OpenAI-compatible path has no equivalent for.
- */
 export declare const openRouterTransformer: {
     /**
      * Convert normalized entries to OpenRouter message format.
      * Tool results become role:"tool" messages; tool calls ride on the assistant message.
+     *
+     * `cacheSystemPrompt` marks the system message *and* the latest eligible
+     * message with a cache breakpoint each — see
+     * {@link markLatestCacheBreakpoint} for why it's both ends, not just the
+     * front, and {@link OpenRouterSpecificConfig.promptCaching} for why this is
+     * opt-in rather than automatic.
      */
-    toProvider(entries: HistoryEntry[]): OpenRouterMessage[];
+    toProvider(entries: HistoryEntry[], options?: {
+        cacheSystemPrompt?: boolean;
+    }): OpenRouterMessage[];
     /**
      * Convert an OpenRouter assistant message to a normalized HistoryEntry.
      */
@@ -201,6 +197,7 @@ type OpenRouterToolCallParam = {
 type OpenRouterContentPart = {
     type: "text";
     text: string;
+    cacheControl?: OpenRouterCacheControl;
 } | {
     type: "image_url";
     imageUrl: {
@@ -208,15 +205,23 @@ type OpenRouterContentPart = {
         detail?: "auto" | "low" | "high";
     };
 };
+/**
+ * A cache breakpoint on one content block. `cacheControl` (camelCase, per
+ * this file's header) rather than the wire's `cache_control` — the SDK
+ * zod-serializes the rename on the way out.
+ */
+export type OpenRouterCacheControl = {
+    type: "ephemeral";
+};
 export type OpenRouterMessage = {
     role: "system";
-    content: string;
+    content: string | OpenRouterContentPart[];
 } | {
     role: "user";
     content: string | OpenRouterContentPart[];
 } | {
     role: "assistant";
-    content: string | null;
+    content: string | null | OpenRouterContentPart[];
     toolCalls?: OpenRouterToolCallParam[];
     /** Plain reasoning text replayed from a previous turn. */
     reasoning?: string;
@@ -228,7 +233,7 @@ export type OpenRouterMessage = {
 } | {
     role: "tool";
     toolCallId: string;
-    content: string;
+    content: string | OpenRouterContentPart[];
 };
 type OpenRouterResponseMessage = {
     role: string;

package/dist/history/transformers.js

@@ -782,12 +782,49 @@ exports.chatCompletionsTransformer = {
  * Beyond the casing it also carries `reasoning_details` through the round trip,
  * which the OpenAI-compatible path has no equivalent for.
  */
+/**
+ * Marks the *last* message carrying plain string content with an Anthropic
+ * cache breakpoint, mutating it in place.
+ *
+ * The system-prompt breakpoint alone only caches the fixed part of a request
+ * — an agentic loop's growing tool-call history is not fixed, and without a
+ * second breakpoint it is resent as fresh, full-price input on every turn.
+ * Marking the tail instead: turn N's breakpoint lands on its newest message,
+ * so turn N+1's *identical, longer prefix up to that point* is a cache hit,
+ * and only the new content past it needs to be freshly priced (and gets its
+ * own breakpoint in turn). Anthropic allows up to 4 breakpoints total; this
+ * is the second, after the one on the system message — see
+ * {@link OpenRouterSpecificConfig.promptCaching}.
+ *
+ * Skips a message whose content isn't a non-empty string — `null` (an
+ * assistant turn that's purely a tool call, nothing to attach a text block
+ * to) or an already-structured array (images). Landing one message later
+ * than ideal in that case is a smaller loss than the alternative of writing
+ * this for every content shape up front.
+ */
+function markLatestCacheBreakpoint(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (typeof message.content === "string" && message.content.length > 0) {
+            message.content = [
+                { type: "text", text: message.content, cacheControl: { type: "ephemeral" } },
+            ];
+            return;
+        }
+    }
+}
 exports.openRouterTransformer = {
     /**
      * Convert normalized entries to OpenRouter message format.
      * Tool results become role:"tool" messages; tool calls ride on the assistant message.
+     *
+     * `cacheSystemPrompt` marks the system message *and* the latest eligible
+     * message with a cache breakpoint each — see
+     * {@link markLatestCacheBreakpoint} for why it's both ends, not just the
+     * front, and {@link OpenRouterSpecificConfig.promptCaching} for why this is
+     * opt-in rather than automatic.
      */
-    toProvider(entries) {
+    toProvider(entries, options) {
         const messages = [];
         for (const entry of entries) {
             const textBlocks = entry.content.filter(types_1.isTextContent);
@@ -798,9 +835,12 @@ exports.openRouterTransformer = {
             const imageBase64Blocks = entry.content.filter(types_1.isImageBase64Content);
             const hasImages = imageUrlBlocks.length > 0 || imageBase64Blocks.length > 0;
             if (entry.role === "system") {
+                const text = textBlocks.map((c) => c.text).join("\n");
                 messages.push({
                     role: "system",
-                    content: textBlocks.map((c) => c.text).join("\n"),
+                    content: options?.cacheSystemPrompt
+                        ? [{ type: "text", text, cacheControl: { type: "ephemeral" } }]
+                        : text,
                 });
                 continue;
             }
@@ -879,6 +919,8 @@ exports.openRouterTransformer = {
                 });
             }
         }
+        if (options?.cacheSystemPrompt)
+            markLatestCacheBreakpoint(messages);
         return messages;
     },
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",