comisai 1.0.42 → 1.0.44

package/node_modules/@comis/channels/dist/slack/slack-reaction-binder.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Slack reaction-add binder (REACT-01, Verified Learning WS1).
+ *
+ * Co-located out of slack-adapter.ts (which keeps only the `reactionHandlers`
+ * array + the bind call + the `onReaction` registration). Registers
+ * `app.event("reaction_added")` and mints a NormalizedReaction from the Slack
+ * payload, filtering the bot's own-user reactions (mirror the own-user filter
+ * on the message binder at slack-adapter.ts:174).
+ *
+ * SHORT-NAME vs UNICODE: Slack delivers `event.reaction` as a short name
+ * (e.g. "thumbsup"), NOT the Unicode `👍` that the default `reactionMap` holds.
+ * The binder passes the RAW short name through unchanged — the daemon-side
+ * reactionMap match (Plan 04) owns reconciling Slack short names against the
+ * map (DECISION deferred to Plan 04 where the map lives). Do not normalize here.
+ *
+ * The reactorId is UNTRUSTED inbound; no trust is assigned here. Fanout is
+ * fire-and-forget so one throwing handler cannot crash the Bolt event loop.
+ *
+ * OPERATOR SETUP (DOC-01): Slack delivers nothing unless the app holds the
+ * `reactions:read` scope + a `reaction_added` event subscription (silent like
+ * Telegram's allowed_updates) — documented as operator setup, not a code gate.
+ *
+ * @module
+ */
+import type { ComisLogger, ReactionHandler } from "@comis/core";
+/**
+ * Minimal structural shape of the Slack `reaction_added` event payload —
+ * mirrors how {@link SlackMessageEvent} types the message binder (no `as any`).
+ * Only the fields the binder reads are declared.
+ */
+export interface SlackReactionAddedEvent {
+    /** The reacting user's Slack id (Uxxxx). */
+    user: string;
+    /** The reaction SHORT NAME (e.g. "thumbsup") — NOT Unicode (mapped at Plan 04). */
+    reaction: string;
+    /** The reacted-to item: a message identified by its ts + channel. */
+    item: {
+        ts: string;
+        channel: string;
+    };
+}
+/**
+ * Minimal structural shape of the @slack/bolt App surface the binder uses —
+ * just the `event(name, handler)` registration. The adapter passes its
+ * dynamically-imported `App` instance (typed `any` at the call site to keep
+ * `@slack/bolt` optional at module level).
+ */
+export interface SlackReactionApp {
+    event(name: "reaction_added", handler: (args: {
+        event: SlackReactionAddedEvent;
+    }) => Promise<void> | void): void;
+}
+/**
+ * Register the `reaction_added` listener on the Bolt `app`. Each non-own-user
+ * reaction mints a NormalizedReaction and is dispatched to every handler.
+ *
+ * @param app - the @slack/bolt App (post-start; `event()` is available)
+ * @param getOwnUserId - lazily resolves the bot's own user id (set post-auth in start())
+ * @param reactionHandlers - the live handler array the adapter pushes onReaction handlers onto
+ * @param logger - adapter logger for the non-fatal handler-failure WARN branch
+ */
+export declare function bindSlackReactions(app: SlackReactionApp, getOwnUserId: () => string, reactionHandlers: ReactionHandler[], logger: ComisLogger): void;

package/node_modules/@comis/channels/dist/slack/slack-reaction-binder.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Slack reaction-add binder (REACT-01, Verified Learning WS1).
+ *
+ * Co-located out of slack-adapter.ts (which keeps only the `reactionHandlers`
+ * array + the bind call + the `onReaction` registration). Registers
+ * `app.event("reaction_added")` and mints a NormalizedReaction from the Slack
+ * payload, filtering the bot's own-user reactions (mirror the own-user filter
+ * on the message binder at slack-adapter.ts:174).
+ *
+ * SHORT-NAME vs UNICODE: Slack delivers `event.reaction` as a short name
+ * (e.g. "thumbsup"), NOT the Unicode `👍` that the default `reactionMap` holds.
+ * The binder passes the RAW short name through unchanged — the daemon-side
+ * reactionMap match (Plan 04) owns reconciling Slack short names against the
+ * map (DECISION deferred to Plan 04 where the map lives). Do not normalize here.
+ *
+ * The reactorId is UNTRUSTED inbound; no trust is assigned here. Fanout is
+ * fire-and-forget so one throwing handler cannot crash the Bolt event loop.
+ *
+ * OPERATOR SETUP (DOC-01): Slack delivers nothing unless the app holds the
+ * `reactions:read` scope + a `reaction_added` event subscription (silent like
+ * Telegram's allowed_updates) — documented as operator setup, not a code gate.
+ *
+ * @module
+ */
+/** Log a non-fatal reaction-handler failure (sync throw or rejected promise). */
+function warnHandlerFailed(logger, handlerErr) {
+    logger.warn({
+        channelType: "slack",
+        errorKind: "platform",
+        err: handlerErr instanceof Error ? handlerErr : new Error(String(handlerErr)),
+        hint: "Slack reaction handler threw; reaction dropped (non-fatal)",
+    }, "Reaction handler failed");
+}
+/**
+ * Register the `reaction_added` listener on the Bolt `app`. Each non-own-user
+ * reaction mints a NormalizedReaction and is dispatched to every handler.
+ *
+ * @param app - the @slack/bolt App (post-start; `event()` is available)
+ * @param getOwnUserId - lazily resolves the bot's own user id (set post-auth in start())
+ * @param reactionHandlers - the live handler array the adapter pushes onReaction handlers onto
+ * @param logger - adapter logger for the non-fatal handler-failure WARN branch
+ */
+export function bindSlackReactions(app, getOwnUserId, reactionHandlers, logger) {
+    app.event("reaction_added", ({ event }) => {
+        // Own-user filter — never count the bot's own reactions.
+        if (event.user === getOwnUserId()) {
+            return;
+        }
+        const normalized = {
+            messageId: event.item.ts,
+            reactorId: event.user,
+            // RAW Slack short name — the daemon reactionMap match (Plan 04) reconciles it.
+            emoji: event.reaction,
+            channelType: "slack",
+            channelId: event.item.channel,
+        };
+        for (const handler of reactionHandlers) {
+            // try/catch in addition to .catch so a SYNCHRONOUS handler throw is also
+            // non-fatal (a sync throw escapes Promise.resolve()).
+            try {
+                void Promise.resolve(handler(normalized)).catch((handlerErr) => warnHandlerFailed(logger, handlerErr));
+            }
+            catch (handlerErr) {
+                warnHandlerFailed(logger, handlerErr);
+            }
+        }
+    });
+}

package/node_modules/@comis/channels/dist/telegram/emoji-fallback.js

@@ -34,8 +34,17 @@ export const TELEGRAM_SAFE_EMOJI = [
  * @returns Result from the successful reaction or the last error
  */
 export async function reactWithFallback(adapter, channelId, messageId, primaryEmoji) {
+    // ChannelPort.reactToMessage is optional, but this helper
+    // is wired only for telegram (real impl) by the lifecycle reactor. Surface a
+    // loud error if a caller bypasses the capability gate to avoid a silent miss.
+    // @allow-throw: Construction-time invariant — capability-gate bypass is a
+    // composition-root bug that must surface loudly; not a runtime Result.err path.
+    if (typeof adapter.reactToMessage !== "function") {
+        throw new Error(`reactWithFallback: adapter "${adapter.channelType}" lacks reactToMessage — capability gate (features.reactions) must be enforced before this call`);
+    }
+    const react = adapter.reactToMessage.bind(adapter);
     // Try primary emoji first
-    const primaryResult = await adapter.reactToMessage(channelId, messageId, primaryEmoji);
+    const primaryResult = await react(channelId, messageId, primaryEmoji);
     if (primaryResult.ok)
         return primaryResult;
     // Check if error is a REACTION_INVALID type
@@ -51,7 +60,7 @@ export async function reactWithFallback(adapter, channelId, messageId, primaryEm
         // Skip if same as the primary that just failed
         if (safeEmoji === primaryEmoji)
             continue;
-        lastResult = await adapter.reactToMessage(channelId, messageId, safeEmoji);
+        lastResult = await react(channelId, messageId, safeEmoji);
         if (lastResult.ok)
             return lastResult;
     }

package/node_modules/@comis/channels/dist/telegram/rich-renderer.d.ts

@@ -9,13 +9,34 @@
  * @module
  */
 import type { RichButton, RichCard } from "@comis/core";
+import { type Result } from "@comis/shared";
 import { InlineKeyboard } from "grammy";
+/** Telegram callback_data byte limit. */
+declare const MAX_CALLBACK_DATA_BYTES = 64;
+/** Over-budget callback_data: refuse loud rather than truncate (the signature would corrupt). */
+export type CallbackDataBudgetError = {
+    kind: "callback_data_overflow";
+    bytes: number;
+    maxBytes: typeof MAX_CALLBACK_DATA_BYTES;
+};
+/**
+ * Validate that callback_data fits Telegram's 64-byte budget without mutating it.
+ *
+ * Signed callback payloads carry an HMAC; truncating one corrupts the signature
+ * and silently breaks verification. The worst-case signed payload is ~40 bytes
+ * (well under the budget), so this is defense-in-depth: it refuses loud (`err`)
+ * on the never-expected overflow instead of cutting bytes. Byte length is the
+ * UTF-8 encoded length, not the character count.
+ */
+export declare function validateCallbackDataWithinBudget(data: string): Result<string, CallbackDataBudgetError>;
 /**
  * Convert domain RichButton rows to a Grammy InlineKeyboard.
  *
  * Each inner array becomes one keyboard row. URL buttons use .url(),
- * callback buttons use .text(). Callback data is truncated to 64 bytes
- * per Telegram's limit.
+ * callback buttons use .text(). Callback data is validated against Telegram's
+ * 64-byte limit and an over-budget callback button is omitted rather than
+ * truncated -- truncating would corrupt a signed payload's HMAC. The worst-case
+ * signed payload is ~40 bytes, so this guard never fires in practice.
  *
  * @param buttons - Two-dimensional array of RichButton (rows x buttons)
  * @returns InlineKeyboard instance ready for Telegram reply_markup
@@ -31,3 +52,4 @@ export declare function renderTelegramButtons(buttons: RichButton[][]): InlineKe
  * @returns HTML string suitable for Telegram parse_mode: "HTML"
  */
 export declare function renderTelegramCards(cards: RichCard[]): string;
+export {};

package/node_modules/@comis/channels/dist/telegram/rich-renderer.js

@@ -9,20 +9,25 @@
  *
  * @module
  */
+import { err, ok } from "@comis/shared";
 import { InlineKeyboard } from "grammy";
 /** Telegram callback_data byte limit. */
 const MAX_CALLBACK_DATA_BYTES = 64;
 /**
- * Truncate callback data to fit within Telegram's 64-byte limit.
+ * Validate that callback_data fits Telegram's 64-byte budget without mutating it.
+ *
+ * Signed callback payloads carry an HMAC; truncating one corrupts the signature
+ * and silently breaks verification. The worst-case signed payload is ~40 bytes
+ * (well under the budget), so this is defense-in-depth: it refuses loud (`err`)
+ * on the never-expected overflow instead of cutting bytes. Byte length is the
+ * UTF-8 encoded length, not the character count.
  */
-function truncateCallbackData(data) {
-    const encoder = new TextEncoder();
-    const bytes = encoder.encode(data);
-    if (bytes.length <= MAX_CALLBACK_DATA_BYTES)
-        return data;
-    // Truncate bytes and decode back -- TextDecoder handles partial chars
-    const truncated = bytes.slice(0, MAX_CALLBACK_DATA_BYTES);
-    return new TextDecoder("utf-8", { fatal: false }).decode(truncated);
+export function validateCallbackDataWithinBudget(data) {
+    const bytes = new TextEncoder().encode(data).length;
+    if (bytes > MAX_CALLBACK_DATA_BYTES) {
+        return err({ kind: "callback_data_overflow", bytes, maxBytes: MAX_CALLBACK_DATA_BYTES });
+    }
+    return ok(data);
 }
 /**
  * Escape HTML special characters for Telegram HTML parse mode.
@@ -37,8 +42,10 @@ function escapeHtml(text) {
  * Convert domain RichButton rows to a Grammy InlineKeyboard.
  *
  * Each inner array becomes one keyboard row. URL buttons use .url(),
- * callback buttons use .text(). Callback data is truncated to 64 bytes
- * per Telegram's limit.
+ * callback buttons use .text(). Callback data is validated against Telegram's
+ * 64-byte limit and an over-budget callback button is omitted rather than
+ * truncated -- truncating would corrupt a signed payload's HMAC. The worst-case
+ * signed payload is ~40 bytes, so this guard never fires in practice.
  *
  * @param buttons - Two-dimensional array of RichButton (rows x buttons)
  * @returns InlineKeyboard instance ready for Telegram reply_markup
@@ -52,8 +59,12 @@ export function renderTelegramButtons(buttons) {
                 keyboard.url(btn.text, btn.url);
             }
             else {
-                const data = truncateCallbackData(btn.callback_data ?? btn.text);
-                keyboard.text(btn.text, data);
+                const budget = validateCallbackDataWithinBudget(btn.callback_data ?? btn.text);
+                // Defensive: skip an over-budget callback button rather than truncate
+                // (truncation corrupts a signed callback's HMAC). Real payloads always fit.
+                if (!budget.ok)
+                    continue;
+                keyboard.text(btn.text, budget.value);
             }
         }
         // Add row break after each row (except the last)

package/node_modules/@comis/channels/dist/telegram/telegram-activity.d.ts

@@ -0,0 +1,39 @@
+import type { ChannelActivityRenderer, ActivityRenderError, ChannelPort, TimerPort, ClockPort, ActivityStatusMarkers } from "@comis/core";
+import type { ActivityRenderActions } from "../shared/strategies/actions.js";
+import { type SignCallbackData } from "../shared/strategies/approval-render.js";
+/**
+ * Classify a raw Telegram platform error into the closed {@link ActivityRenderError}
+ * union by its STRUCTURAL fields. Reads `error_code`/`parameters` off the error
+ * itself and, when the live adapter wrapped the `GrammyError` in
+ * `new Error(msg, { cause })`, off `error.cause`. The `description` is consulted
+ * ONLY to pick the message-not-found variant — never rendered or logged.
+ */
+export declare function classifyTelegramError(e: unknown): ActivityRenderError;
+/** Optional timer used by the local 429 retry buffer. Omit it and a 429 simply propagates. */
+export interface TelegramRenderActionsDeps {
+    timer?: TimerPort;
+}
+/**
+ * Build the {@link ActivityRenderActions} for a Telegram chat. `send` carries the
+ * silent effect; `edit`/`delete` guard the optional port methods and classify
+ * platform errors structurally. When a `timer` is supplied, a `rate_limited`
+ * edit schedules a single bounded retry of the LATEST text.
+ */
+export declare function makeTelegramRenderActions(adapter: ChannelPort, channelId: string, deps?: TelegramRenderActionsDeps): ActivityRenderActions;
+/**
+ * Create the Telegram EditPlace activity renderer — wires the
+ * {@link createEditPlaceRenderer} with the per-channel render-actions adapter.
+ * The daemon composition root constructs this with its runtime `TimerPort` /
+ * `ClockPort` and the chat id.
+ *
+ * `signCallbackData` is the secret-bound signer injected at the composition root:
+ * the renderer CONSUMES it to build the signed inline keyboard and never
+ * imports the orchestrator package (Pitfall 5). When omitted, an
+ * approval frame degrades to a button-less text prompt.
+ */
+export declare function createTelegramActivityRenderer(adapter: ChannelPort, channelId: string, deps: {
+    timer: TimerPort;
+    clock: ClockPort;
+    signCallbackData?: SignCallbackData;
+    markers?: ActivityStatusMarkers;
+}): ChannelActivityRenderer;

package/node_modules/@comis/channels/dist/telegram/telegram-activity.js

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Telegram EditPlace activity renderer (§7.2 / §18.2 row "EditPlace").
+ *
+ * This is the canonical reference the other 3 EditPlace channels (Discord,
+ * Slack, WhatsApp) copy. It has three parts:
+ *
+ *   1. `classifyTelegramError` — the single net-new piece of logic here.
+ *      It reads STRUCTURAL `GrammyError` fields (`error_code`,
+ *      `parameters.retry_after`, and `description` ONLY to disambiguate the
+ *      message-not-found case) to choose one of the closed `ActivityRenderError`
+ *      variants. It NEVER parses the generic "Failed to…" string the live
+ *      adapter wraps the error in (D-Q1) — the adapter attaches the original
+ *      GrammyError as `error.cause`, which the classifier reads structurally.
+ *      §19.3: the `description` selects the variant only; it is never
+ *      rendered or logged as activity text.
+ *
+ *   2. `makeTelegramRenderActions` — the `ActivityRenderActions` adapter. `send`
+ *      passes `{effects:["silent"]}` so the existing outbound path sets
+ *      `disable_notification:true` (no new adapter code). `edit`/`delete` GUARD
+ *      the OPTIONAL `ChannelPort` methods (early `not_supported` — never a
+ *      non-null-asserted call, AGENTS.md §2.8) and map every
+ *      `.error` through `classifyTelegramError`. All paths return `Result`;
+ *      nothing throws across the boundary.
+ *
+ *   3. `createTelegramActivityRenderer` — wires the
+ *      `createEditPlaceRenderer` (the debounce/edit/delete state machine). It
+ *      does NOT re-implement any rendering logic.
+ *
+ * 429 backoff: the channels package depends on `core` and
+ * `shared` only — no observability substrate — so a shared bounded-queue helper
+ * is unreachable here. The 429 buffer is a LOCAL fixed-cap latest-text slot with
+ * a `retryAfterMs`-gated retry through the injected `TimerPort` (the retry handle
+ * is `unref`'d and `cancel()`-able — never a raw timer clear). It coalesces to the
+ * latest text and never grows unbounded. A `not_supported` (message-not-found)
+ * edit drops all further edits.
+ */
+import { ok, err } from "@comis/shared";
+import { createEditPlaceRenderer } from "../shared/strategies/edit-place.js";
+import { buildApprovalButtons, } from "../shared/strategies/approval-render.js";
+import { validateCallbackDataWithinBudget } from "./rich-renderer.js";
+/** Telegram "this message can no longer be edited" descriptions (400 family). */
+const MESSAGE_NOT_EDITABLE = /message (to edit )?not found|message can.?t be edited/i;
+/**
+ * Classify a raw Telegram platform error into the closed {@link ActivityRenderError}
+ * union by its STRUCTURAL fields. Reads `error_code`/`parameters` off the error
+ * itself and, when the live adapter wrapped the `GrammyError` in
+ * `new Error(msg, { cause })`, off `error.cause`. The `description` is consulted
+ * ONLY to pick the message-not-found variant — never rendered or logged.
+ */
+export function classifyTelegramError(e) {
+    const direct = (e ?? {});
+    // Prefer the typed GrammyError the adapter attached as `cause`; fall back to
+    // the error object itself (the fake injects the GrammyError shape directly).
+    const ge = direct.error_code === undefined && direct.cause != null
+        ? (direct.cause ?? direct)
+        : direct;
+    if (ge.error_code === 429) {
+        return { kind: "rate_limited", retryAfterMs: (ge.parameters?.retry_after ?? 1) * 1000 };
+    }
+    if (ge.error_code === 400 && MESSAGE_NOT_EDITABLE.test(ge.description ?? "")) {
+        return { kind: "not_supported", capability: "edit" };
+    }
+    if (ge.error_code === 403) {
+        return { kind: "permission", detail: ge.description ?? "forbidden" };
+    }
+    return { kind: "internal", cause: e };
+}
+/** Latest-text retry cap — a 429 storm coalesces to the latest text; we never replay a backlog. */
+const MAX_RETRY_ATTEMPTS = 4;
+/**
+ * Build the {@link ActivityRenderActions} for a Telegram chat. `send` carries the
+ * silent effect; `edit`/`delete` guard the optional port methods and classify
+ * platform errors structurally. When a `timer` is supplied, a `rate_limited`
+ * edit schedules a single bounded retry of the LATEST text.
+ */
+export function makeTelegramRenderActions(adapter, channelId, deps = {}) {
+    const { timer } = deps;
+    // --- Local bounded 429 buffer (single latest-text slot + single retry) ---
+    /** The latest text awaiting a rate-limit retry (latest-wins; bounded to one slot). */
+    let pendingText;
+    /** The id of the message being edited under backoff. */
+    let pendingId;
+    /** The single in-flight retry timer; cancelled + rescheduled via handle.cancel(). */
+    let retryHandle;
+    /** Consecutive retry attempts; caps the backoff so a sustained 429 cannot loop forever. */
+    let retryAttempts = 0;
+    /** Set once a message-not-found is seen — all further edits are dropped (§drop-on-not_supported). */
+    let editsDropped = false;
+    function cancelRetry() {
+        if (retryHandle && !retryHandle.cancelled)
+            retryHandle.cancel();
+        retryHandle = undefined;
+    }
+    // Perform one edit attempt, applying the 429 buffer + drop-on-not_supported policy.
+    async function attemptEdit(id, text) {
+        if (editsDropped)
+            return err({ kind: "not_supported", capability: "edit" });
+        if (!adapter.editMessage)
+            return err({ kind: "not_supported", capability: "edit" });
+        const r = await adapter.editMessage(channelId, id, text);
+        if (r.ok) {
+            // Success: any pending backoff is satisfied by the latest send.
+            cancelRetry();
+            pendingText = undefined;
+            retryAttempts = 0;
+            return ok(undefined);
+        }
+        const classified = classifyTelegramError(r.error);
+        if (classified.kind === "not_supported") {
+            // Message can no longer be edited → stop editing entirely.
+            editsDropped = true;
+            cancelRetry();
+            pendingText = undefined;
+            return err(classified);
+        }
+        if (classified.kind === "rate_limited" && timer !== undefined) {
+            // Coalesce to the latest text in the single slot and schedule ONE retry.
+            // Pass the narrowed timer so scheduleRetry needs no undefined guard.
+            pendingText = text;
+            pendingId = id;
+            scheduleRetry(timer, classified.retryAfterMs);
+        }
+        return err(classified);
+    }
+    function scheduleRetry(t, retryAfterMs) {
+        if (retryAttempts >= MAX_RETRY_ATTEMPTS) {
+            // Bounded: give up replaying after the cap; the buffer never grows.
+            cancelRetry();
+            pendingText = undefined;
+            return;
+        }
+        cancelRetry();
+        retryAttempts += 1;
+        retryHandle = t.setTimeout(() => {
+            const text = pendingText;
+            const id = pendingId;
+            retryHandle = undefined;
+            // Defensive: a delete/success between scheduling and firing clears the slot.
+            if (text === undefined || id === undefined || editsDropped)
+                return;
+            void attemptEdit(id, text);
+        }, retryAfterMs);
+        // Never hold the event loop open for a retry at shutdown.
+        retryHandle.unref();
+    }
+    return {
+        async send(text, opts) {
+            // An approval placeholder carries the signed inline-keyboard buttons
+            // (callback_data = v1.<choice>.<shortId>.<hmac>); the adapter maps them via
+            // renderTelegramButtons. The silent effect is preserved. Resolution is
+            // owned by the InteractiveCallbackRouter, not this renderer.
+            const r = await adapter.sendMessage(channelId, text, {
+                effects: ["silent"],
+                ...(opts?.buttons !== undefined ? { buttons: opts.buttons } : {}),
+            });
+            return r.ok ? ok(r.value) : err(classifyTelegramError(r.error));
+        },
+        async edit(id, text) {
+            return attemptEdit(id, text);
+        },
+        async delete(id) {
+            // A delete supersedes any pending edit retry.
+            cancelRetry();
+            pendingText = undefined;
+            if (!adapter.deleteMessage)
+                return err({ kind: "not_supported", capability: "delete" });
+            const r = await adapter.deleteMessage(channelId, id);
+            return r.ok ? ok(undefined) : err(classifyTelegramError(r.error));
+        },
+    };
+}
+/**
+ * Drop any over-budget callback button BEFORE it reaches the adapter.
+ *
+ * `renderTelegramButtons` is the adapter-side budget guard, but filtering
+ * here keeps the renderer's emitted rows honest: a >64-byte `callback_data` is
+ * OMITTED (refuse-loud), never truncated — truncation would corrupt the signed
+ * HMAC. The worst-case real signed payload is ~40 bytes, so this never fires in
+ * practice; it is defense-in-depth.
+ */
+function omitOverBudgetButtons(rows) {
+    return rows.map((row) => row.filter((btn) => {
+        if (btn.callback_data === undefined)
+            return true;
+        return validateCallbackDataWithinBudget(btn.callback_data).ok;
+    }));
+}
+/**
+ * Create the Telegram EditPlace activity renderer — wires the
+ * {@link createEditPlaceRenderer} with the per-channel render-actions adapter.
+ * The daemon composition root constructs this with its runtime `TimerPort` /
+ * `ClockPort` and the chat id.
+ *
+ * `signCallbackData` is the secret-bound signer injected at the composition root:
+ * the renderer CONSUMES it to build the signed inline keyboard and never
+ * imports the orchestrator package (Pitfall 5). When omitted, an
+ * approval frame degrades to a button-less text prompt.
+ */
+export function createTelegramActivityRenderer(adapter, channelId, deps) {
+    const { signCallbackData } = deps;
+    return createEditPlaceRenderer({
+        actions: makeTelegramRenderActions(adapter, channelId, { timer: deps.timer }),
+        timer: deps.timer,
+        clock: deps.clock,
+        markers: deps.markers,
+        // Approval frame → signed inline-keyboard rows (rendered to a grammY
+        // InlineKeyboard by renderTelegramButtons in the adapter). Over-budget
+        // buttons are omitted here too (never truncated).
+        buildButtons: signCallbackData === undefined
+            ? undefined
+            : (events) => omitOverBudgetButtons(events.flatMap((event) => buildApprovalButtons(event, signCallbackData))),
+    });
+}

package/node_modules/@comis/channels/dist/telegram/telegram-adapter/index.js

@@ -22,8 +22,8 @@ import { autoRetry } from "@grammyjs/auto-retry";
 import { hydrateFiles } from "@grammyjs/files";
 import { Bot } from "grammy";
 import { getStatusReport, startLifecycle, stopLifecycle, } from "./telegram-lifecycle.js";
-import { registerMessageHandler } from "./telegram-inbound.js";
-import { deleteMessage, editMessage, fetchMessages, platformAction, reactToMessage, removeReaction, sendAttachment, sendMessage, } from "./telegram-outbound.js";
+import { registerMessageHandler, registerReactionHandler } from "./telegram-inbound.js";
+import { deleteMessage, editMessage, platformAction, reactToMessage, removeReaction, sendAttachment, sendMessage, } from "./telegram-outbound.js";
 /**
  * Create a Telegram adapter implementing the ChannelPort interface.
  *
@@ -33,9 +33,8 @@ import { deleteMessage, editMessage, fetchMessages, platformAction, reactToMessa
 export function createTelegramAdapter(deps) {
     // E2E seam: if deps.apiRoot is set, point grammy at that URL instead of
     // api.telegram.org. Production callers leave it unset and grammy uses its
-    // default (https://api.telegram.org). Per AGENTS.md §2.3, the `client`
-    // option is included ONLY when redirected: keeps the production code path
-    // byte-identical to before.
+    // default (https://api.telegram.org). The `client` option is included ONLY
+    // when redirected: keeps the production code path byte-identical to before.
     const bot = deps.apiRoot
         ? new Bot(deps.botToken, { client: { apiRoot: deps.apiRoot } })
         : new Bot(deps.botToken);
@@ -46,6 +45,7 @@ export function createTelegramAdapter(deps) {
     const state = {
         bot,
         handlers: [],
+        reactionHandlers: [],
         channelId: "telegram-pending",
         runnerHandle: null,
         botIdentity: undefined,
@@ -68,12 +68,14 @@ export function createTelegramAdapter(deps) {
         reactToMessage: (chatId, messageId, emoji) => reactToMessage(state, deps, chatId, messageId, emoji),
         removeReaction: (chatId, messageId, emoji) => removeReaction(state, deps, chatId, messageId, emoji),
         deleteMessage: (chatId, messageId) => deleteMessage(state, deps, chatId, messageId),
-        fetchMessages: (channelId, options) => fetchMessages(state, deps, channelId, options),
         sendAttachment: (chatId, attachment, options) => sendAttachment(state, deps, chatId, attachment, options),
         platformAction: (action, params) => platformAction(state, deps, action, params),
         onMessage(handler) {
             registerMessageHandler(state, handler);
         },
+        onReaction(handler) {
+            registerReactionHandler(state, handler);
+        },
         getStatus: () => getStatusReport(state),
         bot, // Expose Grammy Bot instance for resolver creation
     };

package/node_modules/@comis/channels/dist/telegram/telegram-adapter/telegram-adapter-types.d.ts

@@ -12,7 +12,7 @@
  *
  * @module
  */
-import type { ChannelPort, ComisLogger, MessageHandler } from "@comis/core";
+import type { ChannelPort, ComisLogger, MessageHandler, ReactionHandler } from "@comis/core";
 import type { run } from "@grammyjs/runner";
 import type { Bot } from "grammy";
 import type { TelegramBotIdentity } from "../message-mapper.js";
@@ -59,6 +59,8 @@ export interface TelegramAdapterState {
     bot: Bot;
     /** Message handlers registered via handle.onMessage(). */
     handlers: MessageHandler[];
+    /** Reaction handlers registered via handle.onReaction() (REACT-01, WS1). */
+    reactionHandlers: ReactionHandler[];
     /** "telegram-pending" before start(); "telegram-{botId}" after start() succeeds. */
     channelId: string;
     /** grammy/runner handle returned by run(bot); null in webhook mode and before start(). */

package/node_modules/@comis/channels/dist/telegram/telegram-adapter/telegram-inbound.d.ts

@@ -33,3 +33,5 @@ export declare function handleInboundMessage(state: TelegramAdapterState, deps:
 export declare function bindInboundHandlers(state: TelegramAdapterState, deps: TelegramAdapterDeps): void;
 /** Append a MessageHandler to the adapter's dispatch list. */
 export declare function registerMessageHandler(state: TelegramAdapterState, handler: import("@comis/core").MessageHandler): void;
+/** Append a ReactionHandler to the adapter's reaction dispatch list (REACT-01). */
+export declare function registerReactionHandler(state: TelegramAdapterState, handler: import("@comis/core").ReactionHandler): void;