switchroom 0.21.7 → 0.21.9

package/telegram-plugin/tests/grammy-rich-message-types.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Compile-time contract for the grammy 1.44.0 → 1.45.1 bump
+ * (`@grammyjs/types` 3.28.0 → 4.0.0).
+ *
+ * Why this file exists
+ * --------------------
+ * 4.0.0 turned `InputRichMessage` from a plain interface into a GENERIC one:
+ *
+ *   3.28.0  `export interface InputRichMessage {`            (rich.d.ts:280)
+ *   4.0.0   `export interface InputRichMessage<F> {`         (rich.d.ts:283)
+ *
+ * `F` is the file-payload type threaded through the new Bot API 10.2 `blocks`
+ * / `media` fields. Switchroom never uses either — every outbound message is
+ * the plain `{ markdown }` shape (`rich-send.ts:96`), and the plugin defines
+ * its OWN local `InputRichMessageMarkdown` (`rich-send.ts:28`) rather than
+ * importing grammy's. So the bump is only safe as long as a bare
+ * `{ markdown: string }` literal still satisfies the generic parameter at
+ * every call site.
+ *
+ * That invariant is invisible to the rest of the suite for two reasons, and
+ * both are why this test spends ~1s on a real compile instead of asserting on
+ * runtime values:
+ *
+ *   1. Every send in the regression suite is MOCKED — no mock can notice that
+ *      a payload stopped typechecking.
+ *   2. The repo's `tsc --noEmit` does NOT cover this directory. The root
+ *      `tsconfig.json` `include` is `["src/**\/*.ts", "bin/**\/*.ts",
+ *      "scripts/**\/*.ts"]` — `telegram-plugin/` is absent, so a type error
+ *      here is invisible to `npm run lint` (verified empirically: a deliberate
+ *      `const x: number = "s"` in `rich-send.ts` leaves `tsc --noEmit` at exit
+ *      0). A plain `.ts` fixture would therefore be a NO-OP as a guard.
+ *
+ * So the check has to run the compiler itself. The negative controls below are
+ * load-bearing: if the harness ever silently stopped compiling (bad fixture
+ * path, unresolved `grammy`, swallowed diagnostics), the "must fail" cases
+ * would go green and this file goes red — it cannot rot into a vacuous pass.
+ */
+import { describe, it, expect, afterAll } from 'vitest'
+import ts from 'typescript'
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// Fixtures must live INSIDE the repo tree: they `import 'grammy'`, and module
+// resolution walks up from the file to the hoisted root `node_modules`. A
+// fixture in `os.tmpdir()` would fail to resolve grammy and every case would
+// report a misleading "cannot find module" instead of the real answer.
+const fixtureDir = mkdtempSync(join(here, 'grammy-types-fixture-'))
+afterAll(() => rmSync(fixtureDir, { recursive: true, force: true }))
+
+/** Mirrors the compiler settings the plugin is actually authored against. */
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  strict: true,
+  // Matches the root tsconfig: we are asserting on OUR call shapes, not
+  // auditing grammy's own .d.ts files.
+  skipLibCheck: true,
+  noEmit: true,
+}
+
+/**
+ * Typecheck one fixture source and return its syntactic + semantic errors,
+ * formatted `TSxxxx: message`. Empty array means "compiles clean".
+ */
+function typecheck(name: string, source: string): string[] {
+  const file = resolve(fixtureDir, `${name}.ts`)
+  writeFileSync(file, source)
+  const program = ts.createProgram([file], COMPILER_OPTIONS)
+  return ts
+    .getPreEmitDiagnostics(program)
+    .filter((d) => d.file?.fileName === file.split('\\').join('/'))
+    .map((d) => `TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`)
+}
+
+describe('grammy rich-message input still accepts the plain { markdown } shape', () => {
+  it('accepts a bare { markdown } literal on sendRichMessage and editMessageText', () => {
+    expect(
+      typecheck(
+        'plain-literal',
+        `
+        import type { Bot } from 'grammy'
+        declare const bot: Bot
+        export async function send(): Promise<void> {
+          await bot.api.sendRichMessage(1, { markdown: 'hi' })
+          await bot.api.editMessageText(1, 2, { markdown: 'hi' })
+        }
+        `,
+      ),
+    ).toEqual([])
+  })
+
+  it("accepts the production helper's return type (rich-send.ts richMessage())", () => {
+    // The real seam: `richMessage()` returns the plugin's OWN local
+    // `InputRichMessageMarkdown`, which must stay structurally assignable to
+    // grammy's generic parameter. This is the assertion that would break if a
+    // future @grammyjs/types made `blocks`/`media` mandatory or constrained `F`.
+    expect(
+      typecheck(
+        'production-helper',
+        `
+        import type { Bot } from 'grammy'
+        import { richMessage } from '${join(here, '..', 'rich-send.js').split('\\').join('/')}'
+        declare const bot: Bot
+        export async function send(): Promise<void> {
+          await bot.api.sendRichMessage(1, richMessage('hi'))
+          await bot.api.editMessageText(1, 2, richMessage('hi'))
+        }
+        `,
+      ),
+    ).toEqual([])
+  })
+
+  it('still accepts a { markdown } payload through bot.api.raw', () => {
+    // `installRichMarkdownGuard` (shared/bot-runtime.ts) inspects the RAW
+    // payload `{ chat_id, rich_message: { markdown } }`, so pin that shape too.
+    expect(
+      typecheck(
+        'raw-payload',
+        `
+        import type { Bot } from 'grammy'
+        declare const bot: Bot
+        export async function send(): Promise<void> {
+          await bot.api.raw.sendRichMessage({ chat_id: 1, rich_message: { markdown: 'hi' } })
+        }
+        `,
+      ),
+    ).toEqual([])
+  })
+
+  // ── Negative controls: prove the harness has teeth ──────────────────────
+  // Without these, every assertion above would pass just as happily against a
+  // harness that had silently stopped compiling anything at all.
+
+  it('NEGATIVE CONTROL: rejects a wrongly-typed markdown field', () => {
+    const errors = typecheck(
+      'wrong-type',
+      `
+      import type { Bot } from 'grammy'
+      declare const bot: Bot
+      export async function send(): Promise<void> {
+        await bot.api.sendRichMessage(1, { markdown: 123 })
+      }
+      `,
+    )
+    expect(errors.join('\n')).toContain('TS2322')
+  })
+
+  it('NEGATIVE CONTROL: rejects an unknown field on the rich-message literal', () => {
+    const errors = typecheck(
+      'unknown-field',
+      `
+      import type { Bot } from 'grammy'
+      declare const bot: Bot
+      export async function send(): Promise<void> {
+        await bot.api.sendRichMessage(1, { markdwon: 'typo' })
+      }
+      `,
+    )
+    expect(errors.length).toBeGreaterThan(0)
+  })
+})
+
+describe('grammy supply-chain pin', () => {
+  // Assert on `bun.lock` rather than the resolved package: grammy's `exports`
+  // map deliberately hides `./package.json`, and the lockfile is the artifact
+  // CI actually installs from (`bun install --frozen-lockfile`), so it is both
+  // reachable and the more honest source of truth for what ships.
+  const lock = readFileSync(resolve(here, '..', '..', 'bun.lock'), 'utf8')
+
+  /** Pull the resolved version bun.lock pins for a package. */
+  function lockedVersion(pkg: string): string {
+    const escaped = pkg.replace('/', '\\/')
+    const m = new RegExp(`"${escaped}": \\["${escaped}@(\\d+\\.\\d+\\.\\d+)"`).exec(lock)
+    if (!m) throw new Error(`no bun.lock pin found for ${pkg}`)
+    return m[1]
+  }
+
+  // These assert a FLOOR, not an exact version: a later 1.46/5.x bump is a
+  // legitimate change and must not go red here for no substantive reason. What
+  // must never happen silently is a slide BACK below the floor — that would
+  // return @grammyjs/types to 3.28.0 and drop the Bot API 10.2 surface this
+  // bump exists to unlock, while every assertion above stayed green (the plain
+  // `{ markdown }` shape compiles under both).
+
+  it('keeps grammy at or above 1.45 (the floor that ships @grammyjs/types 4.x)', () => {
+    const [major, minor] = lockedVersion('grammy').split('.').map(Number)
+    expect(major).toBe(1)
+    expect(minor).toBeGreaterThanOrEqual(45)
+  })
+
+  it('keeps @grammyjs/types at or above the 4.x major grammy 1.45 depends on', () => {
+    const [major] = lockedVersion('@grammyjs/types').split('.').map(Number)
+    expect(major).toBeGreaterThanOrEqual(4)
+  })
+})

package/telegram-plugin/tests/hermes-messages-paging.test.ts

@@ -0,0 +1,149 @@
+/**
+ * `GET /api/sessions/:id/messages` — ordering and pagination, against a REAL
+ * turns DB.
+ *
+ * Separate from `hermes-rest-parity.test.ts` for one reason: that fixture
+ * points `SWITCHROOM_AGENTS_DIR` at an empty tmpdir, so every session has zero
+ * messages and an assertion about ORDER or about which slice came back passes
+ * vacuously there. Ordering and offset windowing are exactly the properties
+ * that need real rows, and the turns DB is `bun:sqlite` — hence a bun test
+ * (vitest excludes it; see vitest.config.ts). It lives under
+ * telegram-plugin/tests/ rather than beside the adapter because that is the only
+ * tree the bun CI job walks — `bun test` runs with cwd telegram-plugin/, so a
+ * root-level src/ bun test is executed by NEITHER runner
+ * (scripts/check-test-runner-coverage.mjs, and the debt list it guards).
+ *
+ * Upstream contract being asserted (`hermes_cli/web_routers/sessions.py:601-651`
+ * at 9da6d455c9e1f2bf74bb9f47766ee9fc52e17bfb):
+ *   - messages come back CHRONOLOGICAL within the page;
+ *   - `order=oldest` windows from the start, `order=latest` from the end;
+ *   - `pagination.returned` is the real row count of that window.
+ *
+ * The bug each case guards, stated so a future edit cannot weaken it into a
+ * code-path check: the adapter read `listTurnsForAgent` (newest-first) and
+ * projected it without reversing, so the transcript arrived backwards; and it
+ * emitted no `pagination`, which `getAllSessionMessages` (hermes.ts:713-750)
+ * reads as "legacy backend, that was everything" and stops paging on.
+ */
+
+import { test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openTurnsDb } from "../registry/turns-schema.js";
+import { handleHermesRest, type HermesRestResult } from "../../src/web/hermes-adapter.js";
+import type { SwitchroomConfig } from "../../src/config/schema.js";
+
+const AGENT = "alpha";
+let agentsDir = "";
+
+const CONFIG = { agents: { [AGENT]: {} } } as unknown as SwitchroomConfig;
+
+/** Seed `n` completed turns with explicit, strictly-increasing start times. */
+function seedTurns(n: number) {
+  const dir = join(agentsDir, AGENT);
+  mkdirSync(dir, { recursive: true });
+  const db = openTurnsDb(dir);
+  try {
+    for (let i = 0; i < n; i++) {
+      const ts = 1_700_000_000_000 + i * 1000;
+      db.prepare(
+        `INSERT INTO turns
+           (turn_key, chat_id, thread_id, started_at, ended_at, ended_via,
+            user_prompt_preview, assistant_reply_preview, created_at, updated_at)
+         VALUES (?, ?, NULL, ?, ?, 'stop', ?, ?, ?, ?)`,
+      ).run(`t${i}`, "chat", ts, ts + 500, `u${i}`, `a${i}`, ts, ts);
+    }
+  } finally {
+    db.close();
+  }
+}
+
+async function messages(search: string): Promise<Record<string, unknown>> {
+  const res = (await handleHermesRest(
+    "GET",
+    `/api/sessions/${AGENT}/messages`,
+    CONFIG,
+    search,
+  )) as HermesRestResult;
+  expect(res).not.toBeNull();
+  expect(res.status).toBe(200);
+  return res.body as Record<string, unknown>;
+}
+
+function contents(body: Record<string, unknown>): string[] {
+  return (body.messages as { content: string }[]).map((m) => m.content);
+}
+
+beforeEach(() => {
+  agentsDir = mkdtempSync(join(tmpdir(), "sr-hermes-msgs-"));
+  process.env.SWITCHROOM_AGENTS_DIR = agentsDir;
+});
+
+afterEach(() => {
+  rmSync(agentsDir, { recursive: true, force: true });
+});
+
+test("messages are chronological, not the newest-first order the turns DB reads in", async () => {
+  seedTurns(3);
+  const body = await messages("?limit=500&offset=0&order=oldest");
+  // u0/a0 is the OLDEST turn. Before the fix this list started at u2.
+  expect(contents(body)).toEqual(["u0", "a0", "u1", "a1", "u2", "a2"]);
+});
+
+test("order=oldest windows from the start and reports what it returned", async () => {
+  seedTurns(3);
+  const body = await messages("?limit=2&offset=2&order=oldest");
+  expect(contents(body)).toEqual(["u1", "a1"]);
+  expect(body.pagination).toEqual({ limit: 2, offset: 2, order: "oldest", returned: 2 });
+});
+
+test("order=latest windows from the END, still chronological inside the page", async () => {
+  seedTurns(3);
+  const body = await messages("?limit=3&order=latest");
+  expect(contents(body)).toEqual(["a1", "u2", "a2"]);
+  expect(body.pagination).toEqual({ limit: 3, offset: 0, order: "latest", returned: 3 });
+});
+
+test("paging with the desktop's own loop terminates having read every message once", async () => {
+  seedTurns(5); // 10 messages
+  // getAllSessionMessages (hermes.ts:713-750): limit=500, order=oldest, advance
+  // offset by the page length, stop when the page is short of `limit`.
+  const seen: string[] = [];
+  let offset = 0;
+  for (let guard = 0; guard < 10; guard++) {
+    const page = await messages(`?limit=4&offset=${offset}&order=oldest`);
+    const pagination = page.pagination as { limit: number };
+    seen.push(...contents(page));
+    if (contents(page).length === 0 || contents(page).length < pagination.limit) break;
+    offset += contents(page).length;
+  }
+  expect(seen).toEqual(["u0", "a0", "u1", "a1", "u2", "a2", "u3", "a3", "u4", "a4"]);
+});
+
+test("an omitted limit defaults to the latest 500, an explicit one defaults to oldest", async () => {
+  seedTurns(1);
+  expect((await messages("")).pagination).toEqual({
+    limit: 500,
+    offset: 0,
+    order: "latest",
+    returned: 2,
+  });
+  expect((await messages("?limit=10")).pagination).toEqual({
+    limit: 10,
+    offset: 0,
+    order: "oldest",
+    returned: 2,
+  });
+});
+
+test("an unrecognised order is a 400, not a silently-reinterpreted page", async () => {
+  seedTurns(1);
+  const res = await handleHermesRest(
+    "GET",
+    `/api/sessions/${AGENT}/messages`,
+    CONFIG,
+    "?order=sideways",
+  );
+  expect(res?.status).toBe(400);
+});

package/telegram-plugin/tests/hermes-session-search.test.ts

@@ -0,0 +1,146 @@
+/**
+ * `GET /api/sessions/search` — that it actually SEARCHES.
+ *
+ * `hermes-rest-parity.test.ts` can only assert the contract floor here
+ * (`Array.isArray(results)`), because it points `SWITCHROOM_AGENTS_DIR` at an
+ * empty tmpdir: with no turns anywhere, "found the right rows", "found nothing
+ * for a miss" and "hardcoded `{results: []}`" are indistinguishable. A
+ * hardcoded empty list would pass that floor forever, and an always-200 empty
+ * body is the exact bug class the desktop cannot detect —
+ * `isEndpointMissingError` only matches 404s.
+ *
+ * So this file seeds a real turns registry (`bun:sqlite`, hence a bun test —
+ * vitest excludes it; it lives under telegram-plugin/tests/ because that is the
+ * only tree the bun CI job walks) and asserts the discriminating outcomes:
+ * a query that should hit, hits; a query that should miss, misses.
+ */
+
+import { test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openTurnsDb } from "../registry/turns-schema.js";
+import { handleHermesRest, type HermesRestResult } from "../../src/web/hermes-adapter.js";
+import type { SwitchroomConfig } from "../../src/config/schema.js";
+
+const CONFIG = {
+  agents: { alpha: { model: "sonnet" }, beta: {} },
+} as unknown as SwitchroomConfig;
+
+let agentsDir = "";
+
+function seed(agent: string, rows: { user: string; assistant: string }[]) {
+  const dir = join(agentsDir, agent);
+  mkdirSync(dir, { recursive: true });
+  const db = openTurnsDb(dir);
+  try {
+    rows.forEach((r, i) => {
+      const ts = 1_700_000_000_000 + i * 1000;
+      db.prepare(
+        `INSERT INTO turns
+           (turn_key, chat_id, thread_id, started_at, ended_at, ended_via,
+            user_prompt_preview, assistant_reply_preview, created_at, updated_at)
+         VALUES (?, ?, NULL, ?, ?, 'stop', ?, ?, ?, ?)`,
+      ).run(`${agent}-t${i}`, "chat", ts, ts + 500, r.user, r.assistant, ts, ts);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+type Result = {
+  session_id: string;
+  lineage_root: string;
+  snippet: string;
+  role: string | null;
+  source: string | null;
+  model: string | null;
+  session_started: number | null;
+};
+
+async function search(query: string): Promise<Result[]> {
+  const res = (await handleHermesRest(
+    "GET",
+    "/api/sessions/search",
+    CONFIG,
+    query,
+  )) as HermesRestResult;
+  expect(res).not.toBeNull();
+  // The pre-fix behaviour: the /api/sessions/:id regex matched "search" as an
+  // id and answered 404 {error:'Unknown session'}, which threw the panel.
+  expect(res.status).toBe(200);
+  return (res.body as { results: Result[] }).results;
+}
+
+beforeEach(() => {
+  agentsDir = mkdtempSync(join(tmpdir(), "sr-hermes-search-"));
+  process.env.SWITCHROOM_AGENTS_DIR = agentsDir;
+});
+
+afterEach(() => {
+  rmSync(agentsDir, { recursive: true, force: true });
+});
+
+test("a session-id match comes back, with role null and the id as its own lineage root", async () => {
+  const results = await search("?q=alph");
+  expect(results.map((r) => r.session_id)).toEqual(["alpha"]);
+  expect(results[0].role).toBeNull();
+  expect(results[0].lineage_root).toBe("alpha");
+});
+
+test("a message-content match comes back tagged with the role it matched on", async () => {
+  seed("alpha", [{ user: "deploy the gateway", assistant: "done" }]);
+  seed("beta", [{ user: "unrelated", assistant: "also unrelated" }]);
+
+  const onUser = await search("?q=deploy");
+  expect(onUser.map((r) => r.session_id)).toEqual(["alpha"]);
+  expect(onUser[0].role).toBe("user");
+  expect(onUser[0].snippet).toBe("deploy the gateway");
+
+  const onAssistant = await search("?q=also%20unrelated");
+  expect(onAssistant.map((r) => r.session_id)).toEqual(["beta"]);
+  expect(onAssistant[0].role).toBe("assistant");
+  expect(onAssistant[0].snippet).toBe("also unrelated");
+});
+
+test("a query that matches nothing returns nothing — not the whole fleet", async () => {
+  seed("alpha", [{ user: "deploy the gateway", assistant: "done" }]);
+  // The discriminating case: a stub returning every session, and a stub
+  // returning none, are told apart only by running both this and the hit above.
+  expect(await search("?q=zzz-no-such-token")).toEqual([]);
+});
+
+test("an empty or whitespace query is short-circuited, not treated as match-everything", async () => {
+  seed("alpha", [{ user: "deploy", assistant: "done" }]);
+  expect(await search("?q=")).toEqual([]);
+  expect(await search("?q=%20%20")).toEqual([]);
+  expect(await search("")).toEqual([]);
+});
+
+test("one row per session even when several turns match", async () => {
+  seed("alpha", [
+    { user: "deploy one", assistant: "ok" },
+    { user: "deploy two", assistant: "ok" },
+    { user: "deploy three", assistant: "ok" },
+  ]);
+  const results = await search("?q=deploy");
+  expect(results.length).toBe(1);
+  expect(results[0].session_id).toBe("alpha");
+});
+
+test("?limit= caps the result set", async () => {
+  seed("alpha", [{ user: "shared token", assistant: "ok" }]);
+  seed("beta", [{ user: "shared token", assistant: "ok" }]);
+  expect((await search("?q=shared&limit=1")).length).toBe(1);
+  expect((await search("?q=shared")).length).toBe(2);
+});
+
+test("id matches are ordered ahead of content matches", async () => {
+  // beta matches by id; alpha only by content. Upstream surfaces direct
+  // session-id hits first (sessions.py:169-383) and the panel relies on it.
+  seed("alpha", [{ user: "beta is mentioned here", assistant: "ok" }]);
+  const results = await search("?q=beta");
+  expect(results.map((r) => r.session_id)).toEqual(["beta", "alpha"]);
+  expect(results[0].role).toBeNull();
+  expect(results[1].role).toBe("user");
+});