@roj-ai/sdk 0.1.31 → 0.1.33

package/dist/plugins/session-stats/plugin.js

@@ -1,21 +1,28 @@
 import { agentEvents } from '../../core/agents/state.js';
+import { contextEvents } from '../../core/context/state.js';
 import { llmEvents } from '../../core/llm/state.js';
 import { definePlugin } from '../../core/plugins/plugin-builder.js';
 import { selectPluginState } from '../../core/sessions/reducer.js';
 import { toolEvents } from '../../core/tools/state.js';
+import { userChatEvents } from '../../plugins/user-chat/plugin.js';
 const createInitialStats = () => ({
     totalTokens: 0,
     promptTokens: 0,
     completionTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
     totalCost: 0,
     llmCalls: 0,
     llmErrors: 0,
     toolCalls: 0,
     toolErrors: 0,
+    userMessages: 0,
+    compactions: 0,
     agentCount: 0,
     firstEventAt: null,
     lastEventAt: null,
     byProvider: {},
+    byAgent: {},
 });
 const PLUGIN_STATE_KEY = 'sessionStats';
 /**
@@ -28,11 +35,11 @@ export function selectSessionStats(sessionState) {
 // Plugin
 // ============================================================================
 export const sessionStatsPlugin = definePlugin('session-stats')
-    .events([agentEvents, llmEvents, toolEvents])
+    .events([agentEvents, llmEvents, toolEvents, contextEvents, userChatEvents])
     .state({
     key: PLUGIN_STATE_KEY,
     initial: createInitialStats,
-    reduce: (stats, event) => {
+    reduce: (stats, event, sessionState) => {
         const now = event.timestamp;
         const withTimestamp = (partial) => ({
             ...stats,
@@ -61,13 +68,29 @@ export const sessionStatsPlugin = definePlugin('session-stats')
                         },
                     }
                     : stats.byProvider;
+                // Core reducer runs before plugin slices, so the spawning agent is already in state.
+                const definitionName = sessionState.agents.get(event.agentId)?.definitionName;
+                const byAgent = definitionName
+                    ? {
+                        ...stats.byAgent,
+                        [definitionName]: {
+                            llmCalls: (stats.byAgent[definitionName]?.llmCalls ?? 0) + 1,
+                            promptTokens: (stats.byAgent[definitionName]?.promptTokens ?? 0) + event.metrics.promptTokens,
+                            completionTokens: (stats.byAgent[definitionName]?.completionTokens ?? 0) + event.metrics.completionTokens,
+                            totalCost: (stats.byAgent[definitionName]?.totalCost ?? 0) + (event.metrics.cost ?? 0),
+                        },
+                    }
+                    : stats.byAgent;
                 return withTimestamp({
                     llmCalls: stats.llmCalls + 1,
                     totalTokens: stats.totalTokens + event.metrics.totalTokens,
                     promptTokens: stats.promptTokens + event.metrics.promptTokens,
                     completionTokens: stats.completionTokens + event.metrics.completionTokens,
+                    cacheReadTokens: stats.cacheReadTokens + (event.metrics.cachedTokens ?? 0),
+                    cacheWriteTokens: stats.cacheWriteTokens + (event.metrics.cacheWriteTokens ?? 0),
                     totalCost: stats.totalCost + (event.metrics.cost ?? 0),
                     byProvider,
+                    byAgent,
                 });
             }
             case 'inference_failed':
@@ -76,6 +99,10 @@ export const sessionStatsPlugin = definePlugin('session-stats')
                 return withTimestamp({ toolCalls: stats.toolCalls + 1 });
             case 'tool_failed':
                 return withTimestamp({ toolErrors: stats.toolErrors + 1 });
+            case 'user_chat_message_received':
+                return withTimestamp({ userMessages: stats.userMessages + 1 });
+            case 'context_compacted':
+                return withTimestamp({ compactions: stats.compactions + 1 });
             default:
                 return stats;
         }

package/dist/plugins/session-stats/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/plugins/session-stats/plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/plugins/session-stats/plugin.ts"],"names":[],"mappings":"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"}

package/dist/plugins/session-stats/plugin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin.test.d.ts.map

package/dist/plugins/session-stats/plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.d.ts","sourceRoot":"","sources":["../../../src/plugins/session-stats/plugin.test.ts"],"names":[],"mappings":""}

package/dist/plugins/session-stats/plugin.test.js

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'bun:test';
+import { AgentId } from '../../core/agents/schema.js';
+import { agentEvents } from '../../core/agents/state.js';
+import { contextEvents } from '../../core/context/state.js';
+import { withSessionId } from '../../core/events/test-helpers.js';
+import { llmEvents } from '../../core/llm/state.js';
+import { createApplyEvent } from '../../core/sessions/apply-event.js';
+import { SessionId } from '../../core/sessions/schema.js';
+import { createSessionState } from '../../core/sessions/state.js';
+import { ToolCallId } from '../../core/tools/schema.js';
+import { toolEvents } from '../../core/tools/state.js';
+import { userChatEvents } from '../../plugins/user-chat/plugin.js';
+import { ChatMessageId } from '../../plugins/user-chat/schema.js';
+import { selectSessionStats, sessionStatsPlugin } from './plugin.js';
+const sessionId = SessionId('session-stats-test');
+const orchestrator = AgentId('orchestrator-1');
+const worker = AgentId('worker-1');
+const applyEvent = createApplyEvent([sessionStatsPlugin.create()]);
+const metrics = (overrides = {}) => ({
+    promptTokens: 100,
+    completionTokens: 20,
+    totalTokens: 120,
+    latencyMs: 10,
+    model: 'test-model',
+    provider: 'anthropic',
+    cost: 0.5,
+    ...overrides,
+});
+const spawn = (agentId, definitionName) => withSessionId(sessionId, agentEvents.create('agent_spawned', { agentId, definitionName, parentId: null }));
+const inference = (agentId, m) => withSessionId(sessionId, llmEvents.create('inference_completed', {
+    agentId,
+    consumedMessageIds: [],
+    response: { content: 'ok', toolCalls: [] },
+    metrics: m,
+}));
+const reduce = (events) => selectSessionStats(events.reduce(applyEvent, createSessionState(sessionId, 'test-preset', 0)));
+describe('session-stats plugin', () => {
+    it('starts from zeroed counters', () => {
+        const stats = reduce([]);
+        expect(stats.userMessages).toBe(0);
+        expect(stats.compactions).toBe(0);
+        expect(stats.cacheReadTokens).toBe(0);
+        expect(stats.cacheWriteTokens).toBe(0);
+        expect(stats.byAgent).toEqual({});
+    });
+    it('counts user chat messages', () => {
+        const stats = reduce([
+            spawn(orchestrator, 'orchestrator'),
+            withSessionId(sessionId, userChatEvents.create('user_chat_message_received', {
+                agentId: orchestrator,
+                messageId: ChatMessageId('m1'),
+                content: 'hello',
+                timestamp: 1,
+            })),
+            withSessionId(sessionId, userChatEvents.create('user_chat_message_received', {
+                agentId: orchestrator,
+                messageId: ChatMessageId('m2'),
+                content: 'again',
+                timestamp: 2,
+            })),
+        ]);
+        expect(stats.userMessages).toBe(2);
+    });
+    it('counts context compactions', () => {
+        const stats = reduce([
+            spawn(orchestrator, 'orchestrator'),
+            withSessionId(sessionId, contextEvents.create('context_compacted', {
+                agentId: orchestrator,
+                compactedContent: 'summary',
+                newConversationHistory: [],
+                originalTokens: 1000,
+                compactedTokens: 100,
+                messagesRemoved: 8,
+            })),
+        ]);
+        expect(stats.compactions).toBe(1);
+    });
+    it('sums cache read and write tokens across main and auxiliary inferences', () => {
+        const stats = reduce([
+            spawn(orchestrator, 'orchestrator'),
+            inference(orchestrator, metrics({ cachedTokens: 800, cacheWriteTokens: 200 })),
+            withSessionId(sessionId, llmEvents.create('auxiliary_inference_completed', {
+                agentId: orchestrator,
+                metrics: metrics({ cachedTokens: 50, cacheWriteTokens: 10 }),
+            })),
+            // Providers that report no cache usage must not break the totals.
+            inference(orchestrator, metrics()),
+        ]);
+        expect(stats.cacheReadTokens).toBe(850);
+        expect(stats.cacheWriteTokens).toBe(210);
+        expect(stats.llmCalls).toBe(3);
+    });
+    it('breaks LLM usage down by agent definition name', () => {
+        const stats = reduce([
+            spawn(orchestrator, 'orchestrator'),
+            spawn(worker, 'coder'),
+            inference(orchestrator, metrics({ promptTokens: 100, completionTokens: 20, cost: 0.5 })),
+            inference(worker, metrics({ promptTokens: 300, completionTokens: 40, cost: 1.25 })),
+            inference(worker, metrics({ promptTokens: 200, completionTokens: 10, cost: 0.25 })),
+            withSessionId(sessionId, llmEvents.create('auxiliary_inference_completed', {
+                agentId: worker,
+                metrics: metrics({ promptTokens: 10, completionTokens: 1, cost: 0.05 }),
+            })),
+        ]);
+        expect(stats.byAgent).toEqual({
+            orchestrator: { llmCalls: 1, promptTokens: 100, completionTokens: 20, totalCost: 0.5 },
+            coder: { llmCalls: 3, promptTokens: 510, completionTokens: 51, totalCost: 1.55 },
+        });
+        expect(stats.totalCost).toBeCloseTo(2.05, 10);
+    });
+    it('keeps existing counters working', () => {
+        const stats = reduce([
+            spawn(orchestrator, 'orchestrator'),
+            inference(orchestrator, metrics()),
+            withSessionId(sessionId, llmEvents.create('inference_failed', { agentId: orchestrator, error: 'boom' })),
+            withSessionId(sessionId, toolEvents.create('tool_started', {
+                agentId: orchestrator,
+                toolCallId: ToolCallId('tc-1'),
+                toolName: 'read_file',
+                input: {},
+            })),
+            withSessionId(sessionId, toolEvents.create('tool_failed', {
+                agentId: orchestrator,
+                toolCallId: ToolCallId('tc-1'),
+                error: 'ENOENT',
+            })),
+        ]);
+        expect(stats.agentCount).toBe(1);
+        expect(stats.llmCalls).toBe(1);
+        expect(stats.llmErrors).toBe(1);
+        expect(stats.toolCalls).toBe(1);
+        expect(stats.toolErrors).toBe(1);
+        expect(stats.totalTokens).toBe(120);
+        expect(stats.promptTokens).toBe(100);
+        expect(stats.completionTokens).toBe(20);
+        expect(stats.byProvider.anthropic).toEqual({
+            llmCalls: 1,
+            totalTokens: 120,
+            promptTokens: 100,
+            completionTokens: 20,
+            totalCost: 0.5,
+        });
+    });
+});
+//# sourceMappingURL=plugin.test.js.map

package/dist/plugins/session-stats/plugin.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.js","sourceRoot":"","sources":["../../../src/plugins/session-stats/plugin.test.ts"],"names":[],"mappings":"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"}

package/dist/transport/http/middleware/error-handler.d.ts

@@ -17,5 +17,5 @@ export declare const errorHandler: (error: Error, c: Context<AppEnv>) => Respons
         type: string;
         message: string;
     };
-}, 100 | 500 | 404 | 409 | 400 | 403 | -1 | 429 | 401 | 200 | 300 | 501 | 201 | 102 | 103 | 202 | 203 | 206 | 207 | 208 | 226 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 402 | 405 | 406 | 407 | 408 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 431 | 451 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "json">;
+}, 100 | 500 | 404 | 409 | 400 | 403 | -1 | 429 | 401 | 200 | 300 | 501 | 201 | 510 | 102 | 103 | 202 | 203 | 206 | 207 | 208 | 226 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 402 | 405 | 406 | 407 | 408 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 431 | 451 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 511, "json">;
 //# sourceMappingURL=error-handler.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@roj-ai/sdk",
-	"version": "0.1.31",
+	"version": "0.1.33",
 	"type": "module",
 	"main": "./dist/index.js",
 	"exports": {
@@ -135,7 +135,7 @@
 		"type-check": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@roj-ai/transport": "^0.1.31",
+		"@roj-ai/transport": "^0.1.33",
 		"@hono/zod-validator": "0.7.6",
 		"hono": "4.12.5",
 		"ignore": "7.0.5",

package/src/core/agents/agent.ts

@@ -14,7 +14,7 @@ import type { AgentState, HandlerResult } from '~/core/agents/state.js'
 import { agentEvents } from '~/core/agents/state.js'
 import { withSessionId } from '~/core/events/test-helpers.js'
 import type { FileStore } from '~/core/file-store/types.js'
-import { applyCacheBreakpoint } from '~/core/llm/cache-breakpoints.js'
+import { applyCacheBreakpoint, type CacheTtlConfig } from '~/core/llm/cache-breakpoints.js'
 import type { ToolResultContent } from '~/core/llm/llm-log-types.js'
 import type { InferenceRequest, InferenceResponse, LLMError, LLMMessage, LLMProvider } from '~/core/llm/provider.js'
 import { LLMCallId, ModelId } from '~/core/llm/schema.js'
@@ -87,8 +87,11 @@ export interface AgentConfig<TInput = unknown> {
 	 * — useful for long-lived agents (e.g. an orchestrator that waits minutes
 	 * between user turns) where the default 5-minute TTL would expire and force
 	 * full re-uploads. Omit (or '5m') for the standard tier.
+	 *
+	 * A bare tier applies to both breakpoints; `{ prefix, tail }` sets them
+	 * independently, which usually pays better. See {@link CacheTtlConfig}.
 	 */
-	cacheTtl?: '5m' | '1h'
+	cacheTtl?: CacheTtlConfig
 	/** Outer backoff between error-resume cycles (see BaseAgentConfig.errorResumeBackoff). */
 	errorResumeBackoff?: { baseDelayMs?: number; maxDelayMs?: number }
 }

package/src/core/agents/config.ts

@@ -4,6 +4,7 @@
 
 import z from 'zod/v4'
 import type { DebounceCallback } from '~/core/agents/debounce.js'
+import type { CacheTtlConfig } from '~/core/llm/cache-breakpoints.js'
 import type { LLMMiddleware } from '~/core/llm/middleware.js'
 import { ModelId } from '~/core/llm/schema.js'
 import type { AgentPluginConfig } from '~/core/plugins/plugin-builder.js'
@@ -57,8 +58,11 @@ export interface BaseAgentConfig<TInput = unknown> {
 	 * '1h' opts into Anthropic's extended cache tier for long-lived agents
 	 * (e.g. an orchestrator that waits minutes between user turns). Defaults
 	 * to the standard 5-minute tier.
+	 *
+	 * A bare tier applies to both breakpoints; `{ prefix, tail }` sets them
+	 * independently, which usually pays better. See {@link CacheTtlConfig}.
 	 */
-	cacheTtl?: '5m' | '1h'
+	cacheTtl?: CacheTtlConfig
 	/**
 	 * Outer backoff between error-resume cycles after an inference exhausts its
 	 * LLM retries on a retryable error (the message stays queued and is retried).

package/src/core/llm/anthropic.ts

@@ -326,10 +326,16 @@ export class AnthropicProvider implements RoutableLLMProvider {
 		const mappedMessages = await Promise.all(sanitizedMessages.map((m) => this.mapMessage(m, context)))
 		const mergedMessages = this.mergeConsecutiveMessages(mappedMessages)
 
+		// The system prompt precedes every message and Anthropic requires a longer
+		// TTL to come BEFORE a shorter one, so it has to match the longest TTL any
+		// breakpoint asks for — otherwise the order is 5m → 1h → 5m.
+		const systemCacheControl: AnthropicCacheControl = { type: 'ephemeral' }
+		if (sanitizedMessages.some((m) => m.cacheControl?.ttl === '1h')) systemCacheControl.ttl = '1h'
+
 		const body: AnthropicRequestBody = {
 			model: request.model ?? this.defaultModel,
 			max_tokens: request.maxTokens ?? 100_000,
-			system: [{ type: 'text', text: request.systemPrompt, cache_control: { type: 'ephemeral' } }],
+			system: [{ type: 'text', text: request.systemPrompt, cache_control: systemCacheControl }],
 			messages: mergedMessages,
 			stream: false,
 		}

package/src/core/llm/cache-breakpoints.test.ts

@@ -37,14 +37,44 @@ describe('applyCacheBreakpoint', () => {
 		expect(cachedIndices(result)).toEqual([3])
 	})
 
-	test('ttl is propagated onto the marked messages', () => {
-		const messages = userMessages(6)
-		const result = applyCacheBreakpoint(messages, 0, '1h', 2)
-		// prefix = 1, tail = 5
-		for (const idx of [1, 5]) {
-			const m = result[idx]
-			expect('cacheControl' in m && m.cacheControl).toEqual({ type: 'ephemeral', ttl: '1h' })
-		}
+	// prefix = 1, tail = 5 for userMessages(6) with suffix 0 and cachedPrefixCount 2
+	const ttlsOf = (messages: LLMMessage[]) => [1, 5].map((idx) => {
+		const m = messages[idx]
+		return 'cacheControl' in m && m.cacheControl ? m.cacheControl.ttl : undefined
+	})
+
+	test('a bare tier applies to both breakpoints', () => {
+		const result = applyCacheBreakpoint(userMessages(6), 0, '1h', 2)
+		expect(ttlsOf(result)).toEqual(['1h', '1h'])
+	})
+
+	test('{ prefix } leaves the tail on the default tier', () => {
+		// Usually the paying configuration for an interactive agent: the immutable
+		// preamble survives human pauses, the churning tail stays cheap to write.
+		const result = applyCacheBreakpoint(userMessages(6), 0, { prefix: '1h' }, 2)
+		expect(ttlsOf(result)).toEqual(['1h', undefined])
+	})
+
+	test('{ prefix, tail } sets each breakpoint independently', () => {
+		const result = applyCacheBreakpoint(userMessages(6), 0, { prefix: '1h', tail: '5m' }, 2)
+		expect(ttlsOf(result)).toEqual(['1h', '5m'])
+	})
+
+	test('{ tail } alone is honoured — the SDK does not second-guess the caller', () => {
+		const result = applyCacheBreakpoint(userMessages(6), 0, { tail: '1h' }, 2)
+		expect(ttlsOf(result)).toEqual([undefined, '1h'])
+	})
+
+	test('prefixIdx === tailIdx → the single mark covers the preamble, so it takes the prefix ttl', () => {
+		const result = applyCacheBreakpoint(userMessages(3), 0, { prefix: '1h' }, 3)
+		expect(cachedIndices(result)).toEqual([2])
+		const only = result[2]
+		expect('cacheControl' in only && only.cacheControl).toEqual({ type: 'ephemeral', ttl: '1h' })
+	})
+
+	test('no ttl → neither breakpoint carries one', () => {
+		const result = applyCacheBreakpoint(userMessages(6), 0, undefined, 2)
+		expect(ttlsOf(result)).toEqual([undefined, undefined])
 	})
 
 	test('does not mutate the input array', () => {

package/src/core/llm/cache-breakpoints.ts

@@ -1,5 +1,44 @@
 import type { LLMMessage, LLMMessageCacheControl } from '~/core/agents/state.js'
 
+/** Anthropic's two ephemeral cache tiers: 5-minute (write 1.25×) and 1-hour (write 2×). Reads are 0.1× on both. */
+export type CacheTtl = '5m' | '1h'
+
+/**
+ * Per-breakpoint prompt cache TTL.
+ *
+ * A bare tier applies to both breakpoints. The object form sets them
+ * independently, which is usually what you want: the stable prefix and the
+ * churning conversation tail have opposite cost profiles.
+ *
+ * Choosing between them is an economic question about a specific agent's call
+ * pattern, so the SDK does not pick for you:
+ *
+ * - A long TTL on the **prefix** pays off when calls are spread further apart
+ *   than the short tier survives — an orchestrator waiting on a human.
+ * - A long TTL on the **tail** costs 2× on every write while the tail is
+ *   rewritten turn-to-turn anyway, so it only pays when consecutive calls are
+ *   themselves minutes apart.
+ *
+ * Worked example, from a measured 5-week production session: 95% of inferences
+ * followed a sub-5-minute gap, so `'1h'` uniformly came out ~2.5% *worse* than
+ * the default, while `{ prefix: '1h' }` targeted the 29 rewrites that actually
+ * expired. A batch agent called in a tight loop would want the opposite.
+ *
+ * Constraint: Anthropic requires a longer TTL to precede a shorter one, and the
+ * prefix breakpoint always sits before the tail. So `{ prefix: '5m', tail: '1h' }`
+ * is invalid at the API and will be rejected — the tail TTL must not exceed the
+ * prefix TTL.
+ */
+export type CacheTtlConfig = CacheTtl | { prefix?: CacheTtl; tail?: CacheTtl }
+
+const resolveTtls = (config: CacheTtlConfig | undefined): { prefix?: CacheTtl; tail?: CacheTtl } => {
+	if (config === undefined) return {}
+	if (typeof config === 'string') return { prefix: config, tail: config }
+	return config
+}
+
+const cacheControl = (ttl: CacheTtl | undefined): LLMMessageCacheControl => ttl ? { type: 'ephemeral', ttl } : { type: 'ephemeral' }
+
 /**
  * Mark the prompt cache breakpoints on a message list.
  *
@@ -26,22 +65,26 @@ import type { LLMMessage, LLMMessageCacheControl } from '~/core/agents/state.js'
  *    every inference AND compaction call. Anthropic allows up to 4 breakpoints
  *    and matches the longest cached prefix, so the two coexist.
  *
- * If the prefix and tail indices coincide, only one breakpoint is set.
+ * If the prefix and tail indices coincide, only one breakpoint is set — it
+ * covers the preamble, so it takes the prefix TTL.
  *
- * `ttl` opts into Anthropic's 1-hour cache tier (write cost 2× input, read
- * still 0.1×). Useful for long-lived agents where the default 5-minute TTL
- * would expire between user turns. Omit for the default 5-minute tier.
+ * `ttl` sets the cache tier per breakpoint; see {@link CacheTtlConfig} for how
+ * to choose. Providers must additionally give the system block the longest TTL
+ * in use, since it precedes every message and Anthropic rejects a longer entry
+ * that follows a shorter one.
  */
 export function applyCacheBreakpoint(
 	messages: LLMMessage[],
 	uncachedSuffixCount: number,
-	ttl?: '5m' | '1h',
+	ttl?: CacheTtlConfig,
 	cachedPrefixCount = 0,
 ): LLMMessage[] {
-	const cacheControl: LLMMessageCacheControl = ttl ? { type: 'ephemeral', ttl } : { type: 'ephemeral' }
+	const ttls = resolveTtls(ttl)
+	const prefixCacheControl = cacheControl(ttls.prefix)
+	const tailCacheControl = cacheControl(ttls.tail)
 	const result = [...messages]
 
-	const mark = (idx: number) => {
+	const mark = (idx: number, cacheControl: LLMMessageCacheControl) => {
 		if (idx < 0 || idx >= result.length) return
 		const target = result[idx]
 		switch (target.role) {
@@ -59,7 +102,9 @@ export function applyCacheBreakpoint(
 	// summary, sliding recent window), so the immutable preamble is read at 0.1×
 	// on every inference AND compaction call instead of being re-billed each turn.
 	const prefixIdx = cachedPrefixCount - 1
-	if (prefixIdx !== tailIdx) mark(prefixIdx)
-	mark(tailIdx)
+	if (prefixIdx !== tailIdx) mark(prefixIdx, prefixCacheControl)
+	// When the two coincide there is only one entry to pin, and it covers the
+	// preamble — so it takes the prefix TTL.
+	mark(tailIdx, prefixIdx === tailIdx ? prefixCacheControl : tailCacheControl)
 	return result
 }

package/src/core/llm/openrouter-mapping.test.ts

@@ -21,7 +21,7 @@ const createProvider = () =>
 		defaultModel: 'anthropic/claude-haiku-4.5',
 	})
 
-type AnyBlock = { type: string; cache_control?: { type: 'ephemeral' }; [key: string]: unknown }
+type AnyBlock = { type: string; cache_control?: { type: 'ephemeral'; ttl?: '5m' | '1h' }; [key: string]: unknown }
 type OpenRouterMessage = {
 	role: string
 	content: string | AnyBlock[]
@@ -152,6 +152,42 @@ describe('OpenRouterProvider buildHttpRequest', () => {
 		expect(last.content).toBe('<session-context>plugin status</session-context>')
 	})
 
+	test('ttl reaches the wire and the system block matches it', async () => {
+		// The whole point of the fix: OpenRouter dropped `ttl` on the floor, so a
+		// preset asking for the 1-hour tier silently ran on the 5-minute default.
+		const messages = applyCacheBreakpoint([
+			{ role: 'user', content: 'preamble' },
+			{ role: 'assistant', content: 'ok' },
+			{ role: 'user', content: 'work' },
+		], 0, { prefix: '1h' }, 1)
+
+		const http = await createProvider().buildHttpRequest(buildRequest(messages))
+		const msgs = getBodyMessages(http.body)
+
+		// System precedes every message, so it must carry the longest TTL in use —
+		// Anthropic rejects a longer entry that follows a shorter one.
+		const systemBlocks = asBlocks(msgs[0].content)
+		expect(systemBlocks[0].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' })
+
+		// prefix breakpoint (message index 0 → body index 1) carries 1h
+		expect(asBlocks(msgs[1].content)[0].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' })
+		// tail breakpoint stays on the cheap short tier
+		expect(asBlocks(msgs[3].content)[0].cache_control).toEqual({ type: 'ephemeral' })
+	})
+
+	test('no ttl requested: system block stays on the default tier', async () => {
+		const messages = applyCacheBreakpoint([
+			{ role: 'user', content: 'preamble' },
+			{ role: 'user', content: 'work' },
+		], 0, undefined, 1)
+
+		const http = await createProvider().buildHttpRequest(buildRequest(messages))
+		const msgs = getBodyMessages(http.body)
+
+		expect(asBlocks(msgs[0].content)[0].cache_control).toEqual({ type: 'ephemeral' })
+		expect(asBlocks(msgs[1].content)[0].cache_control).toEqual({ type: 'ephemeral' })
+	})
+
 	test('no flag on any message: only system has cache_control', async () => {
 		const http = await createProvider().buildHttpRequest(buildRequest([
 			{ role: 'user', content: 'What is 2+2?' },

package/src/core/llm/openrouter.ts

@@ -89,11 +89,17 @@ interface OpenRouterErrorResponse {
 // Request body types
 // ============================================================================
 
+interface OpenRouterCacheControl {
+	type: 'ephemeral'
+	/** Omitted = the provider default 5-minute tier. */
+	ttl?: '5m' | '1h'
+}
+
 interface OpenRouterContentItem {
 	type: string
 	text?: string
 	image_url?: { url: string; detail?: string }
-	cache_control?: { type: 'ephemeral' }
+	cache_control?: OpenRouterCacheControl
 }
 
 interface OpenRouterMessage {
@@ -104,18 +110,34 @@ interface OpenRouterMessage {
 }
 
 /**
- * Add `cache_control: { type: 'ephemeral' }` to the LAST content block of an
- * OpenRouterMessage, converting string content to an array text block first
- * so the mark has a place to live.
+ * Add `cache_control` to the LAST content block of an OpenRouterMessage,
+ * converting string content to an array text block first so the mark has a
+ * place to live.
+ *
+ * `ttl` reaches Anthropic through the Chat Completions surface. It is NOT
+ * expressible on the Responses API, where a breakpoint is downgraded to the
+ * default 5-minute tier — so this must stay on `/chat/completions`.
  */
-function applyCacheControlToLastBlock(msg: OpenRouterMessage): void {
+function applyCacheControlToLastBlock(msg: OpenRouterMessage, cacheControl: OpenRouterCacheControl): void {
 	if (typeof msg.content === 'string') {
-		msg.content = [{ type: 'text', text: msg.content, cache_control: { type: 'ephemeral' } }]
+		msg.content = [{ type: 'text', text: msg.content, cache_control: cacheControl }]
 		return
 	}
 	if (msg.content.length === 0) return
 	const lastIdx = msg.content.length - 1
-	msg.content[lastIdx] = { ...msg.content[lastIdx], cache_control: { type: 'ephemeral' } }
+	msg.content[lastIdx] = { ...msg.content[lastIdx], cache_control: cacheControl }
+}
+
+/**
+ * Longest TTL requested anywhere in the message list, or undefined when none.
+ *
+ * The system prompt precedes every message, and Anthropic requires a longer TTL
+ * to come BEFORE a shorter one. So when any breakpoint asks for 1h, the system
+ * block has to carry 1h too — otherwise the order is 5m → 1h → 5m and the
+ * longer entry is invalid.
+ */
+function longestCacheTtl(messages: LLMMessage[]): '1h' | undefined {
+	return messages.some((m) => m.cacheControl?.ttl === '1h') ? '1h' : undefined
 }
 
 interface OpenRouterToolDefinition {
@@ -261,8 +283,10 @@ export class OpenRouterProvider implements LLMProvider {
 		const sanitizedMessages = sanitizeProviderMessages(request.messages, this.name, this.logger)
 		const mappedMessages = await Promise.all(sanitizedMessages.map((m) => this.mapMessage(m, context)))
 
+		const systemTtl = longestCacheTtl(sanitizedMessages)
+		const systemCacheControl: OpenRouterCacheControl = systemTtl ? { type: 'ephemeral', ttl: systemTtl } : { type: 'ephemeral' }
 		const messages: OpenRouterMessage[] = [
-			{ role: 'system', content: [{ type: 'text', text: request.systemPrompt, cache_control: { type: 'ephemeral' } }] },
+			{ role: 'system', content: [{ type: 'text', text: request.systemPrompt, cache_control: systemCacheControl }] },
 			...mappedMessages,
 		]
 
@@ -317,7 +341,9 @@ export class OpenRouterProvider implements LLMProvider {
 	private async mapMessage(msg: LLMMessage, context?: InferenceContext): Promise<OpenRouterMessage> {
 		const mapped = await this.mapMessageContent(msg, context)
 		if (msg.cacheControl) {
-			applyCacheControlToLastBlock(mapped)
+			const cacheControl: OpenRouterCacheControl = { type: 'ephemeral' }
+			if (msg.cacheControl.ttl) cacheControl.ttl = msg.cacheControl.ttl
+			applyCacheControlToLastBlock(mapped, cacheControl)
 		}
 		return mapped
 	}