@axplusb/kepler 2.2.0 → 2.3.0

package/KEPLER-README.md

@@ -1,222 +1,237 @@
 # @axplusb/kepler
 
-AI coding agent that plans, builds, tests, and ships. 30.7% on SWE-bench Lite.
+Kepler is an AI coding agent for terminal-first software work. It can inspect a
+repo, plan changes, run tools, ask for human approval, resume prior sessions, and
+keep local project context in `.kepler/`.
 
 ## Install
 
 ```bash
-npm install -g @axplusb/kepler
+npm install -g @axplusb/kepler@latest
 ```
 
-## Quick Start
+Run without global install:
 
 ```bash
-kepler login                        # Sign in via browser (GitHub/Google)
-kepler                              # Start interactive REPL
-kepler "fix the auth bug"           # Run a single instruction
+npx @axplusb/kepler@latest
 ```
 
-## Commands
+Update an existing global install:
 
-```
-kepler                    Start interactive REPL
-kepler "instruction"      Run a single instruction and exit
-kepler login              Sign in via browser
-kepler dashboard          Open Kepler Pulse analytics dashboard
-kepler sessions           List recent local sessions
-kepler stats              Aggregate session stats (tokens, cost, tools)
-kepler history            Recent prompt history
-kepler skills list        List discovered project and global skills
-kepler skills view NAME   View a skill procedure or bundled resource
-kepler skills install SRC Install skills from a directory or Git repository
-kepler skills update NAME Update a locked installed skill
-kepler skills remove NAME Remove an installed skill
-kepler version            Show version
+```bash
+npm update -g @axplusb/kepler
+kepler version
 ```
 
-## Agent Skills
+Requires Node.js 18 or newer.
 
-Kepler supports portable `SKILL.md` bundles and Claude-compatible skill
-directories. Skill metadata is included in the cached agent context; full
-instructions and references are loaded only when the agent calls
-`skill_view`.
-
-Discovery precedence:
+## Quick Start
 
-1. `<project>/.kepler/skills`
-2. `<project>/.claude/skills`
-3. `~/.kepler/skills`
-4. `~/.claude/skills`
+```bash
+kepler login
+kepler
+kepler "fix the failing auth test"
+```
 
-Install a local bundle or a repository containing one or more skills:
+Common startup commands:
 
 ```bash
-kepler skills install ./my-skill
-kepler skills install github:owner/skills-repository
-kepler skills install https://github.com/owner/skills.git
-kepler skills install ./team-skills --project
+kepler                    Start interactive REPL
+kepler "instruction"      Run a single instruction and exit
+kepler login              Sign in through the browser
+kepler dashboard          Open Kepler Pulse analytics dashboard
+kepler sessions           List recent local sessions
+kepler stats              Aggregate local session stats
+kepler history            Show recent prompt history
+kepler version            Show installed version
 ```
 
-Global installations are recorded in `~/.kepler/skills.lock.json`. Project
-installations use `<project>/.kepler/skills.lock.json`. Kepler copies skill
-files as data, rejects symlinks, and does not execute bundled scripts during
-installation.
+## What's New In 2.2.0
+
+- Resume sessions with summary-only, summary plus last 10 turns, or summary plus
+  last 20 turns.
+- Resume summaries are checkpointed in the selected session transcript, so future
+  resumes summarize only new uncovered history.
+- Approval prompts now use one consistent layout across shell, sensitive reads,
+  destructive actions, and backend/framework HITL approvals.
+- Reject/stop is a single action. Use re-plan with note when you want to steer
+  the agent.
+- Approval logs redact secrets before writing to `.kepler/approvals.log`.
+- Long shell commands wrap instead of being truncated.
+- Long-running shell commands return an observed output tail instead of hanging
+  silently.
 
 ## REPL Commands
 
-```
-/help                   Show available commands
-/stats                  Session metrics (tokens, cost, tools)
-/cost                   Detailed cost breakdown by model
+```text
+/help                   Show commands and command groups
+/status                 Session status and loaded project context
+/plan                   Show project plan and task files
+/tasks                  List or add project tasks
+/stats                  Session metrics
 /history                Conversation history
-/clear                  Clear conversation history
+/history approvals      Recent approval decisions
+/resume                 Resume a previous local session
+/clear                  Clear in-memory conversation history
 /explore <query>        Spawn read-only codebase explorer
 /review <query>         Spawn code review agent
 /architect <query>      Spawn architecture planning agent
 /safety                 Show safety guardrail status
 /revoke                 Revoke auto-approvals
+/settings               Show effective settings and policy sources
 /exit                   Exit the REPL
 ```
 
-## Keyboard
+Keyboard:
 
-```
-Esc                     Cancel current execution
+```text
+Esc                     Stop current execution or close a prompt
 Space                   Pause / resume execution
 Ctrl+C                  Exit
 ```
 
-## Configuration
+## Resume Behavior
 
-Settings are managed via the web dashboard at [codekepler.ai/dashboard/settings](https://codekepler.ai/dashboard/settings) and synced to the CLI automatically.
+`/resume` reads local JSONL transcripts from `~/.kepler/projects/**`. The
+selected session is the source of truth.
 
-- **API Key**: Add your OpenRouter/Anthropic/OpenAI key in Settings
-- **Model**: Choose your preferred model (40+ supported)
-- **Gateway**: Select provider (OpenRouter, Anthropic, OpenAI, Bedrock, Google AI, etc.)
-- **Config directory**: `~/.kepler/`
+For large sessions, Kepler shows mode choices:
 
-## Models
+```text
+full transcript
+summary only
+summary + last 10 turns
+summary + last 20 turns
+```
 
-Works with 13 providers and 40+ models:
+The session picker still shows the raw full transcript estimate, for example
+`593k ctx`. If a summary checkpoint exists, it also shows a status such as
+`summarized 82%`. That means earlier reconstructed messages are already covered
+by a stored `resume_summary` marker. Summary and tail modes reuse that marker and
+only summarize uncovered messages when needed.
 
-| Provider | Models |
-|----------|--------|
-| DeepSeek | V4 Flash, V4 Pro, R1 |
-| Anthropic | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 |
-| Google | Gemini 2.5 Pro, Flash |
-| OpenAI | GPT-4.1, O3, Codex |
-| Meta | Llama 4 Maverick, Scout |
-| Mistral | Devstral, Codestral |
-| xAI | Grok 3 |
-| Qwen | Qwen3 Coder |
-| + | AWS Bedrock, Azure OpenAI, Databricks, Moonshot, Custom |
+The agent receives:
 
-Platform default included free. Bring your own API key for unlimited.
+1. resume metadata
+2. the original user request
+3. the checkpointed or freshly generated summary
+4. the retained recent tail for summary-plus-tail modes
 
-## SWE-bench
+## Approvals And HITL
 
-| Model | Score | Cost |
-|-------|-------|------|
-| DeepSeek V4 Flash + stagnation | 47.3% (142/300) | $0.046/instance |
-| DeepSeek V4 Flash | 39.7% (119/300) | $0.046/instance |
-| DeepSeek V4 Flash (baseline) | 30.7% (92/300) | $0.03/instance |
-| DeepSeek V4 Pro | 50% (14/28 sample) | $0.48/instance |
+Kepler auto-approves low-risk reads and safe shell inspection commands. It asks
+for confirmation for sensitive reads, mutating shell commands, destructive
+actions, network actions, and framework-level HITL requests.
 
-### Running SWE-bench
+Prompt actions:
 
-Benchmarks run on an Azure VM (`swebench-eval-vm`, D8s_v3) with a local backend + CLI.
+```text
+Enter / y      approve once
+t              always allow this tool type, when available
+s              trust this pattern for the session, when policy allows it
+a              trust this pattern for the project, when policy allows it
+r              re-plan with a note for the agent
+n / Esc        stop without running
+?              show why approval is required
+```
 
-**Setup (one-time):**
+Sensitive reads include files such as `.env`, `*.pem`, and `secrets/**`.
 
-```bash
-# Deploy backend + CLI + harness to VM
-./benchmark/vm-setup.sh
-```
+Approval decisions are logged locally in `.kepler/approvals.log`. Secret-like
+values in commands, nested args, query strings, authorization headers, and
+rejection notes are redacted before the log is written.
 
-**Run benchmark:**
+## Project Context
 
-```bash
-# SSH into VM
-ssh azureuser@20.9.77.9
-
-# Start backend
-source ~/.tarang-benchmark.env
-cd ~/tarang-backend
-source ~/backend-env/bin/activate
-uvicorn app.main:app --port 8000 &
-
-# Run all 300 instances (3 parallel workers, skip already-done)
-source ~/swebench-env/bin/activate
-cd ~/tarang-npm
-python3 benchmark/swe-bench/harness.py \
-    --dataset lite \
-    --model deepseek/deepseek-v4-flash \
-    --parallel 3 \
-    --skip-done \
-    --timeout 600
+Kepler uses a project-local `.kepler/` folder for hand-editable context:
+
+```text
+.kepler/
+  KEPLER.md          Project operating brief
+  settings.json      Project settings and policy
+  hooks.json         Tool/user hook configuration
+  hitl.md            Approval guidance
+  tasks/
+    backlog.md
+    active.md
+    blocked.md
+    done.md
 ```
 
-**Flags:**
+Use `/plan` and `/tasks` in the REPL to inspect and update task files.
+
+## Skills
 
-| Flag | Description |
-|------|-------------|
-| `--dataset lite\|verified\|full` | SWE-bench split (default: lite, 300 instances) |
-| `--model <id>` | OpenRouter model ID |
-| `--parallel <n>` | Number of parallel workers (default: 1) |
-| `--skip-done` | Skip instances already in the output file |
-| `--timeout <s>` | Per-instance timeout in seconds (default: 600) |
-| `--limit <n>` | Only run first N instances |
-| `--instance <id>` | Run a single instance by ID |
-| `--gen-only` | Generate patches only (skip test evaluation) |
-| `--output <path>` | Custom output file path |
+Kepler supports portable `SKILL.md` bundles and Claude-compatible skill
+directories. Skill metadata is included in cached context; full instructions and
+references are loaded only when needed.
+
+Discovery precedence:
 
-**Results** are saved incrementally to `benchmark/results/<model>_<dataset>.json` — no data loss on kill.
+1. `<project>/.kepler/skills`
+2. `<project>/.claude/skills`
+3. `~/.kepler/skills`
+4. `~/.claude/skills`
 
-**Convenience scripts on VM:**
+Install skills:
 
 ```bash
-# Watchdog (auto-restarts on crash)
-tmux new-session -d -s bench "bash /tmp/start-parallel.sh"
+kepler skills install ./my-skill
+kepler skills install github:owner/skills-repository
+kepler skills install https://github.com/owner/skills.git
+kepler skills install ./team-skills --project
+```
+
+## Configuration
 
-# Check progress
-tmux capture-pane -t bench -p | tail -20
+Settings are managed in the web dashboard and synced to the CLI:
 
-# Or use the pre-built start script
-./start-benchmark.sh deepseek/deepseek-v4-flash
+https://codekepler.ai/dashboard/settings
+
+Common local paths:
+
+```text
+~/.kepler/                         Global CLI state
+~/.kepler/projects/**              Local JSONL transcripts
+~/.kepler/history.jsonl            Prompt history
+<project>/.kepler/                 Project context and policy
+<project>/.kepler/approvals.log    Project approval audit log
 ```
 
-## Terminal-Bench
+Provider API keys can be configured in the dashboard or through environment
+variables such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and
+`OPENROUTER_API_KEY`.
 
-Use the benchmark-only adapter under `benchmark/terminal-bench/` when you want to
-evaluate Kepler in Terminal-Bench without touching the production CLI.
+## Troubleshooting
 
-It runs with:
+Check installed package:
 
-- a separate backend venv
-- a separate backend port (`8001` by default)
-- a custom `--agent-import-path kepler_agent:KeplerAgent`
-- per-trial workspace isolation so memory does not leak across tasks
+```bash
+npm list -g @axplusb/kepler --depth=0
+kepler version
+```
 
-Reusable entrypoints:
+Use a clean one-off run:
 
 ```bash
-benchmark/terminal-bench/setup-kepler-backend.sh
-benchmark/terminal-bench/run-kepler-backend.sh
-benchmark/terminal-bench/run-kepler-benchmark.sh --task-id hello-world
+npx @axplusb/kepler@latest --version
 ```
 
-Environment variables that can be overridden in another machine or CI setup:
+If npm cache permissions are broken, use a temporary cache:
 
-`BACKEND_DIR`, `FRAMEWORK_DIR`, `VENV_DIR`, `TB_VENV`, `TARANG_NPM_DIR`,
-`ENV_FILE`, `BACKEND_URL`, `PORT`, `MODEL`, `DATASET`, `CONCURRENCY`.
+```bash
+env NPM_CONFIG_CACHE=/private/tmp/kepler-npm-cache npm pack --dry-run
+```
 
-Create a local `.tarang-tbench.env` with the benchmark credentials and backend
-auth token, then point `ENV_FILE` at it if needed.
+If a resume session shows a large context number, check whether the row also
+shows `summarized`. The large number is the full transcript estimate; summary and
+tail modes usually send much less.
 
 ## Links
 
-- Website: [codekepler.ai](https://codekepler.ai)
-- Company: [axplusb.tech](https://axplusb.tech)
+- Website: https://codekepler.ai
+- Company: https://axplusb.tech
+- Repository: https://github.com/raviakasapu/codekepler-npm
 
 ## License
 

package/README.md

@@ -1,96 +1,68 @@
 # @axplusb/kepler
 
-AI coding agent that plans, builds, tests, and ships. 30.7% on SWE-bench Lite.
+Kepler is an AI coding agent for terminal-first software work. It can inspect a
+repo, plan changes, run tools, ask for human approval, resume prior sessions, and
+keep local project context in `.kepler/`.
+
+The npm package uses [KEPLER-README.md](./KEPLER-README.md) as the published
+README. Keep that file as the canonical npm-facing documentation.
 
 ## Install
 
 ```bash
-npm install -g @axplusb/kepler
+npm install -g @axplusb/kepler@latest
 ```
 
-## Quick Start
+Run without global install:
 
 ```bash
-kepler login                        # Sign in via browser (GitHub/Google)
-kepler                              # Start interactive REPL
-kepler "fix the auth bug"           # Run a single instruction
+npx @axplusb/kepler@latest
 ```
 
-## Commands
+## Quick Start
 
+```bash
+kepler login
+kepler
+kepler "fix the failing auth test"
 ```
+
+## Common Commands
+
+```text
 kepler                    Start interactive REPL
 kepler "instruction"      Run a single instruction and exit
-kepler login              Sign in via browser
+kepler login              Sign in through the browser
 kepler dashboard          Open Kepler Pulse analytics dashboard
 kepler sessions           List recent local sessions
-kepler stats              Aggregate session stats (tokens, cost, tools)
-kepler history            Recent prompt history
-kepler version            Show version
+kepler stats              Aggregate local session stats
+kepler history            Show recent prompt history
+kepler version            Show installed version
 ```
 
-## REPL Commands
+## 2.2.0 Highlights
 
-```
-/help                   Show available commands
-/stats                  Session metrics (tokens, cost, tools)
-/cost                   Detailed cost breakdown by model
-/history                Conversation history
-/clear                  Clear conversation history
-/explore <query>        Spawn read-only codebase explorer
-/review <query>         Spawn code review agent
-/architect <query>      Spawn architecture planning agent
-/safety                 Show safety guardrail status
-/revoke                 Revoke auto-approvals
-/exit                   Exit the REPL
-```
+- Checkpointed `/resume` summaries with summary-only and summary-plus-tail modes.
+- One approval prompt model for shell, sensitive reads, destructive actions, and
+  backend/framework HITL.
+- Redacted local approval logs.
+- Wrapped full shell command display.
+- Long-running shell command tail capture.
 
-## Keyboard
+## Development
 
+```bash
+npm test
+env NPM_CONFIG_CACHE=/private/tmp/kepler-npm-cache npm pack --dry-run
 ```
-Esc                     Cancel current execution
-Space                   Pause / resume execution
-Ctrl+C                  Exit
-```
-
-## Configuration
-
-Settings are managed via the web dashboard at [codekepler.ai/dashboard/settings](https://codekepler.ai/dashboard/settings) and synced to the CLI automatically.
-
-- **API Key**: Add your OpenRouter/Anthropic/OpenAI key in Settings
-- **Model**: Choose your preferred model (40+ supported)
-- **Gateway**: Select provider (OpenRouter, Anthropic, OpenAI, Bedrock, Google AI, etc.)
-- **Config directory**: `~/.kepler/`
-
-## Models
-
-Works with 13 providers and 40+ models:
-
-| Provider | Models |
-|----------|--------|
-| DeepSeek | V4 Flash, V4 Pro, R1 |
-| Anthropic | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 |
-| Google | Gemini 2.5 Pro, Flash |
-| OpenAI | GPT-4.1, O3, Codex |
-| Meta | Llama 4 Maverick, Scout |
-| Mistral | Devstral, Codestral |
-| xAI | Grok 3 |
-| Qwen | Qwen3 Coder |
-| + | AWS Bedrock, Azure OpenAI, Databricks, Moonshot, Custom |
-
-Platform default included free. Bring your own API key for unlimited.
-
-## SWE-bench
 
-| Model | Score | Cost |
-|-------|-------|------|
-| DeepSeek V4 Flash | 30.7% (92/300) | $0.03/fix |
-| DeepSeek V4 Pro | 50% (14/28 sample) | $0.48/fix |
+See [RELEASE.md](./RELEASE.md) for the merge, PR, and npm publish checklist.
 
 ## Links
 
-- Website: [codekepler.ai](https://codekepler.ai)
-- Company: [axplusb.tech](https://axplusb.tech)
+- Website: https://codekepler.ai
+- Company: https://axplusb.tech
+- Repository: https://github.com/raviakasapu/codekepler-npm
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axplusb/kepler",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Kepler — AI coding agent with operating brief, preflight planning, and sub-agents. SWE-bench Lite evaluated.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   "readme": "KEPLER-README.md",
   "scripts": {
     "start": "node src/terminal/main.mjs",
-    "test": "KEPLER_HOME=/tmp/kepler-test-home node test/test-sse-client.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-tool-executor.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-project-artifacts.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-skills.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-callback.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-rate-limit-display.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-preflight.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-formatter.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-terminal-rendering.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-slash-commands.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-approval.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-approval-log.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-kepler-contract.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-session-manager.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-safety.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-jsonl-writer.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-analytics.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-stagnation.mjs"
+    "test": "KEPLER_HOME=/tmp/kepler-test-home node test/test-sse-client.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-tool-executor.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-project-artifacts.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-work-scope.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-skills.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-callback.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-rate-limit-display.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-preflight.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-formatter.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-terminal-rendering.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-slash-commands.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-approval.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-approval-log.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-kepler-contract.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-session-manager.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-safety.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-jsonl-writer.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-analytics.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-stagnation.mjs"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/config/cli-args.mjs

@@ -103,6 +103,19 @@ export function parseArgs(args) {
                 result.freeswim = true; // headless implies skip permissions
                 break;
 
+            case '--cache-report':
+                // PRD-071 §1.5 — write a machine-readable cache summary to
+                // <path> at end of run. Consumed by benchmark/cache-check.sh.
+                result.cacheReport = args[++i];
+                break;
+
+            case '--local':
+                // Force LocalAgent path (bypass backend). Meant for benchmarks
+                // that need to exercise the CLI's own LLM code — cache_control
+                // wiring, prompt-cache stats, etc.
+                result.local = true;
+                break;
+
             case '--freeswim-open-waters':
             case '--freeswim':
             case '--yes':
@@ -161,6 +174,7 @@ Options:
   --resume, -r [sessionId]   Resume last session (or specific session)
   --continue                 Alias for --resume
   --headless                 Non-interactive mode: auto-approve, JSONL output
+  --cache-report <file>      Write prompt-cache summary JSON to <file> (headless only)
   --freeswim-open-waters     Skip all approval prompts (no boundaries)
   --freeswim                 Alias for --freeswim-open-waters
   --yes                      Alias for --freeswim-open-waters

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