@axplusb/kepler 2.0.7 → 2.3.0

package/src/config/memory-loader.mjs

@@ -0,0 +1,32 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+function readIfExists(filePath, maxChars = 12000) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return {
+      path: filePath,
+      content: content.length > maxChars
+        ? content.slice(0, maxChars) + '\n\n[...truncated...]'
+        : content,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function loadKeplerMemory({ cwd = process.cwd() } = {}) {
+  const files = [];
+  const global = readIfExists(path.join(os.homedir(), '.kepler', 'KEPLER.md'));
+  if (global) files.push({ source: 'global', ...global });
+
+  const topLevel = readIfExists(path.join(cwd, 'KEPLER.md'));
+  if (topLevel) files.push({ source: 'project-top-level', ...topLevel });
+
+  const project = readIfExists(path.join(cwd, '.kepler', 'KEPLER.md'));
+  if (project) files.push({ source: 'project', ...project });
+
+  return files;
+}

package/src/config/settings-loader.mjs

@@ -0,0 +1,45 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { deepMerge } from '../core/policy-resolver.mjs';
+
+export const DEFAULT_KEPLER_SETTINGS = Object.freeze({
+  env: {},
+  permissions: {
+    shellAllowlist: [],
+    editDenylist: [],
+  },
+  hooks: {
+    UserPromptSubmit: [],
+    PreToolUse: [],
+    PostToolUse: [],
+    Stop: [],
+  },
+});
+
+function readJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    return { __error: err.message };
+  }
+}
+
+export function loadKeplerSettings({ cwd = process.cwd() } = {}) {
+  const base = path.join(cwd, '.kepler');
+  const layers = [
+    { name: 'default', path: null, data: DEFAULT_KEPLER_SETTINGS },
+  ];
+  for (const [name, file] of [
+    ['project', path.join(base, 'settings.json')],
+    ['local', path.join(base, 'settings.local.json')],
+  ]) {
+    const data = readJson(file);
+    if (data && !data.__error) layers.push({ name, path: file, data });
+    else if (data?.__error) layers.push({ name, path: file, error: data.__error, data: {} });
+  }
+
+  let settings = {};
+  for (const layer of layers) settings = deepMerge(settings, layer.data || {});
+  return { settings, layers };
+}

package/src/core/agent-loop.mjs

@@ -6,6 +6,7 @@ import { streamResponse, accumulateStream } from './streaming.mjs';
 import { ContextManager } from './context-manager.mjs';
 import { buildSystemPrompt } from './system-prompt.mjs';
 import { createStagnationTracker, stagnationMessage } from './stagnation.mjs';
+import { PromptCache } from './cache.mjs';
 import fs from 'fs';
 import path from 'path';
 export function createAgentLoop({ model, tools, permissions, settings, hooks }) {
@@ -23,10 +24,11 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks })
         messages: [],
         systemPrompt: promptResult.full,
         turnCount: 0,
-        tokenUsage: { input: 0, output: 0 },
+        tokenUsage: { input: 0, output: 0, cache_read: 0, cache_creation: 0 },
         model,
         tools,
         _contextManager: contextManager,
+        _promptCache: new PromptCache(),
     };
     const stagnation = createStagnationTracker({
         enabled: settings.stagnationDetection === true,
@@ -99,10 +101,14 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks })
             return;
         }
 
-        // Track token usage
+        // Track token usage (PRD-071 §1.1: also record cache hits/writes so
+        // /extra-usage and /status stop reporting zeros)
         if (response.usage) {
             state.tokenUsage.input += response.usage.input_tokens || 0;
             state.tokenUsage.output += response.usage.output_tokens || 0;
+            state.tokenUsage.cache_read += response.usage.cache_read_input_tokens || 0;
+            state.tokenUsage.cache_creation += response.usage.cache_creation_input_tokens || 0;
+            state._promptCache.updateStats(response.usage);
         }
 
         // Build assistant message for history

package/src/core/approval-log.mjs

@@ -0,0 +1,104 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const REDACTED = 'REDACTED';
+const SENSITIVE_KEY_RE = /^(?:authorization|api[-_]?key|apikey|key|token|access[-_]?token|refresh[-_]?token|secret|password|passwd|pwd|access[-_]?key|secret[-_]?access[-_]?key)$|(?:^|[-_])(?:api[-_]?key|apikey|token|secret|password|passwd|pwd|access[-_]?key|secret[-_]?access[-_]?key)(?:$|[-_])/i;
+const SENSITIVE_ASSIGNMENT_KEY = String.raw`[A-Z0-9_-]*(?:API[-_]?KEY|APIKEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD|ACCESS[-_]?KEY|SECRET[-_]?ACCESS[-_]?KEY)[A-Z0-9_-]*`;
+const SENSITIVE_JSON_KEY = String.raw`(?:authorization|api[-_]?key|apikey|key|token|access[-_]?token|refresh[-_]?token|secret|password|passwd|pwd|access[-_]?key|secret[-_]?access[-_]?key|[A-Z0-9_-]*(?:API[-_]?KEY|APIKEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD|ACCESS[-_]?KEY|SECRET[-_]?ACCESS[-_]?KEY)[A-Z0-9_-]*)`;
+
+export function redactSensitive(str) {
+  let s = String(str ?? '');
+
+  // Authorization headers in shell commands, curl args, and copied HTTP snippets.
+  s = s.replace(/(Authorization\s*:\s*(?:Bearer|Basic)\s+)(?:"[^"]*"|'[^']*'|[^\s"',;]+)/gi, `$1${REDACTED}`);
+
+  // Secret-bearing query/form parameters.
+  s = s.replace(/([?&](?:api_key|apikey|api-key|key|token|access_token|refresh_token|password|secret)=)([^&\s"']+)/gi, `$1${REDACTED}`);
+
+  // Env-style assignments, including quoted values.
+  s = s.replace(
+    new RegExp(`(^|[\\s;,])(${SENSITIVE_ASSIGNMENT_KEY}\\s*=\\s*)(?:"[^"]*"|'[^']*'|[^\\s"',;]+)`, 'gi'),
+    (_match, prefix, key) => `${prefix}${key}${REDACTED}`
+  );
+
+  // JSON fragments that arrive as strings rather than structured objects.
+  s = s.replace(
+    new RegExp(`("(?:${SENSITIVE_JSON_KEY})"\\s*:\\s*)(?:"(?:\\\\.|[^"\\\\])*"|[^,}\\s]+)`, 'gi'),
+    `$1"${REDACTED}"`
+  );
+
+  return s;
+}
+
+function isSensitiveKey(key) {
+  return SENSITIVE_KEY_RE.test(String(key || ''));
+}
+
+function sanitizeForLog(value, depth = 0) {
+  if (depth > 12) return '[MaxDepth]';
+  if (typeof value === 'string') return redactSensitive(value);
+  if (value == null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.slice(0, 100).map(item => sanitizeForLog(item, depth + 1));
+
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    out[key] = isSensitiveKey(key) ? REDACTED : sanitizeForLog(item, depth + 1);
+  }
+  return out;
+}
+
+function safeArgs(args) {
+  if (args?.command) return redactSensitive(String(args.command)).slice(0, 500);
+  if (args?.file_path || args?.path) return redactSensitive(String(args.file_path || args.path)).slice(0, 500);
+  try { return JSON.stringify(sanitizeForLog(args || {})).slice(0, 500); }
+  catch { return redactSensitive(String(args || '')).slice(0, 500); }
+}
+
+function safeText(value, max = 500) {
+  if (!value) return undefined;
+  return redactSensitive(String(value)).slice(0, max);
+}
+
+export class ApprovalLog {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+    this.filePath = path.join(cwd, '.kepler', 'approvals.log');
+  }
+
+  append(entry) {
+    try {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+      const line = JSON.stringify({
+        ts: new Date().toISOString(),
+        tier: entry.tier,
+        tool: entry.tool,
+        args: safeArgs(entry.args),
+        decision: entry.decision,
+        scope: entry.scope || 'once',
+        rule_id: entry.rule_id || null,
+        reason: safeText(entry.reason),
+      });
+      fs.appendFileSync(this.filePath, line + '\n', { mode: 0o600 });
+      try { fs.chmodSync(this.filePath, 0o600); } catch {}
+    } catch { /* approval logging must not block execution */ }
+  }
+
+  readRecent(limit = 20) {
+    try {
+      if (!fs.existsSync(this.filePath)) return [];
+      return fs.readFileSync(this.filePath, 'utf-8')
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .slice(-limit)
+        .map(line => {
+          try { return JSON.parse(line); }
+          catch { return null; }
+        })
+        .filter(Boolean)
+        .reverse();
+    } catch {
+      return [];
+    }
+  }
+}

package/src/core/approval.mjs

@@ -20,9 +20,12 @@ import {
 } from './risk-tier.mjs';
 import {
   renderApprovalPrompt,
-  renderInlinePrompt,
+  renderTrustedApproval,
   defaultOptions as approvalOptions,
 } from '../ui/approval.mjs';
+import { ApprovalLog } from './approval-log.mjs';
+import { TrustStore } from './trust.mjs';
+import { loadEffectivePolicy } from './policy-resolver.mjs';
 
 // ── Tool Classification ──
 //
@@ -36,6 +39,8 @@ const WRITE_TOOLS = new Set([
 
 function defaultWhy(tier, tool, args) {
     switch (tier) {
+        case TIERS.SENSITIVE_READ:
+            return `Reads a sensitive path (${toolDisplaySummary(tool, args) || 'secret-like file'}). Confirm before exposing its contents to the agent.`;
         case TIERS.SHELL_DANGEROUS:
             return `Shell command matches a high-risk pattern (rm -rf, sudo, force push, etc.). Confirm before running.`;
         case TIERS.DESTRUCTIVE:
@@ -66,12 +71,17 @@ const write = (s) => process.stderr.write(s);
 // ── Approval Manager ──
 
 export class ApprovalManager {
-    constructor({ autoApprove = false, planMode = false } = {}) {
+    constructor({ autoApprove = false, planMode = false, cwd = process.cwd(), policy = null, trustStore = null, approvalLog = null } = {}) {
         this.autoApprove = autoApprove;
         this.planMode = planMode;
+        this.cwd = cwd;
+        this.policy = policy || loadEffectivePolicy({ cwd }).policy;
+        this.trustStore = trustStore || new TrustStore({ cwd, policy: this.policy });
+        this.approvalLog = approvalLog || new ApprovalLog({ cwd });
         this.approveAll = false;
         this.approvedToolTypes = new Set();
         this.history = [];
+        this.rejectionHints = [];
         this._rl = null;
     }
 
@@ -86,7 +96,8 @@ export class ApprovalManager {
         const wasActive = this.approveAll || this.approvedToolTypes.size > 0;
         this.approveAll = false;
         this.approvedToolTypes.clear();
-        return wasActive;
+        const trustActive = this.trustStore?.revoke?.() || false;
+        return wasActive || trustActive;
     }
 
     getModeLabel() {
@@ -122,14 +133,32 @@ export class ApprovalManager {
             return { approved: true, tier, requireCheckpoint: true };
         }
 
+        const trust = this.trustStore?.find?.(toolName, args, tier);
+        if (trust?.decision === 'deny') {
+            this.history.push({ tool: toolName, decision: 'trusted-deny', tier, time: Date.now(), rule_id: trust.rule?.id });
+            this.approvalLog.append({ tool: toolName, args, tier, decision: 'deny_trusted', scope: trust.rule?.scope, rule_id: trust.rule?.id });
+            return { approved: false, tier, reason: `Denied by trust rule ${trust.rule?.id || ''}`.trim() };
+        }
+        if (trust?.decision === 'allow') {
+            this.history.push({ tool: toolName, decision: 'auto_trusted', tier, time: Date.now(), rule_id: trust.rule?.id });
+            this.approvalLog.append({ tool: toolName, args, tier, decision: 'auto_trusted', scope: trust.rule?.scope, rule_id: trust.rule?.id });
+            write(renderTrustedApproval({ tool: toolName, args, scope: trust.rule?.scope, ruleId: trust.rule?.id }));
+            return { approved: true, tier, scope: trust.rule?.scope, rule_id: trust.rule?.id };
+        }
+        if (trust?.decision === 'reask' && trust.reason) {
+            context.reason = context.reason || context.why || `Re-asking: ${trust.reason}`;
+        }
+
         // Honor approve-all / type-allow shortcuts for non-explicit tiers only.
         if (!requiresExplicitApproval(tier)) {
             if (this.approveAll) {
                 this.history.push({ tool: toolName, decision: 'auto-all', tier, time: Date.now() });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'auto-all', scope: 'session' });
                 return { approved: true, tier };
             }
             if (this.approvedToolTypes.has(toolName)) {
                 this.history.push({ tool: toolName, decision: 'type-auto', tier, time: Date.now() });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'type-auto', scope: 'session' });
                 return { approved: true, tier };
             }
         }
@@ -139,10 +168,9 @@ export class ApprovalManager {
 
     async _prompt(toolName, args, context = {}) {
         const tier = context.tier || classifyTier(toolName, args);
-        const explicit = requiresExplicitApproval(tier);
         const why = context.reason || context.why || defaultWhy(tier, toolName, args);
         const summary = toolDisplaySummary(toolName, args);
-        const options = approvalOptions(tier);
+        const options = this._optionsFor(tier);
 
         let selected = 0; // arrow-driven cursor
         let printedHeight = 0;
@@ -151,12 +179,10 @@ export class ApprovalManager {
         // live. For non-TTYs / pipes we just print once and read a line.
         const isInteractive = process.stdin.isTTY;
         if (!isInteractive) {
-            write(explicit
-                ? renderApprovalPrompt({ tool: toolName, args, tier, why, selected, options }) + '\n'
-                : renderInlinePrompt({ tool: toolName, args, tier, why }) + '\n');
+            write(renderApprovalPrompt({ tool: toolName, args, tier, why, selected, options }) + '\n');
         }
 
-        const drawExplicit = () => {
+        const drawPrompt = () => {
             // Move up over the previous render before re-printing.
             if (printedHeight > 0) {
                 write(`\x1b[${printedHeight}F`); // cursor to start of N lines above
@@ -167,8 +193,7 @@ export class ApprovalManager {
             printedHeight = block.split('\n').length;
         };
 
-        if (isInteractive && explicit) drawExplicit();
-        if (isInteractive && !explicit) write(renderInlinePrompt({ tool: toolName, args, tier, why }) + '\n');
+        if (isInteractive) drawPrompt();
 
         // ── Input loop ─────────────────────────────────────────────────
         const choose = async () => {
@@ -176,15 +201,15 @@ export class ApprovalManager {
                 const k = await this._readKey();
 
                 if (k === 'up' || k === 'left') {
-                    if (!explicit || !isInteractive) continue;
+                    if (!isInteractive) continue;
                     selected = (selected - 1 + options.length) % options.length;
-                    drawExplicit();
+                    drawPrompt();
                     continue;
                 }
                 if (k === 'down' || k === 'right' || k === 'tab') {
-                    if (!explicit || !isInteractive) continue;
+                    if (!isInteractive) continue;
                     selected = (selected + 1) % options.length;
-                    drawExplicit();
+                    drawPrompt();
                     continue;
                 }
                 if (k === 'return') {
@@ -198,7 +223,7 @@ export class ApprovalManager {
                     const idx = options.findIndex(o => o.key === lower);
                     if (idx >= 0) {
                         selected = idx;
-                        if (isInteractive && explicit) drawExplicit();
+                        if (isInteractive) drawPrompt();
                         return options[idx].value;
                     }
                 }
@@ -212,25 +237,51 @@ export class ApprovalManager {
             case 'approve':
                 write(`  ${GREEN}✓${RST}  ${DIM}${toolName}${RST} ${DIM}${summary.slice(0, 60)}${RST}\n\n`);
                 this.history.push({ tool: toolName, decision: 'yes', tier, time: Date.now() });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'approve', scope: 'once' });
                 return { approved: true, tier };
 
+            case 'allow-session': {
+                if (!this.policy.hitl?.allowSessionTrust) return this._prompt(toolName, args, context);
+                const rule = this.trustStore.add({ tool: toolName, args, tier, scope: 'SESSION' });
+                write(`  ${GREEN}✓${RST}  ${DIM}trusted for this session: ${rule.pattern}${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'session-trust', tier, time: Date.now(), rule_id: rule.id });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'approve_trusted', scope: 'SESSION', rule_id: rule.id });
+                return { approved: true, tier, scope: 'SESSION', rule_id: rule.id };
+            }
+
+            case 'allow-project': {
+                if (!this.policy.hitl?.allowProjectTrust) return this._prompt(toolName, args, context);
+                const rule = this.trustStore.add({ tool: toolName, args, tier, scope: 'PROJECT' });
+                write(`  ${GREEN}✓${RST}  ${DIM}trusted for this project: ${rule.pattern}${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'project-trust', tier, time: Date.now(), rule_id: rule.id });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'approve_trusted', scope: 'PROJECT', rule_id: rule.id });
+                return { approved: true, tier, scope: 'PROJECT', rule_id: rule.id };
+            }
+
             case 'reject':
-                write(`  ${RED}✗${RST}  ${DIM}denied${RST}\n\n`);
-                this.history.push({ tool: toolName, decision: 'no', tier, time: Date.now() });
-                return { approved: false, tier, reason: 'User denied' };
+            {
+                const reason = 'User stopped the command';
+                write(`  ${RED}✗${RST}  ${DIM}stopped${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'no', tier, time: Date.now(), reason });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'reject', scope: 'once', reason });
+                this._rememberRejection({ tool: toolName, args, tier, decision: 'reject', reason, note: '' });
+                return { approved: false, tier, reason };
+            }
 
             case 'allow-all':
-                if (explicit) return this._prompt(toolName, args, context);
+                if (requiresExplicitApproval(tier)) return this._prompt(toolName, args, context);
                 this.approveAll = true;
                 write(`  ${GREEN}✓✓${RST} ${DIM}allow-all activated${RST}\n\n`);
                 this.history.push({ tool: toolName, decision: 'approve-all', tier, time: Date.now() });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'approve-all', scope: 'session' });
                 return { approved: true, tier };
 
             case 'allow-type':
-                if (explicit) return this._prompt(toolName, args, context);
+                if (requiresExplicitApproval(tier)) return this._prompt(toolName, args, context);
                 this.approvedToolTypes.add(toolName);
                 write(`  ${GREEN}✓${RST}  ${DIM}always allow ${toolName}${RST}\n\n`);
                 this.history.push({ tool: toolName, decision: 'type-approve', tier, time: Date.now() });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'type-approve', scope: 'session' });
                 return { approved: true, tier };
 
             case 'why':
@@ -240,9 +291,15 @@ export class ApprovalManager {
 
             case 'edit':
             case 'replan':
-                write(`  ${YELLOW}↩${RST}  ${DIM}reject with hint — rework the plan${RST}\n\n`);
-                this.history.push({ tool: toolName, decision: 'replan', tier, time: Date.now() });
-                return { approved: false, tier, reason: 'User asked to re-plan' };
+            {
+                const note = await this._readLinePrompt(`  ${DIM}How would you like to proceed? ${RST}`);
+                const reason = note ? `User asked to re-plan: ${note}` : 'User asked to re-plan';
+                write(`  ${YELLOW}↩${RST}  ${DIM}${note ? `re-plan — ${truncateNote(note)}` : 'reject with hint — rework the plan'}${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'replan', tier, time: Date.now(), reason });
+                this.approvalLog.append({ tool: toolName, args, tier, decision: 'replan', scope: 'once', reason });
+                this._rememberRejection({ tool: toolName, args, tier, decision: 'replan', reason, note });
+                return { approved: false, tier, reason };
+            }
 
             default:
                 return this._prompt(toolName, args, context);
@@ -287,6 +344,70 @@ export class ApprovalManager {
         });
     }
 
+    _readLinePrompt(label) {
+        return new Promise((resolve) => {
+            if (!process.stdin.isTTY) {
+                resolve('');
+                return;
+            }
+
+            if (this._execPause) this._execPause();
+            if (this._rl) this._rl.pause();
+
+            const wasRaw = process.stdin.isRaw;
+            if (typeof process.stdin.setRawMode === 'function') {
+                process.stdin.setRawMode(false);
+            }
+            process.stdin.resume();
+            write(label);
+
+            let buffer = '';
+            const cleanup = () => {
+                process.stdin.off('data', onData);
+                if (typeof process.stdin.setRawMode === 'function') {
+                    process.stdin.setRawMode(wasRaw || false);
+                }
+                if (this._rl) this._rl.resume();
+                if (this._execResume) this._execResume();
+            };
+            const finish = () => {
+                cleanup();
+                resolve(buffer.trim());
+            };
+            const onData = (data) => {
+                const str = data.toString();
+                if (data[0] === 0x03) process.exit(0);
+                if (data[0] === 0x1b) {
+                    buffer = '';
+                    write('\n');
+                    finish();
+                    return;
+                }
+                if (str.includes('\n') || str.includes('\r')) {
+                    buffer += str.replace(/[\r\n].*$/s, '');
+                    finish();
+                    return;
+                }
+                buffer += str;
+            };
+
+            process.stdin.on('data', onData);
+        });
+    }
+
+    _optionsFor(tier) {
+        const options = approvalOptions(tier);
+        if (requiresExplicitApproval(tier)) {
+            if (this.policy.hitl?.allowSessionTrust) {
+                options.splice(1, 0, { key: 's', label: 'session', value: 'allow-session', hint: 'trust this pattern until expiry' });
+            }
+            if (this.policy.hitl?.allowProjectTrust) {
+                options.splice(1, 0, { key: 'a', label: 'project', value: 'allow-project', hint: 'trust this pattern in this repo' });
+            }
+        }
+        return options;
+    }
+
     getSummary() {
         const approved = this.history.filter(h => h.decision !== 'no').length;
         const denied = this.history.filter(h => h.decision === 'no').length;
@@ -296,6 +417,25 @@ export class ApprovalManager {
             denied,
             autoApproveAll: this.approveAll,
             autoApprovedTypes: [...this.approvedToolTypes],
+            trust: this.trustStore?.summary?.() || { sessionRules: 0, projectRules: 0 },
         };
     }
+
+    _rememberRejection(entry) {
+        this.rejectionHints.push({ ...entry, time: Date.now() });
+        if (this.rejectionHints.length > 10) {
+            this.rejectionHints.splice(0, this.rejectionHints.length - 10);
+        }
+    }
+
+    consumeRejectionHints() {
+        const hints = [...this.rejectionHints];
+        this.rejectionHints = [];
+        return hints;
+    }
+}
+
+function truncateNote(note) {
+    const text = String(note || '').trim();
+    return text.length <= 120 ? text : text.slice(0, 119) + '…';
 }

package/src/core/cache-control.mjs

@@ -0,0 +1,92 @@
+/**
+ * cache_control breakpoints for Anthropic prompt caching (PRD-071 Phase 2).
+ *
+ * Shared by every direct-API call site that talks to Anthropic — LocalAgent
+ * (Anthropic direct + OpenRouter passthrough) and agent-loop's Task sub-agents.
+ *
+ * Anthropic allows 4 breakpoints per request; we spend 3:
+ *   1) End of system prompt        (1h TTL — persistent across long-idle sessions)
+ *   2) Last tool schema            (1h TTL — persistent)
+ *   3) Second-to-last user message (5min TTL — rolls each turn, cheaper to write)
+ *
+ * The 4th slot stays reserved (attachments, future retrieval prefix).
+ *
+ * Extended 1-hour TTL is a beta — pass ANTHROPIC_BETA_HEADER on the request
+ * whenever any block carries ttl:'1h'.
+ */
+
+export const ANTHROPIC_BETA_HEADER = 'extended-cache-ttl-2025-04-11';
+
+const CACHE_1H = { type: 'ephemeral', ttl: '1h' };
+const CACHE_5M = { type: 'ephemeral' };
+
+/**
+ * Turn a `system` string into a content-block array with a cache_control
+ * breakpoint on the tail. If the caller already passed blocks, returns them
+ * unchanged. Undefined / non-string inputs pass through as-is.
+ */
+export function cacheableSystem(systemPrompt) {
+    if (Array.isArray(systemPrompt)) return systemPrompt;
+    if (!systemPrompt || typeof systemPrompt !== 'string') return systemPrompt;
+    return [{ type: 'text', text: systemPrompt, cache_control: CACHE_1H }];
+}
+
+/**
+ * Return a copy of `tools` with cache_control on the LAST tool. Anthropic
+ * caches system + tools as one prefix from that breakpoint, so this single
+ * marker covers the whole tool schema regardless of length.
+ */
+export function cacheableTools(tools) {
+    if (!Array.isArray(tools) || tools.length === 0) return tools || [];
+    const out = tools.slice();
+    const last = out[out.length - 1];
+    out[out.length - 1] = { ...last, cache_control: CACHE_1H };
+    return out;
+}
+
+/**
+ * Tag the SECOND-to-last user message with a 5-min cache_control breakpoint.
+ * Leaves the last turn write-through so the next round extends the cache
+ * instead of re-writing it. Returns messages unchanged when there aren't
+ * enough user turns yet (< 2).
+ *
+ * Handles both content shapes: string (wrapped into blocks) and block array
+ * (tagged on the last block).
+ */
+export function withMessageBreakpoint(messages) {
+    if (!Array.isArray(messages) || messages.length < 2) return messages;
+    const userIdx = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].role === 'user') userIdx.push(i);
+    }
+    if (userIdx.length < 2) return messages;
+    const targetIdx = userIdx[userIdx.length - 2];
+    const msg = messages[targetIdx];
+
+    if (typeof msg.content === 'string') {
+        return messages.map((m, i) => i === targetIdx ? {
+            ...m,
+            content: [{ type: 'text', text: m.content, cache_control: CACHE_5M }],
+        } : m);
+    }
+
+    if (Array.isArray(msg.content) && msg.content.length > 0) {
+        const blocks = msg.content.slice();
+        const last = blocks[blocks.length - 1];
+        blocks[blocks.length - 1] = { ...last, cache_control: CACHE_5M };
+        return messages.map((m, i) => i === targetIdx ? { ...m, content: blocks } : m);
+    }
+
+    return messages;
+}
+
+/**
+ * True if the given model id needs Anthropic-style explicit cache_control
+ * (vs OpenAI/DeepSeek which auto-cache). Handles bare Claude ids and
+ * OpenRouter's `anthropic/*` prefix.
+ */
+export function needsExplicitCacheControl(model) {
+    if (!model) return false;
+    const m = model.toLowerCase();
+    return m.startsWith('claude') || m.startsWith('anthropic/');
+}