switchroom 0.8.1 → 0.11.0

package/telegram-plugin/gateway/diff-preview-card.ts

@@ -0,0 +1,170 @@
+/**
+ * Telegram renderer for the diff-preview approval card — RFC E §4.2.
+ *
+ * Takes a `DiffPreview` (output of `src/drive/diff-preview.ts`) plus the
+ * two pre-registered approval-kernel request ids — one for the suggest
+ * scope, one for the write scope — and emits a `BuiltApprovalCard`
+ * (HTML body + grammy InlineKeyboard).
+ *
+ * Why two request ids? The card surfaces both "Apply as suggestion"
+ * and "Apply directly" buttons; each one grants a different kernel
+ * scope (`doc:gdrive:suggest:<id>` vs `doc:gdrive:write:<id>`). The
+ * upstream caller (the MCP-tool wrapper, or whoever's posting the
+ * card) registers BOTH up front with `approval_request`, then passes
+ * both ids into this renderer. The user taps one; the other expires
+ * naturally on the kernel side.
+ *
+ * Each action button reuses the existing `apv:<request_id>:once`
+ * callback shape so the generic kernel handler at
+ * `approval-callback.ts` records the grant without surface-specific
+ * routing. The "✅ once" semantics line up with the diff-preview's
+ * single-shot "do this edit now" intent.
+ */
+
+import { InlineKeyboard } from "grammy";
+import type { DiffPreview } from "../../src/drive/diff-preview.js";
+
+export interface BuiltDiffPreviewCard {
+  text: string;
+  reply_markup: InlineKeyboard;
+}
+
+export interface DiffPreviewCardInput {
+  preview: DiffPreview;
+  /**
+   * Kernel request id pre-registered for `doc:gdrive:suggest:<doc_id>`.
+   * Required — the suggest path is the RFC's default. When undefined
+   * the renderer throws (an "approval card with no Apply button"
+   * isn't a coherent UX).
+   */
+  suggestRequestId: string;
+  /**
+   * Kernel request id pre-registered for `doc:gdrive:write:<doc_id>`.
+   * Optional — when omitted, the "⚠ Apply directly" button is hidden
+   * (used for `gdrive_suggest_edit` callers that don't want to offer
+   * the direct-write escalation at all). When `preview.buttons` has
+   * an `apply_directly` entry but this is omitted, the button is
+   * dropped silently.
+   */
+  writeRequestId?: string;
+}
+
+/**
+ * 8-hex request id shape — same regex the kernel uses (RFC B §6.1).
+ * Defense in depth — a malformed request id would render an invalid
+ * callback_data that the dispatcher rejects, but we'd rather fail
+ * loudly at build time.
+ */
+const REQUEST_ID_RE = /^[0-9a-f]{8}$/;
+
+/**
+ * Fragility-guard from B2 review: the `create_doc` prep helper
+ * synthesises a "pending-create" placeholder fileId because the
+ * doc doesn't exist yet. `validateDriveId` happily accepts the
+ * literal "pending-create" string (it's alnum + `-`), so a naive
+ * Open-in-Drive button would emit a broken link. The renderer
+ * detects the sentinel and drops the open-in-drive row instead of
+ * rendering a dead link.
+ */
+const PENDING_FILE_ID_SENTINEL = "pending-create";
+
+export function buildDiffPreviewCard(
+  input: DiffPreviewCardInput,
+): BuiltDiffPreviewCard {
+  if (!REQUEST_ID_RE.test(input.suggestRequestId)) {
+    throw new Error(
+      `buildDiffPreviewCard: suggestRequestId must be 8 hex chars (got '${input.suggestRequestId}')`,
+    );
+  }
+  if (input.writeRequestId !== undefined && !REQUEST_ID_RE.test(input.writeRequestId)) {
+    throw new Error(
+      `buildDiffPreviewCard: writeRequestId must be 8 hex chars (got '${input.writeRequestId}')`,
+    );
+  }
+
+  const preview = input.preview;
+
+  // Body: title + every diff-preview line in order, HTML-escaped.
+  // The 📍 + line-count rows are surfaced verbatim — they're
+  // wrapper-attested and the agent has no input into their content.
+  const bodyLines: string[] = [];
+  bodyLines.push(`<b>${escapeHtml(preview.title)}</b>`);
+  for (const line of preview.lines) {
+    bodyLines.push(escapeHtml(line.text));
+  }
+  const text = bodyLines.join("\n");
+
+  const kb = new InlineKeyboard();
+
+  // Layout per RFC E §4.2 mockup:
+  //   row 1: [ 📖 Open in Drive ]  [ ✅ Apply as suggestion ]
+  //   row 2: [ ⚠ Apply directly ]   [ 🚫 Cancel ]
+  //
+  // Buttons whose `action` doesn't match a known shape are dropped
+  // silently — the diff-preview builder is the source of truth for
+  // which buttons exist; the renderer just maps them to callbacks.
+  const ROW_BREAK_AFTER: Array<DiffPreview["buttons"][number]["action"]> = [
+    "apply_suggestion",
+  ];
+  // `DiffPreview` doesn't carry the original mode, so infer from the
+  // button set: in suggest mode the builder always emits both
+  // `apply_suggestion` and `apply_directly`; in write mode it emits
+  // only `apply_directly`. The renderer drops `apply_directly` when
+  // a writeRequestId wasn't provided AND a suggestion path exists
+  // — caller chose to offer only Suggesting.
+  const offeringSuggestion = preview.buttons.some(
+    (b) => b.action === "apply_suggestion",
+  );
+  const droppedDirectly =
+    offeringSuggestion && input.writeRequestId === undefined;
+
+  const isPendingFileId =
+    preview.audit.wrapperAttested.fileId === PENDING_FILE_ID_SENTINEL;
+
+  let rowStarted = false;
+  const breakRow = () => {
+    if (rowStarted) {
+      kb.row();
+      rowStarted = false;
+    }
+  };
+
+  for (const btn of preview.buttons) {
+    switch (btn.action) {
+      case "open_in_drive": {
+        if (isPendingFileId) break; // drop sentinel-URL buttons
+        if (typeof btn.url !== "string" || btn.url.length === 0) break;
+        kb.url(btn.text, btn.url);
+        rowStarted = true;
+        break;
+      }
+      case "apply_suggestion": {
+        kb.text(btn.text, `apv:${input.suggestRequestId}:once`);
+        rowStarted = true;
+        break;
+      }
+      case "apply_directly": {
+        if (droppedDirectly) break;
+        const id = input.writeRequestId ?? input.suggestRequestId;
+        kb.text(btn.text, `apv:${id}:once`);
+        rowStarted = true;
+        break;
+      }
+      case "cancel": {
+        kb.text(btn.text, `apv:${input.suggestRequestId}:deny`);
+        rowStarted = true;
+        break;
+      }
+    }
+    if (ROW_BREAK_AFTER.includes(btn.action)) breakRow();
+  }
+
+  return { text, reply_markup: kb };
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/telegram-plugin/gateway/drive-write-approval.test.ts

@@ -0,0 +1,312 @@
+/**
+ * Tests for the Drive-write IPC handler — RFC E §4.2 Cut 2.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  DriveApprovalPostedEvent,
+  RequestDriveApprovalMessage,
+} from "./ipc-protocol.js";
+import {
+  type DriveApprovalHandlerDeps,
+  handleRequestDriveApproval,
+} from "./drive-write-approval.js";
+
+// ────────────────────────────────────────────────────────────────────────
+// Fixtures
+// ────────────────────────────────────────────────────────────────────────
+
+/** Valid DiffPreviewInput shape — matches src/drive/diff-preview.ts. */
+function validPreview(): Record<string, unknown> {
+  return {
+    agentName: "klanker",
+    docTitle: "Q3 Strategy Notes",
+    fileId: "DOC1",
+    mimeType: "application/vnd.google-apps.document",
+    resolvedAnchor: {
+      op: { kind: "insert_after", paragraphIndex: 4 },
+      displayName: "inside section 'Goals' (level 2)",
+    },
+    metrics: { linesAdded: 5, linesRemoved: 0 },
+    mode: "write",
+  };
+}
+
+interface Spy {
+  sent: DriveApprovalPostedEvent[];
+  registered: Array<{
+    scope: string;
+    action: string;
+    ttl_ms: number;
+    approver_set: string[];
+  }>;
+  posted: Array<{
+    chatId: number | string;
+    threadId?: number;
+    text: string;
+  }>;
+  logs: string[];
+}
+
+function makeSpy(): Spy {
+  return { sent: [], registered: [], posted: [], logs: [] };
+}
+
+function deps(overrides: Partial<DriveApprovalHandlerDeps> & { spy: Spy }): DriveApprovalHandlerDeps {
+  const spy = overrides.spy;
+  return {
+    agentName: "klanker",
+    loadAllowFrom: () => ["12345"],
+    loadTargetChat: () => ({ chatId: 999 }),
+    registerApproval: async (args) => {
+      spy.registered.push({
+        scope: args.scope,
+        action: args.action,
+        ttl_ms: args.ttl_ms,
+        approver_set: args.approver_set,
+      });
+      return { request_id: "aabbccdd", expires_at_ms: Date.now() + args.ttl_ms };
+    },
+    postCard: async (args) => {
+      spy.posted.push({
+        chatId: args.chatId,
+        ...(args.threadId !== undefined ? { threadId: args.threadId } : {}),
+        text: args.text,
+      });
+      return { messageId: 42 };
+    },
+    buildCard: () => ({ text: "diff-preview card body", reply_markup: { stub: true } }),
+    log: (m) => spy.logs.push(m),
+    ...overrides,
+  };
+}
+
+function clientFor(spy: Spy): { send: (msg: unknown) => void } {
+  return {
+    send: (msg) => {
+      const m = msg as DriveApprovalPostedEvent;
+      if (m.type === "drive_approval_posted") spy.sent.push(m);
+    },
+  };
+}
+
+function msgFor(overrides: Partial<RequestDriveApprovalMessage> = {}): RequestDriveApprovalMessage {
+  return {
+    type: "request_drive_approval",
+    correlationId: "corr-1",
+    agentName: "klanker",
+    preview: validPreview(),
+    ...overrides,
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Happy path
+// ────────────────────────────────────────────────────────────────────────
+
+describe("handleRequestDriveApproval — happy path", () => {
+  it("registers the kernel request + posts the card + replies success", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(clientFor(spy), msgFor(), deps({ spy }));
+    expect(spy.registered).toHaveLength(1);
+    expect(spy.registered[0]).toEqual({
+      scope: "doc:gdrive:write:DOC1",
+      action: "write",
+      ttl_ms: 5 * 60 * 1000,
+      approver_set: ["12345"],
+    });
+    expect(spy.posted).toHaveLength(1);
+    expect(spy.posted[0]?.chatId).toBe(999);
+    expect(spy.sent).toHaveLength(1);
+    expect(spy.sent[0]).toMatchObject({
+      type: "drive_approval_posted",
+      correlationId: "corr-1",
+      ok: true,
+      requestId: "aabbccdd",
+    });
+    expect(spy.sent[0]?.expiresAtMs).toBeGreaterThan(Date.now());
+  });
+
+  it("threads threadId through to postCard when targetChat has one", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({ spy, loadTargetChat: () => ({ chatId: 999, threadId: 7 }) }),
+    );
+    expect(spy.posted[0]?.threadId).toBe(7);
+  });
+
+  it("respects a caller-supplied ttlMs (within clamp)", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor({ ttlMs: 90_000 }),
+      deps({ spy }),
+    );
+    expect(spy.registered[0]?.ttl_ms).toBe(90_000);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Refusals
+// ────────────────────────────────────────────────────────────────────────
+
+describe("handleRequestDriveApproval — refusals", () => {
+  it("refuses cross-agent requests", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor({ agentName: "clerk" }),
+      deps({ spy }),
+    );
+    expect(spy.registered).toEqual([]);
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/serves 'klanker'/);
+  });
+
+  it("refuses malformed preview payloads", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor({ preview: { junk: true } }),
+      deps({ spy }),
+    );
+    expect(spy.registered).toEqual([]);
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/invalid preview/);
+  });
+
+  it("refuses when no operator allowFrom is configured", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({ spy, loadAllowFrom: () => [] }),
+    );
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/allowFrom/);
+  });
+
+  it("refuses when no target chat is available", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({ spy, loadTargetChat: () => null }),
+    );
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/target chat/);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Failure modes
+// ────────────────────────────────────────────────────────────────────────
+
+describe("handleRequestDriveApproval — downstream failures", () => {
+  it("kernel approval_request failure → ok:false with diagnostic reason", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({ spy, registerApproval: async () => null }),
+    );
+    expect(spy.posted).toEqual([]); // card not posted
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/kernel approval_request/);
+  });
+
+  it("card build throw → ok:false (caught + reported)", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({
+        spy,
+        buildCard: () => {
+          throw new Error("invalid request id");
+        },
+      }),
+    );
+    expect(spy.posted).toEqual([]);
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/card build failed/);
+  });
+
+  it("Telegram sendMessage failure → ok:false", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({ spy, postCard: async () => null }),
+    );
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/sendMessage failed/);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// TTL clamping
+// ────────────────────────────────────────────────────────────────────────
+
+describe("handleRequestDriveApproval — TTL clamping", () => {
+  it("clamps below-min TTL up to the minimum", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor({ ttlMs: 1000 }),
+      deps({ spy }),
+    );
+    expect(spy.registered[0]?.ttl_ms).toBe(30_000); // min default
+  });
+
+  it("clamps above-max TTL down to the maximum", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor({ ttlMs: 999_999_999 }),
+      deps({ spy }),
+    );
+    expect(spy.registered[0]?.ttl_ms).toBe(30 * 60 * 1000); // max default
+  });
+
+  it("uses the configured default when ttlMs is undefined", async () => {
+    const spy = makeSpy();
+    await handleRequestDriveApproval(clientFor(spy), msgFor(), deps({ spy }));
+    expect(spy.registered[0]?.ttl_ms).toBe(5 * 60 * 1000);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Always responds (no path drops the response)
+// ────────────────────────────────────────────────────────────────────────
+
+describe("handleRequestDriveApproval — invariant: always sends a reply", () => {
+  it("every refusal path emits exactly one drive_approval_posted event", async () => {
+    const cases: Array<Partial<DriveApprovalHandlerDeps> | "cross-agent" | "bad-preview"> = [
+      "cross-agent",
+      "bad-preview",
+      { loadAllowFrom: () => [] },
+      { loadTargetChat: () => null },
+      { registerApproval: async () => null },
+      { postCard: async () => null },
+    ];
+    for (const c of cases) {
+      const spy = makeSpy();
+      const msg =
+        c === "cross-agent"
+          ? msgFor({ agentName: "clerk" })
+          : c === "bad-preview"
+            ? msgFor({ preview: { bad: true } })
+            : msgFor();
+      const dep =
+        c === "cross-agent" || c === "bad-preview"
+          ? deps({ spy })
+          : deps({ spy, ...c });
+      await handleRequestDriveApproval(clientFor(spy), msg, dep);
+      expect(spy.sent).toHaveLength(1);
+    }
+  });
+});