charness 0.0.0-stage → 3.0.0

package/dist/utils/fileSendService.js

@@ -0,0 +1,387 @@
+"use strict";
+/**
+ * @description Reusable agent→Telegram file-send pipeline. The factory owns the
+ * impure path resolution/snapshot work and executes the pure plan/request through
+ * an injected typed gateway. Each canonical file is opened component-by-component
+ * beneath a pinned root descriptor, identity-checked, and owned through delivery bookkeeping.
+ * Bot-specific stream creation and routing stay in the gateway; pacing/retry is
+ * injected through `executeDelivery`. The service imports neither MCP nor Telegraf.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileSendSnapshotConcurrency = exports.FileSendDeliveryUnknownError = void 0;
+exports.getFileDescriptorPathRoot = getFileDescriptorPathRoot;
+exports.readTelegramFileSnapshot = readTelegramFileSnapshot;
+exports.createSendFilesToThread = createSendFilesToThread;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const utils_1 = require("../utils");
+const abortableFifo_1 = require("./abortableFifo");
+const fileSendPlan_1 = require("./fileSendPlan");
+/** Telegram may have accepted the request, but the response never confirmed it. */
+class FileSendDeliveryUnknownError extends Error {
+    constructor(cause) {
+        super(`Telegram delivery outcome is unknown: ${cause.message}`, { cause });
+        this.name = 'FileSendDeliveryUnknownError';
+    }
+}
+exports.FileSendDeliveryUnknownError = FileSendDeliveryUnknownError;
+/** Bound descriptor-owning operations while Telegram's own queues are occupied. */
+exports.fileSendSnapshotConcurrency = 4;
+/** Linux exposes descriptor-relative child lookup; other platforms fail closed. */
+function getFileDescriptorPathRoot(platform) {
+    return platform === 'linux' ? '/proc/self/fd' : null;
+}
+const fileDescriptorPathRoot = getFileDescriptorPathRoot(process.platform);
+const directoryOpenFlags = fs.constants.O_RDONLY |
+    fs.constants.O_DIRECTORY |
+    fs.constants.O_NOFOLLOW |
+    fs.constants.O_NONBLOCK;
+const fileOpenFlags = fs.constants.O_RDONLY |
+    fs.constants.O_NOFOLLOW |
+    fs.constants.O_NONBLOCK;
+/** Canonicalize and pin the operation root before resolving any send item. */
+function openPinnedFileSendRoot(workDir) {
+    if (fileDescriptorPathRoot === null) {
+        throw new Error(`secure file sending is unsupported on ${process.platform}`);
+    }
+    const rootPath = fs.realpathSync(workDir);
+    return {
+        rootPath,
+        fd: fs.openSync(rootPath, directoryOpenFlags),
+    };
+}
+/** Close one descriptor and return a readable failure instead of throwing. */
+function closeFileDescriptor(fileDescriptor) {
+    try {
+        fs.closeSync(fileDescriptor);
+        return null;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'unknown error';
+        return `cannot close file descriptor: ${errorMessage}`;
+    }
+}
+/** Address one child through its already-open parent directory descriptor. */
+function getDescriptorChildPath(parentDescriptor, childName) {
+    if (fileDescriptorPathRoot === null) {
+        throw new Error(`secure file sending is unsupported on ${process.platform}`);
+    }
+    return path.posix.join(fileDescriptorPathRoot, parentDescriptor.toString(), childName);
+}
+/**
+ * Open a canonical file beneath its canonical root without resolving any
+ * caller-controlled parent component twice. Each directory descriptor pins the
+ * next lookup, and O_NOFOLLOW rejects a component swapped to a symlink.
+ */
+function openFileBeneathRoot(pinnedRoot, absPath) {
+    const relativePath = path.relative(pinnedRoot.rootPath, absPath);
+    if (relativePath.length === 0 ||
+        relativePath === '..' ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        throw new Error(`file is outside its validated root: ${absPath}`);
+    }
+    if (fileDescriptorPathRoot === null) {
+        throw new Error(`secure file sending is unsupported on ${process.platform}`);
+    }
+    const pathComponents = relativePath.split(path.sep);
+    const fileName = pathComponents[pathComponents.length - 1];
+    const directoryComponents = pathComponents.slice(0, -1);
+    const directoryDescriptors = [];
+    let fileDescriptor = null;
+    let openError = null;
+    try {
+        let parentDescriptor = pinnedRoot.fd;
+        for (const directoryName of directoryComponents) {
+            parentDescriptor = fs.openSync(getDescriptorChildPath(parentDescriptor, directoryName), directoryOpenFlags);
+            directoryDescriptors.push(parentDescriptor);
+        }
+        fileDescriptor = fs.openSync(getDescriptorChildPath(parentDescriptor, fileName), fileOpenFlags);
+    }
+    catch (error) {
+        openError = error instanceof Error ? error.message : 'unknown error';
+    }
+    let closeError = null;
+    for (const directoryDescriptor of directoryDescriptors.reverse()) {
+        const descriptorCloseError = closeFileDescriptor(directoryDescriptor);
+        if (closeError === null && descriptorCloseError !== null) {
+            closeError = descriptorCloseError;
+        }
+    }
+    if (openError !== null || closeError !== null || fileDescriptor === null) {
+        if (fileDescriptor !== null) {
+            const descriptorCloseError = closeFileDescriptor(fileDescriptor);
+            if (closeError === null && descriptorCloseError !== null) {
+                closeError = descriptorCloseError;
+            }
+        }
+        throw new Error([openError, closeError, fileDescriptor === null && openError === null ? 'file open failed' : null]
+            .filter((errorMessage) => errorMessage !== null)
+            .join('; '));
+    }
+    return fileDescriptor;
+}
+/**
+ * @description Open one already-canonical path beneath its pinned canonical root
+ * without following swapped parent/final symlinks, validate the opened object's
+ * bigint device/inode identity and size, then transfer ownership of the still-open
+ * descriptor to the caller. Every failure closes the descriptor before returning.
+ */
+function readTelegramFileSnapshot(absPath, expectedIdentity, pinnedRoot) {
+    let fileDescriptor = null;
+    let result;
+    try {
+        fileDescriptor = openFileBeneathRoot(pinnedRoot, absPath);
+        const fileStat = fs.fstatSync(fileDescriptor, { bigint: true });
+        if (!fileStat.isFile()) {
+            result = { ok: false, kind: 'read', error: `not a regular file: ${absPath}` };
+        }
+        else if (fileStat.dev !== expectedIdentity.dev || fileStat.ino !== expectedIdentity.ino) {
+            result = { ok: false, kind: 'read', error: `file changed after validation: ${absPath}` };
+        }
+        else if (fileStat.size > BigInt(fileSendPlan_1.telegramSendMaxBytes)) {
+            result = {
+                ok: false,
+                kind: 'oversize',
+                error: (0, fileSendPlan_1.getTelegramFileOversizeError)(absPath),
+            };
+        }
+        else {
+            result = {
+                ok: true,
+                source: {
+                    fd: fileDescriptor,
+                    filename: (0, fileSendPlan_1.getTelegramUploadFilename)(absPath),
+                    sizeBytes: Number(fileStat.size),
+                },
+            };
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'unknown error';
+        result = { ok: false, kind: 'read', error: errorMessage };
+    }
+    if (!result.ok && fileDescriptor !== null) {
+        const descriptorCloseError = closeFileDescriptor(fileDescriptor);
+        if (descriptorCloseError !== null) {
+            return {
+                ok: false,
+                kind: 'read',
+                error: `${result.error}; ${descriptorCloseError}`,
+            };
+        }
+    }
+    return result;
+}
+const messageIdRecordingWarning = 'Telegram delivery succeeded, but message IDs could not be recorded';
+const descriptorCleanupWarning = 'Telegram delivery succeeded, but local descriptor cleanup failed';
+/** Preserve the normal success summary while surfacing a post-delivery local failure. */
+function appendFileSendWarning(summary, warning) {
+    return `${summary} Warning: ${warning}`;
+}
+/**
+ * @description Compose the complete file-send operation around a target/workdir
+ * resolver and Telegram gateway. A gateway return confirms delivery; subsequent
+ * message-id persistence or descriptor cleanup failures are success warnings so
+ * callers do not retry and duplicate an already-delivered message or album.
+ */
+function createSendFilesToThread(deps) {
+    let activeSnapshotOperations = 0;
+    const snapshotOperationWaiters = new abortableFifo_1.AbortableFifo();
+    async function executeWithSnapshotSlot(operation, signal) {
+        if (signal?.aborted)
+            throw (0, utils_1.getAbortError)(signal);
+        if (activeSnapshotOperations < exports.fileSendSnapshotConcurrency) {
+            activeSnapshotOperations += 1;
+        }
+        else {
+            await snapshotOperationWaiters.wait(signal);
+        }
+        try {
+            if (signal?.aborted)
+                throw (0, utils_1.getAbortError)(signal);
+            return await operation();
+        }
+        finally {
+            if (!snapshotOperationWaiters.resolveNext()) {
+                activeSnapshotOperations -= 1;
+            }
+        }
+    }
+    return async (threadKey, options) => executeWithSnapshotSlot(async () => {
+        const ownedFileDescriptors = [];
+        const ownedRoot = { pinnedRoot: null };
+        let operationResult;
+        let closeError = null;
+        try {
+            operationResult = await (async () => {
+                const targetResolution = deps.resolveTargetAndWorkDir(threadKey);
+                if (!targetResolution.ok)
+                    return { ok: false, error: targetResolution.error };
+                const { target, workDir } = targetResolution;
+                if (options.authorizedWorkDir !== undefined &&
+                    workDir !== options.authorizedWorkDir) {
+                    return {
+                        ok: false,
+                        error: 'thread is no longer bound to the authorized directory',
+                    };
+                }
+                const countError = (0, fileSendPlan_1.getFileSendCountError)(options.paths.length);
+                if (countError !== null)
+                    return { ok: false, error: countError };
+                const pinnedRoot = openPinnedFileSendRoot(workDir);
+                ownedRoot.pinnedRoot = pinnedRoot;
+                const items = [];
+                const readFileSnapshot = deps.readFileSnapshot ?? readTelegramFileSnapshot;
+                for (const rawPath of options.paths) {
+                    const resolved = (0, fileSendPlan_1.resolveSendFileWithinDir)(workDir, rawPath, pinnedRoot.rootPath);
+                    if (!resolved.ok)
+                        return { ok: false, error: resolved.error };
+                    const snapshot = readFileSnapshot(resolved.absPath, resolved.identity, pinnedRoot);
+                    if (!snapshot.ok) {
+                        return {
+                            ok: false,
+                            error: snapshot.kind === 'oversize'
+                                ? snapshot.error
+                                : `cannot read ${rawPath}: ${snapshot.error}`,
+                        };
+                    }
+                    ownedFileDescriptors.push(snapshot.source.fd);
+                    items.push({
+                        absPath: resolved.absPath,
+                        source: snapshot.source,
+                        kind: (0, fileSendPlan_1.classifyFileSendKind)(resolved.absPath),
+                    });
+                }
+                const plan = (0, fileSendPlan_1.planFileSend)(items, options.asFile ?? false);
+                if (plan.kind === 'error')
+                    return { ok: false, error: plan.error };
+                const request = (0, fileSendPlan_1.buildTelegramFileSendRequest)(plan, options.caption);
+                const executeDelivery = deps.executeDelivery ?? ((_target, delivery) => delivery());
+                return executeDelivery(target, async () => {
+                    let deliveryTarget = target;
+                    if (options.authorizedWorkDir !== undefined) {
+                        const currentTargetResolution = deps.resolveTargetAndWorkDir(threadKey);
+                        if (!currentTargetResolution.ok) {
+                            return { ok: false, error: currentTargetResolution.error };
+                        }
+                        if (currentTargetResolution.workDir !== options.authorizedWorkDir) {
+                            return {
+                                ok: false,
+                                error: 'thread is no longer bound to the authorized directory',
+                            };
+                        }
+                        deliveryTarget = currentTargetResolution.target;
+                    }
+                    const requestMethod = request.method;
+                    let gatewayResult;
+                    switch (requestMethod) {
+                        case 'sendPhoto':
+                            gatewayResult = await deps.gateway.sendPhoto(deliveryTarget, request.source, request.caption, options.signal);
+                            break;
+                        case 'sendAnimation':
+                            gatewayResult = await deps.gateway.sendAnimation(deliveryTarget, request.source, request.caption, options.signal);
+                            break;
+                        case 'sendVideo':
+                            gatewayResult = await deps.gateway.sendVideo(deliveryTarget, request.source, request.caption, options.signal);
+                            break;
+                        case 'sendDocument':
+                            gatewayResult = await deps.gateway.sendDocument(deliveryTarget, request.source, request.caption, options.signal);
+                            break;
+                        case 'sendMediaGroup':
+                            gatewayResult = await deps.gateway.sendMediaGroup(deliveryTarget, request.mediaGroup, options.signal);
+                            break;
+                        default: {
+                            const unsupportedMethod = requestMethod;
+                            throw new Error(`Unsupported file send method: ${unsupportedMethod}`);
+                        }
+                    }
+                    const summary = `Sent ${items.length} file(s) to the topic.`;
+                    try {
+                        await deps.recordMessageIds(deliveryTarget, gatewayResult.messageIds);
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : 'unknown error';
+                        return {
+                            ok: true,
+                            summary: appendFileSendWarning(summary, `${messageIdRecordingWarning}: ${errorMessage}`),
+                        };
+                    }
+                    return { ok: true, summary };
+                }, options.signal);
+            })();
+        }
+        catch (error) {
+            if (error instanceof FileSendDeliveryUnknownError) {
+                operationResult = {
+                    ok: false,
+                    kind: 'deliveryUnknown',
+                    error: `${error.message}. Telegram may already have accepted this delivery; MUST NOT retry automatically.`,
+                };
+            }
+            else {
+                if (options.signal?.aborted)
+                    throw (0, utils_1.getAbortError)(options.signal);
+                const errorMessage = error instanceof Error ? error.message : 'unknown error';
+                operationResult = { ok: false, error: errorMessage };
+            }
+        }
+        finally {
+            for (const fileDescriptor of ownedFileDescriptors) {
+                const descriptorCloseError = closeFileDescriptor(fileDescriptor);
+                if (closeError === null && descriptorCloseError !== null) {
+                    closeError = descriptorCloseError;
+                }
+            }
+            if (ownedRoot.pinnedRoot !== null) {
+                const descriptorCloseError = closeFileDescriptor(ownedRoot.pinnedRoot.fd);
+                if (closeError === null && descriptorCloseError !== null) {
+                    closeError = descriptorCloseError;
+                }
+            }
+        }
+        if (closeError !== null) {
+            return operationResult.ok
+                ? {
+                    ok: true,
+                    summary: appendFileSendWarning(operationResult.summary, `${descriptorCleanupWarning}: ${closeError}`),
+                }
+                : { ...operationResult, error: `${operationResult.error}; ${closeError}` };
+        }
+        return operationResult;
+    }, options.signal);
+}
+//# sourceMappingURL=fileSendService.js.map

package/dist/utils/fileSendService.js.map

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

package/dist/utils/groupFinalizePlan.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @description Pure decision for the GROUP output transport's `finalizeInFlight`
+ * (S2): given the thread's coalesced output-queue state at a settle/teardown
+ * boundary, decide whether there is an unsent remainder to force-deliver (so the
+ * agent's final answer is never discarded) or the turn is already fully
+ * delivered (a no-op — no duplicate post).
+ *
+ * Extracted from `bot.ts`'s `finalizeGroupOutput` so the "remainder vs no-op"
+ * + importance decision is unit-testable without the Telegraf / queue
+ * machinery. The bot-side function owns the imperative drain (snapshot + null
+ * the buffer, then `sendOutputImmediate`); this owns only the decision.
+ *
+ * The group queue already SEPARATES what landed from what is pending:
+ * `lastMessageText` holds the last landed message and `pendingOutput` holds the
+ * coalesced-but-unsent remainder. So the "reconcile final accumulated vs last
+ * landed" reduces to: send `pendingOutput` if it is non-empty. No text diff is
+ * needed — the queue is the single source of the remainder.
+ */
+/** The load-bearing fields of `bot.ts`'s `OutputQueueState` the decision needs. */
+export interface GroupFinalizeInput {
+    /** Coalesced, not-yet-sent agent output. `null` = nothing pending. */
+    pendingOutput: string | null;
+    /** Whether the FIRST batch in `pendingOutput` continues the last sent message. */
+    pendingIsContinuation: boolean;
+}
+/**
+ * @description The finalize plan: either nothing to do (fully delivered), or the
+ * exact remainder to send and how.
+ */
+export type GroupFinalizePlan = {
+    action: 'noop';
+} | {
+    action: 'send';
+    text: string;
+    isContinuation: boolean;
+};
+export declare function getGroupFinalizePlan(input: GroupFinalizeInput): GroupFinalizePlan;
+//# sourceMappingURL=groupFinalizePlan.d.ts.map

package/dist/utils/groupFinalizePlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupFinalizePlan.d.ts","sourceRoot":"","sources":["../../src/utils/groupFinalizePlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kFAAkF;IAClF,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,CAYjF"}

package/dist/utils/groupFinalizePlan.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @description Pure decision for the GROUP output transport's `finalizeInFlight`
+ * (S2): given the thread's coalesced output-queue state at a settle/teardown
+ * boundary, decide whether there is an unsent remainder to force-deliver (so the
+ * agent's final answer is never discarded) or the turn is already fully
+ * delivered (a no-op — no duplicate post).
+ *
+ * Extracted from `bot.ts`'s `finalizeGroupOutput` so the "remainder vs no-op"
+ * + importance decision is unit-testable without the Telegraf / queue
+ * machinery. The bot-side function owns the imperative drain (snapshot + null
+ * the buffer, then `sendOutputImmediate`); this owns only the decision.
+ *
+ * The group queue already SEPARATES what landed from what is pending:
+ * `lastMessageText` holds the last landed message and `pendingOutput` holds the
+ * coalesced-but-unsent remainder. So the "reconcile final accumulated vs last
+ * landed" reduces to: send `pendingOutput` if it is non-empty. No text diff is
+ * needed — the queue is the single source of the remainder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGroupFinalizePlan = getGroupFinalizePlan;
+function getGroupFinalizePlan(input) {
+    // A fully-delivered turn (no pending remainder) — and a buffer holding only
+    // whitespace, which would earn a Telegram error and is not a real answer — is
+    // a no-op, so a settle/teardown never double-posts.
+    if (input.pendingOutput === null || input.pendingOutput.trim() === '') {
+        return { action: 'noop' };
+    }
+    return {
+        action: 'send',
+        text: input.pendingOutput,
+        isContinuation: input.pendingIsContinuation,
+    };
+}
+//# sourceMappingURL=groupFinalizePlan.js.map

package/dist/utils/groupFinalizePlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupFinalizePlan.js","sourceRoot":"","sources":["../../src/utils/groupFinalizePlan.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;AAkBH,oDAYC;AAZD,SAAgB,oBAAoB,CAAC,KAAyB;IAC5D,4EAA4E;IAC5E,8EAA8E;IAC9E,oDAAoD;IACpD,IAAI,KAAK,CAAC,aAAa,KAAK,IAAI,IAAI,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACtE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,KAAK,CAAC,aAAa;QACzB,cAAc,EAAE,KAAK,CAAC,qBAAqB;KAC5C,CAAC;AACJ,CAAC"}

package/dist/utils/identicalOutputGuard.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @description Per-thread defense-in-depth backstop against a runaway flood of
+ * byte-identical PERMANENT output.
+ *
+ * WHY it exists (flood 2026-06-16): a Claude tmux-scrape topic emitted a
+ * box-drawing table ~500 times, one byte-identical copy every ~12s for >2h.
+ * The root cause was fixed at the table emit path (S1, `recentRelayWindow`'s
+ * block-level dedup), but ANY emit path that re-sends the same large block —
+ * present or future, either backend — should not be able to flood a topic.
+ * This guard caps that regardless of which path produced the output: if a fresh
+ * permanent output is byte-identical to one recently sent to the SAME thread, it
+ * is suppressed.
+ *
+ * Deliberately NARROW to avoid false positives:
+ *  - only LARGE blocks ({@link identicalOutputMinChars}) are guarded — short
+ *    answers ("done", "yes", a one-line confirmation) legitimately repeat and
+ *    always pass;
+ *  - only within a short TIME window ({@link identicalOutputWindowMs}) and the
+ *    last few outputs ({@link identicalOutputWindowSize}) — a deliberate
+ *    re-print minutes apart is not a flood and passes;
+ *  - it is the BACKSTOP, not the primary fix: byte-identical only, never a
+ *    fuzzy match, so a genuinely-changed block (a cell flipped, a row added) is
+ *    different text and always passes.
+ *
+ * The continuation / status / transient / question exclusions are the caller's
+ * (`bot.ts` handleAgentOutput) — this guard only ever sees fresh permanent
+ * output text + the current time. State is reset at the same per-thread
+ * teardown points as the other relay state (session stop / closed / unbind).
+ */
+/** Last N permanent outputs per thread kept for the identical-repeat check. */
+export declare const identicalOutputWindowSize = 5;
+/** Only an identical output within this time window is treated as a flood. */
+export declare const identicalOutputWindowMs = 60000;
+/**
+ * Minimum candidate length (chars) to be guarded at all. Short answers repeat
+ * legitimately far too often to ever suppress — only LARGE blocks (a re-printed
+ * table, a re-rendered file dump) can flood meaningfully.
+ */
+export declare const identicalOutputMinChars = 200;
+/** One recorded permanent output: its text + when it was sent. */
+export interface RecentOutputRecord {
+    text: string;
+    sentAtMs: number;
+}
+/**
+ * @description Pure decision: is `candidate` a byte-identical repeat of a recent
+ * permanent output still inside the window? Short candidates (< {@link
+ * identicalOutputMinChars}) always return false. Only records within {@link
+ * identicalOutputWindowMs} of `nowMs` count — an older identical output has
+ * already aged out and is not a flood.
+ */
+export declare function checkIsIdenticalOutputRepeat(candidate: string, recentOutputs: readonly RecentOutputRecord[], nowMs: number): boolean;
+/**
+ * @description Append a permanent output to a thread's bounded recent-output
+ * history (newest last), evicting the oldest beyond {@link
+ * identicalOutputWindowSize}. Returns a NEW array (pure) so callers store the
+ * result. Outputs below {@link identicalOutputMinChars} are not recorded — they
+ * are never guarded, so they would only waste a slot.
+ */
+export declare function recordRecentOutput(recentOutputs: readonly RecentOutputRecord[], text: string, sentAtMs: number): RecentOutputRecord[];
+/**
+ * @description Stateful per-thread wrapper around the two pure helpers above.
+ * `bot.ts` keeps ONE instance for all threads; the per-thread history lives in
+ * an internal Map keyed by the serialised thread key.
+ */
+export interface IdenticalOutputGuard {
+    /**
+     * Decide whether `text` (a fresh permanent output) is a byte-identical flood
+     * repeat for `threadKey`. When it is NOT, the output is RECORDED (so the next
+     * identical one is caught) and `false` is returned. When it IS a repeat,
+     * nothing is recorded and `true` is returned — the caller suppresses the send.
+     */
+    checkAndRecord(threadKey: string, text: string, nowMs: number): boolean;
+    /** Forget a thread's history (session stop / closed / unbind). */
+    reset(threadKey: string): void;
+}
+/**
+ * @description Create an empty identical-output guard. `nowMs` is supplied per
+ * call (not read from `Date.now()` here) so tests can drive the time window
+ * deterministically.
+ */
+export declare function createIdenticalOutputGuard(): IdenticalOutputGuard;
+//# sourceMappingURL=identicalOutputGuard.d.ts.map

package/dist/utils/identicalOutputGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identicalOutputGuard.d.ts","sourceRoot":"","sources":["../../src/utils/identicalOutputGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,SAAS,kBAAkB,EAAE,EAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,SAAS,kBAAkB,EAAE,EAC5C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,kBAAkB,EAAE,CAKtB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxE,kEAAkE;IAClE,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,oBAAoB,CAcjE"}