@axplusb/kepler 0.0.1 → 1.0.1

package/src/core/approval.mjs

@@ -0,0 +1,273 @@
+/**
+ * Approval Flow — permission prompts for tool execution.
+ *
+ * Modeled after Claude Code's visual pattern:
+ *   ⏺ Tool(args)          ← tool header
+ *   ⎿ Allow? [y/n/a/t]    ← inline prompt
+ *   ⎿ ✓ allowed            ← result
+ *
+ * Write tools require approval. Read tools auto-approve.
+ * Shell commands are risk-assessed (safe/medium/high).
+ */
+
+import * as path from 'node:path';
+
+// ── Tool Classification ──
+
+const WRITE_TOOLS = new Set([
+    'shell', 'write_file', 'write_project', 'edit_file', 'delete_file',
+    'validate_build', 'lint_check',
+]);
+
+const NEVER_AUTO_APPROVE = new Set(['delete_file']);
+
+const FORCE_APPROVAL_SHELL = [
+    /\brm\s/,
+    /\bunlink\s/,
+    /\brmdir\s/,
+    /\bgit\s+clean/,
+    /\bgit\s+reset/,
+    /\bgit\s+push.*--force/,
+];
+
+const RISK_LEVELS = {
+    read_file: 'none', read_files: 'none', search_code: 'none',
+    search_files: 'none', list_files: 'none', get_file_info: 'none',
+    validate_file: 'none', validate_structure: 'none',
+    write_file: 'low', write_project: 'low', edit_file: 'low',
+    lint_check: 'low', validate_build: 'medium',
+    shell: 'medium',
+    delete_file: 'high',
+};
+
+function assessShellRisk(command) {
+    if (!command) return 'medium';
+    if (/rm\s+-r/i.test(command)) return 'high';
+    if (/git\s+(push|reset|clean|checkout\s+\.)/i.test(command)) return 'high';
+    if (/drop\s+(table|database)/i.test(command)) return 'high';
+    if (/sudo\s/i.test(command)) return 'high';
+    if (/^(ls|cat|head|tail|less|more|wc|file|stat|tree|find|grep|rg|ag|echo|printf|pwd|whoami|date|which|type|env|printenv|uname|hostname|id|df|du|uptime|free|top|ps|lsof)/i.test(command)) return 'low';
+    if (/^git\s+(status|log|diff|show|branch|tag|remote|stash\s+list|blame|shortlog|describe|rev-parse|ls-files|ls-tree)/i.test(command)) return 'low';
+    if (/^(npm\s+(test|run|list|ls|view|info|outdated|audit)|node\s+--check|python3?\s+-m\s+py_compile|cargo\s+(check|test|clippy))/i.test(command)) return 'low';
+    return 'medium';
+}
+
+// ── ANSI helpers ──
+
+const RST = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const GRAY = '\x1b[90m';
+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 {
+    constructor({ autoApprove = false, planMode = false } = {}) {
+        this.autoApprove = autoApprove;
+        this.planMode = planMode;
+        this.approveAll = false;
+        this.approvedToolTypes = new Set();
+        this.history = [];
+        this._rl = null;
+    }
+
+    setReadline(rl) { this._rl = rl; }
+
+    setExecutionHooks({ onPause, onResume } = {}) {
+        this._execPause = onPause || null;
+        this._execResume = onResume || null;
+    }
+
+    revoke() {
+        const wasActive = this.approveAll || this.approvedToolTypes.size > 0;
+        this.approveAll = false;
+        this.approvedToolTypes.clear();
+        return wasActive;
+    }
+
+    getModeLabel() {
+        if (this.approveAll) return `${GREEN}allow-all${RST}`;
+        if (this.approvedToolTypes.size > 0) {
+            return `${CYAN}auto: ${[...this.approvedToolTypes].join(', ')}${RST}`;
+        }
+        return `${DIM}ask${RST}`;
+    }
+
+    async check(toolName, args, requireApproval = false) {
+        if (this.planMode && WRITE_TOOLS.has(toolName)) {
+            return { approved: false, reason: `Blocked by plan mode: ${toolName}` };
+        }
+        // Auto-approve everything in headless/autoApprove mode (no TTY prompts)
+        if (this.autoApprove) {
+            this.history.push({ tool: toolName, decision: 'auto', time: Date.now() });
+            return { approved: true };
+        }
+        if (!WRITE_TOOLS.has(toolName) && !requireApproval) {
+            return { approved: true };
+        }
+        if (toolName === 'shell') {
+            const risk = assessShellRisk(args.command);
+            if (risk === 'low') {
+                this.history.push({ tool: toolName, decision: 'auto-safe', time: Date.now() });
+                return { approved: true };
+            }
+            if (FORCE_APPROVAL_SHELL.some(p => p.test(args.command || ''))) {
+                return this._prompt(toolName, args);
+            }
+        }
+        if (NEVER_AUTO_APPROVE.has(toolName)) {
+            return this._prompt(toolName, args);
+        }
+        if (this.approveAll) {
+            this.history.push({ tool: toolName, decision: 'auto', time: Date.now() });
+            return { approved: true };
+        }
+        if (this.approvedToolTypes.has(toolName)) {
+            this.history.push({ tool: toolName, decision: 'type-auto', time: Date.now() });
+            return { approved: true };
+        }
+        return this._prompt(toolName, args);
+    }
+
+    async _prompt(toolName, args) {
+        const baseRisk = RISK_LEVELS[toolName] || 'medium';
+        const risk = toolName === 'shell' ? assessShellRisk(args.command) : baseRisk;
+        const summary = toolSummary(toolName, args);
+        const isDestructive = risk === 'high';
+
+        // ── Prompt line ──
+        if (isDestructive) {
+            write(`  ${YELLOW}⚠${RST}  ${DIM}Allow?${RST} ${WHITE}[y]${RST} yes  ${WHITE}[n]${RST} no  ${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`);
+        }
+
+        const key = await this._readKey();
+
+        switch (key) {
+            case 'y':
+            case 'Y':
+            case 'return':
+                write(`  ${GREEN}✓${RST}  ${DIM}${toolName}${RST} ${DIM}${summary.slice(0, 60)}${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'yes', time: Date.now() });
+                return { approved: true };
+
+            case 'n':
+            case 'N':
+            case 'escape':
+                write(`  ${RED}✗${RST}  ${DIM}denied${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'no', time: Date.now() });
+                return { approved: false, reason: 'User denied' };
+
+            case 'a':
+            case 'A':
+                if (isDestructive) return this._prompt(toolName, args);
+                this.approveAll = true;
+                write(`  ${GREEN}✓✓${RST} ${DIM}allow-all activated${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'approve-all', time: Date.now() });
+                return { approved: true };
+
+            case 't':
+            case 'T':
+                if (isDestructive) return this._prompt(toolName, args);
+                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() });
+                return { approved: true };
+
+            case 'd':
+            case 'D':
+                write(`\n${DIM}${JSON.stringify(args, null, 2)}${RST}\n\n`);
+                return this._prompt(toolName, args);
+
+            default:
+                return this._prompt(toolName, args);
+        }
+    }
+
+    _readKey() {
+        return new Promise((resolve) => {
+            if (!process.stdin.isTTY) {
+                resolve('return');
+                return;
+            }
+
+            if (this._execPause) this._execPause();
+            if (this._rl) this._rl.pause();
+
+            const wasRaw = process.stdin.isRaw;
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.once('data', (data) => {
+                process.stdin.setRawMode(wasRaw || false);
+                if (this._rl) this._rl.resume();
+                if (this._execResume) this._execResume();
+
+                const bytes = [...data];
+                const str = data.toString();
+
+                if (bytes[0] === 0x03) process.exit(0);
+                if (bytes[0] === 0x1b) { resolve('escape'); return; }
+                if (str === '\r' || str === '\n') { resolve('return'); return; }
+                resolve(str);
+            });
+        });
+    }
+
+    getSummary() {
+        const approved = this.history.filter(h => h.decision !== 'no').length;
+        const denied = this.history.filter(h => h.decision === 'no').length;
+        return {
+            total: this.history.length,
+            approved,
+            denied,
+            autoApproveAll: this.approveAll,
+            autoApprovedTypes: [...this.approvedToolTypes],
+        };
+    }
+}

package/src/core/backend-url.mjs

@@ -0,0 +1,57 @@
+/**
+ * Backend URL resolver — auto-detects the correct backend based on environment.
+ *
+ * Priority:
+ *   1. TARANG_BACKEND_URL env var (explicit override, for dev/admin testing)
+ *   2. TARANG_ENV or NODE_ENV → mapped to known URLs
+ *   3. Default: production
+ */
+
+const BACKEND_URLS = {
+    local:       'http://127.0.0.1:8000',
+    development: 'https://tarang-backend-development.up.railway.app',
+    production:  'https://tarang-backend-intl-web-app-production.up.railway.app',
+};
+
+// Aliases
+BACKEND_URLS.dev = BACKEND_URLS.development;
+BACKEND_URLS.prod = BACKEND_URLS.production;
+
+const WEB_URLS = {
+    local:       'http://localhost:3000',
+    development: 'https://devtarang.ai',
+    production:  'https://devtarang.ai',
+};
+WEB_URLS.dev = WEB_URLS.development;
+WEB_URLS.prod = WEB_URLS.production;
+
+/**
+ * Resolve the web dashboard URL from environment.
+ * @returns {string}
+ */
+export function resolveWebUrl() {
+    if (process.env.TARANG_WEB_URL) {
+        return process.env.TARANG_WEB_URL.replace(/\/$/, '');
+    }
+    const env = (process.env.TARANG_ENV || process.env.NODE_ENV || 'production').toLowerCase();
+    return WEB_URLS[env] || WEB_URLS.production;
+}
+
+/**
+ * Resolve the backend URL from environment.
+ * @returns {string}
+ */
+export function resolveBackendUrl() {
+    // 1. Explicit env var override (for dev/admin testing)
+    if (process.env.TARANG_BACKEND_URL) {
+        return process.env.TARANG_BACKEND_URL.replace(/\/$/, '');
+    }
+
+    // 2. Environment-based detection
+    const env = (process.env.TARANG_ENV || process.env.NODE_ENV || 'production').toLowerCase();
+    const url = BACKEND_URLS[env];
+    if (url) return url;
+
+    // 3. Fallback to production
+    return BACKEND_URLS.production;
+}

package/src/core/cache.mjs

@@ -0,0 +1,105 @@
+/**
+ * Prompt Caching — implements cache_control for Anthropic API.
+ *
+ * Adds cache_control: { type: "ephemeral" } to system prompt blocks
+ * that are static (like CLAUDE.md content), allowing the API to
+ * cache them and reduce input token costs.
+ *
+ * Tracks cache_read_tokens and cache_creation_tokens.
+ */
+
+export class PromptCache {
+    constructor() {
+        this.stats = {
+            cacheCreationTokens: 0,
+            cacheReadTokens: 0,
+            totalRequests: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+        };
+    }
+
+    /**
+     * Apply cache control to system prompt blocks.
+     * Static content (CLAUDE.md, tool definitions) gets ephemeral cache markers.
+     *
+     * @param {string|Array} systemPrompt - system prompt content
+     * @returns {Array} system prompt blocks with cache_control
+     */
+    applyCacheControl(systemPrompt) {
+        if (typeof systemPrompt === 'string') {
+            return [
+                {
+                    type: 'text',
+                    text: systemPrompt,
+                    cache_control: { type: 'ephemeral' },
+                },
+            ];
+        }
+
+        if (Array.isArray(systemPrompt)) {
+            return systemPrompt.map((block, i) => {
+                if (typeof block === 'string') {
+                    return {
+                        type: 'text',
+                        text: block,
+                        cache_control: { type: 'ephemeral' },
+                    };
+                }
+                // Only cache the first block (usually CLAUDE.md) and tool defs
+                if (i === 0 || block.cacheable) {
+                    return { ...block, cache_control: { type: 'ephemeral' } };
+                }
+                return block;
+            });
+        }
+
+        return systemPrompt;
+    }
+
+    /**
+     * Update cache stats from API response usage data.
+     * @param {object} usage - API response usage object
+     */
+    updateStats(usage) {
+        this.stats.totalRequests++;
+        if (usage) {
+            if (usage.cache_creation_input_tokens) {
+                this.stats.cacheCreationTokens += usage.cache_creation_input_tokens;
+                this.stats.cacheMisses++;
+            }
+            if (usage.cache_read_input_tokens) {
+                this.stats.cacheReadTokens += usage.cache_read_input_tokens;
+                this.stats.cacheHits++;
+            }
+        }
+    }
+
+    /**
+     * Get cache efficiency stats.
+     */
+    getStats() {
+        const hitRate = this.stats.totalRequests > 0
+            ? ((this.stats.cacheHits / this.stats.totalRequests) * 100).toFixed(1)
+            : '0.0';
+
+        return {
+            ...this.stats,
+            hitRate: `${hitRate}%`,
+            tokensSaved: this.stats.cacheReadTokens,
+        };
+    }
+
+    /**
+     * Reset stats.
+     */
+    reset() {
+        this.stats = {
+            cacheCreationTokens: 0,
+            cacheReadTokens: 0,
+            totalRequests: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+        };
+    }
+}

package/src/core/callback-client.mjs

@@ -0,0 +1,149 @@
+/**
+ * Callback Client — POST tool results back to Tarang backend.
+ * Implements retry with backoff: 2 retries, 500ms delay.
+ * 4xx: no retry. 5xx/network: retry.
+ */
+
+const MAX_RETRIES = 2;
+const RETRY_DELAY_MS = 500;
+const TIMEOUT_MS = 10_000;
+
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Send a tool execution result to the backend.
+ * @param {string} baseUrl
+ * @param {string} token
+ * @param {string} taskId
+ * @param {string} callId
+ * @param {Object} result - { success, output, ... }
+ * @returns {Promise<boolean>}
+ */
+export async function sendCallback(baseUrl, token, taskId, callId, result) {
+    const url = `${baseUrl}/api/callback`;
+
+    // Clean result for the backend — strip internal CLI metadata so the LLM
+    // sees a clear, unambiguous tool result (not noisy JSON with _tool, _output_meta, etc.)
+    const cleanResult = {};
+    for (const [key, value] of Object.entries(result)) {
+        if (!key.startsWith('_')) {
+            cleanResult[key] = value;
+        }
+    }
+
+    const body = JSON.stringify({
+        task_id: taskId,
+        call_id: callId,
+        result: cleanResult,
+    });
+
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (token) headers['Authorization'] = `Bearer ${token}`;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+            const resp = await fetch(url, {
+                method: 'POST',
+                headers,
+                body,
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            if (resp.ok) return true;
+
+            // 4xx: client error, don't retry
+            if (resp.status >= 400 && resp.status < 500) {
+                return false;
+            }
+
+            // 5xx: server error, retry
+            if (attempt < MAX_RETRIES) {
+                await sleep(RETRY_DELAY_MS * (attempt + 1));
+            }
+        } catch (err) {
+            // Network error or timeout, retry
+            if (attempt < MAX_RETRIES) {
+                await sleep(RETRY_DELAY_MS * (attempt + 1));
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Send a "skipped" callback for rejected operations.
+ * @param {string} baseUrl
+ * @param {string} token
+ * @param {string} taskId
+ * @param {string} callId
+ * @param {string} message
+ * @returns {Promise<boolean>}
+ */
+export async function sendSkippedCallback(baseUrl, token, taskId, callId, message) {
+    return sendCallback(baseUrl, token, taskId, callId, {
+        skipped: true,
+        message: message || 'User rejected operation',
+        success: false,
+    });
+}
+
+/**
+ * Send an approval decision to the backend's HITL handler.
+ * Called when the framework emits approval_required and the CLI
+ * has collected the user's decision via the approval menu.
+ *
+ * @param {string} baseUrl
+ * @param {string} token
+ * @param {string} taskId
+ * @param {string} toolId  - tool_id from the approval_required event
+ * @param {string} decision - "grant" or "deny"
+ * @param {string} [scope]  - "once", "type", or "all" (for grant)
+ * @param {string} [reason] - optional reason
+ * @returns {Promise<boolean>}
+ */
+export async function sendApprovalDecision(baseUrl, token, taskId, toolId, decision, scope = 'once', reason = '') {
+    const url = `${baseUrl}/api/approval_callback`;
+
+    const body = JSON.stringify({
+        task_id: taskId,
+        tool_id: toolId,
+        decision,
+        scope,
+        reason,
+    });
+
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) headers['Authorization'] = `Bearer ${token}`;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+            const resp = await fetch(url, {
+                method: 'POST',
+                headers,
+                body,
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+            if (resp.ok) return true;
+            if (resp.status >= 400 && resp.status < 500) return false;
+            if (attempt < MAX_RETRIES) await sleep(RETRY_DELAY_MS * (attempt + 1));
+        } catch {
+            if (attempt < MAX_RETRIES) await sleep(RETRY_DELAY_MS * (attempt + 1));
+        }
+    }
+    return false;
+}