feat: implement WebSocket handler and event system

package.json

@@ -51,11 +51,13 @@
     "nanoid": "^5.1.5",
     "proper-lockfile": "^4.1.2",
     "write-file-atomic": "^7.0.0",
+    "ws": "^8.19.0",
     "yaml": "^2.7.1"
   },
   "devDependencies": {
     "@types/node": "^22.13.4",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/ws": "^8.18.1",
     "tsup": "^8.4.0",
     "tsx": "^4.19.3",
     "typescript": "^5.7.3",

src/commands/spawn.test.ts

@@ -6,6 +6,7 @@ import { readManifest, resolveWorktree, updateManifest } from '../core/manifest.
 import { spawnAgent } from '../core/agent.js';
 import { getRepoRoot } from '../core/worktree.js';
 import { agentId, sessionId } from '../lib/id.js';
+import type { Manifest } from '../types/manifest.js';
 import * as tmux from '../core/tmux.js';
 
 vi.mock('node:fs/promises', async () => {
@@ -79,7 +80,7 @@ const mockedEnsureSession = vi.mocked(tmux.ensureSession);
 const mockedCreateWindow = vi.mocked(tmux.createWindow);
 const mockedSplitPane = vi.mocked(tmux.splitPane);
 
-function createManifest(tmuxWindow = '') {
+function createManifest(tmuxWindow = ''): Manifest {
   return {
     version: 1 as const,
     projectRoot: '/tmp/repo',
@@ -103,7 +104,7 @@ function createManifest(tmuxWindow = '') {
 }
 
 describe('spawnCommand', () => {
-  let manifestState = createManifest();
+  let manifestState: Manifest = createManifest();
   let nextAgent = 1;
   let nextSession = 1;
 

src/server/ws/events.ts

@@ -0,0 +1,110 @@
+import type { AgentStatus, Manifest, WorktreeStatus } from '../../types/manifest.js';
+
+// --- Inbound Commands (client → server) ---
+
+export interface PingCommand {
+  type: 'ping';
+}
+
+export interface TerminalSubscribeCommand {
+  type: 'terminal:subscribe';
+  agentId: string;
+}
+
+export interface TerminalUnsubscribeCommand {
+  type: 'terminal:unsubscribe';
+  agentId: string;
+}
+
+export interface TerminalInputCommand {
+  type: 'terminal:input';
+  agentId: string;
+  data: string;
+}
+
+export type ClientCommand =
+  | PingCommand
+  | TerminalSubscribeCommand
+  | TerminalUnsubscribeCommand
+  | TerminalInputCommand;
+
+// --- Outbound Events (server → client) ---
+
+export interface PongEvent {
+  type: 'pong';
+}
+
+export interface ManifestUpdatedEvent {
+  type: 'manifest:updated';
+  manifest: Manifest;
+}
+
+export interface AgentStatusEvent {
+  type: 'agent:status';
+  worktreeId: string;
+  agentId: string;
+  status: AgentStatus;
+  worktreeStatus: WorktreeStatus;
+}
+
+export interface TerminalOutputEvent {
+  type: 'terminal:output';
+  agentId: string;
+  data: string;
+}
+
+export interface ErrorEvent {
+  type: 'error';
+  code: string;
+  message: string;
+}
+
+export type ServerEvent =
+  | PongEvent
+  | ManifestUpdatedEvent
+  | AgentStatusEvent
+  | TerminalOutputEvent
+  | ErrorEvent;
+
+// --- Parsing ---
+
+const VALID_COMMAND_TYPES = new Set([
+  'ping',
+  'terminal:subscribe',
+  'terminal:unsubscribe',
+  'terminal:input',
+]);
+
+export function parseCommand(raw: string): ClientCommand | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) return null;
+
+  const obj = parsed as Record<string, unknown>;
+  if (typeof obj.type !== 'string' || !VALID_COMMAND_TYPES.has(obj.type)) return null;
+
+  if (obj.type === 'ping') {
+    return { type: 'ping' };
+  }
+
+  if (obj.type === 'terminal:subscribe' || obj.type === 'terminal:unsubscribe') {
+    if (typeof obj.agentId !== 'string') return null;
+    return { type: obj.type, agentId: obj.agentId };
+  }
+
+  if (obj.type === 'terminal:input') {
+    if (typeof obj.agentId !== 'string' || typeof obj.data !== 'string') return null;
+    return { type: 'terminal:input', agentId: obj.agentId, data: obj.data };
+  }
+
+  return null;
+}
+
+export function serializeEvent(event: ServerEvent): string {
+  return JSON.stringify(event);
+}