homarus 0.1.0

package/dist/timer-service.js

@@ -0,0 +1,142 @@
+// CRC: crc-TimerService.md | Seq: seq-startup.md, seq-timer-fire.md
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { v4 as uuid } from "uuid";
+import { Cron } from "croner";
+export class TimerService {
+    timers = new Map();
+    storePath;
+    logger;
+    emitFn = null;
+    constructor(logger, storePath) {
+        this.logger = logger;
+        this.storePath = storePath;
+    }
+    setEmitter(fn) {
+        this.emitFn = fn;
+    }
+    // CRC: crc-TimerService.md — loadTimers()
+    loadTimers() {
+        if (!existsSync(this.storePath))
+            return;
+        try {
+            const data = JSON.parse(readFileSync(this.storePath, "utf-8"));
+            for (const config of data) {
+                this.timers.set(config.id ?? uuid(), { config });
+            }
+            this.logger.info("Loaded timers", { count: this.timers.size });
+        }
+        catch (err) {
+            this.logger.error("Failed to load timers", { error: String(err) });
+        }
+    }
+    // CRC: crc-TimerService.md — saveTimers()
+    saveTimers() {
+        const data = [...this.timers.values()].map((e) => e.config);
+        const dir = dirname(this.storePath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(this.storePath, JSON.stringify(data, null, 2));
+    }
+    // CRC: crc-TimerService.md — add()
+    add(config) {
+        const id = config.id ?? uuid();
+        config.id = id;
+        this.timers.set(id, { config });
+        this.startTimer(id);
+        this.saveTimers();
+        this.logger.info("Timer added", { id, name: config.name, type: config.type });
+        return id;
+    }
+    // CRC: crc-TimerService.md — remove()
+    remove(timerId) {
+        const entry = this.timers.get(timerId);
+        if (!entry)
+            return;
+        this.stopTimer(entry);
+        this.timers.delete(timerId);
+        this.saveTimers();
+        this.logger.info("Timer removed", { id: timerId });
+    }
+    // CRC: crc-TimerService.md — get()
+    get(timerId) {
+        return this.timers.get(timerId)?.config;
+    }
+    // CRC: crc-TimerService.md — getAll()
+    getAll() {
+        return [...this.timers.values()].map((e) => e.config);
+    }
+    // CRC: crc-TimerService.md — start()
+    start() {
+        for (const [id] of this.timers) {
+            this.startTimer(id);
+        }
+        this.logger.info("Timer service started", { count: this.timers.size });
+    }
+    // CRC: crc-TimerService.md — stop()
+    stop() {
+        for (const entry of this.timers.values()) {
+            this.stopTimer(entry);
+        }
+        this.saveTimers();
+        this.logger.info("Timer service stopped");
+    }
+    // CRC: crc-TimerService.md — onFire()
+    onFire(timerId) {
+        const entry = this.timers.get(timerId);
+        if (!entry || !this.emitFn)
+            return;
+        const event = {
+            id: uuid(),
+            type: "timer_fired",
+            source: `timer:${timerId}`,
+            timestamp: Date.now(),
+            payload: {
+                timerId,
+                name: entry.config.name,
+                prompt: entry.config.prompt,
+                model: entry.config.model,
+            },
+        };
+        this.logger.info("Timer fired", { id: timerId, name: entry.config.name });
+        this.emitFn(event);
+        // Auto-remove one-shot timers
+        if (entry.config.type === "once") {
+            this.timers.delete(timerId);
+            this.saveTimers();
+        }
+    }
+    startTimer(id) {
+        const entry = this.timers.get(id);
+        if (!entry)
+            return;
+        this.stopTimer(entry);
+        const { config } = entry;
+        switch (config.type) {
+            case "cron":
+                entry.job = new Cron(config.schedule, { timezone: config.timezone }, () => this.onFire(id));
+                break;
+            case "interval":
+                entry.timeout = setInterval(() => this.onFire(id), parseInt(config.schedule, 10));
+                break;
+            case "once": {
+                const fireAt = new Date(config.schedule).getTime();
+                const delay = Math.max(0, fireAt - Date.now());
+                entry.timeout = setTimeout(() => this.onFire(id), delay);
+                break;
+            }
+        }
+    }
+    stopTimer(entry) {
+        if (entry.job) {
+            entry.job.stop();
+            entry.job = undefined;
+        }
+        if (entry.timeout) {
+            clearTimeout(entry.timeout);
+            clearInterval(entry.timeout);
+            entry.timeout = undefined;
+        }
+    }
+}
+//# sourceMappingURL=timer-service.js.map

package/dist/tool-registry.d.ts

@@ -0,0 +1,29 @@
+import type { ToolDefinition, ToolResult, ToolContext, Logger } from "./types.js";
+export interface ToolPolicy {
+    name: string;
+    allow?: string[];
+    deny?: string[];
+}
+export declare class ToolRegistry {
+    private tools;
+    private policies;
+    private groups;
+    private logger;
+    constructor(logger: Logger);
+    register(tool: ToolDefinition): void;
+    unregister(name: string): void;
+    get(name: string): ToolDefinition | undefined;
+    getAll(): ToolDefinition[];
+    getForAgent(allowedTools?: string[]): ToolDefinition[];
+    execute(name: string, params: unknown, context: ToolContext): Promise<ToolResult>;
+    registerGroup(name: string, toolNames: string[]): void;
+    resolveGroup(groupName: string): string[];
+    addPolicy(policy: ToolPolicy): void;
+    checkPolicy(toolName: string, _context: ToolContext): boolean;
+    toSchemas(): Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.js

@@ -0,0 +1,100 @@
+const BUILTIN_GROUPS = {
+    "group:fs": ["read", "write", "edit", "glob", "grep"],
+    "group:runtime": ["bash", "git"],
+    "group:web": ["web_fetch", "web_search", "browser"],
+    "group:code": ["lsp"],
+    "group:memory": ["memory_search", "memory_get", "memory_store"],
+};
+export class ToolRegistry {
+    tools = new Map();
+    policies = [];
+    groups = new Map(Object.entries(BUILTIN_GROUPS));
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    // CRC: crc-ToolRegistry.md — register()
+    register(tool) {
+        this.tools.set(tool.name, tool);
+        this.logger.debug("Registered tool", { name: tool.name, source: tool.source });
+    }
+    // CRC: crc-ToolRegistry.md — unregister()
+    unregister(name) {
+        this.tools.delete(name);
+    }
+    // CRC: crc-ToolRegistry.md — get()
+    get(name) {
+        return this.tools.get(name);
+    }
+    // CRC: crc-ToolRegistry.md — getAll()
+    getAll() {
+        return [...this.tools.values()];
+    }
+    // CRC: crc-ToolRegistry.md — getForAgent()
+    getForAgent(allowedTools) {
+        const all = this.getAll();
+        if (!allowedTools)
+            return all;
+        // Resolve groups in the allow list
+        const resolved = new Set();
+        for (const name of allowedTools) {
+            const group = this.groups.get(name);
+            if (group) {
+                group.forEach((t) => resolved.add(t));
+            }
+            else {
+                resolved.add(name);
+            }
+        }
+        return all.filter((t) => resolved.has(t.name));
+    }
+    // CRC: crc-ToolRegistry.md — execute()
+    async execute(name, params, context) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return { output: "", error: `Unknown tool: ${name}` };
+        }
+        if (!this.checkPolicy(name, context)) {
+            return { output: "", error: `Tool ${name} denied by policy` };
+        }
+        const start = Date.now();
+        try {
+            const result = await tool.execute(params, context);
+            this.logger.debug("Tool executed", { name, durationMs: Date.now() - start });
+            return result;
+        }
+        catch (err) {
+            this.logger.error("Tool execution failed", { name, error: String(err) });
+            return { output: "", error: String(err) };
+        }
+    }
+    // CRC: crc-ToolRegistry.md — registerGroup()
+    registerGroup(name, toolNames) {
+        this.groups.set(name, toolNames);
+    }
+    // CRC: crc-ToolRegistry.md — resolveGroup()
+    resolveGroup(groupName) {
+        return this.groups.get(groupName) ?? [];
+    }
+    addPolicy(policy) {
+        this.policies.push(policy);
+    }
+    // CRC: crc-ToolRegistry.md — checkPolicy()
+    checkPolicy(toolName, _context) {
+        for (const policy of this.policies) {
+            if (policy.deny?.includes(toolName))
+                return false;
+            if (policy.allow && !policy.allow.includes(toolName))
+                return false;
+        }
+        return true;
+    }
+    toSchemas() {
+        return this.getAll().map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+        }));
+    }
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/tools/bash.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../types.js";
+export declare const bashTool: ToolDefinition;
+//# sourceMappingURL=bash.d.ts.map

package/dist/tools/bash.js

@@ -0,0 +1,48 @@
+// Built-in tool: bash — execute shell commands
+import { exec } from "node:child_process";
+const MAX_OUTPUT = 50_000; // chars
+export const bashTool = {
+    name: "bash",
+    description: "Execute a bash command and return stdout/stderr. Use for system commands, git operations, running scripts, installing packages, etc.",
+    parameters: {
+        type: "object",
+        properties: {
+            command: { type: "string", description: "The bash command to execute" },
+            timeout: { type: "number", description: "Timeout in milliseconds (default 120000)" },
+            workingDir: { type: "string", description: "Working directory for the command" },
+        },
+        required: ["command"],
+    },
+    source: "builtin",
+    async execute(params, context) {
+        const { command, timeout = 120_000, workingDir } = params;
+        if (context.sandbox) {
+            return { output: "", error: "bash tool is not available in sandbox mode" };
+        }
+        return new Promise((resolve) => {
+            const proc = exec(command, {
+                cwd: workingDir ?? context.workingDir,
+                timeout,
+                maxBuffer: 10 * 1024 * 1024, // 10MB
+                env: { ...process.env, TERM: "dumb" },
+            }, (error, stdout, stderr) => {
+                let output = stdout;
+                if (stderr)
+                    output += (output ? "\n" : "") + stderr;
+                if (output.length > MAX_OUTPUT) {
+                    output = output.slice(0, MAX_OUTPUT) + `\n... (truncated, ${output.length} total chars)`;
+                }
+                if (error && error.killed) {
+                    resolve({ output, error: `Command timed out after ${timeout}ms` });
+                }
+                else if (error) {
+                    resolve({ output, error: `Exit code ${error.code}: ${error.message}` });
+                }
+                else {
+                    resolve({ output });
+                }
+            });
+        });
+    },
+};
+//# sourceMappingURL=bash.js.map

package/dist/tools/browser.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../types.js";
+import type { BrowserManager } from "../browser-manager.js";
+export declare function createBrowserTool(browserManager: BrowserManager): ToolDefinition;
+//# sourceMappingURL=browser.d.ts.map

package/dist/tools/browser.js

@@ -0,0 +1,47 @@
+export function createBrowserTool(browserManager) {
+    return {
+        name: "browser",
+        description: `Control a headless browser. Actions: navigate (go to URL), click (click element by CSS selector), type (fill input by selector), screenshot (capture page as base64 PNG), content (get visible page text), evaluate (run JavaScript), back/forward (navigation history), wait (wait for selector or duration), scroll (scroll up/down).`,
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    description: "The browser action to perform",
+                    enum: ["navigate", "click", "type", "screenshot", "content", "evaluate", "back", "forward", "wait", "scroll"],
+                },
+                url: { type: "string", description: "URL to navigate to (for navigate action)" },
+                selector: { type: "string", description: "CSS selector for the target element (for click, type, wait)" },
+                text: { type: "string", description: "Text to type (for type action)" },
+                script: { type: "string", description: "JavaScript to evaluate (for evaluate action)" },
+                timeout: { type: "number", description: "Timeout in milliseconds" },
+                direction: { type: "string", description: "Scroll direction (for scroll action)", enum: ["up", "down"] },
+                pixels: { type: "number", description: "Pixels to scroll (for scroll action, default 500)" },
+            },
+            required: ["action"],
+        },
+        source: "builtin",
+        async execute(params, context) {
+            if (context.sandbox) {
+                return { output: "", error: "browser tool is not available in sandbox mode" };
+            }
+            const action = params;
+            const result = await browserManager.execute(action);
+            if (!result.success) {
+                return { output: "", error: result.error ?? "Browser action failed" };
+            }
+            // Build output with context
+            const parts = [];
+            if (result.url)
+                parts.push(`URL: ${result.url}`);
+            if (result.title)
+                parts.push(`Title: ${result.title}`);
+            if (result.data)
+                parts.push(result.data);
+            if (result.screenshot)
+                parts.push(`[Screenshot: ${result.screenshot.length} chars base64]`);
+            return { output: parts.join("\n") };
+        },
+    };
+}
+//# sourceMappingURL=browser.js.map

package/dist/tools/edit.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../types.js";
+export declare const editTool: ToolDefinition;
+//# sourceMappingURL=edit.d.ts.map

package/dist/tools/edit.js

@@ -0,0 +1,48 @@
+// Built-in tool: edit — find and replace text in a file
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+export const editTool = {
+    name: "edit",
+    description: "Perform an exact string replacement in a file. The old_string must be unique in the file unless replace_all is true.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Absolute or relative path to the file" },
+            old_string: { type: "string", description: "The exact text to find and replace" },
+            new_string: { type: "string", description: "The replacement text" },
+            replace_all: { type: "boolean", description: "Replace all occurrences (default false)" },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    source: "builtin",
+    async execute(params, context) {
+        const { path: filePath, old_string, new_string, replace_all = false } = params;
+        const absPath = resolve(context.workingDir, filePath);
+        if (context.sandbox) {
+            return { output: "", error: "edit tool is not available in sandbox mode" };
+        }
+        if (!existsSync(absPath)) {
+            return { output: "", error: `File not found: ${absPath}` };
+        }
+        const content = readFileSync(absPath, "utf-8");
+        if (!content.includes(old_string)) {
+            return { output: "", error: "old_string not found in file" };
+        }
+        if (!replace_all) {
+            const firstIdx = content.indexOf(old_string);
+            const secondIdx = content.indexOf(old_string, firstIdx + 1);
+            if (secondIdx !== -1) {
+                return { output: "", error: "old_string is not unique in the file. Provide more context or use replace_all." };
+            }
+        }
+        const updated = replace_all
+            ? content.split(old_string).join(new_string)
+            : content.replace(old_string, new_string);
+        writeFileSync(absPath, updated);
+        const count = replace_all
+            ? content.split(old_string).length - 1
+            : 1;
+        return { output: `Replaced ${count} occurrence(s) in ${absPath}` };
+    },
+};
+//# sourceMappingURL=edit.js.map

package/dist/tools/git.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../types.js";
+export declare const gitTool: ToolDefinition;
+//# sourceMappingURL=git.d.ts.map

package/dist/tools/git.js

@@ -0,0 +1,109 @@
+// Built-in tool: git — safe git operations with guardrails
+import { exec } from "node:child_process";
+// Actions that modify state — require confirmation context
+const WRITE_ACTIONS = new Set([
+    "add", "commit", "checkout", "pull", "push", "fetch",
+    "stash", "stash_pop", "merge", "rebase", "tag", "init", "clone",
+]);
+// Dangerous patterns that are always blocked
+const BLOCKED_PATTERNS = [
+    /--force\b/,
+    /push\s+--force/,
+    /reset\s+--hard/,
+    /clean\s+-f/,
+    /branch\s+-D/,
+    /--no-verify/,
+];
+function buildCommand(action, args, message) {
+    switch (action) {
+        case "status": return `git status${args ? " " + args : ""}`;
+        case "diff": return `git diff${args ? " " + args : ""}`;
+        case "log": return `git log --oneline -20${args ? " " + args : ""}`;
+        case "show": return `git show${args ? " " + args : " HEAD"}`;
+        case "branch": return `git branch${args ? " " + args : ""}`;
+        case "branches": return "git branch -a";
+        case "add": return `git add ${args ?? "."}`;
+        case "commit": {
+            if (!message)
+                return "echo 'Error: commit requires a message'";
+            return `git commit -m ${JSON.stringify(message)}`;
+        }
+        case "checkout": return `git checkout ${args ?? ""}`;
+        case "pull": return `git pull${args ? " " + args : ""}`;
+        case "push": return `git push${args ? " " + args : ""}`;
+        case "fetch": return `git fetch${args ? " " + args : " --all"}`;
+        case "stash": return `git stash${args ? " " + args : ""}`;
+        case "stash_pop": return "git stash pop";
+        case "merge": return `git merge ${args ?? ""}`;
+        case "rebase": return `git rebase ${args ?? ""}`;
+        case "blame": return `git blame ${args ?? ""}`;
+        case "tag": return `git tag ${args ?? ""}`;
+        case "tags": return "git tag -l";
+        case "remote": return `git remote ${args ?? "-v"}`;
+        case "init": return "git init";
+        case "clone": return `git clone ${args ?? ""}`;
+        default: return `git ${action}${args ? " " + args : ""}`;
+    }
+}
+export const gitTool = {
+    name: "git",
+    description: `Git operations with safety guardrails. Blocks force-push, hard reset, and destructive commands. Actions: status, diff, log, show, branch, branches, add, commit (requires message), checkout, pull, push, fetch, stash, stash_pop, merge, rebase, blame, tag, tags, remote, init, clone.`,
+    parameters: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                description: "The git action to perform",
+                enum: [
+                    "status", "diff", "log", "show", "branch", "branches",
+                    "add", "commit", "checkout", "pull", "push", "fetch",
+                    "stash", "stash_pop", "merge", "rebase",
+                    "blame", "tag", "tags", "remote", "init", "clone",
+                ],
+            },
+            args: { type: "string", description: "Additional arguments (e.g. file paths, branch names, flags)" },
+            message: { type: "string", description: "Commit message (required for commit action)" },
+            path: { type: "string", description: "Working directory for the git command" },
+        },
+        required: ["action"],
+    },
+    source: "builtin",
+    async execute(params, context) {
+        const { action, args, message, path } = params;
+        if (context.sandbox && WRITE_ACTIONS.has(action)) {
+            return { output: "", error: `git ${action} is not available in sandbox mode` };
+        }
+        const command = buildCommand(action, args, message);
+        // Safety check — block dangerous patterns
+        for (const pattern of BLOCKED_PATTERNS) {
+            if (pattern.test(command)) {
+                return { output: "", error: `Blocked: "${command}" matches dangerous pattern. Use bash tool directly if you really need this.` };
+            }
+        }
+        const cwd = path ? path : context.workingDir;
+        return new Promise((resolve) => {
+            exec(command, {
+                cwd,
+                timeout: 60_000,
+                maxBuffer: 5 * 1024 * 1024,
+                env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+            }, (error, stdout, stderr) => {
+                let output = stdout;
+                if (stderr) {
+                    // Git uses stderr for progress info — include it
+                    output += (output ? "\n" : "") + stderr;
+                }
+                if (output.length > 50_000) {
+                    output = output.slice(0, 50_000) + "\n... (truncated)";
+                }
+                if (error) {
+                    resolve({ output, error: `git ${action} failed (exit ${error.code}): ${error.message}` });
+                }
+                else {
+                    resolve({ output });
+                }
+            });
+        });
+    },
+};
+//# sourceMappingURL=git.js.map

package/dist/tools/glob.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../types.js";
+export declare const globTool: ToolDefinition;
+//# sourceMappingURL=glob.d.ts.map

package/dist/tools/glob.js

@@ -0,0 +1,86 @@
+// Built-in tool: glob — find files by pattern
+import { resolve } from "node:path";
+import { readdirSync, statSync, existsSync } from "node:fs";
+const MAX_RESULTS = 500;
+function minimatch(filePath, pattern) {
+    // Convert glob pattern to regex
+    let regex = pattern
+        .replace(/\./g, "\\.")
+        .replace(/\*\*/g, "⭐⭐") // placeholder
+        .replace(/\*/g, "[^/]*")
+        .replace(/⭐⭐/g, ".*")
+        .replace(/\?/g, "[^/]");
+    if (!regex.startsWith(".*") && !regex.startsWith("/")) {
+        regex = "(^|/)" + regex;
+    }
+    return new RegExp(regex + "$").test(filePath);
+}
+function walkDir(dir, pattern, results, maxDepth = 20, depth = 0) {
+    if (depth > maxDepth || results.length >= MAX_RESULTS)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // Permission denied or other read error
+    }
+    for (const entry of entries) {
+        if (results.length >= MAX_RESULTS)
+            return;
+        if (entry.name.startsWith(".") && !pattern.startsWith("."))
+            continue;
+        if (entry.name === "node_modules" || entry.name === ".git")
+            continue;
+        const fullPath = resolve(dir, entry.name);
+        if (entry.isDirectory()) {
+            walkDir(fullPath, pattern, results, maxDepth, depth + 1);
+        }
+        else if (entry.isFile()) {
+            // Match against relative path from search root
+            if (minimatch(fullPath, pattern) || minimatch(entry.name, pattern)) {
+                results.push(fullPath);
+            }
+        }
+    }
+}
+export const globTool = {
+    name: "glob",
+    description: 'Find files matching a glob pattern. Supports ** (any depth), * (single level), ? (single char). Excludes node_modules and .git. Examples: "**/*.ts", "src/**/test-*", "*.md"',
+    parameters: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: 'Glob pattern to match files (e.g. "**/*.ts", "src/**/*.test.ts")' },
+            path: { type: "string", description: "Directory to search in (default: working directory)" },
+        },
+        required: ["pattern"],
+    },
+    source: "builtin",
+    async execute(params, context) {
+        const { pattern, path: searchPath } = params;
+        const rootDir = searchPath ? resolve(context.workingDir, searchPath) : context.workingDir;
+        if (!existsSync(rootDir)) {
+            return { output: "", error: `Directory not found: ${rootDir}` };
+        }
+        const results = [];
+        walkDir(rootDir, pattern, results);
+        // Sort by modification time (newest first)
+        results.sort((a, b) => {
+            try {
+                return statSync(b).mtimeMs - statSync(a).mtimeMs;
+            }
+            catch {
+                return 0;
+            }
+        });
+        if (results.length === 0) {
+            return { output: "No files found" };
+        }
+        let output = results.join("\n");
+        if (results.length >= MAX_RESULTS) {
+            output += `\n... (truncated at ${MAX_RESULTS} results)`;
+        }
+        return { output };
+    },
+};
+//# sourceMappingURL=glob.js.map

package/dist/tools/grep.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../types.js";
+export declare const grepTool: ToolDefinition;
+//# sourceMappingURL=grep.d.ts.map