@axplusb/kepler 1.0.4 → 1.0.9

package/pulse/package.json

@@ -1,8 +1,8 @@
 {
-  "name": "orca-pulse",
-  "version": "1.0.0",
+  "name": "kepler-pulse",
+  "version": "1.0.1",
   "private": true,
-  "description": "Orca Pulse — real-time analytics dashboard for Orca AI agent sessions",
+  "description": "Kepler Pulse — real-time analytics dashboard for Kepler AI agent sessions",
   "scripts": {
     "dev": "next dev",
     "build": "next build",

package/src/auth/tarang-auth.mjs

@@ -10,7 +10,7 @@ import * as http from 'node:http';
 import { getLoginSuccessHTML } from '../ui/banner.mjs';
 import { resolveBackendUrl } from '../core/backend-url.mjs';
 
-const CONFIG_DIR = process.env.KEPLER_HOME || process.env.ORCA_HOME || path.join(os.homedir(), '.kepler');
+const CONFIG_DIR = process.env.KEPLER_HOME || path.join(os.homedir(), '.kepler');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
 
 export class TarangAuth {

package/src/config/cli-args.mjs

@@ -26,6 +26,7 @@ export function parseArgs(args) {
         systemPrompt: null,
         addDirs: [],
         maxTurns: null,
+        timeout: null,
         allowedTools: null,
         disallowedTools: null,
         resume: false,
@@ -72,6 +73,10 @@ export function parseArgs(args) {
                 result.maxTurns = parseInt(args[++i], 10);
                 break;
 
+            case '--timeout':
+                result.timeout = parseInt(args[++i], 10);
+                break;
+
             case '--allowedTools':
                 result.allowedTools = args[++i]?.split(',').map(s => s.trim());
                 break;

package/src/context/retriever.mjs

@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { indexDir as getIndexDir } from '../core/paths.mjs';
 
-const IGNORED_DIRS = new Set(['.git', 'node_modules', '.orca', '__pycache__', '.venv', 'venv', 'dist', 'build', '.next']);
+const IGNORED_DIRS = new Set(['.git', 'node_modules', '.kepler', '__pycache__', '.venv', 'venv', 'dist', 'build', '.next']);
 const CODE_EXTS = new Set(['.js', '.mjs', '.ts', '.tsx', '.py', '.go', '.rs', '.java', '.rb', '.php', '.c', '.cpp', '.h', '.css', '.html', '.json', '.yaml', '.yml', '.toml', '.md', '.sh']);
 const MAX_FILE_SIZE = 100_000; // 100KB
 const CHUNK_LINES = 50;

package/src/context/skeleton.mjs

@@ -12,7 +12,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const IGNORED_DIRS = new Set(['.git', 'node_modules', '.orca', '__pycache__', '.venv', 'venv', 'dist', 'build', '.next', '.cache', 'coverage', '.tox']);
+const IGNORED_DIRS = new Set(['.git', 'node_modules', '.kepler', '__pycache__', '.venv', 'venv', 'dist', 'build', '.next', '.cache', 'coverage', '.tox']);
 const CODE_EXTS = new Set(['.js', '.mjs', '.ts', '.tsx', '.py', '.go', '.rs', '.java', '.rb', '.c', '.cpp', '.h']);
 const MAX_FILE_SIZE = 200_000;
 

package/src/core/approval.mjs

@@ -10,7 +10,7 @@
  * Shell commands are risk-assessed (safe/medium/high).
  */
 
-import * as path from 'node:path';
+import { toolDisplayLabel, toolDisplaySummary } from '../terminal/tool-display.mjs';
 
 // ── Tool Classification ──
 
@@ -66,44 +66,6 @@ const WHITE = '\x1b[37m';
 
 const write = (s) => process.stderr.write(s);
 
-// ── Tool Description ──
-
-function shortPath(p) {
-    if (!p) return '';
-    const cwd = process.cwd();
-    return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
-}
-
-function toolSummary(toolName, args) {
-    switch (toolName) {
-        case 'shell':
-            return args.command || '(empty)';
-        case 'write_file':
-            return shortPath(args.path || args.file_path || '');
-        case 'write_project': {
-            const files = args.files || [];
-            if (files.length === 0) return 'batch write';
-            return files.map(f => shortPath(f.path || f.file_path || '')).join(', ');
-        }
-        case 'edit_file': {
-            const fp = shortPath(args.path || args.file_path || '');
-            const search = (args.search || '').slice(0, 30);
-            return search ? `${fp} "${search}..."` : fp;
-        }
-        case 'delete_file':
-            return shortPath(args.path || args.file_path || '');
-        case 'read_file':
-        case 'read_files':
-            return shortPath(args.file_path || args.path || (args.file_paths || [])[0] || '');
-        case 'search_code':
-            return `"${args.query || args.pattern || ''}"`;
-        case 'list_files':
-            return args.pattern || args.path || '';
-        default:
-            return Object.values(args || {}).filter(v => typeof v === 'string').join(', ').slice(0, 50) || '';
-    }
-}
-
 // ── Approval Manager ──
 
 export class ApprovalManager {
@@ -138,7 +100,7 @@ export class ApprovalManager {
         return `${DIM}ask${RST}`;
     }
 
-    async check(toolName, args, requireApproval = false) {
+    async check(toolName, args, requireApproval = false, context = {}) {
         if (this.planMode && WRITE_TOOLS.has(toolName)) {
             return { approved: false, reason: `Blocked by plan mode: ${toolName}` };
         }
@@ -157,11 +119,11 @@ export class ApprovalManager {
                 return { approved: true };
             }
             if (FORCE_APPROVAL_SHELL.some(p => p.test(args.command || ''))) {
-                return this._prompt(toolName, args);
+                return this._prompt(toolName, args, context);
             }
         }
         if (NEVER_AUTO_APPROVE.has(toolName)) {
-            return this._prompt(toolName, args);
+            return this._prompt(toolName, args, context);
         }
         if (this.approveAll) {
             this.history.push({ tool: toolName, decision: 'auto', time: Date.now() });
@@ -171,20 +133,27 @@ export class ApprovalManager {
             this.history.push({ tool: toolName, decision: 'type-auto', time: Date.now() });
             return { approved: true };
         }
-        return this._prompt(toolName, args);
+        return this._prompt(toolName, args, context);
     }
 
-    async _prompt(toolName, args) {
+    async _prompt(toolName, args, context = {}) {
         const baseRisk = RISK_LEVELS[toolName] || 'medium';
-        const risk = toolName === 'shell' ? assessShellRisk(args.command) : baseRisk;
-        const summary = toolSummary(toolName, args);
+        const assessedRisk = toolName === 'shell' ? assessShellRisk(args.command) : baseRisk;
+        const risk = context.risk || assessedRisk;
+        const label = toolDisplayLabel(toolName);
+        const summary = toolDisplaySummary(toolName, args);
         const isDestructive = risk === 'high';
 
-        // ── Prompt line ──
+        write(`\n  ${isDestructive ? `${YELLOW}⚠${RST}` : `${CYAN}?${RST}`}  ${BOLD}Approval required${RST}\n`);
+        write(`  ${GRAY}Action${RST}  ${WHITE}${label}${RST}\n`);
+        if (summary) write(`  ${GRAY}Target${RST}  ${WHITE}${summary.slice(0, 160)}${RST}\n`);
+        write(`  ${GRAY}Risk${RST}    ${isDestructive ? YELLOW : CYAN}${risk}${RST}\n`);
+        if (context.reason) write(`  ${GRAY}Reason${RST}  ${DIM}${String(context.reason).slice(0, 160)}${RST}\n`);
+
         if (isDestructive) {
-            write(`  ${YELLOW}⚠${RST}  ${DIM}Allow?${RST} ${WHITE}[y]${RST} yes  ${WHITE}[n]${RST} no  ${WHITE}[d]${RST} details\n`);
+            write(`  ${DIM}Choose${RST}  ${WHITE}[y]${RST} allow once  ${WHITE}[n]${RST} deny  ${WHITE}[d]${RST} details\n`);
         } else {
-            write(`  ${DIM}?${RST}  ${DIM}Allow?${RST} ${WHITE}[y]${RST} yes  ${WHITE}[n]${RST} no  ${WHITE}[a]${RST} always  ${WHITE}[t]${RST} type  ${WHITE}[d]${RST} details\n`);
+            write(`  ${DIM}Choose${RST}  ${WHITE}[y]${RST} once  ${WHITE}[n]${RST} deny  ${WHITE}[t]${RST} this action  ${WHITE}[a]${RST} all  ${WHITE}[d]${RST} details\n`);
         }
 
         const key = await this._readKey();
@@ -206,7 +175,7 @@ export class ApprovalManager {
 
             case 'a':
             case 'A':
-                if (isDestructive) return this._prompt(toolName, args);
+                if (isDestructive) return this._prompt(toolName, args, context);
                 this.approveAll = true;
                 write(`  ${GREEN}✓✓${RST} ${DIM}allow-all activated${RST}\n\n`);
                 this.history.push({ tool: toolName, decision: 'approve-all', time: Date.now() });
@@ -214,7 +183,7 @@ export class ApprovalManager {
 
             case 't':
             case 'T':
-                if (isDestructive) return this._prompt(toolName, args);
+                if (isDestructive) return this._prompt(toolName, args, context);
                 this.approvedToolTypes.add(toolName);
                 write(`  ${GREEN}✓${RST}  ${DIM}always allow ${toolName}${RST}\n\n`);
                 this.history.push({ tool: toolName, decision: 'type-approve', time: Date.now() });
@@ -223,10 +192,10 @@ export class ApprovalManager {
             case 'd':
             case 'D':
                 write(`\n${DIM}${JSON.stringify(args, null, 2)}${RST}\n\n`);
-                return this._prompt(toolName, args);
+                return this._prompt(toolName, args, context);
 
             default:
-                return this._prompt(toolName, args);
+                return this._prompt(toolName, args, context);
         }
     }
 

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/paths.mjs

@@ -22,7 +22,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import * as crypto from 'node:crypto';
 
-const KEPLER_HOME = process.env.KEPLER_HOME || process.env.ORCA_HOME || path.join(os.homedir(), '.kepler');
+const KEPLER_HOME = process.env.KEPLER_HOME || path.join(os.homedir(), '.kepler');
 
 /**
  * Hash a project path to a short directory name.

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

package/src/core/stream-client.mjs

@@ -290,7 +290,12 @@ export class TarangStreamClient {
         }
 
         // Use the same ApprovalManager for consistent UX
-        const { approved, reason: denyReason } = await this.approval.check(tool, args || {}, true);
+        const { approved, reason: denyReason } = await this.approval.check(
+            tool,
+            args || {},
+            true,
+            { risk, reason },
+        );
 
         // Map ApprovalManager decision to framework scope
         let decision, scope;