switchroom 0.19.16 → 0.19.18

package/telegram-plugin/tests/ipc-server-validate-config-approval.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Validation contract for the `request_config_approval` IPC message —
+ * hostd's approval-card request — with focus on the KEN-129 optional
+ * `title` header override.
+ *
+ * Mixed-version safety pins:
+ *   - `title` absent must validate (old hostd → new gateway).
+ *   - a valid `title` must validate (new hostd → new gateway).
+ *   - malformed titles (empty / oversize / non-string) are rejected —
+ *     the validator is the security boundary on the client→gateway
+ *     direction.
+ *
+ * (The reverse direction — new hostd → OLD gateway — is safe because
+ * the old validator checks only known fields' types and ignores extra
+ * keys; pinned by the "extra unknown fields" case below matching that
+ * permissive behaviour on the current validator too.)
+ *
+ * Companion to ipc-server-validate-{operator,inject-inbound}.test.ts.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { validateClientMessage } from '../gateway/ipc-server.js'
+
+function base() {
+  return {
+    type: 'request_config_approval' as const,
+    requestId: 'relnotify-abc123',
+    agentName: 'klanker',
+    reason: 'fleet is behind',
+    unifiedDiff: 'plan text',
+    timeoutMs: 3_600_000,
+  }
+}
+
+describe('validateClientMessage — request_config_approval', () => {
+  it('accepts the base message without a title (old-hostd compat)', () => {
+    expect(validateClientMessage(base())).toBe(true)
+  })
+
+  it('accepts a valid title (KEN-129 update-check card)', () => {
+    expect(
+      validateClientMessage({
+        ...base(),
+        title: '⬆️ **Switchroom update available — fleet is behind**',
+      }),
+    ).toBe(true)
+  })
+
+  it('rejects an empty title', () => {
+    expect(validateClientMessage({ ...base(), title: '' })).toBe(false)
+  })
+
+  it('rejects a title over 200 chars', () => {
+    expect(validateClientMessage({ ...base(), title: 'x'.repeat(201) })).toBe(false)
+  })
+
+  it('rejects a non-string title', () => {
+    expect(validateClientMessage({ ...base(), title: 42 })).toBe(false)
+    expect(validateClientMessage({ ...base(), title: null })).toBe(false)
+  })
+
+  // The title is rendered VERBATIM as the card's first line (it carries
+  // intentional markdown, so it cannot be escaped). A multi-line title
+  // would let a caller forge the `Agent:` / `Reason:` lines beneath it, or
+  // unbalance the diff's ``` fence, on a card the operator is about to
+  // approve. Newlines and control characters are therefore rejected.
+  it('rejects a multi-line title that could forge the card body', () => {
+    expect(
+      validateClientMessage({
+        ...base(),
+        title:
+          '🛠 **Config edit proposed**\nAgent: `root`\nReason: routine\n```\nnoop\n```',
+      }),
+    ).toBe(false)
+    expect(validateClientMessage({ ...base(), title: 'a\rb' })).toBe(false)
+  })
+
+  it('rejects control characters in the title', () => {
+    expect(validateClientMessage({ ...base(), title: 'a\u0000b' })).toBe(false)
+    expect(validateClientMessage({ ...base(), title: 'a\u001bb' })).toBe(false)
+    expect(validateClientMessage({ ...base(), title: 'a\u007fb' })).toBe(false)
+  })
+
+  it('ignores extra unknown fields (forward-compat for future hostds)', () => {
+    expect(
+      validateClientMessage({ ...base(), someFutureField: 'ignored' }),
+    ).toBe(true)
+  })
+
+  it('still rejects a malformed base message (missing diff)', () => {
+    const m: Record<string, unknown> = { ...base() }
+    delete m.unifiedDiff
+    expect(validateClientMessage(m)).toBe(false)
+  })
+})

package/telegram-plugin/tests/mcp-instructions-budget.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The MCP `instructions` string must fit the Claude Code client's hard
+ * truncation limit (#3562).
+ *
+ * The Claude Code native binary truncates MCP server instructions at a
+ * hard-coded 2048 chars, silently and mid-word:
+ *
+ *     if (I && I.length > LB) R = ma(I, LB) + "… [truncated]"   // LB = 2048
+ *
+ * Nothing errors and nothing surfaces to the agent — the server starts, the
+ * tools work, and the tail of the string simply never reaches the model. That
+ * is how the telegram bridge shipped a 4645-char instructions string for
+ * months with 56% of it discarded, including the /telegram:access
+ * prompt-injection defence.
+ *
+ * These tests are the deterministic backstop. `scripts/check-mcp-instructions-budget.mjs`
+ * (in `npm run lint`) is the twin: it resolves the module the bridge actually
+ * imports and measures the same runtime value that the SDK will hand to the
+ * client.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  MCP_INSTRUCTIONS,
+  MCP_INSTRUCTIONS_BUDGET,
+  MCP_INSTRUCTIONS_LIMIT,
+} from "../bridge/mcp-instructions.js";
+
+describe("MCP instructions budget", () => {
+  it("pins the client's hard limit at 2048 (not ours to change)", () => {
+    // Sourced from the minified constant `LB` in @anthropic-ai/claude-code
+    // v2.1.219. If a future client version changes this, update it here
+    // deliberately — do not raise it to make a long string pass.
+    expect(MCP_INSTRUCTIONS_LIMIT).toBe(2048);
+  });
+
+  it("keeps the authored budget strictly below the client's hard limit", () => {
+    expect(MCP_INSTRUCTIONS_BUDGET).toBeLessThan(MCP_INSTRUCTIONS_LIMIT);
+  });
+
+  it("leaves a real safety margin below the hard limit", () => {
+    // The budget exists to fail an edit BEFORE the client silently cuts it.
+    // Raising it to within a handful of chars of 2048 would leave no room to
+    // notice, so the margin is asserted rather than trusted to review.
+    const margin = MCP_INSTRUCTIONS_LIMIT - MCP_INSTRUCTIONS_BUDGET;
+    expect(
+      margin,
+      `budget ${MCP_INSTRUCTIONS_BUDGET} is only ${margin} chars below the ` +
+        `${MCP_INSTRUCTIONS_LIMIT} hard limit — too close to act as an early ` +
+        `warning. Lower the budget instead of raising it.`,
+    ).toBeGreaterThanOrEqual(50);
+  });
+
+  it("leaves usable authoring headroom under the budget", () => {
+    // The counterpart to the margin above: a budget pinned two chars above the
+    // current string is a nuisance rail, and nuisance rails get "fixed" by
+    // deleting content — which is precisely what caused #3562. If this fails,
+    // MOVE mechanical detail into a tool `description` (those are not capped)
+    // rather than raising the budget toward the limit.
+    const headroom = MCP_INSTRUCTIONS_BUDGET - MCP_INSTRUCTIONS.length;
+    expect(
+      headroom,
+      `only ${headroom} chars of headroom between the string ` +
+        `(${MCP_INSTRUCTIONS.length}) and the budget ` +
+        `(${MCP_INSTRUCTIONS_BUDGET}); a routine edit would trip lint.`,
+    ).toBeGreaterThanOrEqual(25);
+  });
+
+  it("fits under the authored budget", () => {
+    const len = MCP_INSTRUCTIONS.length;
+    expect(
+      len,
+      `MCP instructions are ${len} chars — ${len - MCP_INSTRUCTIONS_BUDGET} over ` +
+        `the ${MCP_INSTRUCTIONS_BUDGET}-char budget (client hard limit ` +
+        `${MCP_INSTRUCTIONS_LIMIT}, which truncates silently and mid-word). ` +
+        `Cut ${len - MCP_INSTRUCTIONS_BUDGET} chars. Prefer MOVING mechanical ` +
+        `per-tool detail into that tool's \`description\` (tool descriptions ` +
+        `are NOT capped) over deleting it; keep safety/trust rules here.`,
+    ).toBeLessThanOrEqual(MCP_INSTRUCTIONS_BUDGET);
+  });
+
+  it("would not be truncated by the client", () => {
+    // The exact predicate the client applies.
+    expect(MCP_INSTRUCTIONS.length > MCP_INSTRUCTIONS_LIMIT).toBe(false);
+  });
+
+  // ── Content assertions: the SAFETY rules must be present, and must be
+  //    present *within the surviving prefix*. A budget test alone would still
+  //    pass if someone kept the length but deleted the guardrail.
+  it("retains the prompt-injection defence inside the un-truncated prefix", () => {
+    const survives = MCP_INSTRUCTIONS.slice(0, MCP_INSTRUCTIONS_LIMIT);
+    expect(survives).toContain("approve the pending pairing");
+    expect(survives).toContain("prompt injection");
+    expect(survives).toContain("Refuse");
+    expect(survives).toMatch(/never invoke that skill|Never invoke that skill/);
+  });
+
+  it("retains the forwarded-provenance trust rules inside the prefix", () => {
+    const survives = MCP_INSTRUCTIONS.slice(0, MCP_INSTRUCTIONS_LIMIT);
+    expect(survives).toContain("hidden_user");
+    expect(survives).toMatch(/no verifiable id/i);
+    expect(survives).toContain("untrusted content");
+  });
+
+  it("retains the reply-is-the-only-channel rule inside the prefix", () => {
+    const survives = MCP_INSTRUCTIONS.slice(0, MCP_INSTRUCTIONS_LIMIT);
+    expect(survives).toContain("reply tool");
+    expect(survives).toContain("never reaches their chat");
+  });
+
+  it("retains the multi-origin forward-attribution rule inside the prefix", () => {
+    // Review catch: this sentence was dropped in the first cut with no
+    // landing spot, surviving only in docs/telegram-features.md. A two-origin
+    // forwarded burst would then be wholly attributed to origin 1 — a
+    // provenance failure, not a mechanical one, so it belongs here.
+    const survives = MCP_INSTRUCTIONS.slice(0, MCP_INSTRUCTIONS_LIMIT);
+    expect(survives).toContain("forwarded_from_2");
+    expect(survives).toMatch(/attribute each part to its OWN origin/i);
+    expect(survives).toMatch(/never the whole burst to the first/i);
+  });
+
+  it("retains the forward id/date/deep-link attributes inside the prefix", () => {
+    const survives = MCP_INSTRUCTIONS.slice(0, MCP_INSTRUCTIONS_LIMIT);
+    for (const attr of [
+      "forwarded_from_id",
+      "forwarded_date",
+      "forwarded_message_id",
+      "t.me/<channel>/<id>",
+      "attachment_count",
+    ]) {
+      expect(survives).toContain(attr);
+    }
+  });
+});
+
+/**
+ * The PR's thesis is "MOVED, not deleted" — mechanical detail was cut from the
+ * instructions only because it landed in a tool `description`, which is not
+ * subject to the 2048-char cap. Nothing tested that the landing actually
+ * happened, so deleting the destination text passed the whole suite.
+ *
+ * These assertions pin the destinations. Comments are stripped first: a
+ * matching comment in bridge.ts must NOT be able to satisfy an assertion about
+ * text the AGENT reads.
+ */
+describe("moved instruction content landed in tool descriptions", () => {
+  const raw = readFileSync(
+    resolve(__dirname, "..", "bridge", "bridge.ts"),
+    "utf-8",
+  );
+  // Strip block and line comments so only real agent-facing strings match.
+  const bridgeCode = raw
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+
+  it("forum-topic routing landed in the reply description", () => {
+    expect(bridgeCode).toContain("FORUM TOPICS:");
+    expect(bridgeCode).toMatch(/do NOT pass message_thread_id on a normal reply/);
+    expect(bridgeCode).toContain("origin_turn_id");
+  });
+
+  it("format modes landed in the reply description", () => {
+    expect(bridgeCode).toContain("FORMAT:");
+    expect(bridgeCode).toMatch(/default format is "html"/);
+    expect(bridgeCode).toContain("markdownv2");
+  });
+
+  it("history-buffer rationale landed in get_recent_messages", () => {
+    expect(bridgeCode).toMatch(/no history endpoint/);
+    expect(bridgeCode).toMatch(/buffer survives restarts/);
+  });
+
+  it("the comment-stripping itself works (guards the assertions above)", () => {
+    // If stripping silently no-ops, every assertion in this block becomes
+    // satisfiable by a comment. Prove it removes both comment forms.
+    const sample = 'const a = 1 // FORUM TOPICS:\n/* FORMAT: */ const b = 2';
+    const stripped = sample
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/(^|[^:])\/\/.*$/gm, "$1");
+    expect(stripped).not.toContain("FORUM TOPICS:");
+    expect(stripped).not.toContain("FORMAT:");
+  });
+});

package/telegram-plugin/tests/multitopic-routing-wiring.test.ts

@@ -11,6 +11,7 @@
 import { describe, it, expect } from 'vitest'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { MCP_INSTRUCTIONS } from '../bridge/mcp-instructions.js'
 
 // #2996 P2: executeReply's body moved VERBATIM to outbound-send-path.ts
 // (`sendReply`); the reply-path routing assertions read the window there.
@@ -39,6 +40,17 @@ const streamSrc = readFileSync(
   'utf-8',
 )
 const gatewayAndStreamSrc = gatewaySrc + '\n' + streamSrc
+// #3562 — the MCP `instructions` string was extracted out of bridge.ts into
+// its own module (it must fit the Claude Code client's 2048-char truncation
+// limit, so it is now length-guarded independently). bridge.ts still owns the
+// per-tool `description` strings.
+//
+// Deliberately NOT concatenated with the instructions module: an earlier
+// revision merged both files into one blob, which meant an assertion could no
+// longer tell WHICH file carried a phrase, and a matching COMMENT satisfied it
+// just as well as real agent-facing text. Instructions text is asserted
+// against the imported runtime constant instead (see below) — a comment cannot
+// satisfy that, by construction.
 const bridgeSrc = readFileSync(
   resolve(__dirname, '..', 'bridge', 'bridge.ts'),
   'utf-8',
@@ -151,8 +163,16 @@ describe('component 4 — per-turn topic framing', () => {
   })
 
   it('the bridge instructions frame each channel message as the current topic', () => {
-    expect(bridgeSrc).toMatch(/answer ONLY this message/)
-    expect(bridgeSrc).toMatch(/do not also answer a pending message from another topic/i)
+    // Asserted against the IMPORTED runtime constant, not file text: this is
+    // the exact string handed to the MCP client, so a comment (or the phrase
+    // living in some other file) cannot satisfy it. Wording was tightened in
+    // #3562 to fit the 2048-char budget; the invariant is unchanged — the
+    // instructions must scope the agent to the current message's topic and
+    // forbid answering a queued other-topic message in the same turn.
+    expect(MCP_INSTRUCTIONS).toMatch(/answer only the current message/i)
+    expect(MCP_INSTRUCTIONS).toMatch(
+      /do not also answer a pending message from another topic/i,
+    )
   })
 })
 

package/telegram-plugin/tests/obligation-determinism.test.ts

@@ -95,6 +95,16 @@ function runSchedule(
   graceMs = 0,
   bgGraceMs = 0,
   bgAlwaysActive = false,
+  // #3550 — per-represent grace. Exercised so the determinism proof actually
+  // reaches `representGraceStillProtecting`; without this the fuzz never passes
+  // representGraceMs and the branch is unvisited.
+  representGraceMs = 0,
+  // #3550 discriminator knob. When FALSE, a re-present turn ends WITHOUT ever
+  // stamping noteTurnEnded — the "re-present still in flight" shape, in which
+  // the early-out provably cannot fire and the full represent window is held.
+  // Running the same seed both ways is what turns the represent-grace case from
+  // a code-path exercise into a test that FAILS if the early-out is removed.
+  stampTurnEndAfterRepresent = true,
 ): Sim {
   const PATH = "/state/agent/telegram/obligations.json";
   const store = memStore();
@@ -107,6 +117,7 @@ function runSchedule(
   // terminal (no livelock).
   let clock = 1_000_000;
   const SWEEP_TICK = 5_000;
+  const TURN_DURATION = 1_000; // virtual ms a turn occupies before it ends
   const r = rng(seed);
 
   const pending = [...msgs]; // not yet received
@@ -128,9 +139,20 @@ function runSchedule(
     const had = (turnsHad.get(id) ?? 0);
     const attemptIndex = had; // 0-based
     turnsHad.set(id, had + 1);
+    const isRepresentTurn = attemptIndex > 0;
     if (byId.get(id)!.answerOnAttempt === attemptIndex) {
       close(id, "answered");
-    } else if (graceMs > 0 && ledger.isOpen(id)) {
+    } else if (isRepresentTurn && !stampTurnEndAfterRepresent) {
+      // In-flight shape: the turn produced nothing observable, so nothing is
+      // stamped and the per-represent window is held for its full duration.
+      // (Deliberately NOT advancing the clock either — the two runs must differ
+      // only in whether the early-out can fire.)
+    } else if ((graceMs > 0 || representGraceMs > 0) && ledger.isOpen(id)) {
+      // A turn takes real time: its end is strictly LATER than the represent
+      // that triggered it. Without this the sim stamps lastTurnEndedAt equal to
+      // lastRepresentedAt and the #3550 early-out (which requires strictly
+      // greater) is never reached — the branch would go unproven.
+      clock += TURN_DURATION;
       ledger.noteTurnEnded(id, clock);
     }
   };
@@ -163,12 +185,13 @@ function runSchedule(
       deliverTurn(m.id); // original turn (attempt 0)
     } else if (open) {
       const decision =
-        graceMs > 0 || bgGraceMs > 0
+        graceMs > 0 || bgGraceMs > 0 || representGraceMs > 0
           ? ledger.decideAtIdle({
               now: clock,
               graceMs,
               backgroundWorkActive: bgGraceMs > 0 && bgAlwaysActive,
               backgroundGraceMs: bgGraceMs,
+              representGraceMs,
             })
           : ledger.decideAtIdle();
       if (decision.action === "none") {
@@ -181,7 +204,10 @@ function runSchedule(
       // INVARIANT (no double-ask): a terminated obligation must never resurface.
       expect(terminals.has(o.originTurnId)).toBe(false);
       if (decision.action === "represent") {
-        ledger.markRepresented(o.originTurnId);
+        // Stamp on the SAME virtual clock as noteTurnEnded, otherwise the
+        // per-represent window is measured against a wall-clock `Date.now()`
+        // default and never interacts with the grace under test.
+        ledger.markRepresented(o.originTurnId, clock);
         deliverTurn(o.originTurnId); // the re-present turn
       } else if (decision.action === "escalate") {
         if (ESC_IN_FLIGHT.has(o.originTurnId)) continue;
@@ -340,6 +366,91 @@ describe("obligation determinism — every inbound reaches a terminal, no silent
     }
   });
 
+  it("holds across 3000 schedules WITH the per-represent grace on, and the #3550 early-out DISCRIMINATES (same terminals, strictly fewer sweeps)", () => {
+    // Honest framing of what this case is and is not.
+    //
+    // The terminal assertions below are NOT a discriminator for the #3550 diff:
+    // a terminal is a function of `answerOnAttempt` / `escalateFailsFor` alone,
+    // and the worst-case schedule settles in ~72 sweep steps against a CAP of
+    // 10_000. Revert the early-out and every terminal — and the step budget —
+    // still holds. Those assertions are a NO-LIVELOCK / NO-LOSS guard on the
+    // represent-grace path, nothing more, and are labelled as such.
+    //
+    // The discriminator is the paired run. The SAME seed is run twice, differing
+    // in exactly one thing: whether a re-present turn ends (stamping
+    // noteTurnEnded) or stays in flight. The early-out fires only in the first,
+    // so:
+    //   - terminals must be IDENTICAL — the early-out changes WHEN the ladder
+    //     advances, never WHERE it lands; and
+    //   - the ended-turn run must take STRICTLY FEWER sweep steps — which is
+    //     the early-out actually firing and shortening rungs. Delete the
+    //     early-out and both runs hold the full 120s window, the step counts
+    //     become equal, and this assertion fails.
+    const ANSWER = [0, 1, 2, 3, 99];
+    const ESCFAIL = [0, 1, 2, 3, 5];
+    const GRACE_MS = 45_000;       // trailing-answer grace, still armed
+    const REPR_GRACE_MS = 120_000; // mirrors OBLIGATION_REPRESENT_GRACE_MS default
+    let discriminated = 0; // schedules the early-out demonstrably shortened
+    let totalRetired = 0;
+    let totalInFlight = 0;
+    for (let seed = 1; seed <= 3000; seed++) {
+      const r = rng(seed * 7919);
+      const n = 1 + Math.floor(r() * 5);
+      const msgs: Msg[] = [];
+      for (let i = 0; i < n; i++) {
+        const msgId = seed * 100 + i;
+        msgs.push({
+          id: `c:3#${msgId}`,
+          msgId,
+          answerOnAttempt: pick(ANSWER, r),
+          escalateFailsFor: pick(ESCFAIL, r),
+        });
+      }
+      const retired = runSchedule(msgs, seed * 104729, GRACE_MS, 0, false, REPR_GRACE_MS, true);
+      const inFlight = runSchedule(msgs, seed * 104729, GRACE_MS, 0, false, REPR_GRACE_MS, false);
+
+      // No-livelock / no-loss guard (NOT the #3550 discriminator).
+      expect(retired.steps).toBeLessThan(10_000);
+      expect(inFlight.steps).toBeLessThan(10_000);
+      for (const m of msgs) {
+        const t = retired.terminals.get(m.id);
+        expect(t, `repr seed=${seed} msg=${m.id} answer=${m.answerOnAttempt} escFail=${m.escalateFailsFor}`).toBeDefined();
+        if (m.answerOnAttempt <= MAX_REPRESENTS) {
+          expect(t).toBe("answered");
+        } else if (m.escalateFailsFor < ESCALATE_MAX) {
+          expect(t).toBe("escalation-delivered");
+        } else {
+          expect(t).toBe("escalation-give-up");
+        }
+      }
+
+      // DISCRIMINATOR 1 — the early-out is terminal-neutral.
+      expect(
+        [...retired.terminals].sort(),
+        `terminals diverged at seed=${seed}`,
+      ).toEqual([...inFlight.terminals].sort());
+
+      // DISCRIMINATOR 2 — the early-out actually fires and shortens rungs.
+      // Directional per seed (retiring a grace can never ADD sweeps)…
+      expect(
+        retired.steps,
+        `early-out LENGTHENED seed=${seed} (retired=${retired.steps} inFlight=${inFlight.steps})`,
+      ).toBeLessThanOrEqual(inFlight.steps);
+      // …and strictly shorter on the schedules that actually sit out a rung.
+      // Not every schedule does: with several messages interleaved, other work
+      // can advance the virtual clock past the window with no waiting sweep, so
+      // the strict inequality is asserted in aggregate rather than per seed.
+      if (retired.steps < inFlight.steps) discriminated++;
+      totalRetired += retired.steps;
+      totalInFlight += inFlight.steps;
+    }
+    // Delete the early-out and BOTH runs hold the full 120s window: every seed
+    // becomes equal, `discriminated` drops to 0 and the totals converge. These
+    // two assertions are what make this case a real test of the #3550 diff.
+    expect(discriminated, "the #3550 early-out never shortened a single schedule").toBeGreaterThan(1_000);
+    expect(totalRetired).toBeLessThan(totalInFlight);
+  });
+
   it("a delivered-but-unanswered obligation survives a restart and is escalated, not lost", () => {
     // Deterministic single case: model NEVER answers, escalation succeeds first try,
     // with a restart forced mid-life via a seed that triggers the 0.15 branch.