@axplusb/kepler 0.0.1 → 1.0.1

package/src/terminal/tool-display.mjs

@@ -0,0 +1,58 @@
+const TOOL_LABELS = Object.freeze({
+  shell: 'Run command',
+  read_file: 'Read file',
+  read_files: 'Read files',
+  write_file: 'Create file',
+  write_project: 'Create project files',
+  edit_file: 'Edit file',
+  delete_file: 'Delete file',
+  list_files: 'List files',
+  search_code: 'Search code',
+  search_files: 'Search files',
+  grep: 'Search text',
+  get_file_info: 'Inspect file',
+  validate_file: 'Validate file',
+  validate_build: 'Validate build',
+  validate_structure: 'Check project structure',
+  lint_check: 'Check code quality',
+  run_tests: 'Run tests',
+  git_diff: 'Review changes',
+  git_status: 'Check repository status',
+  analyze_code: 'Analyze code',
+  explore: 'Explore codebase',
+  plan: 'Create implementation plan',
+});
+
+export function toolDisplayLabel(tool) {
+  if (!tool) return 'Use tool';
+  if (TOOL_LABELS[tool]) return TOOL_LABELS[tool];
+  return tool
+    .replace(/^mcp[_-]?/i, '')
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((part, index) => index === 0
+      ? part.charAt(0).toUpperCase() + part.slice(1)
+      : part.toLowerCase())
+    .join(' ');
+}
+
+export function formatShellCommand(command, colors) {
+  const tokens = String(command || '').match(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|&&|\|\||[|;<>]|[^\s]+|\s+/g) || [];
+  let expectsCommand = true;
+
+  return tokens.map(token => {
+    if (/^\s+$/.test(token)) return token;
+    if (/^(?:&&|\|\||[|;<>])$/.test(token)) {
+      expectsCommand = true;
+      return colors.red(token);
+    }
+    if (expectsCommand) {
+      expectsCommand = false;
+      return colors.blue(token);
+    }
+    if (/^-{1,2}[\w-]+(?:=.*)?$/.test(token) || /^["']/.test(token)) {
+      return colors.yellow(token);
+    }
+    return colors.white(token);
+  }).join('');
+}

package/src/tools/agent.mjs

@@ -0,0 +1,137 @@
+/**
+ * Agent Tool — spawn a subagent with its own agent loop.
+ *
+ * Features:
+ * - subagent_type parameter
+ * - isolation: "worktree" option
+ * - run_in_background option
+ * - model override
+ */
+
+import { createAgentLoop } from '../core/agent-loop.mjs';
+import { createToolRegistry } from './registry.mjs';
+import { createPermissionChecker } from '../permissions/checker.mjs';
+
+export const AgentTool = {
+    name: 'Agent',
+    description: 'Spawn a subagent to handle a task. The subagent has its own context and tools.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            prompt: {
+                type: 'string',
+                description: 'The task for the subagent to perform',
+            },
+            allowed_tools: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of tool names the subagent can use (default: all)',
+            },
+            subagent_type: {
+                type: 'string',
+                description: 'Type of subagent (e.g. coder, reviewer, researcher)',
+            },
+            isolation: {
+                type: 'string',
+                enum: ['default', 'worktree'],
+                description: 'Isolation mode. "worktree" uses a git worktree.',
+            },
+            run_in_background: {
+                type: 'boolean',
+                description: 'Run in background and return immediately',
+            },
+            model: {
+                type: 'string',
+                description: 'Override model for this subagent',
+            },
+        },
+        required: ['prompt'],
+    },
+
+    validateInput(input) {
+        const errors = [];
+        if (!input.prompt) errors.push('prompt is required');
+        return errors;
+    },
+
+    // Track background subagents
+    _backgroundAgents: new Map(),
+    _nextBgId: 0,
+
+    async call(input) {
+        const model = input.model || process.env.SUBAGENT_MODEL || 'claude-sonnet-4-6';
+        const tools = createToolRegistry();
+        const permissions = createPermissionChecker({ defaultMode: 'bypassPermissions' });
+
+        // Build type-specific system prompt prefix
+        let systemPrefix = '';
+        if (input.subagent_type) {
+            const typePrompts = {
+                coder: 'You are a coding agent. Write clean, tested code.',
+                reviewer: 'You are a code reviewer. Analyze code for bugs and improvements.',
+                researcher: 'You are a research agent. Find and summarize information.',
+                tester: 'You are a testing agent. Write and run tests.',
+                planner: 'You are a planning agent. Break down tasks into steps.',
+            };
+            systemPrefix = typePrompts[input.subagent_type] || `You are a ${input.subagent_type} agent.`;
+        }
+
+        const fullPrompt = systemPrefix
+            ? `${systemPrefix}\n\nTask: ${input.prompt}`
+            : input.prompt;
+
+        const loop = createAgentLoop({
+            model,
+            tools,
+            permissions,
+            settings: {
+                stream: false,
+                stagnationDetection: !['0', 'false', 'no', 'off'].includes(
+                    (process.env.KEPLER_STAGNATION_DETECTION ?? '0').toLowerCase(),
+                ),
+                stagnationThreshold: Number.parseInt(
+                    process.env.KEPLER_STAGNATION_THRESHOLD
+                    ?? '3',
+                    10,
+                ),
+            },
+        });
+
+        if (input.run_in_background) {
+            const bgId = ++AgentTool._nextBgId;
+            const entry = { id: bgId, status: 'running', result: null, prompt: input.prompt };
+            AgentTool._backgroundAgents.set(bgId, entry);
+
+            // Run in background
+            runSubagent(loop, fullPrompt).then(result => {
+                entry.status = 'completed';
+                entry.result = result;
+            }).catch(err => {
+                entry.status = 'error';
+                entry.result = err.message;
+            });
+
+            return `Subagent started in background: id=${bgId}`;
+        }
+
+        return runSubagent(loop, fullPrompt);
+    },
+};
+
+async function runSubagent(loop, prompt) {
+    const results = [];
+    try {
+        for await (const event of loop.run(prompt)) {
+            if (event.type === 'assistant' && event.content) {
+                results.push(event.content);
+            }
+            if (event.type === 'result') {
+                results.push(`[tool:${event.tool}] ${String(event.result).slice(0, 500)}`);
+            }
+        }
+    } catch (err) {
+        return `Subagent error: ${err.message}`;
+    }
+
+    return results.join('\n') || 'Subagent completed with no output.';
+}

package/src/tools/ask-user.mjs

@@ -0,0 +1,61 @@
+/**
+ * AskUser Tool — prompt the user with a question and return their response.
+ *
+ * Used when the agent needs clarification or confirmation from the user.
+ * In non-interactive mode, returns a default or times out.
+ */
+
+import readline from 'readline';
+
+export const AskUserTool = {
+    name: 'AskUser',
+    description: 'Ask the user a question and wait for their response.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question to ask the user',
+            },
+            default_value: {
+                type: 'string',
+                description: 'Default value if user provides no input',
+            },
+            timeout: {
+                type: 'number',
+                description: 'Timeout in milliseconds (default: 60000)',
+            },
+        },
+        required: ['question'],
+    },
+
+    validateInput(input) {
+        return input.question ? [] : ['question is required'];
+    },
+
+    async call(input) {
+        // In non-interactive mode, return default
+        if (!process.stdin.isTTY) {
+            return input.default_value || '[non-interactive: no user input available]';
+        }
+
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stderr,
+            });
+
+            const timeout = setTimeout(() => {
+                rl.close();
+                resolve(input.default_value || '[timeout: no response]');
+            }, input.timeout || 60000);
+
+            process.stderr.write(`\n\x1b[36m? ${input.question}\x1b[0m\n> `);
+            rl.question('', (answer) => {
+                clearTimeout(timeout);
+                rl.close();
+                resolve(answer.trim() || input.default_value || '');
+            });
+        });
+    },
+};

package/src/tools/bash.mjs

@@ -0,0 +1,148 @@
+/**
+ * Bash Tool — matches Claude Code's exact behavior.
+ *
+ * Features:
+ * - Timeout with SIGTERM -> SIGKILL escalation
+ * - run_in_background option
+ * - description parameter
+ * - 1MB output limit
+ * - ANSI code stripping by default
+ */
+import { spawn } from 'child_process';
+
+// Strip ANSI escape sequences
+function stripAnsi(str) {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+}
+
+const MAX_OUTPUT_BYTES = 1024 * 1024; // 1MB
+
+export const BashTool = {
+    name: 'Bash',
+    description: 'Execute a bash command and return its output.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            command: { type: 'string', description: 'The command to execute' },
+            timeout: { type: 'number', description: 'Timeout in ms (max 600000)', default: 120000 },
+            description: { type: 'string', description: 'Description of what this command does' },
+            run_in_background: { type: 'boolean', description: 'Run in background', default: false },
+        },
+        required: ['command'],
+    },
+    validateInput(input) {
+        const errors = [];
+        if (!input.command) errors.push('command is required');
+        return errors;
+    },
+    async call(input) {
+        const timeout = Math.min(input.timeout || 120000, 600000);
+
+        if (input.run_in_background) {
+            return runBackground(input.command);
+        }
+
+        return new Promise((resolve) => {
+            let stdout = '';
+            let stderr = '';
+            let killed = false;
+            let exitCode = null;
+
+            const proc = spawn('bash', ['-c', input.command], {
+                env: { ...process.env },
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 0, // we handle timeout ourselves
+            });
+
+            proc.stdout.on('data', (chunk) => {
+                if (stdout.length < MAX_OUTPUT_BYTES) {
+                    stdout += chunk.toString();
+                }
+            });
+
+            proc.stderr.on('data', (chunk) => {
+                if (stderr.length < MAX_OUTPUT_BYTES) {
+                    stderr += chunk.toString();
+                }
+            });
+
+            // Timeout: SIGTERM first, then SIGKILL after 5s
+            const timer = setTimeout(() => {
+                killed = true;
+                proc.kill('SIGTERM');
+                setTimeout(() => {
+                    try { proc.kill('SIGKILL'); } catch { /* already dead */ }
+                }, 5000);
+            }, timeout);
+
+            proc.on('close', (code) => {
+                clearTimeout(timer);
+                exitCode = code;
+
+                // Truncate if over limit
+                if (stdout.length > MAX_OUTPUT_BYTES) {
+                    stdout = stdout.slice(0, MAX_OUTPUT_BYTES) + '\n[output truncated at 1MB]';
+                }
+                if (stderr.length > MAX_OUTPUT_BYTES) {
+                    stderr = stderr.slice(0, MAX_OUTPUT_BYTES) + '\n[output truncated at 1MB]';
+                }
+
+                // Strip ANSI by default
+                stdout = stripAnsi(stdout);
+                stderr = stripAnsi(stderr);
+
+                if (killed) {
+                    resolve(`Error: Command timed out after ${timeout}ms\n${stdout}\n${stderr}`.trim());
+                    return;
+                }
+
+                const output = (stdout + (stderr ? '\n' + stderr : '')).trim();
+                if (code !== 0) {
+                    resolve(`Exit code: ${code}\n${output}`.trim());
+                } else {
+                    resolve(output || '(no output)');
+                }
+            });
+
+            proc.on('error', (err) => {
+                clearTimeout(timer);
+                resolve(`Error: ${err.message}`);
+            });
+
+            // Close stdin
+            proc.stdin.end();
+        });
+    },
+};
+
+// Background jobs store
+const backgroundJobs = new Map();
+let bgJobId = 0;
+
+function runBackground(command) {
+    const id = ++bgJobId;
+    const proc = spawn('bash', ['-c', command], {
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => { stdout += d.toString(); });
+    proc.stderr.on('data', (d) => { stderr += d.toString(); });
+
+    const job = { id, pid: proc.pid, command, status: 'running', stdout: '', stderr: '' };
+    backgroundJobs.set(id, job);
+
+    proc.on('close', (code) => {
+        job.status = code === 0 ? 'completed' : `exited(${code})`;
+        job.stdout = stripAnsi(stdout.slice(0, MAX_OUTPUT_BYTES));
+        job.stderr = stripAnsi(stderr.slice(0, MAX_OUTPUT_BYTES));
+    });
+
+    proc.unref();
+    return `Background job started: id=${id}, pid=${proc.pid}`;
+}
+
+export { backgroundJobs };

package/src/tools/cron-create.mjs

@@ -0,0 +1,120 @@
+/**
+ * CronCreate Tool — create a scheduled task.
+ *
+ * Stores cron definitions in memory and optionally persists them
+ * to ~/.claude/cron.json. Uses setTimeout-based scheduling for
+ * the duration of the session.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Shared cron store
+export const cronStore = new Map();
+let cronIdCounter = 1;
+
+export const CronCreateTool = {
+    name: 'CronCreate',
+    description: 'Create a scheduled task that runs on a cron schedule.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Name for the scheduled task' },
+            schedule: {
+                type: 'string',
+                description: 'Cron expression (e.g., "*/5 * * * *") or interval (e.g., "5m", "1h")',
+            },
+            command: {
+                type: 'string',
+                description: 'Command or prompt to execute on schedule',
+            },
+            type: {
+                type: 'string',
+                enum: ['command', 'prompt'],
+                description: 'Whether to run as shell command or agent prompt',
+            },
+        },
+        required: ['name', 'schedule', 'command'],
+    },
+
+    validateInput(input) {
+        const errors = [];
+        if (!input.name) errors.push('name is required');
+        if (!input.schedule) errors.push('schedule is required');
+        if (!input.command) errors.push('command is required');
+        return errors;
+    },
+
+    async call(input) {
+        if (process.env.CLAUDE_CODE_DISABLE_CRON === '1') {
+            return 'Cron tasks are disabled (CLAUDE_CODE_DISABLE_CRON=1)';
+        }
+
+        const id = `cron_${cronIdCounter++}`;
+        const intervalMs = parseSchedule(input.schedule);
+
+        const job = {
+            id,
+            name: input.name,
+            schedule: input.schedule,
+            command: input.command,
+            type: input.type || 'command',
+            intervalMs,
+            createdAt: new Date().toISOString(),
+            lastRun: null,
+            runCount: 0,
+            timer: null,
+        };
+
+        // Set up interval timer
+        if (intervalMs > 0) {
+            job.timer = setInterval(() => {
+                job.lastRun = new Date().toISOString();
+                job.runCount++;
+                // Execution is handled by the cron runner in the main loop
+            }, intervalMs);
+        }
+
+        cronStore.set(id, job);
+        persistCronJobs();
+
+        return `Created scheduled task:\n  ID: ${id}\n  Name: ${input.name}\n  Schedule: ${input.schedule}\n  Interval: ${intervalMs}ms\n  Type: ${job.type}`;
+    },
+};
+
+/**
+ * Parse a schedule string into milliseconds.
+ * Supports cron shorthand: "5m", "1h", "30s", "1d"
+ */
+function parseSchedule(schedule) {
+    const match = schedule.match(/^(\d+)(s|m|h|d)$/);
+    if (match) {
+        const value = parseInt(match[1], 10);
+        const units = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+        return value * (units[match[2]] || 60000);
+    }
+    // Default: treat as minutes for simple numbers
+    const num = parseInt(schedule, 10);
+    if (!isNaN(num)) return num * 60000;
+    // For full cron expressions, default to 5 minutes
+    return 300000;
+}
+
+function persistCronJobs() {
+    try {
+        const cronDir = path.join(os.homedir(), '.claude');
+        fs.mkdirSync(cronDir, { recursive: true });
+        const jobs = [];
+        for (const [, job] of cronStore) {
+            const { timer, ...rest } = job;
+            jobs.push(rest);
+        }
+        fs.writeFileSync(
+            path.join(cronDir, 'cron.json'),
+            JSON.stringify(jobs, null, 2)
+        );
+    } catch {
+        // Best effort
+    }
+}

package/src/tools/cron-delete.mjs

@@ -0,0 +1,49 @@
+/**
+ * CronDelete Tool — delete a scheduled task.
+ */
+
+import { cronStore } from './cron-create.mjs';
+
+export const CronDeleteTool = {
+    name: 'CronDelete',
+    description: 'Delete a scheduled task by ID or name.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: 'Cron job ID to delete' },
+            name: { type: 'string', description: 'Cron job name to delete (alternative to id)' },
+        },
+        required: [],
+    },
+
+    validateInput(input) {
+        if (!input.id && !input.name) return ['Either id or name is required'];
+        return [];
+    },
+
+    async call(input) {
+        let target = null;
+
+        if (input.id) {
+            target = cronStore.get(input.id);
+        } else if (input.name) {
+            for (const [, job] of cronStore) {
+                if (job.name === input.name) {
+                    target = job;
+                    break;
+                }
+            }
+        }
+
+        if (!target) {
+            return `No cron job found matching ${input.id || input.name}`;
+        }
+
+        if (target.timer) {
+            clearInterval(target.timer);
+        }
+        cronStore.delete(target.id);
+
+        return `Deleted cron job: ${target.id} (${target.name})`;
+    },
+};

package/src/tools/cron-list.mjs

@@ -0,0 +1,37 @@
+/**
+ * CronList Tool — list all scheduled tasks.
+ */
+
+import { cronStore } from './cron-create.mjs';
+
+export const CronListTool = {
+    name: 'CronList',
+    description: 'List all scheduled tasks.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+
+    validateInput() { return []; },
+
+    async call() {
+        if (cronStore.size === 0) {
+            return 'No scheduled tasks.';
+        }
+
+        const lines = [];
+        for (const [, job] of cronStore) {
+            lines.push(
+                `  ${job.id}: ${job.name}\n` +
+                `    Schedule: ${job.schedule} (${job.intervalMs}ms)\n` +
+                `    Type: ${job.type}\n` +
+                `    Runs: ${job.runCount}\n` +
+                `    Last: ${job.lastRun || 'never'}\n` +
+                `    Created: ${job.createdAt}`
+            );
+        }
+
+        return `Scheduled tasks (${cronStore.size}):\n${lines.join('\n\n')}`;
+    },
+};

package/src/tools/edit.mjs

@@ -0,0 +1,82 @@
+/**
+ * Edit Tool — matches Claude Code's exact behavior.
+ *
+ * Features:
+ * - replace_all parameter for global replacement
+ * - Verify old_string is unique (error if not)
+ * - Require file was Read first (track read files)
+ * - Preserve exact indentation
+ */
+import fs from 'fs';
+import path from 'path';
+import { hasBeenRead, markRead } from './read.mjs';
+
+export const EditTool = {
+    name: 'Edit',
+    description: 'Performs exact string replacements in files.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file_path: { type: 'string', description: 'Absolute path to the file' },
+            old_string: { type: 'string', description: 'The text to replace' },
+            new_string: { type: 'string', description: 'The replacement text' },
+            replace_all: { type: 'boolean', description: 'Replace all occurrences', default: false },
+        },
+        required: ['file_path', 'old_string', 'new_string'],
+    },
+    validateInput(input) {
+        const errors = [];
+        if (!input.file_path) errors.push('file_path required');
+        if (!input.old_string && input.old_string !== '') errors.push('old_string required');
+        if (input.old_string === input.new_string) errors.push('old_string must differ from new_string');
+        return errors;
+    },
+    async call(input) {
+        const filePath = path.resolve(input.file_path);
+
+        // Check file exists
+        if (!fs.existsSync(filePath)) {
+            return `Error: File not found: ${filePath}`;
+        }
+
+        // Require file was read first
+        if (!hasBeenRead(filePath)) {
+            return `Error: You must Read ${filePath} before editing it. Use the Read tool first.`;
+        }
+
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        } catch (e) {
+            return `Error: ${e.message}`;
+        }
+
+        if (!content.includes(input.old_string)) {
+            return 'Error: old_string not found in file. Make sure the string matches exactly, including whitespace and indentation.';
+        }
+
+        if (input.replace_all) {
+            // Replace all occurrences
+            const escaped = input.old_string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            content = content.replace(new RegExp(escaped, 'g'), input.new_string);
+        } else {
+            // Check uniqueness: old_string must appear exactly once
+            const firstIdx = content.indexOf(input.old_string);
+            const secondIdx = content.indexOf(input.old_string, firstIdx + 1);
+            if (secondIdx !== -1) {
+                const count = content.split(input.old_string).length - 1;
+                return `Error: old_string is not unique in the file (found ${count} occurrences). Provide more context to make it unique, or use replace_all to replace all occurrences.`;
+            }
+            content = content.replace(input.old_string, input.new_string);
+        }
+
+        try {
+            fs.writeFileSync(filePath, content);
+            // Keep it marked as read
+            markRead(filePath);
+            return `File updated: ${filePath}`;
+        } catch (e) {
+            return `Error writing file: ${e.message}`;
+        }
+    },
+};