switchroom 0.5.0

package/telegram-plugin/tests/idle-footer.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+import { formatIdleFooter, type TurnRow } from "../idle-footer";
+
+// Fixed "now" anchor for all tests: 2026-01-01T00:00:00Z
+const NOW = 1_751_328_000_000;
+
+function row(overrides: Partial<TurnRow> & { startedAt: number }): TurnRow {
+  return {
+    turnKey: "t1",
+    chatId: "100",
+    endedAt: null,
+    ...overrides,
+  };
+}
+
+describe("formatIdleFooter", () => {
+  it("empty rows → quiet", () => {
+    expect(formatIdleFooter([], NOW)).toBe("🟡 quiet · no turns yet");
+  });
+
+  it("single old turn ended 1h ago → idle 1h ago", () => {
+    const r = row({ startedAt: NOW - 70 * 60_000, endedAt: NOW - 60 * 60_000 });
+    expect(formatIdleFooter([r], NOW)).toBe("🟢 idle · last reply 1h ago");
+  });
+
+  it("single turn ended 3m ago → idle 3m ago", () => {
+    const r = row({ startedAt: NOW - 5 * 60_000, endedAt: NOW - 3 * 60_000 });
+    expect(formatIdleFooter([r], NOW)).toBe("🟢 idle · last reply 3m ago");
+  });
+
+  it("single turn ended 10s ago → idle <1m ago", () => {
+    const r = row({ startedAt: NOW - 30_000, endedAt: NOW - 10_000 });
+    expect(formatIdleFooter([r], NOW)).toBe("🟢 idle · last reply <1m ago");
+  });
+
+  it("currently running turn started 2m ago → working since 2m ago", () => {
+    const r = row({ startedAt: NOW - 2 * 60_000 });
+    expect(formatIdleFooter([r], NOW)).toBe("⚙️ working since 2m ago");
+  });
+
+  it("multiple turns, most recent is running → working since recent", () => {
+    const old = row({ turnKey: "t1", startedAt: NOW - 10 * 60_000, endedAt: NOW - 8 * 60_000 });
+    const running = row({ turnKey: "t2", startedAt: NOW - 90_000 }); // 1m 30s ago
+    expect(formatIdleFooter([old, running], NOW)).toBe("⚙️ working since 1m ago");
+  });
+
+  it("multiple turns, most recent is ended → idle last reply", () => {
+    const old = row({ turnKey: "t1", startedAt: NOW - 30 * 60_000, endedAt: NOW - 28 * 60_000 });
+    const recent = row({ turnKey: "t2", startedAt: NOW - 6 * 60_000, endedAt: NOW - 4 * 60_000 });
+    expect(formatIdleFooter([old, recent], NOW)).toBe("🟢 idle · last reply 4m ago");
+  });
+
+  it("day-old turn → 1d ago", () => {
+    const r = row({ startedAt: NOW - 26 * 3_600_000, endedAt: NOW - 25 * 3_600_000 });
+    expect(formatIdleFooter([r], NOW)).toBe("🟢 idle · last reply 1d ago");
+  });
+
+  it("unsorted rows — picks max startedAt", () => {
+    // rows in reverse chronological order; function must not assume sorted
+    const r1 = row({ turnKey: "t1", startedAt: NOW - 20 * 60_000, endedAt: NOW - 18 * 60_000 });
+    const r2 = row({ turnKey: "t2", startedAt: NOW - 5 * 60_000, endedAt: NOW - 2 * 60_000 });
+    const r3 = row({ turnKey: "t3", startedAt: NOW - 40 * 60_000, endedAt: NOW - 38 * 60_000 });
+    // r2 has the largest startedAt, endedAt is 2m ago
+    expect(formatIdleFooter([r1, r2, r3], NOW)).toBe("🟢 idle · last reply 2m ago");
+  });
+});

package/telegram-plugin/tests/inbound-coalesce.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Unit tests for telegram-plugin/gateway/inbound-coalesce.ts.
+ *
+ * Pin the four behaviours `gateway.ts`'s legacy in-line coalescer
+ * relied on, so the extraction (#553 Phase 3) is observably equivalent:
+ *
+ *   1. First message schedules a flush after gapMs.
+ *   2. Subsequent messages reset the timer (sliding window).
+ *   3. Flush invokes onFlush(key, merged) exactly once.
+ *   4. gapMs <= 0 bypasses the buffer entirely.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createInboundCoalescer, inboundCoalesceKey } from '../gateway/inbound-coalesce.js'
+
+interface Payload { text: string }
+
+const merge = (entries: Payload[]): Payload => ({ text: entries.map((e) => e.text).join('\n') })
+
+beforeEach(() => { vi.useFakeTimers() })
+afterEach(() => { vi.useRealTimers() })
+
+describe('inboundCoalesceKey', () => {
+  it('combines chatId and userId so distinct senders never collide', () => {
+    expect(inboundCoalesceKey('c1', 'u1')).not.toBe(inboundCoalesceKey('c1', 'u2'))
+    expect(inboundCoalesceKey('c1', 'u1')).not.toBe(inboundCoalesceKey('c2', 'u1'))
+    expect(inboundCoalesceKey('c1', 'u1')).toBe(inboundCoalesceKey('c1', 'u1'))
+  })
+})
+
+describe('createInboundCoalescer', () => {
+  it('flushes a single message after gapMs with the joined payload', () => {
+    const flushed: Array<{ key: string; merged: Payload }> = []
+    const c = createInboundCoalescer<Payload>({
+      gapMs: 1500,
+      merge,
+      onFlush: (key, merged) => flushed.push({ key, merged }),
+    })
+
+    c.enqueue('c1:u1', { text: 'hi' })
+    expect(c.peek('c1:u1')?.count).toBe(1)
+    expect(flushed).toEqual([])
+
+    vi.advanceTimersByTime(1499)
+    expect(flushed).toEqual([])
+    vi.advanceTimersByTime(1)
+    expect(flushed).toEqual([{ key: 'c1:u1', merged: { text: 'hi' } }])
+    expect(c.peek('c1:u1')).toBeNull()
+  })
+
+  it('resets the timer on each new message (sliding window)', () => {
+    const flushed: Array<{ key: string; merged: Payload }> = []
+    const c = createInboundCoalescer<Payload>({
+      gapMs: 1500,
+      merge,
+      onFlush: (key, merged) => flushed.push({ key, merged }),
+    })
+
+    c.enqueue('c1:u1', { text: 'one' })
+    vi.advanceTimersByTime(1000)         // 1s into the gap
+    c.enqueue('c1:u1', { text: 'two' })  // resets the timer
+    vi.advanceTimersByTime(1000)         // another 1s — still no flush
+    expect(flushed).toEqual([])
+    vi.advanceTimersByTime(500)          // 1.5s since "two" → flush now
+    expect(flushed).toEqual([{ key: 'c1:u1', merged: { text: 'one\ntwo' } }])
+  })
+
+  it('bypasses the buffer entirely when gapMs <= 0', () => {
+    const flushed: Array<{ key: string; merged: Payload }> = []
+    const c = createInboundCoalescer<Payload>({
+      gapMs: 0,
+      merge,
+      onFlush: (key, merged) => flushed.push({ key, merged }),
+    })
+    const r = c.enqueue('c1:u1', { text: 'hi' })
+    expect(r.bypass).toBe(true)
+    expect(c.peek('c1:u1')).toBeNull()
+    expect(flushed).toEqual([])  // caller is responsible for flushing
+  })
+
+  it('keeps distinct keys independent', () => {
+    const flushed: Array<{ key: string; merged: Payload }> = []
+    const c = createInboundCoalescer<Payload>({
+      gapMs: 1500,
+      merge,
+      onFlush: (key, merged) => flushed.push({ key, merged }),
+    })
+    c.enqueue('c1:u1', { text: 'A' })
+    c.enqueue('c2:u2', { text: 'B' })
+    expect(c.size()).toBe(2)
+    vi.advanceTimersByTime(1500)
+    expect(flushed.map((f) => f.key).sort()).toEqual(['c1:u1', 'c2:u2'])
+  })
+
+  it('honours a dynamic gapMs function (read per-call so config changes take effect)', () => {
+    let gap = 1500
+    const flushed: string[] = []
+    const c = createInboundCoalescer<Payload>({
+      gapMs: () => gap,
+      merge,
+      onFlush: (key) => flushed.push(key),
+    })
+    c.enqueue('c1:u1', { text: 'first' })
+    vi.advanceTimersByTime(1500)
+    expect(flushed).toEqual(['c1:u1'])
+
+    // Operator dialled it down to 500ms — next message uses the new value.
+    gap = 500
+    c.enqueue('c1:u1', { text: 'second' })
+    vi.advanceTimersByTime(500)
+    expect(flushed).toEqual(['c1:u1', 'c1:u1'])
+  })
+
+  it('reset() cancels pending flushes and drops buffered entries', () => {
+    const flushed: Array<{ key: string; merged: Payload }> = []
+    const c = createInboundCoalescer<Payload>({
+      gapMs: 1500,
+      merge,
+      onFlush: (key, merged) => flushed.push({ key, merged }),
+    })
+    c.enqueue('c1:u1', { text: 'hi' })
+    c.reset()
+    vi.advanceTimersByTime(5000)
+    expect(flushed).toEqual([])
+    expect(c.size()).toBe(0)
+  })
+})

package/telegram-plugin/tests/inline-keyboard-callbacks.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Unit tests for #271's agent-callback prefix wrapping + parsing.
+ *
+ * These pin the wire-format contract so the gateway's callback_query
+ * dispatcher and the inline_keyboard validation in executeReply /
+ * executeStreamReply stay in sync. If anyone adds a new infrastructure
+ * prefix in callback_query routing, these tests still pass — but the
+ * contract that `agent:` is reserved for round-tripping is enforced
+ * by the parser.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  AGENT_CALLBACK_PREFIX,
+  AGENT_CALLBACK_DATA_MAX,
+  wrapAgentCallbacks,
+  parseAgentCallback,
+  validateAndWrapAgentKeyboard,
+} from '../inline-keyboard-callbacks.js'
+
+describe('inline-keyboard-callbacks (#271)', () => {
+  describe('AGENT_CALLBACK_DATA_MAX', () => {
+    it('reserves room for the prefix within Telegram\'s 64-byte limit', () => {
+      // Sanity: prefix bytes + agent budget == Telegram limit (64).
+      const prefixBytes = new TextEncoder().encode(AGENT_CALLBACK_PREFIX).byteLength
+      expect(prefixBytes + AGENT_CALLBACK_DATA_MAX).toBe(64)
+    })
+  })
+
+  describe('wrapAgentCallbacks', () => {
+    it('prepends `agent:` to every callback_data field', () => {
+      const wrapped = wrapAgentCallbacks([
+        [{ text: 'Approve', callback_data: 'approve_pr_547' }],
+        [{ text: 'Hold', callback_data: 'hold' }],
+      ])
+      expect(wrapped[0]![0]!.callback_data).toBe('agent:approve_pr_547')
+      expect(wrapped[1]![0]!.callback_data).toBe('agent:hold')
+    })
+
+    it('passes URL buttons through unchanged', () => {
+      const wrapped = wrapAgentCallbacks([
+        [{ text: 'Open docs', url: 'https://example.com' }],
+      ])
+      expect(wrapped[0]![0]).toEqual({ text: 'Open docs', url: 'https://example.com' })
+      expect(wrapped[0]![0]!.callback_data).toBeUndefined()
+    })
+
+    it('handles mixed URL + callback_data buttons in one row', () => {
+      const wrapped = wrapAgentCallbacks([
+        [
+          { text: 'Open', url: 'https://x.test' },
+          { text: 'Approve', callback_data: 'ok' },
+        ],
+      ])
+      expect(wrapped[0]![0]!.url).toBe('https://x.test')
+      expect(wrapped[0]![0]!.callback_data).toBeUndefined()
+      expect(wrapped[0]![1]!.callback_data).toBe('agent:ok')
+      expect(wrapped[0]![1]!.url).toBeUndefined()
+    })
+
+    it('returns a fresh array — does not mutate input', () => {
+      const original = [[{ text: 'A', callback_data: 'a' }]]
+      const wrapped = wrapAgentCallbacks(original)
+      expect(original[0]![0]!.callback_data).toBe('a')
+      expect(wrapped[0]![0]!.callback_data).toBe('agent:a')
+      expect(wrapped).not.toBe(original)
+      expect(wrapped[0]).not.toBe(original[0])
+    })
+
+    it('throws when an agent-supplied callback_data exceeds the 58-byte budget', () => {
+      const tooLong = 'x'.repeat(AGENT_CALLBACK_DATA_MAX + 1)
+      expect(() =>
+        wrapAgentCallbacks([[{ text: 'X', callback_data: tooLong }]]),
+      ).toThrow(/exceeds 58-byte agent budget/)
+    })
+
+    it('accepts callback_data exactly at the 58-byte budget', () => {
+      const atLimit = 'x'.repeat(AGENT_CALLBACK_DATA_MAX)
+      const wrapped = wrapAgentCallbacks([[{ text: 'X', callback_data: atLimit }]])
+      const wireBytes = new TextEncoder().encode(wrapped[0]![0]!.callback_data as string).byteLength
+      expect(wireBytes).toBe(64) // hits Telegram's hard limit exactly
+    })
+
+    it('counts BYTES not chars for multi-byte UTF-8', () => {
+      // '🔐' is 4 bytes in UTF-8. 14 of them = 56 bytes — under the
+      // 58-byte budget, so should pass. 15 of them = 60 bytes — over.
+      const ok = '🔐'.repeat(14)
+      expect(() =>
+        wrapAgentCallbacks([[{ text: 'X', callback_data: ok }]]),
+      ).not.toThrow()
+
+      const bad = '🔐'.repeat(15)
+      expect(() =>
+        wrapAgentCallbacks([[{ text: 'X', callback_data: bad }]]),
+      ).toThrow(/exceeds 58-byte agent budget/)
+    })
+
+    it('handles an empty keyboard without crashing', () => {
+      expect(wrapAgentCallbacks([])).toEqual([])
+    })
+  })
+
+  describe('parseAgentCallback', () => {
+    it('strips the prefix and returns the raw payload', () => {
+      const result = parseAgentCallback('agent:approve_pr_547')
+      expect(result).toEqual({ raw: 'approve_pr_547' })
+    })
+
+    it('returns null for non-agent prefixes (lets dispatcher fall through)', () => {
+      expect(parseAgentCallback('auth:rotate:clerk')).toBeNull()
+      expect(parseAgentCallback('op:dismiss:klanker')).toBeNull()
+      expect(parseAgentCallback('vd:unlock:abc')).toBeNull()
+      expect(parseAgentCallback('aq:0:xyz')).toBeNull()
+      expect(parseAgentCallback('perm:allow:abcde')).toBeNull()
+      expect(parseAgentCallback('something_random')).toBeNull()
+    })
+
+    it('returns empty raw payload when the agent emitted bare prefix', () => {
+      // Edge case: agent emits `callback_data: ''` (zero-length). After
+      // wrap we'd send `agent:`. Round-tripping returns { raw: '' }.
+      // Validation upstream should reject empty callback_data; this is
+      // a defensive check.
+      expect(parseAgentCallback('agent:')).toEqual({ raw: '' })
+    })
+  })
+
+  describe('validateAndWrapAgentKeyboard', () => {
+    it('returns ok=true with wrapped keyboard on a valid input', () => {
+      const result = validateAndWrapAgentKeyboard([
+        [{ text: 'Approve', callback_data: 'ok' }],
+      ])
+      expect(result.ok).toBe(true)
+      if (result.ok) {
+        expect(result.wrapped[0]![0]!.callback_data).toBe('agent:ok')
+      }
+    })
+
+    it('returns ok=false with errors when validation fails', () => {
+      // Empty text fails the existing validateInlineKeyboard.
+      const result = validateAndWrapAgentKeyboard([
+        [{ text: '', callback_data: 'ok' }],
+      ])
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.errors.length).toBeGreaterThan(0)
+        expect(result.errors[0]!.field).toBe('text')
+      }
+    })
+  })
+})

package/telegram-plugin/tests/interrupt-marker.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Unit tests for `parseInterruptMarker` — the `!`-prefix interrupt
+ * detector for the steer-or-queue-mid-flight JTBD (#575).
+ *
+ * The gateway-side wiring (bypass-coalesce, SIGINT, forward-stripped)
+ * is covered by integration tests; these focus on the pure parsing
+ * contract so the rule stays unambiguous.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import { parseInterruptMarker } from '../interrupt-marker.js'
+
+describe('parseInterruptMarker — positive cases (interrupt fires)', () => {
+  it('fires on a leading `!` with body', () => {
+    const r = parseInterruptMarker('!stop and do this instead')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('stop and do this instead')
+    expect(r.emptyBody).toBe(false)
+  })
+
+  it('fires on `! body` with space after the marker', () => {
+    const r = parseInterruptMarker('! drop everything')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('drop everything')
+  })
+
+  it('fires on leading whitespace + `!`', () => {
+    const r = parseInterruptMarker('   ! cancel')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('cancel')
+  })
+
+  it('strips ALL leading whitespace after the marker, not just one space', () => {
+    const r = parseInterruptMarker('!\n\n  newline-prefixed body')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('newline-prefixed body')
+  })
+
+  it('flags emptyBody when only `!` is sent', () => {
+    const r = parseInterruptMarker('!')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('')
+    expect(r.emptyBody).toBe(true)
+  })
+
+  it('flags emptyBody when `!` is followed by only whitespace', () => {
+    const r = parseInterruptMarker('!   \n  ')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('')
+    expect(r.emptyBody).toBe(true)
+  })
+})
+
+describe('parseInterruptMarker — negative cases (no interrupt)', () => {
+  it('does NOT fire on doubled `!!` (typo / emphasis)', () => {
+    const r = parseInterruptMarker('!!emphasis on this')
+    expect(r.isInterrupt).toBe(false)
+    expect(r.body).toBe('!!emphasis on this')
+  })
+
+  it('does NOT fire on `!!!` or any longer run of bangs', () => {
+    expect(parseInterruptMarker('!!!hold on').isInterrupt).toBe(false)
+    expect(parseInterruptMarker('!!!!').isInterrupt).toBe(false)
+  })
+
+  it('does NOT fire when `!` is mid-string', () => {
+    const r = parseInterruptMarker('whoops! actually')
+    expect(r.isInterrupt).toBe(false)
+    expect(r.body).toBe('whoops! actually')
+  })
+
+  it('does NOT fire on markdown-style `*!*`', () => {
+    const r = parseInterruptMarker('*!* keep going')
+    expect(r.isInterrupt).toBe(false)
+  })
+
+  it('does NOT fire on `/` slash-commands (reserved for bot commands)', () => {
+    const r = parseInterruptMarker('/stop the agent')
+    expect(r.isInterrupt).toBe(false)
+  })
+
+  it('does NOT fire on uppercase STOP / cancel keywords', () => {
+    expect(parseInterruptMarker('STOP').isInterrupt).toBe(false)
+    expect(parseInterruptMarker('cancel that').isInterrupt).toBe(false)
+  })
+
+  it('does NOT fire on empty text', () => {
+    const r = parseInterruptMarker('')
+    expect(r.isInterrupt).toBe(false)
+    expect(r.body).toBe('')
+  })
+
+  it('does NOT fire on whitespace-only text', () => {
+    const r = parseInterruptMarker('   \n  \t  ')
+    expect(r.isInterrupt).toBe(false)
+  })
+
+  it('passes through normal prose unchanged', () => {
+    const original = 'Hi, can you check the calendar for next week?'
+    const r = parseInterruptMarker(original)
+    expect(r.isInterrupt).toBe(false)
+    expect(r.body).toBe(original)
+  })
+})
+
+describe('parseInterruptMarker — body preservation', () => {
+  it('preserves multi-line bodies after the marker', () => {
+    const r = parseInterruptMarker('!\nLine 1\nLine 2')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('Line 1\nLine 2')
+  })
+
+  it('preserves embedded `!` inside the body', () => {
+    const r = parseInterruptMarker('! WAIT! actually do X')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('WAIT! actually do X')
+  })
+
+  it('preserves trailing whitespace inside the body', () => {
+    // Caller may want to display verbatim; we don't trimEnd in the
+    // body — only the leading whitespace after the marker.
+    const r = parseInterruptMarker('!keep this   ')
+    expect(r.isInterrupt).toBe(true)
+    expect(r.body).toBe('keep this   ')
+  })
+})

package/telegram-plugin/tests/ipc-protocol.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect } from "vitest";
+import type {
+  GatewayToClient,
+  ClientToGateway,
+  InboundMessage,
+  PermissionEvent,
+  PermissionRequestForward,
+  StatusEvent,
+  ToolCallResult,
+  RegisterMessage,
+  ToolCallMessage,
+  SessionEventForward,
+  HeartbeatMessage,
+} from "../gateway/ipc-protocol.js";
+
+describe("IPC Protocol — round-trip serialization", () => {
+  function roundTrip<T>(msg: T): T {
+    return JSON.parse(JSON.stringify(msg));
+  }
+
+  describe("Gateway -> Client messages", () => {
+    it("InboundMessage round-trips", () => {
+      const msg: InboundMessage = {
+        type: "inbound",
+        chatId: "-1001234567890",
+        threadId: 42,
+        messageId: 999,
+        user: "alice",
+        userId: 12345,
+        ts: 1700000000,
+        text: "hello world",
+        imagePath: "/tmp/photo.jpg",
+        attachment: { fileId: "abc123", mimeType: "image/jpeg", fileName: "photo.jpg" },
+        meta: { steering: "false" },
+      };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("InboundMessage round-trips with minimal fields", () => {
+      const msg: InboundMessage = {
+        type: "inbound",
+        chatId: "-100999",
+        messageId: 1,
+        user: "bob",
+        userId: 1,
+        ts: 0,
+        text: "",
+        meta: {},
+      };
+      const parsed = roundTrip(msg);
+      expect(parsed.type).toBe("inbound");
+      expect(parsed.threadId).toBeUndefined();
+      expect(parsed.imagePath).toBeUndefined();
+      expect(parsed.attachment).toBeUndefined();
+    });
+
+    it("PermissionEvent round-trips (allow)", () => {
+      const msg: PermissionEvent = { type: "permission", requestId: "req-1", behavior: "allow" };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("PermissionEvent round-trips (deny)", () => {
+      const msg: PermissionEvent = { type: "permission", requestId: "req-2", behavior: "deny" };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("StatusEvent round-trips all statuses", () => {
+      for (const status of ["agent_down", "agent_connected", "gateway_shutting_down"] as const) {
+        const msg: StatusEvent = { type: "status", status };
+        expect(roundTrip(msg)).toEqual(msg);
+      }
+    });
+
+    it("ToolCallResult round-trips (success)", () => {
+      const msg: ToolCallResult = {
+        type: "tool_call_result",
+        id: "call-1",
+        success: true,
+        result: { text: "done", count: 42 },
+      };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("ToolCallResult round-trips (error)", () => {
+      const msg: ToolCallResult = {
+        type: "tool_call_result",
+        id: "call-2",
+        success: false,
+        error: "not found",
+      };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+  });
+
+  describe("Client -> Gateway messages", () => {
+    it("RegisterMessage round-trips", () => {
+      const msg: RegisterMessage = { type: "register", agentName: "assistant", topicId: 42 };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("RegisterMessage round-trips without topicId", () => {
+      const msg: RegisterMessage = { type: "register", agentName: "worker" };
+      const parsed = roundTrip(msg);
+      expect(parsed.type).toBe("register");
+      expect(parsed.agentName).toBe("worker");
+      expect(parsed.topicId).toBeUndefined();
+    });
+
+    it("ToolCallMessage round-trips", () => {
+      const msg: ToolCallMessage = {
+        type: "tool_call",
+        id: "tc-1",
+        tool: "reply",
+        args: { chat_id: "123", text: "hello" },
+      };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("SessionEventForward round-trips", () => {
+      const msg: SessionEventForward = {
+        type: "session_event",
+        event: { type: "assistant", message: { content: [{ type: "text", text: "hi" }] } },
+        chatId: "123",
+        threadId: 7,
+      };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("PermissionRequestForward round-trips", () => {
+      const msg: PermissionRequestForward = {
+        type: "permission_request",
+        requestId: "abc12",
+        toolName: "Bash",
+        description: "Execute a bash command",
+        inputPreview: '{"command":"rm -rf /tmp/old"}',
+      };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+
+    it("HeartbeatMessage round-trips", () => {
+      const msg: HeartbeatMessage = { type: "heartbeat", agentName: "assistant" };
+      expect(roundTrip(msg)).toEqual(msg);
+    });
+  });
+
+  describe("type discrimination", () => {
+    it("GatewayToClient discriminates by type field", () => {
+      const messages: GatewayToClient[] = [
+        { type: "inbound", chatId: "1", messageId: 1, user: "u", userId: 1, ts: 0, text: "", meta: {} },
+        { type: "permission", requestId: "r1", behavior: "allow" },
+        { type: "status", status: "agent_down" },
+        { type: "tool_call_result", id: "t1", success: true },
+      ];
+
+      const types = messages.map((m) => m.type);
+      expect(types).toEqual(["inbound", "permission", "status", "tool_call_result"]);
+
+      for (const msg of messages) {
+        switch (msg.type) {
+          case "inbound":
+            expect(msg.chatId).toBeDefined();
+            break;
+          case "permission":
+            expect(msg.requestId).toBeDefined();
+            break;
+          case "status":
+            expect(msg.status).toBeDefined();
+            break;
+          case "tool_call_result":
+            expect(msg.id).toBeDefined();
+            break;
+          default: {
+            const _exhaustive: never = msg;
+            throw new Error(`unhandled type: ${(_exhaustive as any).type}`);
+          }
+        }
+      }
+    });
+
+    it("ClientToGateway discriminates by type field", () => {
+      const messages: ClientToGateway[] = [
+        { type: "register", agentName: "a" },
+        { type: "tool_call", id: "t1", tool: "reply", args: {} },
+        { type: "session_event", event: {}, chatId: "1" },
+        { type: "permission_request", requestId: "r1", toolName: "Bash", description: "run cmd", inputPreview: "{}" },
+        { type: "heartbeat", agentName: "a" },
+      ];
+
+      const types = messages.map((m) => m.type);
+      expect(types).toEqual(["register", "tool_call", "session_event", "permission_request", "heartbeat"]);
+
+      for (const msg of messages) {
+        switch (msg.type) {
+          case "register":
+            expect(msg.agentName).toBeDefined();
+            break;
+          case "tool_call":
+            expect(msg.tool).toBeDefined();
+            break;
+          case "session_event":
+            expect(msg.event).toBeDefined();
+            break;
+          case "permission_request":
+            expect(msg.requestId).toBeDefined();
+            expect(msg.toolName).toBeDefined();
+            break;
+          case "heartbeat":
+            expect(msg.agentName).toBeDefined();
+            break;
+          default: {
+            const _exhaustive: never = msg;
+            throw new Error(`unhandled type: ${(_exhaustive as any).type}`);
+          }
+        }
+      }
+    });
+  });
+});