@a1hvdy/cc-openclaw 0.24.0 → 0.25.0

package/dist/src/channels/telegram-mirror/failure/pool-exhausted-fallback.js

@@ -0,0 +1,24 @@
+/**
+ * failure/pool-exhausted-fallback.ts — v0.25.0 M12.
+ *
+ * Mode: pool-exhausted-fallback. The SubprocessPool (v0.16+ / M1
+ * v0.24.0) is saturated — incoming turn falls back to direct CLI spawn.
+ * The user surface is informational only; the engine completes the turn
+ * regardless. Tracked so soak instrumentation can flag if it fires often.
+ */
+export const META = {
+    mode: 'pool-exhausted-fallback',
+    glyph: 'ℹ️',
+    severity: 'info',
+};
+export const handle = (ctx, info) => {
+    const sz = info?.poolSize && Number.isFinite(info.poolSize) ? ` (${info.poolSize} slots in use)` : '';
+    return [
+        {
+            type: 'sendMessage',
+            chat_id: ctx.chatId,
+            text: `${META.glyph} Subprocess pool full${sz} — running this turn via direct CLI.`,
+        },
+    ];
+};
+//# sourceMappingURL=pool-exhausted-fallback.js.map

package/dist/src/channels/telegram-mirror/failure/pool-exhausted-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-exhausted-fallback.js","sourceRoot":"","sources":["../../../../../src/channels/telegram-mirror/failure/pool-exhausted-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,CAAC,MAAM,IAAI,GAAsB;IACrC,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,IAAI;IACX,QAAQ,EAAE,MAAM;CACjB,CAAC;AAOF,MAAM,CAAC,MAAM,MAAM,GAAsC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;IACrE,MAAM,EAAE,GAAG,IAAI,EAAE,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,QAAQ,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IACtG,OAAO;QACL;YACE,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE,GAAG,CAAC,MAAM;YACnB,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,wBAAwB,EAAE,sCAAsC;SACpF;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/channels/telegram-mirror/failure/rate-limit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * failure/rate-limit.ts — v0.25.0 M12.
+ *
+ * Mode: rate-limit. Telegram bot API 429 or Anthropic 429 hit. Caller
+ * supplies the upstream retry-after hint when known; default surface is
+ * a transparent back-off advisory without prompting user action.
+ */
+import type { FailureHandler, FailureModuleMeta } from './types.js';
+export declare const META: FailureModuleMeta;
+export interface RateLimitInfo {
+    /** Source of the limit — "telegram" or "anthropic". */
+    source?: 'telegram' | 'anthropic';
+    /** Server-advertised retry-after seconds, when available. */
+    retryAfterSec?: number;
+}
+export declare const handle: FailureHandler<RateLimitInfo>;

package/dist/src/channels/telegram-mirror/failure/rate-limit.js

@@ -0,0 +1,26 @@
+/**
+ * failure/rate-limit.ts — v0.25.0 M12.
+ *
+ * Mode: rate-limit. Telegram bot API 429 or Anthropic 429 hit. Caller
+ * supplies the upstream retry-after hint when known; default surface is
+ * a transparent back-off advisory without prompting user action.
+ */
+export const META = {
+    mode: 'rate-limit',
+    glyph: '🟧',
+    severity: 'warn',
+};
+export const handle = (ctx, info) => {
+    const src = info?.source ?? 'upstream';
+    const after = info?.retryAfterSec && Number.isFinite(info.retryAfterSec)
+        ? ` Retrying in ${info.retryAfterSec}s.`
+        : '';
+    return [
+        {
+            type: 'sendMessage',
+            chat_id: ctx.chatId,
+            text: `${META.glyph} Rate-limited by ${src}.${after} Auto-backing off.`,
+        },
+    ];
+};
+//# sourceMappingURL=rate-limit.js.map

package/dist/src/channels/telegram-mirror/failure/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../../../../src/channels/telegram-mirror/failure/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,CAAC,MAAM,IAAI,GAAsB;IACrC,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,IAAI;IACX,QAAQ,EAAE,MAAM;CACjB,CAAC;AASF,MAAM,CAAC,MAAM,MAAM,GAAkC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;IACjE,MAAM,GAAG,GAAG,IAAI,EAAE,MAAM,IAAI,UAAU,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,EAAE,aAAa,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC;QACtE,CAAC,CAAC,gBAAgB,IAAI,CAAC,aAAa,IAAI;QACxC,CAAC,CAAC,EAAE,CAAC;IACP,OAAO;QACL;YACE,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE,GAAG,CAAC,MAAM;YACnB,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,oBAAoB,GAAG,IAAI,KAAK,oBAAoB;SACxE;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/channels/telegram-mirror/failure/returning-after-24h.d.ts

@@ -0,0 +1,14 @@
+/**
+ * failure/returning-after-24h.ts — v0.25.0 M12.
+ *
+ * Mode: returning-after-24h. The chat last had inbound activity more
+ * than 24 hours ago. Surfaces a friendly welcome-back + status hint so
+ * the user can decide whether to resume vs start fresh.
+ */
+import type { FailureHandler, FailureModuleMeta } from './types.js';
+export declare const META: FailureModuleMeta;
+export interface ReturningAfter24hInfo {
+    /** Hours since the last inbound activity, rounded to nearest integer. */
+    hoursAgo?: number;
+}
+export declare const handle: FailureHandler<ReturningAfter24hInfo>;

package/dist/src/channels/telegram-mirror/failure/returning-after-24h.js

@@ -0,0 +1,33 @@
+/**
+ * failure/returning-after-24h.ts — v0.25.0 M12.
+ *
+ * Mode: returning-after-24h. The chat last had inbound activity more
+ * than 24 hours ago. Surfaces a friendly welcome-back + status hint so
+ * the user can decide whether to resume vs start fresh.
+ */
+export const META = {
+    mode: 'returning-after-24h',
+    glyph: '👋',
+    severity: 'info',
+};
+function formatHoursAgo(h) {
+    if (h >= 168)
+        return `${Math.floor(h / 168)}w ago`;
+    if (h >= 24)
+        return `${Math.floor(h / 24)}d ago`;
+    return `${h}h ago`;
+}
+export const handle = (ctx, info) => {
+    const ago = info?.hoursAgo && Number.isFinite(info.hoursAgo)
+        ? formatHoursAgo(info.hoursAgo)
+        : '24h+ ago';
+    return [
+        {
+            type: 'sendMessage',
+            chat_id: ctx.chatId,
+            text: `${META.glyph} Welcome back — last activity ${ago}. ` +
+                `Type /status to inspect sessions or /sessions to switch.`,
+        },
+    ];
+};
+//# sourceMappingURL=returning-after-24h.js.map

package/dist/src/channels/telegram-mirror/failure/returning-after-24h.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"returning-after-24h.js","sourceRoot":"","sources":["../../../../../src/channels/telegram-mirror/failure/returning-after-24h.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,CAAC,MAAM,IAAI,GAAsB;IACrC,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,IAAI;IACX,QAAQ,EAAE,MAAM;CACjB,CAAC;AAOF,SAAS,cAAc,CAAC,CAAS;IAC/B,IAAI,CAAC,IAAI,GAAG;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC;IACnD,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;IACjD,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAA0C,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;IACzE,MAAM,GAAG,GACP,IAAI,EAAE,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC9C,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC/B,CAAC,CAAC,UAAU,CAAC;IACjB,OAAO;QACL;YACE,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE,GAAG,CAAC,MAAM;YACnB,IAAI,EACF,GAAG,IAAI,CAAC,KAAK,iCAAiC,GAAG,IAAI;gBACrD,0DAA0D;SAC7D;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/channels/telegram-mirror/failure/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * src/channels/telegram-mirror/failure/types.ts — v0.25.0 M12 shared types.
+ *
+ * Each failure mode lives in its own file per ADR-008 ("per-mode handlers
+ * make each response shape testable and grep-able"). This file holds the
+ * shared types so the 8 handler modules stay tight (each ~30-50 lines).
+ */
+import type { TelegramAction } from '../commands.js';
+export interface FailureContext {
+    chatId: string | number;
+}
+export type Severity = 'info' | 'warn' | 'error';
+/**
+ * Shape every failure handler exports. Handlers are pure functions:
+ * inputs are the chat context + an optional info payload; output is the
+ * array of TelegramAction the dispatch layer applies.
+ */
+export type FailureHandler<I = unknown> = (ctx: FailureContext, info?: I) => TelegramAction[];
+/**
+ * Registry-side metadata per failure module. Asserted by M13's chaos
+ * test against the file name + handler shape.
+ */
+export interface FailureModuleMeta {
+    /** Mode id, matches the file name without the .ts extension. */
+    mode: string;
+    /** Glyph that prefixes every emitted message for this mode. */
+    glyph: string;
+    /** Severity classification used by the chaos test + observability. */
+    severity: Severity;
+}

package/dist/src/channels/telegram-mirror/failure/types.js

@@ -0,0 +1,9 @@
+/**
+ * src/channels/telegram-mirror/failure/types.ts — v0.25.0 M12 shared types.
+ *
+ * Each failure mode lives in its own file per ADR-008 ("per-mode handlers
+ * make each response shape testable and grep-able"). This file holds the
+ * shared types so the 8 handler modules stay tight (each ~30-50 lines).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/channels/telegram-mirror/failure/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/channels/telegram-mirror/failure/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/src/channels/telegram-mirror/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * src/channels/telegram-mirror/index.ts — v0.25.0 Telegram Terminal Mirror entry.
+ *
+ * Parallel implementation per ADR-002. The legacy 14-module live card at
+ * src/channels/telegram/ is read-only observability; this mirror replaces it
+ * with a Telegram-native surface (sessions/plan/cost/compose/etc.) so A1 can
+ * drive cc-openclaw from phone without opening the laptop.
+ *
+ * M0 milestone (this file): empty register() stub gated by
+ * CC_OPENCLAW_TERMINAL_MIRROR=1. Subsequent milestones (M1..M16) wire each
+ * subsystem in dependency order. The flag picks which channel barrel loads
+ * at boot — legacy and mirror are mutually exclusive (no double-listener
+ * collisions). Roadmap + ADRs live at
+ * /home/a1xai/dev/cc-openclaw/PRPs/v0.25.0-telegram-terminal-mirror.md.
+ *
+ * ADRs touched at M0: ADR-002 (parallel impl, not in-place).
+ * Risks monitored: R-7 (parallel maintenance burden — re-evaluate at soak start).
+ */
+export interface PluginApi {
+    on(event: string, handler: (...args: unknown[]) => unknown | Promise<unknown>): void;
+    logger?: Console;
+}
+/**
+ * Mirror channel register — idempotent via defaultRegisterGuard.
+ *
+ * M0: empty stub. No api.on() wiring yet; subsequent milestones add handlers.
+ * The stub still completes successfully so M0's exit criterion ("Plugin boot
+ * succeeds in both flag states") holds end-to-end.
+ */
+export declare function register(api: PluginApi): void;

package/dist/src/channels/telegram-mirror/index.js

@@ -0,0 +1,41 @@
+/**
+ * src/channels/telegram-mirror/index.ts — v0.25.0 Telegram Terminal Mirror entry.
+ *
+ * Parallel implementation per ADR-002. The legacy 14-module live card at
+ * src/channels/telegram/ is read-only observability; this mirror replaces it
+ * with a Telegram-native surface (sessions/plan/cost/compose/etc.) so A1 can
+ * drive cc-openclaw from phone without opening the laptop.
+ *
+ * M0 milestone (this file): empty register() stub gated by
+ * CC_OPENCLAW_TERMINAL_MIRROR=1. Subsequent milestones (M1..M16) wire each
+ * subsystem in dependency order. The flag picks which channel barrel loads
+ * at boot — legacy and mirror are mutually exclusive (no double-listener
+ * collisions). Roadmap + ADRs live at
+ * /home/a1xai/dev/cc-openclaw/PRPs/v0.25.0-telegram-terminal-mirror.md.
+ *
+ * ADRs touched at M0: ADR-002 (parallel impl, not in-place).
+ * Risks monitored: R-7 (parallel maintenance burden — re-evaluate at soak start).
+ */
+import { defaultRegisterGuard } from '../../lib/register-guard.js';
+import { initBotTokenFromConfig } from '../../lib/telegram-bot-api.js';
+/**
+ * Mirror channel register — idempotent via defaultRegisterGuard.
+ *
+ * M0: empty stub. No api.on() wiring yet; subsequent milestones add handlers.
+ * The stub still completes successfully so M0's exit criterion ("Plugin boot
+ * succeeds in both flag states") holds end-to-end.
+ */
+export function register(api) {
+    defaultRegisterGuard.guard('cc-openclaw/telegram-mirror', api, () => {
+        const logger = api.logger || console;
+        logger.info('[cc-openclaw/telegram-mirror] M0 skeleton loaded — no handlers wired yet (CC_OPENCLAW_TERMINAL_MIRROR=1).');
+        // v0.25.0 M16 — initialise Telegram bot token (token sourcing migrated
+        // out of the legacy live-card module into src/lib/telegram-bot-api).
+        // Same precedence as before: api.config first, then ~/.openclaw/openclaw.json.
+        initBotTokenFromConfig({
+            config: api.config,
+            logger: logger,
+        });
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/src/channels/telegram-mirror/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/channels/telegram-mirror/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAOvE;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAc;IACrC,oBAAoB,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,EAAE,GAAG,EAAE;QAClE,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,OAAO,CAAC;QACrC,MAAM,CAAC,IAAI,CACT,2GAA2G,CAC5G,CAAC;QACF,uEAAuE;QACvE,qEAAqE;QACrE,+EAA+E;QAC/E,sBAAsB,CAAC;YACrB,MAAM,EAAG,GAAuD,CAAC,MAAM;YACvE,MAAM,EAAE,MAAiF;SAC1F,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/channels/telegram-mirror/plan-attachment.d.ts

@@ -0,0 +1,120 @@
+/**
+ * src/channels/telegram-mirror/plan-attachment.ts — v0.25.0 M9.
+ *
+ * When Claude emits ExitPlanMode (the plan-mode tool call), the mirror
+ * uploads the plan body as a .md document attachment with two inline
+ * buttons (Approve / Reject). Decision: ADR-006 — sendDocument over
+ * editMessageMedia. Rationale: sendDocument is simpler, has the larger
+ * size limit, and matches A1's on-disk plan-file convention.
+ *
+ * Approve → callback payload `{ action: 'plan-approve', planId }` resolves
+ * to model input "approved" which the engine bridge feeds to the running
+ * session.
+ *
+ * Reject → two-phase. The first tap stashes a pending-reject for the chat;
+ * the next non-slash inbound message becomes the rejection feedback payload
+ * "<plan rejected>\n<feedback text>". A tap-then-tap-Reject again clears
+ * the pending state silently.
+ *
+ * Risk references: R-3 (callback_data 64-byte cap) — payloads here route
+ * through CallbackMap exactly like M3's keyboard.
+ */
+import type { CallbackMap } from './callback-mapping.js';
+import type { TelegramAction } from './commands.js';
+/**
+ * Shape of the ExitPlanMode tool_use event we care about. Mirrors the
+ * subset of the upstream stream-event shape — keep narrow so future
+ * upstream changes don't ripple here unnecessarily.
+ */
+export interface ExitPlanModeEvent {
+    /** Tool name; always "ExitPlanMode" for this handler. */
+    toolName: string;
+    /** Free-form plan body (Markdown). */
+    plan: string;
+    /** Optional project slug — used in the .md filename. */
+    slug?: string;
+    /** Optional caption to surface above the document on Telegram (kept short). */
+    caption?: string;
+}
+/**
+ * Compose the slug-prefixed plan filename. Sanitises non-filename chars
+ * so the Telegram upload always succeeds.
+ */
+export declare function planFilename(slug: string | undefined): string;
+/**
+ * Build a sendDocument action carrying the plan + the Approve/Reject
+ * inline keyboard. The callback ids are minted into the supplied
+ * CallbackMap; payloads include a fresh planId so multiple in-flight
+ * plans on the same chat don't collide.
+ */
+export declare function buildPlanAttachment(opts: {
+    chatId: string | number;
+    event: ExitPlanModeEvent;
+    callbackMap: CallbackMap;
+    /** Optional planId override for deterministic tests. */
+    planId?: string;
+}): {
+    action: Extract<TelegramAction, {
+        type: 'sendDocument';
+    }>;
+    planId: string;
+};
+interface RejectPending {
+    chatId: string;
+    planId: string;
+    pendingSince: number;
+}
+export interface RejectFeedbackTrackerOptions {
+    /** TTL after which a pending-reject silently expires (default 10 min). */
+    ttlMs?: number;
+    /** Clock for tests. */
+    now?: () => number;
+}
+/**
+ * Tracks the (chatId → pending-reject) state for two-phase rejection.
+ * The dispatch layer pokes startPending on a Reject tap and consumeFeedback
+ * on the next non-slash inbound. Pending-state TTL prevents a half-open
+ * rejection from corrupting later turns.
+ */
+export declare class RejectFeedbackTracker {
+    private readonly pending;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(opts?: RejectFeedbackTrackerOptions);
+    /**
+     * Mark a chat as having tapped Reject and waiting for feedback. If a
+     * prior pending exists, it is replaced (the user re-tapped on a newer plan).
+     */
+    startPending(chatId: string, planId: string): void;
+    /**
+     * Returns true when the chat has a non-stale pending-reject.
+     */
+    isPending(chatId: string): boolean;
+    /**
+     * Consume the next inbound text as the rejection feedback. Returns a
+     * formatted payload that the engine bridge feeds to openai-compat as a
+     * single user-message, or undefined when no pending state exists.
+     *
+     * Payload shape: "<plan rejected: planId>\n<feedback text>" — the
+     * "<plan rejected>" sentinel lets the model recognise this as
+     * rejection feedback (not a new turn).
+     */
+    consumeFeedback(chatId: string, feedback: string): string | undefined;
+    /**
+     * Drop the pending state without consuming feedback (e.g. user taps
+     * Reject twice, or types another slash command in the interim).
+     */
+    cancel(chatId: string): boolean;
+    /**
+     * Inspect pending without consuming. Filters expired entries.
+     */
+    peek(chatId: string): RejectPending | undefined;
+    clear(): void;
+}
+/**
+ * Helper: format the approve payload as engine input. Kept as a function
+ * (not a constant) so future variants — e.g. caching a planId reference —
+ * have a single place to extend.
+ */
+export declare function formatApprovePayload(planId: string): string;
+export {};

package/dist/src/channels/telegram-mirror/plan-attachment.js

@@ -0,0 +1,138 @@
+/**
+ * src/channels/telegram-mirror/plan-attachment.ts — v0.25.0 M9.
+ *
+ * When Claude emits ExitPlanMode (the plan-mode tool call), the mirror
+ * uploads the plan body as a .md document attachment with two inline
+ * buttons (Approve / Reject). Decision: ADR-006 — sendDocument over
+ * editMessageMedia. Rationale: sendDocument is simpler, has the larger
+ * size limit, and matches A1's on-disk plan-file convention.
+ *
+ * Approve → callback payload `{ action: 'plan-approve', planId }` resolves
+ * to model input "approved" which the engine bridge feeds to the running
+ * session.
+ *
+ * Reject → two-phase. The first tap stashes a pending-reject for the chat;
+ * the next non-slash inbound message becomes the rejection feedback payload
+ * "<plan rejected>\n<feedback text>". A tap-then-tap-Reject again clears
+ * the pending state silently.
+ *
+ * Risk references: R-3 (callback_data 64-byte cap) — payloads here route
+ * through CallbackMap exactly like M3's keyboard.
+ */
+/**
+ * Compose the slug-prefixed plan filename. Sanitises non-filename chars
+ * so the Telegram upload always succeeds.
+ */
+export function planFilename(slug) {
+    const safe = (slug ?? 'session').replace(/[^a-z0-9-_]/gi, '-').slice(0, 40);
+    // Fall back to "session" when the sanitised slug contains no alphanumeric
+    // characters (e.g. input was empty or all separators) — avoids surfacing
+    // an inscrutable "plan-----.md" filename to the user.
+    const effective = /[a-z0-9]/i.test(safe) ? safe : 'session';
+    return `plan-${effective}.md`;
+}
+/**
+ * Build a sendDocument action carrying the plan + the Approve/Reject
+ * inline keyboard. The callback ids are minted into the supplied
+ * CallbackMap; payloads include a fresh planId so multiple in-flight
+ * plans on the same chat don't collide.
+ */
+export function buildPlanAttachment(opts) {
+    const planId = opts.planId ?? `plan-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const filename = planFilename(opts.event.slug);
+    const approveCb = opts.callbackMap.create({ action: 'plan-approve', planId });
+    const rejectCb = opts.callbackMap.create({ action: 'plan-reject', planId });
+    const inline_keyboard = [
+        [
+            { text: '✅ Approve', callback_data: approveCb },
+            { text: '✖ Reject', callback_data: rejectCb },
+        ],
+    ];
+    return {
+        planId,
+        action: {
+            type: 'sendDocument',
+            chat_id: opts.chatId,
+            filename,
+            content: opts.event.plan,
+            caption: opts.event.caption ?? 'Plan ready — Approve or Reject below.',
+            reply_markup: { inline_keyboard },
+        },
+    };
+}
+/**
+ * Tracks the (chatId → pending-reject) state for two-phase rejection.
+ * The dispatch layer pokes startPending on a Reject tap and consumeFeedback
+ * on the next non-slash inbound. Pending-state TTL prevents a half-open
+ * rejection from corrupting later turns.
+ */
+export class RejectFeedbackTracker {
+    pending = new Map();
+    ttlMs;
+    now;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? 10 * 60_000;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Mark a chat as having tapped Reject and waiting for feedback. If a
+     * prior pending exists, it is replaced (the user re-tapped on a newer plan).
+     */
+    startPending(chatId, planId) {
+        this.pending.set(chatId, { chatId, planId, pendingSince: this.now() });
+    }
+    /**
+     * Returns true when the chat has a non-stale pending-reject.
+     */
+    isPending(chatId) {
+        return this.peek(chatId) !== undefined;
+    }
+    /**
+     * Consume the next inbound text as the rejection feedback. Returns a
+     * formatted payload that the engine bridge feeds to openai-compat as a
+     * single user-message, or undefined when no pending state exists.
+     *
+     * Payload shape: "<plan rejected: planId>\n<feedback text>" — the
+     * "<plan rejected>" sentinel lets the model recognise this as
+     * rejection feedback (not a new turn).
+     */
+    consumeFeedback(chatId, feedback) {
+        const p = this.peek(chatId);
+        if (!p)
+            return undefined;
+        this.pending.delete(chatId);
+        return `<plan rejected: ${p.planId}>\n${feedback}`;
+    }
+    /**
+     * Drop the pending state without consuming feedback (e.g. user taps
+     * Reject twice, or types another slash command in the interim).
+     */
+    cancel(chatId) {
+        return this.pending.delete(chatId);
+    }
+    /**
+     * Inspect pending without consuming. Filters expired entries.
+     */
+    peek(chatId) {
+        const p = this.pending.get(chatId);
+        if (!p)
+            return undefined;
+        if (this.now() - p.pendingSince > this.ttlMs) {
+            this.pending.delete(chatId);
+            return undefined;
+        }
+        return p;
+    }
+    clear() {
+        this.pending.clear();
+    }
+}
+/**
+ * Helper: format the approve payload as engine input. Kept as a function
+ * (not a constant) so future variants — e.g. caching a planId reference —
+ * have a single place to extend.
+ */
+export function formatApprovePayload(planId) {
+    return `<plan approved: ${planId}>`;
+}
+//# sourceMappingURL=plan-attachment.js.map

package/dist/src/channels/telegram-mirror/plan-attachment.js.map

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

package/dist/src/channels/telegram-mirror/quota-reader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * src/channels/telegram-mirror/quota-reader.ts — v0.25.0 M4 stub.
+ *
+ * Minimal QuotaSnapshot interface and a zero-valued reader so /cost in M4
+ * has something to render. M11 replaces the stub with a wire-up to the
+ * production status-tee-reader.ts that the existing /cost handler in the
+ * legacy live card already consumes.
+ *
+ * Decision-link: M11 owns threshold-notification + detail-view wiring;
+ * keeping the surface here in M4 isolates the command-handler layer from
+ * the status-tee read path (so M11 can swap implementations without
+ * touching commands.ts).
+ */
+export interface QuotaPerDay {
+    /** YYYY-MM-DD */
+    date: string;
+    /** 0..100 — percentage of the daily Max 20x window consumed. */
+    percent: number;
+}
+export interface QuotaSnapshot {
+    /** Current Max 20x consumption as 0..100 percent. */
+    maxPercent: number;
+    /** Weekly burn in USD (extra_usage overage tracked separately by status-tee). */
+    weeklyBurn: number;
+    /** Sessions ranked by token consumption (top-5). */
+    topSessions: Array<{
+        slug: string;
+        tokens: number;
+    }>;
+    /** Per-day rollup, most-recent-first (capped at 7). */
+    perDayRollup: QuotaPerDay[];
+}
+export interface QuotaReader {
+    read(): QuotaSnapshot;
+}
+/**
+ * Stub reader for M4 — returns a known-zero snapshot. M11 replaces this
+ * with a wire to status-tee-reader.ts. Tests can pass their own reader
+ * directly to the cost command for fixture-based assertions.
+ */
+export declare const stubQuotaReader: QuotaReader;

package/dist/src/channels/telegram-mirror/quota-reader.js

@@ -0,0 +1,29 @@
+/**
+ * src/channels/telegram-mirror/quota-reader.ts — v0.25.0 M4 stub.
+ *
+ * Minimal QuotaSnapshot interface and a zero-valued reader so /cost in M4
+ * has something to render. M11 replaces the stub with a wire-up to the
+ * production status-tee-reader.ts that the existing /cost handler in the
+ * legacy live card already consumes.
+ *
+ * Decision-link: M11 owns threshold-notification + detail-view wiring;
+ * keeping the surface here in M4 isolates the command-handler layer from
+ * the status-tee read path (so M11 can swap implementations without
+ * touching commands.ts).
+ */
+/**
+ * Stub reader for M4 — returns a known-zero snapshot. M11 replaces this
+ * with a wire to status-tee-reader.ts. Tests can pass their own reader
+ * directly to the cost command for fixture-based assertions.
+ */
+export const stubQuotaReader = {
+    read() {
+        return {
+            maxPercent: 0,
+            weeklyBurn: 0,
+            topSessions: [],
+            perDayRollup: [],
+        };
+    },
+};
+//# sourceMappingURL=quota-reader.js.map

package/dist/src/channels/telegram-mirror/quota-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-reader.js","sourceRoot":"","sources":["../../../../src/channels/telegram-mirror/quota-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC1C,IAAI;QACF,OAAO;YACL,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,EAAE;YACf,YAAY,EAAE,EAAE;SACjB,CAAC;IACJ,CAAC;CACF,CAAC"}