@axplusb/kepler 2.2.0 → 2.3.0

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/');
+}

package/src/core/headless.mjs

@@ -13,6 +13,7 @@
 
 import { TarangStreamClient } from './stream-client.mjs';
 import { createToolExecutor } from './tool-executor.mjs';
+import { buildWorkScope } from './work-scope.mjs';
 import { persistProjectArtifacts } from './project-artifacts.mjs';
 import { TarangAuth } from '../auth/tarang-auth.mjs';
 import { ApprovalManager } from './approval.mjs';
@@ -26,7 +27,7 @@ import { ApprovalManager } from './approval.mjs';
  * @param {number} [opts.maxCost] - abort if cost exceeds this USD amount
  * @param {boolean} [opts.verbose] - show progress on stderr
  */
-export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false }) {
+export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false, cacheReport = null, local = false }) {
     const startTime = Date.now();
 
     const log = (msg) => {
@@ -51,13 +52,41 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     // Auto-approve everything — no prompts
     const approval = new ApprovalManager({ autoApprove: true });
 
-    // ── Stream client ──
-    const client = new TarangStreamClient({
-        baseUrl: creds.backendUrl,
-        token: creds.token,
-        toolExecutor,
-        approvalManager: approval,
-    });
+    // ── Client selection ──
+    // PRD-071 Phase 2 measurement — --local forces the CLI-side LocalAgent path,
+    // bypassing the backend so we can exercise the cache_control wiring we
+    // just added to _callClaude / _callOpenRouter. Model comes from the
+    // --model flag (which overrides settings dynamically for benchmarking).
+    let client;
+    if (local) {
+        const { LocalAgent } = await import('./local-agent.mjs');
+        const localModel = model || creds.models?.local || 'anthropic/claude-sonnet-4';
+        const orKey = process.env.OPENROUTER_API_KEY || creds.openRouterKey;
+        const anthKey = process.env.ANTHROPIC_API_KEY || creds.anthropicKey;
+        if (!orKey && !anthKey) {
+            emit({ type: 'error', error: '--local requires OPENROUTER_API_KEY or ANTHROPIC_API_KEY' });
+            process.exit(1);
+        }
+        client = {
+            execute: (instr, ctx) => new LocalAgent({
+                apiKey: anthKey,
+                openRouterKey: orKey,
+                model: localModel,
+                toolExecutor,
+                verbose,
+                cwd: process.cwd(),
+                maxTurns: 50,
+            }).execute(instr, ctx),
+        };
+        log(`Local mode: ${localModel}`);
+    } else {
+        client = new TarangStreamClient({
+            baseUrl: creds.backendUrl,
+            token: creds.token,
+            toolExecutor,
+            approvalManager: approval,
+        });
+    }
 
     // ── Timeout ──
     const timeoutMs = timeout * 1000;
@@ -70,10 +99,16 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     // ── Execute ──
     emit({ type: 'start', timestamp: Date.now(), instruction, model: model || 'default', cwd: process.cwd() });
 
+    const projectResources = toolExecutor.getProjectResources();
     const execContext = {
         cwd: process.cwd(),
         freeswim: true,
-        project_resources: toolExecutor.getProjectResources(),
+        project_resources: projectResources,
+        work_scope: buildWorkScope({
+            instruction,
+            cwd: process.cwd(),
+            projectResources,
+        }),
         agent_context: toolExecutor.getAgentContext(),
     };
     if (model) execContext.model_override = model;
@@ -219,6 +254,47 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
         content_length: finalContent.length,
     });
 
+    // PRD-071 §1.5 — cache summary for benchmark harness. Machine-readable,
+    // one file per run. Fields match what benchmark/cache-check.sh already
+    // computes (input, cache_read, cache_write, rate) so the shell script
+    // becomes a thin reader instead of re-doing the arithmetic.
+    if (cacheReport && usage) {
+        const cacheRead = usage.cache_read || 0;
+        const cacheWrite = usage.cache_write || 0;
+        const inputT = usage.input_tokens || 0;
+        // Two conventions in the wild:
+        //   OpenAI/DeepSeek: input_tokens INCLUDES cached tokens
+        //                    → hit_rate = cache_read / input_tokens
+        //   Anthropic:       input_tokens EXCLUDES cache reads AND writes
+        //                    → hit_rate = cache_read / (input + cache_read + cache_write)
+        // Report both. Also expose `cache_hit_rate_pct` as the "sane" number
+        // — auto-detects convention by whether cache_read > input_tokens.
+        const rateOpenAI = inputT > 0 ? Math.round((cacheRead / inputT) * 100) : 0;
+        const anthropicDenom = inputT + cacheRead + cacheWrite;
+        const rateAnthropic = anthropicDenom > 0 ? Math.round((cacheRead / anthropicDenom) * 100) : 0;
+        const rateAuto = cacheRead > inputT ? rateAnthropic : rateOpenAI;
+        const report = {
+            schema: 'kepler.cache-report/1',
+            model: model || 'default',
+            input_tokens: inputT,
+            output_tokens: usage.output_tokens || 0,
+            cache_read_tokens: cacheRead,
+            cache_write_tokens: cacheWrite,
+            cache_hit_rate_pct: rateAuto,
+            cache_hit_rate_openai_pct: rateOpenAI,
+            cache_hit_rate_anthropic_pct: rateAnthropic,
+            duration_s: Math.round(durationS * 10) / 10,
+            cost_usd: totalCost,
+        };
+        try {
+            const fs = await import('node:fs');
+            fs.writeFileSync(cacheReport, JSON.stringify(report, null, 2) + '\n');
+            log(`Cache report written: ${cacheReport}`);
+        } catch (err) {
+            log(`Cache report write failed: ${err.message}`);
+        }
+    }
+
     log(`Done: ${toolCount} tools, ${durationS.toFixed(1)}s, $${totalCost.toFixed(3)}`);
 
     // Write final content to stderr so it's human-readable (stdout is JSONL)

package/src/core/local-agent.mjs

@@ -6,6 +6,14 @@
 
 import { ContextRetriever } from '../context/retriever.mjs';
 import { createStagnationTracker, stagnationMessage } from './stagnation.mjs';
+import { PromptCache } from './cache.mjs';
+import {
+    ANTHROPIC_BETA_HEADER,
+    cacheableSystem,
+    cacheableTools,
+    withMessageBreakpoint,
+    needsExplicitCacheControl,
+} from './cache-control.mjs';
 
 const MAX_ITERATIONS = 50;
 
@@ -209,12 +217,14 @@ export class LocalAgent {
         this.stagnationDetection = stagnationDetection;
         this.stagnationThreshold = stagnationThreshold;
         this._cancelled = false;
+        this.promptCache = new PromptCache();
     }
 
     async *execute(instruction, context = {}) {
         this._cancelled = false;
         const startTime = Date.now();
         let toolCount = 0;
+        const usageTotals = { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 };
 
         yield { type: 'status', data: { message: `Local mode: ${this.model}` } };
 
@@ -252,7 +262,15 @@ export class LocalAgent {
                 return;
             }
 
-            const { content, stopReason } = response;
+            const { content, stopReason, usage } = response;
+
+            if (usage) {
+                this.promptCache.updateStats(usage);
+                usageTotals.input_tokens += usage.input_tokens || 0;
+                usageTotals.output_tokens += usage.output_tokens || 0;
+                usageTotals.cache_read_tokens += usage.cache_read_input_tokens || 0;
+                usageTotals.cache_creation_tokens += usage.cache_creation_input_tokens || 0;
+            }
 
             // Process content blocks
             let hasToolUse = false;
@@ -303,13 +321,29 @@ export class LocalAgent {
 
             if (!hasToolUse || stopReason === 'end_turn') {
                 const duration = (Date.now() - startTime) / 1000;
-                yield { type: 'complete', data: { summary: 'Done (local)', changes: toolCount, duration_s: duration } };
+                yield {
+                    type: 'complete',
+                    data: {
+                        summary: 'Done (local)',
+                        changes: toolCount,
+                        duration_s: duration,
+                        usage: _buildLocalUsageEnvelope(this.model, usageTotals),
+                    },
+                };
                 return;
             }
         }
 
         yield { type: 'error', data: { message: `Max turns (${this.maxTurns}) reached.` } };
-        yield { type: 'complete', data: { summary: 'Aborted (max turns)', changes: toolCount, duration_s: (Date.now() - startTime) / 1000 } };
+        yield {
+            type: 'complete',
+            data: {
+                summary: 'Aborted (max turns)',
+                changes: toolCount,
+                duration_s: (Date.now() - startTime) / 1000,
+                usage: _buildLocalUsageEnvelope(this.model, usageTotals),
+            },
+        };
     }
 
     async _callLLM(systemPrompt, messages, tools) {
@@ -333,18 +367,26 @@ export class LocalAgent {
     }
 
     async _callClaude(systemPrompt, messages, tools) {
+        // PRD-071 Phase 2 — cache_control breakpoints for Anthropic direct.
+        // Extended 1-hour TTL beta on the persistent prefix (system + tools).
+        // Message history breakpoint stays at default 5-min TTL.
+        const cachedSystem = cacheableSystem(systemPrompt);
+        const cachedTools = cacheableTools(tools);
+        const cachedMessages = withMessageBreakpoint(messages);
+
         const resp = await fetch('https://api.anthropic.com/v1/messages', {
             method: 'POST',
             headers: {
                 'x-api-key': this.apiKey,
                 'anthropic-version': '2023-06-01',
+                'anthropic-beta': ANTHROPIC_BETA_HEADER,
                 'content-type': 'application/json',
             },
             body: JSON.stringify({
                 model: this.model,
-                system: systemPrompt,
-                messages,
-                tools: tools.length > 0 ? tools : undefined,
+                system: cachedSystem,
+                messages: cachedMessages,
+                tools: cachedTools.length > 0 ? cachedTools : undefined,
                 max_tokens: 8192,
             }),
         });
@@ -353,7 +395,7 @@ export class LocalAgent {
             throw new Error(`Claude API ${resp.status}: ${text.slice(0, 200)}`);
         }
         const data = await resp.json();
-        return { content: data.content || [], stopReason: data.stop_reason };
+        return { content: data.content || [], stopReason: data.stop_reason, usage: data.usage || null };
     }
 
     async _callOpenRouter(systemPrompt, messages, tools) {
@@ -363,17 +405,43 @@ export class LocalAgent {
             model = `anthropic/${model}`;
         }
 
-        const orMessages = [{ role: 'system', content: systemPrompt }, ...messages];
+        // PRD-071 Phase 2 — for anthropic/* models we need explicit cache_control
+        // breakpoints (OpenRouter relays them through to Anthropic). OpenAI +
+        // DeepSeek auto-cache, so the string system prompt path is fine there.
+        const isAnthropic = needsExplicitCacheControl(model);
+        const systemForOR = isAnthropic
+            ? { role: 'system', content: cacheableSystem(systemPrompt) }
+            : { role: 'system', content: systemPrompt };
+        const messagesForOR = isAnthropic ? withMessageBreakpoint(messages) : messages;
+        const orMessages = [systemForOR, ...messagesForOR];
+
+        // Same tool-schema shape as before, but tag the last tool for Anthropic
+        // (OpenRouter passes cache_control on function tools through).
+        const orTools = tools.length > 0
+            ? tools.map(t => ({
+                type: 'function',
+                function: { name: t.name, description: t.description, parameters: t.input_schema },
+            }))
+            : [];
+        const finalTools = isAnthropic ? cacheableTools(orTools) : orTools;
+
+        const headers = {
+            'Authorization': `Bearer ${this.openRouterKey}`,
+            'Content-Type': 'application/json',
+        };
+        // OpenRouter forwards `anthropic-beta` to Anthropic upstreams.
+        if (isAnthropic) headers['anthropic-beta'] = ANTHROPIC_BETA_HEADER;
+
         const resp = await fetch('https://openrouter.ai/api/v1/chat/completions', {
             method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.openRouterKey}`,
-                'Content-Type': 'application/json',
-            },
+            headers,
             body: JSON.stringify({
                 model,
                 messages: orMessages,
-                tools: tools.length > 0 ? tools.map(t => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.input_schema } })) : undefined,
+                tools: finalTools.length > 0 ? finalTools : undefined,
+                // Ask OpenRouter to include upstream cache accounting in the
+                // usage payload so PromptCache.updateStats() sees real numbers.
+                usage: { include: true },
             }),
         });
         if (!resp.ok) {
@@ -389,7 +457,11 @@ export class LocalAgent {
                 content.push({ type: 'tool_use', id: tc.id, name: tc.function.name, input: JSON.parse(tc.function.arguments || '{}') });
             }
         }
-        return { content, stopReason: choice?.finish_reason === 'stop' ? 'end_turn' : 'tool_use' };
+        return {
+            content,
+            stopReason: choice?.finish_reason === 'stop' ? 'end_turn' : 'tool_use',
+            usage: _normalizeOpenRouterUsage(data.usage),
+        };
     }
 
     _buildToolDefs() {
@@ -427,3 +499,38 @@ export class LocalAgent {
 
     cancel() { this._cancelled = true; }
 }
+
+// Shape the accumulated per-turn totals into the same envelope the remote
+// SSE `complete` event uses, so repl.mjs:837 can consume both modes with the
+// same code path. `models[0].role = 'local'` distinguishes single-agent
+// local mode from remote's Coder/Explorer/Planner breakdown.
+function _buildLocalUsageEnvelope(model, totals) {
+    return {
+        total_input_tokens: totals.input_tokens,
+        total_output_tokens: totals.output_tokens,
+        models: [{
+            model,
+            role: 'local',
+            input_tokens: totals.input_tokens,
+            output_tokens: totals.output_tokens,
+            cache_read_tokens: totals.cache_read_tokens,
+            cache_creation_tokens: totals.cache_creation_tokens,
+        }],
+    };
+}
+
+// Normalize OpenRouter usage into Anthropic's field names so downstream
+// consumers (PromptCache, pricing.calculateCost) don't branch on shape.
+// OpenRouter returns OpenAI-style: prompt_tokens, completion_tokens,
+// prompt_tokens_details.cached_tokens. When the underlying model is
+// Anthropic, OpenRouter also relays cache_read_input_tokens verbatim.
+function _normalizeOpenRouterUsage(usage) {
+    if (!usage) return null;
+    const cachedFromOpenAI = usage.prompt_tokens_details?.cached_tokens || 0;
+    return {
+        input_tokens: usage.prompt_tokens || 0,
+        output_tokens: usage.completion_tokens || 0,
+        cache_read_input_tokens: usage.cache_read_input_tokens || cachedFromOpenAI || 0,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens || 0,
+    };
+}

package/src/core/tasks.mjs

@@ -67,6 +67,57 @@ export function appendTask({ cwd = process.cwd(), list = 'backlog', text }) {
   return { list: normalized, path: filePath, text: taskText };
 }
 
+export function updateTask({ cwd = process.cwd(), list = 'active', index, text, checked } = {}) {
+  const normalized = normalizeList(list);
+  const taskIndex = normalizeTaskIndex(index);
+  ensureTaskFiles({ cwd });
+  const filePath = taskFilePath(cwd, normalized);
+  const content = readText(filePath);
+  const tasks = parseTaskMarkdown(content, normalized);
+  const task = tasks[taskIndex - 1];
+  if (!task) throw new Error(`No task ${taskIndex} in ${normalized}`);
+
+  const lines = content.split(/\r?\n/);
+  const nextText = String(text ?? task.text).trim();
+  if (!nextText) throw new Error('Task text is required');
+  const nextChecked = checked === undefined ? task.checked : Boolean(checked);
+  lines[task.line - 1] = taskLine(nextText, normalized, nextChecked);
+  fs.writeFileSync(filePath, lines.join('\n'));
+  return { list: normalized, path: filePath, index: taskIndex, previous: task, text: nextText, checked: nextChecked };
+}
+
+export function removeTask({ cwd = process.cwd(), list = 'active', index } = {}) {
+  const normalized = normalizeList(list);
+  const taskIndex = normalizeTaskIndex(index);
+  ensureTaskFiles({ cwd });
+  const filePath = taskFilePath(cwd, normalized);
+  const content = readText(filePath);
+  const tasks = parseTaskMarkdown(content, normalized);
+  const task = tasks[taskIndex - 1];
+  if (!task) throw new Error(`No task ${taskIndex} in ${normalized}`);
+
+  const lines = content.split(/\r?\n/);
+  lines.splice(task.line - 1, 1);
+  fs.writeFileSync(filePath, lines.join('\n'));
+  return { list: normalized, path: filePath, index: taskIndex, task };
+}
+
+export function moveTask({ cwd = process.cwd(), from = 'active', index, to = 'done', text } = {}) {
+  const source = normalizeList(from);
+  const target = normalizeList(to);
+  const removed = removeTask({ cwd, list: source, index });
+  const taskText = String(text ?? removed.task.text).trim();
+  const appended = appendTask({ cwd, list: target, text: taskText });
+  return {
+    from: source,
+    to: target,
+    index: removed.index,
+    text: taskText,
+    sourcePath: removed.path,
+    targetPath: appended.path,
+  };
+}
+
 export function taskCounts(board) {
   const lists = board?.lists || {};
   return Object.fromEntries(
@@ -74,7 +125,7 @@ export function taskCounts(board) {
   );
 }
 
-function normalizeList(value) {
+export function normalizeList(value) {
   const key = String(value || '').toLowerCase();
   if (key === 'todo' || key === 'pending') return 'backlog';
   if (key === 'current' || key === 'doing') return 'active';
@@ -83,6 +134,21 @@ function normalizeList(value) {
   throw new Error(`Unknown task list: ${value}`);
 }
 
+function normalizeTaskIndex(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw new Error('Task index must be a positive number');
+  return n;
+}
+
+function taskFilePath(cwd, list) {
+  return path.join(cwd, '.kepler', 'tasks', TASK_FILES[list]);
+}
+
+function taskLine(text, list, checked = false) {
+  const mark = checked || list === 'done' ? 'x' : ' ';
+  return `- [${mark}] ${text}`;
+}
+
 function readText(filePath) {
   try {
     return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';