W6: Telegram notifications bridge (V1) (#524)

* feat(gateway): reviewer/PM collision map (W5) The collision surface (intends_to_touch / adds_migration / touches_shared) is authored at delegate time, consumed once by SequencingService to wire dependency edges, then never shown to a reviewer again. This surfaces it: - Pure builder (services/gateway/choreographer/collision.py): for a task under review, the surfaced siblings (same parent) that would collide — file-overlap globs or a shared migration chain (both adds_migration) — with the overlapping globs and a declared-vs-actual drift check. No DB/IO; callers fetch siblings (one indexed get_subtasks query, mig 069) + actual files (git). Caps: 10 siblings, 5 globs. - Evidence envelopes: collision_context block injected into QA claim_review, PR-gate claim_gate_review (both carry real touched files so drift is populated), and the PM i_will_plan briefing (no actual files at plan time, drift omitted). Best-effort — a failure omits the block, never breaks the verb/briefing. Empty block omitted (zero token cost via _EVIDENCE_OMIT_WHEN_EMPTY). - Panel: GET /api/tasks/{id}/collision-map (declared surface + sibling overlap; no drift — the panel route resolves no workspace) + a Collision tab on the task detail (8th tab). Mock-mode returns an empty map. - docs/map added to the RAG auto-index dirs so the collision-map concept is fleet-retrievable; skipped gracefully if the dir is absent. 19 new tests (15 unit on the pure builder + 4 integration on the route). Gate green: ruff/mypy/xenon (module rank A)/pytest 13000/coverage 94.81%, panel typecheck/lint/516 tests. * [w6-telegram] Add Telegram notifications bridge (V1) CEO-facing Telegram DM bridge, flag-gated off by default (ROBOCO_TELEGRAM_ENABLED). Mirrors the X-credentials / X-client pattern: - TelegramCredentialsTable (migration 073) — singleton Fernet-encrypted bot_token + chat_id, all-or-nothing set/clear; API never returns plaintext. - TelegramClient ABC / NullTelegramClient (no-op, configured->False, never raises) / LiveTelegramClient (httpx POST sendMessage) / build_telegram_client factory (Null when creds unset). - /telegram/credentials CEO-only routes (write-only, guard-decorated). - Best-effort _notify_telegram fan-out from the two CEO-notify producers (notify_ceo_of_escalation, notify_ceo_of_completion) — guarded by the flag, never raises into the producer, carries a panel deep-link when panel_base_url is set. - panel credentials card (2 fields) nested in the Telegram feature-flag row. - panel_base_url + telegram_timeout_seconds config fields. V1 scope only: credentials + flag + panel card + client + one-line fan-out. Out of scope (V2): inbound commands, a TelegramEngine background loop, a dedup ledger, a bus subscription. * [w6-telegram] fix: slave mypy/xenon regression (product tests + helper extract) Pre-existing on slave from prior session's merges — no PR's CI caught them (squash merges don't re-CI the result; each branch was based on older slave). - test_product: _product helper returned MagicMock -> list invariant error; cast to ProductTable, move import under TYPE_CHECKING. - test_usage: svc.session.execute (AsyncSession) has no call_args_list; cast to MagicMock at the two call sites. - product.progress_for_products: xenon rank C -> extract module-level _project_to_products_map helper (repo pattern: helper-extract). --------- Co-authored-by: Renn F <rennf93@users.noreply.github.com>
2026-08-03 07:23:24 +02:00 · 2026-07-15 05:45:57 +02:00
parent d80dfb8bbe
commit bb3b4b0c6d
35 changed files with 2100 additions and 20 deletions
@@ -0,0 +1,143 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+
+const { getCredentialsStatus, setCredentials } = vi.hoisted(() => ({
+  getCredentialsStatus: vi.fn(async () => ({ has_credentials: false })),
+  setCredentials: vi.fn(async () => ({ has_credentials: true })),
+}));
+
+vi.mock("@/lib/api", () => ({
+  telegramApi: { getCredentialsStatus, setCredentials },
+}));
+
+import { TelegramCredentialsForm } from "../telegram-credentials-card";
+
+function withQueryClient(ui: ReactNode) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{ui}</QueryClientProvider>;
+}
+
+describe("TelegramCredentialsForm", () => {
+  beforeEach(() => {
+    getCredentialsStatus.mockClear();
+    setCredentials.mockClear();
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("shows 'no credentials configured' by default", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    expect(
+      await screen.findByText("No credentials configured"),
+    ).toBeInTheDocument();
+  });
+
+  it("disables Save until both fields are filled", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("No credentials configured");
+    const saveButton = screen.getByRole("button", { name: "Save" });
+    expect(saveButton).toBeDisabled();
+
+    fireEvent.change(screen.getByLabelText("Bot token (from @BotFather)"), {
+      target: { value: "123:abc" },
+    });
+    expect(saveButton).toBeDisabled(); // chat id still unfilled
+
+    fireEvent.change(screen.getByLabelText("Chat id (destination)"), {
+      target: { value: "987" },
+    });
+    expect(saveButton).not.toBeDisabled();
+  });
+
+  it("saves both secrets and clears the inputs on success", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("No credentials configured");
+
+    fireEvent.change(screen.getByLabelText("Bot token (from @BotFather)"), {
+      target: { value: "123:abc" },
+    });
+    fireEvent.change(screen.getByLabelText("Chat id (destination)"), {
+      target: { value: "987" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() =>
+      expect(setCredentials).toHaveBeenCalledWith({
+        bot_token: "123:abc",
+        chat_id: "987",
+      }),
+    );
+    await waitFor(() =>
+      expect(
+        (
+          screen.getByLabelText("Bot token (from @BotFather)") as HTMLInputElement
+        ).value,
+      ).toBe(""),
+    );
+  });
+
+  it("a clear (both blank + has_credentials) opens a confirm dialog and defers the mutation until confirmed", async () => {
+    getCredentialsStatus.mockResolvedValueOnce({ has_credentials: true });
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("Credentials are set");
+
+    const saveButton = screen.getByRole("button", { name: "Save" });
+    expect(saveButton).not.toBeDisabled();
+
+    fireEvent.click(saveButton);
+
+    const dialog = await screen.findByRole("alertdialog");
+    expect(dialog).toBeInTheDocument();
+    expect(setCredentials).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByRole("button", { name: "Clear" }));
+    await waitFor(() =>
+      expect(setCredentials).toHaveBeenCalledWith({
+        bot_token: "",
+        chat_id: "",
+      }),
+    );
+  });
+
+  it("a normal both-filled save fires immediately without a confirm dialog", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("No credentials configured");
+
+    fireEvent.change(screen.getByLabelText("Bot token (from @BotFather)"), {
+      target: { value: "123:abc" },
+    });
+    fireEvent.change(screen.getByLabelText("Chat id (destination)"), {
+      target: { value: "987" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() =>
+      expect(setCredentials).toHaveBeenCalledWith({
+        bot_token: "123:abc",
+        chat_id: "987",
+      }),
+    );
+    expect(screen.queryByRole("alertdialog")).not.toBeInTheDocument();
+  });
+
+  it("a clear confirm dialog cancel does NOT fire the mutation", async () => {
+    getCredentialsStatus.mockResolvedValueOnce({ has_credentials: true });
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("Credentials are set");
+
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    const dialog = await screen.findByRole("alertdialog");
+    expect(dialog).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    await waitFor(() =>
+      expect(screen.queryByRole("alertdialog")).not.toBeInTheDocument(),
+    );
+    expect(setCredentials).not.toHaveBeenCalled();
+  });
+});
@@ -31,6 +31,7 @@ import {
 } from "@/components/ui/collapsible";
 import { XCredentialsForm } from "@/components/settings/x-credentials-card";
 import { TikTokCredentialsForm } from "@/components/settings/tiktok-credentials-card";
+import { TelegramCredentialsForm } from "@/components/settings/telegram-credentials-card";
 import { cn } from "@/lib/utils";
 import { Flag, ChevronDown, ChevronRight } from "lucide-react";
 import { toast } from "sonner";
@@ -93,12 +94,15 @@ const FLAG_DESCRIPTIONS: Record<string, string> = {
    "Materialize a weekly org-report note (velocity, cycle time, rework, cost) in the vault's Reports/ folder and notify you — deterministic numbers, no LLM. Needs the Obsidian vault projection on.",
  vault_kb_enabled:
    "Index your own vault notes (default RoboCo/Notes/) into the knowledge base so the fleet can retrieve what you write — every note is screened for injection attempts before it's indexed. Needs the Obsidian vault projection on.",
+  telegram_enabled:
+    "Best-effort Telegram DMs to you alongside in-app notifications when a task is escalated for your approval or completes. Server-side fan-out — never blocks the in-app notification. Stays inert until you set bot-token + chat-id credentials in the Telegram card below.",
 };

 export function FeatureFlagsCard() {
  const queryClient = useQueryClient();
  const [xCredsOpen, setXCredsOpen] = useState(false);
  const [tiktokCredsOpen, setTiktokCredsOpen] = useState(false);
+  const [telegramCredsOpen, setTelegramCredsOpen] = useState(false);
  // Off-transition awaiting operator confirm. Null = no dialog open.
  const [confirmFlag, setConfirmFlag] = useState<FeatureFlag | null>(null);
  // Every in-flight toggle key — added on mutate, removed on settle. Tracks
@@ -170,12 +174,13 @@ export function FeatureFlagsCard() {
          {flags.map((flag) => {
            const isXEngine = flag.key === "x_engine_enabled";
            const isVideoEngine = flag.key === "video_engine_enabled";
+            const isTelegram = flag.key === "telegram_enabled";
            return (
              <div
                key={flag.key}
                className={cn(
                  "rounded-lg border p-4",
-                  (isXEngine || isVideoEngine) && "md:col-span-2",
+                  (isXEngine || isVideoEngine || isTelegram) && "md:col-span-2",
                )}
              >
                <div className="flex items-start justify-between gap-4">
@@ -251,6 +256,31 @@ export function FeatureFlagsCard() {
                    </CollapsibleContent>
                  </Collapsible>
                )}
+                {isTelegram && (
+                  <Collapsible
+                    open={telegramCredsOpen}
+                    onOpenChange={setTelegramCredsOpen}
+                    className="mt-3"
+                  >
+                    <CollapsibleTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        className="w-full justify-between px-2 text-muted-foreground"
+                      >
+                        <span className="text-sm">Telegram credentials</span>
+                        {telegramCredsOpen ? (
+                          <ChevronDown className="h-4 w-4" />
+                        ) : (
+                          <ChevronRight className="h-4 w-4" />
+                        )}
+                      </Button>
+                    </CollapsibleTrigger>
+                    <CollapsibleContent className="pt-3">
+                      <TelegramCredentialsForm />
+                    </CollapsibleContent>
+                  </Collapsible>
+                )}
              </div>
            );
          })}
@@ -0,0 +1,149 @@
+"use client";
+
+import { useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { telegramApi } from "@/lib/api";
+import { Label } from "@/components/ui/label";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Key, KeyRound, Save } from "lucide-react";
+import { toast } from "sonner";
+
+const FIELDS: Array<{ key: "bot_token" | "chat_id"; label: string }> = [
+  { key: "bot_token", label: "Bot token (from @BotFather)" },
+  { key: "chat_id", label: "Chat id (destination)" },
+];
+
+// The CEO's one-time entry of the Telegram bot token + destination chat id.
+// Write-only — the stored values are never displayed back, only whether
+// they're set (mirrors the X / git-token cards). Both are required together:
+// a token alone can't target a DM. Rendered chrome-less so it can nest inside
+// the Telegram feature-flag row.
+export function TelegramCredentialsForm() {
+  const queryClient = useQueryClient();
+  const [values, setValues] = useState({ bot_token: "", chat_id: "" });
+
+  const { data: status, isLoading } = useQuery({
+    queryKey: ["telegram", "credentials"],
+    queryFn: () => telegramApi.getCredentialsStatus(),
+  });
+
+  const saveMutation = useMutation({
+    mutationFn: () => telegramApi.setCredentials(values),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["telegram", "credentials"] });
+      setValues({ bot_token: "", chat_id: "" });
+      toast.success("Telegram credentials saved");
+    },
+    onError: (error) => {
+      toast.error(
+        `Failed to save: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    },
+  });
+
+  const allFilled = FIELDS.every((f) => values[f.key].trim().length > 0);
+  const noneFilled = FIELDS.every((f) => values[f.key].trim().length === 0);
+  const canSave = allFilled || (noneFilled && !!status?.has_credentials);
+  const isClearing = noneFilled && !!status?.has_credentials;
+  const [confirmClear, setConfirmClear] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-muted-foreground">
+        The bot token from <span className="font-medium">@BotFather</span> and the
+        chat id to DM (your user/channel id). Stored encrypted server-side; agents
+        never see them and this panel never displays them again once saved.
+      </p>
+
+      <div className="flex items-center gap-2 rounded-md border p-3">
+        {status?.has_credentials ? (
+          <>
+            <Key className="h-4 w-4 text-green-500" />
+            <span className="text-sm text-green-600 dark:text-green-400">
+              Credentials are set
+            </span>
+          </>
+        ) : (
+          <>
+            <KeyRound className="h-4 w-4 text-amber-500" />
+            <span className="text-sm text-amber-600 dark:text-amber-400">
+              {isLoading ? "Checking..." : "No credentials configured"}
+            </span>
+          </>
+        )}
+      </div>
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+        {FIELDS.map((field) => (
+          <div key={field.key} className="space-y-2">
+            <Label htmlFor={`tg-cred-${field.key}`}>
+              {status?.has_credentials ? `Replace ${field.label}` : field.label}
+            </Label>
+            <Input
+              id={`tg-cred-${field.key}`}
+              type="password"
+              value={values[field.key]}
+              onChange={(e) =>
+                setValues((prev) => ({ ...prev, [field.key]: e.target.value }))
+              }
+              placeholder="••••••••••••"
+            />
+          </div>
+        ))}
+      </div>
+
+      <p className="text-xs text-muted-foreground">
+        Set both to save (or rotate); leave both blank and save to clear.
+      </p>
+
+      <Button
+        onClick={() =>
+          isClearing ? setConfirmClear(true) : saveMutation.mutate()
+        }
+        disabled={saveMutation.isPending || !canSave}
+      >
+        <Save className="mr-2 h-4 w-4" />
+        {saveMutation.isPending ? "Saving..." : "Save"}
+      </Button>
+
+      <AlertDialog
+        open={confirmClear}
+        onOpenChange={(open) => {
+          if (!open) setConfirmClear(false);
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Clear Telegram credentials?</AlertDialogTitle>
+            <AlertDialogDescription>
+              This will clear the stored bot token and chat id. This cannot be
+              undone.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={() => {
+                setConfirmClear(false);
+                saveMutation.mutate();
+              }}
+            >
+              Clear
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}