@bahulam/code 2.6.0

package/src/core/callback-client.mjs

@@ -0,0 +1,180 @@
+/**
+ * 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));
+}
+
+export function cleanCallbackResult(result = {}) {
+    // 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;
+        }
+    }
+    return cleanResult;
+}
+
+export function backendToolResultForLlm(toolName, cleanResult = {}) {
+    const rawResult = cleanCallbackResult(cleanResult);
+    if (toolName === 'get_project_overview' && !Object.hasOwn(rawResult, 'error')) {
+        return {
+            output: rawResult.output || '',
+            project_resource: rawResult.project_resource,
+            already_registered: rawResult.already_registered || false,
+        };
+    }
+    if (!Object.hasOwn(rawResult, 'error')) {
+        const outputText = rawResult.output || '';
+        if (rawResult.success && outputText) {
+            return { output: outputText };
+        }
+        return rawResult;
+    }
+    return rawResult;
+}
+
+export function llmToolResultContent(toolName, result = {}) {
+    return JSON.stringify(backendToolResultForLlm(toolName, result));
+}
+
+/**
+ * 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`;
+    const cleanResult = cleanCallbackResult(result);
+
+    const body = JSON.stringify({
+        task_id: taskId,
+        call_id: callId,
+        result: cleanResult,
+    });
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'Idempotency-Key': `${taskId}:${callId}`,
+    };
+    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',
+        'Idempotency-Key': `${taskId}:${toolId}:${decision}`,
+    };
+    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;
+}

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 ~/.bahulam/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/compact-history.mjs

@@ -0,0 +1,127 @@
+const SUMMARY_PREFIX = 'Session continuity summary after /compact:';
+
+export function parseCompactTailCount(rest = '', fallback = 8) {
+  const text = String(rest || '').trim();
+  const match = text.match(/(?:^|\s)(?:--tail=|--tail\s+)?(\d+)(?:\s|$)/);
+  const n = match ? Number(match[1]) : Number(fallback);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(2, Math.min(50, Math.floor(n)));
+}
+
+export function isCompactHistory(history = []) {
+  return typeof history?.[2]?.content === 'string'
+    && history[2].content.startsWith(SUMMARY_PREFIX);
+}
+
+export function extractCompactSummary(history = []) {
+  const content = String(history?.[2]?.content || '');
+  if (!content.startsWith(SUMMARY_PREFIX)) return '';
+  return content.slice(SUMMARY_PREFIX.length).trim();
+}
+
+export function prepareCompactHistory({
+  agentHistory = [],
+  tailCount = 8,
+  minSourceMessages = 2,
+} = {}) {
+  const history = Array.isArray(agentHistory)
+    ? agentHistory.filter(msg => msg && typeof msg.content === 'string' && msg.content.trim())
+    : [];
+  const beforeCount = history.length;
+  const retainedCount = Math.min(Math.max(2, Number(tailCount) || 8), Math.max(0, beforeCount));
+  const prefixCount = isCompactHistory(history) ? 3 : 0;
+  const sourceEnd = Math.max(prefixCount, beforeCount - retainedCount);
+  const sourceMessages = history.slice(prefixCount, sourceEnd);
+  const tail = history.slice(sourceEnd);
+
+  if (sourceMessages.length < minSourceMessages) {
+    return {
+      ok: false,
+      reason: beforeCount <= prefixCount + retainedCount
+        ? 'not enough history beyond the retained tail'
+        : 'not enough compactable messages',
+      beforeCount,
+      prefixCount,
+      sourceMessages,
+      tail,
+      retainedCount,
+    };
+  }
+
+  return {
+    ok: true,
+    beforeCount,
+    prefixCount,
+    sourceMessages,
+    tail,
+    retainedCount: tail.length,
+    previousSummary: extractCompactSummary(history),
+  };
+}
+
+export function applyCompactSummary({
+  prepared,
+  summary,
+  sessionId = '',
+  cwd = '',
+  originalRequest = '',
+  previousSourceMessageCount = 0,
+  now = new Date(),
+} = {}) {
+  if (!prepared?.ok) throw new Error(prepared?.reason || 'history is not compactable');
+  const compactSummary = String(summary || '').trim();
+  if (!compactSummary) throw new Error('summary is required');
+  const priorCount = Math.max(0, Number(previousSourceMessageCount) || 0);
+  const sourceMessageCount = priorCount + prepared.sourceMessages.length;
+  const timestamp = now instanceof Date ? now.toISOString() : String(now || new Date().toISOString());
+  const firstUser = originalRequest || firstUserMessage(prepared.sourceMessages) || firstUserMessage(prepared.tail) || '(unknown)';
+
+  const metadata = [
+    'Compact metadata.',
+    sessionId ? `Session: ${sessionId}` : '',
+    cwd ? `Project: ${cwd}` : '',
+    `Compacted at: ${timestamp}`,
+    `Covered live messages: ${sourceMessageCount}`,
+    `Retained tail messages: ${prepared.tail.length}`,
+  ].filter(Boolean).join('\n');
+
+  const agentHistory = [
+    { role: 'user', content: metadata },
+    { role: 'user', content: `Original user request from this compacted session:\n${firstUser}` },
+    { role: 'user', content: `${SUMMARY_PREFIX}\n${compactSummary}` },
+    ...prepared.tail,
+  ];
+
+  return {
+    agentHistory,
+    summary: compactSummary,
+    sourceMessageCount,
+    previousSourceMessageCount: priorCount,
+    beforeCount: prepared.beforeCount,
+    afterCount: agentHistory.length,
+    retainedCount: prepared.tail.length,
+    compactedCount: prepared.sourceMessages.length,
+  };
+}
+
+export function localCompactSummary(messages = []) {
+  const list = Array.isArray(messages) ? messages : [];
+  const userMessages = list.filter(m => m.role === 'user').map(m => String(m.content || '').trim()).filter(Boolean);
+  const assistantMessages = list.filter(m => m.role === 'assistant').map(m => String(m.content || '').trim()).filter(Boolean);
+  return [
+    'Local compact summary from live conversation context.',
+    userMessages.length ? `User requests (${userMessages.length}):` : '',
+    ...userMessages.slice(-8).map(text => `- ${truncate(text, 500)}`),
+    assistantMessages.length ? `Assistant progress (${assistantMessages.length}):` : '',
+    ...assistantMessages.slice(-8).map(text => `- ${truncate(text, 700)}`),
+  ].filter(Boolean).join('\n');
+}
+
+function firstUserMessage(messages = []) {
+  return messages.find(m => m?.role === 'user' && typeof m.content === 'string')?.content || '';
+}
+
+function truncate(text, max) {
+  const value = String(text || '').replace(/\s+/g, ' ').trim();
+  return value.length > max ? value.slice(0, max - 3) + '...' : value;
+}

package/src/core/context-envelope.mjs

@@ -0,0 +1,54 @@
+import { contextToPromptBlock } from './project-context-loader.mjs';
+
+export function buildContextEnvelope({
+  cwd = process.cwd(),
+  command = null,
+  args = [],
+  source = 'repl',
+  dryRun = false,
+  aliasesResolved = [],
+  effectivePolicy,
+  projectContext,
+  activeHints = [],
+  projectResources = [],
+  agentContext = {},
+} = {}) {
+  const policy = effectivePolicy?.policy || {};
+  const commandTimeouts = policy.commands?.timeouts || {};
+  const enabled = policy.commands?.enabled || [];
+  const activeCommand = command || null;
+  const specificTimeout = activeCommand ? commandTimeouts[`${activeCommand}Seconds`] : null;
+
+  return {
+    cwd,
+    project_resources: projectResources,
+    agent_context: agentContext,
+    project_context: {
+      loaded_files: projectContext?.loaded || [],
+      changed_files: projectContext?.changed?.map(f => ({ label: f.label, path: f.path, hash: f.hash })) || [],
+      prompt_block: contextToPromptBlock(projectContext),
+    },
+    command_context: {
+      active_command: activeCommand,
+      source,
+      args,
+      dry_run: dryRun,
+      aliases_resolved: aliasesResolved,
+      runtime_limits: {
+        command_timeout_seconds: specificTimeout || commandTimeouts.defaultSeconds || 300,
+        tool_timeout_seconds: 120,
+        approval_timeout_seconds: null,
+      },
+    },
+    effective_options: {
+      commands_enabled: enabled,
+      plan_owner: policy.planning?.owner || 'auto',
+      hitl_default_scope: policy.hitl?.defaultScope || 'once',
+      reask_after_minutes: policy.hitl?.reaskAfterMinutes ?? 30,
+      hook_timeout_seconds: policy.hooks?.timeoutSeconds ?? 5,
+    },
+    context_hints: activeHints,
+    available_skills: projectContext?.available_skills || [],
+    task_state: projectContext?.task_state || [],
+  };
+}

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