@spencerbeggs/claude-coordinator-server 0.1.0

package/36.js

@@ -0,0 +1,263 @@
+import { AnswerInputSchema, AskInputSchema, DEFAULT_HOST, DEFAULT_PORT, GetContextInputSchema, JoinInputSchema, ListContextInputSchema, LogDecisionInputSchema, ShareContextInputSchema } from "@spencerbeggs/claude-coordinator-core";
+import { initTRPC } from "@trpc/server";
+import { observable } from "@trpc/server/observable";
+import { z } from "zod";
+import { EventEmitter } from "node:events";
+import { applyWSSHandler } from "@trpc/server/adapters/ws";
+import { WebSocketServer } from "ws";
+class CoordinatorState extends EventEmitter {
+    sessionId;
+    agents = new Map();
+    context = new Map();
+    questions = new Map();
+    decisions = [];
+    constructor(sessionId){
+        super();
+        this.sessionId = sessionId;
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    addAgent(agent) {
+        this.agents.set(agent.id, agent);
+        this.emit("agentChange", this.listAgents());
+    }
+    removeAgent(agentId) {
+        const removed = this.agents.delete(agentId);
+        if (removed) this.emit("agentChange", this.listAgents());
+        return removed;
+    }
+    getAgent(agentId) {
+        return this.agents.get(agentId);
+    }
+    listAgents() {
+        return Array.from(this.agents.values());
+    }
+    setContext(entry) {
+        this.context.set(entry.key, entry);
+        this.emit("contextChange", entry);
+    }
+    getContext(key) {
+        return this.context.get(key);
+    }
+    listContext(filters) {
+        let entries = Array.from(this.context.values());
+        const filterTags = filters?.tags;
+        if (filterTags && filterTags.length > 0) entries = entries.filter((entry)=>filterTags.every((tag)=>entry.tags.includes(tag)));
+        if (filters?.createdBy) entries = entries.filter((entry)=>entry.createdBy === filters.createdBy);
+        return entries;
+    }
+    addQuestion(question) {
+        this.questions.set(question.id, question);
+        this.emit("question", question);
+    }
+    answerQuestion(questionId, answer, answeredBy) {
+        const question = this.questions.get(questionId);
+        if (!question) return;
+        const answered = {
+            ...question,
+            answer,
+            answeredBy,
+            status: "answered",
+            answeredAt: new Date()
+        };
+        this.questions.set(questionId, answered);
+        this.emit("answer", answered);
+        return answered;
+    }
+    getQuestion(questionId) {
+        return this.questions.get(questionId);
+    }
+    listPendingQuestions(forAgentId) {
+        return Array.from(this.questions.values()).filter((q)=>{
+            if ("pending" !== q.status) return false;
+            if (forAgentId && q.to && q.to !== forAgentId) return false;
+            return true;
+        });
+    }
+    addDecision(decision) {
+        this.decisions.push(decision);
+    }
+    listDecisions() {
+        return [
+            ...this.decisions
+        ];
+    }
+}
+let globalState = null;
+function getOrCreateState(sessionId) {
+    if (!globalState) globalState = new CoordinatorState(sessionId ?? crypto.randomUUID());
+    return globalState;
+}
+function resetState() {
+    globalState = null;
+}
+const t = initTRPC.context().create();
+const publicProcedure = t.procedure;
+const sessionRouter = t.router({
+    join: publicProcedure.input(JoinInputSchema).mutation(({ input, ctx })=>{
+        const agent = {
+            id: crypto.randomUUID(),
+            name: input.name,
+            role: input.role,
+            repoPath: input.repoPath,
+            connectedAt: new Date()
+        };
+        ctx.state.addAgent(agent);
+        return {
+            agent,
+            sessionId: ctx.state.getSessionId()
+        };
+    }),
+    leave: publicProcedure.input(z.object({
+        agentId: z.string().uuid()
+    })).mutation(({ input, ctx })=>{
+        const removed = ctx.state.removeAgent(input.agentId);
+        return {
+            success: removed
+        };
+    }),
+    list: publicProcedure.query(({ ctx })=>ctx.state.listAgents()),
+    onAgentChange: publicProcedure.subscription(({ ctx })=>observable((emit)=>{
+            const handler = (agents)=>{
+                emit.next(agents);
+            };
+            ctx.state.on("agentChange", handler);
+            emit.next(ctx.state.listAgents());
+            return ()=>{
+                ctx.state.off("agentChange", handler);
+            };
+        }))
+});
+const contextRouter = t.router({
+    share: publicProcedure.input(ShareContextInputSchema.extend({
+        agentId: z.string().uuid()
+    })).mutation(({ input, ctx })=>{
+        const now = new Date();
+        const existing = ctx.state.getContext(input.key);
+        const entry = {
+            id: existing?.id ?? crypto.randomUUID(),
+            key: input.key,
+            value: input.value,
+            tags: input.tags ?? [],
+            createdBy: existing?.createdBy ?? input.agentId,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now
+        };
+        ctx.state.setContext(entry);
+        return entry;
+    }),
+    get: publicProcedure.input(GetContextInputSchema).query(({ input, ctx })=>ctx.state.getContext(input.key) ?? null),
+    list: publicProcedure.input(ListContextInputSchema.optional()).query(({ input, ctx })=>ctx.state.listContext(input)),
+    onContextChange: publicProcedure.subscription(({ ctx })=>observable((emit)=>{
+            const handler = (entry)=>{
+                emit.next(entry);
+            };
+            ctx.state.on("contextChange", handler);
+            return ()=>{
+                ctx.state.off("contextChange", handler);
+            };
+        }))
+});
+const questionsRouter = t.router({
+    ask: publicProcedure.input(AskInputSchema.extend({
+        agentId: z.string().uuid()
+    })).mutation(({ input, ctx })=>{
+        const question = {
+            id: crypto.randomUUID(),
+            question: input.question,
+            from: input.agentId,
+            to: input.to,
+            status: "pending",
+            createdAt: new Date()
+        };
+        ctx.state.addQuestion(question);
+        return question;
+    }),
+    answer: publicProcedure.input(AnswerInputSchema.extend({
+        agentId: z.string().uuid()
+    })).mutation(({ input, ctx })=>{
+        const answered = ctx.state.answerQuestion(input.questionId, input.answer, input.agentId);
+        if (!answered) throw new Error(`Question not found: ${input.questionId}`);
+        return answered;
+    }),
+    listPending: publicProcedure.input(z.object({
+        agentId: z.string().uuid().optional()
+    }).optional()).query(({ input, ctx })=>ctx.state.listPendingQuestions(input?.agentId)),
+    onQuestion: publicProcedure.subscription(({ ctx })=>observable((emit)=>{
+            const questionHandler = (question)=>{
+                emit.next(question);
+            };
+            const answerHandler = (question)=>{
+                emit.next(question);
+            };
+            ctx.state.on("question", questionHandler);
+            ctx.state.on("answer", answerHandler);
+            return ()=>{
+                ctx.state.off("question", questionHandler);
+                ctx.state.off("answer", answerHandler);
+            };
+        }))
+});
+const decisionsRouter = t.router({
+    log: publicProcedure.input(LogDecisionInputSchema.extend({
+        agentId: z.string().uuid()
+    })).mutation(({ input, ctx })=>{
+        const decision = {
+            id: crypto.randomUUID(),
+            decision: input.decision,
+            rationale: input.rationale,
+            by: input.agentId,
+            createdAt: new Date()
+        };
+        ctx.state.addDecision(decision);
+        return decision;
+    }),
+    list: publicProcedure.query(({ ctx })=>ctx.state.listDecisions())
+});
+const appRouter = t.router({
+    session: sessionRouter,
+    context: contextRouter,
+    questions: questionsRouter,
+    decisions: decisionsRouter
+});
+function createContext() {
+    return {
+        state: getOrCreateState()
+    };
+}
+function createServer(options = {}) {
+    const port = options.port ?? 3030;
+    const host = options.host ?? "localhost";
+    const wss = new WebSocketServer({
+        port,
+        host
+    });
+    const handler = applyWSSHandler({
+        wss,
+        router: appRouter,
+        createContext: createContext,
+        keepAlive: {
+            enabled: true,
+            pingMs: 30000,
+            pongWaitMs: 5000
+        }
+    });
+    console.error(`[coordinator] WebSocket server listening on ws://${host}:${port}`);
+    wss.on("connection", (ws)=>{
+        console.error(`[coordinator] Client connected (${wss.clients.size} total)`);
+        ws.on("close", ()=>{
+            console.error(`[coordinator] Client disconnected (${wss.clients.size} total)`);
+        });
+    });
+    const close = ()=>{
+        console.error("[coordinator] Shutting down server...");
+        handler.broadcastReconnectNotification();
+        wss.close();
+    };
+    return {
+        wss,
+        close
+    };
+}
+export { CoordinatorState, DEFAULT_HOST, DEFAULT_PORT, appRouter, createContext, createServer, getOrCreateState, resetState };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @spencerbeggs/claude-coordinator-server
+
+tRPC WebSocket server enabling real-time coordination between Claude Code
+instances through session management, context sharing, Q&A, and decision
+logging.
+
+## Features
+
+- **Real-time communication** - WebSocket-based with tRPC subscriptions
+- **Session management** - Agents join/leave coordinated sessions
+- **Context sharing** - Share and retrieve key-value context entries
+- **Q&A system** - Ask and answer questions between agents
+- **Decision logging** - Track decisions made during coordination
+
+## Installation
+
+```bash
+npm install @spencerbeggs/claude-coordinator-server
+```
+
+## Quick Start
+
+### Start the Server
+
+```bash
+# Using npx
+npx @spencerbeggs/claude-coordinator-server
+
+# With custom port
+PORT=3031 npx @spencerbeggs/claude-coordinator-server
+
+# With custom host
+HOST=0.0.0.0 PORT=3030 npx @spencerbeggs/claude-coordinator-server
+```
+
+### Use Programmatically
+
+```typescript
+import { createServer } from "@spencerbeggs/claude-coordinator-server";
+
+const server = createServer({
+  port: 3030,
+  host: "localhost",
+});
+
+console.log("Server started on ws://localhost:3030");
+
+// Graceful shutdown
+process.on("SIGTERM", () => {
+  server.close();
+});
+```
+
+## API Overview
+
+The server exposes tRPC procedures organized by domain:
+
+### Session
+
+| Procedure | Type | Description |
+| --------- | ---- | ----------- |
+| `session.join` | mutation | Join session as an agent |
+| `session.leave` | mutation | Leave current session |
+| `session.list` | query | List connected agents |
+| `session.onAgentChange` | subscription | Real-time agent updates |
+
+### Context
+
+| Procedure | Type | Description |
+| --------- | ---- | ----------- |
+| `context.share` | mutation | Share a context entry |
+| `context.get` | query | Get context by key |
+| `context.list` | query | List context entries |
+| `context.onContextChange` | subscription | Real-time context updates |
+
+### Questions
+
+| Procedure | Type | Description |
+| --------- | ---- | ----------- |
+| `questions.ask` | mutation | Ask a question |
+| `questions.answer` | mutation | Answer a question |
+| `questions.listPending` | query | List unanswered questions |
+| `questions.onQuestion` | subscription | Real-time Q&A updates |
+
+### Decisions
+
+| Procedure | Type | Description |
+| --------- | ---- | ----------- |
+| `decisions.log` | mutation | Log a decision |
+| `decisions.list` | query | List all decisions |
+
+## Configuration
+
+| Environment Variable | Default | Description |
+| -------------------- | ------- | ----------- |
+| `PORT` | `3030` | Server port |
+| `HOST` | `localhost` | Server host |
+
+## Documentation
+
+- [Architecture Design Doc](../../.claude/design/claude-coordinator-server/architecture.md)
+- [Core Schemas Package](../claude-coordinator-core/README.md)
+- [MCP Bridge Package](../claude-coordinator-mcp/README.md)
+
+## License
+
+MIT

package/bin/claude-coordinator-server.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { DEFAULT_PORT, createServer, DEFAULT_HOST } from "../36.js";
+const port = Number(process.env.PORT) || DEFAULT_PORT;
+const host = process.env.HOST ?? DEFAULT_HOST;
+const server = createServer({
+    port: port,
+    host: host
+});
+const shutdown = ()=>{
+    server.close();
+    process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+console.error("[coordinator] Server started. Press Ctrl+C to stop.");

package/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * \@spencerbeggs/claude-coordinator-server
+ *
+ * tRPC WebSocket server for the Claude Coordinator system.
+ * Provides real-time communication between Claude Code instances.
+ *
+ * @packageDocumentation
+ */
+
+import type { Agent } from '@spencerbeggs/claude-coordinator-core';
+import type { ContextEntry } from '@spencerbeggs/claude-coordinator-core';
+import type { Decision } from '@spencerbeggs/claude-coordinator-core';
+import { EventEmitter } from 'node:events';
+import type { Question } from '@spencerbeggs/claude-coordinator-core';
+import { TRPCDefaultErrorShape } from '@trpc/server';
+import { TRPCRootObject } from '@trpc/server';
+import { TRPCRuntimeConfigOptions } from '@trpc/server';
+import { WebSocketServer } from 'ws';
+
+/**
+ * Type exports for clients
+ */
+export declare type AppRouter = typeof appRouter;
+
+/**
+ * Main application router
+ */
+export declare const appRouter: typeof t.router extends (...args: any) => infer R ? R : unknown;
+
+/**
+ * Context passed to each tRPC procedure
+ */
+export declare interface Context {
+    state: CoordinatorState;
+    agentId?: string;
+}
+
+/**
+ * Server instance with cleanup method
+ */
+export declare interface CoordinatorServer {
+    wss: WebSocketServer;
+    close: () => void;
+}
+
+/**
+ * EventEmitter-based state manager for the coordinator
+ */
+export declare class CoordinatorState extends EventEmitter<CoordinatorStateEvents> {
+    private sessionId;
+    private agents;
+    private context;
+    private questions;
+    private decisions;
+    constructor(sessionId: string);
+    getSessionId(): string;
+    addAgent(agent: Agent): void;
+    removeAgent(agentId: string): boolean;
+    getAgent(agentId: string): Agent | undefined;
+    listAgents(): Agent[];
+    setContext(entry: ContextEntry): void;
+    getContext(key: string): ContextEntry | undefined;
+    listContext(filters?: {
+        tags?: string[];
+        createdBy?: string;
+    }): ContextEntry[];
+    addQuestion(question: Question): void;
+    answerQuestion(questionId: string, answer: string, answeredBy: string): Question | undefined;
+    getQuestion(questionId: string): Question | undefined;
+    listPendingQuestions(forAgentId?: string): Question[];
+    addDecision(decision: Decision): void;
+    listDecisions(): Decision[];
+}
+
+/**
+ * Events emitted by the coordinator state
+ */
+export declare interface CoordinatorStateEvents {
+    agentChange: [agents: Agent[]];
+    contextChange: [entry: ContextEntry];
+    question: [question: Question];
+    answer: [question: Question];
+}
+
+/**
+ * Create context for a request
+ */
+export declare function createContext(): Context;
+
+/**
+ * Create and start the coordinator WebSocket server
+ */
+export declare function createServer(options?: ServerOptions): CoordinatorServer;
+
+export declare function getOrCreateState(sessionId?: string): CoordinatorState;
+
+/**
+ * Resets the global coordinator state singleton to null.
+ *
+ * @remarks
+ * Call this in test teardown (e.g., `afterEach` or `afterAll`) to ensure clean
+ * state between test suites. This prevents state from leaking across tests when
+ * using the singleton pattern.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   resetState();
+ * });
+ * ```
+ */
+export declare function resetState(): void;
+
+/**
+ * Options for creating the coordinator server
+ */
+export declare interface ServerOptions {
+    port?: number;
+    host?: string;
+}
+
+declare const t: TRPCRootObject<Context, object, TRPCRuntimeConfigOptions<Context, object>, {
+ctx: Context;
+meta: object;
+errorShape: TRPCDefaultErrorShape;
+transformer: false;
+}>;
+
+export { }

package/index.js

@@ -0,0 +1 @@
+export { CoordinatorState, appRouter, createContext, createServer, getOrCreateState, resetState } from "./36.js";

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@spencerbeggs/claude-coordinator-server",
+	"version": "0.1.0",
+	"private": false,
+	"description": "tRPC WebSocket server for Claude Coordinator",
+	"keywords": [
+		"claude",
+		"coordinator",
+		"trpc",
+		"websocket",
+		"server"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/claude-design-coordinator.git",
+		"directory": "pkgs/claude-coordinator-server"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		}
+	},
+	"bin": {
+		"claude-coordinator-server": "./bin/claude-coordinator-server.js"
+	},
+	"dependencies": {
+		"@spencerbeggs/claude-coordinator-core": "0.1.0",
+		"@trpc/server": "^11.8.1",
+		"ws": "^8.19.0",
+		"zod": "^4.3.5"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"files": [
+		"36.js",
+		"LICENSE",
+		"README.md",
+		"bin/claude-coordinator-server.js",
+		"index.d.ts",
+		"index.js",
+		"package.json"
+	]
+}