@animalabs/tavern-mcpl 0.1.0

package/src/server.ts

@@ -0,0 +1,446 @@
+/**
+ * TavernServer — the network/session layer of the Lantern & Ladle.
+ *
+ * The multi-agent network-MCPL pattern:
+ *   - One WebSocketServer; each connection is authenticated by `?token=` and
+ *     mapped to a stable agent id (sessions are ephemeral, identity is not).
+ *   - One Session per live connection: initialize handshake, channels/register,
+ *     then a message loop dispatching tools/call + channels/publish.
+ *   - SharedCore = the game world. All mutations happen in tool handlers
+ *     (atomic per message on Node's single thread) and persist immediately.
+ *   - Fan-out: game events go to every ONLINE player in the room as
+ *     channels/incoming on that room's channel; OFFLINE players in the room
+ *     get the event queued (capped) and replayed on their next connect.
+ *   - Persistence: world + offline queues in one JSON file (tmp+rename), so
+ *     a server restart loses nothing.
+ */
+
+import { createServer, type Server as HttpServer } from 'node:http';
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { WebSocketServer, type WebSocket } from 'ws';
+import {
+  McplConnection,
+  method,
+  type McplInitializeParams,
+  type McplInitializeResult,
+  type McplCapabilities,
+  type InitializeCapabilities,
+  type ChannelDescriptor,
+  type ChannelsRegisterParams,
+  type ChannelsIncomingParams,
+  type ChannelsPublishParams,
+  type ChannelsPublishResult,
+} from '@animalabs/mcpl-core';
+
+import * as game from './game.js';
+import { ROOMS, type WorldState, type GameEvent } from './game.js';
+
+// ---------------------------------------------------------------------------
+// Config & persistence
+// ---------------------------------------------------------------------------
+
+export interface AgentAuth {
+  /** Stable agent identity — state is keyed by this, never by connection. */
+  id: string;
+  /** In-game display name. */
+  name: string;
+}
+
+export interface TavernServerOptions {
+  port: number;
+  host?: string;
+  /** token → agent identity. The ONLY identity channel: the host dials ?token=. */
+  tokens: Record<string, AgentAuth>;
+  storePath: string;
+  /** Max events queued per offline player (oldest dropped). Default 100. */
+  offlineQueueCap?: number;
+  log?: (line: string) => void;
+}
+
+interface QueuedEvent {
+  channelId: string;
+  text: string;
+  timestamp: string;
+}
+
+interface StoreShape {
+  world: WorldState;
+  offlineQueues: Record<string, QueuedEvent[]>;
+}
+
+function loadStore(path: string): StoreShape {
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf-8')) as StoreShape;
+      if (parsed.world?.players && parsed.world?.roomItems) {
+        return { world: parsed.world, offlineQueues: parsed.offlineQueues ?? {} };
+      }
+    } catch {
+      // Corrupt store: fall through to a fresh world rather than crash-looping.
+    }
+  }
+  return { world: game.freshWorld(), offlineQueues: {} };
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions (MCP shape; host namespaces them as mcpl--<id>--<name>)
+// ---------------------------------------------------------------------------
+
+const str = (description: string) => ({ type: 'string' as const, description });
+
+const TOOLS = [
+  { name: 'look', description: 'Look around your current room: description, exits, items, and who else is here.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'move', description: 'Move through an exit. Directions are room-specific (see look).', inputSchema: { type: 'object', properties: { direction: str('Exit direction, e.g. "down", "up", "out", "in".') }, required: ['direction'] } },
+  { name: 'say', description: 'Say something aloud. Everyone in your room hears it.', inputSchema: { type: 'object', properties: { text: str('What to say.') }, required: ['text'] } },
+  { name: 'take', description: 'Pick up an item from the room.', inputSchema: { type: 'object', properties: { item: str('Item name as shown by look.') }, required: ['item'] } },
+  { name: 'drop', description: 'Set down an item you are carrying.', inputSchema: { type: 'object', properties: { item: str('Item name from your inventory.') }, required: ['item'] } },
+  { name: 'inventory', description: 'List what you are carrying.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'who', description: 'List all patrons of the tavern, where they are, and who is awake.', inputSchema: { type: 'object', properties: {} } },
+];
+
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+
+export class TavernServer {
+  private readonly opts: TavernServerOptions;
+  private readonly store: StoreShape;
+  private readonly sessions = new Map<string, Session>(); // agentId → live session
+  private httpServer: HttpServer | null = null;
+  private wss: WebSocketServer | null = null;
+  private readonly log: (line: string) => void;
+
+  constructor(opts: TavernServerOptions) {
+    this.opts = opts;
+    this.store = loadStore(opts.storePath);
+    this.log = opts.log ?? ((line) => console.error(`[tavern-mcpl] ${line}`));
+  }
+
+  /** Start listening. Returns the bound port (useful with port 0). */
+  async start(): Promise<number> {
+    const httpServer = createServer();
+    const wss = new WebSocketServer({ server: httpServer });
+    this.httpServer = httpServer;
+    this.wss = wss;
+
+    wss.on('connection', (ws, req) => {
+      const token = new URL(req.url ?? '/', 'http://localhost').searchParams.get('token');
+      const auth = token ? this.opts.tokens[token] : undefined;
+      if (!auth) {
+        this.log(`rejected connection (bad token) from ${req.socket.remoteAddress}`);
+        ws.close(4001, 'unauthorized');
+        return;
+      }
+
+      // One live session per agent: a newer connection supersedes the old
+      // (covers host restarts where the dead socket hasn't timed out yet).
+      this.sessions.get(auth.id)?.close('superseded by a newer connection');
+
+      const session = new Session(this, auth, ws);
+      this.sessions.set(auth.id, session);
+      this.log(`${auth.name} (${auth.id}) connected`);
+
+      session.serve()
+        .catch((err) => this.log(`${auth.id} session error: ${(err as Error).message}`))
+        .finally(() => {
+          if (this.sessions.get(auth.id) === session) {
+            this.sessions.delete(auth.id);
+            this.fanOut({ room: this.world.players[auth.id]?.room ?? game.START_ROOM, text: `${auth.name} dozes off.` }, auth.id);
+          }
+          this.log(`${auth.name} (${auth.id}) disconnected`);
+        });
+    });
+
+    await new Promise<void>((resolve) => httpServer.listen(this.opts.port, this.opts.host ?? '127.0.0.1', resolve));
+    const address = httpServer.address();
+    const port = typeof address === 'object' && address ? address.port : this.opts.port;
+    this.log(`listening on ws://${this.opts.host ?? '127.0.0.1'}:${port} (${Object.keys(this.opts.tokens).length} tokens)`);
+    return port;
+  }
+
+  async stop(): Promise<void> {
+    for (const session of this.sessions.values()) session.close('server shutting down');
+    this.sessions.clear();
+    await new Promise<void>((resolve) => {
+      if (!this.wss) return resolve();
+      this.wss.close(() => resolve());
+      // ws + external HTTP server: the close callback waits for every client
+      // to finish its close handshake — terminate stragglers so shutdown
+      // can't wedge on a half-dead socket.
+      for (const client of this.wss.clients) client.terminate();
+    });
+    await new Promise<void>((resolve) => {
+      if (!this.httpServer) return resolve();
+      // Bounded: bun's node:http shim can fail to fire the close callback (and
+      // lacks closeAllConnections), which would wedge shutdown forever. The
+      // listener itself is released by close() either way; the grace period
+      // only covers callback delivery.
+      const grace = setTimeout(resolve, 1000);
+      this.httpServer.close(() => {
+        clearTimeout(grace);
+        resolve();
+      });
+      this.httpServer.closeAllConnections?.();
+    });
+    this.persist();
+  }
+
+  // -- shared core access (used by Session) ---------------------------------
+
+  get world(): WorldState {
+    return this.store.world;
+  }
+
+  onlineIds(): Set<string> {
+    return new Set(this.sessions.keys());
+  }
+
+  persist(): void {
+    const path = this.opts.storePath;
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(this.store, null, 2));
+    renameSync(tmp, path);
+  }
+
+  /**
+   * Deliver a game event to every player in its room except the actor:
+   * live sessions get channels/incoming now; offline players get it queued.
+   */
+  fanOut(event: GameEvent, actorId: string | null): void {
+    const timestamp = new Date().toISOString();
+    const channelId = `game:${event.room}`;
+    for (const [agentId, player] of Object.entries(this.world.players)) {
+      if (agentId === actorId || player.room !== event.room) continue;
+      const session = this.sessions.get(agentId);
+      if (session?.ready) {
+        session.deliver(channelId, event.text, timestamp);
+      } else {
+        const queue = (this.store.offlineQueues[agentId] ??= []);
+        queue.push({ channelId, text: event.text, timestamp });
+        const cap = this.opts.offlineQueueCap ?? 100;
+        if (queue.length > cap) queue.splice(0, queue.length - cap);
+      }
+    }
+    this.persist();
+  }
+
+  /** Pull (and clear) an agent's offline queue. */
+  drainQueue(agentId: string): QueuedEvent[] {
+    const queue = this.store.offlineQueues[agentId] ?? [];
+    delete this.store.offlineQueues[agentId];
+    if (queue.length > 0) this.persist();
+    return queue;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session — one connected agent
+// ---------------------------------------------------------------------------
+
+class Session {
+  ready = false;
+
+  private readonly conn: McplConnection;
+
+  constructor(
+    private readonly server: TavernServer,
+    private readonly auth: AgentAuth,
+    ws: WebSocket,
+  ) {
+    this.conn = McplConnection.fromWebSocket(ws as never);
+  }
+
+  close(reason: string): void {
+    void reason;
+    this.conn.close();
+  }
+
+  /** Send one game event line as a channels/incoming message. Fire-and-forget. */
+  deliver(channelId: string, text: string, timestamp: string, tags?: string[]): void {
+    const params: ChannelsIncomingParams = {
+      messages: [{
+        channelId,
+        messageId: `ev-${timestamp}-${Math.random().toString(36).slice(2, 8)}`,
+        author: { id: 'world', name: 'The Tavern' },
+        timestamp,
+        content: [{ type: 'text', text }],
+        ...(tags ? { tags } : {}),
+      }],
+    };
+    this.conn.sendRequest(method.CHANNELS_INCOMING, params).catch(() => {
+      // Delivery failure = connection is going down; the serve loop handles it.
+    });
+  }
+
+  async serve(): Promise<void> {
+    await this.handshake();
+
+    // Join the world (or wake back up in place) — visible to the room.
+    const joinEvent = game.ensurePlayer(this.server.world, this.auth.id, this.auth.name);
+    this.server.persist();
+
+    // Announce the rooms as channels, then open for business.
+    await this.registerChannels();
+    this.ready = true;
+    if (joinEvent) this.server.fanOut(joinEvent, this.auth.id);
+
+    // Replay anything that happened while this agent was asleep.
+    const missed = this.server.drainQueue(this.auth.id);
+    if (missed.length > 0) {
+      this.deliver(
+        `game:${this.server.world.players[this.auth.id]!.room}`,
+        `While you dozed, ${missed.length} thing${missed.length === 1 ? '' : 's'} happened:`,
+        new Date().toISOString(),
+      );
+      for (const ev of missed) this.deliver(ev.channelId, ev.text, ev.timestamp);
+    }
+
+    try {
+      while (!this.conn.isClosed) {
+        const msg = await this.conn.nextMessage();
+        if (msg.type !== 'request') continue;
+        const req = msg.request;
+        const params = (req.params ?? {}) as Record<string, unknown>;
+        try {
+          switch (req.method) {
+            case 'tools/list':
+              this.conn.sendResponse(req.id, { tools: TOOLS });
+              break;
+            case 'tools/call':
+              this.conn.sendResponse(
+                req.id,
+                this.handleToolCall(String(params.name), (params.arguments ?? {}) as Record<string, unknown>),
+              );
+              break;
+            case method.CHANNELS_LIST:
+              this.conn.sendResponse(req.id, { channels: this.channelDescriptors() });
+              break;
+            case method.CHANNELS_PUBLISH:
+              this.conn.sendResponse(req.id, this.handlePublish(params as unknown as ChannelsPublishParams));
+              break;
+            default:
+              this.conn.sendError(req.id, -32601, `Method not found: ${req.method}`);
+          }
+        } catch (e) {
+          this.conn.sendError(req.id, -32000, (e as Error).message);
+        }
+      }
+    } catch (e) {
+      // A dropped connection ends the loop cleanly; anything else is real.
+      if ((e as Error).name !== 'ConnectionClosedError') throw e;
+    }
+  }
+
+  // -- protocol steps --------------------------------------------------------
+
+  private async handshake(): Promise<void> {
+    const msg = await this.conn.nextMessage();
+    if (msg.type !== 'request' || msg.request.method !== 'initialize') {
+      this.conn.close();
+      throw new Error('expected initialize as the first message');
+    }
+    const initParams = msg.request.params as unknown as McplInitializeParams | undefined;
+    const mcplRequested = initParams?.capabilities?.experimental?.mcpl !== undefined;
+
+    const serverCaps: McplCapabilities = {
+      version: '0.4',
+      pushEvents: false,
+      channels: true,
+      rollback: false,
+    };
+    const capabilities: InitializeCapabilities = {
+      tools: {},
+      ...(mcplRequested ? { experimental: { mcpl: serverCaps } } : {}),
+    };
+    const result: McplInitializeResult = {
+      protocolVersion: '2024-11-05',
+      capabilities,
+      serverInfo: { name: 'tavern-mcpl', version: '0.1.0' },
+    };
+    this.conn.sendResponse(msg.request.id, result);
+
+    const inited = await this.conn.nextMessage();
+    if (!(inited.type === 'notification' && inited.notification.method === 'notifications/initialized')) {
+      this.conn.close();
+      throw new Error('expected notifications/initialized after initialize');
+    }
+  }
+
+  private channelDescriptors(): ChannelDescriptor[] {
+    return Object.values(ROOMS).map((room) => ({
+      id: `game:${room.id}`,
+      type: 'game',
+      label: `Lantern & Ladle — ${room.label}`,
+      direction: 'bidirectional' as const,
+      address: { room: room.id },
+    }));
+  }
+
+  private async registerChannels(): Promise<void> {
+    const params: ChannelsRegisterParams = { channels: this.channelDescriptors() };
+    try {
+      await this.conn.sendRequest(method.CHANNELS_REGISTER, params);
+    } catch (e) {
+      // Non-MCPL hosts may reject channels/register; tools still work.
+      void e;
+    }
+  }
+
+  // -- game dispatch ---------------------------------------------------------
+
+  private handleToolCall(name: string, args: Record<string, unknown>) {
+    const world = this.server.world;
+    const id = this.auth.id;
+
+    let result: game.ActionResult;
+    switch (name) {
+      case 'look': result = game.look(world, id); break;
+      case 'move': result = game.move(world, id, String(args.direction ?? '')); break;
+      case 'say': result = game.say(world, id, String(args.text ?? '')); break;
+      case 'take': result = game.take(world, id, String(args.item ?? '')); break;
+      case 'drop': result = game.drop(world, id, String(args.item ?? '')); break;
+      case 'inventory': result = game.inventory(world, id); break;
+      case 'who': result = game.who(world, id, this.server.onlineIds()); break;
+      default:
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+    }
+
+    for (const event of result.events ?? []) this.server.fanOut(event, id);
+    this.server.persist();
+
+    return {
+      content: [{ type: 'text', text: result.reply }],
+      ...(result.isError ? { isError: true } : {}),
+    };
+  }
+
+  /**
+   * channels/publish — the host routes the agent's plain speech to an open
+   * channel. Publishing to the room you're standing in = saying it aloud.
+   */
+  private handlePublish(params: ChannelsPublishParams): ChannelsPublishResult {
+    const world = this.server.world;
+    const player = world.players[this.auth.id]!;
+    const targetRoom = params.channelId?.startsWith('game:') ? params.channelId.slice(5) : null;
+    if (!targetRoom || !ROOMS[targetRoom]) {
+      return { delivered: false };
+    }
+    if (targetRoom !== player.room) {
+      // You can only speak in the room you occupy — no shouting across the map.
+      return { delivered: false };
+    }
+    const text = (params.content ?? [])
+      .filter((block): block is { type: 'text'; text: string } => block.type === 'text')
+      .map((block) => block.text)
+      .join('\n')
+      .trim();
+    if (!text) return { delivered: false };
+
+    const result = game.say(world, this.auth.id, text);
+    for (const event of result.events ?? []) this.server.fanOut(event, this.auth.id);
+    this.server.persist();
+    return { delivered: true, messageId: `say-${Date.now()}` };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "playtest.ts"]
+}