switchroom 0.5.0

package/telegram-plugin/tests/ipc-server-anonymous-refuse.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { validateClientMessage } from "../gateway/ipc-server.js";
+
+/**
+ * #430 Phase 2 — bridge anonymous refuse.
+ *
+ * The bridge defaults to SWITCHROOM_AGENT_NAME="default" if the env
+ * var isn't set (legacy behaviour). That's how we got the
+ * `registered agent=default` lines in every gateway log: any
+ * non-switchroom claude session that loaded the telegram MCP plugin
+ * would probe each agent's gateway socket and register as "default",
+ * crosstalking into someone else's chat.
+ *
+ * The bridge now refuses to start without a real agent name. The
+ * gateway's validator is the server-side defence: if anyone sends a
+ * register message with agentName="default" — a stale older bridge,
+ * a third-party tool, an attacker — we drop it.
+ */
+
+describe("validateClientMessage — register agentName='default' refused (#430)", () => {
+  it("rejects register with agentName=default (legacy anonymous fallback)", () => {
+    expect(
+      validateClientMessage({
+        type: "register",
+        agentName: "default",
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts register with a real agent name", () => {
+    expect(
+      validateClientMessage({
+        type: "register",
+        agentName: "klanker",
+      }),
+    ).toBe(true);
+  });
+
+  it("still rejects empty / missing agentName (existing contract)", () => {
+    expect(validateClientMessage({ type: "register", agentName: "" })).toBe(false);
+    expect(validateClientMessage({ type: "register" })).toBe(false);
+  });
+
+  it("rejects oversized agentName (existing contract preserved)", () => {
+    expect(
+      validateClientMessage({
+        type: "register",
+        agentName: "x".repeat(129),
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts a real name even when 'default' appears as a substring", () => {
+    // Sanity: we reject the literal string, not anything containing it.
+    expect(
+      validateClientMessage({
+        type: "register",
+        agentName: "default-finance-agent",
+      }),
+    ).toBe(true);
+    expect(
+      validateClientMessage({
+        type: "register",
+        agentName: "my-default",
+      }),
+    ).toBe(true);
+  });
+
+  it("validator rejection happens before handleRegister side effects", () => {
+    // No state to inspect at this layer — the validator is pure. The
+    // contract this test guards: validate() returning false means the
+    // gateway's main loop logs "invalid IPC message shape from
+    // client" and continues without dispatching to handleRegister.
+    // See ipc-server.ts processBuffer for the early-return.
+    expect(
+      validateClientMessage({
+        type: "register",
+        agentName: "default",
+      }),
+    ).toBe(false);
+  });
+});

package/telegram-plugin/tests/ipc-server-client.test.ts

@@ -0,0 +1,323 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { createIpcServer, type IpcServer, type IpcClient } from "../gateway/ipc-server.js";
+import { createIpcClient, type IpcClientHandle } from "../bridge/ipc-client.js";
+import type {
+  ToolCallMessage,
+  ToolCallResult,
+  SessionEventForward,
+  HeartbeatMessage,
+  InboundMessage,
+  StatusEvent,
+} from "../gateway/ipc-protocol.js";
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ipc-test-"));
+  return join(dir, "test.sock");
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+describe("IPC Server + Client integration", () => {
+  const servers: IpcServer[] = [];
+  const clients: IpcClientHandle[] = [];
+
+  afterEach(async () => {
+    for (const c of clients) c.close();
+    clients.length = 0;
+    for (const s of servers) await s.close();
+    servers.length = 0;
+  });
+
+  function makeServer(
+    socketPath: string,
+    overrides: Partial<Parameters<typeof createIpcServer>[0]> = {},
+  ) {
+    const registered = vi.fn();
+    const disconnected = vi.fn();
+    const toolCallHandler = vi.fn(async (_client: IpcClient, msg: ToolCallMessage): Promise<ToolCallResult> => ({
+      type: "tool_call_result",
+      id: msg.id,
+      success: true,
+      result: { echo: msg.tool },
+    }));
+    const sessionEventHandler = vi.fn();
+    const permissionRequestHandler = vi.fn();
+    const heartbeatHandler = vi.fn();
+
+    const server = createIpcServer({
+      socketPath,
+      onClientRegistered: overrides.onClientRegistered ?? registered,
+      onClientDisconnected: overrides.onClientDisconnected ?? disconnected,
+      onToolCall: overrides.onToolCall ?? toolCallHandler,
+      onSessionEvent: overrides.onSessionEvent ?? sessionEventHandler,
+      onPermissionRequest: overrides.onPermissionRequest ?? permissionRequestHandler,
+      onHeartbeat: overrides.onHeartbeat ?? heartbeatHandler,
+    });
+    servers.push(server);
+    return { server, registered, disconnected, toolCallHandler, sessionEventHandler, permissionRequestHandler, heartbeatHandler };
+  }
+
+  async function makeClient(
+    socketPath: string,
+    agentName: string,
+    overrides: Partial<Parameters<typeof createIpcClient>[0]> = {},
+  ) {
+    const onInbound = overrides.onInbound ?? vi.fn();
+    const onPermission = overrides.onPermission ?? vi.fn();
+    const onStatus = overrides.onStatus ?? vi.fn();
+    const client = await createIpcClient({
+      socketPath,
+      agentName,
+      topicId: overrides.topicId,
+      onInbound,
+      onPermission,
+      onStatus,
+      heartbeatIntervalMs: overrides.heartbeatIntervalMs ?? 60000, // long default to avoid noise
+      reconnectDelayMs: overrides.reconnectDelayMs ?? 100,
+      maxReconnectDelayMs: overrides.maxReconnectDelayMs ?? 500,
+    });
+    clients.push(client);
+    return { client, onInbound, onPermission, onStatus };
+  }
+
+  it("server starts and listens on socket", () => {
+    const path = tmpSocket();
+    const { server } = makeServer(path);
+    expect(server.clientCount()).toBe(0);
+  });
+
+  it("client connects and registers", async () => {
+    const path = tmpSocket();
+    const { server, registered } = makeServer(path);
+    const { client } = await makeClient(path, "assistant");
+
+    await wait(50);
+
+    expect(client.isConnected()).toBe(true);
+    expect(server.clientCount()).toBe(1);
+    expect(registered).toHaveBeenCalledTimes(1);
+
+    const registeredClient = registered.mock.calls[0][0] as IpcClient;
+    expect(registeredClient.agentName).toBe("assistant");
+  });
+
+  it("client calls tool, server receives and responds", async () => {
+    const path = tmpSocket();
+    const { server, toolCallHandler } = makeServer(path);
+    const { client } = await makeClient(path, "assistant");
+    await wait(50);
+
+    const result = await client.callTool("reply", { text: "hi" });
+
+    expect(result.type).toBe("tool_call_result");
+    expect(result.success).toBe(true);
+    expect(result.result).toEqual({ echo: "reply" });
+    expect(toolCallHandler).toHaveBeenCalledTimes(1);
+    expect(toolCallHandler.mock.calls[0][1].tool).toBe("reply");
+    expect(toolCallHandler.mock.calls[0][1].args).toEqual({ text: "hi" });
+  });
+
+  it("client disconnects, server cleans up routing", async () => {
+    const path = tmpSocket();
+    const { server, disconnected } = makeServer(path);
+    const { client } = await makeClient(path, "worker");
+    await wait(50);
+
+    expect(server.clientCount()).toBe(1);
+    expect(server.getClient("worker")).toBeDefined();
+
+    client.close();
+    await wait(100);
+
+    expect(server.clientCount()).toBe(0);
+    expect(server.getClient("worker")).toBeUndefined();
+    expect(disconnected).toHaveBeenCalledTimes(1);
+  });
+
+  it("multiple clients can connect", async () => {
+    const path = tmpSocket();
+    const { server, registered } = makeServer(path);
+
+    await makeClient(path, "assistant", { topicId: 10 });
+    await makeClient(path, "worker", { topicId: 20 });
+    await wait(50);
+
+    expect(server.clientCount()).toBe(2);
+    expect(registered).toHaveBeenCalledTimes(2);
+    expect(server.getClient("assistant")).toBeDefined();
+    expect(server.getClient("worker")).toBeDefined();
+  });
+
+  it("server broadcasts to all clients", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer(path);
+
+    const c1 = await makeClient(path, "agent-a");
+    const c2 = await makeClient(path, "agent-b");
+    await wait(50);
+
+    const statusMsg: StatusEvent = { type: "status", status: "gateway_shutting_down" };
+    server.broadcast(statusMsg);
+    await wait(100);
+
+    expect(c1.onStatus).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "status", status: "gateway_shutting_down" }),
+    );
+    expect(c2.onStatus).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "status", status: "gateway_shutting_down" }),
+    );
+  });
+
+  it("server sendToAgent routes to correct client", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer(path);
+
+    const c1 = await makeClient(path, "agent-a");
+    const c2 = await makeClient(path, "agent-b");
+    await wait(50);
+
+    const msg: InboundMessage = {
+      type: "inbound",
+      chatId: "123",
+      messageId: 1,
+      user: "alice",
+      userId: 1,
+      ts: Date.now(),
+      text: "hello",
+      meta: {},
+    };
+
+    const sent = server.sendToAgent("agent-a", msg);
+    expect(sent).toBe(true);
+    await wait(50);
+
+    expect(c1.onInbound).toHaveBeenCalledTimes(1);
+    expect(c2.onInbound).not.toHaveBeenCalled();
+  });
+
+  it("server sendToTopic routes to correct client", async () => {
+    const path = tmpSocket();
+    const { server } = makeServer(path);
+
+    const c1 = await makeClient(path, "agent-a", { topicId: 100 });
+    const c2 = await makeClient(path, "agent-b", { topicId: 200 });
+    await wait(50);
+
+    const msg: InboundMessage = {
+      type: "inbound",
+      chatId: "123",
+      messageId: 1,
+      user: "bob",
+      userId: 2,
+      ts: Date.now(),
+      text: "world",
+      meta: {},
+    };
+
+    const sent = server.sendToTopic(200, msg);
+    expect(sent).toBe(true);
+    await wait(50);
+
+    expect(c2.onInbound).toHaveBeenCalledTimes(1);
+    expect(c1.onInbound).not.toHaveBeenCalled();
+  });
+
+  it("client reconnects after server restart", async () => {
+    const path = tmpSocket();
+    const { server: server1, registered: registered1 } = makeServer(path);
+    const { client } = await makeClient(path, "resilient", {
+      reconnectDelayMs: 100,
+      maxReconnectDelayMs: 200,
+    });
+    await wait(50);
+
+    expect(registered1).toHaveBeenCalledTimes(1);
+
+    await server1.close();
+    servers.length = 0;
+    await wait(50);
+
+    expect(client.isConnected()).toBe(false);
+
+    const { server: server2, registered: registered2 } = makeServer(path);
+    await wait(500);
+
+    expect(client.isConnected()).toBe(true);
+    expect(registered2).toHaveBeenCalledTimes(1);
+    expect(registered2.mock.calls[0][0].agentName).toBe("resilient");
+  });
+
+  it("callTool timeout produces error", async () => {
+    const path = tmpSocket();
+    makeServer(path, {
+      onToolCall: async (_client, msg) => {
+        // Never respond — simulate a hung tool call
+        await new Promise(() => {});
+        return { type: "tool_call_result", id: msg.id, success: true };
+      },
+    });
+    const { client } = await makeClient(path, "timeout-test");
+    await wait(50);
+
+    await expect(client.callTool("slow_tool", {}, 200)).rejects.toThrow(/timed out/);
+  });
+
+  it("callTool when disconnected rejects immediately", async () => {
+    const path = tmpSocket();
+    makeServer(path);
+    const { client } = await makeClient(path, "disc-test");
+    await wait(50);
+
+    client.close();
+    await expect(client.callTool("reply", {})).rejects.toThrow(/not connected/);
+  });
+
+  it("heartbeat keeps connection alive and is received by server", async () => {
+    const path = tmpSocket();
+    const { heartbeatHandler } = makeServer(path);
+    await makeClient(path, "hb-agent", { heartbeatIntervalMs: 100 });
+    await wait(350);
+
+    expect(heartbeatHandler).toHaveBeenCalled();
+    const lastCall = heartbeatHandler.mock.calls[heartbeatHandler.mock.calls.length - 1];
+    expect(lastCall[1].agentName).toBe("hb-agent");
+  });
+
+  it("session events are forwarded to server", async () => {
+    const path = tmpSocket();
+    const { sessionEventHandler } = makeServer(path);
+    const { client } = await makeClient(path, "session-agent");
+    await wait(50);
+
+    const event: SessionEventForward = {
+      type: "session_event",
+      event: { type: "assistant", message: "test" },
+      chatId: "456",
+      threadId: 7,
+    };
+    client.sendSessionEvent(event);
+    await wait(50);
+
+    expect(sessionEventHandler).toHaveBeenCalledTimes(1);
+    expect(sessionEventHandler.mock.calls[0][1]).toEqual(event);
+  });
+
+  it("sendToAgent returns false for unknown agent", () => {
+    const path = tmpSocket();
+    const { server } = makeServer(path);
+    const result = server.sendToAgent("nonexistent", { type: "status", status: "agent_down" });
+    expect(result).toBe(false);
+  });
+
+  it("sendToTopic returns false for unknown topic", () => {
+    const path = tmpSocket();
+    const { server } = makeServer(path);
+    const result = server.sendToTopic(9999, { type: "status", status: "agent_down" });
+    expect(result).toBe(false);
+  });
+});

package/telegram-plugin/tests/ipc-server-race.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { mkdtempSync, writeFileSync, existsSync, statSync, renameSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { createIpcServer, type IpcServer, type IpcClient } from "../gateway/ipc-server.js";
+import type { ToolCallMessage, ToolCallResult } from "../gateway/ipc-protocol.js";
+
+/**
+ * Race-protection tests for the gateway IPC socket cleanup.
+ *
+ * Background (bug diagnosed 2026-04-24): a `systemctl restart` of the gateway
+ * could result in an orphaned Unix socket — the new gateway's bind was racing
+ * against the old gateway's delayed shutdown `unlinkSync`. If the old cleanup
+ * arrived after the new bind, it would delete the new socket's filesystem
+ * entry while the server kept listening on an unreachable inode.
+ *
+ * Fix: replace `unlinkSync(socketPath)` with `renameSync(socketPath, socketPath + ".bak")`
+ * both at startup (clean-slate) and at shutdown (cleanup). Rename-to-sidecar
+ * means a late cleanup moves the current file aside rather than destroying it,
+ * and startup-side unlink of the stale .bak prevents sidecars from piling up.
+ */
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ipc-race-test-"));
+  return join(dir, "test.sock");
+}
+
+function makeHandlers() {
+  const registered = vi.fn();
+  const disconnected = vi.fn();
+  const toolCallHandler = vi.fn(async (_client: IpcClient, msg: ToolCallMessage): Promise<ToolCallResult> => ({
+    type: "tool_call_result",
+    id: msg.id,
+    success: true,
+  }));
+  const sessionEventHandler = vi.fn();
+  const permissionRequestHandler = vi.fn();
+  const heartbeatHandler = vi.fn();
+  const scheduleRestartHandler = vi.fn();
+  return {
+    onClientRegistered: registered,
+    onClientDisconnected: disconnected,
+    onToolCall: toolCallHandler,
+    onSessionEvent: sessionEventHandler,
+    onPermissionRequest: permissionRequestHandler,
+    onHeartbeat: heartbeatHandler,
+    onScheduleRestart: scheduleRestartHandler,
+  };
+}
+
+describe("IPC server socket cleanup race protection", () => {
+  const servers: IpcServer[] = [];
+
+  afterEach(async () => {
+    for (const s of servers) {
+      try { await s.close(); } catch {}
+    }
+    servers.length = 0;
+  });
+
+  it("renames existing socket to .bak on startup before binding", () => {
+    const path = tmpSocket();
+    // Write a dummy file at the socket path to simulate a leftover entry.
+    writeFileSync(path, "leftover-from-prior-gateway");
+    expect(existsSync(path)).toBe(true);
+
+    const server = createIpcServer({ socketPath: path, ...makeHandlers() });
+    servers.push(server);
+
+    // After startup, the prior file has been renamed to .bak and then unlinked
+    // (stale-bak cleanup on startup). The live path must be a fresh socket.
+    expect(existsSync(path + ".bak")).toBe(false);
+    expect(existsSync(path)).toBe(true);
+    expect(statSync(path).isSocket()).toBe(true);
+  });
+
+  it("cleans up stale .bak on startup", () => {
+    const path = tmpSocket();
+    // Pre-seed both a stale live file and a stale .bak.
+    writeFileSync(path, "dummy-live");
+    writeFileSync(path + ".bak", "dummy-bak");
+    expect(existsSync(path)).toBe(true);
+    expect(existsSync(path + ".bak")).toBe(true);
+
+    const server = createIpcServer({ socketPath: path, ...makeHandlers() });
+    servers.push(server);
+
+    // Both prior files are gone; only the new socket exists.
+    expect(existsSync(path + ".bak")).toBe(false);
+    expect(existsSync(path)).toBe(true);
+    expect(statSync(path).isSocket()).toBe(true);
+  });
+
+  it("renames live socket to .bak on close (not unlink)", async () => {
+    const path = tmpSocket();
+    const server = createIpcServer({ socketPath: path, ...makeHandlers() });
+    expect(statSync(path).isSocket()).toBe(true);
+
+    await server.close();
+    servers.length = 0;
+
+    // After close, the live path is gone (renamed away). We accept either
+    // outcome for the .bak — existence or absence — as long as the live
+    // entry is no longer present.
+    expect(existsSync(path)).toBe(false);
+  });
+
+  // SKIP: flaky under bun (passes 5/5 locally but consistently fails on CI agent).
+  // The test documents a "residual gap" in the rename-to-sidecar cleanup —
+  // an actual race the existing code accepts (see the lenient assertion at
+  // the end). Re-enable once we either fix the underlying race or stabilise
+  // the test under bun's IO timing. Tracked as a follow-up.
+  it.skip("concurrent-restart race: old close after new bind does not remove new's live entry", async () => {
+    const path = tmpSocket();
+
+    // 1. Old gateway (A) binds.
+    const serverA = createIpcServer({ socketPath: path, ...makeHandlers() });
+    servers.push(serverA);
+    expect(statSync(path).isSocket()).toBe(true);
+
+    // 2. Simulate the old gateway's normal shutdown: it renames its live
+    //    socket to .bak before exit (the fix's shutdown behavior).
+    renameSync(path, path + ".bak");
+    expect(existsSync(path)).toBe(false);
+    expect(existsSync(path + ".bak")).toBe(true);
+
+    // 3. New gateway (B) starts and binds to the same path. Its startup
+    //    logic unlinks the stale .bak and binds fresh.
+    const serverB = createIpcServer({ socketPath: path, ...makeHandlers() });
+    servers.push(serverB);
+    expect(statSync(path).isSocket()).toBe(true);
+    expect(existsSync(path + ".bak")).toBe(false);
+
+    // 4. Now fire off A's delayed close — this is the race scenario: the old
+    //    gateway's shutdown cleanup arrives AFTER the new gateway is already
+    //    listening.
+    await serverA.close();
+
+    // The failure mode the fix is chasing: A's cleanup must NOT leave B's
+    // live socket entry missing. With rename-to-.bak, A's delayed rename
+    // moves B's live file to .bak — which is still wrong: B is now orphaned.
+    // This test documents the residual gap. The orphan recovery path is:
+    // on the NEXT restart, startup-side rename + stale-.bak-unlink heals it.
+    const liveExists = existsSync(path);
+    const bakExists = existsSync(path + ".bak");
+
+    // Lenient assertion: either the live entry survived (ideal outcome when
+    // rename fails because target already exists, which is platform-dependent),
+    // OR the .bak exists (meaning A clobbered B's live file — residual gap,
+    // self-heals on next startup).
+    //
+    // The hard assertion we DO make: we have NOT lost both files. The live
+    // path is never both missing AND without a .bak backup — that would be
+    // the original bug where unlinkSync destroyed the file outright.
+    expect(liveExists || bakExists).toBe(true);
+  });
+
+  it("missing socket path on startup: no-op (no error)", () => {
+    const path = tmpSocket();
+    // Path intentionally does not exist yet.
+    expect(existsSync(path)).toBe(false);
+
+    // Must not throw.
+    const server = createIpcServer({ socketPath: path, ...makeHandlers() });
+    servers.push(server);
+
+    expect(statSync(path).isSocket()).toBe(true);
+  });
+
+  it("missing socket path on close: no-op (no error)", async () => {
+    const path = tmpSocket();
+    const server = createIpcServer({ socketPath: path, ...makeHandlers() });
+
+    // Manually remove the socket before close to simulate a torn-down path.
+    try { renameSync(path, path + ".bak"); } catch {}
+    // Remove the .bak too so close has nothing to act on.
+    try { const { unlinkSync } = await import("fs"); unlinkSync(path + ".bak"); } catch {}
+
+    // Close must not throw even though the socket path is gone.
+    await expect(server.close()).resolves.toBeUndefined();
+    servers.length = 0;
+  });
+});

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

@@ -0,0 +1,91 @@
+/**
+ * Tightened operator_event validation in `validateClientMessage`
+ * (Phase 4c wiring — issue #30 task 2).
+ *
+ * The Phase 4b shape check accepted any non-empty kind/agent string. With
+ * the producer side now actually wired (bridge → IPC), the gateway needs
+ * a stricter gate so a misbehaving or compromised bridge can't:
+ *   - inject an unknown `kind` that crashes the renderer at switch-default
+ *   - send an agent name that bypasses systemctl-arg sanity (the same
+ *     regex as `assertSafeAgentName`)
+ *   - flood the gateway journal with a giant `detail` payload
+ */
+
+import { describe, it, expect } from 'vitest'
+import { validateClientMessage } from '../gateway/ipc-server.js'
+
+const VALID_KINDS = [
+  'credentials-expired',
+  'credentials-invalid',
+  'credit-exhausted',
+  'quota-exhausted',
+  'rate-limited',
+  'agent-crashed',
+  'agent-restarted-unexpectedly',
+  'unknown-4xx',
+  'unknown-5xx',
+]
+
+function base() {
+  return {
+    type: 'operator_event' as const,
+    kind: 'credentials-expired',
+    agent: 'gymbro',
+    detail: 'token expired at 2026-04-27',
+    chatId: '',
+  }
+}
+
+describe('validateClientMessage — operator_event', () => {
+  it('accepts every taxonomy kind', () => {
+    for (const kind of VALID_KINDS) {
+      expect(validateClientMessage({ ...base(), kind })).toBe(true)
+    }
+  })
+
+  it('rejects unknown kinds', () => {
+    expect(validateClientMessage({ ...base(), kind: 'something-else' })).toBe(false)
+    expect(validateClientMessage({ ...base(), kind: '' })).toBe(false)
+    expect(validateClientMessage({ ...base(), kind: 'CREDENTIALS-EXPIRED' })).toBe(false)
+  })
+
+  it('accepts well-formed agent names', () => {
+    for (const agent of ['gymbro', 'a', 'a1', 'agent-1', 'a_b', '0xff']) {
+      expect(validateClientMessage({ ...base(), agent })).toBe(true)
+    }
+  })
+
+  it('rejects malformed agent names', () => {
+    // leading hyphen would let `switchroom-${agent}` look like a flag
+    expect(validateClientMessage({ ...base(), agent: '-bad' })).toBe(false)
+    // uppercase, spaces, slashes, semicolons all rejected — the regex
+    // is the same one `assertSafeAgentName` uses for systemctl arg safety
+    expect(validateClientMessage({ ...base(), agent: 'BadName' })).toBe(false)
+    expect(validateClientMessage({ ...base(), agent: 'a b' })).toBe(false)
+    expect(validateClientMessage({ ...base(), agent: '../etc' })).toBe(false)
+    expect(validateClientMessage({ ...base(), agent: 'a;rm' })).toBe(false)
+    expect(validateClientMessage({ ...base(), agent: '' })).toBe(false)
+    // Over the 51-char cap (1 leading + 50 trailing)
+    expect(validateClientMessage({ ...base(), agent: 'a' + 'b'.repeat(51) })).toBe(false)
+  })
+
+  it('caps detail at 1000 chars', () => {
+    expect(validateClientMessage({ ...base(), detail: 'x'.repeat(1000) })).toBe(true)
+    expect(validateClientMessage({ ...base(), detail: 'x'.repeat(1001) })).toBe(false)
+  })
+
+  it('requires chatId to be a string (may be empty)', () => {
+    expect(validateClientMessage({ ...base(), chatId: '' })).toBe(true)
+    expect(validateClientMessage({ ...base(), chatId: '12345' })).toBe(true)
+    const noChat = { ...base() } as Record<string, unknown>
+    delete noChat.chatId
+    expect(validateClientMessage(noChat)).toBe(false)
+    expect(validateClientMessage({ ...base(), chatId: 12345 })).toBe(false)
+  })
+
+  it('rejects wrong types on every field', () => {
+    expect(validateClientMessage({ ...base(), kind: 42 })).toBe(false)
+    expect(validateClientMessage({ ...base(), agent: null })).toBe(false)
+    expect(validateClientMessage({ ...base(), detail: null })).toBe(false)
+  })
+})