switchroom 0.19.40 → 0.19.42

package/telegram-plugin/dist/server.js

@@ -25007,7 +25007,7 @@ var init_bridge = __esm(async () => {
     },
     {
       name: "send_checklist",
-      description: 'Send a native Telegram checklist (interactive task list) to a chat. Users can tick tasks directly in the Telegram app. Returns the message_id of the created checklist. The bot is notified when tasks are ticked \u2014 these arrive as channel events with kind="checklist_task_changed". Limit: 30 tasks per checklist.',
+      description: 'Send a checklist (task list) to a chat. Native interactive Telegram checklists require a Business-account connection, which most deployments do not have \u2014 in that normal case the checklist is sent as a formatted TEXT message (bold title + \u2705/\u2b1c task lines) and the result carries degraded:"text": tasks are NOT tappable, and you tick them yourself via update_checklist (task ids are 1..N in send order). With a Business connection configured, the checklist is sent natively and tick events arrive as channel events with kind="checklist_task_changed". Returns JSON with message_id and mode. Limit: 30 tasks.',
       inputSchema: {
         type: "object",
         properties: {
@@ -25092,7 +25092,7 @@ var init_bridge = __esm(async () => {
     },
     {
       name: "update_checklist",
-      description: "Patch an existing native Telegram checklist. Supports updating the title, adding new tasks, removing tasks, or marking tasks done/undone. Tasks with an id target existing items; tasks without an id are appended. Preserves existing task ids across edits.",
+      description: `Patch a checklist previously sent with send_checklist: update the title, append tasks, or mark tasks done/undone. Tasks with an id target existing items (ids are 1..N in send order for text-mode checklists); tasks without an id are appended. Removal is not supported. The edit re-renders in the mode the checklist was sent in (text for most deployments). Returns JSON { ok, ... }; after a gateway restart the stored task state may be gone \u2014 then it returns ok:false with reason "unknown_checklist" unless you pass a full replacement (title + every task's text).`,
       inputSchema: {
         type: "object",
         properties: {

package/telegram-plugin/gateway/approval-callback-consume-record.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Regression test for #4069 — the "kernel record failed" false toast.
+ *
+ * The kernel's approval_consume_record reply carries `decision_id`, but
+ * the client decodes every reply through ResponseSchema (a plain
+ * z.union, first-match wins, unknown keys stripped). With
+ * OkApprovalConsumeResponseSchema ordered before
+ * OkApprovalConsumeRecordResponseSchema, the consume_record reply
+ * matched the prefix schema and `decision_id` was silently stripped —
+ * so handleApprovalCallback hit its defensive `!result.decision_id`
+ * branch, toasted "kernel record failed", and returned before editing
+ * the card to its granted state. Deterministic on EVERY `apv:` approval
+ * tap. The audit row was never lost — the kernel committed it — this
+ * was purely the client's mangled view of the reply.
+ *
+ * This test drives handleApprovalCallback end-to-end against a fake
+ * kernel serving a REAL wire frame through the REAL
+ * rpcRaw/decodeResponse path (the kernel suites parse the wire with raw
+ * JSON.parse and bypass decodeResponse — which is exactly why they
+ * missed this). It asserts the tap lands: no "kernel record failed"
+ * toast, and the card advances to its granted body carrying the
+ * decision_id revoke hint.
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Context } from "grammy";
+import { handleApprovalCallback } from "./approval-callback.js";
+
+const REQUEST_ID = "0123456789abcdef0123456789abcdef";
+const DECISION_ID = "dec-4069";
+
+/** One-shot fake kernel: replies to the first request line with `reply`. */
+function startFakeKernel(
+  socketPath: string,
+  reply: Record<string, unknown>,
+  seen: string[],
+): Promise<net.Server> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer((conn) => {
+      let buf = "";
+      conn.on("data", (chunk) => {
+        buf += chunk.toString("utf8");
+        const idx = buf.indexOf("\n");
+        if (idx === -1) return;
+        seen.push(buf.slice(0, idx));
+        conn.write(JSON.stringify(reply) + "\n");
+      });
+    });
+    server.on("error", reject);
+    server.listen(socketPath, () => resolve(server));
+  });
+}
+
+function makeFakeCtx(): {
+  ctx: Context;
+  toasts: string[];
+  edits: Array<{ markdown: string }>;
+} {
+  const toasts: string[] = [];
+  const edits: Array<{ markdown: string }> = [];
+  const ctx = {
+    from: { id: 42 },
+    answerCallbackQuery: async (args?: { text?: string }) => {
+      toasts.push(args?.text ?? "");
+      return true;
+    },
+    editMessageText: async (body: { markdown: string }) => {
+      edits.push(body);
+      return true;
+    },
+  } as unknown as Context;
+  return { ctx, toasts, edits };
+}
+
+describe("handleApprovalCallback × real decodeResponse (#4069)", () => {
+  let server: net.Server | undefined;
+  let tmpDir: string | undefined;
+  const savedEnv = process.env.SWITCHROOM_KERNEL_SOCKET;
+
+  afterEach(async () => {
+    if (server) await new Promise((r) => server!.close(r));
+    server = undefined;
+    if (savedEnv === undefined) delete process.env.SWITCHROOM_KERNEL_SOCKET;
+    else process.env.SWITCHROOM_KERNEL_SOCKET = savedEnv;
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it("approve tap records + advances the card — no false 'kernel record failed'", async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sr4069-"));
+    const socketPath = path.join(tmpDir, "kernel.sock");
+    const seen: string[] = [];
+    server = await startFakeKernel(
+      socketPath,
+      {
+        ok: true,
+        consumed: true,
+        decision_id: DECISION_ID,
+        agent_unit: "clerk",
+        scope: "doc:gdrive:D1",
+        action: "write",
+        why: null,
+      },
+      seen,
+    );
+    process.env.SWITCHROOM_KERNEL_SOCKET = socketPath;
+
+    const { ctx, toasts, edits } = makeFakeCtx();
+    await handleApprovalCallback(ctx, `apv:${REQUEST_ID}:once`);
+
+    // The fake kernel really received the atomic consume+record op.
+    expect(seen.length).toBe(1);
+    expect(JSON.parse(seen[0]!)).toMatchObject({
+      op: "approval_consume_record",
+      request_id: REQUEST_ID,
+      decision: "allow_once",
+    });
+
+    // Outcome: the tap must land as Approved, never the false-failure
+    // toast, and the card must advance to its granted body carrying the
+    // decision_id revoke hint.
+    expect(toasts).not.toContain("kernel record failed");
+    expect(toasts).toContain("Approved");
+    expect(edits.length).toBe(1);
+    expect(edits[0]!.markdown).toContain(DECISION_ID);
+    expect(edits[0]!.markdown).toContain("granted once");
+  });
+});

package/telegram-plugin/gateway/checklist-fallback.ts

@@ -0,0 +1,370 @@
+/**
+ * Checklist send/update with graceful degradation.
+ *
+ * Telegram's native `sendChecklist` / `editMessageChecklist` (Bot API 9.1)
+ * are **Business-account-only**: both REQUIRE a `business_connection_id`,
+ * and the payload nests `title`/`tasks` inside a single `checklist` object
+ * (`InputChecklist`) whose tasks each carry a REQUIRED integer `id` and NO
+ * completion flag (`InputChecklistTask = { id, text }` — a native checklist
+ * cannot be pre-marked done). The original wrapper sent a FLAT
+ * `{ chat_id, title, tasks: [{ text, is_completed? }] }` payload, which
+ * Telegram rejected with `400: parameter "checklist" is required` — and even
+ * a well-formed payload fails for ordinary bot DMs/groups (no business
+ * connection), which is every chat this fleet uses.
+ *
+ * So the tool degrades gracefully instead of surfacing a raw 400:
+ *   1. If a business connection id is configured AND the Bot API supports
+ *      checklists → build the CORRECT native payload and send natively.
+ *   2. Otherwise (the normal case) → render the checklist as a formatted
+ *      text message (bold title + ✅/⬜ task lines — text CAN show the
+ *      `done` flag) and send via the normal message path. The tool result
+ *      carries `degraded: "text"` so the caller knows it is not interactive.
+ *   3. A failed native attempt falls back to text rather than erroring.
+ *
+ * Updates work against a per-message in-memory state store (the gateway has
+ * no other record of a text-rendered checklist's tasks): a patch is applied
+ * to the stored state and the message is edited (natively or as text to
+ * match how it was sent). State is process-local — after a gateway restart
+ * an update to a pre-restart checklist returns a graceful
+ * `unknown_checklist` result unless the patch itself carries a full
+ * replacement (title + all task texts), never a raw Telegram error.
+ *
+ * Pure/deps-injected so the orchestration is unit-testable without a bot
+ * (same pattern as checklist-message-handler.ts).
+ */
+
+export interface ChecklistTaskState {
+  /** 1-based sequential id assigned at send time (mirrors the native API's
+   *  required per-task integer id; doubles as the patch handle in text mode). */
+  id: number
+  text: string
+  done: boolean
+}
+
+export interface ChecklistState {
+  title: string
+  tasks: ChecklistTaskState[]
+  /** How the message was actually delivered — updates must match it. */
+  mode: 'native' | 'text'
+}
+
+export interface ChecklistPatchTask {
+  id?: string | number
+  text?: string
+  done?: boolean
+}
+
+export interface ChecklistPatch {
+  title?: string
+  tasks?: ChecklistPatchTask[]
+}
+
+export const CHECKLIST_MAX_TASKS = 30
+
+/** Assign sequential 1-based ids and normalize the `done` flag. */
+export function buildChecklistTasks(
+  tasks: ReadonlyArray<{ text: string; done?: boolean }>,
+): ChecklistTaskState[] {
+  if (tasks.length > CHECKLIST_MAX_TASKS) {
+    throw new Error(`checklist exceeds ${CHECKLIST_MAX_TASKS}-task limit (got ${tasks.length})`)
+  }
+  return tasks.map((t, i) => ({ id: i + 1, text: t.text, done: t.done === true }))
+}
+
+/**
+ * Render a checklist as a text message: title header + one ✅/⬜ line per
+ * task. Rich (default) output is GFM markdown for `richMessage()`; pass
+ * `literal: true` when the access config pins `parseMode: 'text'` (plain
+ * sends, no markdown parsing) so the title doesn't ship raw asterisks.
+ */
+export function renderChecklistText(
+  cl: { title: string; tasks: ReadonlyArray<{ text: string; done: boolean }> },
+  opts?: { literal?: boolean },
+): string {
+  const header = opts?.literal ? cl.title : `**${cl.title}**`
+  const lines = cl.tasks.map((t) => `${t.done ? '✅' : '⬜'} ${t.text}`)
+  return [header, ...lines].join('\n')
+}
+
+/**
+ * Apply an update_checklist patch: `title` replaces the title; a task with
+ * an `id` matching an existing task updates its text/done in place; a task
+ * without an `id` (or with an unknown id) is appended. Returns a NEW state
+ * (input untouched). Removal is not supported by the patch shape.
+ */
+export function applyChecklistPatch(
+  cl: { title: string; tasks: ReadonlyArray<ChecklistTaskState> },
+  patch: ChecklistPatch,
+): { title: string; tasks: ChecklistTaskState[] } {
+  const tasks = cl.tasks.map((t) => ({ ...t }))
+  for (const p of patch.tasks ?? []) {
+    const pid = p.id != null ? Number(p.id) : undefined
+    const existing = pid != null ? tasks.find((t) => t.id === pid) : undefined
+    if (existing) {
+      if (p.text != null) existing.text = p.text
+      if (p.done != null) existing.done = p.done
+    } else {
+      const nextId = pid != null && Number.isFinite(pid)
+        ? pid
+        : tasks.reduce((m, t) => Math.max(m, t.id), 0) + 1
+      tasks.push({ id: nextId, text: p.text ?? '', done: p.done === true })
+    }
+  }
+  if (tasks.length > CHECKLIST_MAX_TASKS) {
+    throw new Error(`checklist exceeds ${CHECKLIST_MAX_TASKS}-task limit (got ${tasks.length})`)
+  }
+  return { title: patch.title ?? cl.title, tasks }
+}
+
+/**
+ * Build a CORRECT native `sendChecklist` payload per Bot API 9.1:
+ * `business_connection_id` is required, `title`/`tasks` nest inside a single
+ * `checklist` object (`InputChecklist`), each task carries its integer `id`,
+ * and there is NO completion field (`InputChecklistTask` has none).
+ */
+export function buildNativeChecklistPayload(p: {
+  businessConnectionId: string
+  chatId: number
+  title: string
+  tasks: ReadonlyArray<ChecklistTaskState>
+  replyToMessageId?: number
+  protectContent?: boolean
+}): Record<string, unknown> {
+  return {
+    business_connection_id: p.businessConnectionId,
+    chat_id: p.chatId,
+    checklist: {
+      title: p.title,
+      tasks: p.tasks.map((t) => ({ id: t.id, text: t.text })),
+    },
+    ...(p.replyToMessageId != null ? { reply_parameters: { message_id: p.replyToMessageId } } : {}),
+    ...(p.protectContent === true ? { protect_content: true } : {}),
+  }
+}
+
+/**
+ * Build a native `editMessageChecklist` payload. The native edit REPLACES
+ * the whole checklist, so the FULL post-patch state is sent; reusing the
+ * stored task ids preserves user tick state for unchanged tasks.
+ */
+export function buildNativeEditChecklistPayload(p: {
+  businessConnectionId: string
+  chatId: number
+  messageId: number
+  title: string
+  tasks: ReadonlyArray<ChecklistTaskState>
+}): Record<string, unknown> {
+  return {
+    business_connection_id: p.businessConnectionId,
+    chat_id: p.chatId,
+    message_id: p.messageId,
+    checklist: {
+      title: p.title,
+      tasks: p.tasks.map((t) => ({ id: t.id, text: t.text })),
+    },
+  }
+}
+
+/** Bounded per-message checklist state store (insertion-order eviction). */
+export interface ChecklistStore {
+  get(key: string): ChecklistState | undefined
+  set(key: string, state: ChecklistState): void
+}
+
+export function createChecklistStore(cap = 500): ChecklistStore {
+  const map = new Map<string, ChecklistState>()
+  return {
+    get: (key) => map.get(key),
+    set: (key, state) => {
+      if (map.has(key)) map.delete(key) // refresh insertion order
+      map.set(key, state)
+      while (map.size > cap) {
+        const oldest = map.keys().next().value as string | undefined
+        if (oldest == null) break
+        map.delete(oldest)
+      }
+    },
+  }
+}
+
+export function checklistStoreKey(chatId: string, messageId: string | number): string {
+  return `${chatId}:${messageId}`
+}
+
+// ─── Orchestration (deps-injected, unit-testable) ─────────────────────────
+
+export interface SendChecklistDeps {
+  /** Business connection id, when the operator has one configured. Native
+   *  checklists are impossible without it (required API parameter). */
+  businessConnectionId: string | undefined
+  /** Boot-probe result: the connected grammY/Bot API exposes sendChecklist. */
+  nativeAvailable: boolean
+  sendNative: (payload: Record<string, unknown>) => Promise<{ message_id: number }>
+  sendText: (text: string) => Promise<{ message_id: number }>
+  /** access.parseMode === 'text' — render without markdown. */
+  literalText: boolean
+  log: (line: string) => void
+}
+
+export interface SendChecklistResult {
+  message_id: number
+  mode: 'native' | 'text'
+  state: ChecklistState
+}
+
+/**
+ * Send a checklist: natively when possible, degrading to a formatted text
+ * message otherwise. NEVER lets a native-send failure escape — the fallback
+ * is the text render. (A text-send failure still throws: there is nothing
+ * further to degrade to, and the caller's normal error path applies.)
+ */
+export async function performSendChecklist(
+  deps: SendChecklistDeps,
+  args: {
+    title: string
+    tasks: ReadonlyArray<{ text: string; done?: boolean }>
+    chatId: number
+    replyToMessageId?: number
+    protectContent?: boolean
+  },
+): Promise<SendChecklistResult> {
+  const tasks = buildChecklistTasks(args.tasks)
+  if (deps.nativeAvailable && deps.businessConnectionId) {
+    try {
+      const sent = await deps.sendNative(buildNativeChecklistPayload({
+        businessConnectionId: deps.businessConnectionId,
+        chatId: args.chatId,
+        title: args.title,
+        tasks,
+        replyToMessageId: args.replyToMessageId,
+        protectContent: args.protectContent,
+      }))
+      return {
+        message_id: sent.message_id,
+        mode: 'native',
+        state: { title: args.title, tasks, mode: 'native' },
+      }
+    } catch (err) {
+      deps.log(`native sendChecklist failed — falling back to text render: ${err}\n`)
+    }
+  }
+  const text = renderChecklistText({ title: args.title, tasks }, { literal: deps.literalText })
+  const sent = await deps.sendText(text)
+  return {
+    message_id: sent.message_id,
+    mode: 'text',
+    state: { title: args.title, tasks, mode: 'text' },
+  }
+}
+
+/** Tool-result text for send_checklist. The degraded shape carries
+ *  `degraded: "text"` + a note so the calling agent knows the checklist is a
+ *  formatted message, not a natively tickable one. */
+export function sendChecklistToolText(r: SendChecklistResult): string {
+  return JSON.stringify(
+    r.mode === 'native'
+      ? { ok: true, message_id: r.message_id, mode: 'native' }
+      : {
+          ok: true,
+          message_id: r.message_id,
+          mode: 'text',
+          degraded: 'text',
+          note: 'rendered as a formatted text message (native Telegram checklists require a Business connection) — tasks are not tappable; use update_checklist with task ids 1..N to tick them',
+        },
+  )
+}
+
+export interface UpdateChecklistDeps {
+  /** Stored state for this chat:message, if the gateway still has it. */
+  state: ChecklistState | undefined
+  businessConnectionId: string | undefined
+  nativeAvailable: boolean
+  editNative: (payload: Record<string, unknown>) => Promise<void>
+  editText: (text: string) => Promise<void>
+  literalText: boolean
+  log: (line: string) => void
+  chatId: number
+  messageId: number
+}
+
+export type UpdateChecklistResult =
+  | { ok: true; mode: 'native' | 'text'; state: ChecklistState }
+  | { ok: false; reason: 'unknown_checklist' | 'edit_failed'; hint: string }
+
+/**
+ * Update a checklist message. Applies the patch to the stored state and
+ * re-renders in the mode the message was originally sent in. Failures come
+ * back as structured `{ ok: false, reason, hint }` results — never a raw
+ * Telegram error thrown at the caller.
+ */
+export async function performUpdateChecklist(
+  deps: UpdateChecklistDeps,
+  patch: ChecklistPatch,
+): Promise<UpdateChecklistResult> {
+  let base = deps.state
+  if (!base) {
+    // State lost (gateway restart / evicted). If the patch is a full
+    // replacement — a title plus tasks that all carry text — we can rebuild
+    // and edit as text (the fleet-normal mode). Otherwise we cannot know
+    // the existing tasks; degrade gracefully.
+    const fullReplacement =
+      patch.title != null &&
+      (patch.tasks?.length ?? 0) > 0 &&
+      (patch.tasks ?? []).every((t) => t.text != null)
+    if (!fullReplacement) {
+      return {
+        ok: false,
+        reason: 'unknown_checklist',
+        hint: 'no stored state for this checklist (gateway restarted?). Re-send it with send_checklist, or pass a full replacement (title + every task\'s text) to update_checklist.',
+      }
+    }
+    base = { title: patch.title!, tasks: [], mode: 'text' }
+  }
+  let next: { title: string; tasks: ChecklistTaskState[] }
+  try {
+    next = applyChecklistPatch(base, patch)
+  } catch (err) {
+    return { ok: false, reason: 'edit_failed', hint: String(err) }
+  }
+  const state: ChecklistState = { title: next.title, tasks: next.tasks, mode: base.mode }
+  if (base.mode === 'native') {
+    // A native checklist message cannot be edited into plain text — there is
+    // no text fallback here; a failure surfaces as a structured result.
+    if (!deps.nativeAvailable || !deps.businessConnectionId) {
+      return {
+        ok: false,
+        reason: 'edit_failed',
+        hint: 'this checklist was sent natively but the business connection / checklist API is no longer available.',
+      }
+    }
+    try {
+      await deps.editNative(buildNativeEditChecklistPayload({
+        businessConnectionId: deps.businessConnectionId,
+        chatId: deps.chatId,
+        messageId: deps.messageId,
+        title: state.title,
+        tasks: state.tasks,
+      }))
+      return { ok: true, mode: 'native', state }
+    } catch (err) {
+      deps.log(`native editMessageChecklist failed: ${err}\n`)
+      return { ok: false, reason: 'edit_failed', hint: String(err) }
+    }
+  }
+  try {
+    await deps.editText(renderChecklistText(state, { literal: deps.literalText }))
+    return { ok: true, mode: 'text', state }
+  } catch (err) {
+    deps.log(`checklist text edit failed: ${err}\n`)
+    return { ok: false, reason: 'edit_failed', hint: String(err) }
+  }
+}
+
+/** Tool-result text for update_checklist — structured for both outcomes. */
+export function updateChecklistToolText(r: UpdateChecklistResult, messageId: number): string {
+  return JSON.stringify(
+    r.ok
+      ? { ok: true, message_id: messageId, mode: r.mode, ...(r.mode === 'text' ? { degraded: 'text' } : {}) }
+      : { ok: false, reason: r.reason, hint: r.hint },
+  )
+}