@axplusb/kepler 2.0.7 → 2.3.0

package/src/core/context-envelope.mjs

@@ -0,0 +1,54 @@
+import { contextToPromptBlock } from './project-context-loader.mjs';
+
+export function buildContextEnvelope({
+  cwd = process.cwd(),
+  command = null,
+  args = [],
+  source = 'repl',
+  dryRun = false,
+  aliasesResolved = [],
+  effectivePolicy,
+  projectContext,
+  activeHints = [],
+  projectResources = [],
+  agentContext = {},
+} = {}) {
+  const policy = effectivePolicy?.policy || {};
+  const commandTimeouts = policy.commands?.timeouts || {};
+  const enabled = policy.commands?.enabled || [];
+  const activeCommand = command || null;
+  const specificTimeout = activeCommand ? commandTimeouts[`${activeCommand}Seconds`] : null;
+
+  return {
+    cwd,
+    project_resources: projectResources,
+    agent_context: agentContext,
+    project_context: {
+      loaded_files: projectContext?.loaded || [],
+      changed_files: projectContext?.changed?.map(f => ({ label: f.label, path: f.path, hash: f.hash })) || [],
+      prompt_block: contextToPromptBlock(projectContext),
+    },
+    command_context: {
+      active_command: activeCommand,
+      source,
+      args,
+      dry_run: dryRun,
+      aliases_resolved: aliasesResolved,
+      runtime_limits: {
+        command_timeout_seconds: specificTimeout || commandTimeouts.defaultSeconds || 300,
+        tool_timeout_seconds: 120,
+        approval_timeout_seconds: null,
+      },
+    },
+    effective_options: {
+      commands_enabled: enabled,
+      plan_owner: policy.planning?.owner || 'auto',
+      hitl_default_scope: policy.hitl?.defaultScope || 'once',
+      reask_after_minutes: policy.hitl?.reaskAfterMinutes ?? 30,
+      hook_timeout_seconds: policy.hooks?.timeoutSeconds ?? 5,
+    },
+    context_hints: activeHints,
+    available_skills: projectContext?.available_skills || [],
+    task_state: projectContext?.task_state || [],
+  };
+}

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;
@@ -81,6 +116,7 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     let toolCount = 0;
     let finalContent = '';
     let totalCost = 0;
+    let rateLimit = null;
 
     // ── Telemetry collectors ──
     const toolCalls = [];       // { tool, duration_ms, success }
@@ -149,7 +185,12 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
                 if (text) finalContent = text;
             }
 
+            if (type === 'session_info' && data?.rate_limit) {
+                rateLimit = data.rate_limit;
+            }
+
             if (type === 'complete') {
+                if (data?.rate_limit) rateLimit = data.rate_limit;
                 totalCost = data?.cost || data?.total_cost || 0;
                 if (data?.usage?.total_cost) totalCost = data.usage.total_cost;
                 // Capture token usage
@@ -164,7 +205,13 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
             }
 
             if (type === 'error') {
-                emit({ type: 'error', error: data?.message || 'Unknown error' });
+                emit({
+                    type: 'error',
+                    error: data?.message || 'Unknown error',
+                    code: data?.code,
+                    retry_after: data?.retry_after,
+                    rate_limit: data?.rate_limit || null,
+                });
             }
 
             // ── Cost guard ──
@@ -202,10 +249,52 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
         usage,
         duration_s: Math.round(durationS * 10) / 10,
         cost_usd: totalCost,
+        rate_limit: rateLimit,
         model: model || 'default',
         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/jsonl-writer.mjs

@@ -40,6 +40,23 @@ function normalizeToolResultContent(output) {
   }
 }
 
+function sanitizeEventValue(value, depth = 0) {
+  if (depth > 8) return '[truncated-depth]';
+  if (typeof value === 'string') {
+    return value.length > 10000 ? value.slice(0, 10000) + '\n[...truncated...]' : value;
+  }
+  if (value == null || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.slice(0, 100).map(item => sanitizeEventValue(item, depth + 1));
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [key, item] of Object.entries(value).slice(0, 100)) {
+      out[key] = sanitizeEventValue(item, depth + 1);
+    }
+    return out;
+  }
+  return String(value);
+}
+
 export class JsonlWriter {
   /**
    * @param {string} cwd — project working directory
@@ -68,6 +85,7 @@ export class JsonlWriter {
     this._turnToolResults = []; // [{tool_use_id, content, is_error}, ...]
     this._turnUsage = null;
     this._turnModel = null;
+    this._pendingKeplerEvents = [];
 
     // Git branch (captured once at construction)
     this._gitBranch = this._detectGitBranch();
@@ -83,6 +101,11 @@ export class JsonlWriter {
     this.sessionId = id;
     this._transcriptPath = path.join(this.projectDir, `${id}.jsonl`);
     this._ready = true;
+    if (this._pendingKeplerEvents.length > 0) {
+      const pending = this._pendingKeplerEvents;
+      this._pendingKeplerEvents = [];
+      for (const event of pending) this.writeKeplerEvent(event);
+    }
     // Flush any buffered entries now that we have a path
     if (this._buffer.length > 0) this._flush();
   }
@@ -119,6 +142,33 @@ export class JsonlWriter {
     this.lastUuid = uuid;
   }
 
+  /**
+   * Write a Kepler UI/SSE event for exact-ish terminal replay on /resume.
+   * This is a Kepler extension; cc-lens readers should ignore unknown types.
+   */
+  writeKeplerEvent(event) {
+    if (!event || !event.type) return;
+    const sanitized = sanitizeEventValue({
+      type: event.type,
+      data: event.data || {},
+    });
+
+    if (!this.sessionId) {
+      this._pendingKeplerEvents.push(sanitized);
+      return;
+    }
+
+    const entry = {
+      type: 'kepler_event',
+      timestamp: new Date().toISOString(),
+      cwd: this.cwd,
+      sessionId: this.sessionId,
+      version: this.version,
+      event: sanitized,
+    };
+    this._appendEntry(entry);
+  }
+
   /**
    * Accumulate content during streaming (call on content/content_partial events).
    */

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,
+    };
+}