@johpaz/hive-orchestrator 1.0.8

package/README.md

@@ -0,0 +1,78 @@
+# @johpaz/orchestrator
+
+Subagent CLI Orchestrator for the Hive ecosystem. Exposes a **local WebSocket mesh** (via `Bun.serve`) that spawns and supervises CLI AI tools (e.g. `opencode`, `gemini`, `qwen`) as child processes, streaming their output and telemetry to any connected dashboard client.
+
+## Architecture
+
+```
+Dashboard (Angular) ──WS──► @johpaz/orchestrator ──Bun.spawn──► CLI tool (opencode / gemini / qwen…)
+                                                    ◄──WS──── telemetry events (stdout chunks, progress, tokens)
+```
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `src/index.ts` | Bun.serve entry point — HTTP health + WebSocket handler |
+| `src/schemas.ts` | Zod schemas: `AgentRole`, `SubagentConfig`, `TelemetryEvent`, `DashboardCommand` |
+| `src/process-manager.ts` | Spawns/kills processes, streams stdout/stderr, parses `HIVE_PROGRESS` and `HIVE_TOKENS` hints |
+
+## Running
+
+```bash
+# From the monorepo root:
+bun run packages/orchestrator/src/index.ts
+
+# Or from this package:
+bun run src/index.ts
+```
+
+Server starts on `ws://localhost:18791` by default (`ORCHESTRATOR_PORT` env override).
+
+## WebSocket Protocol
+
+### Dashboard → Orchestrator
+
+```jsonc
+// Launch a CLI subagent
+{ "cmd": "launch", "taskId": "uuid", "prompt": "Refactor auth module", "config": { "role": "development", "cli": "opencode" } }
+
+// Cancel a running agent
+{ "cmd": "cancel", "taskId": "uuid" }
+
+// Request current status snapshot
+{ "cmd": "status" }
+```
+
+### Orchestrator → Dashboard (broadcast)
+
+| Event type | Description |
+|---|---|
+| `orchestrator:status` | Full snapshot of all agents (sent on connect and on `status` command) |
+| `agent:started` | Process PID and CLI tool |
+| `agent:output` | stdout/stderr chunk |
+| `agent:progress` | 0–100 percent (from `HIVE_PROGRESS:<n>` in stdout) |
+| `agent:token_usage` | Token counters + model (from `HIVE_TOKENS:input=<n>,output=<n>,model=<name>`) |
+| `agent:finished` | Exit code |
+| `agent:cancelled` | Cancelled by dashboard |
+| `agent:error` | Non-zero exit or spawn error |
+
+## HIVE Protocol Hints
+
+CLI tools can emit structured hints in their stdout to feed the dashboard:
+
+```
+HIVE_PROGRESS:42
+HIVE_TOKENS:input=1200,output=350,model=gemini-2.0-flash
+```
+
+## Tests
+
+```bash
+bun test src/schemas.test.ts
+bun test src/process-manager.test.ts
+# or all at once:
+bun test
+```
+
+Tests cover: schema validation, launch/cancel lifecycle, stdout streaming, progress/token hint parsing.

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@johpaz/hive-orchestrator",
+  "version": "1.0.8",
+  "description": "Subagent CLI Orchestrator and WebSocket Mesh local server",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "@johpaz/hive-mcp": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@johpaz/hive-core": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+import { ProcessManager } from "./process-manager.ts";
+import { DashboardCommand } from "./schemas.ts";
+
+const ORCHESTRATOR_PORT = parseInt(process.env.ORCHESTRATOR_PORT ?? "18791", 10);
+
+const manager = new ProcessManager();
+
+const server = Bun.serve<{ id: string }>({
+    port: ORCHESTRATOR_PORT,
+
+    // ── HTTP routes ──────────────────────────────────────────────────────────
+    fetch(req, server) {
+        const url = new URL(req.url);
+
+        // Upgrade WebSocket connections
+        if (url.pathname === "/ws") {
+            const id = crypto.randomUUID();
+            const upgraded = server.upgrade(req, { data: { id } });
+            if (upgraded) return undefined;
+            return new Response("WebSocket upgrade failed", { status: 400 });
+        }
+
+        // Simple REST ping
+        if (url.pathname === "/health") {
+            return new Response(JSON.stringify({ ok: true, port: ORCHESTRATOR_PORT }), {
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+
+        // Status snapshot (REST fallback for the dashboard initial load)
+        if (url.pathname === "/status") {
+            return new Response(JSON.stringify(manager.status()), {
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+
+        return new Response("Not found", { status: 404 });
+    },
+
+    // ── WebSocket handlers ───────────────────────────────────────────────────
+    websocket: {
+        open(ws) {
+            manager.subscribe(ws);
+            // Immediately send the current snapshot to the newly connected client
+            ws.send(JSON.stringify(manager.status()));
+        },
+
+        async message(ws, raw) {
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(typeof raw === "string" ? raw : new TextDecoder().decode(raw));
+            } catch {
+                ws.send(JSON.stringify({ type: "error", message: "Invalid JSON" }));
+                return;
+            }
+
+            const cmd = DashboardCommand.safeParse(parsed);
+            if (!cmd.success) {
+                ws.send(JSON.stringify({ type: "error", message: cmd.error.message }));
+                return;
+            }
+
+            const command = cmd.data;
+
+            switch (command.cmd) {
+                case "launch": {
+                    try {
+                        const pid = await manager.launch(command.taskId, command.config, command.prompt);
+                        ws.send(JSON.stringify({ type: "ack", cmd: "launch", taskId: command.taskId, pid }));
+                    } catch (err: any) {
+                        ws.send(JSON.stringify({ type: "error", message: err.message }));
+                    }
+                    break;
+                }
+
+                case "cancel": {
+                    const ok = manager.cancel(command.taskId);
+                    ws.send(JSON.stringify({ type: "ack", cmd: "cancel", taskId: command.taskId, ok }));
+                    break;
+                }
+
+                case "status": {
+                    ws.send(JSON.stringify(manager.status()));
+                    break;
+                }
+            }
+        },
+
+        close(ws) {
+            manager.unsubscribe(ws);
+        },
+    },
+});
+
+console.log(`🐝 Hive Orchestrator running on ws://localhost:${server.port}`);

package/src/process-manager.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { ProcessManager } from "./process-manager.ts";
+
+describe("ProcessManager", () => {
+    let manager: ProcessManager;
+    const capturedEvents: any[] = [];
+
+    // We mock a WebSocket-like subscriber
+    const mockWs = {
+        id: "test-ws",
+        send(payload: string) {
+            capturedEvents.push(JSON.parse(payload));
+        },
+    } as any;
+
+    beforeEach(() => {
+        manager = new ProcessManager();
+        capturedEvents.length = 0;
+        manager.subscribe(mockWs);
+    });
+
+    afterEach(() => {
+        manager.unsubscribe(mockWs);
+    });
+
+    it("initial status has no agents", () => {
+        const status = manager.status();
+        expect(status.type).toBe("orchestrator:status");
+        expect(status.agents).toHaveLength(0);
+    });
+
+    it("launches a simple process and receives started event", async () => {
+        const taskId = "test-task-1";
+        const pid = await manager.launch(
+            taskId,
+            { role: "development", cli: "echo", args: ["hello"], timeoutSeconds: 10 },
+            "" // empty prompt sent to stdin
+        );
+
+        expect(typeof pid).toBe("number");
+        expect(pid).toBeGreaterThan(0);
+
+        // agent:started should be the first broadcast
+        expect(capturedEvents[0].type).toBe("agent:started");
+        expect(capturedEvents[0].taskId).toBe(taskId);
+        expect(capturedEvents[0].cli).toBe("echo");
+
+        // Wait for echo to finish
+        await Bun.sleep(200);
+
+        // Verify status reflects the finished agent
+        const status = manager.status();
+        const agent = status.agents.find((a) => a.taskId === taskId);
+        expect(agent).toBeDefined();
+        expect(agent!.state).toBe("finished");
+    });
+
+    it("throws if same taskId is launched twice", async () => {
+        const taskId = "test-task-dup";
+        await manager.launch(
+            taskId,
+            { role: "testing", cli: "sleep", args: ["1"], timeoutSeconds: 10 },
+            ""
+        );
+
+        expect(
+            manager.launch(taskId, { role: "testing", cli: "sleep", args: ["1"], timeoutSeconds: 10 }, "")
+        ).rejects.toThrow(`Task ${taskId} is already running`);
+
+        manager.cancel(taskId);
+    });
+
+    it("can cancel a running process", async () => {
+        const taskId = "test-task-cancel";
+        await manager.launch(
+            taskId,
+            { role: "architecture", cli: "sleep", args: ["30"], timeoutSeconds: 60 },
+            ""
+        );
+
+        const cancelled = manager.cancel(taskId);
+        expect(cancelled).toBe(true);
+
+        await Bun.sleep(100);
+
+        const cancelEvent = capturedEvents.find((e) => e.type === "agent:cancelled");
+        expect(cancelEvent).toBeDefined();
+        expect(cancelEvent.taskId).toBe(taskId);
+
+        const status = manager.status();
+        const agent = status.agents.find((a) => a.taskId === taskId);
+        expect(agent!.state).toBe("cancelled");
+    });
+
+    it("returns false when cancelling a non-existent task", () => {
+        const result = manager.cancel("non-existent-task");
+        expect(result).toBe(false);
+    });
+
+    it("broadcasts output chunks from stdout", async () => {
+        const taskId = "test-task-output";
+        await manager.launch(
+            taskId,
+            { role: "documentation", cli: "echo", args: ["HIVE_TEST_OUTPUT"], timeoutSeconds: 10 },
+            ""
+        );
+
+        await Bun.sleep(300);
+
+        const outputEvents = capturedEvents.filter((e) => e.type === "agent:output" && e.taskId === taskId);
+        expect(outputEvents.length).toBeGreaterThan(0);
+        const combined = outputEvents.map((e) => e.chunk).join("");
+        expect(combined).toContain("HIVE_TEST_OUTPUT");
+    });
+
+    it("parses HIVE_PROGRESS hints from stdout", async () => {
+        const taskId = "test-task-progress";
+        // We use printf to emit a progress hint
+        await manager.launch(
+            taskId,
+            { role: "testing", cli: "sh", args: ["-c", "printf 'HIVE_PROGRESS:75\\n'"], timeoutSeconds: 10 },
+            ""
+        );
+
+        await Bun.sleep(300);
+
+        const progressEvents = capturedEvents.filter(
+            (e) => e.type === "agent:progress" && e.taskId === taskId
+        );
+        expect(progressEvents.length).toBeGreaterThan(0);
+        expect(progressEvents[0].percent).toBe(75);
+
+        const status = manager.status();
+        const agent = status.agents.find((a) => a.taskId === taskId);
+        expect(agent!.progress).toBe(75);
+    });
+
+    it("parses HIVE_TOKENS hints from stdout", async () => {
+        const taskId = "test-task-tokens";
+        await manager.launch(
+            taskId,
+            {
+                role: "development",
+                cli: "sh",
+                args: ["-c", "printf 'HIVE_TOKENS:input=150,output=300,model=gemini-2.0-flash\\n'"],
+                timeoutSeconds: 10,
+            },
+            ""
+        );
+
+        await Bun.sleep(300);
+
+        const tokenEvents = capturedEvents.filter(
+            (e) => e.type === "agent:token_usage" && e.taskId === taskId
+        );
+        expect(tokenEvents.length).toBeGreaterThan(0);
+        expect(tokenEvents[0].inputTokens).toBe(150);
+        expect(tokenEvents[0].outputTokens).toBe(300);
+        expect(tokenEvents[0].model).toBe("gemini-2.0-flash");
+    });
+
+    it("status reflects all running agents", async () => {
+        await manager.launch("t-a", { role: "development", cli: "sleep", args: ["2"], timeoutSeconds: 10 }, "");
+        await manager.launch("t-b", { role: "testing", cli: "sleep", args: ["2"], timeoutSeconds: 10 }, "");
+
+        const status = manager.status();
+        expect(status.agents).toHaveLength(2);
+
+        manager.cancel("t-a");
+        manager.cancel("t-b");
+    });
+});

package/src/process-manager.ts

@@ -0,0 +1,212 @@
+import type { ServerWebSocket } from "bun";
+import type { SubagentConfig, TelemetryEvent } from "./schemas.ts";
+import { AgentRole } from "./schemas.ts";
+
+/** Live record of a running subagent process */
+interface AgentRecord {
+    taskId: string;
+    config: SubagentConfig;
+    pid: number;
+    proc: ReturnType<typeof Bun.spawn>;
+    state: "running" | "finished" | "cancelled" | "error";
+    progress: number;
+    tokens: { input: number; output: number };
+    model?: string;
+    startedAt: number;
+}
+
+type WsData = { id: string };
+
+export class ProcessManager {
+    private agents = new Map<string, AgentRecord>();
+    private sockets = new Set<ServerWebSocket<WsData>>();
+
+    // ── Socket subscription ──────────────────────────────────────────────────
+
+    subscribe(ws: ServerWebSocket<WsData>) {
+        this.sockets.add(ws);
+    }
+
+    unsubscribe(ws: ServerWebSocket<WsData>) {
+        this.sockets.delete(ws);
+    }
+
+    private broadcast(event: TelemetryEvent) {
+        const payload = JSON.stringify(event);
+        for (const ws of this.sockets) {
+            try {
+                ws.send(payload);
+            } catch {
+                this.sockets.delete(ws);
+            }
+        }
+    }
+
+    // ── Launch ───────────────────────────────────────────────────────────────
+
+    async launch(taskId: string, config: SubagentConfig, prompt: string) {
+        if (this.agents.has(taskId)) {
+            throw new Error(`Task ${taskId} is already running`);
+        }
+
+        const args = [config.cli, ...config.args];
+        const proc = Bun.spawn(args, {
+            cwd: config.cwd ?? process.cwd(),
+            stdin: "pipe",
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, HIVE_ROLE: config.role },
+        });
+
+        const record: AgentRecord = {
+            taskId,
+            config,
+            pid: proc.pid,
+            proc,
+            state: "running",
+            progress: 0,
+            tokens: { input: 0, output: 0 },
+            startedAt: Date.now(),
+        };
+
+        this.agents.set(taskId, record);
+
+        this.broadcast({
+            type: "agent:started",
+            ts: Date.now(),
+            role: config.role,
+            pid: proc.pid,
+            cli: config.cli,
+            taskId,
+        });
+
+        // Write the prompt to stdin then close it
+        proc.stdin.write(prompt);
+        proc.stdin.end();
+
+        // Stream stdout
+        this.pipeStream(record, proc.stdout, "stdout");
+        // Stream stderr
+        this.pipeStream(record, proc.stderr, "stderr");
+
+        // Wait for process exit
+        proc.exited.then((exitCode) => {
+            const r = this.agents.get(taskId);
+            if (!r || r.state === "cancelled") return;
+            r.state = exitCode === 0 ? "finished" : "error";
+            if (exitCode === 0) {
+                this.broadcast({
+                    type: "agent:finished",
+                    ts: Date.now(),
+                    role: config.role,
+                    taskId,
+                    exitCode,
+                });
+            } else {
+                this.broadcast({
+                    type: "agent:error",
+                    ts: Date.now(),
+                    role: config.role,
+                    taskId,
+                    message: `Process exited with code ${exitCode}`,
+                });
+            }
+        });
+
+        return record.pid;
+    }
+
+    // ── Cancel ───────────────────────────────────────────────────────────────
+
+    cancel(taskId: string) {
+        const record = this.agents.get(taskId);
+        if (!record) return false;
+        record.state = "cancelled";
+        record.proc.kill();
+        this.broadcast({
+            type: "agent:cancelled",
+            ts: Date.now(),
+            role: record.config.role,
+            taskId,
+        });
+        return true;
+    }
+
+    // ── Status snapshot ──────────────────────────────────────────────────────
+
+    status(): TelemetryEvent {
+        return {
+            type: "orchestrator:status",
+            ts: Date.now(),
+            agents: [...this.agents.values()].map((r) => ({
+                taskId: r.taskId,
+                role: r.config.role,
+                cli: r.config.cli,
+                pid: r.pid,
+                state: r.state,
+                progress: r.progress,
+                tokens: r.tokens,
+                model: r.model,
+            })),
+        };
+    }
+
+    // ── Helpers ──────────────────────────────────────────────────────────────
+
+    private async pipeStream(
+        record: AgentRecord,
+        stream: ReadableStream<Uint8Array>,
+        kind: "stdout" | "stderr"
+    ) {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                const chunk = decoder.decode(value);
+
+                // Parse progress hints: lines containing "HIVE_PROGRESS:<n>"
+                for (const line of chunk.split("\n")) {
+                    const m = line.match(/HIVE_PROGRESS:(\d+)/);
+                    if (m) {
+                        record.progress = Math.min(100, parseInt(m[1], 10));
+                        this.broadcast({
+                            type: "agent:progress",
+                            ts: Date.now(),
+                            role: record.config.role,
+                            taskId: record.taskId,
+                            percent: record.progress,
+                        });
+                    }
+                    // Parse token hints: "HIVE_TOKENS:input=<n>,output=<n>,model=<name>"
+                    const t = line.match(/HIVE_TOKENS:input=(\d+),output=(\d+)(?:,model=(.+))?/);
+                    if (t) {
+                        record.tokens = { input: parseInt(t[1], 10), output: parseInt(t[2], 10) };
+                        if (t[3]) record.model = t[3].trim();
+                        this.broadcast({
+                            type: "agent:token_usage",
+                            ts: Date.now(),
+                            role: record.config.role,
+                            taskId: record.taskId,
+                            inputTokens: record.tokens.input,
+                            outputTokens: record.tokens.output,
+                            model: record.model ?? "unknown",
+                        });
+                    }
+                }
+
+                this.broadcast({
+                    type: "agent:output",
+                    ts: Date.now(),
+                    role: record.config.role,
+                    taskId: record.taskId,
+                    stream: kind,
+                    chunk,
+                });
+            }
+        } catch {
+            // stream closed
+        }
+    }
+}

package/src/schemas.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import {
+    AgentRole,
+    SubagentConfig,
+    DashboardCommand,
+    TelemetryEvent,
+    AgentStartedEvent,
+    AgentOutputEvent,
+    AgentProgressEvent,
+    AgentTokenUsageEvent,
+    AgentFinishedEvent,
+    AgentErrorEvent,
+    AgentCancelledEvent,
+    OrchestratorStatusEvent,
+} from "./schemas.ts";
+
+// ─── AgentRole ───────────────────────────────────────────────────────────────
+
+describe("AgentRole", () => {
+    it("accepts all valid roles", () => {
+        const roles = ["architecture", "development", "testing", "documentation"] as const;
+        for (const role of roles) {
+            expect(AgentRole.parse(role)).toBe(role);
+        }
+    });
+
+    it("rejects unknown roles", () => {
+        expect(() => AgentRole.parse("design")).toThrow();
+        expect(() => AgentRole.parse("")).toThrow();
+        expect(() => AgentRole.parse(123)).toThrow();
+    });
+});
+
+// ─── SubagentConfig ──────────────────────────────────────────────────────────
+
+describe("SubagentConfig", () => {
+    it("parses a minimal config with defaults", () => {
+        const result = SubagentConfig.parse({ role: "development", cli: "opencode" });
+        expect(result.role).toBe("development");
+        expect(result.cli).toBe("opencode");
+        expect(result.args).toEqual([]);
+        expect(result.timeoutSeconds).toBe(600);
+        expect(result.cwd).toBeUndefined();
+    });
+
+    it("parses a full config", () => {
+        const result = SubagentConfig.parse({
+            role: "architecture",
+            cli: "gemini",
+            args: ["--model", "gemini-2.0-flash"],
+            cwd: "/tmp/project",
+            timeoutSeconds: 300,
+        });
+        expect(result.args).toEqual(["--model", "gemini-2.0-flash"]);
+        expect(result.cwd).toBe("/tmp/project");
+        expect(result.timeoutSeconds).toBe(300);
+    });
+
+    it("rejects missing required fields", () => {
+        expect(() => SubagentConfig.parse({ cli: "opencode" })).toThrow(); // missing role
+        expect(() => SubagentConfig.parse({ role: "development" })).toThrow(); // missing cli
+    });
+});
+
+// ─── TelemetryEvent discriminated union ─────────────────────────────────────
+
+describe("TelemetryEvent", () => {
+    const base = { ts: Date.now(), role: "development" as const, taskId: "t-123" };
+
+    it("parses agent:started", () => {
+        const ev = TelemetryEvent.parse({ ...base, type: "agent:started", pid: 9999, cli: "opencode" });
+        expect(ev.type).toBe("agent:started");
+        if (ev.type === "agent:started") expect(ev.pid).toBe(9999);
+    });
+
+    it("parses agent:output for stdout", () => {
+        const ev = TelemetryEvent.parse({ ...base, type: "agent:output", stream: "stdout", chunk: "Hello" });
+        expect(ev.type).toBe("agent:output");
+        if (ev.type === "agent:output") {
+            expect(ev.chunk).toBe("Hello");
+            expect(ev.stream).toBe("stdout");
+        }
+    });
+
+    it("parses agent:output for stderr", () => {
+        const ev = TelemetryEvent.parse({ ...base, type: "agent:output", stream: "stderr", chunk: "error msg" });
+        if (ev.type === "agent:output") expect(ev.stream).toBe("stderr");
+    });
+
+    it("parses agent:progress", () => {
+        const ev = TelemetryEvent.parse({ ...base, type: "agent:progress", percent: 42 });
+        if (ev.type === "agent:progress") expect(ev.percent).toBe(42);
+    });
+
+    it("rejects progress > 100", () => {
+        expect(() => TelemetryEvent.parse({ ...base, type: "agent:progress", percent: 101 })).toThrow();
+    });
+
+    it("rejects progress < 0", () => {
+        expect(() => TelemetryEvent.parse({ ...base, type: "agent:progress", percent: -1 })).toThrow();
+    });
+
+    it("parses agent:token_usage", () => {
+        const ev = TelemetryEvent.parse({
+            ...base,
+            type: "agent:token_usage",
+            inputTokens: 100,
+            outputTokens: 200,
+            model: "gemini-2.0-flash",
+        });
+        if (ev.type === "agent:token_usage") {
+            expect(ev.inputTokens).toBe(100);
+            expect(ev.model).toBe("gemini-2.0-flash");
+        }
+    });
+
+    it("parses agent:finished", () => {
+        const ev = TelemetryEvent.parse({ ...base, type: "agent:finished", exitCode: 0 });
+        if (ev.type === "agent:finished") expect(ev.exitCode).toBe(0);
+    });
+
+    it("parses agent:error", () => {
+        const ev = TelemetryEvent.parse({ ...base, type: "agent:error", message: "crash" });
+        if (ev.type === "agent:error") expect(ev.message).toBe("crash");
+    });
+
+    it("parses agent:cancelled", () => {
+        const ev = TelemetryEvent.parse({ ...base, type: "agent:cancelled" });
+        expect(ev.type).toBe("agent:cancelled");
+    });
+
+    it("parses orchestrator:status", () => {
+        const ev = TelemetryEvent.parse({
+            type: "orchestrator:status",
+            ts: Date.now(),
+            agents: [
+                {
+                    taskId: "t-1",
+                    role: "development",
+                    cli: "opencode",
+                    pid: 1234,
+                    state: "running",
+                    progress: 50,
+                    tokens: { input: 10, output: 20 },
+                },
+            ],
+        });
+        expect(ev.type).toBe("orchestrator:status");
+        if (ev.type === "orchestrator:status") {
+            expect(ev.agents).toHaveLength(1);
+            expect(ev.agents[0].state).toBe("running");
+        }
+    });
+
+    it("rejects unknown event types", () => {
+        expect(() => TelemetryEvent.parse({ ...base, type: "agent:unknown" })).toThrow();
+    });
+});
+
+// ─── DashboardCommand ────────────────────────────────────────────────────────
+
+describe("DashboardCommand", () => {
+    it("parses launch command", () => {
+        const cmd = DashboardCommand.parse({
+            cmd: "launch",
+            taskId: "t-456",
+            prompt: "Refactor auth module",
+            config: { role: "development", cli: "opencode" },
+        });
+        expect(cmd.cmd).toBe("launch");
+        if (cmd.cmd === "launch") expect(cmd.prompt).toBe("Refactor auth module");
+    });
+
+    it("parses cancel command", () => {
+        const cmd = DashboardCommand.parse({ cmd: "cancel", taskId: "t-456" });
+        expect(cmd.cmd).toBe("cancel");
+    });
+
+    it("parses status command", () => {
+        const cmd = DashboardCommand.parse({ cmd: "status" });
+        expect(cmd.cmd).toBe("status");
+    });
+
+    it("rejects launch without required fields", () => {
+        expect(() => DashboardCommand.parse({ cmd: "launch" })).toThrow(); // missing taskId, prompt, config
+    });
+
+    it("rejects launch with invalid role", () => {
+        expect(() =>
+            DashboardCommand.parse({
+                cmd: "launch",
+                taskId: "t-1",
+                prompt: "test",
+                config: { role: "finance", cli: "opencode" }, // invalid role
+            })
+        ).toThrow();
+    });
+});

package/src/schemas.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+
+// ─── Agent Roles ────────────────────────────────────────────────────────────
+
+export const AgentRole = z.enum([
+    "architecture",
+    "development",
+    "testing",
+    "documentation",
+]);
+export type AgentRole = z.infer<typeof AgentRole>;
+
+// ─── Subagent Configuration ──────────────────────────────────────────────────
+
+export const SubagentConfig = z.object({
+    role: AgentRole,
+    /** The CLI tool to use for this role (e.g. "opencode", "gemini", "qwen") */
+    cli: z.string(),
+    /** Extra args to pass to the CLI tool */
+    args: z.array(z.string()).default([]),
+    /** Working directory override. Defaults to monorepo root. */
+    cwd: z.string().optional(),
+    /** Max wallclock seconds before the process is auto-killed */
+    timeoutSeconds: z.number().default(600),
+});
+export type SubagentConfig = z.infer<typeof SubagentConfig>;
+
+// ─── Telemetry event shapes sent over the local WebSocket mesh ──────────────
+
+export const TelemetryEventType = z.enum([
+    "agent:started",
+    "agent:output",      // stdout/stderr chunk
+    "agent:progress",    // 0-100 progress hint emitted by the CLI tool
+    "agent:token_usage", // token counters
+    "agent:finished",
+    "agent:error",
+    "agent:cancelled",
+    "orchestrator:status",
+]);
+export type TelemetryEventType = z.infer<typeof TelemetryEventType>;
+
+const BaseEvent = z.object({
+    ts: z.number().default(() => Date.now()),
+    role: AgentRole,
+});
+
+export const AgentStartedEvent = BaseEvent.extend({
+    type: z.literal("agent:started"),
+    pid: z.number(),
+    cli: z.string(),
+    taskId: z.string(),
+});
+
+export const AgentOutputEvent = BaseEvent.extend({
+    type: z.literal("agent:output"),
+    taskId: z.string(),
+    stream: z.enum(["stdout", "stderr"]),
+    chunk: z.string(),
+});
+
+export const AgentProgressEvent = BaseEvent.extend({
+    type: z.literal("agent:progress"),
+    taskId: z.string(),
+    percent: z.number().min(0).max(100),
+});
+
+export const AgentTokenUsageEvent = BaseEvent.extend({
+    type: z.literal("agent:token_usage"),
+    taskId: z.string(),
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    model: z.string(),
+});
+
+export const AgentFinishedEvent = BaseEvent.extend({
+    type: z.literal("agent:finished"),
+    taskId: z.string(),
+    exitCode: z.number(),
+});
+
+export const AgentErrorEvent = BaseEvent.extend({
+    type: z.literal("agent:error"),
+    taskId: z.string(),
+    message: z.string(),
+});
+
+export const AgentCancelledEvent = BaseEvent.extend({
+    type: z.literal("agent:cancelled"),
+    taskId: z.string(),
+});
+
+export const OrchestratorStatusEvent = z.object({
+    type: z.literal("orchestrator:status"),
+    ts: z.number().default(() => Date.now()),
+    agents: z.array(
+        z.object({
+            taskId: z.string(),
+            role: AgentRole,
+            cli: z.string(),
+            pid: z.number(),
+            state: z.enum(["running", "finished", "cancelled", "error"]),
+            progress: z.number(),
+            tokens: z.object({ input: z.number(), output: z.number() }),
+            model: z.string().optional(),
+        })
+    ),
+});
+
+export const TelemetryEvent = z.discriminatedUnion("type", [
+    AgentStartedEvent,
+    AgentOutputEvent,
+    AgentProgressEvent,
+    AgentTokenUsageEvent,
+    AgentFinishedEvent,
+    AgentErrorEvent,
+    AgentCancelledEvent,
+    OrchestratorStatusEvent,
+]);
+export type TelemetryEvent = z.infer<typeof TelemetryEvent>;
+
+// ─── Dashboard → Orchestrator commands ──────────────────────────────────────
+
+export const DashboardCommand = z.discriminatedUnion("cmd", [
+    z.object({
+        cmd: z.literal("launch"),
+        config: SubagentConfig,
+        taskId: z.string(),
+        prompt: z.string(),
+    }),
+    z.object({ cmd: z.literal("cancel"), taskId: z.string() }),
+    z.object({ cmd: z.literal("status") }),
+]);
+export type DashboardCommand = z.infer<typeof DashboardCommand>;