daemora 1.0.0-alpha.0

package/dist/core/InboundDebouncer.js

@@ -0,0 +1,81 @@
+/**
+ * InboundDebouncer — batches rapid-fire inbound messages from the same
+ * session/channel into a single agent task.
+ *
+ * When messages arrive within the debounce window (default 1500ms),
+ * they're concatenated into one task input:
+ *
+ *   [Queued messages]
+ *   ---
+ *   Message 1: first
+ *   ---
+ *   Message 2: second
+ *
+ * First caller's promise resolves with the batched text; later callers
+ * get `null` — they must SKIP task creation (their message is already
+ * included in the first caller's batch).
+ *
+ * Ported from daemora-js core/MessageQueue.js. Most valuable when
+ * running channels (Telegram/Discord) where users burst-send; no-op
+ * for the CLI where each message waits on the previous response.
+ */
+const DEFAULT_WINDOW_MS = 1500;
+export class InboundDebouncer {
+    pending = new Map();
+    windowMs;
+    constructor(opts = {}) {
+        this.windowMs = Math.max(50, opts.windowMs ?? DEFAULT_WINDOW_MS);
+    }
+    /**
+     * Add a message to the per-session debounce queue. Returns a promise
+     * that resolves with the batched text once the window closes. If this
+     * caller's message is bundled into someone else's batch, resolves with
+     * `null` — the caller must not create a task.
+     */
+    debounce(sessionKey, message) {
+        return new Promise((resolve) => {
+            const existing = this.pending.get(sessionKey);
+            if (existing) {
+                existing.messages.push(message);
+                existing.resolvers.push(resolve);
+                clearTimeout(existing.timer);
+                existing.timer = setTimeout(() => this.flush(sessionKey), this.windowMs);
+                return;
+            }
+            const entry = {
+                messages: [message],
+                resolvers: [resolve],
+                timer: setTimeout(() => this.flush(sessionKey), this.windowMs),
+            };
+            this.pending.set(sessionKey, entry);
+        });
+    }
+    flush(sessionKey) {
+        const entry = this.pending.get(sessionKey);
+        if (!entry)
+            return;
+        this.pending.delete(sessionKey);
+        const batched = entry.messages.length === 1
+            ? entry.messages[0]
+            : `[Queued messages]\n---\n${entry.messages.map((m, i) => `Message ${i + 1}: ${m}`).join("\n---\n")}`;
+        // First resolver wins; others get null so callers know not to spawn tasks.
+        entry.resolvers[0]?.(batched);
+        for (let i = 1; i < entry.resolvers.length; i++) {
+            entry.resolvers[i]?.(null);
+        }
+    }
+    hasPending(sessionKey) {
+        return this.pending.has(sessionKey);
+    }
+    get debounceMs() { return this.windowMs; }
+    /** Cancel all pending batches (graceful shutdown). */
+    shutdown() {
+        for (const [key, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            for (const r of entry.resolvers)
+                r(null);
+            this.pending.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=InboundDebouncer.js.map

package/dist/core/InboundDebouncer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InboundDebouncer.js","sourceRoot":"","sources":["../../src/core/InboundDebouncer.ts"],"names":[],"mappings":"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"}

package/dist/core/LoopDetector.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LoopDetector — prevents the agent from burning tokens in repetitive
+ * tool call patterns. Ported from hermes tools/file_tools.py + daemora-js
+ * core/LoopDetector.js with four detection strategies:
+ *
+ *   1. Exact repeat: same tool + same params 3x in a row
+ *   2. Ping-pong: alternating A→B→A→B within a rolling window of 8
+ *   3. Semantic repeat: same tool + same param keys (ignoring values) 4+
+ *      times in the last 10 calls
+ *   4. Polling: same tool 8+ times in the last 10 regardless of params
+ *
+ * On block: returns a structured message the wrapper turns into a
+ * tool-error, so the model sees the error and gets a chance to change
+ * course. Cleanup is explicit — the TaskRunner calls `cleanup(taskId)`
+ * once the task ends.
+ *
+ * Wiring: see `wrapWithLoopDetection` in AgentLoop.
+ */
+import type { EventBus } from "../events/eventBus.js";
+export type LoopPattern = "exact_repeat" | "ping_pong" | "semantic_repeat" | "polling";
+export interface LoopCheckResult {
+    readonly blocked: boolean;
+    readonly pattern?: LoopPattern;
+    readonly message?: string;
+}
+export declare class LoopDetector {
+    private readonly bus?;
+    private readonly history;
+    constructor(bus?: EventBus | undefined);
+    /** Record a tool call and check for loop patterns. */
+    record(toolName: string, params: unknown, taskId: string): LoopCheckResult;
+    /** Drop task history once the task ends — prevents memory growth. */
+    cleanup(taskId: string): void;
+    private block;
+}
+//# sourceMappingURL=LoopDetector.d.ts.map

package/dist/core/LoopDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoopDetector.d.ts","sourceRoot":"","sources":["../../src/core/LoopDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAuBtD,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAEvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAQD,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IAFjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;gBAEhC,GAAG,CAAC,EAAE,QAAQ,YAAA;IAE3C,sDAAsD;IACtD,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe;IAuD1E,qEAAqE;IACrE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI7B,OAAO,CAAC,KAAK;CAKd"}

package/dist/core/LoopDetector.js

@@ -0,0 +1,139 @@
+/**
+ * LoopDetector — prevents the agent from burning tokens in repetitive
+ * tool call patterns. Ported from hermes tools/file_tools.py + daemora-js
+ * core/LoopDetector.js with four detection strategies:
+ *
+ *   1. Exact repeat: same tool + same params 3x in a row
+ *   2. Ping-pong: alternating A→B→A→B within a rolling window of 8
+ *   3. Semantic repeat: same tool + same param keys (ignoring values) 4+
+ *      times in the last 10 calls
+ *   4. Polling: same tool 8+ times in the last 10 regardless of params
+ *
+ * On block: returns a structured message the wrapper turns into a
+ * tool-error, so the model sees the error and gets a chance to change
+ * course. Cleanup is explicit — the TaskRunner calls `cleanup(taskId)`
+ * once the task ends.
+ *
+ * Wiring: see `wrapWithLoopDetection` in AgentLoop.
+ */
+import { createLogger } from "../util/logger.js";
+const log = createLogger("core.loop_detector");
+const WINDOW_SIZE = 10;
+const PING_PONG_WINDOW = 8;
+/** Tools where different param VALUES mean genuinely different operations. */
+const VALUE_SENSITIVE_TOOLS = new Set([
+    "read_file", "write_file", "edit_file", "apply_patch", "list_directory",
+    "glob", "grep",
+    "execute_command", "web_fetch", "web_search", "fetch_url",
+    "use_crew", "parallel_crew", "use_mcp",
+    "image_analysis", "image_ops", "generate_image", "generate_music", "generate_video",
+    "skill_view", "skill_manage",
+    "memory", "memory_save", "memory_recall", "session_search",
+    // Agent-management tools — every call has a distinct action/name/task
+    // payload, so identical-key/distinct-value calls (e.g. 4 cron adds with
+    // different schedules) must NOT trigger semantic_repeat.
+    "cron", "goal", "watcher", "manage_mcp", "manage_agents", "poll", "reload",
+]);
+export class LoopDetector {
+    bus;
+    history = new Map();
+    constructor(bus) {
+        this.bus = bus;
+    }
+    /** Record a tool call and check for loop patterns. */
+    record(toolName, params, taskId) {
+        const key = taskId || "_default";
+        let hist = this.history.get(key);
+        if (!hist) {
+            hist = [];
+            this.history.set(key, hist);
+        }
+        const paramHash = hashParams(toolName, params);
+        const exact = safeJson({ tool: toolName, params });
+        hist.push({ tool: toolName, exact, hash: paramHash });
+        if (hist.length > WINDOW_SIZE)
+            hist.shift();
+        // 1. Exact repeat
+        if (hist.length >= 3) {
+            const last3 = hist.slice(-3);
+            if (last3.every((h) => h.exact === last3[0].exact)) {
+                return this.block(toolName, taskId, "exact_repeat", `Tool "${toolName}" called 3× with identical params. Change your approach — try different parameters, a different tool, or re-read the context.`);
+            }
+        }
+        // 2. Ping-pong (A↔B or A→B→C→A→B→C)
+        if (hist.length >= 4) {
+            const recent = hist.slice(-PING_PONG_WINDOW);
+            const pp = detectPingPong(recent);
+            if (pp) {
+                const last4 = recent.slice(-4);
+                const toolsInPair = new Set(last4.map((h) => h.tool));
+                const allValueSensitive = [...toolsInPair].every((t) => VALUE_SENSITIVE_TOOLS.has(t));
+                const hasDistinctParams = new Set(last4.map((h) => h.hash)).size > 2;
+                // Different params each time on value-sensitive tools = legit verify-fix cycle
+                if (!(allValueSensitive && hasDistinctParams)) {
+                    return this.block(toolName, taskId, "ping_pong", `Detected ping-pong loop: ${pp}. You're alternating between the same tools without progress. Stop and try a completely different approach.`);
+                }
+            }
+        }
+        // 3. Semantic repeat
+        if (hist.length >= 4) {
+            const hashCount = hist.filter((h) => h.hash === paramHash).length;
+            if (hashCount >= 4) {
+                return this.block(toolName, taskId, "semantic_repeat", `Tool "${toolName}" called ${hashCount}× with similar params. You're repeating the same pattern. Try a fundamentally different approach.`);
+            }
+        }
+        // 4. Polling (high threshold — read/execute are legitimately frequent)
+        const toolCount = hist.filter((h) => h.tool === toolName).length;
+        if (toolCount >= 8) {
+            return this.block(toolName, taskId, "polling", `Tool "${toolName}" called ${toolCount}× in the last ${WINDOW_SIZE} steps. If polling for a result, stop and report the current status instead.`);
+        }
+        return { blocked: false };
+    }
+    /** Drop task history once the task ends — prevents memory growth. */
+    cleanup(taskId) {
+        this.history.delete(taskId || "_default");
+    }
+    block(toolName, taskId, pattern, message) {
+        log.info({ taskId: taskId.slice(0, 8), tool: toolName, pattern }, "loop detected");
+        this.bus?.emit("loop:detected", { taskId, toolName, pattern, message });
+        return { blocked: true, pattern, message };
+    }
+}
+function hashParams(toolName, params) {
+    if (!params || typeof params !== "object")
+        return `${toolName}:`;
+    const p = params;
+    if (VALUE_SENSITIVE_TOOLS.has(toolName)) {
+        const sorted = Object.keys(p).sort()
+            .map((k) => `${k}=${String(p[k]).slice(0, 80)}`)
+            .join(",");
+        return `${toolName}:${sorted}`;
+    }
+    const keys = Object.keys(p).sort().join(",");
+    return `${toolName}:${keys}`;
+}
+function detectPingPong(entries) {
+    if (entries.length < 4)
+        return null;
+    const last4 = entries.slice(-4).map((e) => e.tool);
+    if (last4[0] === last4[2] && last4[1] === last4[3] && last4[0] !== last4[1]) {
+        return `${last4[0]} ↔ ${last4[1]}`;
+    }
+    if (entries.length >= 6) {
+        const last6 = entries.slice(-6).map((e) => e.tool);
+        if (last6[0] === last6[3] && last6[1] === last6[4] && last6[2] === last6[5]
+            && (last6[0] !== last6[1] || last6[1] !== last6[2])) {
+            return `${last6[0]} → ${last6[1]} → ${last6[2]}`;
+        }
+    }
+    return null;
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v) ?? "";
+    }
+    catch {
+        return String(v);
+    }
+}
+//# sourceMappingURL=LoopDetector.js.map

package/dist/core/LoopDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoopDetector.js","sourceRoot":"","sources":["../../src/core/LoopDetector.ts"],"names":[],"mappings":"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"}

package/dist/core/TaskRunner.d.ts

@@ -0,0 +1,134 @@
+/**
+ * TaskRunner — the one place where an agent turn is driven end-to-end.
+ *
+ * Both `/api/chat` (HTTP SSE) and ChannelManager (Discord/Telegram/etc.)
+ * go through this runner so task persistence, session history, event
+ * emission, and error handling are identical across entry points.
+ *
+ * A run:
+ *   1. Resolves the session (creating it if needed for this sessionId).
+ *   2. Persists user message + task row (with channel metadata).
+ *   3. Drives AgentLoop, consuming its event stream.
+ *   4. Emits lifecycle events to the EventBus (streaming deltas, tool
+ *      calls, final state) — any subscriber keyed by taskId can react.
+ *   5. Optionally forwards the same events to a local callback (SSE).
+ *   6. Persists response messages to session history and writes the
+ *      terminal state to TaskStore.
+ *
+ * Returns a sync handle with `taskId`, `sessionId`, and a `done`
+ * promise that resolves with the terminal state.
+ */
+import type { ChannelMeta } from "../channels/BaseChannel.js";
+import type { ConfigManager } from "../config/ConfigManager.js";
+import type { EventBus } from "../events/eventBus.js";
+import type { HookRunner } from "../hooks/HookRunner.js";
+import type { BackgroundReviewer } from "../learning/BackgroundReviewer.js";
+import type { SessionStore } from "../memory/SessionStore.js";
+import type { TaskStore } from "../tasks/TaskStore.js";
+import type { CostTracker } from "../costs/CostTracker.js";
+import type { AgentLoop } from "./AgentLoop.js";
+import type { CompactionManager } from "./Compaction.js";
+import type { LoopDetector } from "./LoopDetector.js";
+import type { AttachmentProcessor } from "./AttachmentProcessor.js";
+export interface RunOptions {
+    readonly input: string;
+    readonly sessionId?: string;
+    readonly channel?: string;
+    readonly channelMeta?: ChannelMeta;
+    readonly model?: string;
+    /** Voice turns ask the agent to answer in spoken style. */
+    readonly voiceMode?: boolean;
+    /** Forwarded every event, for SSE emission on the chat route. */
+    readonly onLocal?: (event: string, data: unknown) => void;
+    /**
+     * Files the user sent along with their text. Resolved + inlined via
+     * AttachmentProcessor before the agent turn starts: images become
+     * inline content parts for multimodal models, audio is transcribed
+     * and merged into `input`, documents are text-extracted when
+     * possible and otherwise surfaced as "[file: /path]" hints so the
+     * agent can reach for read_file / execute_command.
+     */
+    readonly attachments?: ReadonlyArray<{
+        readonly kind: "image" | "audio" | "video" | "document" | "file";
+        readonly url?: string;
+        readonly path?: string;
+        readonly mimeType: string;
+        readonly filename?: string;
+        readonly size?: number;
+        readonly authHeader?: string;
+    }>;
+}
+export interface TerminalState {
+    readonly status: "completed" | "failed";
+    readonly result?: string;
+    readonly error?: string;
+}
+export interface RunHandle {
+    readonly taskId: string;
+    readonly sessionId: string;
+    readonly done: Promise<TerminalState>;
+}
+export declare class TaskRunner {
+    private readonly agent;
+    private readonly sessions;
+    private readonly tasks;
+    private readonly bus;
+    private readonly hooks?;
+    private readonly compaction?;
+    private readonly reviewer?;
+    private readonly dataDir?;
+    private readonly loopDetector?;
+    private readonly attachments?;
+    private readonly cfg?;
+    private readonly costs?;
+    /**
+     * Abort controllers for every in-flight task, keyed by taskId. Used
+     * by `cancel(taskId)` and by Supervisor-initiated kills. The entry
+     * is removed once `_execute` finishes (success or fail).
+     */
+    private readonly inflight;
+    /**
+     * Reverse index: which task is currently driving each session. Used
+     * by `send()` to detect "loop already running on this session — just
+     * inject into the pending queue instead of spawning a new parallel
+     * loop". Maintained in lockstep with `inflight`.
+     */
+    private readonly activeBySession;
+    constructor(agent: AgentLoop, sessions: SessionStore, tasks: TaskStore, bus: EventBus, hooks?: HookRunner | undefined, compaction?: CompactionManager | undefined, reviewer?: BackgroundReviewer | undefined, dataDir?: string | undefined, loopDetector?: LoopDetector | undefined, attachments?: AttachmentProcessor | undefined, cfg?: ConfigManager | undefined, costs?: CostTracker | undefined);
+    run(opts: RunOptions): RunHandle;
+    /**
+     * Single entry point for any source that wants to deliver a user
+     * message into a session (chat UI, crons, channels, webhooks, voice).
+     *
+     *   - If a loop is already driving this session: append the message
+     *     to the in-memory pending queue and return that existing task's
+     *     handle with `mode: "injected"`. The running loop will drain
+     *     the pending queue at its next safe boundary (between
+     *     streamText calls) and re-issue with the new history.
+     *
+     *   - If no loop is active on this session: enqueue the message and
+     *     spawn a fresh loop. Returns `mode: "fresh"` plus the new task
+     *     handle.
+     *
+     * The pending queue is in-memory only (lost on restart — clients
+     * resend). The drain only ever happens at iteration boundaries, so
+     * a user message is never appended in the middle of a tool call.
+     */
+    send(opts: RunOptions): {
+        mode: "fresh" | "injected";
+        taskId: string;
+        sessionId: string;
+        done?: Promise<TerminalState>;
+    };
+    /** List every running task id. */
+    inflightTaskIds(): readonly string[];
+    /**
+     * Abort a running task. Returns true if the task was live and got
+     * signalled; false if it had already finished. Supervisor uses this
+     * to enforce tool-call rate limits and budget guards.
+     */
+    cancel(taskId: string, reason?: string): boolean;
+    private resolveSession;
+    private _execute;
+}
+//# sourceMappingURL=TaskRunner.d.ts.map

package/dist/core/TaskRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskRunner.d.ts","sourceRoot":"","sources":["../../src/core/TaskRunner.ts"],"names":[],"mappings":"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"}