@axplusb/kepler 2.2.0 → 2.3.0

package/src/core/work-scope.mjs

@@ -0,0 +1,217 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const SCHEMA = 'kepler.work_scope/1';
+const ROOT_MARKERS = [
+    '.kepler',
+    '.git',
+    'package.json',
+    'pyproject.toml',
+    'setup.py',
+    'go.mod',
+    'Cargo.toml',
+];
+
+function stable(value) {
+    if (Array.isArray(value)) return value.map(stable);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value)
+                .filter(([, v]) => v !== undefined)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => [k, stable(v)]),
+        );
+    }
+    return value;
+}
+
+function sha(payload) {
+    return crypto
+        .createHash('sha256')
+        .update(JSON.stringify(stable(payload)))
+        .digest('hex')
+        .slice(0, 16);
+}
+
+function normalizePathInput(value) {
+    let s = String(value || '').trim();
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        s = s.slice(1, -1);
+    }
+    if (s === '~' || s.startsWith('~/')) {
+        s = path.join(os.homedir(), s.slice(1));
+    }
+    return s.replace(/\\([ \t()&$;'"])/g, '$1');
+}
+
+function nearestProjectRoot(candidate) {
+    let resolved = normalizePathInput(candidate);
+    if (!resolved || !path.isAbsolute(resolved)) return null;
+
+    try {
+        resolved = fs.realpathSync(resolved);
+    } catch {
+        return null;
+    }
+
+    let dir = resolved;
+    try {
+        if (fs.statSync(resolved).isFile()) dir = path.dirname(resolved);
+    } catch {
+        return null;
+    }
+
+    const root = path.parse(dir).root;
+    let current = dir;
+    while (current && current !== root) {
+        if (ROOT_MARKERS.some(marker => fs.existsSync(path.join(current, marker)))) {
+            return fs.realpathSync(current);
+        }
+        current = path.dirname(current);
+    }
+    return fs.realpathSync(dir);
+}
+
+function extractQuotedPaths(text) {
+    const paths = [];
+    const re = /(['"])(\/[^'"\n]+)\1/g;
+    let match;
+    while ((match = re.exec(String(text || ''))) !== null) {
+        paths.push(match[2]);
+    }
+    return paths;
+}
+
+function extractPastedPaths(text) {
+    const source = String(text || '');
+    const paths = [];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] !== '/') continue;
+        const line = source.slice(i).split(/\r?\n/, 1)[0].replace(/[),.;:]+$/g, '');
+        const parts = line.split(/\s+/).filter(Boolean);
+        let candidate = '';
+        let lastRoot = null;
+        for (const part of parts.slice(0, 12)) {
+            candidate = candidate ? `${candidate} ${part}` : part;
+            const root = nearestProjectRoot(candidate.replace(/[),.;:]+$/g, ''));
+            if (root) lastRoot = root;
+        }
+        if (lastRoot) paths.push(lastRoot);
+    }
+    return paths;
+}
+
+function uniqueRoots(entries) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of entries) {
+        if (!entry?.path || seen.has(entry.path)) continue;
+        seen.add(entry.path);
+        result.push(entry);
+    }
+    return result;
+}
+
+function roleForRoot(root, cwd) {
+    const base = path.basename(root).toLowerCase();
+    if (base.includes('backend')) return 'backend';
+    if (base.includes('frontend') || base.includes('web')) return 'frontend';
+    if (base.includes('deploy')) return 'deploy';
+    if (base.includes('docs') || base.includes('prd')) return 'docs';
+    if (base.includes('npm') || base.includes('cli')) return 'cli';
+    if (root === cwd) return 'primary';
+    return 'workspace';
+}
+
+function truncate(value, max = 280) {
+    const s = String(value || '').replace(/\s+/g, ' ').trim();
+    return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+function sortedResources(resources) {
+    return (Array.isArray(resources) ? resources : [])
+        .filter(resource => resource && resource.root)
+        .map(resource => ({
+            project_id: String(resource.project_id || ''),
+            root: String(resource.root || ''),
+            name: String(resource.name || path.basename(String(resource.root || ''))),
+            index_version: String(resource.index_version || ''),
+        }))
+        .sort((a, b) => a.root.localeCompare(b.root));
+}
+
+export function buildWorkScope({
+    instruction = '',
+    cwd = process.cwd(),
+    projectResources = [],
+} = {}) {
+    const cwdRoot = nearestProjectRoot(cwd) || path.resolve(cwd);
+    const roots = [{
+        path: cwdRoot,
+        role: roleForRoot(cwdRoot, cwdRoot),
+        source: 'cwd',
+        status: 'active',
+    }];
+
+    for (const raw of [...extractQuotedPaths(instruction), ...extractPastedPaths(instruction)]) {
+        const root = nearestProjectRoot(raw);
+        if (!root) continue;
+        roots.push({
+            path: root,
+            role: roleForRoot(root, cwdRoot),
+            source: 'prompt',
+            status: 'active',
+        });
+    }
+
+    for (const resource of sortedResources(projectResources)) {
+        roots.push({
+            path: resource.root,
+            role: roleForRoot(resource.root, cwdRoot),
+            source: 'registered',
+            status: 'active',
+            project_id: resource.project_id || undefined,
+        });
+    }
+
+    const activeRoots = uniqueRoots(roots);
+    const resources = sortedResources(projectResources);
+    const scope = {
+        schema: SCHEMA,
+        primary_root: cwdRoot,
+        intent: truncate(instruction),
+        active_roots: activeRoots,
+        candidate_roots: [],
+        workspace_resources: resources,
+        cache_policy: {
+            stable_system: false,
+            placement: 'pinned_context',
+            reason: 'scope changes with user intent and discovered roots',
+        },
+    };
+    scope.version = sha({
+        schema: scope.schema,
+        primary_root: scope.primary_root,
+        intent: scope.intent,
+        active_roots: scope.active_roots,
+        workspace_resources: scope.workspace_resources,
+    });
+    return scope;
+}
+
+export function summarizeWorkScope(scope) {
+    if (!scope || typeof scope !== 'object') return '';
+    const roots = Array.isArray(scope.active_roots) ? scope.active_roots : [];
+    const lines = [
+        `Work scope ${scope.version || 'unknown'}`,
+        `Primary: ${scope.primary_root || '(unknown)'}`,
+    ];
+    if (scope.intent) lines.push(`Intent: ${scope.intent}`);
+    for (const root of roots) {
+        if (!root?.path) continue;
+        lines.push(`- ${root.path} [${root.role || 'workspace'}; ${root.source || 'unknown'}]`);
+    }
+    return lines.join('\n');
+}

package/src/terminal/main.mjs

@@ -162,6 +162,8 @@ async function main() {
       model: args.model,
       timeout: args.timeout || (args.maxTurns ? args.maxTurns * 60 : 600),
       verbose: args.verbose,
+      cacheReport: args.cacheReport,
+      local: args.local,
     });
     return;
   }

package/src/terminal/repl.mjs

@@ -23,6 +23,7 @@ import { calculateCost, formatCostValue, formatTokens, costToCredits, formatCred
 import { TarangStreamClient, EVENT_TYPES } from '../core/stream-client.mjs';
 import { JsonlWriter } from '../core/jsonl-writer.mjs';
 import { createToolExecutor } from '../core/tool-executor.mjs';
+import { buildWorkScope } from '../core/work-scope.mjs';
 import { CheckpointManager } from '../core/checkpoints.mjs';
 import { HookRunner } from '../config/hook-runner.mjs';
 import { runPreflight } from '../onboarding/preflight.mjs';
@@ -47,7 +48,7 @@ import { loadProjectContext } from '../core/project-context-loader.mjs';
 import { buildContextEnvelope } from '../core/context-envelope.mjs';
 import { buildResumeHistory, combineResumeSummaries, getRecentSessions, getSessionDetail, getTranscriptProjectRoots } from '../core/local-store.mjs';
 import { decideResumeMode, projectedTokensForChoice, formatTokens as formatCtxTokens } from '../core/resume-mode.mjs';
-import { appendTask, ensureTaskFiles, loadTaskBoard, taskCounts, TASK_FILES } from '../core/tasks.mjs';
+import { appendTask, ensureTaskFiles, loadTaskBoard, moveTask, removeTask, taskCounts, TASK_FILES, updateTask } from '../core/tasks.mjs';
 import { toolDisplayLabel, toolDisplaySummary } from './tool-display.mjs';
 import { createOrbit } from '../state/orbit.mjs';
 import { attachOrbit, unmount as unmountStatusBar } from '../ui/status-bar.mjs';
@@ -1121,12 +1122,26 @@ function printBanner(auth) {
  * Left side: last-turn summary (tools, time, cost)
  * Right side: session totals (ctx%, tokens)
  */
+function computeCacheTotals() {
+  let read = 0;
+  let write = 0;
+  for (const b of session.costBreakdown) {
+    read += b.cache_read_tokens || 0;
+    write += b.cache_creation_tokens || 0;
+  }
+  const denom = session.inputTokens + read;
+  const hitRate = denom > 0 ? Math.round((read / denom) * 100) : 0;
+  return { read, write, hitRate };
+}
+
 function buildContextStrip() {
   const totalTokens = session.inputTokens + session.outputTokens;
   const elapsed = formatElapsed(session.startTime);
+  const cache = computeCacheTotals();
 
   const right = [
     c.dim(`${formatTokens(totalTokens)} tok`),
+    ...(cache.read > 0 ? [c.dim(`cache ${cache.hitRate}%`)] : []),
     c.dim(elapsed),
   ].join(c.dim(' · '));
 
@@ -1968,7 +1983,7 @@ function renderPlanOverview({ ctx, mode = 'overview' } = {}) {
   }
 
   renderTaskBoard(board, { showDone: mode === 'status' });
-  process.stderr.write(`\n  ${c.dim('Update: /tasks add <text> · /tasks active|blocked|done <text>')}\n\n`);
+  process.stderr.write(`\n  ${c.dim('Update: /tasks add <text> · /tasks move active 1 done · /tasks edit active 1 <text>')}\n\n`);
 }
 
 function refreshTaskContext(ctx) {
@@ -1987,7 +2002,7 @@ function handleTasksCommand(rest, ctx) {
     process.stderr.write(`\n  ${c.bold('Tasks')}\n`);
     process.stderr.write(`  ${c.dim('─'.repeat(60))}\n`);
     renderTaskBoard(board, { showDone: true });
-    process.stderr.write(`\n  ${c.dim('Update: /tasks add <text> · /tasks active|backlog|blocked|done <text>')}\n\n`);
+    process.stderr.write(`\n  ${c.dim('Update: /tasks add <text> · /tasks move active 1 done · /tasks edit active 1 <text>')}\n\n`);
     return;
   }
 
@@ -1998,6 +2013,60 @@ function handleTasksCommand(rest, ctx) {
 
   const parts = raw.split(/\s+/);
   let verb = (parts.shift() || '').toLowerCase();
+
+  if (verb === 'move') {
+    try {
+      const [from, index, to, ...textParts] = parts;
+      const result = moveTask({ cwd: safeCwd(), from, index, to, text: textParts.join(' ') || undefined });
+      refreshTaskContext(ctx);
+      process.stderr.write(`  ${c.green('✓')} ${c.dim(`moved ${result.from} #${result.index} → ${result.to}`)} ${result.text}\n`);
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+      process.stderr.write(`  ${c.gray('Usage: /tasks move <active|backlog|blocked|done> <number> <active|backlog|blocked|done> [new text]')}\n`);
+    }
+    return;
+  }
+
+  if (verb === 'edit' || verb === 'rename') {
+    try {
+      const [list, index, ...textParts] = parts;
+      const result = updateTask({ cwd: safeCwd(), list, index, text: textParts.join(' ') });
+      refreshTaskContext(ctx);
+      process.stderr.write(`  ${c.green('✓')} ${c.dim(`updated ${result.list} #${result.index}`)} ${result.text}\n`);
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+      process.stderr.write(`  ${c.gray('Usage: /tasks edit <active|backlog|blocked|done> <number> <new text>')}\n`);
+    }
+    return;
+  }
+
+  if (verb === 'remove' || verb === 'rm' || verb === 'delete') {
+    try {
+      const [list, index] = parts;
+      const result = removeTask({ cwd: safeCwd(), list, index });
+      refreshTaskContext(ctx);
+      process.stderr.write(`  ${c.green('✓')} ${c.dim(`removed ${result.list} #${result.index}`)} ${result.task.text}\n`);
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+      process.stderr.write(`  ${c.gray('Usage: /tasks remove <active|backlog|blocked|done> <number>')}\n`);
+    }
+    return;
+  }
+
+  if (verb === 'finish' || verb === 'complete' || verb === 'block' || verb === 'unblock') {
+    try {
+      const [from, index, ...textParts] = parts;
+      const to = verb === 'block' ? 'blocked' : verb === 'unblock' ? 'active' : 'done';
+      const result = moveTask({ cwd: safeCwd(), from, index, to, text: textParts.join(' ') || undefined });
+      refreshTaskContext(ctx);
+      process.stderr.write(`  ${c.green('✓')} ${c.dim(`moved ${result.from} #${result.index} → ${result.to}`)} ${result.text}\n`);
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+      process.stderr.write(`  ${c.gray(`Usage: /tasks ${verb} <active|backlog|blocked|done> <number> [new text]`)}\n`);
+    }
+    return;
+  }
+
   let list = 'backlog';
   if (verb === 'add' || verb === 'new') {
     const maybeList = (parts[0] || '').toLowerCase();
@@ -2192,6 +2261,15 @@ async function handleCommand(input, ctx) {
       }
       process.stderr.write(`  ${c.dim('CWD')}          ${safeCwd()}\n`);
 
+      // Cache — PRD-071 §1.2. Only surface when we have data; a fresh session
+      // shows nothing rather than a misleading "0%".
+      const cache = computeCacheTotals();
+      if (cache.read > 0 || cache.write > 0) {
+        const readLabel = formatTokens(cache.read);
+        const writeLabel = formatTokens(cache.write);
+        process.stderr.write(`  ${c.dim('Cache')}        ${cache.hitRate}% hit ${c.dim('·')} ${readLabel} read ${c.dim('·')} ${writeLabel} write\n`);
+      }
+
       // Permissions
       process.stderr.write(`\n  ${c.bold('Permissions')}\n`);
       process.stderr.write(`  ${c.dim('─'.repeat(44))}\n`);
@@ -3358,6 +3436,7 @@ export async function startTerminalRepl() {
       if (approval.trustStore) approval.trustStore.policy = effectivePolicy.policy;
       hookRunner.reload();
       latestProjectContext = loadProjectContext({ cwd: safeCwd(), previous: latestProjectContext });
+      const projectResources = toolExecutor.getProjectResources();
       const promptHook = await hookRunner.run('UserPromptSubmit', {
         input: { prompt: input },
         turnId: String(session.turns),
@@ -3379,7 +3458,7 @@ export async function startTerminalRepl() {
         effectivePolicy,
         projectContext: latestProjectContext,
         activeHints: [...hookHints, ...rejectionHints],
-        projectResources: toolExecutor.getProjectResources(),
+        projectResources,
         agentContext: toolExecutor.getAgentContext(),
       });
       ctx.effectivePolicy = effectivePolicy;
@@ -3387,6 +3466,14 @@ export async function startTerminalRepl() {
       ctx.latestEnvelope = latestEnvelope;
       Object.assign(execContext, latestEnvelope);
       if (skipPerms) execContext.freeswim = true;
+      // PRD-071: seed work_scope from CLI so the backend has a byte-stable
+      // scope block from turn 1. Uses projectResources already gathered by
+      // the envelope above.
+      execContext.work_scope = buildWorkScope({
+        instruction: input,
+        cwd: safeCwd(),
+        projectResources,
+      });
       for (const file of latestProjectContext.changed || []) {
         if (effectivePolicy.policy.context?.showReloadNotice) {
           process.stderr.write(`  ${c.dim(`[Context] ${file.label} updated — re-read`)}\n`);

package/src/ui/commands.mjs

@@ -7,12 +7,10 @@
 
 import { SessionManager } from '../core/session.mjs';
 import { CheckpointManager } from '../core/checkpoints.mjs';
-import { PromptCache } from '../core/cache.mjs';
 import { readEnv, listEnvVars } from '../config/env.mjs';
 import * as telemetry from '../telemetry/index.mjs';
 
 const checkpoints = new CheckpointManager();
-const promptCache = new PromptCache();
 let sessionManager = null;
 
 function getSession() {
@@ -399,11 +397,14 @@ export const COMMANDS = {
     '/extra-usage': {
         description: 'Show detailed usage stats',
         handler(args, state) {
-            const cacheStats = promptCache.getStats();
             const telemetryStats = telemetry.getStats();
+            const cacheRead = state.tokenUsage.cache_read || 0;
+            const cacheWrite = state.tokenUsage.cache_creation || 0;
+            const denom = state.tokenUsage.input + cacheRead;
+            const rate = denom > 0 ? Math.round((cacheRead / denom) * 100) : 0;
             return [
                 `Tokens: in=${state.tokenUsage.input}, out=${state.tokenUsage.output}`,
-                `Cache: hits=${cacheStats.cacheHits}, misses=${cacheStats.cacheMisses}, rate=${cacheStats.hitRate}`,
+                `Cache: read=${cacheRead}, write=${cacheWrite}, hit-rate=${rate}%`,
                 `Telemetry: ${telemetryStats.totalEvents} events`,
             ].join('\n');
         },