@hncode/hncode 0.3.2 → 0.3.4

package/README.md

@@ -13,10 +13,53 @@ A cyan-blue terminal user interface (TUI) coding agent inspired by [Kimi Code](h
 - **Cyan-blue TUI**: Raw terminal renderer for perfect Windows Terminal compatibility
 - **Dual Protocol Support**: Works with both OpenAI-compatible APIs and Anthropic
 - **Smart Context Management**: Auto-compaction at 85% usage, AI-summarized history retention
+- **Prompt Caching**: Explicit cache breakpoints for the stable prefix (`/cache`)
 - **MCP-style Toolbelt**: Read, Write, Edit, Bash, Glob, Grep, TodoList, WebSearch, etc.
+- **MCP Client**: Connect real Model Context Protocol servers (stdio + HTTP) and use their tools
+- **Skills**: Package reusable prompts as Markdown (`/import-skill`, `/skill:<name>` with tab-completion)
+- **Shell Hooks**: Run your own commands at lifecycle events (`PreToolUse`, `PostToolUse`, …)
+- **Git Workflow**: `/git`, `/commit`, `/branch`, `/worktree`, `/pr` plus a `Git` tool for the agent
+- **Plan Review**: Review what a plan will touch, edit it, then approve before any file changes
 - **Plugin System**: Extend with custom tools, commands, and hooks
 - **Session Persistence**: Resume conversations across sessions
 - **Permission Modes**: Ask, YOLO, or Auto modes for different workflows
+- **Shell Passthrough**: type `!` on an empty prompt to switch the composer into shell mode — no model round-trip
+- **CI / Scripting**: Headless `-p` with `json` / `stream-json` output and outcome-based exit codes
+- **Remote Control**: `--control` exposes a local socket to prompt/status/interrupt a running session
+
+### CI usage
+
+```bash
+# One prompt, machine-readable result, exit code reflects the outcome.
+hncode -p "fix the failing tests" --output-format json
+# -> {"type":"result","ok":true,"reply":"…","toolCalls":["Bash"],"files":["src/a.js"],…}
+
+# Exit codes: 0 ok · 1 failure · 2 config · 3 no answer · 4 interrupted
+hncode -p "run the linter and fix everything" --output-format stream-json | jq -c 'select(.type=="result")'
+```
+
+### Shell passthrough
+
+Type `!` on an **empty** prompt to switch the composer into shell mode — the `!`
+becomes the prompt symbol and the line runs directly, with no model involved:
+
+```
+! git add -A && git push
+! npm test
+```
+
+The `!` is a mode marker, not part of what you type, so it appears exactly once.
+Press `Esc` or `Backspace` on an empty line to leave the mode. Output appears in
+the transcript as a `↳` receipt.
+
+### Remote control
+
+```bash
+hncode --control                       # in one terminal (TUI)
+hncode control status                  # in another
+hncode control prompt "run the tests"  # queue a prompt on the running session
+hncode control interrupt
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hncode/hncode",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "hncode — A cyan-blue TUI AI coding agent with zero runtime dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/agent-task.js

@@ -176,3 +176,81 @@ export function statusColor(status) {
   if (status === 'completed') return 'gray';
   return 'red';
 }
+
+// ---- background-task transcript card (mirrors kimi-code) --------------------
+// A background task reports its lifecycle as a one-line card in the transcript:
+//
+//     ● agent task completed in background (review the diff)
+//     ✗ bash task failed in background (npm test · exit 1)
+//
+// `phase` drives the bullet colour (started / completed / failed); `headline`
+// and the dim `detail` carry the rest. Ported from kimi-code's
+// formatBackgroundTaskTranscript (apps/kimi-code/src/tui/utils/background-task-status.ts)
+// so the two tools read the same way.
+
+const BG_DETAIL_MAX = 240;
+
+function bgTruncate(value) {
+  if (value === undefined || value === null) return undefined;
+  const collapsed = String(value).trim().replace(/\s+/g, ' ');
+  if (!collapsed) return undefined;
+  return collapsed.length <= BG_DETAIL_MAX ? collapsed : collapsed.slice(0, BG_DETAIL_MAX - 1) + '…';
+}
+
+export function backgroundTaskPhase(status) {
+  if (status === 'running') return 'started';
+  if (status === 'completed') return 'completed';
+  return 'failed';   // failed / timed_out / killed / lost
+}
+
+function bgSubject(kind) {
+  if (kind === 'agent') return 'agent task';
+  if (kind === 'question') return 'question task';
+  return 'bash task';
+}
+
+function bgHeadline(status, kind) {
+  const subject = bgSubject(kind);
+  switch (status) {
+    case 'running': return `${subject} started in background`;
+    case 'completed': return `${subject} completed in background`;
+    case 'failed': return `${subject} failed in background`;
+    case 'timed_out': return `${subject} timed out`;
+    case 'killed': return `${subject} stopped`;
+    case 'lost': return `${subject} lost`;
+    default: return `${subject} ${status}`;
+  }
+}
+
+function bgDetail(task) {
+  const parts = [];
+  const description = bgTruncate(task.description);
+  if (description !== undefined) parts.push(description);
+
+  if (task.status === 'completed' || task.status === 'failed') {
+    if (task.kind === 'process' && task.exitCode !== null && task.exitCode !== undefined) {
+      parts.push(`exit ${task.exitCode}`);
+    }
+  }
+  if (task.status === 'killed') {
+    const reason = bgTruncate(task.stopReason);
+    parts.push(reason !== undefined ? `stopped — ${reason}` : 'stopped');
+  }
+  if (task.status === 'failed') {
+    const reason = bgTruncate(task.stopReason);
+    if (reason !== undefined) parts.push(reason);
+  }
+  if (task.status === 'timed_out') parts.push('timed out');
+  if (task.status === 'lost') parts.push('session restarted before completion');
+
+  return parts.length ? parts.join(' · ') : undefined;
+}
+
+// Build the card payload for a task snapshot.
+export function backgroundTaskCard(task) {
+  return {
+    phase: backgroundTaskPhase(task.status),
+    headline: bgHeadline(task.status, task.kind),
+    detail: bgDetail(task),
+  };
+}

package/src/agent.js

@@ -7,22 +7,28 @@ import { tools, getTool, llmTools } from './tools/index.js';
 import { DELEGATION_TOOLS } from './subagent-types.js';
 import { estimateMessagesTokens } from './term.js';
 import { runHooks } from './plugin.js';
+import { loadHooks, runShellHooks } from './hooks.js';
 
-// ---- completion guard --------------------------------------------------------
-// A turn is only complete when the model ends it with an actual answer. Models
-// do stop mid-task: the stream ends right after a reasoning block, or with an
-// empty assistant message, and the caller would report "done" for unfinished
-// work. When that happens we tell the model what it did and give it more steps.
-// Bounded, so a model that insists on stopping cannot loop forever.
-export const MAX_NUDGES = 5;
-
-export function nudgeMessage(why) {
-  return `[hncode] Your turn ended without a final answer: ${why}. `
-    + 'This usually means the task is not finished. If the work IS complete, reply with a short '
-    + 'summary of what changed and how you verified it. Otherwise keep going with the tools right '
-    + 'now — do not stop silently.';
+// A short, stable key for the prompt cache, derived from the conversation's
+// first user message. Stability is the whole point: the same conversation must
+// produce the same key on every turn, so a cheap deterministic hash beats a
+// random id. (Different conversations may collide — that is harmless, it only
+// means the provider's routing key is shared.)
+function hashKey(s) {
+  let h = 0x811c9dc5;
+  const str = String(s || '');
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h * 0x01000193) >>> 0;
+  }
+  return h.toString(36) + '-' + str.length.toString(36);
 }
 
+
+// Final instruction appended to the system prompt (see SYSTEM_PROMPT).
+// (The wording lives in SYSTEM_PROMPT itself, under "Finishing a turn".)
+
+
 // Final instruction appended to the system prompt (see SYSTEM_PROMPT).
 // (The wording lives in SYSTEM_PROMPT itself, under "Finishing a turn".)
 
@@ -118,9 +124,28 @@ export class Agent {
     // tool a live getter over this agent's own messages instead of a copy, so the
     // snapshot is taken at spawn time and reflects everything up to that point.
     this.ctx._parentMessages = this.messages;
+    // Prompt-cache key: identify the SESSION, not the request, so the cached
+    // prefix is reused across turns instead of thrashing. The caller may pass one
+    // (the TUI knows the session id); otherwise derive a stable value from the
+    // first user message so repeated runs of the same conversation still share a
+    // prefix. A subagent inherits the parent's key (same conversation family).
+    if (cfg.sessionId == null) {
+      const firstUser = (Array.isArray(messages) ? messages : []).find((m) => m.role === 'user' && typeof m.content === 'string');
+      cfg = { ...cfg, sessionId: firstUser ? hashKey(firstUser.content) : 'default' };
+      this.cfg = cfg;
+    }
     this.llm = new LLM(cfg);
     this.stopRequested = false;
     this.onApproval = onApproval; // async (toolName, args) => boolean
+    // Shell hooks (Claude Code-style): user-configured commands run at lifecycle
+    // events. ALWAYS stored as a `{ hooks: {Event: [...]} }` config, which is the
+    // shape runShellHooks() reads. A caller may inject one (tests / the TUI,
+    // which reloads per turn); otherwise it is read from disk for this workspace.
+    this.hookConfig = cfg.hookConfig
+      ? (cfg.hookConfig.hooks ? cfg.hookConfig : { hooks: cfg.hookConfig })
+      : { hooks: loadHooks(cfg.workspace).hooks };
+    // The turn's user prompt, for the UserPromptSubmit hook. Set by run().
+    this._turnPrompt = '';
     // Messages the user types while the agent is streaming. They are injected
     // as user messages right AFTER the current round of tool calls, so the
     // model sees "tool callback / user steer" together on the next request —
@@ -147,11 +172,23 @@ export class Agent {
     // block at the end of this method. Both are awaited and both swallow plugin
     // errors (see runHooks), so a broken plugin cannot abort a turn.
     await runHooks('onTurnStart', { messages: this.messages });
+    // SHELL HOOK: SessionStart fires once per agent run (the first turn of a
+    // session). A hook failure never blocks — it is a convenience signal.
+    await runShellHooks(this.hookConfig, 'SessionStart', { messages: this.messages }, this.cfg.workspace);
+    // SHELL HOOK: UserPromptSubmit fires with the latest user message. It cannot
+    // block (Claude Code's can add context; blocking the user's own prompt is a
+    // worse failure than a missing hook), so the result is only logged.
+    {
+      const lastUser = [...this.messages].reverse().find((m) => m.role === 'user' && typeof m.content === 'string');
+      if (lastUser) {
+        this._turnPrompt = lastUser.content;
+        await runShellHooks(this.hookConfig, 'UserPromptSubmit', { prompt: lastUser.content }, this.cfg.workspace);
+      }
+    }
     let text = '';
     let toolCalls = [];
     let emittedEnd = false;
     let thought = '';
-    let nudges = 0;
     // decide whether running out of steps actually left the turn unfinished.
     let hadToolCallsOnFinalStep = false;
 
@@ -204,8 +241,6 @@ export class Agent {
     // No step cap: the loop runs until the model produces a final answer, the
     // user interrupts (Esc / Ctrl-C), or an error ends the turn. maxSteps is
     // kept only for callers that explicitly request a bound (0/undefined = none).
-    // Runaway safety comes from the completion guard (MAX_NUDGES) and the user's
-    // ability to interrupt, not from a fixed tool-round budget.
     const stepLimit = (this.maxSteps > 0) ? this.maxSteps : Infinity;
     for (let step = 0; step < stepLimit; step++) {
       // Process any steer messages collected during the previous step
@@ -230,32 +265,90 @@ export class Agent {
       // preserved rather than simply discarded.
       const maxCtx = this.cfg.maxContextTokens || 512000;
       let usedNow = estimateMessagesTokens(this.messages, this.cfg);
-      if (maxCtx > 0 && usedNow >= maxCtx * 0.85) {
+      if (this.cfg.autoCompact !== false && maxCtx > 0 && usedNow >= maxCtx * 0.85) {
         const before = usedNow;
-        const keepN = Math.max(1, Math.ceil(this.messages.length * 0.2));
-        const keep = this.messages.slice(-keepN);
-        const dropped = this.messages.slice(0, this.messages.length - keepN);
-        this.messages = keep;
-        // Ask the model to summarize what was trimmed so far, then prepend it
-        // as a system message so the model retains the conversation arc.
+        // SHELL HOOK: PreCompact — a chance to back up the transcript before the
+        // older half is summarized away. Never blocks (the trim must go ahead).
+        await runShellHooks(this.hookConfig, 'PreCompact',
+          { tokens: usedNow, messages: this.messages }, this.cfg.workspace);
+        // Tell the TUI the trim is under way. Summarizing is a full model
+        // round-trip, so without this the UI sat silent for seconds mid-turn
+        // with no sign anything was happening.
+        this.onEvent({ type: 'compacting', before: usedNow, keep: 0, dropped: 0 });
+        //
+        // ORDER: SUMMARIZE FIRST, THEN TRIM. The summary is generated from the
+        // FULL history so the summarizing model can see what just happened — the
+        // most recent exchange is what tells it what the session is doing now.
+        // Trimming first and summarizing the leftovers summarized only the OLD
+        // part and lost the information the summary needed most.
+        //
+        // The transcript fed to the summarizer is BOUNDED: the full history can
+        // itself exceed the window, in which case the call fails and the trim
+        // would drop everything with nothing to show for it. Keep the MOST RECENT
+        // messages within the budget — they carry the live state — and clip any
+        // single oversized message.
+        const SUMMARY_INPUT_CHARS = 120_000;
+        const perMsgCap = 8_000;
+        const summaryParts = [];
+        let summaryChars = 0;
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+          const m = this.messages[i];
+          const raw = typeof m.content === 'string' ? m.content : JSON.stringify(m.content || '');
+          const clipped = raw.length > perMsgCap ? raw.slice(0, perMsgCap) + '\n…[clipped]' : raw;
+          const line = `${m.role}: ${clipped}`;
+          if (summaryChars + line.length > SUMMARY_INPUT_CHARS) break;
+          summaryChars += line.length;
+          summaryParts.unshift(line);
+        }
         let summary = '';
-        if (dropped.length > 0) {
+        if (this.messages.length > 0) {
           const summaryPrompt = [
             { role: 'system', content: 'Summarize the conversation history that follows. Capture the user\'s goals, the key decisions made, files created/modified, and the current state of any ongoing work. Be concise but thorough.' },
-            ...dropped,
+            { role: 'user', content: summaryParts.join('\n\n') },
           ];
           const cfgCopy = { ...this.cfg, maxOutputTokens: Math.min(this.cfg.maxOutputTokens || 4096, 2048) };
           const llm = new LLM(cfgCopy);
           try { summary = await llm.requestText(summaryPrompt); } catch { summary = ''; }
-          if (summary) {
-            this.messages = [{
-              role: 'system',
-              content: `[hncode] Earlier conversation context was auto-compacted to stay within the context window. Summary of what was trimmed:\n\n${summary}`,
-            }, ...this.messages];
-          }
         }
+        // NOW trim. Keep under a TOKEN budget, not a message count: sizes vary by
+        // orders of magnitude (one Read result can dwarf fifty short turns), so a
+        // fixed 20%-of-messages slice could still leave the request above the
+        // threshold or throw away far more than needed. Walk backwards until the
+        // retained tail reaches ~30% of the window; always keep at least the last
+        // two so the newest exchange survives.
+        const keepBudget = Math.max(1, Math.floor(maxCtx * 0.3));
+        let keepFrom = this.messages.length;
+        let keptTokens = 0;
+        while (keepFrom > 0) {
+          const n = this.messages.length - keepFrom;   // already-kept count
+          if (n >= 2 && keptTokens >= keepBudget) break;
+          const cand = this.messages[keepFrom - 1];
+          const t = estimateMessagesTokens([cand], this.cfg) - estimateMessagesTokens([], this.cfg);
+          // Always take at least the last two messages, however big they are.
+          if (n >= 2 && keptTokens + t > keepBudget) break;
+          keptTokens += t;
+          keepFrom--;
+        }
+        // BOUNDARY FIX: never let the kept slice START on a `tool` message whose
+        // assistant(toolCalls) was dropped — most APIs reject a tool result with
+        // no preceding call. Pull the boundary back over any leading tool rows.
+        while (keepFrom > 0 && keepFrom < this.messages.length && this.messages[keepFrom].role === 'tool') {
+          keepFrom--;
+        }
+        const keep = this.messages.slice(keepFrom);
+        const droppedCount = keepFrom;
+        // Final shape: SUMMARY + the most recent messages.
+        // ALWAYS prepend a marker, even when summarization failed. Silently
+        // dropping history left the model (and the user) with no idea that context
+        // was lost; a one-line note makes the gap explicit.
+        this.messages = [{
+          role: 'system',
+          content: summary
+            ? `[hncode] Earlier conversation context was auto-compacted to stay within the context window. Summary of the conversation so far:\n\n${summary}`
+            : `[hncode] ${droppedCount} earlier message(s) were dropped to stay within the context window, and no summary could be generated. Their detail is no longer available.`,
+        }, ...keep];
         usedNow = estimateMessagesTokens(this.messages, this.cfg);
-        this.onEvent({ type: 'compacted', before, after: usedNow, kept: keepN });
+        this.onEvent({ type: 'compacted', before, after: usedNow, kept: keep.length });
       }
       // Live context gauge: report the estimated size of the request about to be
       // sent, so the TUI's context readout is refreshed at every step rather than
@@ -311,18 +404,8 @@ export class Agent {
         for (const msg of steers) this.messages.push({ role: 'user', content: msg });
         continue;
       } else if (!hasText) {
-        if (nudges < MAX_NUDGES) {
-          nudges++;
-          const why = thought.trim()
-            ? 'your last output was reasoning/thinking only, with no answer text'
-            : 'your final message was empty';
-          this.onEvent({ type: 'nudge', reason: why, attempt: nudges, max: MAX_NUDGES });
-          const last = this.messages[this.messages.length - 1];
-          const body = nudgeMessage(why);
-          if (last && last.role === 'user' && typeof last.content === 'string') last.content += '\n\n' + body;
-          else this.messages.push({ role: 'user', content: body });
-          continue;
-        }
+        // No tool calls and no answer text: the model stopped without saying
+        // anything. End the turn.
         break;
       } else {
         // The model produced its answer. A steer typed WHILE that answer was
@@ -389,6 +472,21 @@ export class Agent {
           result = `Error: unknown tool "${tc.name}".`;
           allOk = false;
         } else {
+          // SHELL HOOK: PreToolUse. A non-zero exit blocks the tool, and its
+          // message goes back to the model in place of the tool result — that is
+          // the whole point of a pre-hook (e.g. refuse a write that fails a lint
+          // gate). Checked BEFORE approving/executing so a blocked call never
+          // touches the filesystem.
+          const pre = await runShellHooks(this.hookConfig, 'PreToolUse',
+            { toolName: tc.name, toolArgs: tc.args }, this.ctx.cwd || this.cfg.workspace);
+          if (pre.blocked) {
+            result = `Blocked by a PreToolUse hook: ${pre.reason}`;
+            this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
+            this.messages.push({ role: 'tool', toolCallId: tc.id, content: result });
+            this.onEvent({ type: 'tool_result', id: tc.id, name: tc.name, content: result });
+            allOk = false;
+            continue;
+          }
           if (this.onToolStart) this.onToolStart(tc.name, tc.args);
           this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
           // Plugin hook: onToolExecute fires BEFORE the tool runs and receives the
@@ -404,6 +502,10 @@ export class Agent {
           this.ctx.lastResult = result;
           // Plugin hook: onToolResult fires with the tool's output.
           await runHooks('onToolResult', tc.name, result, this.ctx);
+          // SHELL HOOK: PostToolUse. Never blocks (the tool already ran); a
+          // failure is logged. This is where "format after every edit" lives.
+          await runShellHooks(this.hookConfig, 'PostToolUse',
+            { toolName: tc.name, toolArgs: tc.args, toolResult: result }, this.ctx.cwd || this.cfg.workspace);
           // Surface the live TODO list so the TUI can render its panel.
           if (tc.name === 'TodoList') {
             this.onEvent({ type: 'todos', todos: this.ctx.todoState || [] });
@@ -441,7 +543,6 @@ export class Agent {
       this.onEvent({
         type: 'incomplete',
         reason: 'the step budget was exhausted while tools were still being called',
-        usedNudges: nudges,
       });
     }
     if (!emittedEnd && this.onEvent) this.onEvent({ type: 'done' });
@@ -453,5 +554,9 @@ export class Agent {
     // Plugin lifecycle: the turn is over (normally, interrupted, or out of steps).
     // In a finally-equivalent position — every exit path above reaches here.
     await runHooks('onTurnEnd', { messages: this.messages, stopped: this.stopRequested });
+    // SHELL HOOK: Stop fires when the turn ends, whether it finished or was
+    // interrupted. Never blocks.
+    await runShellHooks(this.hookConfig, 'Stop',
+      { messages: this.messages, stopped: this.stopRequested, prompt: this._turnPrompt }, this.cfg.workspace);
   }
 }

package/src/cache.js

@@ -0,0 +1,130 @@
+// Prompt caching — explicit cache breakpoints for long, stable prefixes.
+//
+// Why this is worth doing: an agent resends the whole conversation every turn,
+// and the prefix (system prompt + tool definitions + early messages) is
+// byte-identical across turns. Providers that support prompt caching bill those
+// tokens at a fraction of the input price and skip the prefill compute. Without
+// explicit breakpoints only the providers that cache automatically benefit.
+//
+// Protocol differences:
+//   * anthropic — explicit: mark up to N breakpoints with
+//     `cache_control: { type: "ephemeral" }`. Anthropic caches everything UP TO
+//     and INCLUDING a marked block, so the LAST breakpoint should sit at the end
+//     of the stable prefix. The minimum cacheable prefix is model-dependent
+//     (~1024 tokens); marking a shorter prefix is a no-op, not an error.
+//   * openai — automatic for prompts over ~1024 tokens on supporting models. A
+//     stable `prompt_cache_key` improves routing; keys must not vary per request.
+//   * everything else — no-op. Unknown providers are left untouched: sending an
+//     unsupported `cache_control` field can 400 some gateways.
+//
+// The cache is only useful when the prefix is STABLE, so the helpers here take
+// care to mark the same positions every turn for the same conversation.
+
+import { estimateTokens } from './term.js';
+
+// Anthropic allows at most 4 cache breakpoints per request.
+export const MAX_BREAKPOINTS = 4;
+// Below this, a breakpoint is pointless: most providers will not cache a prefix
+// this short, and the marker is wasted budget.
+export const MIN_CACHEABLE_TOKENS = 1024;
+
+export function supportsCaching(protocol) {
+  return protocol === 'anthropic' || protocol === 'openai';
+}
+
+// Index (into `messages`) of the last message that belongs to the STABLE prefix.
+//
+// The prefix is only cacheable while it cannot change between turns. The system
+// prompt and tool list are fixed for a session; the conversation then grows by
+// APPENDING. So the prefix is "everything except the recent tail", and the tail
+// must be excluded because it is what changes next turn.
+//
+// We keep the last `keepTail` messages out of the cached region: a tool result
+// appended this turn is not part of the stable prefix next turn until it is
+// itself superseded. Returns -1 when there is nothing worth marking.
+export function stablePrefixEnd(messages, keepTail = 2) {
+  const n = Array.isArray(messages) ? messages.length : 0;
+  if (n === 0) return -1;
+  // Never mark the very last message: it is the newest content and is the most
+  // likely to be replaced/regenerated.
+  const end = Math.min(n - 1, n - 1 - Math.max(1, keepTail));
+  return end >= 0 ? end : -1;
+}
+
+// Attach Anthropic `cache_control` breakpoints to a request body IN PLACE-safe
+// fashion (returns a new body). Breakpoints are placed:
+//   1. on the LAST tool definition (caches the whole tool block),
+//   2. on the system prompt (caches tools + system together),
+//   3. on the last message of the stable prefix (caches the conversation head).
+// Marking the tail first and working backwards keeps the total <= MAX_BREAKPOINTS.
+export function withAnthropicCache(body, opts = {}) {
+  if (!body || typeof body !== 'object') return body;
+  const minTokens = opts.minTokens || MIN_CACHEABLE_TOKENS;
+  const out = { ...body };
+  const marker = { type: 'ephemeral' };
+
+  // Tools: marking the last one caches the entire tools array.
+  if (Array.isArray(out.tools) && out.tools.length) {
+    const tools = out.tools.slice();
+    tools[tools.length - 1] = { ...tools[tools.length - 1], cache_control: marker };
+    out.tools = tools;
+  }
+
+  // System: a plain string must become a text block to carry cache_control.
+  if (typeof out.system === 'string' && out.system.trim()) {
+    out.system = [{ type: 'text', text: out.system, cache_control: marker }];
+  } else if (Array.isArray(out.system) && out.system.length) {
+    const sys = out.system.slice();
+    const last = sys.length - 1;
+    sys[last] = { ...(typeof sys[last] === 'string' ? { type: 'text', text: sys[last] } : sys[last]), cache_control: marker };
+    out.system = sys;
+  }
+
+  // Conversation head: mark the stable prefix's last message.
+  if (Array.isArray(out.messages) && out.messages.length) {
+    const end = stablePrefixEnd(out.messages, opts.keepTail);
+    if (end >= 0 && end < out.messages.length) {
+      // Only worth a breakpoint once the prefix is long enough to cache.
+      const prefixText = out.messages.slice(0, end + 1)
+        .map((m) => (typeof m.content === 'string' ? m.content
+          : Array.isArray(m.content) ? m.content.map((b) => b.text || '').join('') : ''))
+        .join('\n');
+      if (estimateTokens(prefixText) >= minTokens) {
+        const msgs = out.messages.slice();
+        const msg = { ...msgs[end] };
+        if (typeof msg.content === 'string') {
+          msg.content = [{ type: 'text', text: msg.content }];
+        }
+        if (Array.isArray(msg.content) && msg.content.length) {
+          const c = msg.content.slice();
+          const li = c.length - 1;
+          c[li] = { ...c[li], cache_control: marker };
+          msg.content = c;
+        }
+        msgs[end] = msg;
+        out.messages = msgs;
+      }
+    }
+  }
+  return out;
+}
+
+// OpenAI-compatible: most providers cache automatically. A STABLE
+// `prompt_cache_key` helps routing on the providers that accept it, and must not
+// change between turns of the same conversation or the cache thrashes.
+// `seed` should therefore identify the SESSION, not the request.
+export function withOpenAiCache(body, opts = {}) {
+  if (!body || typeof body !== 'object') return body;
+  const key = opts.sessionKey;
+  if (!key) return body;
+  return { ...body, prompt_cache_key: String(key) };
+}
+
+// Apply the right caching strategy for `protocol`. Returns the body unchanged
+// for protocols with no explicit support.
+export function applyPromptCache(protocol, body, opts = {}) {
+  if (!opts.enabled) return body;
+  if (protocol === 'anthropic') return withAnthropicCache(body, opts);
+  if (protocol === 'openai') return withOpenAiCache(body, opts);
+  return body;
+}