xonecas.io
64875
Mc

mini-coder / commit 422aa8c

feat: implement prompt caching preferences and session time anchors

Adds initialPromptCachingEnabled, initialOpenAIPromptCacheRetention, and initialGoogleCachedContent. Updates buildSystemPrompt to accept a sessionTimeAnchor. Renames writer subagent to blogger.

xonecas2026-03-12 422aa8cd425664d99ac54d6f2e5e5c4127216d7c parent 1346e81

15 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.agents/agents/blogger.md+1−1
@@ -1,5 +1,5 @@
11 ---
2-description: Write short prose in a personal, informal style from topics or resources
2+description: Writes blog posts drafts.
33 mode: subagent
44 ---
55
src/agent/agent.ts+30−0
@@ -10,7 +10,10 @@ import {
1010 listMcpServers,
1111 setPreferredActiveAgent,
1212 setPreferredContextPruningMode,
13+ setPreferredGoogleCachedContent,
1314 setPreferredModel,
15+ setPreferredOpenAIPromptCacheRetention,
16+ setPreferredPromptCachingEnabled,
1417 setPreferredShowReasoning,
1518 setPreferredThinkingEffort,
1619 setPreferredToolResultPayloadCapBytes,
@@ -28,6 +31,9 @@ interface AgentOptions {
2831 initialShowReasoning: boolean;
2932 initialPruningMode: ContextPruningMode;
3033 initialToolResultPayloadCapBytes: number;
34+ initialPromptCachingEnabled: boolean;
35+ initialOpenAIPromptCacheRetention: "in_memory" | "24h";
36+ initialGoogleCachedContent: string | null;
3137 sessionId?: string;
3238 reporter: AgentReporter;
3339 headless?: boolean;
@@ -102,6 +108,9 @@ export async function initAgent(opts: AgentOptions): Promise<{
102108 initialShowReasoning: opts.initialShowReasoning,
103109 initialPruningMode: opts.initialPruningMode,
104110 initialToolResultPayloadCapBytes: opts.initialToolResultPayloadCapBytes,
111+ initialPromptCachingEnabled: opts.initialPromptCachingEnabled,
112+ initialOpenAIPromptCacheRetention: opts.initialOpenAIPromptCacheRetention,
113+ initialGoogleCachedContent: opts.initialGoogleCachedContent,
105114 sessionId: opts.sessionId,
106115 extraSystemPrompt: opts.agentSystemPrompt,
107116 isSubagent: opts.headless,
@@ -160,6 +169,27 @@ export async function initAgent(opts: AgentOptions): Promise<{
160169 runner.toolResultPayloadCapBytes = Math.max(0, bytes);
161170 setPreferredToolResultPayloadCapBytes(runner.toolResultPayloadCapBytes);
162171 },
172+ get promptCachingEnabled() {
173+ return runner.promptCachingEnabled;
174+ },
175+ setPromptCachingEnabled: (enabled) => {
176+ runner.promptCachingEnabled = enabled;
177+ setPreferredPromptCachingEnabled(enabled);
178+ },
179+ get openaiPromptCacheRetention() {
180+ return runner.openaiPromptCacheRetention;
181+ },
182+ setOpenAIPromptCacheRetention: (retention) => {
183+ runner.openaiPromptCacheRetention = retention;
184+ setPreferredOpenAIPromptCacheRetention(retention);
185+ },
186+ get googleCachedContent() {
187+ return runner.googleCachedContent;
188+ },
189+ setGoogleCachedContent: (contentId) => {
190+ runner.googleCachedContent = contentId;
191+ setPreferredGoogleCachedContent(contentId);
192+ },
163193 get planMode() {
164194 return runner.planMode;
165195 },
src/agent/session-runner.ts+16−0
@@ -33,6 +33,9 @@ interface SessionRunnerOptions {
3333 initialShowReasoning: boolean;
3434 initialPruningMode: ContextPruningMode;
3535 initialToolResultPayloadCapBytes: number;
36+ initialPromptCachingEnabled: boolean;
37+ initialOpenAIPromptCacheRetention: "in_memory" | "24h";
38+ initialGoogleCachedContent: string | null;
3639 sessionId?: string | undefined;
3740 extraSystemPrompt?: string | undefined;
3841 isSubagent?: boolean | undefined;
@@ -49,8 +52,12 @@ export class SessionRunner {
4952 public showReasoning: boolean;
5053 public pruningMode: ContextPruningMode;
5154 public toolResultPayloadCapBytes: number;
55+ public promptCachingEnabled: boolean;
56+ public openaiPromptCacheRetention: "in_memory" | "24h";
57+ public googleCachedContent: string | null;
5258
5359 public session!: ActiveSession;
60+ public sessionTimeAnchor!: string;
5461 public coreHistory!: CoreMessage[];
5562 public turnIndex = 1;
5663 public snapshotStack: Array<number | null> = [];
@@ -75,6 +82,9 @@ export class SessionRunner {
7582 this.showReasoning = opts.initialShowReasoning;
7683 this.pruningMode = opts.initialPruningMode;
7784 this.toolResultPayloadCapBytes = opts.initialToolResultPayloadCapBytes;
85+ this.promptCachingEnabled = opts.initialPromptCachingEnabled;
86+ this.openaiPromptCacheRetention = opts.initialOpenAIPromptCacheRetention;
87+ this.googleCachedContent = opts.initialGoogleCachedContent;
7888 this.extraSystemPrompt = opts.extraSystemPrompt;
7989 this.isSubagent = opts.isSubagent;
8090 this.killSubprocesses = opts.killSubprocesses;
@@ -103,6 +113,7 @@ export class SessionRunner {
103113 // (including providerOptions/providerMetadata thought-signature fields and
104114 // part ordering); do not reconstruct tool-call history on resume.
105115
116+ this.sessionTimeAnchor = new Date(this.session.createdAt).toISOString();
106117 this.coreHistory = [...this.session.messages];
107118 }
108119
@@ -114,6 +125,7 @@ export class SessionRunner {
114125 this.totalIn = 0;
115126 this.totalOut = 0;
116127 this.lastContextTokens = 0;
128+ this.sessionTimeAnchor = new Date(this.session.createdAt).toISOString();
117129 this.snapshotStack.length = 0;
118130 }
119131
@@ -160,6 +172,7 @@ export class SessionRunner {
160172
161173 const llm = resolveModel(this.currentModel);
162174 const systemPrompt = buildSystemPrompt(
175+ this.sessionTimeAnchor,
163176 this.cwd,
164177 this.extraSystemPrompt,
165178 this.isSubagent,
@@ -182,6 +195,9 @@ export class SessionRunner {
182195 signal: abortController.signal,
183196 pruningMode: this.pruningMode,
184197 toolResultPayloadCapBytes: this.toolResultPayloadCapBytes,
198+ promptCachingEnabled: this.promptCachingEnabled,
199+ openaiPromptCacheRetention: this.openaiPromptCacheRetention,
200+ googleCachedContent: this.googleCachedContent,
185201 ...(this.currentThinkingEffort
186202 ? { thinkingEffort: this.currentThinkingEffort }
187203 : {}),
src/agent/system-prompt.test.ts+70−10
@@ -44,7 +44,13 @@ describe("loadLocalContextFile", () => {
4444
4545 describe("buildSystemPrompt", () => {
4646 it("includes base guidelines without context files", () => {
47- const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
47+ const prompt = buildSystemPrompt(
48+ "mock-time-anchor",
49+ tmpDir,
50+ undefined,
51+ undefined,
52+ fakeHome,
53+ );
4854 expect(prompt).toContain("You are mini-coder");
4955 expect(prompt).toContain("Guidelines:");
5056 expect(prompt).not.toContain("# Project context");
@@ -57,20 +63,38 @@ describe("buildSystemPrompt", () => {
5763
5864 it("includes local context under # Project context", () => {
5965 writeFileSync(join(tmpDir, "AGENTS.md"), "local project info");
60- const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
66+ const prompt = buildSystemPrompt(
67+ "mock-time-anchor",
68+ tmpDir,
69+ undefined,
70+ undefined,
71+ fakeHome,
72+ );
6173 expect(prompt).toContain("# Project context");
6274 expect(prompt).toContain("local project info");
6375 });
6476
6577 it("has exactly one # Project context section when local context present", () => {
6678 writeFileSync(join(tmpDir, "AGENTS.md"), "local info");
67- const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
79+ const prompt = buildSystemPrompt(
80+ "mock-time-anchor",
81+ tmpDir,
82+ undefined,
83+ undefined,
84+ fakeHome,
85+ );
6886 const occurrences = prompt.split("# Project context").length - 1;
6987 expect(occurrences).toBe(1);
7088 });
7189
7290 it("appends subagent delegation wording in subagent mode", () => {
73- const prompt = buildSystemPrompt(tmpDir, undefined, true, fakeHome);
91+ const prompt = buildSystemPrompt(
92+ "mock-time-anchor",
93+ tmpDir,
94+ undefined,
95+ true,
96+ fakeHome,
97+ );
7498 expect(prompt).toContain("You are running as a subagent");
7599 expect(prompt).toContain(
76100 "Do not spawn further subagents unless the subtask is unambiguously separable",
@@ -78,13 +102,25 @@ describe("buildSystemPrompt", () => {
78102 });
79103
80104 it("does not append subagent wording in non-subagent mode", () => {
81- const prompt = buildSystemPrompt(tmpDir, undefined, false, fakeHome);
105+ const prompt = buildSystemPrompt(
106+ "mock",
107+ tmpDir,
108+ undefined,
109+ false,
110+ fakeHome,
111+ );
82112 expect(prompt).not.toContain("You are running as a subagent");
83113 });
84114
85115 it("appends extraSystemPrompt after context and subagent wording", () => {
86116 writeFileSync(join(tmpDir, "AGENTS.md"), "ctx");
87- const prompt = buildSystemPrompt(tmpDir, "custom extra", true, fakeHome);
117+ const prompt = buildSystemPrompt(
118+ "mock",
119+ tmpDir,
120+ "custom extra",
121+ true,
122+ fakeHome,
123+ );
88124 const subagentIdx = prompt.indexOf("You are running as a subagent");
89125 const extraIdx = prompt.indexOf("custom extra");
90126 const contextIdx = prompt.indexOf("ctx");
@@ -93,7 +129,13 @@ describe("buildSystemPrompt", () => {
93129 });
94130
95131 it("includes cwd and current time in prompt", () => {
96- const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
132+ const prompt = buildSystemPrompt(
133+ "mock",
134+ tmpDir,
135+ undefined,
136+ undefined,
137+ fakeHome,
138+ );
97139 expect(prompt).toContain("Current working directory:");
98140 expect(prompt).toContain("Current date/time:");
99141 });
@@ -101,7 +143,13 @@ describe("buildSystemPrompt", () => {
101143 it("includes global context when ~/.agents/AGENTS.md present", () => {
102144 mkdirSync(join(fakeHome, ".agents"), { recursive: true });
103145 writeFileSync(join(fakeHome, ".agents", "AGENTS.md"), "global info");
104- const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
146+ const prompt = buildSystemPrompt(
147+ "mock",
148+ tmpDir,
149+ undefined,
150+ undefined,
151+ fakeHome,
152+ );
105153 expect(prompt).toContain("# Project context");
106154 expect(prompt).toContain("global info");
107155 });
@@ -110,7 +158,13 @@ describe("buildSystemPrompt", () => {
110158 mkdirSync(join(fakeHome, ".agents"), { recursive: true });
111159 writeFileSync(join(fakeHome, ".agents", "AGENTS.md"), "global info");
112160 writeFileSync(join(tmpDir, "AGENTS.md"), "local info");
113- const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
161+ const prompt = buildSystemPrompt(
162+ "mock",
163+ tmpDir,
164+ undefined,
165+ undefined,
166+ fakeHome,
167+ );
114168 expect(prompt).toContain("global info");
115169 expect(prompt).toContain("local info");
116170 expect(prompt.indexOf("global info")).toBeLessThan(
@@ -119,7 +173,13 @@ describe("buildSystemPrompt", () => {
119173 });
120174
121175 it("does not include # Project context when neither global nor local context present", () => {
122- const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
176+ const prompt = buildSystemPrompt(
177+ "mock",
178+ tmpDir,
179+ undefined,
180+ undefined,
181+ fakeHome,
182+ );
123183 expect(prompt).not.toContain("# Project context");
124184 });
125185 });
src/agent/system-prompt.ts+2−3
@@ -73,6 +73,7 @@ const FINAL_MESSAGE = `
7373 const SUBAGENT_DELEGATION = `You are running as a subagent. Complete the task you have been given directly using your tools. Do not spawn further subagents unless the subtask is unambiguously separable and self-contained.`;
7474
7575 export function buildSystemPrompt(
76+ sessionTimeAnchor: string,
7677 cwd: string,
7778 extraSystemPrompt?: string,
7879 isSubagent?: boolean,
@@ -82,13 +83,11 @@ export function buildSystemPrompt(
8283 const globalContext = loadGlobalContextFile(homeDir ?? homedir());
8384 const localContext = loadLocalContextFile(cwd);
8485 const cwdDisplay = tildePath(cwd);
85- const now = new Date().toLocaleString(undefined, { hour12: false });
86-
8786 let prompt = `You are mini-coder, a small and fast CLI coding agent.
8887 You have access to tools to read files, search code, make edits, run shell commands, and spawn subagents.
8988
9089 Current working directory: ${cwdDisplay}
91-Current date/time: ${now}
90+Current date/time: ${sessionTimeAnchor}
9291
9392 Guidelines:
9493 - Be concise and precise. Avoid unnecessary preamble.
src/cli/commands.ts+56−0
@@ -244,6 +244,59 @@ function handleContext(ctx: CommandContext, args: string): void {
244244
245245 writeln(`${PREFIX.error} usage: /context <prune|cap> ...`);
246246 }
247+function handleCache(ctx: CommandContext, args: string): void {
248+ const [sub, value] = args.trim().split(/\s+/, 2);
249+
250+ if (!sub) {
251+ const gCache = ctx.googleCachedContent
252+ ? c.cyan(ctx.googleCachedContent)
253+ : "off";
254+ writeln(
255+ `${PREFIX.info} prompt-caching=${ctx.promptCachingEnabled ? c.green("on") : c.dim("off")} openai-retention=${c.cyan(ctx.openaiPromptCacheRetention)} gemini-cache=${gCache}`,
256+ );
257+ writeln(c.dim(" usage: /cache <on|off>"));
258+ writeln(c.dim(" /cache openai <in_memory|24h>"));
259+ writeln(c.dim(" /cache gemini <off|cachedContents/...>"));
260+ return;
261+ }
262+
263+ if (sub === "on" || sub === "off") {
264+ ctx.setPromptCachingEnabled(sub === "on");
265+ writeln(
266+ `${PREFIX.success} prompt caching → ${sub === "on" ? c.green("on") : c.dim("off")}`,
267+ );
268+ return;
269+ }
270+
271+ if (sub === "openai") {
272+ if (value === "in_memory" || value === "24h") {
273+ ctx.setOpenAIPromptCacheRetention(value);
274+ writeln(
275+ `${PREFIX.success} openai prompt cache retention → ${c.cyan(value)}`,
276+ );
277+ return;
278+ }
279+ writeln(`${PREFIX.error} usage: /cache openai <in_memory|24h>`);
280+ return;
281+ }
282+
283+ if (sub === "gemini") {
284+ if (!value) {
285+ writeln(`${PREFIX.error} usage: /cache gemini <off|cachedContents/...>`);
286+ return;
287+ }
288+ if (value === "off") {
289+ ctx.setGoogleCachedContent(null);
290+ writeln(`${PREFIX.success} gemini cached content → ${c.dim("off")}`);
291+ return;
292+ }
293+ ctx.setGoogleCachedContent(value);
294+ writeln(`${PREFIX.success} gemini cached content → ${c.cyan(value)}`);
295+ return;
296+ }
297+
298+ writeln(`${PREFIX.error} usage: /cache <on|off|openai|gemini> ...`);
299+}
247300
248301 function handlePlan(ctx: CommandContext): void {
249302 ctx.setPlanMode(!ctx.planMode);
@@ -615,6 +668,9 @@ export async function handleCommand(
615668 case "context":
616669 handleContext(ctx, args);
617670 return { type: "handled" };
671+ case "cache":
672+ handleCache(ctx, args);
673+ return { type: "handled" };
618674
619675 case "plan":
620676 handlePlan(ctx);
src/cli/types.ts+6−0
@@ -13,6 +13,12 @@ export interface CommandContext {
1313 setPruningMode: (mode: ContextPruningMode) => void;
1414 toolResultPayloadCapBytes: number;
1515 setToolResultPayloadCapBytes: (bytes: number) => void;
16+ promptCachingEnabled: boolean;
17+ setPromptCachingEnabled: (enabled: boolean) => void;
18+ openaiPromptCacheRetention: "in_memory" | "24h";
19+ setOpenAIPromptCacheRetention: (retention: "in_memory" | "24h") => void;
20+ googleCachedContent: string | null;
21+ setGoogleCachedContent: (contentId: string | null) => void;
1622 planMode: boolean;
1723 setPlanMode: (enabled: boolean) => void;
1824 ralphMode: boolean;
src/index.ts+11−0
@@ -26,7 +26,10 @@ import { autoDiscoverModel } from "./llm-api/providers.ts";
2626
2727 import {
2828 getPreferredContextPruningMode,
29+ getPreferredGoogleCachedContent,
2930 getPreferredModel,
31+ getPreferredOpenAIPromptCacheRetention,
32+ getPreferredPromptCachingEnabled,
3033 getPreferredShowReasoning,
3134 getPreferredThinkingEffort,
3235 getPreferredToolResultPayloadCapBytes,
@@ -103,6 +106,10 @@ async function main(): Promise<void> {
103106 initialPruningMode: getPreferredContextPruningMode(),
104107 initialToolResultPayloadCapBytes:
105108 getPreferredToolResultPayloadCapBytes(),
109+ initialPromptCachingEnabled: getPreferredPromptCachingEnabled(),
110+ initialOpenAIPromptCacheRetention:
111+ getPreferredOpenAIPromptCacheRetention(),
112+ initialGoogleCachedContent: getPreferredGoogleCachedContent(),
106113 reporter: new HeadlessReporter(),
107114 headless: true,
108115 ...(agentSystemPrompt ? { agentSystemPrompt } : {}),
@@ -146,6 +153,10 @@ async function main(): Promise<void> {
146153 initialShowReasoning: getPreferredShowReasoning(),
147154 initialPruningMode: getPreferredContextPruningMode(),
148155 initialToolResultPayloadCapBytes: getPreferredToolResultPayloadCapBytes(),
156+ initialPromptCachingEnabled: getPreferredPromptCachingEnabled(),
157+ initialOpenAIPromptCacheRetention:
158+ getPreferredOpenAIPromptCacheRetention(),
159+ initialGoogleCachedContent: getPreferredGoogleCachedContent(),
149160 reporter: new CliReporter(),
150161 };
151162 if (sessionId) agentOpts.sessionId = sessionId;
src/llm-api/providers.test.ts+79−0
@@ -42,3 +42,82 @@ describe("getThinkingProviderOptions", () => {
4242 });
4343 });
4444 });
45+
46+import { getCacheFamily, getCachingProviderOptions } from "./providers.ts";
47+
48+describe("getCacheFamily", () => {
49+ test("identifies anthropic family", () => {
50+ expect(getCacheFamily("anthropic/claude-3-opus")).toBe("anthropic");
51+ expect(getCacheFamily("zen/claude-sonnet-4-6")).toBe("anthropic");
52+ });
53+ test("identifies openai family", () => {
54+ expect(getCacheFamily("openai/gpt-4")).toBe("openai");
55+ expect(getCacheFamily("zen/gpt-4o")).toBe("openai");
56+ expect(getCacheFamily("zen/o1")).toBe("openai");
57+ });
58+ test("identifies google family", () => {
59+ expect(getCacheFamily("google/gemini-2.0-flash")).toBe("google");
60+ expect(getCacheFamily("zen/gemini-2.5-pro")).toBe("google");
61+ });
62+ test("identifies none for others", () => {
63+ expect(getCacheFamily("ollama/llama3")).toBe("none");
64+ });
65+});
66+
67+describe("getCachingProviderOptions", () => {
68+ test("returns null if disabled", () => {
69+ expect(
70+ getCachingProviderOptions("openai/gpt-4", { enabled: false }),
71+ ).toBeNull();
72+ });
73+
74+ test("returns openai prompt cache retention", () => {
75+ expect(
76+ getCachingProviderOptions("openai/gpt-4", {
77+ enabled: true,
78+ openaiRetention: "24h",
79+ }),
80+ ).toEqual({
81+ openai: { promptCacheRetention: "24h" },
82+ });
83+ });
84+
85+ test("returns google cached content when explicit caching is compatible", () => {
86+ expect(
87+ getCachingProviderOptions("google/gemini-1.5-pro", {
88+ enabled: true,
89+ googleCachedContent: "cache-123",
90+ googleExplicitCachingCompatible: true,
91+ }),
92+ ).toEqual({
93+ google: { cachedContent: "cache-123" },
94+ });
95+ });
96+
97+ test("returns null for google when explicit caching is incompatible", () => {
98+ expect(
99+ getCachingProviderOptions("google/gemini-1.5-pro", {
100+ enabled: true,
101+ googleCachedContent: "cache-123",
102+ googleExplicitCachingCompatible: false,
103+ }),
104+ ).toBeNull();
105+ });
106+
107+ test("returns null for google if no content id", () => {
108+ expect(
109+ getCachingProviderOptions("google/gemini-1.5-pro", {
110+ enabled: true,
111+ googleCachedContent: null,
112+ }),
113+ ).toBeNull();
114+ });
115+
116+ test("returns null for anthropic (handled via messages)", () => {
117+ expect(
118+ getCachingProviderOptions("anthropic/claude-3-opus", {
119+ enabled: true,
120+ }),
121+ ).toBeNull();
122+ });
123+});
src/llm-api/providers.ts+61−0
@@ -288,6 +288,67 @@ export function getThinkingProviderOptions(
288288 // return null and let the call proceed without thinking options.
289289 return null;
290290 }
291+interface CachingOptions {
292+ enabled: boolean;
293+ openaiRetention?: "in_memory" | "24h";
294+ googleCachedContent?: string | null;
295+ googleExplicitCachingCompatible?: boolean;
296+}
297+
298+type CacheFamily = "openai" | "google" | "anthropic" | "none";
299+
300+export function getCacheFamily(modelString: string): CacheFamily {
301+ const { provider, modelId } = parseModelString(modelString);
302+
303+ if (
304+ provider === "anthropic" ||
305+ (provider === "zen" && modelId.startsWith("claude-"))
306+ ) {
307+ return "anthropic";
308+ }
309+
310+ if (
311+ provider === "openai" ||
312+ (provider === "zen" &&
313+ (modelId.startsWith("gpt-") || modelId.startsWith("o")))
314+ ) {
315+ return "openai";
316+ }
317+
318+ if (
319+ provider === "google" ||
320+ (provider === "zen" && modelId.startsWith("gemini-"))
321+ ) {
322+ return "google";
323+ }
324+
325+ return "none";
326+}
327+
328+export function getCachingProviderOptions(
329+ modelString: string,
330+ opts: CachingOptions,
331+): Record<string, unknown> | null {
332+ if (!opts.enabled) return null;
333+
334+ const family = getCacheFamily(modelString);
335+
336+ if (family === "openai") {
337+ return {
338+ openai: { promptCacheRetention: opts.openaiRetention ?? "in_memory" },
339+ };
340+ }
341+
342+ if (
343+ family === "google" &&
344+ opts.googleCachedContent &&
345+ opts.googleExplicitCachingCompatible !== false
346+ ) {
347+ return { google: { cachedContent: opts.googleCachedContent } };
348+ }
349+
350+ return null;
351+}
291352
292353 /**
293354 * Return the known context window size (in tokens) for a model string.
src/llm-api/turn.test.ts+83−0
@@ -1,6 +1,7 @@
11 import { describe, expect, test } from "bun:test";
22 import type { CoreMessage } from "./turn.ts";
33 import {
4+ annotateAnthropicCacheBreakpoints,
45 applyContextPruning,
56 compactToolResultPayloads,
67 getMessageDiagnostics,
@@ -729,3 +730,85 @@ describe("compactToolResultPayloads", () => {
729730 expectCompactedJsonOutput({ type: "text", value: largePayload });
730731 });
731732 });
733+
734+describe("annotateAnthropicCacheBreakpoints", () => {
735+ test("adds cache control to system prompt and removes it from returned systemPrompt", () => {
736+ const messages: CoreMessage[] = [{ role: "user", content: "hello" }];
737+ const {
738+ messages: annotated,
739+ systemPrompt,
740+ diagnostics,
741+ } = annotateAnthropicCacheBreakpoints(messages, "System rules");
742+
743+ expect(systemPrompt).toBeUndefined();
744+ expect(annotated.length).toBe(2);
745+ expect(annotated[0]).toEqual({
746+ role: "system",
747+ content: "System rules",
748+ providerOptions: {
749+ anthropic: { cacheControl: { type: "ephemeral" } },
750+ },
751+ });
752+ expect(diagnostics.breakpointsAdded).toBe(1);
753+ });
754+
755+ test("adds breakpoint to second to last message if there are enough messages", () => {
756+ const messages: CoreMessage[] = [
757+ { role: "user", content: "m1" },
758+ { role: "assistant", content: "m2" },
759+ { role: "user", content: "m3" },
760+ { role: "assistant", content: "m4" },
761+ ];
762+ const {
763+ messages: annotated,
764+ systemPrompt,
765+ diagnostics,
766+ } = annotateAnthropicCacheBreakpoints(messages, undefined);
767+
768+ expect(systemPrompt).toBeUndefined();
769+ expect(annotated.length).toBe(4);
770+ // 2nd to last message is index 2 (m3)
771+ expect(annotated[2]).toEqual({
772+ role: "user",
773+ content: "m3",
774+ providerOptions: {
775+ anthropic: { cacheControl: { type: "ephemeral" } },
776+ },
777+ });
778+ expect(annotated[3]?.providerOptions).toBeUndefined();
779+ expect(diagnostics.breakpointsAdded).toBe(1);
780+ });
781+
782+ test("handles system prompt and second to last message together", () => {
783+ const messages: CoreMessage[] = [
784+ { role: "user", content: "m1" },
785+ { role: "assistant", content: "m2" },
786+ { role: "user", content: "m3" },
787+ ];
788+ const {
789+ messages: annotated,
790+ systemPrompt,
791+ diagnostics,
792+ } = annotateAnthropicCacheBreakpoints(messages, "System rules");
793+
794+ expect(systemPrompt).toBeUndefined();
795+ expect(annotated.length).toBe(4);
796+
797+ // system message
798+ expect(annotated[0]).toEqual({
799+ role: "system",
800+ content: "System rules",
801+ providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
802+ });
803+
804+ // 2nd to last message was index 1 of the original array, which is "assistant m2".
805+ // Now it is at index 2 of annotated array.
806+ expect(annotated[2]).toEqual({
807+ role: "assistant",
808+ content: "m2",
809+ providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
810+ });
811+
812+ expect(diagnostics.breakpointsAdded).toBe(2);
813+ });
814+});
src/llm-api/turn.ts+115−4
@@ -8,6 +8,8 @@ import {
88 } from "ai";
99 import { logApiEvent } from "./api-log.ts";
1010 import {
11+ getCacheFamily,
12+ getCachingProviderOptions,
1113 getThinkingProviderOptions,
1214 parseModelString,
1315 type ThinkingEffort,
@@ -624,12 +626,83 @@ export function isOpenAIGPT(modelString: string): boolean {
624626 );
625627 }
626628
629+export function annotateAnthropicCacheBreakpoints(
630+ turnMessages: CoreMessage[],
631+ systemPrompt?: string,
632+): {
633+ messages: CoreMessage[];
634+ systemPrompt?: string;
635+ diagnostics: { breakpointsAdded: number; stableIdx: number };
636+} {
637+ const finalMessages = [...turnMessages];
638+ let breakpointsAdded = 0;
639+
640+ // Breakpoint 2: The last user message or 2nd to last message,
641+ // to cache the conversation history minus the very last turn.
642+ const stableIdx = finalMessages.length > 2 ? finalMessages.length - 2 : -1;
643+ if (stableIdx >= 0 && finalMessages[stableIdx]) {
644+ const msg = finalMessages[stableIdx];
645+ finalMessages[stableIdx] = {
646+ ...msg,
647+ providerOptions: {
648+ ...(msg?.providerOptions ?? {}),
649+ anthropic: {
650+ ...((msg?.providerOptions?.anthropic as Record<string, unknown>) ??
651+ {}),
652+ cacheControl: { type: "ephemeral" },
653+ },
654+ },
655+ } as CoreMessage;
656+ breakpointsAdded++;
657+ }
658+
659+ // Breakpoint 1: the system prompt
660+ let finalSystemPrompt = systemPrompt;
661+ if (systemPrompt) {
662+ finalMessages.unshift({
663+ role: "system",
664+ content: systemPrompt,
665+ providerOptions: {
666+ anthropic: { cacheControl: { type: "ephemeral" } },
667+ },
668+ });
669+ finalSystemPrompt = undefined; // Do not send as top-level system
670+ breakpointsAdded++;
671+ }
672+
673+ return {
674+ messages: finalMessages,
675+ ...(finalSystemPrompt !== undefined
676+ ? { systemPrompt: finalSystemPrompt }
677+ : {}),
678+ diagnostics: { breakpointsAdded, stableIdx },
679+ };
680+}
681+
627682 /**
628683 * Run a single agent turn against the model.
629684 *
630685 * Yields TurnEvents as they arrive, then yields a final TurnCompleteEvent
631686 * (or TurnErrorEvent on failure).
632687 */
688+// helper for deep merge
689+const mergeDeep = (
690+ target: Record<string, unknown>,
691+ source: Record<string, unknown>,
692+) => {
693+ const output: Record<string, unknown> = { ...target };
694+ for (const key in source) {
695+ const sVal = source[key];
696+ const tVal = target[key];
697+ if (isRecord(sVal) && isRecord(tVal)) {
698+ output[key] = { ...tVal, ...sVal };
699+ } else {
700+ output[key] = sVal;
701+ }
702+ }
703+ return output;
704+};
705+
633706 export async function* runTurn(options: {
634707 model: CoreModel;
635708 modelString: string;
@@ -640,6 +713,9 @@ export async function* runTurn(options: {
640713 thinkingEffort?: ThinkingEffort;
641714 pruningMode?: ContextPruningMode;
642715 toolResultPayloadCapBytes?: number;
716+ promptCachingEnabled?: boolean;
717+ openaiPromptCacheRetention?: "in_memory" | "24h";
718+ googleCachedContent?: string | null;
643719 }): AsyncGenerator<TurnEvent> {
644720 const {
645721 model,
@@ -650,6 +726,9 @@ export async function* runTurn(options: {
650726 signal,
651727 thinkingEffort,
652728 pruningMode = "balanced",
729+ promptCachingEnabled = true,
730+ openaiPromptCacheRetention = "in_memory",
731+ googleCachedContent = null,
653732 toolResultPayloadCapBytes = DEFAULT_TOOL_RESULT_PAYLOAD_CAP_BYTES,
654733 } = options;
655734
@@ -745,8 +824,21 @@ export async function* runTurn(options: {
745824 diagnostics: getMessageDiagnostics(turnMessages),
746825 });
747826 }
748-
749- const mergedProviderOptions = {
827+ const cacheFamily = getCacheFamily(modelString);
828+ const googleExplicitCachingCompatible = toolCount === 0 && !systemPrompt;
829+ const cacheOpts = getCachingProviderOptions(modelString, {
830+ enabled: promptCachingEnabled,
831+ openaiRetention: openaiPromptCacheRetention,
832+ googleCachedContent,
833+ googleExplicitCachingCompatible,
834+ });
835+ logApiEvent("prompt caching configured", {
836+ enabled: promptCachingEnabled,
837+ cacheFamily,
838+ cacheOpts,
839+ googleExplicitCachingCompatible,
840+ });
841+ let mergedProviderOptions = {
750842 ...(thinkingOpts ?? {}),
751843 ...(isOpenAIGPT(modelString)
752844 ? {
@@ -771,9 +863,26 @@ export async function* runTurn(options: {
771863 : {}),
772864 };
773865
866+ if (cacheOpts) {
867+ mergedProviderOptions = mergeDeep(mergedProviderOptions, cacheOpts);
868+ }
869+
870+ let finalMessages = turnMessages;
871+ let finalSystemPrompt = systemPrompt;
872+
873+ if (cacheFamily === "anthropic" && promptCachingEnabled) {
874+ const annotated = annotateAnthropicCacheBreakpoints(
875+ turnMessages,
876+ systemPrompt,
877+ );
878+ finalMessages = annotated.messages;
879+ finalSystemPrompt = annotated.systemPrompt;
880+ logApiEvent("Anthropic prompt caching", annotated.diagnostics);
881+ }
882+
774883 const streamOpts: StreamTextOptions = {
775884 model,
776- messages: turnMessages,
885+ messages: finalMessages,
777886 tools: toolSet,
778887 stopWhen: stepCountIs(MAX_STEPS),
779888 onStepFinish: (step: StepResult<ToolSet>) => {
@@ -807,7 +916,9 @@ export async function* runTurn(options: {
807916 return undefined;
808917 },
809918
810- ...(systemPrompt && !useInstructions ? { system: systemPrompt } : {}),
919+ ...(finalSystemPrompt && !useInstructions
920+ ? { system: finalSystemPrompt }
921+ : {}),
811922 ...(Object.keys(mergedProviderOptions).length > 0
812923 ? { providerOptions: mergedProviderOptions }
813924 : {}),
src/session/db/settings-repo.ts+37−0
@@ -89,3 +89,40 @@ export function setPreferredActiveAgent(agent: string | null): void {
8989 setSetting("preferred_active_agent", agent);
9090 }
9191 }
92+export function getPreferredPromptCachingEnabled(): boolean {
93+ const v = getSetting("preferred_prompt_caching_enabled");
94+ if (v === null) return true;
95+ return v !== "false";
96+}
97+
98+export function setPreferredPromptCachingEnabled(enabled: boolean): void {
99+ setSetting("preferred_prompt_caching_enabled", enabled ? "true" : "false");
100+}
101+
102+export function getPreferredOpenAIPromptCacheRetention(): "in_memory" | "24h" {
103+ const v = getSetting("preferred_openai_prompt_cache_retention");
104+ if (v === "24h") return "24h";
105+ return "in_memory";
106+}
107+
108+export function setPreferredOpenAIPromptCacheRetention(
109+ retention: "in_memory" | "24h",
110+): void {
111+ setSetting("preferred_openai_prompt_cache_retention", retention);
112+}
113+
114+export function getPreferredGoogleCachedContent(): string | null {
115+ return getSetting("preferred_google_cached_content");
116+}
117+
118+export function setPreferredGoogleCachedContent(
119+ contentId: string | null,
120+): void {
121+ if (contentId === null) {
122+ getDb().run(
123+ "DELETE FROM settings WHERE key = 'preferred_google_cached_content'",
124+ );
125+ } else {
126+ setSetting("preferred_google_cached_content", contentId);
127+ }
128+}
src/session/manager.ts+4−3
@@ -17,19 +17,20 @@ export interface ActiveSession {
1717 id: string;
1818 model: string;
1919 messages: CoreMessage[];
20+ createdAt: number;
2021 }
2122
2223 export function newSession(model: string, cwd: string): ActiveSession {
2324 const id = generateSessionId();
24- createSession({ id, cwd, model });
25- return { id, model, messages: [] };
25+ const row = createSession({ id, cwd, model });
26+ return { id, model, messages: [], createdAt: row.created_at };
2627 }
2728
2829 export function resumeSession(id: string): ActiveSession | null {
2930 const row = getSession(id);
3031 if (!row) return null;
3132 const messages = loadMessages(id);
32- return { id: row.id, model: row.model, messages };
33+ return { id: row.id, model: row.model, messages, createdAt: row.created_at };
3334 }
3435
3536 export function touchActiveSession(session: ActiveSession): void {
zen-prompt-caching-implementation-plan.md+485−0
@@ -0,0 +1,485 @@
1+# Zen prompt caching implementation plan
2+
3+## Summary
4+
5+Goal: assume Zen forwards the same provider-specific cache settings that the Vercel AI SDK supports, and update mini-coder so Zen requests actually use prompt caching where possible.
6+
7+The key conclusion from the code review is that we already have most of the plumbing needed for **top-level provider options**, but we do **not** currently have:
8+
9+- any cache-specific settings or request shaping
10+- any per-message provider-option injection for Anthropic cache breakpoints
11+- any Gemini explicit-cache lifecycle support
12+- a stable system prompt prefix suitable for cache reuse
13+
14+The last point is the biggest blocker: `buildSystemPrompt()` currently injects a fresh `Current date/time` string on every turn, which makes the prompt prefix change every turn and substantially defeats provider-side prefix caching.
15+
16+## Findings
17+
18+### 1) Zen already runs through the same provider SDKs that expose cache settings
19+
20+Mini-coder routes Zen models through the same AI SDK providers Zen recommends:
21+
22+- `@ai-sdk/anthropic`, `@ai-sdk/google`, `@ai-sdk/openai` are installed in `package.json:22-24`
23+- Zen Anthropic provider factory: `src/llm-api/providers.ts:70-79`
24+- Zen OpenAI provider factory: `src/llm-api/providers.ts:82-91`
25+- Zen Google provider factory: `src/llm-api/providers.ts:94-103`
26+
27+That means the implementation path is to change **request construction**, not provider selection.
28+
29+### 2) `runTurn()` already has a top-level provider-options merge point
30+
31+The main request path is in `src/llm-api/turn.ts:644-824`.
32+
33+Important pieces:
34+
35+- current request options are assembled in `mergedProviderOptions` at `src/llm-api/turn.ts:749-772`
36+- those options are passed into `streamText()` at `src/llm-api/turn.ts:811-813`
37+- the final call is `streamText(streamOpts)` at `src/llm-api/turn.ts:824`
38+
39+This is already sufficient for providers that accept cache settings at the **function-call level**:
40+
41+- OpenAI prompt caching settings
42+- Google `cachedContent`
43+
44+It is **not** sufficient for Anthropic prompt caching, because Anthropic cache control is attached to **messages / content blocks**, not just the top-level call.
45+
46+### 3) The current system prompt shape is hostile to cache reuse
47+
48+`buildSystemPrompt()` is rebuilt on every turn in `src/agent/session-runner.ts:161-166`.
49+
50+Inside that function, the prompt includes:
51+
52+- working directory: `src/agent/system-prompt.ts:84-91`
53+- **current date/time** via `new Date().toLocaleString(...)`: `src/agent/system-prompt.ts:85`
54+
55+Because that timestamp changes every turn, the repeated prefix is not stable across turns. Even if Zen/OpenAI/Anthropic support provider-side prompt caching, the changing timestamp makes the highest-value prefix differ near the top of the prompt.
56+
57+This should be treated as a required prerequisite for meaningful caching.
58+
59+### 4) Anthropic needs message-level request shaping that we do not have today
60+
61+Right now, the request uses:
62+
63+- `messages: turnMessages` at `src/llm-api/turn.ts:776`
64+- optional top-level `system` at `src/llm-api/turn.ts:810`
65+- optional top-level `providerOptions` at `src/llm-api/turn.ts:811-813`
66+
67+There is currently no helper that walks `CoreMessage[]` and annotates specific messages or parts with provider options.
68+
69+That matters because Anthropic prompt caching needs `cacheControl` attached to stable prefix content rather than only to the whole request.
70+
71+### 5) Message persistence is already compatible with cache metadata
72+
73+Lossless message persistence is already a design invariant:
74+
75+- save verbatim JSON: `src/session/db/message-repo.ts:16-23`
76+- load verbatim JSON: `src/session/db/message-repo.ts:62-78`
77+- runner preserves model-authored message shape: `src/agent/session-runner.ts:198-203`
78+
79+This is good news for caching because provider metadata on messages or content parts can survive round-trips if we need it.
80+
81+### 6) Existing history sanitizers are not a blocker, but they must be respected
82+
83+Before requests are sent, history passes through:
84+
85+- Gemini tool-message sanitization: `src/llm-api/turn.ts:693-707`
86+- GPT commentary stripping: `src/llm-api/turn.ts:709-715`
87+- OpenAI item-id stripping: `src/llm-api/turn.ts:717-723`
88+- context pruning: `src/llm-api/turn.ts:729-736`
89+- tool-result compaction: `src/llm-api/turn.ts:738-747`
90+
91+Any cache annotation helper must run **after** the structural sanitizers that intentionally rewrite history, otherwise the cache annotations can be dropped or attached to messages that later get removed.
92+
93+### 7) Gemini explicit caching is only partially supported by the current stack
94+
95+The AI SDK Google provider supports `providerOptions.google.cachedContent`, which matches our existing top-level provider-options plumbing.
96+
Cut short: this commit's diff is over 1000 lines.