@axplusb/kepler 0.0.1 → 1.0.1

package/src/core/checkpoints.mjs

@@ -0,0 +1,142 @@
+/**
+ * File Checkpointing — save and restore file state before edits.
+ *
+ * Before any file edit, a checkpoint is created containing the
+ * original file content. The /undo command restores the last checkpoint.
+ * Checkpoints are stored in ~/.kepler/projects/{hash}/checkpoints/
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { checkpointsDir } from './paths.mjs';
+
+export class CheckpointManager {
+    /**
+     * @param {string} [baseDir] - project root directory
+     */
+    constructor(baseDir = process.cwd()) {
+        this.baseDir = baseDir;
+        this.checkpointDir = checkpointsDir(baseDir);
+        this.history = []; // Stack of checkpoint IDs
+        this.maxCheckpoints = 50;
+    }
+
+    /**
+     * Create a checkpoint for a file before editing.
+     * @param {string} filePath - absolute path to the file
+     * @returns {string|null} checkpoint ID, or null if file doesn't exist
+     */
+    save(filePath) {
+        const absPath = path.resolve(filePath);
+
+        try {
+            const content = fs.readFileSync(absPath, 'utf-8');
+            const id = `ckpt_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+
+            fs.mkdirSync(this.checkpointDir, { recursive: true });
+
+            const checkpoint = {
+                id,
+                filePath: absPath,
+                relativePath: path.relative(this.baseDir, absPath),
+                content,
+                timestamp: new Date().toISOString(),
+                size: content.length,
+            };
+
+            const ckptFile = path.join(this.checkpointDir, `${id}.json`);
+            fs.writeFileSync(ckptFile, JSON.stringify(checkpoint));
+
+            this.history.push(id);
+
+            // Trim old checkpoints
+            while (this.history.length > this.maxCheckpoints) {
+                const old = this.history.shift();
+                try {
+                    fs.unlinkSync(path.join(this.checkpointDir, `${old}.json`));
+                } catch {
+                    // Already deleted
+                }
+            }
+
+            return id;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Restore the most recent checkpoint (undo last edit).
+     * @returns {{ filePath: string, restored: boolean, id: string }|null}
+     */
+    undo() {
+        if (this.history.length === 0) return null;
+
+        const id = this.history.pop();
+        const ckptFile = path.join(this.checkpointDir, `${id}.json`);
+
+        try {
+            const raw = fs.readFileSync(ckptFile, 'utf-8');
+            const checkpoint = JSON.parse(raw);
+
+            fs.writeFileSync(checkpoint.filePath, checkpoint.content);
+            fs.unlinkSync(ckptFile);
+
+            return {
+                id: checkpoint.id,
+                filePath: checkpoint.filePath,
+                restored: true,
+            };
+        } catch (err) {
+            return { id, filePath: null, restored: false, error: err.message };
+        }
+    }
+
+    /**
+     * List recent checkpoints.
+     * @param {number} [limit=10]
+     * @returns {Array}
+     */
+    list(limit = 10) {
+        const result = [];
+        const ids = this.history.slice(-limit).reverse();
+
+        for (const id of ids) {
+            try {
+                const raw = fs.readFileSync(
+                    path.join(this.checkpointDir, `${id}.json`),
+                    'utf-8'
+                );
+                const ckpt = JSON.parse(raw);
+                result.push({
+                    id: ckpt.id,
+                    file: ckpt.relativePath,
+                    timestamp: ckpt.timestamp,
+                    size: ckpt.size,
+                });
+            } catch {
+                result.push({ id, file: '?', timestamp: '?', size: 0 });
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Clear all checkpoints.
+     */
+    clear() {
+        this.history.length = 0;
+        try {
+            const entries = fs.readdirSync(this.checkpointDir);
+            for (const entry of entries) {
+                if (entry.startsWith('ckpt_') && entry.endsWith('.json')) {
+                    fs.unlinkSync(path.join(this.checkpointDir, entry));
+                }
+            }
+        } catch {
+            // Directory doesn't exist
+        }
+    }
+}

package/src/core/context-manager.mjs

@@ -0,0 +1,198 @@
+/**
+ * Context Manager — tracks token usage and compacts conversation history.
+ *
+ * Features:
+ * - Proper token estimation (4 chars ~ 1 token for English)
+ * - Micro-compaction (remove stale tool results older than 5 turns)
+ * - Keep system prompt and recent 3 turns intact during compaction
+ * - Track pre/post compaction token counts
+ */
+
+const DEFAULT_MAX_TOKENS = 180000; // ~200k model limit with buffer
+const COMPACT_THRESHOLD = 0.80;
+const CHARS_PER_TOKEN = 4; // rough estimate for English text
+const STALE_TOOL_RESULT_TURNS = 5; // tool results older than this are micro-compacted
+
+export class ContextManager {
+    /**
+     * @param {number} maxTokens - Maximum tokens for context window
+     */
+    constructor(maxTokens = DEFAULT_MAX_TOKENS) {
+        this.maxTokens = maxTokens;
+        this.threshold = COMPACT_THRESHOLD;
+        this.compactionCount = 0;
+        this.lastPreCompactTokens = 0;
+        this.lastPostCompactTokens = 0;
+    }
+
+    /**
+     * Estimate token count for a message array.
+     * Uses character-based heuristic (no external tokenizer dependency).
+     * @param {Array} messages - conversation messages
+     * @returns {number} estimated token count
+     */
+    getTokenCount(messages) {
+        let chars = 0;
+        for (const msg of messages) {
+            // Role overhead (~4 tokens)
+            chars += 16;
+
+            if (typeof msg.content === 'string') {
+                chars += msg.content.length;
+            } else if (Array.isArray(msg.content)) {
+                for (const block of msg.content) {
+                    if (block.type === 'text') chars += (block.text || '').length;
+                    else if (block.type === 'tool_result') chars += (block.content || '').length;
+                    else if (block.type === 'tool_use') chars += JSON.stringify(block.input || {}).length + 20;
+                    else if (block.type === 'thinking') chars += (block.thinking || '').length;
+                    else chars += JSON.stringify(block).length;
+                }
+            }
+        }
+        return Math.ceil(chars / CHARS_PER_TOKEN);
+    }
+
+    /**
+     * Check if compaction is needed.
+     * @param {Array} messages - current conversation messages
+     * @returns {boolean}
+     */
+    shouldCompact(messages) {
+        const tokenCount = this.getTokenCount(messages);
+        return tokenCount >= this.maxTokens * this.threshold;
+    }
+
+    /**
+     * Micro-compact: remove verbose tool results from messages older than N turns.
+     * Keeps the tool call reference but truncates result content.
+     * @param {Array} messages
+     * @param {number} recentTurns - number of recent user/assistant pairs to preserve
+     * @returns {Array}
+     */
+    microCompact(messages, recentTurns = STALE_TOOL_RESULT_TURNS) {
+        // Count turns (each user message is roughly one turn)
+        let turnCount = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === 'user') turnCount++;
+        }
+
+        if (turnCount <= recentTurns) return messages;
+
+        // Mark the boundary: keep last recentTurns user messages intact
+        let usersSeen = 0;
+        let boundary = messages.length;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === 'user') {
+                usersSeen++;
+                if (usersSeen >= recentTurns) {
+                    boundary = i;
+                    break;
+                }
+            }
+        }
+
+        // Truncate tool results before the boundary
+        const result = messages.map((msg, idx) => {
+            if (idx >= boundary) return msg;
+            if (!Array.isArray(msg.content)) return msg;
+
+            const newContent = msg.content.map(block => {
+                if (block.type === 'tool_result' && typeof block.content === 'string' && block.content.length > 200) {
+                    return {
+                        ...block,
+                        content: block.content.slice(0, 100) + '...[truncated]',
+                    };
+                }
+                return block;
+            });
+
+            return { ...msg, content: newContent };
+        });
+
+        return result;
+    }
+
+    /**
+     * Compact messages by summarizing older history.
+     * Keeps the most recent N messages intact and replaces older ones
+     * with a summary message.
+     *
+     * @param {Array} messages - current conversation messages
+     * @param {number} keepRecent - number of recent messages to preserve (default 6 = ~3 turns)
+     * @returns {Array} compacted message array
+     */
+    compact(messages, keepRecent = 6) {
+        if (messages.length <= keepRecent) return messages;
+
+        this.lastPreCompactTokens = this.getTokenCount(messages);
+        this.compactionCount++;
+
+        // First try micro-compaction
+        let working = this.microCompact(messages);
+        if (!this.shouldCompact(working)) {
+            this.lastPostCompactTokens = this.getTokenCount(working);
+            return working;
+        }
+
+        // Full compaction
+        const oldMessages = messages.slice(0, -keepRecent);
+        const recentMessages = messages.slice(-keepRecent);
+
+        // Build a summary of old messages
+        const summaryParts = [];
+        for (const msg of oldMessages) {
+            const role = msg.role;
+            let text = '';
+            if (typeof msg.content === 'string') {
+                text = msg.content.slice(0, 200);
+            } else if (Array.isArray(msg.content)) {
+                text = msg.content
+                    .map(b => {
+                        if (b.type === 'text') return b.text?.slice(0, 100);
+                        if (b.type === 'tool_use') return `[tool:${b.name}]`;
+                        if (b.type === 'tool_result') return `[result:${String(b.content).slice(0, 80)}]`;
+                        return `[${b.type}]`;
+                    })
+                    .filter(Boolean)
+                    .join(' ');
+            }
+            if (text) summaryParts.push(`${role}: ${text}`);
+        }
+
+        const summary = {
+            role: 'user',
+            content: `[Context compacted — summary of ${oldMessages.length} earlier messages]\n` +
+                summaryParts.join('\n').slice(0, 2000),
+        };
+
+        const compacted = [summary, ...recentMessages];
+        this.lastPostCompactTokens = this.getTokenCount(compacted);
+        return compacted;
+    }
+
+    /**
+     * Add a message and auto-compact if needed.
+     * @param {Array} messages - mutable message array
+     * @param {object} msg - new message to add
+     * @returns {Array} possibly compacted array with new message
+     */
+    addMessage(messages, msg) {
+        messages.push(msg);
+        if (this.shouldCompact(messages)) {
+            return this.compact(messages);
+        }
+        return messages;
+    }
+
+    /**
+     * Get compaction statistics.
+     * @returns {object}
+     */
+    getStats() {
+        return {
+            compactionCount: this.compactionCount,
+            lastPreCompactTokens: this.lastPreCompactTokens,
+            lastPostCompactTokens: this.lastPostCompactTokens,
+        };
+    }
+}

package/src/core/headless.mjs

@@ -0,0 +1,168 @@
+/**
+ * Headless Runner — non-interactive mode for benchmarks and automation.
+ *
+ * No REPL, no spinners, no approval prompts. Auto-approves all tools.
+ * Outputs structured JSONL to stdout for machine consumption.
+ * stderr gets minimal progress (optional with --verbose).
+ *
+ * Usage:
+ *   kepler --headless "Fix the bug in auth.py"
+ *   kepler --headless --timeout 300 --max-cost 2.00 "Refactor the login flow"
+ *   kepler --headless --model deepseek/deepseek-chat-v3-0324 "Add tests"
+ */
+
+import { TarangStreamClient } from './stream-client.mjs';
+import { createToolExecutor } from './tool-executor.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.
+ * @param {object} opts
+ * @param {string} opts.instruction - the prompt to send
+ * @param {string} [opts.model] - model override
+ * @param {number} [opts.timeout] - max seconds (default: 300)
+ * @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 }) {
+    const startTime = Date.now();
+
+    const log = (msg) => {
+        if (verbose) process.stderr.write(`[headless] ${msg}\n`);
+    };
+
+    const emit = (obj) => {
+        process.stdout.write(JSON.stringify(obj) + '\n');
+    };
+
+    // ── Auth ──
+    const auth = new TarangAuth();
+    const creds = auth.loadCredentials();
+    if (!creds.token) {
+        emit({ type: 'error', error: 'Not logged in. Run: kepler login' });
+        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 });
+
+    // 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,
+    });
+
+    // ── Timeout ──
+    const timeoutMs = timeout * 1000;
+    const timeoutTimer = setTimeout(() => {
+        emit({ type: 'timeout', duration_s: timeout });
+        log(`Timeout after ${timeout}s`);
+        process.exit(2);
+    }, timeoutMs);
+
+    // ── 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;
+    if (model) execContext.model_override = model;
+
+    let toolCount = 0;
+    let finalContent = '';
+    let totalCost = 0;
+
+    try {
+        for await (const event of client.execute(instruction, execContext)) {
+            const { type, data } = event;
+
+            if (type === 'tool_call' || type === 'tool_request') {
+                toolCount++;
+                const toolName = data?.tool || 'unknown';
+                const args = data?.args || {};
+                emit({ type: 'tool_call', tool: toolName, args, approved: true });
+                log(`Tool: ${toolName}`);
+            }
+
+            if (type === 'tool_result' || type === 'tool_done') {
+                const success = data?.success !== false;
+                const duration = data?.duration_s || 0;
+                emit({ type: 'tool_result', tool: data?.tool || '', success, duration_ms: Math.round(duration * 1000) });
+            }
+
+            if (type === 'content') {
+                finalContent = data?.text || '';
+            }
+
+            if (type === 'content_partial') {
+                const text = data?.text || '';
+                if (text) finalContent = text;
+            }
+
+            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 (type === 'error') {
+                emit({ type: 'error', error: data?.message || 'Unknown error' });
+            }
+
+            // ── Cost guard ──
+            if (maxCost && totalCost > maxCost) {
+                emit({ type: 'cost_exceeded', cost_usd: totalCost, max_cost: maxCost });
+                log(`Cost exceeded: $${totalCost.toFixed(3)} > $${maxCost}`);
+                break;
+            }
+        }
+    } catch (err) {
+        emit({ type: 'error', error: err.message });
+    }
+
+    clearTimeout(timeoutTimer);
+
+    const durationS = (Date.now() - startTime) / 1000;
+
+    emit({
+        type: 'complete',
+        tools: toolCount,
+        duration_s: Math.round(durationS * 10) / 10,
+        cost_usd: totalCost,
+        model: model || 'default',
+        content_length: finalContent.length,
+    });
+
+    log(`Done: ${toolCount} tools, ${durationS.toFixed(1)}s, $${totalCost.toFixed(3)}`);
+
+    // Write final content to stderr so it's human-readable (stdout is JSONL)
+    if (verbose && finalContent) {
+        process.stderr.write(`\n--- Response ---\n${finalContent.slice(0, 2000)}\n`);
+    }
+
+    process.exit(0);
+}

package/src/core/hooks-manager.mjs

@@ -0,0 +1,87 @@
+/**
+ * Hooks Manager — T22: PreToolUse/PostToolUse hooks from config.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+import { projectHooksPath, globalHooksPath } from './paths.mjs';
+
+export class HooksManager {
+    constructor(projectDir = process.cwd()) {
+        this.projectHooksPath = projectHooksPath(projectDir);
+        this.globalHooksPath = globalHooksPath();
+        this.hooks = this._loadHooks();
+        this.firedHooks = [];
+    }
+
+    _loadHooks() {
+        const hooks = { PreToolUse: [], PostToolUse: [] };
+
+        // Global hooks (lower priority)
+        try {
+            if (fs.existsSync(this.globalHooksPath)) {
+                const global = JSON.parse(fs.readFileSync(this.globalHooksPath, 'utf-8'));
+                if (global.PreToolUse) hooks.PreToolUse.push(...global.PreToolUse);
+                if (global.PostToolUse) hooks.PostToolUse.push(...global.PostToolUse);
+            }
+        } catch { /* skip corrupt */ }
+
+        // Project hooks (higher priority, appended after global)
+        try {
+            if (fs.existsSync(this.projectHooksPath)) {
+                const project = JSON.parse(fs.readFileSync(this.projectHooksPath, 'utf-8'));
+                if (project.PreToolUse) hooks.PreToolUse.push(...project.PreToolUse);
+                if (project.PostToolUse) hooks.PostToolUse.push(...project.PostToolUse);
+            }
+        } catch { /* skip corrupt */ }
+
+        return hooks;
+    }
+
+    /** Run PreToolUse hooks. Returns { allowed, message }. */
+    runPreToolUse(toolName, toolInput) {
+        return this._runHooks('PreToolUse', toolName, toolInput);
+    }
+
+    /** Run PostToolUse hooks. Returns { success }. */
+    runPostToolUse(toolName, toolInput, result) {
+        return this._runHooks('PostToolUse', toolName, toolInput, result);
+    }
+
+    _runHooks(event, toolName, toolInput, result = null) {
+        const hooks = (this.hooks[event] || []).filter(h => !h.tool || h.tool === toolName);
+        for (const hook of hooks) {
+            try {
+                const env = {
+                    ...process.env,
+                    HOOK_EVENT: event,
+                    TOOL_NAME: toolName,
+                    TOOL_INPUT: JSON.stringify(toolInput),
+                    FILE_PATH: toolInput?.path || toolInput?.file_path || '',
+                };
+                if (result) env.TOOL_RESULT = JSON.stringify(result);
+
+                execSync(hook.command, { env, stdio: 'pipe', timeout: 10_000 });
+                this.firedHooks.push({ event, tool: toolName, command: hook.command, success: true });
+            } catch (err) {
+                this.firedHooks.push({ event, tool: toolName, command: hook.command, success: false });
+                if (event === 'PreToolUse') {
+                    return { allowed: false, message: `Hook blocked ${toolName}: ${err.message}` };
+                }
+            }
+        }
+        return { allowed: true, success: true };
+    }
+
+    /** List configured hooks. */
+    listHooks() { return this.hooks; }
+
+    /** List hooks that fired this session. */
+    getFiredHooks() { return this.firedHooks; }
+
+    /** Check if any hooks are configured. */
+    hasHooks() {
+        return (this.hooks.PreToolUse.length + this.hooks.PostToolUse.length) > 0;
+    }
+}