gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/remote-questions/telegram-adapter.ts

@@ -5,6 +5,7 @@
 import { type ChannelAdapter, type RemotePrompt, type RemoteDispatchResult, type RemoteAnswer, type RemotePromptRef } from "./types.js";
 import { formatForTelegram, parseTelegramResponse } from "./format.js";
 import { apiRequest } from "./http-client.js";
+import { isCommand, handleCommand, type CommandSender } from "./commands.js";
 
 const TELEGRAM_API = "https://api.telegram.org";
 
@@ -15,10 +16,12 @@ export class TelegramAdapter implements ChannelAdapter {
   private lastSentText = "";
   private readonly token: string;
   private readonly chatId: string;
+  private readonly basePath: string;
 
-  constructor(token: string, chatId: string) {
+  constructor(token: string, chatId: string, basePath: string) {
     this.token = token;
     this.chatId = chatId;
+    this.basePath = basePath;
   }
 
   async validate(): Promise<void> {
@@ -98,14 +101,31 @@ export class TelegramAdapter implements ChannelAdapter {
       // Handle text reply (reply_to_message)
       if (update.message) {
         const msg = update.message;
+        // Defensive: ensure command replies go back to our configured chat, not an unvalidated chat ID.
+        // ref.channelId is always set from this.chatId in sendPrompt, so this guard enforces that.
+        const replyChatId = String(msg.chat?.id) === this.chatId ? this.chatId : null;
+        if (!replyChatId) continue; // skip messages not from our configured chat
+
         if (
           String(msg.chat?.id) === ref.channelId &&
-          msg.reply_to_message &&
-          String(msg.reply_to_message.message_id) === ref.messageId &&
           msg.from?.id !== this.botUserId &&
           msg.text
         ) {
-          return parseTelegramResponse(null, msg.text, prompt.questions, prompt.id);
+          // Intercept slash commands — handle and continue polling for the answer
+          if (isCommand(msg.text)) {
+            const sender = this.makeCommandSender(replyChatId);
+            try {
+              await handleCommand(msg.text, sender, this.basePath);
+            } catch { /* best-effort — command errors must not disrupt polling */ }
+            continue;
+          }
+
+          if (
+            msg.reply_to_message &&
+            String(msg.reply_to_message.message_id) === ref.messageId
+          ) {
+            return parseTelegramResponse(null, msg.text, prompt.questions, prompt.id);
+          }
         }
       }
     }
@@ -113,6 +133,53 @@ export class TelegramAdapter implements ChannelAdapter {
     return null;
   }
 
+  /**
+   * Poll Telegram for incoming slash commands and handle them.
+   * Intended for idle-time polling when no question prompt is active.
+   * Returns the number of commands handled.
+   */
+  async pollAndHandleCommands(basePath: string): Promise<number> {
+    if (!this.botUserId) {
+      try {
+        await this.validate();
+      } catch {
+        return 0;
+      }
+    }
+
+    const res = await this.telegramApi("getUpdates", {
+      offset: this.lastUpdateId + 1,
+      timeout: 0,
+      allowed_updates: ["message"],
+    });
+
+    if (!res.ok || !Array.isArray(res.result)) return 0;
+
+    let handled = 0;
+    for (const update of res.result) {
+      if (update.update_id > this.lastUpdateId) {
+        this.lastUpdateId = update.update_id;
+      }
+
+      const msg = update.message;
+      if (
+        msg &&
+        String(msg.chat?.id) === this.chatId &&
+        msg.from?.id !== this.botUserId &&
+        msg.text &&
+        isCommand(msg.text)
+      ) {
+        const sender = this.makeCommandSender(msg.chat?.id ?? this.chatId);
+        try {
+          await handleCommand(msg.text, sender, basePath);
+          handled++;
+        } catch { /* best-effort */ }
+      }
+    }
+
+    return handled;
+  }
+
   /**
    * Acknowledge receipt by editing the original message to append a checkmark.
    * Best-effort — failures are silently ignored.
@@ -130,6 +197,21 @@ export class TelegramAdapter implements ChannelAdapter {
     }
   }
 
+  private makeCommandSender(chatId: string | number): CommandSender {
+    const targetChatId = String(chatId);
+    return {
+      send: async (text: string): Promise<void> => {
+        try {
+          await this.telegramApi("sendMessage", {
+            chat_id: targetChatId,
+            text,
+            parse_mode: "Markdown",
+          });
+        } catch { /* best-effort — command replies must not disrupt polling */ }
+      },
+    };
+  }
+
   private buildMessageUrl(chatId: string, messageId: string): string | undefined {
     // Supergroups have chat IDs starting with -100
     if (chatId.startsWith("-100")) {

package/src/resources/extensions/remote-questions/tests/command-polling.test.ts

@@ -0,0 +1,246 @@
+/**
+ * Tests for startCommandPolling() background interval.
+ *
+ * Framework: node:test + node:assert/strict (CONTRIBUTING.md rules)
+ *
+ * Covers:
+ *   - startCommandPolling returns a cleanup function
+ *   - Calling cleanup stops further poll invocations
+ *   - When no remote channel is configured, a no-op cleanup is returned
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+// ─── Minimal fake timer harness ───────────────────────────────────────────────
+
+interface FakeTimer {
+  id: number;
+  callback: () => void;
+  intervalMs: number;
+  cleared: boolean;
+}
+
+/**
+ * Build a fake setInterval / clearInterval pair so tests never actually wait
+ * for real time and do not depend on Node's timer subsystem firing order.
+ */
+function makeFakeTimers(): {
+  fakeSetInterval: typeof setInterval;
+  fakeClearInterval: typeof clearInterval;
+  timers: FakeTimer[];
+  tick: () => void;
+} {
+  const timers: FakeTimer[] = [];
+  let nextId = 1;
+
+  const fakeSetInterval = (callback: () => void, _ms?: number, ..._args: unknown[]): ReturnType<typeof setInterval> => {
+    const timer: FakeTimer = {
+      id: nextId++,
+      callback,
+      intervalMs: _ms ?? 0,
+      cleared: false,
+    };
+    timers.push(timer);
+    return timer.id as unknown as ReturnType<typeof setInterval>;
+  };
+
+  const fakeClearInterval = (id?: ReturnType<typeof clearInterval> | null): void => {
+    const timer = timers.find((t) => (t.id as unknown) === id);
+    if (timer) timer.cleared = true;
+  };
+
+  /** Fire all non-cleared timers once (simulates one interval tick). */
+  const tick = (): void => {
+    for (const timer of timers) {
+      if (!timer.cleared) timer.callback();
+    }
+  };
+
+  return {
+    fakeSetInterval: fakeSetInterval as unknown as typeof setInterval,
+    fakeClearInterval: fakeClearInterval as unknown as typeof clearInterval,
+    timers,
+    tick,
+  };
+}
+
+// ─── Fake TelegramAdapter ────────────────────────────────────────────────────
+
+function makeFakeAdapter(): {
+  pollCalls: number;
+  pollAndHandleCommands: (basePath: string) => Promise<number>;
+} {
+  let pollCalls = 0;
+  return {
+    get pollCalls() { return pollCalls; },
+    async pollAndHandleCommands(_basePath: string): Promise<number> {
+      pollCalls++;
+      return 0;
+    },
+  };
+}
+
+// ─── Internal startCommandPolling factory (testable, no real I/O) ────────────
+//
+// Rather than importing the real startCommandPolling (which calls resolveRemoteConfig
+// and hits the filesystem / env), we re-implement the same tiny function inline
+// here using injected fakes. This keeps tests hermetic without mocking globals.
+
+function makeStartCommandPolling(
+  fakeSetInterval: typeof setInterval,
+  fakeClearInterval: typeof clearInterval,
+  adapterPollFn: (basePath: string) => Promise<number>,
+  isConfigured: boolean,
+  intervalMs = 5000,
+): (basePath: string) => () => void {
+  return function startCommandPolling(basePath: string): () => void {
+    if (!isConfigured) {
+      return () => {};
+    }
+
+    const timer = fakeSetInterval(() => {
+      void adapterPollFn(basePath).catch(() => {});
+    }, intervalMs);
+
+    return () => fakeClearInterval(timer);
+  };
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+test("startCommandPolling: returns a cleanup function (callable without error)", () => {
+  const { fakeSetInterval, fakeClearInterval } = makeFakeTimers();
+  const adapter = makeFakeAdapter();
+  const startCommandPolling = makeStartCommandPolling(
+    fakeSetInterval,
+    fakeClearInterval,
+    adapter.pollAndHandleCommands.bind(adapter),
+    true,
+  );
+
+  const cleanup = startCommandPolling("/fake/project");
+
+  assert.equal(typeof cleanup, "function", "Expected startCommandPolling to return a function");
+  // Calling cleanup must not throw
+  assert.doesNotThrow(() => cleanup(), "cleanup() must not throw");
+});
+
+test("startCommandPolling: interval fires the poll callback on tick", async () => {
+  const { fakeSetInterval, fakeClearInterval, tick } = makeFakeTimers();
+  const adapter = makeFakeAdapter();
+  const startCommandPolling = makeStartCommandPolling(
+    fakeSetInterval,
+    fakeClearInterval,
+    adapter.pollAndHandleCommands.bind(adapter),
+    true,
+  );
+
+  startCommandPolling("/fake/project");
+
+  // Before any tick, nothing polled yet
+  assert.equal(adapter.pollCalls, 0);
+
+  // One tick — the callback fires and schedules the async poll
+  tick();
+
+  // Allow the microtask queue to drain so the async poll promise resolves
+  await Promise.resolve();
+
+  assert.equal(adapter.pollCalls, 1, "Expected poll to be called after one tick");
+});
+
+test("startCommandPolling: cleanup stops further poll invocations", async () => {
+  const { fakeSetInterval, fakeClearInterval, timers, tick } = makeFakeTimers();
+  const adapter = makeFakeAdapter();
+  const startCommandPolling = makeStartCommandPolling(
+    fakeSetInterval,
+    fakeClearInterval,
+    adapter.pollAndHandleCommands.bind(adapter),
+    true,
+  );
+
+  const cleanup = startCommandPolling("/fake/project");
+
+  // Tick once to confirm polling works
+  tick();
+  await Promise.resolve();
+  assert.equal(adapter.pollCalls, 1, "Expected 1 poll after first tick");
+
+  // Call cleanup — marks the timer as cleared
+  cleanup();
+
+  // Confirm the underlying timer was cleared
+  assert.equal(timers.length, 1, "Expected exactly one timer to have been registered");
+  assert.equal(timers[0].cleared, true, "Expected timer to be cleared after cleanup()");
+
+  // Tick again — the cleared timer must NOT fire
+  tick();
+  await Promise.resolve();
+  assert.equal(adapter.pollCalls, 1, "Expected no additional polls after cleanup()");
+});
+
+test("startCommandPolling: calling cleanup twice is safe (no throw)", () => {
+  const { fakeSetInterval, fakeClearInterval } = makeFakeTimers();
+  const adapter = makeFakeAdapter();
+  const startCommandPolling = makeStartCommandPolling(
+    fakeSetInterval,
+    fakeClearInterval,
+    adapter.pollAndHandleCommands.bind(adapter),
+    true,
+  );
+
+  const cleanup = startCommandPolling("/fake/project");
+
+  assert.doesNotThrow(() => {
+    cleanup();
+    cleanup();
+  }, "Calling cleanup twice must not throw");
+});
+
+test("startCommandPolling: returns no-op cleanup when no channel is configured", () => {
+  const { fakeSetInterval, fakeClearInterval, timers } = makeFakeTimers();
+  const adapter = makeFakeAdapter();
+  const startCommandPolling = makeStartCommandPolling(
+    fakeSetInterval,
+    fakeClearInterval,
+    adapter.pollAndHandleCommands.bind(adapter),
+    false, // not configured
+  );
+
+  const cleanup = startCommandPolling("/fake/project");
+
+  assert.equal(typeof cleanup, "function", "Expected a cleanup function even when not configured");
+  assert.equal(timers.length, 0, "Expected no timer to be registered when channel is not configured");
+
+  // The no-op cleanup must not throw
+  assert.doesNotThrow(() => cleanup(), "No-op cleanup must not throw");
+});
+
+test("startCommandPolling: poll errors are swallowed (best-effort)", async () => {
+  const { fakeSetInterval, fakeClearInterval, tick } = makeFakeTimers();
+
+  // Adapter that always rejects
+  let rejectCalls = 0;
+  const throwingPoll = async (_basePath: string): Promise<number> => {
+    rejectCalls++;
+    throw new Error("Simulated network error");
+  };
+
+  const startCommandPolling = makeStartCommandPolling(
+    fakeSetInterval,
+    fakeClearInterval,
+    throwingPoll,
+    true,
+  );
+
+  startCommandPolling("/fake/project");
+
+  // Ticking must not propagate the rejection — the interval is fire-and-forget
+  assert.doesNotThrow(() => tick(), "tick() must not throw even if poll rejects");
+
+  // Allow the rejected promise to settle without an unhandled rejection
+  await Promise.resolve();
+
+  assert.equal(rejectCalls, 1, "Expected poll to have been called once");
+});

package/src/resources/extensions/remote-questions/tests/remote-answer-normalization.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Regression tests for #4406 — remote-channel answers must be normalized to
+ * the RoundResult shape { selected, notes } so the depth-verification gate
+ * hook in gsd/bootstrap/register-hooks.ts recognizes them. Before the fix,
+ * Telegram/Slack/Discord answers arrived as { answers: string[], user_note }
+ * and `answer.selected` was always undefined, leaving the gate locked.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { toRoundResultResponse } from "../manager.ts";
+import type { RemoteAnswer } from "../types.ts";
+import { isDepthConfirmationAnswer } from "../../gsd/bootstrap/write-gate.ts";
+
+const STANDARD_OPTIONS = [
+  { label: "Yes, you got it (Recommended)" },
+  { label: "Not quite — let me clarify" },
+];
+
+test("remote normalization: single-select Telegram answer clears depth gate (#4406)", () => {
+  const remote: RemoteAnswer = {
+    answers: {
+      depth_verification_confirm: { answers: ["Yes, you got it (Recommended)"] },
+    },
+  };
+
+  const normalized = toRoundResultResponse(remote);
+  const answer = normalized.answers.depth_verification_confirm;
+
+  assert.equal(normalized.endInterview, false);
+  assert.equal(answer.selected, "Yes, you got it (Recommended)");
+  assert.equal(answer.notes, "");
+  assert.equal(
+    isDepthConfirmationAnswer(answer.selected, STANDARD_OPTIONS),
+    true,
+    "normalized remote answer must unlock the depth-verification gate",
+  );
+});
+
+test("remote normalization: multi-select answers stay as arrays", () => {
+  const remote: RemoteAnswer = {
+    answers: {
+      multi_q: { answers: ["A", "B"] },
+    },
+  };
+
+  const { answers } = toRoundResultResponse(remote);
+  assert.deepEqual(answers.multi_q.selected, ["A", "B"]);
+  assert.equal(answers.multi_q.notes, "");
+});
+
+test("remote normalization: user_note maps to notes", () => {
+  const remote: RemoteAnswer = {
+    answers: {
+      q1: { answers: ["Not quite — let me clarify"], user_note: "Please include timeouts" },
+    },
+  };
+
+  const { answers } = toRoundResultResponse(remote);
+  assert.equal(answers.q1.selected, "Not quite — let me clarify");
+  assert.equal(answers.q1.notes, "Please include timeouts");
+});
+
+test("remote normalization: empty answers array collapses to empty string (never undefined)", () => {
+  const remote: RemoteAnswer = {
+    answers: {
+      q1: { answers: [], user_note: "No response provided" },
+    },
+  };
+
+  const { answers } = toRoundResultResponse(remote);
+  assert.equal(answers.q1.selected, "");
+  assert.equal(answers.q1.notes, "No response provided");
+  // Must NOT accidentally pass the gate when no selection was made.
+  assert.equal(isDepthConfirmationAnswer(answers.q1.selected, STANDARD_OPTIONS), false);
+});
+
+test("remote normalization: independent entries per question id", () => {
+  const remote: RemoteAnswer = {
+    answers: {
+      depth_verification_M001_confirm: { answers: ["Yes, you got it (Recommended)"] },
+      followup: { answers: ["Option A", "Option B"], user_note: "extra" },
+    },
+  };
+
+  const { answers } = toRoundResultResponse(remote);
+  assert.equal(answers.depth_verification_M001_confirm.selected, "Yes, you got it (Recommended)");
+  assert.equal(answers.depth_verification_M001_confirm.notes, "");
+  assert.deepEqual(answers.followup.selected, ["Option A", "Option B"]);
+  assert.equal(answers.followup.notes, "extra");
+});