homarus 0.1.0

package/dist/browser-manager.d.ts

@@ -0,0 +1,33 @@
+import type { BrowserConfig, Logger } from "./types.js";
+export interface BrowserAction {
+    action: "navigate" | "click" | "type" | "screenshot" | "content" | "evaluate" | "back" | "forward" | "wait" | "scroll";
+    url?: string;
+    selector?: string;
+    text?: string;
+    script?: string;
+    timeout?: number;
+    direction?: "up" | "down";
+    pixels?: number;
+}
+export interface BrowserResult {
+    success: boolean;
+    data?: string;
+    screenshot?: string;
+    error?: string;
+    url?: string;
+    title?: string;
+}
+export declare class BrowserManager {
+    private browser;
+    private context;
+    private page;
+    private config;
+    private logger;
+    private launched;
+    constructor(logger: Logger, config?: BrowserConfig);
+    launch(): Promise<void>;
+    close(): Promise<void>;
+    isLaunched(): boolean;
+    execute(action: BrowserAction): Promise<BrowserResult>;
+}
+//# sourceMappingURL=browser-manager.d.ts.map

package/dist/browser-manager.js

@@ -0,0 +1,170 @@
+export class BrowserManager {
+    browser = null;
+    context = null;
+    page = null;
+    config;
+    logger;
+    launched = false;
+    constructor(logger, config = {}) {
+        this.logger = logger;
+        this.config = config;
+    }
+    async launch() {
+        if (this.launched)
+            return;
+        const modName = "playwright";
+        // Dynamic import — fails at runtime (not compile time) if playwright isn't installed
+        const pw = await import(modName).catch(() => {
+            throw new Error("playwright is not installed — run: npm install playwright");
+        });
+        const chromium = pw.chromium;
+        const launchOptions = {
+            headless: this.config.headless ?? true,
+        };
+        if (this.config.executablePath) {
+            launchOptions.executablePath = this.config.executablePath;
+        }
+        if (this.config.proxy) {
+            launchOptions.proxy = { server: this.config.proxy };
+        }
+        this.browser = await chromium.launch(launchOptions);
+        this.context = await this.browser.newContext({
+            viewport: this.config.viewport ?? { width: 1280, height: 720 },
+        });
+        this.page = await this.context.newPage();
+        this.page.setDefaultTimeout(this.config.timeout ?? 30_000);
+        this.launched = true;
+        this.logger.info("Browser launched", { headless: this.config.headless ?? true });
+    }
+    async close() {
+        if (!this.launched)
+            return;
+        await this.context?.close();
+        await this.browser?.close();
+        this.page = null;
+        this.context = null;
+        this.browser = null;
+        this.launched = false;
+        this.logger.info("Browser closed");
+    }
+    isLaunched() {
+        return this.launched;
+    }
+    async execute(action) {
+        if (!this.launched || !this.page) {
+            // Auto-launch on first use
+            await this.launch();
+            if (!this.page) {
+                return { success: false, error: "Browser failed to launch" };
+            }
+        }
+        const page = this.page;
+        const timeout = action.timeout ?? this.config.timeout ?? 30_000;
+        try {
+            switch (action.action) {
+                case "navigate": {
+                    if (!action.url)
+                        return { success: false, error: "url required for navigate" };
+                    await page.goto(action.url, { timeout, waitUntil: "domcontentloaded" });
+                    return {
+                        success: true,
+                        url: page.url(),
+                        title: await page.title(),
+                        data: `Navigated to ${page.url()}`,
+                    };
+                }
+                case "click": {
+                    if (!action.selector)
+                        return { success: false, error: "selector required for click" };
+                    await page.click(action.selector, { timeout });
+                    await page.waitForLoadState("domcontentloaded").catch(() => { });
+                    return {
+                        success: true,
+                        url: page.url(),
+                        data: `Clicked ${action.selector}`,
+                    };
+                }
+                case "type": {
+                    if (!action.selector)
+                        return { success: false, error: "selector required for type" };
+                    if (action.text === undefined)
+                        return { success: false, error: "text required for type" };
+                    await page.fill(action.selector, action.text, { timeout });
+                    return {
+                        success: true,
+                        data: `Typed into ${action.selector}`,
+                    };
+                }
+                case "screenshot": {
+                    const buffer = await page.screenshot({ fullPage: false, type: "png" });
+                    return {
+                        success: true,
+                        screenshot: buffer.toString("base64"),
+                        url: page.url(),
+                        title: await page.title(),
+                        data: `Screenshot captured (${buffer.length} bytes)`,
+                    };
+                }
+                case "content": {
+                    // Get visible text content, not raw HTML
+                    const text = await page.evaluate(() => {
+                        // Get innerText which respects visibility
+                        return document.body.innerText;
+                    });
+                    const truncated = text.length > 50_000
+                        ? text.slice(0, 50_000) + `\n... (truncated, ${text.length} total chars)`
+                        : text;
+                    return {
+                        success: true,
+                        data: truncated,
+                        url: page.url(),
+                        title: await page.title(),
+                    };
+                }
+                case "evaluate": {
+                    if (!action.script)
+                        return { success: false, error: "script required for evaluate" };
+                    const result = await page.evaluate(action.script);
+                    return {
+                        success: true,
+                        data: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                    };
+                }
+                case "back": {
+                    await page.goBack({ timeout });
+                    return { success: true, url: page.url(), data: "Navigated back" };
+                }
+                case "forward": {
+                    await page.goForward({ timeout });
+                    return { success: true, url: page.url(), data: "Navigated forward" };
+                }
+                case "wait": {
+                    if (action.selector) {
+                        await page.waitForSelector(action.selector, { timeout });
+                        return { success: true, data: `Element found: ${action.selector}` };
+                    }
+                    // Wait a fixed duration
+                    await page.waitForTimeout(action.timeout ?? 1000);
+                    return { success: true, data: `Waited ${action.timeout ?? 1000}ms` };
+                }
+                case "scroll": {
+                    const dir = action.direction ?? "down";
+                    const px = action.pixels ?? 500;
+                    const delta = dir === "down" ? px : -px;
+                    await page.evaluate((d) => window.scrollBy(0, d), delta);
+                    return { success: true, data: `Scrolled ${dir} ${px}px` };
+                }
+                default:
+                    return { success: false, error: `Unknown action: ${action.action}` };
+            }
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: String(err.message ?? err),
+                url: page.url(),
+            };
+        }
+    }
+}
+//# sourceMappingURL=browser-manager.js.map

package/dist/channel-adapter.d.ts

@@ -0,0 +1,29 @@
+import type { Event, MessagePayload, OutboundMessage, DmPolicy, GroupPolicy, HealthStatus, Logger } from "./types.js";
+export type AdapterState = "disconnected" | "connecting" | "connected" | "error";
+export declare abstract class ChannelAdapter {
+    readonly name: string;
+    protected state: AdapterState;
+    protected dmPolicy: DmPolicy;
+    protected groupPolicy: GroupPolicy;
+    protected logger: Logger;
+    private messageHandler;
+    constructor(name: string, logger: Logger, dmPolicy?: DmPolicy, groupPolicy?: GroupPolicy);
+    getState(): AdapterState;
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract send(target: string, message: OutboundMessage): Promise<void>;
+    abstract health(): HealthStatus;
+    onMessage(handler: (event: Event) => void): void;
+    protected normalizeInbound(payload: MessagePayload): Event;
+    protected checkAccess(payload: MessagePayload): boolean;
+    protected deliver(payload: MessagePayload): void;
+}
+export declare class CLIChannelAdapter extends ChannelAdapter {
+    private rl;
+    constructor(logger: Logger);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    send(_target: string, message: OutboundMessage): Promise<void>;
+    health(): HealthStatus;
+}
+//# sourceMappingURL=channel-adapter.d.ts.map

package/dist/channel-adapter.js

@@ -0,0 +1,94 @@
+// CRC: crc-ChannelAdapter.md | Seq: seq-message-dispatch.md
+import { v4 as uuid } from "uuid";
+export class ChannelAdapter {
+    name;
+    state = "disconnected";
+    dmPolicy;
+    groupPolicy;
+    logger;
+    messageHandler = null;
+    constructor(name, logger, dmPolicy = "open", groupPolicy = "mention_required") {
+        this.name = name;
+        this.logger = logger;
+        this.dmPolicy = dmPolicy;
+        this.groupPolicy = groupPolicy;
+    }
+    getState() {
+        return this.state;
+    }
+    // CRC: crc-ChannelAdapter.md — onMessage()
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    // CRC: crc-ChannelAdapter.md — normalizeInbound()
+    normalizeInbound(payload) {
+        return {
+            id: uuid(),
+            type: "message",
+            source: `channel:${this.name}`,
+            timestamp: Date.now(),
+            payload,
+        };
+    }
+    // CRC: crc-ChannelAdapter.md — checkAccess()
+    checkAccess(payload) {
+        if (payload.isGroup) {
+            if (this.groupPolicy === "disabled")
+                return false;
+            if (this.groupPolicy === "mention_required" && !payload.isMention)
+                return false;
+            return true;
+        }
+        // DM
+        if (this.dmPolicy === "disabled")
+            return false;
+        return true;
+    }
+    // Subclasses call this to deliver normalized events to the loop
+    deliver(payload) {
+        if (!this.checkAccess(payload)) {
+            this.logger.debug("Message rejected by policy", { channel: this.name, from: payload.from });
+            return;
+        }
+        const event = this.normalizeInbound(payload);
+        this.messageHandler?.(event);
+    }
+}
+// CLI channel adapter — reads from stdin, writes to stdout
+export class CLIChannelAdapter extends ChannelAdapter {
+    rl = null;
+    constructor(logger) {
+        super("cli", logger, "open", "always_on");
+    }
+    async connect() {
+        this.state = "connecting";
+        const { createInterface } = await import("node:readline");
+        this.rl = createInterface({ input: process.stdin });
+        this.rl.on("line", (line) => {
+            if (!line.trim())
+                return;
+            this.deliver({
+                from: "user",
+                channel: "cli",
+                text: line,
+                isGroup: false,
+                isMention: false,
+                raw: line,
+            });
+        });
+        this.state = "connected";
+        this.logger.info("CLI channel connected");
+    }
+    async disconnect() {
+        this.rl?.close();
+        this.rl = null;
+        this.state = "disconnected";
+    }
+    async send(_target, message) {
+        process.stdout.write(message.text + "\n");
+    }
+    health() {
+        return { healthy: this.state === "connected", lastCheck: Date.now() };
+    }
+}
+//# sourceMappingURL=channel-adapter.js.map

package/dist/channel-manager.d.ts

@@ -0,0 +1,17 @@
+import type { Event, OutboundMessage, ChannelConfig, HealthStatus, Logger } from "./types.js";
+import { ChannelAdapter } from "./channel-adapter.js";
+export declare class ChannelManager {
+    private adapters;
+    private logger;
+    private eventHandler;
+    constructor(logger: Logger);
+    setEventHandler(fn: (event: Event) => void): void;
+    loadAdapters(channels: Record<string, ChannelConfig>): void;
+    connectAll(): Promise<void>;
+    disconnectAll(): Promise<void>;
+    send(channel: string, target: string, message: OutboundMessage): Promise<void>;
+    getAdapter(name: string): ChannelAdapter | undefined;
+    getConnected(): ChannelAdapter[];
+    healthCheck(): Record<string, HealthStatus>;
+}
+//# sourceMappingURL=channel-manager.d.ts.map

package/dist/channel-manager.js

@@ -0,0 +1,84 @@
+import { CLIChannelAdapter } from "./channel-adapter.js";
+import { TelegramChannelAdapter } from "./telegram-adapter.js";
+export class ChannelManager {
+    adapters = new Map();
+    logger;
+    eventHandler = null;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    setEventHandler(fn) {
+        this.eventHandler = fn;
+    }
+    // CRC: crc-ChannelManager.md — loadAdapters()
+    loadAdapters(channels) {
+        for (const [name, config] of Object.entries(channels)) {
+            let adapter;
+            switch (name) {
+                case "cli":
+                    adapter = new CLIChannelAdapter(this.logger);
+                    break;
+                case "telegram":
+                    adapter = TelegramChannelAdapter.fromChannelConfig(config, this.logger);
+                    break;
+                default:
+                    this.logger.warn("Unknown channel type, skipping", { name });
+                    continue;
+            }
+            this.adapters.set(name, adapter);
+        }
+        // Always ensure CLI adapter exists as fallback
+        if (!this.adapters.has("cli")) {
+            this.adapters.set("cli", new CLIChannelAdapter(this.logger));
+        }
+    }
+    // CRC: crc-ChannelManager.md — connectAll()
+    async connectAll() {
+        for (const [name, adapter] of this.adapters) {
+            try {
+                adapter.onMessage((event) => this.eventHandler?.(event));
+                await adapter.connect();
+            }
+            catch (err) {
+                this.logger.error("Failed to connect channel", { name, error: String(err) });
+            }
+        }
+        this.logger.info("Channels connected", { count: this.adapters.size });
+    }
+    // CRC: crc-ChannelManager.md — disconnectAll()
+    async disconnectAll() {
+        for (const [name, adapter] of this.adapters) {
+            try {
+                await adapter.disconnect();
+            }
+            catch (err) {
+                this.logger.warn("Error disconnecting channel", { name, error: String(err) });
+            }
+        }
+    }
+    // CRC: crc-ChannelManager.md — send()
+    async send(channel, target, message) {
+        const adapter = this.adapters.get(channel);
+        if (!adapter) {
+            throw new Error(`Unknown channel: ${channel}`);
+        }
+        await adapter.send(target, message);
+    }
+    // CRC: crc-ChannelManager.md — getAdapter()
+    getAdapter(name) {
+        return this.adapters.get(name);
+    }
+    // CRC: crc-ChannelManager.md — getConnected()
+    getConnected() {
+        return [...this.adapters.values()].filter((a) => a.getState() === "connected");
+    }
+    // CRC: crc-ChannelManager.md — healthCheck()
+    healthCheck() {
+        const results = {};
+        for (const [name, adapter] of this.adapters) {
+            results[name] = adapter.health();
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=channel-manager.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// CRC: crc-CLI.md | Seq: seq-startup.md
+import { resolve } from "node:path";
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { Homarus } from "./homarus.js";
+import { runSetupWizard, buildConfigFromWizard } from "./setup-wizard.js";
+const logger = {
+    debug: (msg, meta) => { if (process.env.DEBUG)
+        console.error(`[DEBUG] ${msg}`, meta ?? ""); },
+    info: (msg, meta) => console.error(`[INFO] ${msg}`, meta ? JSON.stringify(meta) : ""),
+    warn: (msg, meta) => console.error(`[WARN] ${msg}`, meta ? JSON.stringify(meta) : ""),
+    error: (msg, meta) => console.error(`[ERROR] ${msg}`, meta ? JSON.stringify(meta) : ""),
+};
+const [, , command, ...args] = process.argv;
+const noWizard = args.includes("--no-wizard");
+async function main() {
+    switch (command) {
+        case "start":
+            return start();
+        case "init":
+            return init();
+        case "status":
+            return status();
+        case "config":
+            return configValidate();
+        case "skills":
+            return skillList();
+        case "install-daemon":
+            return installDaemon();
+        default:
+            printUsage();
+    }
+}
+// CRC: crc-CLI.md — start()
+async function start() {
+    const loop = new Homarus(logger, args[0]);
+    // Graceful shutdown on signals
+    const shutdown = async () => {
+        logger.info("Shutdown signal received");
+        await loop.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await loop.start();
+}
+// CRC: crc-CLI.md — init()
+async function init() {
+    const home = process.env.HOME ?? ".";
+    const configDir = resolve(home, ".homarus");
+    const configPath = resolve(configDir, "config.json");
+    const envPath = resolve(configDir, ".env");
+    if (existsSync(configPath)) {
+        logger.info("Config already exists", { path: configPath });
+        return;
+    }
+    mkdirSync(configDir, { recursive: true });
+    mkdirSync(resolve(configDir, "identity"), { recursive: true });
+    mkdirSync(resolve(configDir, "identity/overlays"), { recursive: true });
+    mkdirSync(resolve(configDir, "workspace"), { recursive: true });
+    mkdirSync(resolve(configDir, "memory"), { recursive: true });
+    mkdirSync(resolve(configDir, "skills"), { recursive: true });
+    let configObj;
+    let envLines = [];
+    if (noWizard || !process.stdin.isTTY) {
+        // Non-interactive: use defaults
+        configObj = {
+            models: {
+                default: "anthropic/claude-sonnet-4-5",
+                aliases: { smart: "anthropic/claude-opus-4-5", fast: "anthropic/claude-haiku-4-5" },
+                providers: {
+                    anthropic: { apiKey: "${ANTHROPIC_API_KEY}" },
+                },
+            },
+            channels: { cli: {} },
+            agents: { maxConcurrent: 5, defaultTimeout: 300000, defaultMaxTurns: 20 },
+            memory: { embedding: { provider: "ollama", model: "nomic-embed-text", baseUrl: "http://127.0.0.1:11434/v1" } },
+            skills: { paths: [resolve(configDir, "skills")] },
+            server: { port: 18800 },
+            timers: { enabled: true },
+            identity: { dir: resolve(configDir, "identity"), workspaceDir: resolve(configDir, "workspace") },
+        };
+    }
+    else {
+        // Interactive wizard
+        const result = await runSetupWizard();
+        const built = buildConfigFromWizard(result, configDir);
+        configObj = built.config;
+        envLines = built.envLines;
+    }
+    writeFileSync(configPath, JSON.stringify(configObj, null, 2));
+    writeFileSync(resolve(configDir, "identity/soul.md"), "# Soul\n\nYou are a helpful AI assistant.");
+    writeFileSync(resolve(configDir, "identity/user.md"), "# User\n\nNo user profile configured.");
+    if (envLines.length > 0) {
+        writeFileSync(envPath, envLines.join("\n") + "\n", { mode: 0o600 });
+        console.log(`Secrets written to ${envPath}`);
+    }
+    logger.info("Initialized homarus", { configDir });
+    console.log(`Config created at ${configPath}`);
+    if (noWizard || !process.stdin.isTTY) {
+        console.log("Edit the config to add your API keys and customize settings.");
+    }
+}
+// CRC: crc-CLI.md — status()
+async function status() {
+    const port = args[0] ?? "18800";
+    try {
+        const response = await fetch(`http://localhost:${port}/status`);
+        if (!response.ok) {
+            console.log(`Status check failed: ${response.status}`);
+            return;
+        }
+        const data = await response.json();
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch {
+        console.log("Event loop is not running or not reachable.");
+    }
+}
+// CRC: crc-CLI.md — configValidate()
+async function configValidate() {
+    const { Config } = await import("./config.js");
+    const config = new Config(logger, args[0]);
+    try {
+        config.load();
+        console.log("Config is valid.");
+    }
+    catch (err) {
+        console.error("Config validation failed:", String(err));
+        process.exit(1);
+    }
+}
+// CRC: crc-CLI.md — skillList()
+function skillList() {
+    console.log("Use `homarus status` to see loaded skills from a running instance.");
+}
+// CRC: crc-CLI.md — installDaemon()
+function installDaemon() {
+    const home = process.env.HOME ?? ".";
+    const platform = process.platform;
+    if (platform === "darwin") {
+        const plistPath = resolve(home, "Library/LaunchAgents/com.homarus.plist");
+        const nodePath = process.execPath;
+        const cliPath = resolve(import.meta.dirname ?? ".", "cli.js");
+        const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.homarus</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${cliPath}</string>
+    <string>start</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${home}/.homarus/stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>${home}/.homarus/stderr.log</string>
+</dict>
+</plist>`;
+        writeFileSync(plistPath, plist);
+        console.log(`LaunchAgent plist written to ${plistPath}`);
+        console.log("Run: launchctl load " + plistPath);
+    }
+    else {
+        // systemd
+        const servicePath = resolve(home, ".config/systemd/user/homarus.service");
+        const serviceDir = resolve(home, ".config/systemd/user");
+        mkdirSync(serviceDir, { recursive: true });
+        const nodePath = process.execPath;
+        const cliPath = resolve(import.meta.dirname ?? ".", "cli.js");
+        const unit = `[Unit]
+Description=Homarus Agent
+After=network.target
+
+[Service]
+ExecStart=${nodePath} ${cliPath} start
+Restart=on-failure
+RestartSec=5
+KillMode=control-group
+
+[Install]
+WantedBy=default.target
+`;
+        writeFileSync(servicePath, unit);
+        console.log(`Systemd service written to ${servicePath}`);
+        console.log("Run: systemctl --user daemon-reload && systemctl --user enable --now homarus");
+    }
+}
+function printUsage() {
+    console.log(`homarus - Event-driven AI agent coordinator
+
+Usage:
+  homarus start [config-path]   Start the event loop (foreground)
+  homarus init [--no-wizard]     Create config via interactive wizard (or defaults)
+  homarus status [port]         Show status of running instance
+  homarus config [config-path]  Validate config file
+  homarus skills                List loaded skills
+  homarus install-daemon        Install systemd/launchd service
+`);
+}
+main().catch((err) => {
+    logger.error("Fatal error", { error: String(err) });
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+import type { ConfigData, Logger } from "./types.js";
+export declare class Config {
+    private data;
+    private configPath;
+    private watching;
+    private logger;
+    constructor(logger: Logger, configPath?: string);
+    load(path?: string): ConfigData;
+    get<T = unknown>(key: string): T | undefined;
+    getSection<T = unknown>(section: string): T;
+    getAll(): ConfigData;
+    private resolveEnvVars;
+    private loadEnvFile;
+    startWatching(onChange: (safeChange: boolean) => void): void;
+    stopWatching(): void;
+    private isSafeChange;
+    private resolveConfigPath;
+    private merge;
+    private flatten;
+}
+//# sourceMappingURL=config.d.ts.map