charness 0.0.0-stage → 3.0.0

package/dist/utils/providerDisconnectPlan.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @description Pure decision layer behind `/disconnect`: what did deleting a
+ * provider's stored credentials actually achieve?
+ *
+ * `DELETE /auth/:id` only removes what OpenCode keeps in its own auth store. A
+ * provider it enables from an ENVIRONMENT VARIABLE (`openrouter` ←
+ * `OPENROUTER_API_KEY`) stays fully active afterwards — reporting "disconnected"
+ * there would be a lie, and it is exactly the case that motivated the
+ * bot-side "hide provider" toggle in `/model`. So the adapter re-reads the live
+ * provider config after the delete and asks this helper what to tell the user.
+ */
+/**
+ * @name ProviderDisconnectOutcome
+ * @description
+ * - `removed` — the provider is gone from the live catalog: a clean disconnect.
+ * - `stillActiveViaEnv` — credentials were removed but the provider is still
+ *   listed, i.e. it comes from an environment variable the bot cannot unset.
+ */
+export type ProviderDisconnectOutcome = 'removed' | 'stillActiveViaEnv';
+/** Anchored matcher for `bot.action(...)`, kept beside the builder so the wire
+ *  format has one definition. */
+export declare const disconnectProviderCallbackRe: RegExp;
+/**
+ * @description Callback id for one row of the bare-`/disconnect` provider
+ * picker. Index-based like `connm_<idx>` / `resume_<idx>`: Telegram caps
+ * `callback_data` at 64 bytes, so the tapped entry is resolved against the
+ * per-thread snapshot the picker stored rather than carried by name.
+ */
+export declare function buildDisconnectProviderCallback(providerIndex: number): string;
+export declare function parseDisconnectProviderCallback(callbackData: string): number | null;
+/**
+ * @description How many picker snapshots the bot keeps before evicting the
+ * oldest. Each is a handful of short provider ids, and an operator realistically
+ * opens a couple of pickers — the cap only exists so a long-lived process can
+ * never accumulate them without bound.
+ */
+export declare const disconnectPickerSnapshotLimit = 50;
+/**
+ * @description Snapshot key for ONE picker message.
+ *
+ * Keying by thread alone is a destructive bug: a second `/disconnect`
+ * overwrites the thread's snapshot while the FIRST picker's buttons stay
+ * tappable forever, so tapping "openai" (index 1) on the old message resolves
+ * index 1 against the NEW list and deletes a different provider's credentials.
+ * The message id makes each keyboard resolve only against the list it was
+ * rendered from.
+ */
+export declare function buildDisconnectPickerKey(threadKeyString: string, messageId: number): string;
+/**
+ * @description Every snapshot key belonging to `threadKeyString` — the thread
+ * teardown sweep, which must drop ALL of a thread's picker snapshots, not just
+ * one.
+ *
+ * The trailing-digits check is load-bearing: a bare `startsWith` on the thread
+ * key would make thread `-100:1` claim thread `-100:12`'s snapshots
+ * (`"-100:12:5".startsWith("-100:1")` is true), wiping a live sibling topic's
+ * picker.
+ */
+export declare function getDisconnectPickerKeysForThread(pickerKeys: Iterable<string>, threadKeyString: string): string[];
+/**
+ * @description Keys to evict so the snapshot store stays bounded — the oldest
+ * first (`Map` preserves insertion order), keeping at most `limit` entries.
+ */
+export declare function getEvictedDisconnectPickerKeys(pickerKeys: Iterable<string>, limit?: number): string[];
+/**
+ * @description Resolve a tapped `dscp_<idx>` button against the snapshot of the
+ * message it sits on.
+ *
+ * Returns `null` — never another message's provider — when the tap carries no
+ * message id, when that message's snapshot is gone (an old picker after a
+ * restart or an eviction), or when the index is out of range. The caller turns
+ * `null` into the "this menu expired" toast.
+ */
+export declare function getDisconnectPickerProviderAt(snapshots: ReadonlyMap<string, readonly string[]>, threadKeyString: string, messageId: number | null, index: number): string | null;
+/**
+ * @description Classify a finished disconnect from the provider ids still
+ * active after the delete. Comparison is trim+lowercase so a differently-cased
+ * catalog entry is never mistaken for a removed provider (which would report a
+ * clean disconnect for a provider that is still serving models).
+ */
+export declare function getProviderDisconnectOutcome(providerId: string, activeProviderIdsAfterDelete: readonly string[]): ProviderDisconnectOutcome;
+//# sourceMappingURL=providerDisconnectPlan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"providerDisconnectPlan.d.ts","sourceRoot":"","sources":["../../src/utils/providerDisconnectPlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,mBAAmB,CAAC;AAIxE;iCACiC;AACjC,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGnF;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,eAAe,EAAE,MAAM,GACtB,MAAM,EAAE,CAKV;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,KAAK,GAAE,MAAsC,GAC5C,MAAM,EAAE,CAGV;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EACjD,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAIf;AAMD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,4BAA4B,EAAE,SAAS,MAAM,EAAE,GAC9C,yBAAyB,CAM3B"}

package/dist/utils/providerDisconnectPlan.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * @description Pure decision layer behind `/disconnect`: what did deleting a
+ * provider's stored credentials actually achieve?
+ *
+ * `DELETE /auth/:id` only removes what OpenCode keeps in its own auth store. A
+ * provider it enables from an ENVIRONMENT VARIABLE (`openrouter` ←
+ * `OPENROUTER_API_KEY`) stays fully active afterwards — reporting "disconnected"
+ * there would be a lie, and it is exactly the case that motivated the
+ * bot-side "hide provider" toggle in `/model`. So the adapter re-reads the live
+ * provider config after the delete and asks this helper what to tell the user.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.disconnectPickerSnapshotLimit = exports.disconnectProviderCallbackRe = void 0;
+exports.buildDisconnectProviderCallback = buildDisconnectProviderCallback;
+exports.parseDisconnectProviderCallback = parseDisconnectProviderCallback;
+exports.buildDisconnectPickerKey = buildDisconnectPickerKey;
+exports.getDisconnectPickerKeysForThread = getDisconnectPickerKeysForThread;
+exports.getEvictedDisconnectPickerKeys = getEvictedDisconnectPickerKeys;
+exports.getDisconnectPickerProviderAt = getDisconnectPickerProviderAt;
+exports.getProviderDisconnectOutcome = getProviderDisconnectOutcome;
+const disconnectProviderCallbackPrefix = 'dscp_';
+/** Anchored matcher for `bot.action(...)`, kept beside the builder so the wire
+ *  format has one definition. */
+exports.disconnectProviderCallbackRe = /^dscp_(\d+)$/;
+/**
+ * @description Callback id for one row of the bare-`/disconnect` provider
+ * picker. Index-based like `connm_<idx>` / `resume_<idx>`: Telegram caps
+ * `callback_data` at 64 bytes, so the tapped entry is resolved against the
+ * per-thread snapshot the picker stored rather than carried by name.
+ */
+function buildDisconnectProviderCallback(providerIndex) {
+    return `${disconnectProviderCallbackPrefix}${providerIndex}`;
+}
+function parseDisconnectProviderCallback(callbackData) {
+    const match = exports.disconnectProviderCallbackRe.exec(callbackData);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * @description How many picker snapshots the bot keeps before evicting the
+ * oldest. Each is a handful of short provider ids, and an operator realistically
+ * opens a couple of pickers — the cap only exists so a long-lived process can
+ * never accumulate them without bound.
+ */
+exports.disconnectPickerSnapshotLimit = 50;
+/**
+ * @description Snapshot key for ONE picker message.
+ *
+ * Keying by thread alone is a destructive bug: a second `/disconnect`
+ * overwrites the thread's snapshot while the FIRST picker's buttons stay
+ * tappable forever, so tapping "openai" (index 1) on the old message resolves
+ * index 1 against the NEW list and deletes a different provider's credentials.
+ * The message id makes each keyboard resolve only against the list it was
+ * rendered from.
+ */
+function buildDisconnectPickerKey(threadKeyString, messageId) {
+    return `${threadKeyString}:${messageId}`;
+}
+/**
+ * @description Every snapshot key belonging to `threadKeyString` — the thread
+ * teardown sweep, which must drop ALL of a thread's picker snapshots, not just
+ * one.
+ *
+ * The trailing-digits check is load-bearing: a bare `startsWith` on the thread
+ * key would make thread `-100:1` claim thread `-100:12`'s snapshots
+ * (`"-100:12:5".startsWith("-100:1")` is true), wiping a live sibling topic's
+ * picker.
+ */
+function getDisconnectPickerKeysForThread(pickerKeys, threadKeyString) {
+    const prefix = `${threadKeyString}:`;
+    return [...pickerKeys].filter((pickerKey) => pickerKey.startsWith(prefix) && /^\d+$/.test(pickerKey.slice(prefix.length)));
+}
+/**
+ * @description Keys to evict so the snapshot store stays bounded — the oldest
+ * first (`Map` preserves insertion order), keeping at most `limit` entries.
+ */
+function getEvictedDisconnectPickerKeys(pickerKeys, limit = exports.disconnectPickerSnapshotLimit) {
+    const keys = [...pickerKeys];
+    return keys.length <= limit ? [] : keys.slice(0, keys.length - limit);
+}
+/**
+ * @description Resolve a tapped `dscp_<idx>` button against the snapshot of the
+ * message it sits on.
+ *
+ * Returns `null` — never another message's provider — when the tap carries no
+ * message id, when that message's snapshot is gone (an old picker after a
+ * restart or an eviction), or when the index is out of range. The caller turns
+ * `null` into the "this menu expired" toast.
+ */
+function getDisconnectPickerProviderAt(snapshots, threadKeyString, messageId, index) {
+    if (messageId === null || !Number.isInteger(index) || index < 0)
+        return null;
+    const providers = snapshots.get(buildDisconnectPickerKey(threadKeyString, messageId));
+    return providers?.[index] ?? null;
+}
+function normalizeProviderId(providerId) {
+    return providerId.trim().toLowerCase();
+}
+/**
+ * @description Classify a finished disconnect from the provider ids still
+ * active after the delete. Comparison is trim+lowercase so a differently-cased
+ * catalog entry is never mistaken for a removed provider (which would report a
+ * clean disconnect for a provider that is still serving models).
+ */
+function getProviderDisconnectOutcome(providerId, activeProviderIdsAfterDelete) {
+    const target = normalizeProviderId(providerId);
+    const isStillActive = activeProviderIdsAfterDelete.some((activeProviderId) => normalizeProviderId(activeProviderId) === target);
+    return isStillActive ? 'stillActiveViaEnv' : 'removed';
+}
+//# sourceMappingURL=providerDisconnectPlan.js.map

package/dist/utils/providerDisconnectPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providerDisconnectPlan.js","sourceRoot":"","sources":["../../src/utils/providerDisconnectPlan.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAuBH,0EAEC;AAED,0EAGC;AAoBD,4DAEC;AAYD,4EAQC;AAMD,wEAMC;AAWD,sEASC;AAYD,oEASC;AAlHD,MAAM,gCAAgC,GAAG,OAAO,CAAC;AAEjD;iCACiC;AACpB,QAAA,4BAA4B,GAAG,cAAc,CAAC;AAE3D;;;;;GAKG;AACH,SAAgB,+BAA+B,CAAC,aAAqB;IACnE,OAAO,GAAG,gCAAgC,GAAG,aAAa,EAAE,CAAC;AAC/D,CAAC;AAED,SAAgB,+BAA+B,CAAC,YAAoB;IAClE,MAAM,KAAK,GAAG,oCAA4B,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9D,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACU,QAAA,6BAA6B,GAAG,EAAE,CAAC;AAEhD;;;;;;;;;GASG;AACH,SAAgB,wBAAwB,CAAC,eAAuB,EAAE,SAAiB;IACjF,OAAO,GAAG,eAAe,IAAI,SAAS,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,gCAAgC,CAC9C,UAA4B,EAC5B,eAAuB;IAEvB,MAAM,MAAM,GAAG,GAAG,eAAe,GAAG,CAAC;IACrC,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,MAAM,CAC3B,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAC5F,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,8BAA8B,CAC5C,UAA4B,EAC5B,QAAgB,qCAA6B;IAE7C,MAAM,IAAI,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,6BAA6B,CAC3C,SAAiD,EACjD,eAAuB,EACvB,SAAwB,EACxB,KAAa;IAEb,IAAI,SAAS,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7E,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,wBAAwB,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC,CAAC;IACtF,OAAO,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AACpC,CAAC;AAED,SAAS,mBAAmB,CAAC,UAAkB;IAC7C,OAAO,UAAU,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,4BAA4B,CAC1C,UAAkB,EAClB,4BAA+C;IAE/C,MAAM,MAAM,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,4BAA4B,CAAC,IAAI,CACrD,CAAC,gBAAgB,EAAE,EAAE,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,KAAK,MAAM,CACvE,CAAC;IACF,OAAO,aAAa,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC"}

package/dist/utils/rateLimitLog.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @description Pure formatters for the always-on rate-limit instrumentation
+ * (plan 2026-06-24-rate-limit-429-metrics). Kept pure + separate from
+ * `rateLimiter.ts`'s module state so they're trivially unit-testable: given the
+ * measured rate + queue context, return the exact log string.
+ *
+ * Both lines stay greppable in the bot-console log:
+ *   - `[RateLimit] 429` — every 429 the bot receives, with rich context;
+ *   - `[RateLimit] rate` — the periodic per-chat outbound-rate summary.
+ */
+/**
+ * @description Snapshot of the outbound channel at the instant a 429 was
+ * received, gathered from the send-rate tracker (rate) and the global send
+ * pacer (how many sends were parked behind the gate).
+ */
+export interface RateLimit429Context {
+    chatId: number;
+    /** Telegram's `retry_after` for this 429, in seconds (already parsed). */
+    retryAfterSec: number;
+    /** Sends issued for this chat in the last 60s at the moment of the 429. */
+    sentPerMin: number;
+    /** Busiest short-burst count (sends in any 10s sub-window) in that minute. */
+    peak10s: number;
+    /** Sends currently parked on the global send pacer (FCFS, no priority). */
+    queuedSends: number;
+    /** Whether this was the SECOND consecutive 429 (after the single retry). */
+    isAfterRetry: boolean;
+}
+/**
+ * @description Build the rich, greppable 429 log line. Example:
+ *
+ *   [RateLimit] 429 chat=-100123 retryAfter=5s sent/min=38 peak10s=12 queue=7 after_retry=yes
+ *
+ * Every field is load-bearing for tuning the send pacing later: the measured
+ * send-rate (how hard we were pushing), the peak burst (spikes the average
+ * hides), and the global queue depth (how much was backed up behind the gate).
+ */
+export declare function formatRateLimit429Line(context: RateLimit429Context): string;
+/**
+ * @description Build the periodic per-chat outbound-rate summary line. Example:
+ *
+ *   [RateLimit] rate chat=-100123 sent/min=22 peak10s=8
+ *
+ * Logged only for chats with recent activity so we can see how close normal
+ * operation runs to the per-chat ceiling WITHOUT needing a 429 to occur.
+ */
+export declare function formatRateSummaryLine(chatId: number, sentPerMin: number, peak10s: number): string;
+//# sourceMappingURL=rateLimitLog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimitLog.d.ts","sourceRoot":"","sources":["../../src/utils/rateLimitLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAS3E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjG"}

package/dist/utils/rateLimitLog.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * @description Pure formatters for the always-on rate-limit instrumentation
+ * (plan 2026-06-24-rate-limit-429-metrics). Kept pure + separate from
+ * `rateLimiter.ts`'s module state so they're trivially unit-testable: given the
+ * measured rate + queue context, return the exact log string.
+ *
+ * Both lines stay greppable in the bot-console log:
+ *   - `[RateLimit] 429` — every 429 the bot receives, with rich context;
+ *   - `[RateLimit] rate` — the periodic per-chat outbound-rate summary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRateLimit429Line = formatRateLimit429Line;
+exports.formatRateSummaryLine = formatRateSummaryLine;
+/**
+ * @description Build the rich, greppable 429 log line. Example:
+ *
+ *   [RateLimit] 429 chat=-100123 retryAfter=5s sent/min=38 peak10s=12 queue=7 after_retry=yes
+ *
+ * Every field is load-bearing for tuning the send pacing later: the measured
+ * send-rate (how hard we were pushing), the peak burst (spikes the average
+ * hides), and the global queue depth (how much was backed up behind the gate).
+ */
+function formatRateLimit429Line(context) {
+    return (`[RateLimit] 429 chat=${context.chatId} ` +
+        `retryAfter=${context.retryAfterSec}s ` +
+        `sent/min=${context.sentPerMin} ` +
+        `peak10s=${context.peak10s} ` +
+        `queue=${context.queuedSends} ` +
+        `after_retry=${context.isAfterRetry ? 'yes' : 'no'}`);
+}
+/**
+ * @description Build the periodic per-chat outbound-rate summary line. Example:
+ *
+ *   [RateLimit] rate chat=-100123 sent/min=22 peak10s=8
+ *
+ * Logged only for chats with recent activity so we can see how close normal
+ * operation runs to the per-chat ceiling WITHOUT needing a 429 to occur.
+ */
+function formatRateSummaryLine(chatId, sentPerMin, peak10s) {
+    return `[RateLimit] rate chat=${chatId} sent/min=${sentPerMin} peak10s=${peak10s}`;
+}
+//# sourceMappingURL=rateLimitLog.js.map

package/dist/utils/rateLimitLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimitLog.js","sourceRoot":"","sources":["../../src/utils/rateLimitLog.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AA8BH,wDASC;AAUD,sDAEC;AA9BD;;;;;;;;GAQG;AACH,SAAgB,sBAAsB,CAAC,OAA4B;IACjE,OAAO,CACL,wBAAwB,OAAO,CAAC,MAAM,GAAG;QACzC,cAAc,OAAO,CAAC,aAAa,IAAI;QACvC,YAAY,OAAO,CAAC,UAAU,GAAG;QACjC,WAAW,OAAO,CAAC,OAAO,GAAG;QAC7B,SAAS,OAAO,CAAC,WAAW,GAAG;QAC/B,eAAe,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CACrD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,qBAAqB,CAAC,MAAc,EAAE,UAAkB,EAAE,OAAe;IACvF,OAAO,yBAAyB,MAAM,aAAa,UAAU,YAAY,OAAO,EAAE,CAAC;AACrF,CAAC"}

package/dist/utils/recentRelayWindow.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @description Rolling window of recently-RELAYED Claude pane lines — the
+ * long-horizon companion to the per-poll line-set diff (`getNewPaneContent`
+ * in `adapters/claudeCliAdapter.ts`).
+ *
+ * WHY it exists (live incident 2026-06-10, plan
+ * `agent/tasks/actual/2026-06-10-claude-stale-rescrape-dedup.md`): the
+ * per-poll diff only knows the immediately-previous pane capture. When the
+ * Claude TUI re-renders hours-old scrollback (full repaint, scroll-through,
+ * resize), the redrawn lines are absent from that previous capture, so the
+ * diff classifies them as "new" and re-relays them — chunked and overlapping
+ * as the pane scrolls (a topic was flooded with ~12 chunks of a stale ~1400
+ * line diff). This window remembers what was actually RELAYED to the topic,
+ * so a re-render of already-sent content is suppressed regardless of WHAT
+ * triggered the redraw.
+ *
+ * Locked tradeoff — the SAME direction as the per-poll set diff (see
+ * `getNewPaneContent`'s JSDoc): err toward DROPPING a re-render duplicate. A
+ * re-send flood is the user-visible bug; a rare suppressed legit repeat (e.g.
+ * re-running an identical long command within the window horizon) is a
+ * low-cost loss. Like `lastContent`, the window does not self-heal a
+ * wrongly-suppressed line within its horizon. Two guards bound the damage:
+ * only SUBSTANTIAL lines (≥ {@link relayDedupMinLineLength} after
+ * normalization) are ever recorded or suppressed — short lines ("yes",
+ * "done", list bullets) repeat legitimately all the time and always pass —
+ * and the FIFO bound means old lines eventually evict as new content is
+ * relayed.
+ */
+/**
+ * @description Minimum NORMALIZED line length for the window to record or
+ * suppress a line. Shorter lines repeat legitimately too often (confirmations,
+ * bullets, numbers) to ever be treated as re-render duplicates.
+ */
+export declare const relayDedupMinLineLength = 16;
+/**
+ * @description Window capacity in lines. Sized to cover the incident-scale
+ * re-render (a ~1400-line stale diff) with headroom, while keeping the memory
+ * bound trivial and letting truly old content evict.
+ */
+export declare const relayWindowMaxLines = 1500;
+/**
+ * @description Capacity of the block-signature FIFO behind
+ * {@link RecentRelayWindow.checkBlockAlreadyRelayed}. A block is one emitted
+ * chunk (a table, a prose paragraph) recorded as a SINGLE joined signature, so
+ * far fewer entries than the per-line window need bounding. Sized to remember a
+ * good run of recent emitted blocks (covers a looped table re-printed many times
+ * within a turn) while keeping the memory bound trivial.
+ */
+export declare const relayBlockSignatureMax = 200;
+/**
+ * @description Normalise a pane line for line-identity comparison: trim, then
+ * drop a single leading spinner/state glyph ({@link LEADING_COMPARISON_GLYPH_RE}).
+ *
+ * Single source of truth for BOTH dedup layers — the per-poll set diff
+ * (`getNewPaneContent`) and this relay window — which MUST share one
+ * normalization domain: the window stores the same normalized forms the pane
+ * diff compares, otherwise a redraw would slip past one layer or the other.
+ * Comparison-ONLY: this shapes equality/dedup keys, never the text emitted.
+ */
+export declare function normalizeForComparison(line: string): string;
+/**
+ * @description COARSER normalization for the LONG-HORIZON relay-window dedup
+ * (record + suppress). Builds on {@link normalizeForComparison} and ADDITIONALLY
+ * strips markdown emphasis/code markers (`*`, `_`, `` ` ``, `~`) and collapses
+ * whitespace runs.
+ *
+ * WHY a second, coarser form (live re-emit 2026-06-15): a line that scrolled off
+ * and was re-rendered comes back with the SAME text but different emphasis spans
+ * — `the Claude *liveness loop* …` one capture, `the Claude *liveness* *loop* …`
+ * the next — or shifted padding/wrapping. The per-poll diff's plain
+ * normalization left those as DIFFERENT strings, so the window failed to
+ * recognise the re-render and re-emitted it. Stripping the volatile markup makes
+ * the re-render match.
+ *
+ * It is a strict COARSENING of {@link normalizeForComparison} (only further
+ * transforms its output), so the window still recognises every line the per-poll
+ * diff emitted (it can only match MORE, never fewer) — the "no redraw slips past
+ * one layer" guarantee holds, WITHOUT touching the per-poll core diff (and group
+ * mode), where over-suppression would risk dropping genuinely-new content.
+ */
+export declare function normalizeForRelayDedup(line: string): string;
+/**
+ * @description Build a single normalized signature for a WHOLE block (a table,
+ * a paragraph) so a fully-duplicate block can be recognised even when its
+ * individual lines are too short to clear the per-line {@link
+ * relayDedupMinLineLength} gate — table border rows (`├──┤`) and tiny cells
+ * (`│ ✅ │`) are exactly that case. Drops blank lines, normalizes each surviving
+ * line in the SAME coarse domain {@link normalizeForRelayDedup} uses, and joins
+ * with `\n`. Returns `''` for a block with no substantial content (so a
+ * whitespace-only block is never treated as a relayed block).
+ */
+export declare function buildRelayBlockSignature(blockText: string): string;
+/**
+ * @description Bounded FIFO of normalized, already-relayed pane lines.
+ * Created per Claude session; see {@link createRecentRelayWindow}.
+ */
+export interface RecentRelayWindow {
+    /**
+     * Store the chunk's substantial lines (normalized) AND the chunk's joined
+     * block signature ({@link buildRelayBlockSignature}). Call ONLY after the
+     * chunk was actually emitted as permanent OUTPUT — transient status frames
+     * roll in place and never flood as separate messages, so recording them
+     * would only risk suppressing genuine output.
+     */
+    record(chunkText: string): void;
+    /**
+     * True when the line's normalized form is a substantial line already
+     * relayed. Short lines (< {@link relayDedupMinLineLength}) always return
+     * false — they are never suppressed — EXCEPT a short `NN +` diff-change
+     * gutter ({@link DIFF_CHANGE_GUTTER_RE}), which is recorded + suppressed on
+     * re-appearance (it re-renders and leaks; the shape is never short prose).
+     */
+    checkHasLine(line: string): boolean;
+    /**
+     * True when the WHOLE block (its joined {@link buildRelayBlockSignature})
+     * was already relayed — the table-flood guard. Recognises a fully-duplicate
+     * block even when every line is too short for the per-line gate. An
+     * empty-signature block (whitespace only) always returns false.
+     */
+    checkBlockAlreadyRelayed(blockText: string): boolean;
+    /** Forget everything (session lifecycle reset points). */
+    reset(): void;
+}
+/**
+ * @description Create an empty relay window holding up to `maxLines`
+ * normalized lines; the oldest line is evicted first once full.
+ */
+export declare function createRecentRelayWindow(maxLines?: number): RecentRelayWindow;
+/**
+ * @description Seed a FRESH relay window from a full pane snapshot so a re-render
+ * of content ALREADY ON the pane is recognised as already-relayed on the very
+ * first poll — never re-emitted.
+ *
+ * WHY (live incident 2026-06-24): on adopt/re-attach the bot already
+ * seeds the pane-diff baseline (`lastContent`), which suppresses re-appearing
+ * PROSE. But a SETTLED table already on the pane is deduped ONLY at the BLOCK
+ * level ({@link RecentRelayWindow.checkBlockAlreadyRelayed} in
+ * `emitStabilizedTable`) — its border rows and tiny cells fall under the per-line
+ * gate. Adopt did NOT seed this window, so the first post-adopt poll saw the
+ * table's block signature as unknown and RE-EMITTED the whole table once per
+ * restart (~1100 chars). Recording the pane (per-line + whole-pane block) AND the
+ * settled table's OWN block signature here makes that first re-render hit
+ * `checkBlockAlreadyRelayed === true` and be suppressed.
+ *
+ * `getTableBlock` is injected (the adapter passes its `getLastSharpTableBlock`)
+ * to keep this module free of an adapter import — the adapter already imports
+ * from here, so the reverse would be a cycle. Pure (no I/O); the `record` calls
+ * are byte-identical to the ones the live emit path makes, so the window's
+ * domains agree.
+ */
+export declare function seedRelayWindowFromPane(window: RecentRelayWindow, paneText: string, getTableBlock: (content: string) => string | null): void;
+/**
+ * @description Filter a pane-diff chunk against the window: drop every line
+ * whose normalized form was already relayed (substantial lines only — short
+ * lines always pass). Returns `''` when nothing survives, so the caller can
+ * skip the poll's emit entirely (no empty messages).
+ *
+ * Blank-line shaping mirrors `getNewPaneContent`'s pending-blank exactly: a
+ * single blank that sat BETWEEN two surviving lines is preserved as a
+ * paragraph separator; leading/trailing blanks and blanks adjacent to dropped
+ * lines never leak out. An already-shaped chunk passes through an empty
+ * window byte-identical — fresh output is never altered.
+ */
+export declare function getRelayDedupedChunk(relayWindow: RecentRelayWindow, chunkText: string): string;
+//# sourceMappingURL=recentRelayWindow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recentRelayWindow.d.ts","sourceRoot":"","sources":["../../src/utils/recentRelayWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAqB1C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAa1C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMlE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC;;;;;OAKG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACrD,0DAA0D;IAC1D,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,GAAE,MAA4B,GAAG,iBAAiB,CA6DjG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAChD,IAAI,CAUN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAwB9F"}