daemora 1.0.0-alpha.0

package/dist/core/AttachmentProcessor.js

@@ -0,0 +1,191 @@
+/**
+ * AttachmentProcessor — normalise inbound files into model-ready input.
+ *
+ * A channel / HTTP upload hands us one or more `InboundAttachment`s.
+ * Before the agent turn starts we:
+ *
+ *   1. Resolve each to a readable local path (downloading remote URLs
+ *      into `<dataDir>/inbox/` if needed).
+ *   2. Decide what to do based on kind/mime:
+ *        image  → emit an `image` content-part alongside the text turn
+ *                 (multimodal models see it inline)
+ *        audio  → transcribe via existing STT pipeline + merge text
+ *        text   → read the file and inline a bounded excerpt
+ *        other  → leave on disk, append a `[file: /path (mime, size)]`
+ *                 hint so the agent can reach for read_file / execute_command
+ *
+ * Returns the potentially-modified user text plus any image parts the
+ * caller should merge into the message content array. Failures never
+ * break the turn — the agent gets a best-effort result with any errors
+ * noted inline.
+ */
+import { mkdirSync, writeFileSync, statSync, existsSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join, extname } from "node:path";
+import { createLogger } from "../util/logger.js";
+import { transcribeAudioFile } from "../voice/transcribe.js";
+const log = createLogger("attachments");
+/** Size caps to keep model context from exploding. */
+const MAX_INLINE_TEXT_BYTES = 50_000;
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_AUDIO_BYTES = 25 * 1024 * 1024; // 25 MB — STT provider limit
+const MAX_FILE_PART_BYTES = 20 * 1024 * 1024; // 20 MB — provider file-upload cap (Anthropic + Google)
+/**
+ * MIME types we pass to the model as first-class `file` content parts
+ * (the AI SDK will forward them to provider-native document input
+ * channels on Anthropic / Google / OpenAI). Anything else gets either
+ * inlined as text (for small text files) or left on disk for the
+ * agent's filesystem tools to open explicitly.
+ */
+const FILE_PART_MIMES = new Set([
+    "application/pdf",
+]);
+export class AttachmentProcessor {
+    deps;
+    inboxDir;
+    constructor(deps) {
+        this.deps = deps;
+        this.inboxDir = join(deps.dataDir, "inbox");
+        try {
+            mkdirSync(this.inboxDir, { recursive: true });
+        }
+        catch {
+            // directory creation failures are reported lazily when we try to write
+        }
+    }
+    async process(baseText, attachments) {
+        if (!attachments || attachments.length === 0) {
+            return { text: baseText, imageParts: [], fileParts: [] };
+        }
+        const hints = [];
+        const images = [];
+        const files = [];
+        for (const att of attachments) {
+            try {
+                const localPath = await this.ensureLocal(att);
+                const size = sizeOf(localPath);
+                if (att.kind === "image" && size <= MAX_IMAGE_BYTES) {
+                    images.push({
+                        type: "image",
+                        image: readFileSync(localPath),
+                        mimeType: att.mimeType,
+                    });
+                    continue;
+                }
+                if (att.kind === "audio") {
+                    if (size > MAX_AUDIO_BYTES) {
+                        hints.push(`[audio: ${att.filename ?? basenameOf(localPath)} — too large to transcribe (${size} bytes), saved at ${localPath}]`);
+                        continue;
+                    }
+                    const transcript = await this.transcribe(localPath, att.mimeType);
+                    if (transcript) {
+                        hints.push(`[voice note transcript] ${transcript}`);
+                    }
+                    else {
+                        hints.push(`[audio: ${att.filename ?? basenameOf(localPath)} — transcription failed, saved at ${localPath}]`);
+                    }
+                    continue;
+                }
+                // PDFs (and future provider-supported doc types) go to the model
+                // as a first-class `file` content part — the provider sees the
+                // original bytes, keeping text + figures + layout intact. No
+                // local parsing that would strip structure.
+                if (FILE_PART_MIMES.has(att.mimeType) && size <= MAX_FILE_PART_BYTES) {
+                    files.push({
+                        type: "file",
+                        data: readFileSync(localPath),
+                        mimeType: att.mimeType,
+                        ...(att.filename ? { filename: att.filename } : {}),
+                    });
+                    continue;
+                }
+                if (isInlineableText(att.mimeType, localPath) && size <= MAX_INLINE_TEXT_BYTES) {
+                    const contents = readFileSync(localPath, "utf-8");
+                    hints.push(`[file: ${att.filename ?? basenameOf(localPath)}]\n${contents}`);
+                    continue;
+                }
+                // Fallback — oversized PDF, office doc, video, binary. Leave on
+                // disk with a minimal hint so the agent can reach for read_file
+                // / read_pdf / execute_command as needed.
+                hints.push(`[file attached: ${att.filename ?? basenameOf(localPath)} (${att.mimeType}, ${size} bytes) — saved at ${localPath}]`);
+            }
+            catch (e) {
+                log.warn({ err: e.message, kind: att.kind, url: att.url }, "attachment processing failed");
+                hints.push(`[file attach failed: ${att.filename ?? att.url ?? "?"} — ${e.message}]`);
+            }
+        }
+        const text = [baseText, ...hints].filter((s) => s && s.length > 0).join("\n\n");
+        return { text, imageParts: images, fileParts: files };
+    }
+    /**
+     * Return a local path for the attachment. If the channel already
+     * provided one we use it directly; otherwise we download the remote
+     * URL into the inbox directory and return the saved path.
+     */
+    async ensureLocal(att) {
+        if (att.path && existsSync(att.path))
+            return att.path;
+        if (!att.url)
+            throw new Error("attachment has neither path nor url");
+        const headers = {};
+        if (att.authHeader)
+            headers["Authorization"] = att.authHeader;
+        const resp = await fetch(att.url, { headers });
+        if (!resp.ok)
+            throw new Error(`fetch ${att.url} -> ${resp.status}`);
+        const buf = Buffer.from(await resp.arrayBuffer());
+        const ext = att.filename ? extname(att.filename) : guessExt(att.mimeType);
+        const name = `${Date.now()}-${randomUUID().slice(0, 8)}${ext}`;
+        const full = join(this.inboxDir, name);
+        writeFileSync(full, buf);
+        return full;
+    }
+    async transcribe(localPath, _mimeType) {
+        try {
+            const result = await transcribeAudioFile(this.deps.cfg, localPath);
+            return result?.text ?? null;
+        }
+        catch (e) {
+            log.warn({ err: e.message, path: localPath }, "transcription failed");
+            return null;
+        }
+    }
+}
+function sizeOf(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function basenameOf(path) {
+    return path.split("/").pop() ?? path;
+}
+function isInlineableText(mime, path) {
+    if (mime.startsWith("text/"))
+        return true;
+    if (mime === "application/json" || mime === "application/xml")
+        return true;
+    const ext = extname(path).toLowerCase();
+    return [".md", ".txt", ".log", ".csv", ".json", ".xml", ".yaml", ".yml", ".ini", ".toml"].includes(ext);
+}
+function guessExt(mime) {
+    const map = {
+        "image/png": ".png",
+        "image/jpeg": ".jpg",
+        "image/gif": ".gif",
+        "image/webp": ".webp",
+        "audio/ogg": ".ogg",
+        "audio/mpeg": ".mp3",
+        "audio/wav": ".wav",
+        "audio/mp4": ".m4a",
+        "audio/webm": ".webm",
+        "video/mp4": ".mp4",
+        "application/pdf": ".pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    };
+    return map[mime] ?? "";
+}
+//# sourceMappingURL=AttachmentProcessor.js.map

package/dist/core/AttachmentProcessor.js.map

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

package/dist/core/Compaction.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Compaction — hermes-pattern background context compression.
+ *
+ * Triggered when a session's estimated token count approaches the
+ * model's context window (threshold = min(contextWindow * 0.5,
+ * contextWindow - 20_000)). Runs in the background — the next turn
+ * awaits any pending compaction before building messages.
+ *
+ * Steps:
+ *   1. Anti-thrashing check (skip if last 2 passes saved <10%).
+ *   2. Protect first 3 messages + tail (~4k tokens).
+ *   3. Pre-prune: truncate / persist-to-disk huge tool outputs.
+ *   4. Summarise the pruned middle with the cheap model, structured
+ *      template: Resolved / Pending / Active Task / Files / Prefs.
+ *   5. Create a child session linked to the parent (compaction chain).
+ *   6. Copy the summary + tail messages to the child session; the
+ *      original session stays intact for audit.
+ *
+ * The caller receives the new sessionId to continue the conversation on.
+ */
+import type { EventBus } from "../events/eventBus.js";
+import type { SessionStore, SessionRow } from "../memory/SessionStore.js";
+import type { ModelRouter } from "../models/ModelRouter.js";
+export interface CompactionContext {
+    /** Model's advertised context window (tokens). */
+    readonly contextWindow: number;
+    /** Path to write large tool outputs to (relative to data dir). */
+    readonly dataDir: string;
+}
+export interface CompactionResult {
+    readonly triggered: boolean;
+    readonly newSessionId?: string;
+    readonly tokensBefore?: number;
+    readonly tokensAfter?: number;
+    readonly savingsPct?: number;
+    readonly skippedReason?: string;
+}
+export declare class CompactionManager {
+    private readonly sessions;
+    private readonly models;
+    private readonly bus?;
+    private readonly state;
+    constructor(sessions: SessionStore, models: ModelRouter, bus?: EventBus | undefined);
+    /**
+     * The session id a new turn should READ/WRITE from. Compaction may
+     * have rolled the session to a child; callers track the latest id
+     * here instead of holding a stale reference.
+     */
+    currentSessionId(originalId: string): string;
+    /** Block on any in-flight compaction for this session. No-op if none. */
+    awaitPending(sessionId: string): Promise<void>;
+    /**
+     * Check context pressure; if over threshold, kick off compaction in
+     * the background (no await). Returns immediately.
+     */
+    maybeCompactInBackground(sessionId: string, ctx: CompactionContext): void;
+    private getOrCreateState;
+    private runCompaction;
+    private buildSummary;
+}
+export { SessionRow };
+//# sourceMappingURL=Compaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Compaction.d.ts","sourceRoot":"","sources":["../../src/core/Compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAc,MAAM,2BAA2B,CAAC;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAc5D,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AASD,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IALvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;gBAGtC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,WAAW,EACnB,GAAG,CAAC,EAAE,QAAQ,YAAA;IAGjC;;;;OAIG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAK5C,yEAAyE;IACnE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD;;;OAGG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI;IAuBzE,OAAO,CAAC,gBAAgB;YASV,aAAa;YAyFb,YAAY;CA6B3B;AAgED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/core/Compaction.js

@@ -0,0 +1,260 @@
+/**
+ * Compaction — hermes-pattern background context compression.
+ *
+ * Triggered when a session's estimated token count approaches the
+ * model's context window (threshold = min(contextWindow * 0.5,
+ * contextWindow - 20_000)). Runs in the background — the next turn
+ * awaits any pending compaction before building messages.
+ *
+ * Steps:
+ *   1. Anti-thrashing check (skip if last 2 passes saved <10%).
+ *   2. Protect first 3 messages + tail (~4k tokens).
+ *   3. Pre-prune: truncate / persist-to-disk huge tool outputs.
+ *   4. Summarise the pruned middle with the cheap model, structured
+ *      template: Resolved / Pending / Active Task / Files / Prefs.
+ *   5. Create a child session linked to the parent (compaction chain).
+ *   6. Copy the summary + tail messages to the child session; the
+ *      original session stays intact for audit.
+ *
+ * The caller receives the new sessionId to continue the conversation on.
+ */
+import { generateText } from "ai";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../util/logger.js";
+import { msgText } from "../util/msgText.js";
+import { estimateTokens } from "../util/tokenEstimate.js";
+const log = createLogger("core.compaction");
+const PROTECT_HEAD = 3;
+const PROTECT_TAIL_TOKENS = 4_000;
+const TOOL_OUTPUT_MAX = 5_000;
+const TOOL_OUTPUT_PERSIST = 50_000;
+const SUMMARY_MAX_TOKENS = 1_500;
+const MIN_SAVINGS_PCT = 10;
+export class CompactionManager {
+    sessions;
+    models;
+    bus;
+    state = new Map();
+    constructor(sessions, models, bus) {
+        this.sessions = sessions;
+        this.models = models;
+        this.bus = bus;
+    }
+    /**
+     * The session id a new turn should READ/WRITE from. Compaction may
+     * have rolled the session to a child; callers track the latest id
+     * here instead of holding a stale reference.
+     */
+    currentSessionId(originalId) {
+        const st = this.state.get(originalId);
+        return st?.latestSessionId ?? originalId;
+    }
+    /** Block on any in-flight compaction for this session. No-op if none. */
+    async awaitPending(sessionId) {
+        const st = this.state.get(sessionId);
+        if (st?.pending) {
+            try {
+                await st.pending;
+            }
+            catch { /* failures shouldn't block the turn */ }
+        }
+    }
+    /**
+     * Check context pressure; if over threshold, kick off compaction in
+     * the background (no await). Returns immediately.
+     */
+    maybeCompactInBackground(sessionId, ctx) {
+        const threshold = Math.min(ctx.contextWindow * 0.5, ctx.contextWindow - 20_000);
+        const session = this.sessions.getSession(sessionId);
+        if (!session)
+            return;
+        const tokens = session.totalTokens > 0
+            ? session.totalTokens
+            : estimateTokens(this.sessions.getMessagesAsConversation(sessionId)
+                .map((m) => msgText(m.content)).join("\n"));
+        if (tokens < threshold)
+            return;
+        const st = this.getOrCreateState(sessionId);
+        if (st.pending)
+            return; // already in flight
+        log.info({ sessionId, tokens, threshold, contextWindow: ctx.contextWindow }, "compaction scheduled");
+        this.bus?.emit("compact:triggered", { sessionId, tokens, threshold });
+        st.pending = this.runCompaction(sessionId, ctx, tokens).finally(() => {
+            const s = this.state.get(sessionId);
+            if (s)
+                s.pending = null;
+        });
+    }
+    getOrCreateState(sessionId) {
+        let s = this.state.get(sessionId);
+        if (!s) {
+            s = { pending: null, recentSavings: [], latestSessionId: sessionId };
+            this.state.set(sessionId, s);
+        }
+        return s;
+    }
+    async runCompaction(sessionId, ctx, tokensBefore) {
+        const st = this.getOrCreateState(sessionId);
+        // Anti-thrashing: if the last two passes saved <10%, skip.
+        const recent = st.recentSavings.slice(-2);
+        if (recent.length >= 2 && recent.every((s) => s < MIN_SAVINGS_PCT)) {
+            log.info({ sessionId, recent }, "compaction skipped (anti-thrashing)");
+            this.bus?.emit("compact:skipped", { sessionId, reason: "anti_thrashing" });
+            return { triggered: false, skippedReason: "anti_thrashing" };
+        }
+        const session = this.sessions.getSession(sessionId);
+        if (!session)
+            return { triggered: false, skippedReason: "session_not_found" };
+        const messages = this.sessions.getMessagesFull(sessionId);
+        if (messages.length < PROTECT_HEAD + 4) {
+            return { triggered: false, skippedReason: "too_short" };
+        }
+        // Split into head (protected), middle (compact), tail (protected by token budget)
+        const head = messages.slice(0, PROTECT_HEAD);
+        const { tail, middle } = splitTailByTokenBudget(messages.slice(PROTECT_HEAD), PROTECT_TAIL_TOKENS);
+        if (middle.length === 0)
+            return { triggered: false, skippedReason: "nothing_to_compact" };
+        // Pre-prune giant tool outputs
+        const prunedMiddle = middle.map((m, i) => pruneLargeToolOutput(m, ctx.dataDir, sessionId, i));
+        // Summarise the middle
+        let summary;
+        try {
+            summary = await this.buildSummary(prunedMiddle);
+        }
+        catch (e) {
+            log.warn({ sessionId, err: e.message }, "summary failed — falling back to prune-only");
+            summary = `(summary unavailable — ${prunedMiddle.length} older messages pruned)`;
+        }
+        // Create child session + persist head, summary marker, tail
+        const child = this.sessions.createChildSession(session.id, {
+            title: session.title,
+            ...(session.modelHint ? { modelHint: session.modelHint } : {}),
+            ...(session.source ? { source: session.source } : {}),
+            ...(session.userId ? { userId: session.userId } : {}),
+            ...(session.systemPrompt ? { systemPrompt: session.systemPrompt } : {}),
+        });
+        for (const m of head) {
+            this.sessions.appendMessage(child.id, JSON.parse(m.contentJson), m.tokenCount);
+        }
+        const summaryMsg = {
+            role: "system",
+            content: [
+                "<conversation-summary>",
+                "The following is a summary of earlier conversation compacted to save context:",
+                "",
+                summary,
+                "</conversation-summary>",
+            ].join("\n"),
+        };
+        this.sessions.appendMessage(child.id, summaryMsg, estimateTokens(summary));
+        for (const m of tail) {
+            this.sessions.appendMessage(child.id, JSON.parse(m.contentJson), m.tokenCount);
+        }
+        const tokensAfter = (this.sessions.getSession(child.id)?.totalTokens) ?? estimateTokens(summary);
+        const savingsPct = tokensBefore > 0 ? Math.round(((tokensBefore - tokensAfter) / tokensBefore) * 100) : 0;
+        st.recentSavings.push(savingsPct);
+        if (st.recentSavings.length > 4)
+            st.recentSavings.shift();
+        st.latestSessionId = child.id;
+        log.info({
+            sessionId, newSessionId: child.id, tokensBefore, tokensAfter, savingsPct,
+        }, "compaction complete");
+        this.bus?.emit("compact:completed", {
+            sessionId, newSessionId: child.id, tokensBefore, tokensAfter, savingsPct,
+        });
+        return {
+            triggered: true,
+            newSessionId: child.id,
+            tokensBefore,
+            tokensAfter,
+            savingsPct,
+        };
+    }
+    async buildSummary(messages) {
+        const cheap = await this.models.getCheap();
+        const transcript = messages
+            .map((m) => {
+            const parsed = JSON.parse(m.contentJson);
+            return `[${m.role}] ${msgText(parsed.content).slice(0, 2000)}`;
+        })
+            .join("\n---\n");
+        const system = [
+            "You are compacting a conversation before it exceeds the model's context.",
+            "Produce a STRUCTURED summary using exactly these sections:",
+            "  ## Resolved",
+            "  ## Pending",
+            "  ## Active Task",
+            "  ## Files & Decisions",
+            "  ## User Preferences",
+            "Preserve: commands run, file paths touched, errors and how they were resolved,",
+            "user-stated constraints, and any half-finished work. Be concise but specific.",
+        ].join(" ");
+        const { text } = await generateText({
+            model: cheap.model,
+            system,
+            prompt: `Conversation to summarise:\n\n${transcript}`,
+            temperature: 0.1,
+        });
+        return text.trim();
+    }
+}
+function splitTailByTokenBudget(rest, budgetTokens) {
+    let used = 0;
+    const tailRev = [];
+    for (let i = rest.length - 1; i >= 0; i--) {
+        const m = rest[i];
+        const toks = m.tokenCount > 0
+            ? m.tokenCount
+            : estimateTokens(msgText(JSON.parse(m.contentJson).content));
+        if (used + toks > budgetTokens && tailRev.length >= 2)
+            break;
+        tailRev.push(m);
+        used += toks;
+    }
+    tailRev.reverse();
+    const middleCount = rest.length - tailRev.length;
+    return {
+        tail: tailRev,
+        middle: rest.slice(0, middleCount),
+    };
+}
+function pruneLargeToolOutput(m, dataDir, sessionId, stepIndex) {
+    if (m.role !== "tool")
+        return m;
+    const parsed = JSON.parse(m.contentJson);
+    const text = msgText(parsed.content);
+    if (text.length <= TOOL_OUTPUT_MAX)
+        return m;
+    // The tool role's content must be a ToolContent array (not a plain
+    // string). Build the replacement as a generic object and serialise —
+    // consumers parse it back through the SDK which validates shape.
+    if (text.length > TOOL_OUTPUT_PERSIST) {
+        const outDir = join(dataDir, "tool-outputs");
+        try {
+            mkdirSync(outDir, { recursive: true });
+        }
+        catch { }
+        const file = join(outDir, `${sessionId}-step${stepIndex}-${Date.now()}.txt`);
+        try {
+            writeFileSync(file, text, "utf-8");
+        }
+        catch { }
+        const replaced = {
+            ...parsed,
+            content: [{ type: "tool-result", toolCallId: "compacted", toolName: "compacted",
+                    output: { type: "text", value: `[Tool output (${text.length} chars) saved to disk: ${file}]` } }],
+        };
+        return { ...m, contentJson: JSON.stringify(replaced) };
+    }
+    const head = Math.floor(TOOL_OUTPUT_MAX * 0.6);
+    const tail = Math.floor(TOOL_OUTPUT_MAX * 0.3);
+    const truncated = `${text.slice(0, head)}\n\n[… truncated ${text.length - head - tail} chars …]\n\n${text.slice(-tail)}`;
+    const replaced = {
+        ...parsed,
+        content: [{ type: "tool-result", toolCallId: "compacted", toolName: "compacted",
+                output: { type: "text", value: truncated } }],
+    };
+    return { ...m, contentJson: JSON.stringify(replaced) };
+}
+//# sourceMappingURL=Compaction.js.map

package/dist/core/Compaction.js.map

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

package/dist/core/InboundDebouncer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+export interface DebouncerOptions {
+    readonly windowMs?: number;
+}
+export declare class InboundDebouncer {
+    private readonly pending;
+    private readonly windowMs;
+    constructor(opts?: DebouncerOptions);
+    /**
+     * 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: string, message: string): Promise<string | null>;
+    private flush;
+    hasPending(sessionKey: string): boolean;
+    get debounceMs(): number;
+    /** Cancel all pending batches (graceful shutdown). */
+    shutdown(): void;
+}
+//# sourceMappingURL=InboundDebouncer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InboundDebouncer.d.ts","sourceRoot":"","sources":["../../src/core/InboundDebouncer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAUD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,IAAI,GAAE,gBAAqB;IAIvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAmBrE,OAAO,CAAC,KAAK;IAgBb,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIvC,IAAI,UAAU,IAAI,MAAM,CAA0B;IAElD,sDAAsD;IACtD,QAAQ,IAAI,IAAI;CAOjB"}