charness 0.0.0-stage → 3.1.0

package/dist/utils/startupReadiness.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * @description Pure decision layer for the boot-time readiness status message
+ * (plan 2026-07-12-startup-readiness-status). On startup the bot tells the owner
+ * whether it can process messages in the topics / group, or — if not — a numbered
+ * list of only the setup steps that are still unmet. This module holds the pure,
+ * unit-testable core: which items are unmet, whether the bot is ready, the
+ * cadence gate, and the full message composition (via an injected translate so
+ * the numbering / header logic is testable without the i18n runtime). `bot.ts`
+ * gathers the live facts and does the actual Telegram send.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.botRightLabels = void 0;
+exports.getMissingBotRights = getMissingBotRights;
+exports.formatMissingRights = formatMissingRights;
+exports.buildReadinessReport = buildReadinessReport;
+exports.checkShouldSendStartupStatus = checkShouldSendStartupStatus;
+exports.resolveStartupTargets = resolveStartupTargets;
+exports.buildStartupStatusText = buildStartupStatusText;
+/** The order every checklist item renders in — matches the IDEAL list. */
+const readinessItemOrder = [
+    'create_group',
+    'grant_admin',
+    'bind_topic',
+    'install_agent',
+    'optional_groq',
+    'optional_owner',
+];
+/** The REQUIRED items — an unmet one makes the bot not-ready. */
+const requiredItemKeys = [
+    'create_group',
+    'grant_admin',
+    'bind_topic',
+    'install_agent',
+];
+/**
+ * @description Telegram's canonical permission names for the three rights the
+ * bot needs — proper nouns shown verbatim in the `grant_admin` item so the
+ * operator can find the exact toggles in Telegram's admin UI. Kept here (not in
+ * i18n) because they are feature identifiers, not translated prose.
+ */
+exports.botRightLabels = {
+    manageTopics: 'Manage Topics',
+    pin: 'Pin Messages',
+    delete: 'Delete Messages',
+};
+/**
+ * @description The admin rights the bot is missing. A `null` rights object (not
+ * an admin / unreadable) counts as ALL three missing.
+ */
+function getMissingBotRights(rights) {
+    if (!rights)
+        return ['manageTopics', 'pin', 'delete'];
+    const missing = [];
+    if (!rights.manageTopics)
+        missing.push('manageTopics');
+    if (!rights.pin)
+        missing.push('pin');
+    if (!rights.delete)
+        missing.push('delete');
+    return missing;
+}
+/** Join the missing rights into the human list for the `grant_admin` item copy. */
+function formatMissingRights(keys) {
+    return keys.map((key) => exports.botRightLabels[key]).join(', ');
+}
+/**
+ * @description Turn the live facts into the readiness verdict.
+ *
+ * `isReady` is true iff NONE of the required items are unmet:
+ *   groupPaired  &&  all admin rights held  &&  a binding exists  &&  an agent CLI installed.
+ * The optional groq / owner items are informational — they populate `unmetKeys`
+ * (so they render inside a not-ready checklist) but never flip `isReady`.
+ *
+ * `grant_admin` is only unmet while a group IS paired (you cannot grant admin
+ * before the group exists — an unpaired bot shows `create_group` instead).
+ */
+function buildReadinessReport(facts) {
+    const missingRights = facts.groupPaired ? getMissingBotRights(facts.botRights) : [];
+    const unmet = new Set();
+    if (!facts.groupPaired)
+        unmet.add('create_group');
+    if (facts.groupPaired && missingRights.length > 0)
+        unmet.add('grant_admin');
+    if (!facts.hasBinding)
+        unmet.add('bind_topic');
+    if (facts.availableAgents.length === 0)
+        unmet.add('install_agent');
+    if (!facts.hasGroq)
+        unmet.add('optional_groq');
+    if (!facts.ownerSet && facts.usedGeneralFallback)
+        unmet.add('optional_owner');
+    const isReady = requiredItemKeys.every((key) => !unmet.has(key));
+    const unmetKeys = readinessItemOrder.filter((key) => unmet.has(key));
+    return { isReady, unmetKeys, missingRights };
+}
+/**
+ * @description Cadence gate. A COLD start always sends (ready or not). A HOT
+ * reload stays silent when fully ready (no spam on frequent rebuilds) and sends
+ * only when something is missing.
+ */
+function checkShouldSendStartupStatus(input) {
+    return !(input.isHotReload && input.isReady);
+}
+/**
+ * @description Resolve the ordered delivery targets for the boot-time status.
+ *
+ * The READY status is only meaningful in the owner's private DM, so it is
+ * DM-ONLY and NEVER falls back to the group's General topic (a "✅ Ready" in the
+ * shared group is pure noise). If there is no owner DM, a ready status resolves
+ * to an empty list — nothing is delivered (the caller logs it).
+ *
+ * The NOT-READY checklist is actionable, so it uses the owner DM when available
+ * and falls back to General otherwise (owner first):
+ *
+ *   ready      → hasOwnerTarget ? ['owner'] : []            (private-only, never 'general')
+ *   not-ready  → ['owner', 'general'] filtered to the available surfaces (owner first)
+ */
+function resolveStartupTargets(isReady, hasOwnerTarget, hasGeneralTarget) {
+    if (isReady) {
+        return hasOwnerTarget ? ['owner'] : [];
+    }
+    const targets = [];
+    if (hasOwnerTarget)
+        targets.push('owner');
+    if (hasGeneralTarget)
+        targets.push('general');
+    return targets;
+}
+/**
+ * @description Compose the full status message. Ready ⇒ the short ready line.
+ * Not ready ⇒ a header followed by the unmet items renumbered 1..N (the
+ * `grant_admin` line interpolates the missing-rights list).
+ */
+function buildStartupStatusText(report, translate) {
+    if (report.isReady) {
+        return translate('startup.ready');
+    }
+    const header = translate('startup.header_not_ready');
+    const lines = report.unmetKeys.map((key, index) => {
+        const itemText = key === 'grant_admin'
+            ? translate('startup.item.grant_admin', { missing: formatMissingRights(report.missingRights) })
+            : translate(`startup.item.${key}`);
+        return `${index + 1}. ${itemText}`;
+    });
+    return `${header}\n\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=startupReadiness.js.map

package/dist/utils/startupReadiness.js.map

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

package/dist/utils/statusFlushDecision.d.ts

@@ -0,0 +1,18 @@
+export type StatusFlushAction = 'send' | 'skip' | 'defer';
+export interface StatusFlushDecisionInput {
+    /** Frame the loop is about to send. */
+    nextText: string;
+    /** Last frame that successfully reached Telegram for this thread, or null. */
+    lastSentText: string | null;
+    /** Is the chat currently inside a Telegram 429 cooldown? */
+    isRateLimited: boolean;
+}
+/**
+ * @description Decide what the status-flush loop should do with `nextText`.
+ *
+ * Cooldown wins over dedup: while rate-limited we always `defer` (even an
+ * identical frame) so the loop exits leaving the latest `pendingText` for the
+ * post-cooldown flush, instead of spinning and re-checking the clock.
+ */
+export declare function getStatusFlushAction(input: StatusFlushDecisionInput): StatusFlushAction;
+//# sourceMappingURL=statusFlushDecision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"statusFlushDecision.d.ts","sourceRoot":"","sources":["../../src/utils/statusFlushDecision.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,wBAAwB,GAAG,iBAAiB,CAWvF"}

package/dist/utils/statusFlushDecision.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStatusFlushAction = getStatusFlushAction;
+/**
+ * @description Pure decision for the per-thread status-coalescer flush loop:
+ * given the frame about to be sent, the last frame that actually reached
+ * Telegram, and whether the chat is in a 429 cooldown, decide what the loop
+ * should do with this frame.
+ *
+ * Extracted from `bot.ts`'s `flushStatusCoalescer` so the rule is unit-testable
+ * without the Telegraf / bucket machinery (same pattern as
+ * `clearThreadOutputQueues.ts`). Status frames are disposable spinner ticks:
+ * during congestion it is correct to drop or defer them rather than burn the
+ * chat-wide send budget that interactive command replies and agent output need.
+ *
+ * @name StatusFlushAction
+ * @description
+ * - `send`   — text differs from the last sent frame and the chat is not in a
+ *   cooldown: send it now.
+ * - `skip`   — text equals the last sent frame after stripping the leading
+ *   spinner glyph: sending it would either earn a `400 "message is not
+ *   modified"` (truly identical) or an `editMessageText` that changed ONLY the
+ *   rotating liveness glyph — a per-second edit purely for animation. Either
+ *   way it wastes a token, so consume `pendingText` and move on. The native
+ *   typing indicator already carries alive-ness; the visible status frame's
+ *   glyph effectively freezes until the activity text actually changes.
+ * - `defer`  — the chat is rate-limited: do NOT send (a stale spinner frame is
+ *   not worth a token while a 429 cooldown is starving real traffic). Leave
+ *   `pendingText` in place so the newest frame is sent once the cooldown lifts.
+ */
+const claudeScrapeShapes_1 = require("./claudeScrapeShapes");
+/**
+ * @description Decide what the status-flush loop should do with `nextText`.
+ *
+ * Cooldown wins over dedup: while rate-limited we always `defer` (even an
+ * identical frame) so the loop exits leaving the latest `pendingText` for the
+ * post-cooldown flush, instead of spinning and re-checking the clock.
+ */
+function getStatusFlushAction(input) {
+    if (input.isRateLimited)
+        return 'defer';
+    if (input.lastSentText === null)
+        return 'send';
+    // Compare on a glyph-stripped signature: the liveness frame rotates its
+    // leading spinner glyph every tick, so an exact-string compare treated each
+    // cosmetic-only tick as new → one editMessageText per second. Equal after
+    // stripping the lead glyph ⇒ skip (no edit); a real activity-text change ⇒ send.
+    if ((0, claudeScrapeShapes_1.stripLeadingSpinnerGlyph)(input.nextText) === (0, claudeScrapeShapes_1.stripLeadingSpinnerGlyph)(input.lastSentText)) {
+        return 'skip';
+    }
+    return 'send';
+}
+//# sourceMappingURL=statusFlushDecision.js.map

package/dist/utils/statusFlushDecision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statusFlushDecision.js","sourceRoot":"","sources":["../../src/utils/statusFlushDecision.ts"],"names":[],"mappings":";;AA+CA,oDAWC;AA1DD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,6DAAgE;AAahE;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAAC,KAA+B;IAClE,IAAI,KAAK,CAAC,aAAa;QAAE,OAAO,OAAO,CAAC;IACxC,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC/C,wEAAwE;IACxE,4EAA4E;IAC5E,0EAA0E;IAC1E,iFAAiF;IACjF,IAAI,IAAA,6CAAwB,EAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAA,6CAAwB,EAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9F,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/subagentRender.d.ts

@@ -0,0 +1,52 @@
+import type { DisplayVerbosityMode } from '../types';
+/** Part kinds a sub-agent (child session) event can carry that the adapter
+ * must decide on. `step-start`/`step-finish`/unknown parts are skipped before
+ * the matrix is consulted (same as for the parent's own parts). */
+export type SubagentPartKind = 'text' | 'tool' | 'reasoning';
+/**
+ * @name SubagentPartAction
+ * @description What the adapter does with one sub-agent part event.
+ *
+ * - `status` — emit/refresh a transient status only (for `text` that is the
+ *   rolling "🤖 sub-agent: <title> …" line; for `tool` the generic 🔧 line).
+ * - `stream` — accumulate into the SEPARATE child accumulator and emit as
+ *   marked `output` (`meta.isSubagent`). Never the parent accumulator.
+ * - `ignore` — drop entirely (no status, no output, no toolResult).
+ */
+export type SubagentPartAction = 'status' | 'stream' | 'ignore';
+/**
+ * @description The sub-agent mode×part-kind matrix:
+ * ```
+ *             minimal/short    full
+ * text        status           stream
+ * tool        ignore           status
+ * reasoning   ignore           ignore
+ * ```
+ * `minimal` and `short` are EQUIVALENT here (the v1 contract on the unified
+ * vocabulary): both are status-only, because the "working" indicator is never
+ * hidden (locked decision — see {@link DisplayVerbosityMode}). Reasoning is
+ * `ignore` in EVERY mode — child chain-of-thought is never rendered (locked
+ * decision). Non-`full` ignores child tool parts because their generic 🔧
+ * statuses would overwrite the single sub-agent status line. Child toolResult
+ * bodies are suppressed in ALL modes (handled by the adapter outside this
+ * matrix): the parent's `task` tool output already carries the child's final
+ * result.
+ */
+export declare function getSubagentPartAction(mode: DisplayVerbosityMode, partKind: SubagentPartKind): SubagentPartAction;
+/**
+ * @description Build the parent-side "Delegating" activity status
+ * ("🤖 Delegating: <title> …") rendered while the parent's delegation (`task`)
+ * tool part is pending/running (S5) — in `full` mode only (in `minimal`/`short`
+ * the dedicated self-updating sub-agent status message owns this indicator; see
+ * `utils/subagentStatusRender.ts`). `title` is the part's `state.title` falling
+ * back to its `input.description`; `null` (neither present) falls back to the
+ * same localized generic label.
+ */
+export declare function buildDelegatingStatusText(title: string | null): string;
+/**
+ * @description The marker prepended to every full-mode sub-agent chunk
+ * ("🤖 ⤷") so a streamed child transcript is visually separated from the main
+ * agent's reply.
+ */
+export declare function buildSubagentOutputPrefix(): string;
+//# sourceMappingURL=subagentRender.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subagentRender.d.ts","sourceRoot":"","sources":["../../src/utils/subagentRender.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD;;mEAEmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,CAIhH;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD"}

package/dist/utils/subagentRender.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSubagentPartAction = getSubagentPartAction;
+exports.buildDelegatingStatusText = buildDelegatingStatusText;
+exports.buildSubagentOutputPrefix = buildSubagentOutputPrefix;
+/**
+ * @description Decision + formatting helpers for sub-agent rendering behind
+ * `/subagent` (S4). Claude's transcript-tail path lives in
+ * `claudeSubagentTail.ts`; the mode×part-kind matrix
+ * ({@link getSubagentPartAction}) and the status builders are OpenCode's
+ * child-session SSE concerns. The matrix is consulted by the ADAPTER — unlike
+ * the thinking / tool-result modes the sub-agent mode decides what is
+ * ACCUMULATED (status vs a separate streamed accumulator), which cannot be
+ * deferred to the bot's render time. Extracted from the adapter so the matrix
+ * is unit-testable without an SSE stream (same pattern as
+ * `toolResultRender.ts`). The string builders are pure-ish (they only read
+ * i18n), mirroring `buildThinkingFrameText`. Mode options / type guard /
+ * default live in the shared `utils/displayVerbosity.ts`.
+ */
+const i18n_1 = require("../i18n");
+/**
+ * @description The sub-agent mode×part-kind matrix:
+ * ```
+ *             minimal/short    full
+ * text        status           stream
+ * tool        ignore           status
+ * reasoning   ignore           ignore
+ * ```
+ * `minimal` and `short` are EQUIVALENT here (the v1 contract on the unified
+ * vocabulary): both are status-only, because the "working" indicator is never
+ * hidden (locked decision — see {@link DisplayVerbosityMode}). Reasoning is
+ * `ignore` in EVERY mode — child chain-of-thought is never rendered (locked
+ * decision). Non-`full` ignores child tool parts because their generic 🔧
+ * statuses would overwrite the single sub-agent status line. Child toolResult
+ * bodies are suppressed in ALL modes (handled by the adapter outside this
+ * matrix): the parent's `task` tool output already carries the child's final
+ * result.
+ */
+function getSubagentPartAction(mode, partKind) {
+    if (partKind === 'reasoning')
+        return 'ignore';
+    if (partKind === 'text')
+        return mode === 'full' ? 'stream' : 'status';
+    return mode === 'full' ? 'status' : 'ignore';
+}
+/**
+ * @description Build the parent-side "Delegating" activity status
+ * ("🤖 Delegating: <title> …") rendered while the parent's delegation (`task`)
+ * tool part is pending/running (S5) — in `full` mode only (in `minimal`/`short`
+ * the dedicated self-updating sub-agent status message owns this indicator; see
+ * `utils/subagentStatusRender.ts`). `title` is the part's `state.title` falling
+ * back to its `input.description`; `null` (neither present) falls back to the
+ * same localized generic label.
+ */
+function buildDelegatingStatusText(title) {
+    return (0, i18n_1.t)('subagent.delegating_status', { title: title ?? (0, i18n_1.t)('subagent.fallback_title') });
+}
+/**
+ * @description The marker prepended to every full-mode sub-agent chunk
+ * ("🤖 ⤷") so a streamed child transcript is visually separated from the main
+ * agent's reply.
+ */
+function buildSubagentOutputPrefix() {
+    return (0, i18n_1.t)('subagent.chunk_prefix');
+}
+//# sourceMappingURL=subagentRender.js.map

package/dist/utils/subagentRender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagentRender.js","sourceRoot":"","sources":["../../src/utils/subagentRender.ts"],"names":[],"mappings":";;AAoDA,sDAIC;AAWD,8DAEC;AAOD,8DAEC;AA9ED;;;;;;;;;;;;;GAaG;AACH,kCAA4B;AAoB5B;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,qBAAqB,CAAC,IAA0B,EAAE,QAA0B;IAC1F,IAAI,QAAQ,KAAK,WAAW;QAAE,OAAO,QAAQ,CAAC;IAC9C,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IACtE,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,yBAAyB,CAAC,KAAoB;IAC5D,OAAO,IAAA,QAAC,EAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,KAAK,IAAI,IAAA,QAAC,EAAC,yBAAyB,CAAC,EAAE,CAAC,CAAC;AAC3F,CAAC;AAED;;;;GAIG;AACH,SAAgB,yBAAyB;IACvC,OAAO,IAAA,QAAC,EAAC,uBAAuB,CAAC,CAAC;AACpC,CAAC"}

package/dist/utils/subagentStatusRender.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @description Format an elapsed duration (ms) as `m:ss` — minutes unpadded,
+ * seconds zero-padded to two digits. Floored to whole seconds (the timer ticks
+ * coarsely, sub-second precision is noise). Examples: `0 → "0:00"`,
+ * `7000 → "0:07"`, `60000 → "1:00"`, `843000 → "14:03"`.
+ */
+export declare function formatElapsed(ms: number): string;
+/**
+ * @description Build the dedicated sub-agent status line
+ * ("🤖 sub-agent: <title> · m:ss") from the sticky title and the elapsed ms.
+ * `null` title falls back to the same localized generic label the other
+ * sub-agent status builders use.
+ */
+export declare function buildSubagentElapsedText(title: string | null, elapsedMs: number): string;
+/**
+ * @name SubagentStatusAction
+ * @description The bot's next move for the dedicated sub-agent status message,
+ * decided purely from whether a message currently exists and whether the
+ * incoming event says a delegation is active.
+ *
+ * - `open`    — a delegation started and no message exists yet → create one + arm the timer.
+ * - `refresh` — a delegation is in flight and a message exists → re-edit it (title/elapsed).
+ * - `close`   — the delegation ended and a message exists → delete it + stop the timer.
+ * - `noop`    — the delegation ended and no message exists → nothing to do (idempotent close).
+ */
+export type SubagentStatusAction = 'open' | 'refresh' | 'close' | 'noop';
+/**
+ * @description Map "(does a message exist?) × (is the event active?)" to the
+ * bot's next move. Keeping it a named pure helper makes the lifecycle a truth
+ * table the bot handler reads declaratively (same shape as
+ * `getToolResultRenderAction`), and lets a defensive `active:false` close
+ * no-op safely when nothing is open.
+ */
+export declare function getSubagentStatusAction(input: {
+    hasMessage: boolean;
+    eventActive: boolean;
+}): SubagentStatusAction;
+/**
+ * @description S1 dedup gate for the dedicated sub-agent status edit: should the
+ * freshly rendered line actually be re-sent, given the last text that reached
+ * Telegram? `false` when the text is unchanged — re-editing identical text only
+ * earns a `400 "message is not modified"`, and a stuck/frozen elapsed counter
+ * would otherwise churn that 400 on every refresh until the per-group 429 flood
+ * limit starves the whole topic (live incident 2026-08-03). A `null` last text
+ * (fresh open / post-clear) always sends.
+ */
+export declare function checkShouldSendSubagentStatus(nextText: string, lastText: string | null): boolean;
+/**
+ * @description S1' COALESCING gate for the dedicated sub-agent status edit:
+ * should a fresh refresh actually ENQUEUE an edit right now? Combines the text
+ * dedup ({@link checkShouldSendSubagentStatus}) with an in-flight guard so that,
+ * under a per-thread send backlog (the global pacer drains ~1 send / 2s), a
+ * burst of same-second refreshes can enqueue AT MOST ONE edit instead of
+ * stacking hundreds of identical closures.
+ *
+ * The bug this closes (live 2026-08-07): OpenCode streams frequent
+ * `message.part.updated` events for a live parent `task` part, so the bot got a
+ * high-frequency run of `subagentStatus{active:true}` refreshes. The plain S1
+ * dedup compared against the last text that REACHED Telegram, which only updates
+ * after the pacer-delayed send resolves — so during that window every same-text
+ * refresh passed the gate and enqueued another identical `editMessageText`.
+ * Hundreds piled into the thread's FIFO, drained one every 2s, and
+ * head-of-line-blocked the agent's OWN answer behind them — the topic looked
+ * hung. Fix: dedup against the last text we DECIDED to enqueue (recorded
+ * synchronously at decision time) AND never enqueue while one edit is still in
+ * flight.
+ */
+export declare function checkShouldEnqueueSubagentStatus(input: {
+    nextText: string;
+    lastEnqueuedText: string | null;
+    isEditInFlight: boolean;
+}): boolean;
+/**
+ * @description S2 hard safety net for the dedicated sub-agent status tick:
+ * should the frame be CLOSED (instead of re-arming the elapsed-tick timer)?
+ * `true` when the owning session is no longer active, OR the frame has outlived
+ * any realistic delegation (`maxAgeMs`). A session that dies server-side emits
+ * no clean idle/finish, so the adapter's defensive close never fires and the
+ * self-re-arming timer would otherwise live forever churning the topic (live
+ * 2026-08-03). A `null` `startedAtMs` (should never happen while a message is
+ * open) is treated as "just started", so a transient race can never force-close
+ * an otherwise healthy frame on the age branch.
+ */
+export declare function checkShouldExpireSubagentStatus(input: {
+    startedAtMs: number | null;
+    nowMs: number;
+    maxAgeMs: number;
+    isOwningSessionActive: boolean;
+}): boolean;
+//# sourceMappingURL=subagentStatusRender.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subagentStatusRender.d.ts","sourceRoot":"","sources":["../../src/utils/subagentStatusRender.ts"],"names":[],"mappings":"AA6BA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,oBAAoB,CAGvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEhG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAGV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,OAAO,CAAC;CAChC,GAAG,OAAO,CAIV"}

package/dist/utils/subagentStatusRender.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatElapsed = formatElapsed;
+exports.buildSubagentElapsedText = buildSubagentElapsedText;
+exports.getSubagentStatusAction = getSubagentStatusAction;
+exports.checkShouldSendSubagentStatus = checkShouldSendSubagentStatus;
+exports.checkShouldEnqueueSubagentStatus = checkShouldEnqueueSubagentStatus;
+exports.checkShouldExpireSubagentStatus = checkShouldExpireSubagentStatus;
+/**
+ * @description Pure decision + formatting helpers behind the dedicated OpenCode
+ * sub-agent status message (the `subagentStatus` adapter event, for the
+ * `minimal`/`short` `/subagent` modes). The adapter emits a mode-AGNOSTIC
+ * {@link SubagentStatusEvent}; the bot's `handleSubagentStatus` owns the
+ * message lifecycle and a ticking elapsed timer, and consults
+ * {@link getSubagentStatusAction} (open / refresh / close / noop) +
+ * {@link buildSubagentElapsedText} here. Extracted from `bot.ts` so the
+ * elapsed formatting and the lifecycle decision are unit-testable without the
+ * Telegraf machinery (same pattern as `toolResultRender.ts` /
+ * `subagentRender.ts`).
+ *
+ * Why a DEDICATED message instead of the shared transient status: the old
+ * status-only sub-agent line rode `statusMessageId`, whose single-message
+ * identity was lost between sparse child-text bursts, so every burst posted a
+ * NEW message (flood). This module backs the fix — one explicitly-managed
+ * message edited in place with a live elapsed counter.
+ */
+const i18n_1 = require("../i18n");
+/** Seconds in one minute — for the `m:ss` split in {@link formatElapsed}. */
+const secondsPerMinute = 60;
+/** Milliseconds in one second — for flooring elapsed ms to whole seconds. */
+const millisPerSecond = 1000;
+/** Zero-pad target width for the seconds field in `m:ss` (always two digits). */
+const secondsPadWidth = 2;
+/**
+ * @description Format an elapsed duration (ms) as `m:ss` — minutes unpadded,
+ * seconds zero-padded to two digits. Floored to whole seconds (the timer ticks
+ * coarsely, sub-second precision is noise). Examples: `0 → "0:00"`,
+ * `7000 → "0:07"`, `60000 → "1:00"`, `843000 → "14:03"`.
+ */
+function formatElapsed(ms) {
+    const totalSeconds = Math.floor(ms / millisPerSecond);
+    const minutes = Math.floor(totalSeconds / secondsPerMinute);
+    const seconds = totalSeconds % secondsPerMinute;
+    return `${minutes}:${seconds.toString().padStart(secondsPadWidth, '0')}`;
+}
+/**
+ * @description Build the dedicated sub-agent status line
+ * ("🤖 sub-agent: <title> · m:ss") from the sticky title and the elapsed ms.
+ * `null` title falls back to the same localized generic label the other
+ * sub-agent status builders use.
+ */
+function buildSubagentElapsedText(title, elapsedMs) {
+    return (0, i18n_1.t)('subagent.status_elapsed', {
+        title: title ?? (0, i18n_1.t)('subagent.fallback_title'),
+        elapsed: formatElapsed(elapsedMs),
+    });
+}
+/**
+ * @description Map "(does a message exist?) × (is the event active?)" to the
+ * bot's next move. Keeping it a named pure helper makes the lifecycle a truth
+ * table the bot handler reads declaratively (same shape as
+ * `getToolResultRenderAction`), and lets a defensive `active:false` close
+ * no-op safely when nothing is open.
+ */
+function getSubagentStatusAction(input) {
+    if (input.eventActive)
+        return input.hasMessage ? 'refresh' : 'open';
+    return input.hasMessage ? 'close' : 'noop';
+}
+/**
+ * @description S1 dedup gate for the dedicated sub-agent status edit: should the
+ * freshly rendered line actually be re-sent, given the last text that reached
+ * Telegram? `false` when the text is unchanged — re-editing identical text only
+ * earns a `400 "message is not modified"`, and a stuck/frozen elapsed counter
+ * would otherwise churn that 400 on every refresh until the per-group 429 flood
+ * limit starves the whole topic (live incident 2026-08-03). A `null` last text
+ * (fresh open / post-clear) always sends.
+ */
+function checkShouldSendSubagentStatus(nextText, lastText) {
+    return nextText !== lastText;
+}
+/**
+ * @description S1' COALESCING gate for the dedicated sub-agent status edit:
+ * should a fresh refresh actually ENQUEUE an edit right now? Combines the text
+ * dedup ({@link checkShouldSendSubagentStatus}) with an in-flight guard so that,
+ * under a per-thread send backlog (the global pacer drains ~1 send / 2s), a
+ * burst of same-second refreshes can enqueue AT MOST ONE edit instead of
+ * stacking hundreds of identical closures.
+ *
+ * The bug this closes (live 2026-08-07): OpenCode streams frequent
+ * `message.part.updated` events for a live parent `task` part, so the bot got a
+ * high-frequency run of `subagentStatus{active:true}` refreshes. The plain S1
+ * dedup compared against the last text that REACHED Telegram, which only updates
+ * after the pacer-delayed send resolves — so during that window every same-text
+ * refresh passed the gate and enqueued another identical `editMessageText`.
+ * Hundreds piled into the thread's FIFO, drained one every 2s, and
+ * head-of-line-blocked the agent's OWN answer behind them — the topic looked
+ * hung. Fix: dedup against the last text we DECIDED to enqueue (recorded
+ * synchronously at decision time) AND never enqueue while one edit is still in
+ * flight.
+ */
+function checkShouldEnqueueSubagentStatus(input) {
+    if (input.isEditInFlight)
+        return false;
+    return checkShouldSendSubagentStatus(input.nextText, input.lastEnqueuedText);
+}
+/**
+ * @description S2 hard safety net for the dedicated sub-agent status tick:
+ * should the frame be CLOSED (instead of re-arming the elapsed-tick timer)?
+ * `true` when the owning session is no longer active, OR the frame has outlived
+ * any realistic delegation (`maxAgeMs`). A session that dies server-side emits
+ * no clean idle/finish, so the adapter's defensive close never fires and the
+ * self-re-arming timer would otherwise live forever churning the topic (live
+ * 2026-08-03). A `null` `startedAtMs` (should never happen while a message is
+ * open) is treated as "just started", so a transient race can never force-close
+ * an otherwise healthy frame on the age branch.
+ */
+function checkShouldExpireSubagentStatus(input) {
+    if (!input.isOwningSessionActive)
+        return true;
+    const startedAt = input.startedAtMs ?? input.nowMs;
+    return input.nowMs - startedAt > input.maxAgeMs;
+}
+//# sourceMappingURL=subagentStatusRender.js.map

package/dist/utils/subagentStatusRender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagentStatusRender.js","sourceRoot":"","sources":["../../src/utils/subagentStatusRender.ts"],"names":[],"mappings":";;AAmCA,sCAKC;AAQD,4DAKC;AAsBD,0DAMC;AAWD,sEAEC;AAsBD,4EAOC;AAaD,0EASC;AAjJD;;;;;;;;;;;;;;;;;GAiBG;AACH,kCAA4B;AAE5B,6EAA6E;AAC7E,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B,6EAA6E;AAC7E,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,iFAAiF;AACjF,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,EAAU;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,eAAe,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,gBAAgB,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,YAAY,GAAG,gBAAgB,CAAC;IAChD,OAAO,GAAG,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED;;;;;GAKG;AACH,SAAgB,wBAAwB,CAAC,KAAoB,EAAE,SAAiB;IAC9E,OAAO,IAAA,QAAC,EAAC,yBAAyB,EAAE;QAClC,KAAK,EAAE,KAAK,IAAI,IAAA,QAAC,EAAC,yBAAyB,CAAC;QAC5C,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAeD;;;;;;GAMG;AACH,SAAgB,uBAAuB,CAAC,KAGvC;IACC,IAAI,KAAK,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IACpE,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,6BAA6B,CAAC,QAAgB,EAAE,QAAuB;IACrF,OAAO,QAAQ,KAAK,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,gCAAgC,CAAC,KAIhD;IACC,IAAI,KAAK,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,6BAA6B,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,+BAA+B,CAAC,KAK/C;IACC,IAAI,CAAC,KAAK,CAAC,qBAAqB;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,KAAK,CAAC;IACnD,OAAO,KAAK,CAAC,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC;AAClD,CAAC"}

package/dist/utils/telegramError.d.ts

@@ -0,0 +1,2 @@
+export declare function checkIsStaleAnswerCallbackQueryError(err: unknown): boolean;
+//# sourceMappingURL=telegramError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"telegramError.d.ts","sourceRoot":"","sources":["../../src/utils/telegramError.ts"],"names":[],"mappings":"AAcA,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAS1E"}

package/dist/utils/telegramError.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkIsStaleAnswerCallbackQueryError = checkIsStaleAnswerCallbackQueryError;
+function checkIsRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function checkIsStaleAnswerCallbackQueryError(err) {
+    if (!checkIsRecord(err))
+        return false;
+    const e = err;
+    const description = e.response?.description ?? '';
+    return (e.response?.error_code === 400 &&
+        e.on?.method === 'answerCallbackQuery' &&
+        /query is too old|query ID is invalid/i.test(description));
+}
+//# sourceMappingURL=telegramError.js.map

package/dist/utils/telegramError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegramError.js","sourceRoot":"","sources":["../../src/utils/telegramError.ts"],"names":[],"mappings":";;AAcA,oFASC;AAbD,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,SAAgB,oCAAoC,CAAC,GAAY;IAC/D,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,CAAC,GAAG,GAAwB,CAAC;IACnC,MAAM,WAAW,GAAG,CAAC,CAAC,QAAQ,EAAE,WAAW,IAAI,EAAE,CAAC;IAClD,OAAO,CACL,CAAC,CAAC,QAAQ,EAAE,UAAU,KAAK,GAAG;QAC9B,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,qBAAqB;QACtC,uCAAuC,CAAC,IAAI,CAAC,WAAW,CAAC,CAC1D,CAAC;AACJ,CAAC"}