@axplusb/kepler 1.0.5 → 1.0.9

package/KEPLER-README.md

@@ -26,9 +26,42 @@ 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
 ```
 
+## Agent Skills
+
+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:
+
+1. `<project>/.kepler/skills`
+2. `<project>/.claude/skills`
+3. `~/.kepler/skills`
+4. `~/.claude/skills`
+
+Install a local bundle or a repository containing one or more skills:
+
+```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
+```
+
+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.
+
 ## REPL Commands
 
 ```
@@ -84,6 +117,7 @@ Platform default included free. Bring your own API key for unlimited.
 
 | 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 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@axplusb/kepler",
-  "version": "1.0.5",
-  "description": "Kepler — AI coding agent that plans, builds, tests, and ships. 30.7% on SWE-bench Lite.",
+  "version": "1.0.9",
+  "description": "Kepler — AI coding agent with operating brief, preflight planning, and sub-agents. SWE-bench Lite evaluated.",
   "type": "module",
   "bin": {
     "kepler": "src/terminal/main.mjs"
@@ -14,7 +14,7 @@
   "readme": "KEPLER-README.md",
   "scripts": {
     "start": "node src/terminal/main.mjs",
-    "test": "node test/test-sse-client.mjs && node test/test-tool-executor.mjs && node test/test-callback.mjs && node test/test-formatter.mjs && node test/test-terminal-rendering.mjs && node test/test-slash-commands.mjs && node test/test-approval.mjs && node test/test-session-manager.mjs && node test/test-safety.mjs && node test/test-jsonl-writer.mjs && node test/test-analytics.mjs && node test/test-stagnation.mjs"
+    "test": "node test/test-sse-client.mjs && node test/test-tool-executor.mjs && node test/test-project-artifacts.mjs && node test/test-skills.mjs && node test/test-callback.mjs && node test/test-formatter.mjs && node test/test-terminal-rendering.mjs && node test/test-slash-commands.mjs && node test/test-approval.mjs && node test/test-session-manager.mjs && node test/test-safety.mjs && node test/test-jsonl-writer.mjs && node test/test-analytics.mjs && node test/test-stagnation.mjs"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -38,7 +38,7 @@
   "homepage": "https://codekepler.ai",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/raviakasapu/codekepler-web.git"
+    "url": "git+https://github.com/raviakasapu/codekepler-npm.git"
   },
   "dependencies": {}
 }

package/src/core/headless.mjs

@@ -13,10 +13,9 @@
 
 import { TarangStreamClient } from './stream-client.mjs';
 import { createToolExecutor } from './tool-executor.mjs';
+import { persistProjectArtifacts } from './project-artifacts.mjs';
 import { TarangAuth } from '../auth/tarang-auth.mjs';
 import { ApprovalManager } from './approval.mjs';
-import { ContextRetriever } from '../context/retriever.mjs';
-import { buildProjectSkeleton } from '../context/skeleton.mjs';
 
 /**
  * Run a single instruction in headless mode.
@@ -46,22 +45,8 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
         process.exit(1);
     }
 
-    // ── Index project (with timeout — large repos can take minutes) ──
-    log('Indexing project...');
-    const retriever = new ContextRetriever(process.cwd());
-    try {
-        const indexPromise = retriever.buildIndex();
-        const indexTimeout = new Promise((_, reject) =>
-            setTimeout(() => reject(new Error('Index timeout')), 15000)
-        );
-        await Promise.race([indexPromise, indexTimeout]);
-        log('Index ready');
-    } catch (e) {
-        log(`Index skipped: ${e.message || 'failed'}`);
-    }
-
-    const skeleton = buildProjectSkeleton(process.cwd());
-    const toolExecutor = createToolExecutor({ retriever });
+    // Projects are registered and indexed only when the agent requests an overview.
+    const toolExecutor = createToolExecutor();
 
     // Auto-approve everything — no prompts
     const approval = new ApprovalManager({ autoApprove: true });
@@ -85,14 +70,24 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     // ── Execute ──
     emit({ type: 'start', timestamp: Date.now(), instruction, model: model || 'default', cwd: process.cwd() });
 
-    const execContext = { cwd: process.cwd(), freeswim: true };
-    if (skeleton) execContext.project_skeleton = skeleton;
+    const execContext = {
+        cwd: process.cwd(),
+        freeswim: true,
+        project_resources: toolExecutor.getProjectResources(),
+        agent_context: toolExecutor.getAgentContext(),
+    };
     if (model) execContext.model_override = model;
 
     let toolCount = 0;
     let finalContent = '';
     let totalCost = 0;
 
+    // ── Telemetry collectors ──
+    const toolCalls = [];       // { tool, duration_ms, success }
+    const subAgents = [];       // { type, model, duration_s, tool_calls, success }
+    let stagnationCount = 0;
+    let usage = {};             // { input_tokens, output_tokens, cache_read, cache_write }
+
     try {
         for await (const event of client.execute(instruction, execContext)) {
             const { type, data } = event;
@@ -101,6 +96,7 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
                 toolCount++;
                 const toolName = data?.tool || 'unknown';
                 const args = data?.args || {};
+                toolCalls.push({ tool: toolName, success: null, duration_ms: 0 });
                 emit({ type: 'tool_call', tool: toolName, args, approved: true });
                 log(`Tool: ${toolName}`);
             }
@@ -108,9 +104,42 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
             if (type === 'tool_result' || type === 'tool_done') {
                 const success = data?.success !== false;
                 const duration = data?.duration_s || 0;
+                // Update last tool call with result
+                const last = toolCalls.findLast(t => t.tool === (data?.tool || ''));
+                if (last) { last.success = success; last.duration_ms = Math.round(duration * 1000); }
                 emit({ type: 'tool_result', tool: data?.tool || '', success, duration_ms: Math.round(duration * 1000) });
             }
 
+            if (type === 'sub_agent_start') {
+                log(`SubAgent: ${data?.type} (${data?.model})`);
+            }
+
+            if (type === 'sub_agent_complete') {
+                subAgents.push({
+                    type: data?.type || '',
+                    model: data?.model || '',
+                    duration_s: data?.duration_s || 0,
+                    tool_calls: data?.tool_calls || 0,
+                    success: data?.success !== false,
+                });
+                emit({ type: 'sub_agent', ...data });
+                log(`SubAgent done: ${data?.type} (${data?.tool_calls} tools, ${data?.duration_s}s)`);
+            }
+
+            if (type === 'plan_created' || type === 'goal_created') {
+                persistProjectArtifacts(
+                    data,
+                    toolExecutor.getProjectResources(),
+                    log,
+                );
+            }
+
+            if (type === 'stagnation' || type === 'stagnation_detected') {
+                stagnationCount++;
+                emit({ type: 'stagnation', reason: data?.reason || '', strategy: data?.recovery_strategy || '' });
+                log(`Stagnation: ${data?.reason || ''}`);
+            }
+
             if (type === 'content') {
                 finalContent = data?.text || '';
             }
@@ -122,10 +151,15 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
 
             if (type === 'complete') {
                 totalCost = data?.cost || data?.total_cost || 0;
-
-                // Extract cost from usage breakdown if available
-                if (data?.usage?.total_cost) {
-                    totalCost = data.usage.total_cost;
+                if (data?.usage?.total_cost) totalCost = data.usage.total_cost;
+                // Capture token usage
+                if (data?.usage) {
+                    usage = {
+                        input_tokens: data.usage.total_input_tokens || data.usage.input_tokens || 0,
+                        output_tokens: data.usage.total_output_tokens || data.usage.output_tokens || 0,
+                        cache_read: data.usage.cache_read_input_tokens || data.usage.cache_read || 0,
+                        cache_write: data.usage.cache_creation_input_tokens || data.usage.cache_write || 0,
+                    };
                 }
             }
 
@@ -148,9 +182,19 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
 
     const durationS = (Date.now() - startTime) / 1000;
 
+    // ── Tool breakdown ──
+    const toolBreakdown = {};
+    for (const t of toolCalls) {
+        toolBreakdown[t.tool] = (toolBreakdown[t.tool] || 0) + 1;
+    }
+
     emit({
         type: 'complete',
         tools: toolCount,
+        tool_breakdown: toolBreakdown,
+        sub_agents: subAgents,
+        stagnation_triggers: stagnationCount,
+        usage,
         duration_s: Math.round(durationS * 10) / 10,
         cost_usd: totalCost,
         model: model || 'default',

package/src/core/project-artifacts.mjs

@@ -0,0 +1,37 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Persist generated session artifacts only beneath roots registered by the CLI.
+ */
+export function persistProjectArtifacts(data, resources, log = () => {}) {
+    const projectIds = new Set(
+        Array.isArray(data?.project_ids) ? data.project_ids.filter(Boolean) : []
+    );
+    const registered = Array.isArray(resources) ? resources : [];
+    const targets = projectIds.size > 0
+        ? registered.filter(resource => projectIds.has(resource.project_id))
+        : registered.length === 1 ? registered : [];
+    const artifacts = [
+        ['goal', 'goal.md'],
+        ['plan', 'plan.md'],
+    ].filter(([field]) => typeof data?.[field] === 'string' && data[field].trim());
+    const written = [];
+
+    for (const resource of targets) {
+        for (const [field, filename] of artifacts) {
+            try {
+                const keplerDir = path.join(resource.root, '.kepler');
+                fs.mkdirSync(keplerDir, { recursive: true });
+                const artifactPath = path.join(keplerDir, filename);
+                fs.writeFileSync(artifactPath, data[field], 'utf-8');
+                resource[field] = data[field];
+                written.push(artifactPath);
+                log(`${field} saved -> ${artifactPath}`);
+            } catch {
+                // Persistence is helpful but must not stop the agent.
+            }
+        }
+    }
+    return written;
+}