@axplusb/kepler 0.0.1 → 1.0.0

package/src/tools/skill.mjs

@@ -0,0 +1,52 @@
+/**
+ * Skill Tool — invoke a loaded skill by name.
+ *
+ * Skills are loaded from .claude/skills/{name}/SKILL.md and provide
+ * specialized prompts injected into the conversation.
+ */
+
+export const SkillTool = {
+    name: 'Skill',
+    description: 'Invoke a skill within the conversation. Skills provide specialized capabilities.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            skill: {
+                type: 'string',
+                description: 'The skill name to invoke (e.g., "commit", "review-pr")',
+            },
+            args: {
+                type: 'string',
+                description: 'Optional arguments for the skill',
+            },
+        },
+        required: ['skill'],
+    },
+
+    // Set by skills loader
+    _skillsLoader: null,
+
+    validateInput(input) {
+        return input.skill ? [] : ['skill name is required'];
+    },
+
+    async call(input) {
+        if (!this._skillsLoader) {
+            return 'Skills system not initialized. No skills available.';
+        }
+
+        try {
+            const skill = this._skillsLoader.get(input.skill);
+            if (!skill) {
+                const available = this._skillsLoader.list();
+                const names = available.map(s => s.name).join(', ');
+                return `Unknown skill: "${input.skill}". Available: ${names || 'none'}`;
+            }
+
+            const result = await this._skillsLoader.run(input.skill, input.args);
+            return result;
+        } catch (err) {
+            return `Skill error: ${err.message}`;
+        }
+    },
+};

package/src/tools/test-runner.mjs

@@ -0,0 +1,49 @@
+/**
+ * Test Runner Tool — run test suites in contained environment.
+ *
+ * Executes in .venv/sandbox when available.
+ * Agent should use this instead of shell("pytest tests/").
+ *
+ * Execution: contained (.venv + OS sandbox if available).
+ */
+
+import { BashTool } from './bash.mjs';
+
+export const TestRunnerTool = {
+    name: 'TestRunner',
+    description: 'Run tests. Executes in project environment. Use this instead of Bash for pytest, jest, vitest, cargo test, go test.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            command: {
+                type: 'string',
+                description: 'Test command (e.g., "pytest tests/test_auth.py -v", "npm test", "cargo test")',
+            },
+            timeout: {
+                type: 'number',
+                description: 'Timeout in ms (default: 120000, max: 300000)',
+                default: 120000,
+            },
+        },
+        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, 300000);
+
+        // TODO: Wire sandbox.mjs here when sandbox execution is ready
+        // For now, execute directly (same as Bash but with metadata)
+        const result = await BashTool.call({
+            command: input.command,
+            timeout,
+            description: `Test: ${input.command.slice(0, 60)}`,
+        });
+
+        return result;
+    },
+    _executionPolicy: 'contained',
+};

package/src/tools/todo-write.mjs

@@ -0,0 +1,68 @@
+/**
+ * TodoWrite Tool — in-memory task management.
+ *
+ * Maintains a task list that the agent can use to track work items.
+ * State persists for the duration of the session.
+ */
+
+const todos = [];
+let nextId = 1;
+
+export const TodoWriteTool = {
+    name: 'TodoWrite',
+    description: 'Manage a task list. Supports add, update, complete, and list operations.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            todos: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string', description: 'Task ID (auto-assigned if adding)' },
+                        content: { type: 'string', description: 'Task description' },
+                        status: {
+                            type: 'string',
+                            enum: ['pending', 'in_progress', 'completed'],
+                            description: 'Task status',
+                        },
+                        priority: {
+                            type: 'string',
+                            enum: ['high', 'medium', 'low'],
+                            description: 'Task priority',
+                        },
+                    },
+                    required: ['content', 'status'],
+                },
+                description: 'Array of todo items to write (replaces all todos)',
+            },
+        },
+        required: ['todos'],
+    },
+
+    validateInput(input) {
+        if (!input.todos || !Array.isArray(input.todos)) return ['todos must be an array'];
+        return [];
+    },
+
+    async call(input) {
+        // Replace entire todo list (matches Claude Code behavior)
+        todos.length = 0;
+        nextId = 1;
+
+        for (const item of input.todos) {
+            todos.push({
+                id: item.id || String(nextId++),
+                content: item.content,
+                status: item.status || 'pending',
+                priority: item.priority || 'medium',
+            });
+        }
+
+        const summary = todos.map(t =>
+            `[${t.status === 'completed' ? 'x' : t.status === 'in_progress' ? '~' : ' '}] ${t.id}. ${t.content} (${t.priority})`
+        ).join('\n');
+
+        return `Updated ${todos.length} todos:\n${summary}`;
+    },
+};

package/src/tools/tool-search.mjs

@@ -0,0 +1,77 @@
+/**
+ * ToolSearch Tool — deferred tool loading / search.
+ *
+ * Allows the agent to discover and load tools that are not
+ * in the default set. Supports searching MCP servers and
+ * deferred tool definitions.
+ */
+
+export const ToolSearchTool = {
+    name: 'ToolSearch',
+    description: 'Search for and load deferred tools by name or keyword.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Tool name or search keywords',
+            },
+            max_results: {
+                type: 'number',
+                description: 'Maximum results to return (default: 5)',
+            },
+        },
+        required: ['query'],
+    },
+
+    // Will be set by the registry when MCP tools are available
+    _mcpTools: [],
+    _registry: null,
+
+    validateInput(input) {
+        return input.query ? [] : ['query is required'];
+    },
+
+    async call(input) {
+        const query = input.query.toLowerCase();
+        const maxResults = input.max_results || 5;
+        const matches = [];
+
+        // Search MCP tools
+        for (const tool of this._mcpTools) {
+            const name = (tool.name || '').toLowerCase();
+            const desc = (tool.description || '').toLowerCase();
+            if (name.includes(query) || desc.includes(query)) {
+                matches.push({
+                    name: tool.name,
+                    description: tool.description,
+                    source: 'mcp',
+                });
+            }
+        }
+
+        // Search registry tools
+        if (this._registry) {
+            for (const tool of this._registry.list()) {
+                const name = (tool.name || '').toLowerCase();
+                const desc = (tool.description || '').toLowerCase();
+                if (name.includes(query) || desc.includes(query)) {
+                    matches.push({
+                        name: tool.name,
+                        description: tool.description,
+                        source: 'builtin',
+                    });
+                }
+            }
+        }
+
+        if (matches.length === 0) {
+            return `No tools found matching "${input.query}"`;
+        }
+
+        const limited = matches.slice(0, maxResults);
+        return limited.map(m =>
+            `[${m.source}] ${m.name}: ${m.description}`
+        ).join('\n');
+    },
+};

package/src/tools/web-fetch.mjs

@@ -0,0 +1,65 @@
+/**
+ * Web Fetch Tool — fetch URL content using built-in Node.js fetch.
+ */
+
+export const WebFetchTool = {
+    name: 'WebFetch',
+    description: 'Fetch content from a URL. Returns the response body as text.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'The URL to fetch' },
+            headers: {
+                type: 'object',
+                description: 'Optional HTTP headers',
+            },
+            max_length: {
+                type: 'number',
+                description: 'Max response length in characters (default: 50000)',
+            },
+        },
+        required: ['url'],
+    },
+
+    validateInput(input) {
+        const errors = [];
+        if (!input.url) errors.push('url is required');
+        try {
+            new URL(input.url);
+        } catch {
+            errors.push('url must be a valid URL');
+        }
+        return errors;
+    },
+
+    async call(input) {
+        const maxLength = input.max_length || 50000;
+
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 30000);
+
+            const res = await fetch(input.url, {
+                headers: input.headers || {},
+                signal: controller.signal,
+                redirect: 'follow',
+            });
+
+            clearTimeout(timeout);
+
+            if (!res.ok) {
+                return `HTTP ${res.status}: ${res.statusText}`;
+            }
+
+            const contentType = res.headers.get('content-type') || '';
+            const text = await res.text();
+            const truncated = text.length > maxLength
+                ? text.slice(0, maxLength) + `\n...[truncated at ${maxLength} chars]`
+                : text;
+
+            return `Content-Type: ${contentType}\nLength: ${text.length}\n\n${truncated}`;
+        } catch (err) {
+            return `Fetch error: ${err.message}`;
+        }
+    },
+};

package/src/tools/web-search.mjs

@@ -0,0 +1,89 @@
+/**
+ * Web Search Tool — search the web via configurable API backends.
+ *
+ * Supports:
+ * - Brave Search API (BRAVE_API_KEY)
+ * - SearXNG (self-hosted, SEARXNG_URL)
+ * - Fallback: returns instructions to use web-fetch instead
+ */
+
+export const WebSearchTool = {
+    name: 'WebSearch',
+    description: 'Search the web for information. Requires BRAVE_API_KEY or SEARXNG_URL.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Search query' },
+            limit: { type: 'number', description: 'Max results (default: 5)' },
+        },
+        required: ['query'],
+    },
+
+    validateInput(input) {
+        return input.query ? [] : ['query is required'];
+    },
+
+    async call(input) {
+        const limit = input.limit || 5;
+
+        // Try Brave Search API
+        const braveKey = process.env.BRAVE_API_KEY;
+        if (braveKey) {
+            return searchBrave(input.query, limit, braveKey);
+        }
+
+        // Try SearXNG
+        const searxUrl = process.env.SEARXNG_URL;
+        if (searxUrl) {
+            return searchSearxng(input.query, limit, searxUrl);
+        }
+
+        return 'No search API configured. Set BRAVE_API_KEY or SEARXNG_URL environment variable. ' +
+            'Alternatively, use the WebFetch tool to fetch specific URLs directly.';
+    },
+};
+
+async function searchBrave(query, limit, apiKey) {
+    try {
+        const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${limit}`;
+        const res = await fetch(url, {
+            headers: {
+                'Accept': 'application/json',
+                'X-Subscription-Token': apiKey,
+            },
+        });
+
+        if (!res.ok) return `Brave API error: ${res.status}`;
+
+        const data = await res.json();
+        const results = (data.web?.results || []).slice(0, limit);
+
+        if (results.length === 0) return 'No results found.';
+
+        return results.map((r, i) =>
+            `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.description || ''}`
+        ).join('\n\n');
+    } catch (err) {
+        return `Search error: ${err.message}`;
+    }
+}
+
+async function searchSearxng(query, limit, baseUrl) {
+    try {
+        const url = `${baseUrl}/search?q=${encodeURIComponent(query)}&format=json&categories=general`;
+        const res = await fetch(url);
+
+        if (!res.ok) return `SearXNG error: ${res.status}`;
+
+        const data = await res.json();
+        const results = (data.results || []).slice(0, limit);
+
+        if (results.length === 0) return 'No results found.';
+
+        return results.map((r, i) =>
+            `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.content || ''}`
+        ).join('\n\n');
+    } catch (err) {
+        return `Search error: ${err.message}`;
+    }
+}

package/src/tools/write.mjs

@@ -0,0 +1,55 @@
+/**
+ * Write Tool — matches Claude Code's exact behavior.
+ *
+ * Features:
+ * - Creates parent directories if needed
+ * - Requires Read first for existing file overwrites
+ * - No README creation unless explicitly asked
+ */
+import fs from 'fs';
+import path from 'path';
+import { hasBeenRead, markRead } from './read.mjs';
+
+export const WriteTool = {
+    name: 'Write',
+    description: 'Write content to a file. Creates parent dirs if needed.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file_path: { type: 'string', description: 'Absolute path to the file' },
+            content: { type: 'string', description: 'The content to write' },
+        },
+        required: ['file_path', 'content'],
+    },
+    validateInput(input) {
+        const errors = [];
+        if (!input.file_path) errors.push('file_path required');
+        return errors;
+    },
+    async call(input) {
+        const filePath = path.resolve(input.file_path);
+
+        // Check if file already exists — require Read first for overwrites
+        if (fs.existsSync(filePath)) {
+            if (!hasBeenRead(filePath)) {
+                return `Error: File ${filePath} already exists. You must Read it first before overwriting.`;
+            }
+        }
+
+        // Create parent directory if it doesn't exist
+        const dir = path.dirname(filePath);
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        } catch (e) {
+            return `Error creating directory ${dir}: ${e.message}`;
+        }
+
+        try {
+            fs.writeFileSync(filePath, input.content);
+            markRead(filePath); // Mark as read after writing
+            return `File written: ${filePath}`;
+        } catch (e) {
+            return `Error writing file: ${e.message}`;
+        }
+    },
+};

package/src/ui/banner.mjs

@@ -0,0 +1,237 @@
+/**
+ * Banner & Branding — Tarang CLI startup display.
+ */
+
+import { execSync } from 'node:child_process';
+import * as path from 'node:path';
+
+// ANSI color helpers
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const BLUE = '\x1b[34m';
+const BOLD_GREEN = '\x1b[1;32m';
+const BOLD_CYAN = '\x1b[1;36m';
+
+const BANNER_ORCA = [
+    ' ██████╗  ██████╗   ██████╗  █████╗ ',
+    '██╔═══██╗ ██╔══██╗ ██╔════╝ ██╔══██╗',
+    '██║   ██║ ██████╔╝ ██║      ███████║',
+    '██║   ██║ ██╔══██╗ ██║      ██╔══██║',
+    '╚██████╔╝ ██║  ██║ ╚██████╗ ██║  ██║',
+    ' ╚═════╝  ╚═╝  ╚═╝  ╚═════╝ ╚═╝  ╚═╝',
+];
+
+/**
+ * Print the branded ASCII art banner.
+ */
+export function printBanner() {
+    process.stderr.write('\n');
+    for (const line of BANNER_ORCA) {
+        process.stderr.write(`  ${BOLD_CYAN}${line}${RESET}\n`);
+    }
+    process.stderr.write(`  ${DIM}Orchestration of Composable Agents${RESET}\n`);
+    process.stderr.write('\n');
+}
+
+/**
+ * Print project info bar with version, project name, and git info.
+ * @param {string} version
+ */
+export function printProjectInfo(version) {
+    const cwd = process.cwd();
+    const projectName = path.basename(cwd);
+    const gitInfo = getGitInfo(cwd);
+
+    const sep = `${DIM} │ ${RESET}`;
+    let info = `  ${DIM}v${version}${RESET}${sep}${BOLD}${projectName}${RESET}`;
+    if (gitInfo) {
+        info += `${sep}${YELLOW}${gitInfo}${RESET}`;
+    }
+
+    // Draw a boxed info bar
+    const barWidth = 60;
+    const topBorder = `${BLUE}┌${'─'.repeat(barWidth)}┐${RESET}`;
+    const bottomBorder = `${BLUE}└${'─'.repeat(barWidth)}┘${RESET}`;
+
+    process.stderr.write(`${topBorder}\n`);
+    process.stderr.write(`${BLUE}│${RESET} ${info}${' '.repeat(Math.max(0, barWidth - stripAnsi(info).length - 1))}${BLUE}│${RESET}\n`);
+    process.stderr.write(`${bottomBorder}\n`);
+}
+
+/**
+ * Print keyboard hints and usage tips.
+ */
+export function printHints() {
+    const env = process.env.TARANG_ENV || process.env.NODE_ENV || 'production';
+
+    process.stderr.write(`${GREEN}Type your instructions${RESET}, or ${CYAN}/help${RESET} for commands\n`);
+    process.stderr.write(`${DIM}Ctrl+C${RESET}${DIM}=exit  ${RESET}${DIM}/clear${RESET}${DIM}=reset  ${RESET}${DIM}/config${RESET}${DIM}=settings  ${RESET}${DIM}/login${RESET}${DIM}=auth${RESET}\n`);
+    process.stderr.write(`${DIM}env:${env}  models:configured via browser (/config)${RESET}\n`);
+    process.stderr.write('\n');
+}
+
+/**
+ * Print auth status indicators.
+ * @param {object} creds - { token, openRouterKey, anthropicKey, backendUrl, mode }
+ */
+export function printAuthStatus(creds) {
+    const check = `${GREEN}✓${RESET}`;
+    const cross = `${RED}✗${RESET}`;
+
+    const tokenOk = !!creds.token;
+    const env = process.env.TARANG_ENV || process.env.NODE_ENV || 'production';
+
+    process.stderr.write(`  Auth:     ${tokenOk ? `${check} logged in ${DIM}(/whoami for details)${RESET}` : `${cross} not logged in ${DIM}(/login)${RESET}`}\n`);
+    process.stderr.write(`  Env:      ${DIM}${env}${RESET}\n`);
+    process.stderr.write(`  Mode:     ${DIM}${creds.mode || 'auto'}${RESET}\n`);
+    process.stderr.write('\n');
+}
+
+/**
+ * Print config in a styled format.
+ * @param {object} creds
+ */
+export function printStyledConfig(creds) {
+    const check = `${GREEN}✓${RESET}`;
+    const cross = `${RED}✗${RESET}`;
+    const mask = (val) => {
+        if (!val) return `${cross} not set`;
+        if (val.length <= 8) return `${check} ****`;
+        return `${check} ${val.slice(0, 6)}...${val.slice(-4)}`;
+    };
+
+    process.stderr.write(`\n${BOLD}Orca Configuration${RESET} ${DIM}(~/.orca/config.json)${RESET}\n`);
+    process.stderr.write(`${'─'.repeat(50)}\n`);
+    process.stderr.write(`  Token:          ${mask(creds.token)}\n`);
+    process.stderr.write(`  OpenRouter:     ${mask(creds.openRouterKey)}\n`);
+    process.stderr.write(`  Anthropic:      ${mask(creds.anthropicKey)}\n`);
+    const env = process.env.TARANG_ENV || process.env.NODE_ENV || 'production';
+    process.stderr.write(`  Environment:    ${DIM}${env}${RESET}\n`);
+    process.stderr.write(`  Backend URL:    ${DIM}${creds.backendUrl}${RESET}\n`);
+    process.stderr.write(`  Mode:           ${DIM}${creds.mode || 'auto'}${RESET}\n`);
+    process.stderr.write('\n');
+}
+
+/**
+ * Print a goodbye message.
+ */
+export function printGoodbye() {
+    process.stderr.write(`\n${BOLD_CYAN}Goodbye!${RESET}\n\n`);
+}
+
+/**
+ * Get git branch and change count for current directory.
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function getGitInfo(cwd) {
+    try {
+        const branch = execSync('git branch --show-current', {
+            cwd, encoding: 'utf-8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+
+        if (!branch) return null;
+
+        const status = execSync('git status --porcelain', {
+            cwd, encoding: 'utf-8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+
+        const changes = status ? status.split('\n').filter(Boolean).length : 0;
+
+        if (changes > 0) {
+            return `\u2387 ${branch} (${changes} changed)`;
+        }
+        return `\u2387 ${branch}`;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Strip ANSI escape codes for length calculation.
+ */
+function stripAnsi(str) {
+    return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/**
+ * Branded HTML for OAuth success page.
+ */
+export function getLoginSuccessHTML() {
+    return `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>Orca - Login Successful</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: #0d1117;
+            color: #c9d1d9;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            min-height: 100vh;
+            margin: 0;
+        }
+        .container {
+            text-align: center;
+            padding: 40px;
+        }
+        .logo {
+            font-size: 48px;
+            font-weight: bold;
+            margin-bottom: 8px;
+        }
+        .dev { color: #3fb950; }
+        .orca { color: #58a6ff; }
+        .check {
+            font-size: 64px;
+            color: #3fb950;
+            margin: 24px 0;
+        }
+        h1 {
+            color: #f0f6fc;
+            font-size: 24px;
+            margin: 16px 0 8px;
+        }
+        p {
+            color: #8b949e;
+            font-size: 16px;
+        }
+        .hint {
+            margin-top: 32px;
+            padding: 16px;
+            background: #161b22;
+            border-radius: 8px;
+            border: 1px solid #30363d;
+        }
+        code {
+            background: #1f2937;
+            padding: 2px 6px;
+            border-radius: 4px;
+            color: #58a6ff;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="logo">
+            <span class="orca">ORCA</span>
+        </div>
+        <div class="check">&#10003;</div>
+        <h1>Login Successful!</h1>
+        <p>You can close this tab and return to your terminal.</p>
+        <div class="hint">
+            <p>Next step: set your API key</p>
+            <code>orca config --openrouter-key YOUR_KEY</code>
+        </div>
+    </div>
+</body>
+</html>`;
+}