homarus 0.1.0

package/dist/tools/web-search.js

@@ -0,0 +1,73 @@
+// Uses DuckDuckGo HTML search (no API key needed)
+async function duckduckgoSearch(query, limit) {
+    const encoded = encodeURIComponent(query);
+    const url = `https://html.duckduckgo.com/html/?q=${encoded}`;
+    const response = await fetch(url, {
+        headers: {
+            "User-Agent": "Mozilla/5.0 (compatible; Homarus/1.0)",
+        },
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!response.ok) {
+        throw new Error(`Search failed: HTTP ${response.status}`);
+    }
+    const html = await response.text();
+    const results = [];
+    // Parse DuckDuckGo HTML results
+    // Results are in <a class="result__a"> with <a class="result__snippet">
+    const resultBlocks = html.split("class=\"result__body\"");
+    for (let i = 1; i < resultBlocks.length && results.length < limit; i++) {
+        const block = resultBlocks[i];
+        // Extract URL and title from result__a
+        const linkMatch = block.match(/class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/);
+        if (!linkMatch)
+            continue;
+        let resultUrl = linkMatch[1];
+        // DuckDuckGo wraps URLs in a redirect — extract the actual URL
+        const uddgMatch = resultUrl.match(/uddg=([^&]*)/);
+        if (uddgMatch) {
+            resultUrl = decodeURIComponent(uddgMatch[1]);
+        }
+        const title = linkMatch[2].replace(/<[^>]+>/g, "").trim();
+        // Extract snippet
+        const snippetMatch = block.match(/class="result__snippet"[^>]*>([\s\S]*?)<\/a>/);
+        const snippet = snippetMatch
+            ? snippetMatch[1].replace(/<[^>]+>/g, "").trim()
+            : "";
+        if (title && resultUrl) {
+            results.push({ title, url: resultUrl, snippet });
+        }
+    }
+    return results;
+}
+export const webSearchTool = {
+    name: "web_search",
+    description: "Search the web and return results with titles, URLs, and snippets. Uses DuckDuckGo (no API key required).",
+    parameters: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "The search query" },
+            limit: { type: "number", description: "Maximum number of results (default 10)" },
+        },
+        required: ["query"],
+    },
+    source: "builtin",
+    async execute(params, context) {
+        if (context.sandbox) {
+            return { output: "", error: "web_search tool is not available in sandbox mode" };
+        }
+        const { query, limit = 10 } = params;
+        try {
+            const results = await duckduckgoSearch(query, limit);
+            if (results.length === 0) {
+                return { output: "No results found." };
+            }
+            const formatted = results.map((r, i) => `[${i + 1}] ${r.title}\n    ${r.url}\n    ${r.snippet}`).join("\n\n");
+            return { output: formatted };
+        }
+        catch (err) {
+            return { output: "", error: `Search failed: ${String(err.message ?? err)}` };
+        }
+    },
+};
+//# sourceMappingURL=web-search.js.map

package/dist/tools/write.d.ts

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

package/dist/tools/write.js

@@ -0,0 +1,31 @@
+// Built-in tool: write — create or overwrite a file
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+export const writeTool = {
+    name: "write",
+    description: "Write content to a file, creating it if it doesn't exist. Creates parent directories as needed. Overwrites existing files.",
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Absolute or relative path to the file" },
+            content: { type: "string", description: "The content to write to the file" },
+        },
+        required: ["path", "content"],
+    },
+    source: "builtin",
+    async execute(params, context) {
+        const { path: filePath, content } = params;
+        const absPath = resolve(context.workingDir, filePath);
+        if (context.sandbox) {
+            return { output: "", error: "write tool is not available in sandbox mode" };
+        }
+        const dir = dirname(absPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(absPath, content);
+        const lines = content.split("\n").length;
+        return { output: `Wrote ${lines} lines to ${absPath}` };
+    },
+};
+//# sourceMappingURL=write.js.map

package/dist/types.d.ts

@@ -0,0 +1,240 @@
+export interface Event {
+    id: string;
+    type: string;
+    source: string;
+    timestamp: number;
+    payload: unknown;
+    replyTo?: string;
+    priority?: number;
+}
+export interface MessagePayload {
+    from: string;
+    channel: string;
+    text: string;
+    attachments?: Attachment[];
+    replyTo?: string;
+    isGroup: boolean;
+    isMention: boolean;
+    raw: unknown;
+}
+export interface Attachment {
+    type: string;
+    url?: string;
+    data?: Buffer;
+    mimeType?: string;
+    filename?: string;
+}
+export interface OutboundMessage {
+    text: string;
+    attachments?: Attachment[];
+    replyTo?: string;
+}
+export type ExecutionStrategyType = "embedded" | "subprocess";
+export interface AgentConfig {
+    prompt: string;
+    model?: string;
+    tools?: string[];
+    timeout?: number;
+    maxTurns?: number;
+    systemPrompt?: string;
+    memory?: boolean;
+    sandbox?: boolean;
+    channel?: string;
+    taskOverlay?: string;
+    replyTo?: string;
+    executionStrategy?: ExecutionStrategyType;
+}
+export type AgentState = "pending" | "running" | "complete" | "failed" | "cancelled";
+export interface AgentResult {
+    output: string;
+    toolCalls: ToolCallRecord[];
+    usage: TokenUsage;
+}
+export interface ToolCallRecord {
+    tool: string;
+    params: unknown;
+    result: unknown;
+    durationMs: number;
+}
+export interface ChatRequest {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolSchema[];
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface ChatChunk {
+    content?: string;
+    toolCalls?: ToolCall[];
+    finishReason?: "stop" | "tool_calls" | "length" | "error";
+    usage?: TokenUsage;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface ModelInfo {
+    id: string;
+    name: string;
+    contextWindow?: number;
+    maxOutput?: number;
+}
+export interface AuthProfile {
+    apiKey: string;
+    cooldownUntil?: number;
+    failCount?: number;
+}
+export interface ToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (params: unknown, context: ToolContext) => Promise<ToolResult>;
+    source: string;
+}
+export interface ToolContext {
+    agentId: string;
+    sandbox: boolean;
+    workingDir: string;
+}
+export interface ToolResult {
+    output: string;
+    error?: string;
+}
+export interface SkillManifest {
+    name: string;
+    version: string;
+    description: string;
+    emits?: string[];
+    handles?: string[];
+    tools?: ToolSchema[];
+    process?: {
+        command: string;
+        args?: string[];
+        port?: number;
+        healthCheck?: string;
+    };
+    hooks?: {
+        onStart?: string;
+        onStop?: string;
+        onHealth?: string;
+    };
+}
+export type SkillState = "loaded" | "starting" | "running" | "stopping" | "stopped" | "error";
+export type TransportType = "http" | "stdio" | "direct";
+export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
+export type GroupPolicy = "mention_required" | "always_on" | "disabled";
+export interface HealthStatus {
+    healthy: boolean;
+    message?: string;
+    lastCheck: number;
+}
+export interface BrowserConfig {
+    enabled?: boolean;
+    headless?: boolean;
+    executablePath?: string;
+    proxy?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    timeout?: number;
+}
+export interface ConfigData {
+    models: ModelsConfig;
+    channels: Record<string, ChannelConfig>;
+    agents: AgentsConfig;
+    memory: MemoryConfig;
+    skills: SkillsConfig;
+    server: ServerConfig;
+    timers: TimersConfig;
+    identity: IdentityConfig;
+    browser?: BrowserConfig;
+}
+export interface ModelsConfig {
+    default: string;
+    fallback?: string[];
+    aliases?: Record<string, string>;
+    providers?: Record<string, ProviderConfig>;
+}
+export interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    profiles?: AuthProfile[];
+}
+export interface ChannelConfig {
+    token?: string;
+    dmPolicy?: DmPolicy;
+    groupPolicy?: GroupPolicy;
+    [key: string]: unknown;
+}
+export interface AgentsConfig {
+    maxConcurrent?: number;
+    defaultTimeout?: number;
+    defaultMaxTurns?: number;
+    defaultExecutionStrategy?: ExecutionStrategyType;
+}
+export interface MemoryConfig {
+    embedding?: {
+        provider: string;
+        model: string;
+        baseUrl?: string;
+        apiKey?: string;
+        dimensions?: number;
+    };
+    search?: {
+        vectorWeight?: number;
+        ftsWeight?: number;
+    };
+    extraPaths?: string[];
+}
+export interface SkillsConfig {
+    paths?: string[];
+}
+export interface ServerConfig {
+    port?: number;
+    auth?: {
+        token: string;
+    };
+}
+export interface TimersConfig {
+    enabled?: boolean;
+    store?: string;
+}
+export interface IdentityConfig {
+    dir?: string;
+    workspaceDir?: string;
+}
+export type DirectHandler = (event: Event) => void | Promise<void>;
+export interface AgentHandlerConfig {
+    id: string;
+    agentConfig: Partial<AgentConfig>;
+    buildPrompt?: (event: Event) => string;
+}
+export interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+export declare class HomarusError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, cause?: Error | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,14 @@
+// Shared types for homarus
+// CRC: crc-Homarus.md, crc-Agent.md, crc-Skill.md, crc-ModelProvider.md, crc-ChannelAdapter.md, crc-ToolRegistry.md
+// --- Errors ---
+export class HomarusError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = "HomarusError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "homarus",
+  "version": "0.1.0",
+  "description": "Event-loop based AI agent coordinator",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "homarus": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js start",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kcdjmaxx/HomarUS.git"
+  },
+  "author": "Max Ross",
+  "license": "MIT",
+  "homepage": "https://github.com/kcdjmaxx/HomarUS#readme",
+  "bugs": {
+    "url": "https://github.com/kcdjmaxx/HomarUS/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "coordinator",
+    "event-loop",
+    "llm",
+    "orchestration"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "better-sqlite3": "^11.7.0",
+    "croner": "^9.0.0",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "sqlite-vec": "^0.1.0",
+    "uuid": "^11.0.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.50.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}