charness 0.0.0-stage → 3.1.0

package/dist/utils/identicalOutputGuard.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * @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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identicalOutputMinChars = exports.identicalOutputWindowMs = exports.identicalOutputWindowSize = void 0;
+exports.checkIsIdenticalOutputRepeat = checkIsIdenticalOutputRepeat;
+exports.recordRecentOutput = recordRecentOutput;
+exports.createIdenticalOutputGuard = createIdenticalOutputGuard;
+/** Last N permanent outputs per thread kept for the identical-repeat check. */
+exports.identicalOutputWindowSize = 5;
+/** Only an identical output within this time window is treated as a flood. */
+exports.identicalOutputWindowMs = 60_000;
+/**
+ * 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.
+ */
+exports.identicalOutputMinChars = 200;
+/**
+ * @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.
+ */
+function checkIsIdenticalOutputRepeat(candidate, recentOutputs, nowMs) {
+    if (candidate.length < exports.identicalOutputMinChars)
+        return false;
+    for (const record of recentOutputs) {
+        if (nowMs - record.sentAtMs > exports.identicalOutputWindowMs)
+            continue;
+        if (record.text === candidate)
+            return true;
+    }
+    return false;
+}
+/**
+ * @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.
+ */
+function recordRecentOutput(recentOutputs, text, sentAtMs) {
+    if (text.length < exports.identicalOutputMinChars)
+        return [...recentOutputs];
+    const next = [...recentOutputs, { text, sentAtMs }];
+    if (next.length > exports.identicalOutputWindowSize)
+        next.splice(0, next.length - exports.identicalOutputWindowSize);
+    return next;
+}
+/**
+ * @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.
+ */
+function createIdenticalOutputGuard() {
+    const historyByThread = new Map();
+    return {
+        checkAndRecord(threadKey, text, nowMs) {
+            const history = historyByThread.get(threadKey) ?? [];
+            if (checkIsIdenticalOutputRepeat(text, history, nowMs))
+                return true;
+            historyByThread.set(threadKey, recordRecentOutput(history, text, nowMs));
+            return false;
+        },
+        reset(threadKey) {
+            historyByThread.delete(threadKey);
+        },
+    };
+}
+//# sourceMappingURL=identicalOutputGuard.js.map

package/dist/utils/identicalOutputGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identicalOutputGuard.js","sourceRoot":"","sources":["../../src/utils/identicalOutputGuard.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AA4BH,oEAWC;AASD,gDASC;AAwBD,gEAcC;AA7FD,+EAA+E;AAClE,QAAA,yBAAyB,GAAG,CAAC,CAAC;AAE3C,8EAA8E;AACjE,QAAA,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;;GAIG;AACU,QAAA,uBAAuB,GAAG,GAAG,CAAC;AAQ3C;;;;;;GAMG;AACH,SAAgB,4BAA4B,CAC1C,SAAiB,EACjB,aAA4C,EAC5C,KAAa;IAEb,IAAI,SAAS,CAAC,MAAM,GAAG,+BAAuB;QAAE,OAAO,KAAK,CAAC;IAC7D,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,KAAK,GAAG,MAAM,CAAC,QAAQ,GAAG,+BAAuB;YAAE,SAAS;QAChE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAChC,aAA4C,EAC5C,IAAY,EACZ,QAAgB;IAEhB,IAAI,IAAI,CAAC,MAAM,GAAG,+BAAuB;QAAE,OAAO,CAAC,GAAG,aAAa,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,GAAG,iCAAyB;QAAE,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,iCAAyB,CAAC,CAAC;IACrG,OAAO,IAAI,CAAC;AACd,CAAC;AAmBD;;;;GAIG;AACH,SAAgB,0BAA0B;IACxC,MAAM,eAAe,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEhE,OAAO;QACL,cAAc,CAAC,SAAiB,EAAE,IAAY,EAAE,KAAa;YAC3D,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACrD,IAAI,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACpE,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE,kBAAkB,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YACzE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,CAAC,SAAiB;YACrB,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/isoTimestamp.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @description Pure formatter for the `/timestamps` prompt injection: an
+ * ISO-8601 wall-clock timestamp carrying the host's LOCAL UTC offset
+ * (`2026-06-27T19:42:10+04:00`), never the `Z` suffix `toISOString()` emits.
+ * The agent-facing use case is absolute-time context for long multi-day
+ * sessions ("yesterday", "2-3 days ago"), so the operator's local clock — not
+ * UTC — is the meaningful frame of reference.
+ */
+/**
+ * @description Format an epoch-ms instant as local-offset ISO-8601, second
+ * precision: `YYYY-MM-DDTHH:mm:ss±HH:MM`. Uses the host timezone in effect for
+ * that instant (DST-correct — the offset comes from the Date itself), so
+ * parsing the result back yields the same instant.
+ */
+export declare function formatIsoLocalOffset(epochMs: number): string;
+//# sourceMappingURL=isoTimestamp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"isoTimestamp.d.ts","sourceRoot":"","sources":["../../src/utils/isoTimestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW5D"}

package/dist/utils/isoTimestamp.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * @description Pure formatter for the `/timestamps` prompt injection: an
+ * ISO-8601 wall-clock timestamp carrying the host's LOCAL UTC offset
+ * (`2026-06-27T19:42:10+04:00`), never the `Z` suffix `toISOString()` emits.
+ * The agent-facing use case is absolute-time context for long multi-day
+ * sessions ("yesterday", "2-3 days ago"), so the operator's local clock — not
+ * UTC — is the meaningful frame of reference.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatIsoLocalOffset = formatIsoLocalOffset;
+const minutesPerHour = 60;
+/** Zero-pad a calendar/clock component to two digits. */
+function padTwo(value) {
+    return value.toString().padStart(2, '0');
+}
+/**
+ * @description Format an epoch-ms instant as local-offset ISO-8601, second
+ * precision: `YYYY-MM-DDTHH:mm:ss±HH:MM`. Uses the host timezone in effect for
+ * that instant (DST-correct — the offset comes from the Date itself), so
+ * parsing the result back yields the same instant.
+ */
+function formatIsoLocalOffset(epochMs) {
+    const date = new Date(epochMs);
+    const offsetTotalMinutes = -date.getTimezoneOffset();
+    const offsetSign = offsetTotalMinutes >= 0 ? '+' : '-';
+    const offsetAbsMinutes = Math.abs(offsetTotalMinutes);
+    const offsetHours = Math.floor(offsetAbsMinutes / minutesPerHour);
+    const offsetMinutes = offsetAbsMinutes % minutesPerHour;
+    const datePart = `${date.getFullYear()}-${padTwo(date.getMonth() + 1)}-${padTwo(date.getDate())}`;
+    const timePart = `${padTwo(date.getHours())}:${padTwo(date.getMinutes())}:${padTwo(date.getSeconds())}`;
+    return `${datePart}T${timePart}${offsetSign}${padTwo(offsetHours)}:${padTwo(offsetMinutes)}`;
+}
+//# sourceMappingURL=isoTimestamp.js.map

package/dist/utils/isoTimestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isoTimestamp.js","sourceRoot":"","sources":["../../src/utils/isoTimestamp.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAeH,oDAWC;AAxBD,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B,yDAAyD;AACzD,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,OAAe;IAClD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,kBAAkB,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;IACrD,MAAM,UAAU,GAAG,kBAAkB,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IACvD,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,GAAG,cAAc,CAAC,CAAC;IAClE,MAAM,aAAa,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAExD,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;IAClG,MAAM,QAAQ,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;IACxG,OAAO,GAAG,QAAQ,IAAI,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;AAC/F,CAAC"}

package/dist/utils/jsonStreamBusyWatchdog.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @description Pure idle-watchdog decision for the `claude-json-stream` adapter's
+ * `isBusy` flag — the flag that (via `checkIsBusy` → `checkShouldKeepTyping`)
+ * keeps the native Telegram "agent is typing…" indicator alive.
+ *
+ * ROOT-CAUSE CONTEXT. In `claudeJsonStreamAdapter` `isBusy` has exactly ONE
+ * clear-point: a processed terminal `result` line (`handleTurnEnd`). Every other
+ * event only ever SETS it (`sendInput`, a text/thinking delta, a `tool_use`, a
+ * surfaced question). So if that single `result` is ever missed — an `interrupt`
+ * the CLI aborts without a final `result`, a process that goes quiet after the
+ * answer, a `result` shape a newer CLI stops emitting — `isBusy` sticks `true`
+ * forever and the typing indicator hangs. Observed live: an otherwise-idle topic
+ * firing `sendChatAction('typing')` every 4s for an hour+ after the agent was
+ * already done. The typing loop self-stops only when `checkShouldKeepTyping`
+ * (`isBusy || isOutputStreaming`) goes false and has NO absolute bound, so a
+ * single stuck flag is unbounded.
+ *
+ * This is the bounded safety net: when the session is flagged busy but stdout has
+ * been SILENT for {@link busyIdleWatchdogMs} AND nothing is genuinely in flight
+ * (no outstanding tool, no active sub-agent, no pending user question, no
+ * un-emitted answer batch), the turn has really ended — clear `isBusy`.
+ *
+ * SILENCE — not wall-clock since the turn started — is the signal, so a
+ * legitimately long turn is NEVER cut short: a working agent is always doing one
+ * of (a) streaming text/thinking deltas → stdout activity, (b) waiting on a tool
+ * → `outstandingToolCount > 0`, (c) waiting on a sub-agent → `subagentActive`,
+ * (d) waiting on the user → `hasPendingQuestion`. Each of those VETOES the clear.
+ * The watchdog can therefore only fire once the work is provably done but the
+ * terminal `result` never arrived.
+ */
+/**
+ * @description How long stdout may be silent, with nothing in flight, before a
+ * busy session is force-declared idle. Comfortably longer than the only silent
+ * gap a working-yet-nothing-in-flight turn has (pre-first-token latency), far
+ * shorter than the reported hour+ hang.
+ */
+export declare const busyIdleWatchdogMs = 120000;
+export interface BusyIdleWatchdogInput {
+    /** Is the session currently flagged busy (drives the typing indicator)? */
+    isBusy: boolean;
+    /** ms since the last stdout byte was consumed for this session. */
+    msSinceStdoutActivity: number;
+    /** The silence threshold (injected so tests need no fake clock). */
+    idleTimeoutMs: number;
+    /** Tool calls started but whose `tool_result` hasn't returned (Bash/Read/Task/…). */
+    outstandingToolCount: number;
+    /** A sub-agent delegation is mid-flight. */
+    subagentActive: boolean;
+    /** A user question is awaiting an answer. */
+    hasPendingQuestion: boolean;
+    /** Answer text still sits un-emitted in the coalesce batch. */
+    hasUnflushedAnswer: boolean;
+}
+/**
+ * @description True iff a busy session should be force-cleared to idle: it is
+ * busy, stdout has been silent past the threshold, and every "in flight" signal
+ * is absent. Any single in-flight signal (tool / sub-agent / question / batched
+ * answer) VETOES the clear so a legitimately mid-turn agent is never truncated.
+ */
+export declare function checkShouldClearBusyOnIdle(input: BusyIdleWatchdogInput): boolean;
+/**
+ * @description How long stdout may be silent before a compaction the CLI never
+ * confirmed is declared dead. Same signal, same reasoning as
+ * {@link busyIdleWatchdogMs}: while it compacts, the CLI heartbeats
+ * `system/status status:"compacting"` every few seconds, so real silence this long
+ * means the process is gone — not that it is thinking.
+ */
+export declare const compactionSilenceTimeoutMs = 120000;
+/**
+ * @description Absolute backstop on one compaction wait. Only reachable by a CLI
+ * that keeps talking forever without ever finishing (a retry loop), which silence
+ * alone cannot catch; without it the caller's promise — and with it the
+ * "a compaction is running" guard — would never settle.
+ */
+export declare const compactionAbsoluteTimeoutMs: number;
+/** How often the compaction wait re-evaluates its verdict. */
+export declare const compactionWaitPollMs = 15000;
+export type CompactionWaitVerdict = 'keepWaiting' | 'timedOutSilent' | 'timedOutTotal';
+/** How a timed-out wait is REPORTED (decided by {@link getCompactionTimeoutOutcome}). */
+export type CompactionTimeoutOutcome = 
+/** It demonstrably worked; only the frame carrying the token counts is missing. */
+{
+    kind: 'succeededWithoutTokenCounts';
+} | {
+    kind: 'failed';
+    reason: 'silent' | 'total';
+};
+/**
+ * @description What a timed-out compaction wait should report.
+ *
+ * `sawSuccess` means the CLI already sent `compact_status success` and only the
+ * boundary frame (which carries the pre/post token counts) never followed. The
+ * context IS compacted at that point, so reporting failure would suppress the
+ * notice over an already-compacted session and leave the operator with the same
+ * silence this whole fix exists to remove. Token counts are a diagnostic; the
+ * compaction is the outcome.
+ */
+export declare function getCompactionTimeoutOutcome(input: {
+    verdict: Exclude<CompactionWaitVerdict, 'keepWaiting'>;
+    sawSuccess: boolean;
+}): CompactionTimeoutOutcome;
+/**
+ * @description Decide whether to keep waiting for a compaction to confirm.
+ *
+ * ROOT-CAUSE CONTEXT. This wait used to be a flat 3-minute cap on TOTAL elapsed
+ * time, and it produced the operator's report that idle compaction "runs but never
+ * says so": the compaction fired, the CLI compacted successfully, and the bot had
+ * already given up and posted nothing. Measured on the real session that exposed
+ * it — `compact_metadata.duration_ms: 195649`, i.e. 3 min 15.6 s against a 180 s
+ * cap, missing by 15 seconds. Elapsed time is the wrong bound: how long a summary
+ * takes scales with the context being summarised, so ANY fixed cap is a guess that
+ * a big enough session beats, and compact-on-idle exists precisely FOR big
+ * sessions — the bound was guaranteed to fail exactly where the feature matters.
+ *
+ * So silence decides instead, and the absolute cap survives only as a backstop
+ * against a CLI that never finishes at all. Silence is checked FIRST: for a dead
+ * process both bounds can be past, and "still talking, never finished" would be
+ * the wrong report.
+ */
+export declare function getCompactionWaitVerdict(input: {
+    /** ms since the last stdout byte was consumed for this session. */
+    msSinceStdoutActivity: number;
+    /** ms since the `/compact` turn was written to stdin. */
+    msSinceCompactionStarted: number;
+    /** Silence threshold (injected so tests need no fake clock). */
+    silenceTimeoutMs: number;
+    /** Absolute backstop (injected for the same reason). */
+    absoluteTimeoutMs: number;
+}): CompactionWaitVerdict;
+//# sourceMappingURL=jsonStreamBusyWatchdog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStreamBusyWatchdog.d.ts","sourceRoot":"","sources":["../../src/utils/jsonStreamBusyWatchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,cAAc,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,+DAA+D;IAC/D,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAQhF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAE1D,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEvF,yFAAyF;AACzF,MAAM,MAAM,wBAAwB;AAClC,mFAAmF;AACjF;IAAE,IAAI,EAAE,6BAA6B,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,CAAC;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,OAAO,EAAE,OAAO,CAAC,qBAAqB,EAAE,aAAa,CAAC,CAAC;IACvD,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,wBAAwB,CAG3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,mEAAmE;IACnE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,wBAAwB,EAAE,MAAM,CAAC;IACjC,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,qBAAqB,CAIxB"}

package/dist/utils/jsonStreamBusyWatchdog.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * @description Pure idle-watchdog decision for the `claude-json-stream` adapter's
+ * `isBusy` flag — the flag that (via `checkIsBusy` → `checkShouldKeepTyping`)
+ * keeps the native Telegram "agent is typing…" indicator alive.
+ *
+ * ROOT-CAUSE CONTEXT. In `claudeJsonStreamAdapter` `isBusy` has exactly ONE
+ * clear-point: a processed terminal `result` line (`handleTurnEnd`). Every other
+ * event only ever SETS it (`sendInput`, a text/thinking delta, a `tool_use`, a
+ * surfaced question). So if that single `result` is ever missed — an `interrupt`
+ * the CLI aborts without a final `result`, a process that goes quiet after the
+ * answer, a `result` shape a newer CLI stops emitting — `isBusy` sticks `true`
+ * forever and the typing indicator hangs. Observed live: an otherwise-idle topic
+ * firing `sendChatAction('typing')` every 4s for an hour+ after the agent was
+ * already done. The typing loop self-stops only when `checkShouldKeepTyping`
+ * (`isBusy || isOutputStreaming`) goes false and has NO absolute bound, so a
+ * single stuck flag is unbounded.
+ *
+ * This is the bounded safety net: when the session is flagged busy but stdout has
+ * been SILENT for {@link busyIdleWatchdogMs} AND nothing is genuinely in flight
+ * (no outstanding tool, no active sub-agent, no pending user question, no
+ * un-emitted answer batch), the turn has really ended — clear `isBusy`.
+ *
+ * SILENCE — not wall-clock since the turn started — is the signal, so a
+ * legitimately long turn is NEVER cut short: a working agent is always doing one
+ * of (a) streaming text/thinking deltas → stdout activity, (b) waiting on a tool
+ * → `outstandingToolCount > 0`, (c) waiting on a sub-agent → `subagentActive`,
+ * (d) waiting on the user → `hasPendingQuestion`. Each of those VETOES the clear.
+ * The watchdog can therefore only fire once the work is provably done but the
+ * terminal `result` never arrived.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compactionWaitPollMs = exports.compactionAbsoluteTimeoutMs = exports.compactionSilenceTimeoutMs = exports.busyIdleWatchdogMs = void 0;
+exports.checkShouldClearBusyOnIdle = checkShouldClearBusyOnIdle;
+exports.getCompactionTimeoutOutcome = getCompactionTimeoutOutcome;
+exports.getCompactionWaitVerdict = getCompactionWaitVerdict;
+/**
+ * @description How long stdout may be silent, with nothing in flight, before a
+ * busy session is force-declared idle. Comfortably longer than the only silent
+ * gap a working-yet-nothing-in-flight turn has (pre-first-token latency), far
+ * shorter than the reported hour+ hang.
+ */
+exports.busyIdleWatchdogMs = 120_000;
+/**
+ * @description True iff a busy session should be force-cleared to idle: it is
+ * busy, stdout has been silent past the threshold, and every "in flight" signal
+ * is absent. Any single in-flight signal (tool / sub-agent / question / batched
+ * answer) VETOES the clear so a legitimately mid-turn agent is never truncated.
+ */
+function checkShouldClearBusyOnIdle(input) {
+    if (!input.isBusy)
+        return false;
+    if (input.msSinceStdoutActivity < input.idleTimeoutMs)
+        return false;
+    if (input.outstandingToolCount > 0)
+        return false;
+    if (input.subagentActive)
+        return false;
+    if (input.hasPendingQuestion)
+        return false;
+    if (input.hasUnflushedAnswer)
+        return false;
+    return true;
+}
+/**
+ * @description How long stdout may be silent before a compaction the CLI never
+ * confirmed is declared dead. Same signal, same reasoning as
+ * {@link busyIdleWatchdogMs}: while it compacts, the CLI heartbeats
+ * `system/status status:"compacting"` every few seconds, so real silence this long
+ * means the process is gone — not that it is thinking.
+ */
+exports.compactionSilenceTimeoutMs = 120_000;
+/**
+ * @description Absolute backstop on one compaction wait. Only reachable by a CLI
+ * that keeps talking forever without ever finishing (a retry loop), which silence
+ * alone cannot catch; without it the caller's promise — and with it the
+ * "a compaction is running" guard — would never settle.
+ */
+exports.compactionAbsoluteTimeoutMs = 30 * 60 * 1000;
+/** How often the compaction wait re-evaluates its verdict. */
+exports.compactionWaitPollMs = 15_000;
+/**
+ * @description What a timed-out compaction wait should report.
+ *
+ * `sawSuccess` means the CLI already sent `compact_status success` and only the
+ * boundary frame (which carries the pre/post token counts) never followed. The
+ * context IS compacted at that point, so reporting failure would suppress the
+ * notice over an already-compacted session and leave the operator with the same
+ * silence this whole fix exists to remove. Token counts are a diagnostic; the
+ * compaction is the outcome.
+ */
+function getCompactionTimeoutOutcome(input) {
+    if (input.sawSuccess)
+        return { kind: 'succeededWithoutTokenCounts' };
+    return { kind: 'failed', reason: input.verdict === 'timedOutSilent' ? 'silent' : 'total' };
+}
+/**
+ * @description Decide whether to keep waiting for a compaction to confirm.
+ *
+ * ROOT-CAUSE CONTEXT. This wait used to be a flat 3-minute cap on TOTAL elapsed
+ * time, and it produced the operator's report that idle compaction "runs but never
+ * says so": the compaction fired, the CLI compacted successfully, and the bot had
+ * already given up and posted nothing. Measured on the real session that exposed
+ * it — `compact_metadata.duration_ms: 195649`, i.e. 3 min 15.6 s against a 180 s
+ * cap, missing by 15 seconds. Elapsed time is the wrong bound: how long a summary
+ * takes scales with the context being summarised, so ANY fixed cap is a guess that
+ * a big enough session beats, and compact-on-idle exists precisely FOR big
+ * sessions — the bound was guaranteed to fail exactly where the feature matters.
+ *
+ * So silence decides instead, and the absolute cap survives only as a backstop
+ * against a CLI that never finishes at all. Silence is checked FIRST: for a dead
+ * process both bounds can be past, and "still talking, never finished" would be
+ * the wrong report.
+ */
+function getCompactionWaitVerdict(input) {
+    if (input.msSinceStdoutActivity >= input.silenceTimeoutMs)
+        return 'timedOutSilent';
+    if (input.msSinceCompactionStarted >= input.absoluteTimeoutMs)
+        return 'timedOutTotal';
+    return 'keepWaiting';
+}
+//# sourceMappingURL=jsonStreamBusyWatchdog.js.map

package/dist/utils/jsonStreamBusyWatchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStreamBusyWatchdog.js","sourceRoot":"","sources":["../../src/utils/jsonStreamBusyWatchdog.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAiCH,gEAQC;AAwCD,kEAMC;AAoBD,4DAaC;AAtHD;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,OAAO,CAAC;AAmB1C;;;;;GAKG;AACH,SAAgB,0BAA0B,CAAC,KAA4B;IACrE,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,KAAK,CAAC,qBAAqB,GAAG,KAAK,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACpE,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,KAAK,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,KAAK,CAAC,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,KAAK,CAAC,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACU,QAAA,0BAA0B,GAAG,OAAO,CAAC;AAElD;;;;;GAKG;AACU,QAAA,2BAA2B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1D,8DAA8D;AACjD,QAAA,oBAAoB,GAAG,MAAM,CAAC;AAU3C;;;;;;;;;GASG;AACH,SAAgB,2BAA2B,CAAC,KAG3C;IACC,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC;IACrE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,wBAAwB,CAAC,KASxC;IACC,IAAI,KAAK,CAAC,qBAAqB,IAAI,KAAK,CAAC,gBAAgB;QAAE,OAAO,gBAAgB,CAAC;IACnF,IAAI,KAAK,CAAC,wBAAwB,IAAI,KAAK,CAAC,iBAAiB;QAAE,OAAO,eAAe,CAAC;IACtF,OAAO,aAAa,CAAC;AACvB,CAAC"}