@bahulam/code 0.1.2 → 0.1.3

package/src/tools/meta-tools.mjs

@@ -0,0 +1,85 @@
+/**
+ * Sub-agent meta-tools: explore, plan, verify, debug, refactor.
+ *
+ * These are the LLM-visible peer-agent tools that map to gateway
+ * /v1/agent/subagent calls. For branch-01 they are registered with
+ * full schema parity to the Python originals (tool_bridge.py);
+ * the actual dispatch becomes a gateway call in a later phase.
+ */
+
+const HANDOFF_SCHEMA = {
+    type: 'object',
+    description: 'Optional compact handoff envelope. Pass known facts so the peer starts with context.',
+    properties: {
+        objective: { type: 'string' },
+        context: { type: 'string' },
+        files: { type: 'array', items: { type: 'object' } },
+        findings: { type: 'array', items: { type: 'object' } },
+        constraints: { type: 'array', items: { type: 'string' } },
+        acceptance_criteria: { type: 'array', items: { type: 'string' } },
+        open_questions: { type: 'array', items: { type: 'string' } },
+        output_contract: { type: 'string' },
+    },
+};
+
+/** Stub call — signals this is a gateway-dispatched sub-agent. */
+async function stubCall(_input) {
+    // Actual dispatch goes through gateway /v1/agent/subagent in a later phase.
+    // The LLM sees this tool registered so the gateway can serve its schema.
+    return 'Sub-agent dispatch via gateway — not yet implemented client-side.';
+}
+
+function metaTool(name, description, params) {
+    return {
+        name,
+        description,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: { type: 'string', description: 'The task to delegate to this sub-agent.' },
+                handoff: HANDOFF_SCHEMA,
+                ...params,
+            },
+            required: ['task'],
+        },
+        validateInput(input) { return input.task ? [] : ['task required']; },
+        async call(input) { return stubCall(input); },
+    };
+}
+
+export const ExploreTool = metaTool(
+    'explore',
+    'Read-only codebase investigation and orientation.',
+    {
+        thoroughness: {
+            type: 'string',
+            enum: ['quick', 'medium', 'thorough'],
+            description: 'How deep to investigate.',
+            default: 'medium',
+        },
+    },
+);
+
+export const PlanTool = metaTool(
+    'plan',
+    'Sequencing, design, and risk analysis for multi-file changes.',
+    {},
+);
+
+export const VerifyTool = metaTool(
+    'verify',
+    'Tests, lint, build checks, and evidence gathering.',
+    {},
+);
+
+export const DebugTool = metaTool(
+    'debug',
+    'Failure reproduction and root-cause investigation.',
+    {},
+);
+
+export const RefactorTool = metaTool(
+    'refactor',
+    'Mechanical broad cleanup, renames, and structure-only changes.',
+    {},
+);

package/src/tools/read-files.mjs

@@ -0,0 +1,37 @@
+/**
+ * Read Files Tool — read multiple files at once (matches Python schema).
+ */
+import * as path from 'node:path';
+
+export const ReadFilesTool = {
+    name: 'read_files',
+    description: 'Read multiple files at once',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file_paths: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'File paths',
+            },
+        },
+        required: ['file_paths'],
+    },
+    validateInput(input) {
+        return Array.isArray(input.file_paths) && input.file_paths.length > 0 ? [] : ['file_paths array required'];
+    },
+    async call(input) {
+        const { ReadTool } = await import('./read.mjs');
+        const results = [];
+        for (const fp of input.file_paths) {
+            try {
+                const result = await ReadTool.call({ file_path: path.resolve(fp) });
+                const text = typeof result === 'string' ? result : (result?.output || result?.content || String(result));
+                results.push(`## ${fp}\n${text}`);
+            } catch (err) {
+                results.push(`## ${fp}\nError: ${err.message}`);
+            }
+        }
+        return results.join('\n\n');
+    },
+};

package/src/tools/read.mjs

@@ -35,14 +35,14 @@ function isBinary(buffer) {
 }
 
 export const ReadTool = {
-    name: 'Read',
+    name: 'read_file',
     description: 'Read a file from the local filesystem.',
     inputSchema: {
         type: 'object',
         properties: {
             file_path: { type: 'string', description: 'Absolute path to the file' },
-            offset: { type: 'number', description: 'Line number to start reading from (0-based)' },
-            limit: { type: 'number', description: 'Number of lines to read (default 2000)' },
+            start_line: { type: 'integer', description: 'Line number to start reading from (1-indexed)' },
+            end_line: { type: 'integer', description: 'Line number to stop reading at (1-indexed, inclusive)' },
             pages: { type: 'string', description: 'Page range for PDF files (e.g. "1-5")' },
         },
         required: ['file_path'],
@@ -87,9 +87,6 @@ export const ReadTool = {
         try {
             const content = fs.readFileSync(filePath, 'utf-8');
             const lines = content.split('\n');
-            const start = input.offset || 0;
-            const limit = input.limit || DEFAULT_LIMIT;
-            const end = Math.min(start + limit, lines.length);
 
             // Track as read
             readFiles.add(filePath);
@@ -99,13 +96,26 @@ export const ReadTool = {
                 return '[File exists but is empty]';
             }
 
+            // start_line/end_line: 1-indexed, inclusive
+            const hasStart = input.start_line != null;
+            const hasEnd = input.end_line != null;
+            const startIdx = hasStart ? Math.max(0, Number(input.start_line) - 1) : 0;
+            let endIdx;
+            if (hasEnd) {
+                endIdx = Math.min(Number(input.end_line), lines.length); // inclusive → exclusive bound
+            } else if (hasStart) {
+                endIdx = lines.length;
+            } else {
+                endIdx = Math.min(DEFAULT_LIMIT, lines.length);
+            }
+
             const output = lines
-                .slice(start, end)
-                .map((l, i) => `${start + i + 1}\t${l}`)
+                .slice(startIdx, endIdx)
+                .map((l, i) => `${startIdx + i + 1}\t${l}`)
                 .join('\n');
 
-            if (end < lines.length) {
-                return output + `\n\n[File has ${lines.length} lines total. Showing lines ${start + 1}-${end}. Use offset/limit for more.]`;
+            if (endIdx < lines.length) {
+                return output + `\n\n[File has ${lines.length} lines total. Showing lines ${startIdx + 1}-${endIdx}. Use read_file with start_line/end_line for more.]`;
             }
 
             return output;

package/src/tools/registry.mjs

@@ -29,6 +29,14 @@ import { CronDeleteTool } from './cron-delete.mjs';
 import { CronListTool } from './cron-list.mjs';
 import { LspTool } from './lsp.mjs';
 import { ReadMcpResourceTool } from './read-mcp-resource.mjs';
+import { GitDiffTool } from './git-diff.mjs';
+import { GitStatusTool } from './git-status.mjs';
+import { WriteProjectTool } from './write-project.mjs';
+import { ReadFilesTool } from './read-files.mjs';
+import { SearchFilesTool } from './search-files.mjs';
+import { AnalyzeCodeTool } from './analyze-code.mjs';
+import { ExploreTool, PlanTool, VerifyTool, DebugTool, RefactorTool } from './meta-tools.mjs';
+import { RememberTool } from './remember.mjs';
 
 const BUILTIN_TOOLS = [
     BashTool,
@@ -41,6 +49,7 @@ const BUILTIN_TOOLS = [
     WebFetchTool,
     WebSearchTool,
     TodoWriteTool,
+    RememberTool,
     NotebookEditTool,
     MultiEditTool,
     LsTool,
@@ -56,6 +65,17 @@ const BUILTIN_TOOLS = [
     CronListTool,
     LspTool,
     ReadMcpResourceTool,
+    GitDiffTool,
+    GitStatusTool,
+    WriteProjectTool,
+    ReadFilesTool,
+    SearchFilesTool,
+    AnalyzeCodeTool,
+    ExploreTool,
+    PlanTool,
+    VerifyTool,
+    DebugTool,
+    RefactorTool,
 ];
 
 export function createToolRegistry() {

package/src/tools/remember.mjs

@@ -0,0 +1,147 @@
+/**
+ * Remember Tool — persist a cross-session memory fact to the user's disk.
+ *
+ * CLI-local tool. The agent calls this when it wants to remember something
+ * about the user, the project, or a preference. The fact lands in
+ * ~/.bahulam/memory.md (global) or <cwd>/.bahulam/memory.md (project),
+ * matching the disk-first CLI memory model (PRD-217).
+ *
+ * Contrast: chat / cloud-IDE / workspace surfaces continue writing to the
+ * Supabase agent_memory table via the framework's SupabaseMemoryBackend.
+ * Only CLI-originated requests use this local tool.
+ *
+ * The persisted shape round-trips 1:1 with the Supabase agent_memory
+ * schema — see src/core/memory-disk.mjs for the file format and helpers.
+ */
+
+import { upsertFacts, loadDiskMemory, ensureBahulamDir } from '../core/memory-disk.mjs';
+
+// Slug-safe generator when the caller didn't supply a fact_id. Prefer the
+// caller's own id when they give one — that's how they update an existing
+// fact instead of piling on near-duplicates.
+function _makeFactId(hint) {
+  const base = String(hint || 'fact').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60);
+  const stamp = Math.floor(Date.now() / 1000).toString(36);
+  return `${base || 'fact'}-${stamp}`;
+}
+
+export const RememberTool = {
+    name: 'remember',
+    description:
+        'Save a cross-session memory fact to the user\'s disk (~/.bahulam/memory.md). ' +
+        'Use when the user tells you a preference, when you learn a durable detail ' +
+        'about their project, or when the current turn establishes a decision worth ' +
+        'carrying forward. Do NOT use for ephemeral session state (that belongs in ' +
+        'the current conversation) or for temporary task tracking (use TodoWrite).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            content: {
+                type: 'string',
+                description:
+                    'The fact to remember, in prose. One or a few sentences. ' +
+                    'Include enough context to be useful without the surrounding conversation.',
+            },
+            fact_type: {
+                type: 'string',
+                enum: ['preference', 'entity', 'decision', 'context', 'other'],
+                description:
+                    'Category. `preference` = user always/never wants X. `entity` = ' +
+                    'thing/person/service (their company, their stack, their env). ' +
+                    '`decision` = choice made this session worth remembering. ' +
+                    '`context` = ongoing situation the agent should know next turn. ' +
+                    '`other` = anything else.',
+            },
+            fact_id: {
+                type: 'string',
+                description:
+                    'Stable ID. Reuse the same id to UPDATE a prior fact (in-place ' +
+                    'overwrite). Auto-generated from `content` if omitted, so ' +
+                    'auto-generated ids create new rows every time — pass an ' +
+                    'explicit id for anything you might want to update later.',
+            },
+            memory_scope: {
+                type: 'string',
+                enum: ['global', 'project'],
+                description:
+                    '`global` (default) writes to ~/.bahulam/memory.md — visible ' +
+                    'across every session. `project` writes to ' +
+                    '<cwd>/.bahulam/memory.md and only surfaces when running in ' +
+                    'this project. Use `project` for facts tied to this specific ' +
+                    'codebase (its architecture, its conventions, its history).',
+            },
+            confidence: {
+                type: 'number',
+                minimum: 0,
+                maximum: 1,
+                description:
+                    '0..1. How sure are you this fact is durably true? Use 0.9+ ' +
+                    'when the user stated it explicitly. Use 0.5-0.7 for inferred ' +
+                    'facts. Below 0.5 usually isn\'t worth saving.',
+            },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description:
+                    'Short lowercase labels (e.g. ["performance", "cache"]). ' +
+                    'Help future turns retrieve related facts.',
+            },
+        },
+        required: ['content'],
+    },
+
+    validateInput(input) {
+        const errs = [];
+        if (!input || typeof input.content !== 'string' || !input.content.trim()) {
+            errs.push('content is required and must be a non-empty string');
+        }
+        if (input.confidence != null) {
+            const n = Number(input.confidence);
+            if (!Number.isFinite(n) || n < 0 || n > 1) errs.push('confidence must be a number in [0, 1]');
+        }
+        return errs;
+    },
+
+    async call(input, _options = {}) {
+        const now = new Date().toISOString();
+        const scope = input.memory_scope === 'project' ? 'project' : 'global';
+        const fact = {
+            fact_id: (input.fact_id || _makeFactId(input.content)).trim(),
+            content: String(input.content).trim(),
+            fact_type: input.fact_type || 'other',
+            confidence: typeof input.confidence === 'number' ? input.confidence : 0.8,
+            source: 'agent',
+            tags: Array.isArray(input.tags) ? input.tags.map(String) : [],
+            metadata: {},
+            project_id: null,
+            memory_scope: scope,
+            created_at: now,
+            updated_at: now,
+        };
+
+        // Preserve created_at if we're updating an existing fact.
+        const existing = loadDiskMemory().find(f => f.fact_id === fact.fact_id);
+        if (existing?.created_at) fact.created_at = existing.created_at;
+
+        try {
+            // Belt-and-braces: upsertFacts also mkdir's, but a stale cwd on
+            // a project write could still miss the parent — do it explicitly.
+            ensureBahulamDir(scope);
+            upsertFacts([fact]);
+        } catch (err) {
+            return {
+                success: false,
+                output: `remember failed: ${err?.message || err}`,
+                _tool: 'remember',
+            };
+        }
+        return {
+            success: true,
+            output: `Saved ${scope} fact '${fact.fact_id}' (${fact.content.length} chars).`,
+            _tool: 'remember',
+            _fact_id: fact.fact_id,
+            _scope: scope,
+        };
+    },
+};

package/src/tools/search-files.mjs

@@ -0,0 +1,41 @@
+/**
+ * Search Files Tool — regex-based file content search (matches Python schema).
+ */
+import { spawnSync } from 'child_process';
+import * as path from 'node:path';
+
+export const SearchFilesTool = {
+    name: 'search_files',
+    description: 'Search file contents with regex',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Regex pattern' },
+            path: { type: 'string', description: 'Directory' },
+        },
+        required: ['pattern'],
+    },
+    validateInput(input) {
+        return input.pattern ? [] : ['pattern required'];
+    },
+    async call(input) {
+        const dir = path.resolve(input.path || '.');
+        try {
+            const args = ['-rn', '--max-count', '10', '--max-filesize', '500K'];
+            args.push('-e', input.pattern);
+            args.push(dir);
+            const result = spawnSync('rg', args, {
+                encoding: 'utf-8',
+                timeout: 15_000,
+                stdio: 'pipe',
+            });
+            if (result.status === 0 || result.status === 1) {
+                const output = (result.stdout || '').trim();
+                return output || `No matches for "${input.pattern}" in ${dir}`;
+            }
+            return `grep error (exit ${result.status}): ${result.stderr?.trim() || 'unknown'}`;
+        } catch (err) {
+            return `Error: ${err.message}`;
+        }
+    },
+};

package/src/tools/write-project.mjs

@@ -0,0 +1,62 @@
+/**
+ * Write Project Tool — batch write multiple files at once (matches Python schema).
+ */
+import fs from 'fs';
+import path from 'path';
+import { hasBeenRead, markRead } from './read.mjs';
+
+export const WriteProjectTool = {
+    name: 'write_project',
+    description: 'Write multiple files at once',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            files: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'File path' },
+                        content: { type: 'string', description: 'File content' },
+                    },
+                    required: ['path', 'content'],
+                },
+                description: 'Files to write',
+            },
+        },
+        required: ['files'],
+    },
+    validateInput(input) {
+        const errors = [];
+        if (!Array.isArray(input.files) || input.files.length === 0) errors.push('files array required');
+        return errors;
+    },
+    async call(input) {
+        const results = [];
+        const errors = [];
+        for (const file of input.files) {
+            const filePath = path.resolve(file.path || file.file_path);
+            try {
+                const dir = path.dirname(filePath);
+                fs.mkdirSync(dir, { recursive: true });
+                if (fs.existsSync(filePath) && !hasBeenRead(filePath)) {
+                    // Read first for overwrites
+                    const { ReadTool } = await import('./read.mjs');
+                    await ReadTool.call({ file_path: filePath, limit: 1 });
+                }
+                fs.writeFileSync(filePath, file.content || '', 'utf-8');
+                markRead(filePath);
+                results.push(filePath);
+            } catch (err) {
+                errors.push(`${filePath}: ${err.message}`);
+            }
+        }
+        const output = results.length > 0
+            ? `Created ${results.length} file(s):\n${results.map(f => `  ✓ ${f}`).join('\n')}`
+            : 'No files written';
+        if (errors.length > 0) {
+            return `${output}\n\nErrors:\n${errors.map(e => `  ✗ ${e}`).join('\n')}`;
+        }
+        return output;
+    },
+};

package/src/tools/write.mjs

@@ -11,7 +11,7 @@ import path from 'path';
 import { hasBeenRead, markRead } from './read.mjs';
 
 export const WriteTool = {
-    name: 'Write',
+    name: 'write_file',
     description: 'Write content to a file. Creates parent dirs if needed.',
     inputSchema: {
         type: 'object',

package/src/ui/sub-agent.mjs

@@ -19,6 +19,7 @@
 
 import { paint } from './palette.mjs';
 import { icons } from './icons.mjs';
+import { formatSeconds } from '../terminal/ansi.mjs';
 
 const SUB_ICONS = {
   explore: '🔭',
@@ -122,9 +123,14 @@ export function renderSubAgentClose({
   const parts = [];
   if (toolCalls > 0)              parts.push(`${toolCalls} tools`);
   if (iterations > 0)             parts.push(`${iterations} iter`);
-  if (tokens > 0)                 parts.push(`${formatTokens(tokens)} tok`);
+  // Tokens: pass the OUTPUT (generation) count only. Summing input+output
+  // across a multi-iteration sub-agent double-counts the context that is
+  // re-shipped each iteration, and the resulting number reads huge and
+  // misleading (e.g. 632.8k for a 16-iter run whose actual generation was
+  // a fraction of that). Output tokens are the honest "work done" number.
+  if (tokens > 0)                 parts.push(`${formatTokens(tokens)} gen`);
   if (typeof costUsd === 'number' && costUsd > 0) parts.push(formatCost(costUsd));
-  if (durationS != null)          parts.push(`${Number(durationS).toFixed(1)}s`);
+  if (durationS != null)          parts.push(formatSeconds(durationS));
   const detail = parts.length ? paint.text.dim(' · ' + parts.join(' · ')) : '';
 
   const body = summary