homarus 0.1.0

package/dist/config.js

@@ -0,0 +1,185 @@
+// CRC: crc-Config.md | Seq: seq-startup.md
+import { readFileSync, existsSync, watchFile, unwatchFile } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { config as loadDotenv } from "dotenv";
+const DEFAULT_CONFIG = {
+    models: { default: "anthropic/claude-sonnet-4-5" },
+    channels: {},
+    agents: { maxConcurrent: 5, defaultTimeout: 300_000, defaultMaxTurns: 20 },
+    memory: { search: { vectorWeight: 0.7, ftsWeight: 0.3 } },
+    skills: { paths: [] },
+    server: { port: 18800 },
+    timers: { enabled: true },
+    identity: {},
+    browser: { enabled: false, headless: true },
+};
+// Keys that can be hot-reloaded without restart
+const SAFE_KEYS = new Set([
+    "models.aliases",
+    "models.fallback",
+    "agents.maxConcurrent",
+    "agents.defaultTimeout",
+    "agents.defaultMaxTurns",
+    "memory.search",
+    "skills.paths",
+    "timers.enabled",
+]);
+export class Config {
+    data = structuredClone(DEFAULT_CONFIG);
+    configPath;
+    watching = false;
+    logger;
+    constructor(logger, configPath) {
+        this.logger = logger;
+        this.configPath = configPath ?? this.resolveConfigPath();
+    }
+    // CRC: crc-Config.md — load()
+    load(path) {
+        if (path)
+            this.configPath = path;
+        this.loadEnvFile();
+        if (!existsSync(this.configPath)) {
+            this.logger.info("No config file found, using defaults", { path: this.configPath });
+            return this.data;
+        }
+        const raw = readFileSync(this.configPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const resolved = this.resolveEnvVars(parsed);
+        this.data = this.merge(DEFAULT_CONFIG, resolved);
+        this.logger.info("Config loaded", { path: this.configPath });
+        return this.data;
+    }
+    // CRC: crc-Config.md — get()
+    get(key) {
+        const parts = key.split(".");
+        let current = this.data;
+        for (const part of parts) {
+            if (current == null || typeof current !== "object")
+                return undefined;
+            current = current[part];
+        }
+        return current;
+    }
+    // CRC: crc-Config.md — getSection()
+    getSection(section) {
+        return this.data[section];
+    }
+    getAll() {
+        return this.data;
+    }
+    // CRC: crc-Config.md — resolveEnvVars()
+    resolveEnvVars(obj) {
+        if (typeof obj === "string") {
+            return obj.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+                return process.env[varName] ?? "";
+            });
+        }
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this.resolveEnvVars(item));
+        }
+        if (obj !== null && typeof obj === "object") {
+            const result = {};
+            for (const [key, value] of Object.entries(obj)) {
+                result[key] = this.resolveEnvVars(value);
+            }
+            return result;
+        }
+        return obj;
+    }
+    // CRC: crc-Config.md — loadEnvFile()
+    loadEnvFile() {
+        const envPath = resolve(dirname(this.configPath), ".env");
+        if (existsSync(envPath)) {
+            loadDotenv({ path: envPath });
+            this.logger.debug("Loaded .env file", { path: envPath });
+        }
+    }
+    // CRC: crc-Config.md — startWatching()
+    startWatching(onChange) {
+        if (this.watching)
+            return;
+        this.watching = true;
+        watchFile(this.configPath, { interval: 2000 }, () => {
+            try {
+                const oldData = structuredClone(this.data);
+                this.load();
+                const safe = this.isSafeChange(oldData, this.data);
+                if (!safe) {
+                    this.logger.warn("Config change requires restart for full effect");
+                }
+                onChange(safe);
+            }
+            catch (err) {
+                this.logger.error("Failed to reload config", { error: String(err) });
+            }
+        });
+    }
+    // CRC: crc-Config.md — stopWatching()
+    stopWatching() {
+        if (!this.watching)
+            return;
+        unwatchFile(this.configPath);
+        this.watching = false;
+    }
+    // CRC: crc-Config.md — isSafeChange()
+    isSafeChange(oldConfig, newConfig) {
+        const oldJson = JSON.stringify(oldConfig);
+        const newJson = JSON.stringify(newConfig);
+        if (oldJson === newJson)
+            return true;
+        // Check if only safe keys changed
+        const oldFlat = this.flatten(oldConfig);
+        const newFlat = this.flatten(newConfig);
+        const allKeys = new Set([...Object.keys(oldFlat), ...Object.keys(newFlat)]);
+        for (const key of allKeys) {
+            if (JSON.stringify(oldFlat[key]) !== JSON.stringify(newFlat[key])) {
+                const isSafe = [...SAFE_KEYS].some((sk) => key.startsWith(sk));
+                if (!isSafe)
+                    return false;
+            }
+        }
+        return true;
+    }
+    resolveConfigPath() {
+        // Check project-level first, then user-level
+        const projectPath = resolve(process.cwd(), "homarus.json");
+        if (existsSync(projectPath))
+            return projectPath;
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? "~";
+        return resolve(home, ".homarus", "config.json");
+    }
+    merge(defaults, overrides) {
+        const result = structuredClone(defaults);
+        for (const [key, value] of Object.entries(overrides)) {
+            if (value !== undefined && value !== null) {
+                const resultObj = result;
+                if (typeof value === "object" && !Array.isArray(value) && typeof resultObj[key] === "object") {
+                    resultObj[key] = {
+                        ...resultObj[key],
+                        ...value,
+                    };
+                }
+                else {
+                    resultObj[key] = value;
+                }
+            }
+        }
+        return result;
+    }
+    flatten(obj, prefix = "") {
+        const result = {};
+        if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+            for (const [key, value] of Object.entries(obj)) {
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                    Object.assign(result, this.flatten(value, fullKey));
+                }
+                else {
+                    result[fullKey] = value;
+                }
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/embedding-provider.d.ts

@@ -0,0 +1,35 @@
+import type { Logger } from "./types.js";
+import type { EmbeddingProvider } from "./memory-index.js";
+/**
+ * OpenAI-compatible embedding provider.
+ * Works with: OpenAI, Ollama (/v1/), LiteLLM, vLLM, LocalAI, etc.
+ */
+export declare class OpenAIEmbeddingProvider implements EmbeddingProvider {
+    private baseUrl;
+    private apiKey;
+    private model;
+    private dims;
+    private logger;
+    constructor(options: {
+        baseUrl: string;
+        apiKey?: string;
+        model: string;
+        dimensions: number;
+        logger: Logger;
+    });
+    dimensions(): number;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    private requestEmbeddings;
+}
+/**
+ * Create an embedding provider from HomarUS config.
+ */
+export declare function createEmbeddingProvider(config: {
+    provider: string;
+    model: string;
+    baseUrl?: string;
+    apiKey?: string;
+    dimensions?: number;
+}, logger: Logger): EmbeddingProvider;
+//# sourceMappingURL=embedding-provider.d.ts.map

package/dist/embedding-provider.js

@@ -0,0 +1,103 @@
+/**
+ * OpenAI-compatible embedding provider.
+ * Works with: OpenAI, Ollama (/v1/), LiteLLM, vLLM, LocalAI, etc.
+ */
+export class OpenAIEmbeddingProvider {
+    baseUrl;
+    apiKey;
+    model;
+    dims;
+    logger;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.apiKey = options.apiKey ?? "";
+        this.model = options.model;
+        this.dims = options.dimensions;
+        this.logger = options.logger;
+    }
+    dimensions() {
+        return this.dims;
+    }
+    async embed(text) {
+        const results = await this.embedBatch([text]);
+        return results[0];
+    }
+    async embedBatch(texts) {
+        // Ollama doesn't support batch API, so we fall back to sequential calls
+        // if batch fails. Most OpenAI-compatible APIs support array input though.
+        try {
+            return await this.requestEmbeddings(texts);
+        }
+        catch (err) {
+            // Fallback: sequential single requests
+            this.logger.debug("Batch embedding failed, falling back to sequential", { error: String(err) });
+            const results = [];
+            for (const text of texts) {
+                const [embedding] = await this.requestEmbeddings([text]);
+                results.push(embedding);
+            }
+            return results;
+        }
+    }
+    async requestEmbeddings(input) {
+        const body = {
+            model: this.model,
+            input: input.length === 1 ? input[0] : input,
+        };
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetch(`${this.baseUrl}/embeddings`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Embedding API error ${response.status}: ${errorText}`);
+        }
+        const data = (await response.json());
+        // Sort by index to ensure order matches input
+        const sorted = data.data.sort((a, b) => a.index - b.index);
+        return sorted.map((d) => d.embedding);
+    }
+}
+/**
+ * Create an embedding provider from HomarUS config.
+ */
+export function createEmbeddingProvider(config, logger) {
+    const baseUrl = config.baseUrl ?? getDefaultBaseUrl(config.provider);
+    const dimensions = config.dimensions ?? getDefaultDimensions(config.model);
+    return new OpenAIEmbeddingProvider({
+        baseUrl,
+        apiKey: config.apiKey,
+        model: config.model,
+        dimensions,
+        logger,
+    });
+}
+function getDefaultBaseUrl(provider) {
+    switch (provider) {
+        case "ollama": return "http://127.0.0.1:11434/v1";
+        case "openai": return "https://api.openai.com/v1";
+        default: return `https://api.${provider}.com/v1`;
+    }
+}
+function getDefaultDimensions(model) {
+    // Known model dimensions
+    if (model.includes("nomic-embed-text"))
+        return 768;
+    if (model.includes("all-minilm"))
+        return 384;
+    if (model.includes("text-embedding-3-small"))
+        return 1536;
+    if (model.includes("text-embedding-3-large"))
+        return 3072;
+    if (model.includes("text-embedding-ada"))
+        return 1536;
+    return 768; // sensible default
+}
+//# sourceMappingURL=embedding-provider.js.map

package/dist/event-bus.d.ts

@@ -0,0 +1,18 @@
+import type { DirectHandler, AgentHandlerConfig, Logger } from "./types.js";
+export interface HandlerSet {
+    direct: DirectHandler[];
+    agent: AgentHandlerConfig[];
+}
+export declare class EventBus {
+    private directHandlers;
+    private agentHandlers;
+    private logger;
+    constructor(logger: Logger);
+    registerDirect(eventType: string, handler: DirectHandler): void;
+    registerAgent(eventType: string, config: AgentHandlerConfig): void;
+    unregister(eventType: string, handlerId: string): void;
+    getHandlers(eventType: string): HandlerSet;
+    hasHandlers(eventType: string): boolean;
+    clear(): void;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/event-bus.js

@@ -0,0 +1,46 @@
+export class EventBus {
+    directHandlers = new Map();
+    agentHandlers = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    // CRC: crc-EventBus.md — registerDirect()
+    registerDirect(eventType, handler) {
+        const handlers = this.directHandlers.get(eventType) ?? [];
+        handlers.push(handler);
+        this.directHandlers.set(eventType, handlers);
+        this.logger.debug("Registered direct handler", { eventType });
+    }
+    // CRC: crc-EventBus.md — registerAgent()
+    registerAgent(eventType, config) {
+        const handlers = this.agentHandlers.get(eventType) ?? [];
+        handlers.push(config);
+        this.agentHandlers.set(eventType, handlers);
+        this.logger.debug("Registered agent handler", { eventType, handlerId: config.id });
+    }
+    // CRC: crc-EventBus.md — unregister()
+    unregister(eventType, handlerId) {
+        const agents = this.agentHandlers.get(eventType);
+        if (agents) {
+            this.agentHandlers.set(eventType, agents.filter((a) => a.id !== handlerId));
+        }
+    }
+    // CRC: crc-EventBus.md — getHandlers()
+    getHandlers(eventType) {
+        return {
+            direct: this.directHandlers.get(eventType) ?? [],
+            agent: this.agentHandlers.get(eventType) ?? [],
+        };
+    }
+    // CRC: crc-EventBus.md — hasHandlers()
+    hasHandlers(eventType) {
+        const { direct, agent } = this.getHandlers(eventType);
+        return direct.length > 0 || agent.length > 0;
+    }
+    clear() {
+        this.directHandlers.clear();
+        this.agentHandlers.clear();
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/event-queue.d.ts

@@ -0,0 +1,18 @@
+import type { Event, Logger } from "./types.js";
+export type OverflowStrategy = "drop_lowest" | "delay" | "reject";
+export declare class EventQueue {
+    private queue;
+    private maxSize;
+    private overflowStrategy;
+    private logger;
+    constructor(logger: Logger, maxSize?: number, overflowStrategy?: OverflowStrategy);
+    enqueue(event: Event): boolean;
+    dequeue(): Event | undefined;
+    peek(): Event | undefined;
+    size(): number;
+    isFull(): boolean;
+    clear(): Event[];
+    private insertByPriority;
+    private handleOverflow;
+}
+//# sourceMappingURL=event-queue.d.ts.map

package/dist/event-queue.js

@@ -0,0 +1,77 @@
+export class EventQueue {
+    queue = [];
+    maxSize;
+    overflowStrategy;
+    logger;
+    constructor(logger, maxSize = 1000, overflowStrategy = "drop_lowest") {
+        this.logger = logger;
+        this.maxSize = maxSize;
+        this.overflowStrategy = overflowStrategy;
+    }
+    // CRC: crc-EventQueue.md — enqueue()
+    enqueue(event) {
+        if (this.isFull()) {
+            return this.handleOverflow(event);
+        }
+        this.insertByPriority(event);
+        return true;
+    }
+    // CRC: crc-EventQueue.md — dequeue()
+    dequeue() {
+        return this.queue.shift();
+    }
+    // CRC: crc-EventQueue.md — peek()
+    peek() {
+        return this.queue[0];
+    }
+    // CRC: crc-EventQueue.md — size()
+    size() {
+        return this.queue.length;
+    }
+    // CRC: crc-EventQueue.md — isFull()
+    isFull() {
+        return this.queue.length >= this.maxSize;
+    }
+    // CRC: crc-EventQueue.md — clear()
+    clear() {
+        const remaining = [...this.queue];
+        this.queue = [];
+        return remaining;
+    }
+    insertByPriority(event) {
+        const priority = event.priority ?? 0;
+        // Higher priority = earlier in queue. Same priority = FIFO.
+        let i = this.queue.length;
+        while (i > 0 && (this.queue[i - 1].priority ?? 0) < priority) {
+            i--;
+        }
+        this.queue.splice(i, 0, event);
+    }
+    handleOverflow(event) {
+        switch (this.overflowStrategy) {
+            case "drop_lowest": {
+                // Drop the lowest priority event (last in queue)
+                const dropped = this.queue.pop();
+                if (dropped) {
+                    this.logger.warn("Queue full, dropped lowest priority event", {
+                        droppedId: dropped.id,
+                        droppedType: dropped.type,
+                    });
+                }
+                this.insertByPriority(event);
+                return true;
+            }
+            case "reject": {
+                this.logger.warn("Queue full, rejecting event", { eventId: event.id, eventType: event.type });
+                return false;
+            }
+            case "delay": {
+                // In delay mode, we still accept but log a warning
+                this.logger.warn("Queue at capacity, event delayed", { eventId: event.id, size: this.queue.length });
+                this.insertByPriority(event);
+                return true;
+            }
+        }
+    }
+}
+//# sourceMappingURL=event-queue.js.map

package/dist/execution-strategy.d.ts

@@ -0,0 +1,26 @@
+import type { AgentConfig, AgentResult, Event, Logger } from "./types.js";
+import { Agent } from "./agent.js";
+import type { ModelRouter } from "./model-router.js";
+import type { ToolRegistry } from "./tool-registry.js";
+import type { IdentityManager } from "./identity-manager.js";
+export interface ExecutionHandle {
+    readonly agentId: string;
+    cancel(): void;
+    readonly result: Promise<AgentResult>;
+    onEvent(fn: (event: Event) => void): void;
+    /** The Agent instance, available only for embedded strategy */
+    readonly agent?: Agent;
+}
+export interface ExecutionDeps {
+    modelRouter: ModelRouter;
+    toolRegistry: ToolRegistry;
+    identityManager: IdentityManager;
+    logger: Logger;
+}
+export interface ExecutionStrategy {
+    execute(config: AgentConfig, deps: ExecutionDeps): ExecutionHandle;
+}
+export declare class EmbeddedStrategy implements ExecutionStrategy {
+    execute(config: AgentConfig, deps: ExecutionDeps): ExecutionHandle;
+}
+//# sourceMappingURL=execution-strategy.d.ts.map

package/dist/execution-strategy.js

@@ -0,0 +1,20 @@
+import { Agent } from "./agent.js";
+// Wraps the existing Agent class — same behavior as the original AgentManager.spawn()
+export class EmbeddedStrategy {
+    execute(config, deps) {
+        const agent = new Agent(config, deps.modelRouter, deps.toolRegistry, deps.identityManager, deps.logger);
+        let eventListener = null;
+        agent.setEmitter((event) => {
+            eventListener?.(event);
+        });
+        const resultPromise = agent.run();
+        return {
+            agentId: agent.id,
+            cancel: () => agent.cancel(),
+            result: resultPromise,
+            onEvent: (fn) => { eventListener = fn; },
+            agent,
+        };
+    }
+}
+//# sourceMappingURL=execution-strategy.js.map

package/dist/homarus.d.ts

@@ -0,0 +1,36 @@
+import type { Event, AgentConfig, Logger } from "./types.js";
+export type LoopState = "starting" | "running" | "stopping" | "stopped";
+export declare class Homarus {
+    private state;
+    private config;
+    private eventBus;
+    private eventQueue;
+    private agentManager;
+    private skillManager;
+    private channelManager;
+    private toolRegistry;
+    private modelRouter;
+    private memoryIndex;
+    private identityManager;
+    private timerService;
+    private httpApi;
+    private browserManager;
+    private logger;
+    private processing;
+    private processInterval;
+    constructor(logger: Logger, configPath?: string);
+    getState(): LoopState;
+    emit(event: Event): void;
+    registerHandler(eventType: string, handler: (event: Event) => void | Promise<void>): void;
+    registerAgentHandler(eventType: string, agentConfig: Partial<AgentConfig>, buildPrompt?: (event: Event) => string): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private processEvent;
+    private startProcessing;
+    private stopProcessing;
+    private processNext;
+    private registerDefaultHandlers;
+    private initProviders;
+    private getStatus;
+}
+//# sourceMappingURL=homarus.d.ts.map