switchroom 0.13.9 → 0.13.10

package/telegram-plugin/gateway/config-approval-handler.test.ts

@@ -0,0 +1,246 @@
+/**
+ * Gateway-side `request_config_approval` handler tests (#1623).
+ *
+ * Focuses on the load-bearing transitions, not exhaustive plumbing:
+ *   - Happy path: card posted, callback resolved, finalize edits.
+ *   - Cross-agent rejection.
+ *   - Double-tap is a no-op (second `resolvePendingConfigApproval`
+ *     returns false and does not send a second verdict).
+ *   - Timeout fires `verdict: "timeout"` automatically.
+ *   - parseConfigApprovalCallback parses + rejects malformed input.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  buildConfigApprovalCardBody,
+  handleRequestConfigApproval,
+  handleRequestConfigFinalize,
+  parseConfigApprovalCallback,
+  resolvePendingConfigApproval,
+  _resetPendingConfigApprovalsForTest,
+  _peekPendingConfigApprovalForTest,
+} from "./config-approval-handler.js";
+import type { RequestConfigApprovalMessage } from "./ipc-protocol.js";
+
+const baseMsg: RequestConfigApprovalMessage = {
+  type: "request_config_approval",
+  requestId: "req-1",
+  agentName: "klanker",
+  reason: "tighten doctor schedule",
+  unifiedDiff: "--- a/x\n+++ b/x\n@@\n-a\n+b\n",
+  timeoutMs: 60_000,
+};
+
+function fakeDeps(overrides: Partial<Parameters<typeof handleRequestConfigApproval>[2]> = {}) {
+  const sent: Array<{ type: string; [k: string]: unknown }> = [];
+  const client = {
+    send: (m: { type: string; [k: string]: unknown }) => {
+      sent.push(m);
+    },
+  };
+  const editCalls: Array<{
+    chatId: number | string;
+    messageId: number;
+    text: string;
+  }> = [];
+  const deps = {
+    agentName: "klanker",
+    loadTargetChat: () => ({ chatId: 42 }),
+    postCard: vi.fn(async () => ({ messageId: 1001 })),
+    buildKeyboard: () => ({ inline_keyboard: [] }),
+    editCard: async (a: { chatId: number | string; messageId: number; text: string }) => {
+      editCalls.push(a);
+    },
+    log: () => {},
+    ...overrides,
+  };
+  return { client, sent, deps, editCalls };
+}
+
+beforeEach(() => {
+  _resetPendingConfigApprovalsForTest();
+});
+afterEach(() => {
+  _resetPendingConfigApprovalsForTest();
+});
+
+describe("buildConfigApprovalCardBody", () => {
+  it("HTML-escapes the diff body so `<` / `&` can't break out of the <pre> block", () => {
+    const body = buildConfigApprovalCardBody({
+      agentName: "klanker",
+      reason: "<script>",
+      unifiedDiff: "a & b <c>",
+    });
+    expect(body).toContain("&lt;script&gt;");
+    expect(body).toContain("a &amp; b &lt;c&gt;");
+  });
+});
+
+describe("handleRequestConfigApproval", () => {
+  it("posts the card, registers a pending entry, and stays open until resolved", async () => {
+    const { client, deps } = fakeDeps();
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    expect(deps.postCard).toHaveBeenCalledTimes(1);
+    const pending = _peekPendingConfigApprovalForTest("req-1");
+    expect(pending).toBeDefined();
+    expect(pending!.messageId).toBe(1001);
+  });
+
+  it("rejects a cross-agent request without posting a card", async () => {
+    const { client, sent, deps } = fakeDeps();
+    await handleRequestConfigApproval(
+      client,
+      { ...baseMsg, agentName: "evilpeer" },
+      deps,
+    );
+    expect(deps.postCard).not.toHaveBeenCalled();
+    expect(sent).toEqual([
+      {
+        type: "config_approval_resolved",
+        requestId: "req-1",
+        verdict: "deny",
+        reason: expect.stringContaining("gateway serves 'klanker'"),
+      },
+    ]);
+  });
+
+  it("rejects when no target chat is paired", async () => {
+    const { client, sent, deps } = fakeDeps({ loadTargetChat: () => null });
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    expect(sent[0]!.verdict).toBe("deny");
+    expect(sent[0]!.reason).toMatch(/not paired/);
+  });
+
+  it("rejects when postCard fails (Telegram down)", async () => {
+    const { client, sent, deps } = fakeDeps({
+      postCard: vi.fn(async () => null),
+    });
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    expect(sent[0]!.verdict).toBe("deny");
+    expect(sent[0]!.reason).toMatch(/sendMessage failed/);
+  });
+});
+
+describe("resolvePendingConfigApproval — double-tap and verdict propagation", () => {
+  it("first tap resolves; second tap is a no-op", async () => {
+    const { client, sent, deps, editCalls } = fakeDeps();
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    const first = await resolvePendingConfigApproval("req-1", "approve", deps);
+    expect(first).toBe(true);
+    const second = await resolvePendingConfigApproval("req-1", "deny", deps);
+    expect(second).toBe(false);
+    // Only one verdict crossed the wire to hostd.
+    const verdicts = sent.filter((s) => s.type === "config_approval_resolved");
+    expect(verdicts.length).toBe(1);
+    expect(verdicts[0]!.verdict).toBe("approve");
+    // Card edited once to the interim 'Applying' state.
+    expect(editCalls.length).toBe(1);
+    expect(editCalls[0]!.text).toMatch(/Applying/);
+  });
+
+  it("returns false when no entry exists (unknown requestId)", async () => {
+    const { deps } = fakeDeps();
+    const r = await resolvePendingConfigApproval("unknown", "approve", deps);
+    expect(r).toBe(false);
+  });
+});
+
+describe("timeout path", () => {
+  it("auto-fires verdict 'timeout' after timeoutMs and edits card to '⏱ Expired'", async () => {
+    vi.useFakeTimers();
+    try {
+      const { client, sent, deps, editCalls } = fakeDeps();
+      await handleRequestConfigApproval(
+        client,
+        { ...baseMsg, timeoutMs: 1000 },
+        deps,
+      );
+      vi.advanceTimersByTime(1500);
+      // Allow microtasks scheduled inside the timer callback to flush.
+      // NOT vi.runAllTimersAsync() — that is unimplemented under bun's
+      // vitest-compat shim and this suite also runs under `bun test`
+      // (CLAUDE.md § "Import the right runner"). advanceTimersByTime
+      // already fired the timer synchronously; we only need to drain
+      // the microtask queue the timer's async callback scheduled.
+      for (let i = 0; i < 8; i++) await Promise.resolve();
+      const verdicts = sent.filter((s) => s.type === "config_approval_resolved");
+      expect(verdicts.length).toBe(1);
+      expect(verdicts[0]!.verdict).toBe("timeout");
+      expect(editCalls[0]!.text).toMatch(/Expired/);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("handleRequestConfigFinalize", () => {
+  it("edits the card to '✅ Applied' on success", async () => {
+    const { client, deps, editCalls } = fakeDeps();
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    await resolvePendingConfigApproval("req-1", "approve", deps);
+    await handleRequestConfigFinalize(
+      client,
+      {
+        type: "request_config_finalize",
+        requestId: "req-1",
+        outcome: "applied",
+      },
+      deps,
+    );
+    const last = editCalls[editCalls.length - 1]!;
+    expect(last.text).toMatch(/Applied/);
+  });
+
+  it("edits to '⚠️ Reconcile failed; rolled back' with detail", async () => {
+    const { client, deps, editCalls } = fakeDeps();
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    await resolvePendingConfigApproval("req-1", "approve", deps);
+    await handleRequestConfigFinalize(
+      client,
+      {
+        type: "request_config_finalize",
+        requestId: "req-1",
+        outcome: "reconcile_failed_rolled_back",
+        detail: "rolled back successfully",
+      },
+      deps,
+    );
+    const last = editCalls[editCalls.length - 1]!;
+    expect(last.text).toMatch(/Reconcile failed/);
+    expect(last.text).toMatch(/rolled back successfully/);
+  });
+
+  it("is a no-op when no pending entry exists for the requestId", async () => {
+    const { client, deps, editCalls } = fakeDeps();
+    await handleRequestConfigFinalize(
+      client,
+      {
+        type: "request_config_finalize",
+        requestId: "missing",
+        outcome: "applied",
+      },
+      deps,
+    );
+    expect(editCalls.length).toBe(0);
+  });
+});
+
+describe("parseConfigApprovalCallback", () => {
+  it("parses well-formed callbacks", () => {
+    expect(parseConfigApprovalCallback("cfg:abc:approve")).toEqual({
+      requestId: "abc",
+      choice: "approve",
+    });
+    expect(parseConfigApprovalCallback("cfg:deadbeef:deny")).toEqual({
+      requestId: "deadbeef",
+      choice: "deny",
+    });
+  });
+
+  it("rejects malformed input", () => {
+    expect(parseConfigApprovalCallback("apv:abc:once")).toBeNull();
+    expect(parseConfigApprovalCallback("cfg:")).toBeNull();
+    expect(parseConfigApprovalCallback("cfg:abc:bogus")).toBeNull();
+    expect(parseConfigApprovalCallback("cfg::approve")).toBeNull();
+  });
+});

package/telegram-plugin/gateway/config-approval-handler.ts

@@ -0,0 +1,284 @@
+// hostd config-edit approval handler (#1623 / RFC §3.3): posts an approval
+// card, resolves the verdict back to hostd over IPC, and flips the card to
+// a terminal state on finalize.
+
+import type { IpcClient } from "./ipc-server.js";
+import type {
+  RequestConfigApprovalMessage,
+  RequestConfigFinalizeMessage,
+} from "./ipc-protocol.js";
+
+/** Pending approval state — in-memory only (no SQLite per RFC §3.4). */
+interface PendingConfigApproval {
+  requestId: string;
+  client: Pick<IpcClient, "send">;
+  chatId: number | string;
+  threadId?: number;
+  messageId: number;
+  /** node:Timeout — set when the timer is armed; cleared once the
+   *  request resolves (approve/deny/timeout) to make resolve idempotent. */
+  timer: ReturnType<typeof setTimeout> | null;
+  /** Has a verdict already been sent? Guards against double-tap. */
+  resolved: boolean;
+}
+
+const pending = new Map<string, PendingConfigApproval>();
+
+// Injected deps — gateway.ts wires these from the existing surface.
+
+export interface ConfigApprovalHandlerDeps {
+  /** This gateway's agent name — cross-agent requests rejected. */
+  agentName: string;
+  /** Operator's primary chat for the card. Returns null if not paired. */
+  loadTargetChat: () => {
+    chatId: number | string;
+    threadId?: number;
+  } | null;
+  /** Post the Telegram card. Returns the posted message id on success. */
+  postCard: (args: {
+    chatId: number | string;
+    threadId?: number;
+    text: string;
+    /** grammy InlineKeyboard, passed through verbatim. */
+    replyMarkup: unknown;
+  }) => Promise<{ messageId: number } | null>;
+  /** Build the inline keyboard with [✅ Approve] [🚫 Deny] buttons. */
+  buildKeyboard: (requestId: string) => unknown;
+  /** Edit a posted card to a new body. Best-effort — failures logged. */
+  editCard: (args: {
+    chatId: number | string;
+    messageId: number;
+    text: string;
+  }) => Promise<void>;
+  log?: (msg: string) => void;
+}
+
+/**
+ * Build the card body (HTML). Renders the full diff in a `<pre>`
+ * code block — Telegram caps messages at 4096 chars, so very large
+ * diffs may be truncated by the API; the validator already caps
+ * unified_diff at ~63 KiB so practical fleet edits fit comfortably.
+ */
+export function buildConfigApprovalCardBody(args: {
+  agentName: string;
+  reason: string;
+  unifiedDiff: string;
+}): string {
+  const esc = (s: string) =>
+    s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return (
+    `🛠 <b>Config edit proposed</b>\n` +
+    `Agent: <code>${esc(args.agentName)}</code>\n` +
+    `Reason: ${esc(args.reason)}\n\n` +
+    `<pre>${esc(args.unifiedDiff)}</pre>`
+  );
+}
+
+/**
+ * Top-level handler — called by the IPC dispatcher.
+ */
+export async function handleRequestConfigApproval(
+  client: Pick<IpcClient, "send">,
+  msg: RequestConfigApprovalMessage,
+  deps: ConfigApprovalHandlerDeps,
+): Promise<void> {
+  const reply = (
+    verdict: "approve" | "deny" | "timeout",
+    reason?: string,
+  ) => {
+    try {
+      client.send({
+        type: "config_approval_resolved",
+        requestId: msg.requestId,
+        verdict,
+        ...(reason ? { reason } : {}),
+      });
+    } catch (err) {
+      deps.log?.(
+        `config_approval_resolved send failed (requestId=${msg.requestId}): ${(err as Error).message}`,
+      );
+    }
+  };
+
+  if (msg.agentName !== deps.agentName) {
+    reply("deny", `gateway serves '${deps.agentName}', not '${msg.agentName}'`);
+    return;
+  }
+
+  const target = deps.loadTargetChat();
+  if (target === null) {
+    reply("deny", "no target chat available — operator not paired?");
+    return;
+  }
+
+  const body = buildConfigApprovalCardBody({
+    agentName: msg.agentName,
+    reason: msg.reason,
+    unifiedDiff: msg.unifiedDiff,
+  });
+  const replyMarkup = deps.buildKeyboard(msg.requestId);
+
+  const posted = await deps.postCard({
+    chatId: target.chatId,
+    ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+    text: body,
+    replyMarkup,
+  });
+  if (posted === null) {
+    reply("deny", "Telegram sendMessage failed");
+    return;
+  }
+
+  const entry: PendingConfigApproval = {
+    requestId: msg.requestId,
+    client,
+    chatId: target.chatId,
+    ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+    messageId: posted.messageId,
+    timer: null,
+    resolved: false,
+  };
+  entry.timer = setTimeout(() => {
+    void resolvePendingConfigApproval(msg.requestId, "timeout", deps).catch(
+      (err) =>
+        deps.log?.(
+          `config approval timeout handler threw (requestId=${msg.requestId}): ${(err as Error).message}`,
+        ),
+    );
+  }, msg.timeoutMs);
+  pending.set(msg.requestId, entry);
+
+  deps.log?.(
+    `config_approval_posted requestId=${msg.requestId} agent=${msg.agentName} messageId=${posted.messageId}`,
+  );
+}
+
+/**
+ * Called by the `cfg:` callback dispatcher in gateway.ts on an
+ * operator tap, by the per-request timer on expiry, OR by the
+ * finalize path defensively before edit. Sends a single
+ * `config_approval_resolved` reply over the original client
+ * connection and edits the card to the interim state. Double-tap
+ * safe — subsequent calls for the same requestId are no-ops.
+ *
+ * Returns true if THIS call resolved the request (first call wins),
+ * false if it was already resolved.
+ */
+export async function resolvePendingConfigApproval(
+  requestId: string,
+  verdict: "approve" | "deny" | "timeout",
+  deps: Pick<ConfigApprovalHandlerDeps, "editCard" | "log">,
+): Promise<boolean> {
+  const entry = pending.get(requestId);
+  if (!entry || entry.resolved) return false;
+  entry.resolved = true;
+  if (entry.timer !== null) {
+    clearTimeout(entry.timer);
+    entry.timer = null;
+  }
+
+  // Send the verdict back to hostd. Best effort — if the IPC
+  // connection has dropped, hostd's own timeout will fire.
+  try {
+    entry.client.send({
+      type: "config_approval_resolved",
+      requestId,
+      verdict,
+    });
+  } catch (err) {
+    deps.log?.(
+      `config_approval_resolved send failed (requestId=${requestId}): ${(err as Error).message}`,
+    );
+  }
+
+  // Edit the card to an interim/terminal state.
+  const interim =
+    verdict === "approve"
+      ? "👀 <b>Applying…</b>"
+      : verdict === "deny"
+        ? "🚫 <b>Denied</b>"
+        : "⏱ <b>Expired</b>";
+  try {
+    await deps.editCard({
+      chatId: entry.chatId,
+      messageId: entry.messageId,
+      text: interim,
+    });
+  } catch (err) {
+    deps.log?.(
+      `config approval card edit failed (requestId=${requestId}): ${(err as Error).message}`,
+    );
+  }
+  return true;
+}
+
+/** IPC `request_config_finalize` handler — edits the card to the terminal outcome. */
+export async function handleRequestConfigFinalize(
+  _client: Pick<IpcClient, "send">,
+  msg: RequestConfigFinalizeMessage,
+  deps: Pick<ConfigApprovalHandlerDeps, "editCard" | "log">,
+): Promise<void> {
+  const entry = pending.get(msg.requestId);
+  if (!entry) {
+    deps.log?.(
+      `config_finalize: no pending entry for requestId=${msg.requestId} (likely already cleaned up)`,
+    );
+    return;
+  }
+  // Clean up the pending entry — finalize is the terminal transition.
+  pending.delete(msg.requestId);
+
+  const body =
+    msg.outcome === "applied"
+      ? `✅ <b>Applied</b>${msg.detail ? `\n${escapeHtml(msg.detail)}` : ""}`
+      : `⚠️ <b>Reconcile failed; rolled back</b>${msg.detail ? `\n${escapeHtml(msg.detail)}` : ""}`;
+  try {
+    await deps.editCard({
+      chatId: entry.chatId,
+      messageId: entry.messageId,
+      text: body,
+    });
+  } catch (err) {
+    deps.log?.(
+      `config finalize card edit failed (requestId=${msg.requestId}): ${(err as Error).message}`,
+    );
+  }
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// Test-only: clear the in-memory pending map between cases.
+export function _resetPendingConfigApprovalsForTest(): void {
+  for (const entry of pending.values()) {
+    if (entry.timer !== null) clearTimeout(entry.timer);
+  }
+  pending.clear();
+}
+
+// Test-only: peek at a pending entry.
+export function _peekPendingConfigApprovalForTest(
+  requestId: string,
+): Readonly<PendingConfigApproval> | undefined {
+  return pending.get(requestId);
+}
+
+/**
+ * Parse `cfg:<requestId>:<choice>` callback data. Returns null on
+ * malformed input. The callback handler in gateway.ts uses this +
+ * resolvePendingConfigApproval to drive the tap → resolve flow.
+ */
+export function parseConfigApprovalCallback(
+  data: string,
+): { requestId: string; choice: "approve" | "deny" } | null {
+  if (!data.startsWith("cfg:")) return null;
+  const rest = data.slice(4);
+  const colon = rest.lastIndexOf(":");
+  if (colon < 0) return null;
+  const requestId = rest.slice(0, colon);
+  const choice = rest.slice(colon + 1);
+  if (requestId.length === 0 || requestId.length > 64) return null;
+  if (choice !== "approve" && choice !== "deny") return null;
+  return { requestId, choice };
+}