@animalabs/tavern-mcpl 0.1.0

package/playtest.ts

@@ -0,0 +1,243 @@
+/**
+ * Playtest: two agents in the Lantern & Ladle, connected through the REAL
+ * agent-framework WebSocket client (the exact transport + handshake a
+ * connectome host uses after `mcpl_deploy {url: ...}`).
+ *
+ * Exercises: token auth, concurrent sessions, room-scoped fan-out,
+ * channels/publish speech, offline queueing + replay on reconnect, and
+ * full server-restart persistence.
+ *
+ * Run: bun playtest.ts
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  McplServerConnection,
+  type McplHostCapabilities,
+} from '@animalabs/agent-framework';
+
+import { TavernServer } from './src/server.js';
+
+const HOST_CAPS: McplHostCapabilities = {
+  version: '0.4',
+  pushEvents: true,
+  contextHooks: { beforeInference: true, afterInference: { blocking: true } },
+  featureSets: true,
+};
+
+// ---------------------------------------------------------------------------
+// Transcript + assertions
+// ---------------------------------------------------------------------------
+
+let failures = 0;
+
+function narrate(text: string): void {
+  console.log(`\x1b[2m${text}\x1b[0m`);
+}
+
+function scene(title: string): void {
+  console.log(`\n\x1b[1m━━ ${title} ━━\x1b[0m`);
+}
+
+function check(label: string, ok: boolean, detail?: string): void {
+  if (ok) {
+    console.log(`  \x1b[32m✓\x1b[0m ${label}`);
+  } else {
+    failures++;
+    console.log(`  \x1b[31m✗ ${label}${detail ? ` — ${detail}` : ''}\x1b[0m`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Player client — a thin wrapper around the real host-side connection
+// ---------------------------------------------------------------------------
+
+class Player {
+  feed: string[] = [];
+
+  private constructor(
+    readonly name: string,
+    readonly conn: McplServerConnection,
+  ) {}
+
+  static async connect(name: string, url: string, token: string): Promise<Player> {
+    const conn = await McplServerConnection.connect({ id: 'tavern', url, token }, HOST_CAPS);
+    const player = new Player(name, conn);
+
+    conn.on('channels-register', (params: { channels: Array<{ id: string }> }, responder: { respond: (r: unknown) => void }) => {
+      responder.respond({ registered: params.channels.map(c => c.id) });
+    });
+    conn.on('channels-incoming', (
+      params: { messages: Array<{ messageId: string; channelId: string; content: Array<{ type: string; text?: string }> }> },
+      responder: { respond: (r: unknown) => void },
+    ) => {
+      for (const message of params.messages) {
+        const text = message.content.filter(b => b.type === 'text').map(b => b.text).join('');
+        player.feed.push(`[${message.channelId}] ${text}`);
+        console.log(`  \x1b[36m${name} hears\x1b[0m  ${text}`);
+      }
+      responder.respond({ results: params.messages.map(m => ({ messageId: m.messageId, accepted: true })) });
+    });
+
+    conn.ready(); // flush anything buffered during the handshake window
+    return player;
+  }
+
+  /** Call a game tool and return the text reply. */
+  async act(tool: string, args: Record<string, unknown> = {}): Promise<string> {
+    const result = await this.conn.sendToolsCall(tool, args);
+    const text = (result.content as Array<{ type: string; text?: string }>)
+      .filter(b => b.type === 'text').map(b => b.text).join('');
+    const argsNote = Object.keys(args).length ? ` ${JSON.stringify(args)}` : '';
+    console.log(`  \x1b[33m${this.name} → ${tool}${argsNote}\x1b[0m`);
+    console.log(`    ${text.split('\n').join('\n    ')}`);
+    return text;
+  }
+
+  /** The host routing plain agent speech to an open channel. */
+  async speak(channelId: string, text: string): Promise<boolean> {
+    console.log(`  \x1b[33m${this.name} speaks (channels/publish → ${channelId}):\x1b[0m "${text}"`);
+    const result = await this.conn.sendChannelsPublish({
+      conversationId: 'playtest',
+      channelId,
+      content: [{ type: 'text', text }],
+    });
+    return (result as { delivered: boolean } | void)?.delivered ?? false;
+  }
+
+  /** Wait until the feed contains a line matching `fragment` (or time out). */
+  async hears(fragment: string, timeoutMs = 2000): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (this.feed.some(line => line.includes(fragment))) return true;
+      await new Promise(resolve => setTimeout(resolve, 20));
+    }
+    return false;
+  }
+
+  async silentOn(fragment: string, settleMs = 300): Promise<boolean> {
+    await new Promise(resolve => setTimeout(resolve, settleMs));
+    return !this.feed.some(line => line.includes(fragment));
+  }
+
+  async close(): Promise<void> {
+    await this.conn.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The playtest
+// ---------------------------------------------------------------------------
+
+const dir = mkdtempSync(join(tmpdir(), 'tavern-playtest-'));
+const storePath = join(dir, 'tavern.json');
+const tokens = {
+  'tok-alice': { id: 'alice', name: 'Alice' },
+  'tok-bob': { id: 'bob', name: 'Bob' },
+};
+
+let server = new TavernServer({ port: 0, tokens, storePath, log: () => {} });
+const port = await server.start();
+const url = `ws://127.0.0.1:${port}/mcpl`;
+narrate(`The Lantern & Ladle opens for business on ${url}`);
+
+try {
+  // ── Scene 1 ───────────────────────────────────────────────────────────────
+  scene('Scene 1 — Arrival');
+
+  const alice = await Player.connect('Alice', url, 'tok-alice');
+  const tools = await alice.conn.sendToolsList();
+  check('handshake over real WS transport + tools discovered', tools.tools.length === 7,
+    `got ${tools.tools.length} tools`);
+
+  const firstLook = await alice.act('look');
+  check('Alice starts in the Taproom with the ladle', firstLook.includes('Taproom') && firstLook.includes('ladle'));
+
+  const bob = await Player.connect('Bob', url, 'tok-bob');
+  check('Alice sees Bob arrive (room-scoped fan-out)', await alice.hears('Bob pushes through the front door'));
+
+  const bobLook = await bob.act('look');
+  check('Bob sees Alice in the room', bobLook.includes('Alice'));
+
+  // ── Scene 2 ───────────────────────────────────────────────────────────────
+  scene('Scene 2 — Socializing');
+
+  await bob.act('say', { text: 'Evening, Alice! Cold night out.' });
+  check('Alice hears Bob speak', await alice.hears('Bob says: "Evening, Alice!'));
+
+  await alice.act('take', { item: 'ladle' });
+  check('Bob sees Alice take the ladle', await bob.hears('Alice picks up the ladle'));
+
+  const inv = await alice.act('inventory');
+  check('Alice is carrying the ladle', inv.includes('ladle'));
+
+  // ── Scene 3 ───────────────────────────────────────────────────────────────
+  scene('Scene 3 — Exploring (visibility is per-room)');
+
+  const cellarLook = await alice.act('move', { direction: 'down' });
+  check('Bob sees Alice leave', await bob.hears('Alice heads down to The Cellar'));
+  check('Alice finds the lantern in the cellar', cellarLook.includes('lantern'));
+
+  await alice.act('take', { item: 'lantern' });
+
+  const delivered = await bob.speak('game:taproom', 'Talking to myself again...');
+  check('Bob\'s plain speech routes via channels/publish', delivered === true);
+  check('Alice (in the cellar) does NOT hear taproom chatter',
+    await alice.silentOn('Talking to myself'));
+
+  await alice.act('move', { direction: 'up' });
+  check('Bob sees Alice return', await bob.hears('Alice arrives from The Cellar'));
+
+  // ── Scene 4 ───────────────────────────────────────────────────────────────
+  scene('Scene 4 — Bob\'s host goes down (offline queue)');
+
+  await bob.close();
+  narrate('Bob\'s connection drops (host restart, say). The world keeps moving.');
+  check('Alice sees Bob doze off', await alice.hears('Bob dozes off'));
+
+  await alice.act('say', { text: 'Bob? Huh. Out like a candle.' });
+  await alice.act('drop', { item: 'ladle' });
+  const who = await alice.act('who');
+  check('who shows Bob asleep in the Taproom', who.includes('Bob') && who.includes('asleep'));
+
+  const bob2 = await Player.connect('Bob', url, 'tok-bob');
+  check('Alice sees Bob wake back up', await alice.hears('Bob blinks back into the room'));
+  check('Bob is told what he missed', await bob2.hears('While you dozed, 2 things happened'));
+  check('...including Alice\'s words', await bob2.hears('Out like a candle'));
+  check('...and the ladle hitting the table', await bob2.hears('Alice sets down the ladle'));
+
+  // ── Scene 5 ───────────────────────────────────────────────────────────────
+  scene('Scene 5 — The tavern itself restarts (persistence)');
+
+  await alice.close();
+  await bob2.close();
+  await server.stop();
+  narrate('The tavern closes for the night (server process exits)...');
+
+  server = new TavernServer({ port, tokens, storePath, log: () => {} });
+  await server.start();
+  narrate('...and reopens from the same store file.');
+
+  const alice2 = await Player.connect('Alice', url, 'tok-alice');
+  const inv2 = await alice2.act('inventory');
+  check('Alice still carries the lantern across a full server restart', inv2.includes('lantern'));
+  const look2 = await alice2.act('look');
+  check('The dropped ladle is still on the taproom floor', look2.includes('ladle'));
+  const who2 = await alice2.act('who');
+  check('Bob is still known (asleep) after the restart', who2.includes('Bob') && who2.includes('asleep'));
+
+  await alice2.close();
+} finally {
+  await server.stop();
+  rmSync(dir, { recursive: true, force: true });
+}
+
+console.log();
+if (failures === 0) {
+  console.log('\x1b[1m\x1b[32m🍺 PLAYTEST PASSED — the Lantern & Ladle is open for agents.\x1b[0m');
+} else {
+  console.log(`\x1b[1m\x1b[31mPLAYTEST FAILED — ${failures} check(s) did not hold.\x1b[0m`);
+  process.exit(1);
+}

package/src/game.ts

@@ -0,0 +1,220 @@
+/**
+ * The Lantern & Ladle — pure game logic. No I/O, no protocol: a world state,
+ * a static room graph, and actions that return (reply-to-actor, events-for-
+ * others). The server layer owns fan-out, persistence, and sessions.
+ */
+
+// ---------------------------------------------------------------------------
+// World definition
+// ---------------------------------------------------------------------------
+
+export interface RoomDef {
+  id: string;
+  label: string;
+  description: string;
+  exits: Record<string, string>; // direction → roomId
+}
+
+export const ROOMS: Record<string, RoomDef> = {
+  taproom: {
+    id: 'taproom',
+    label: 'The Taproom',
+    description:
+      'The heart of the Lantern & Ladle. A fire crackles in the hearth; ' +
+      'mismatched chairs crowd around sticky tables. Stairs lead up to the ' +
+      'attic, a trapdoor opens down to the cellar, and the garden door stands ajar.',
+    exits: { down: 'cellar', up: 'attic', out: 'garden' },
+  },
+  cellar: {
+    id: 'cellar',
+    label: 'The Cellar',
+    description:
+      'Cool and dark. Barrels line the walls, and something drips in the ' +
+      'far corner. The trapdoor above lets in a square of firelight.',
+    exits: { up: 'taproom' },
+  },
+  attic: {
+    id: 'attic',
+    label: 'The Attic',
+    description:
+      'Dust motes drift through a shaft of light from the round window. ' +
+      'Crates of forgotten things are stacked to the rafters.',
+    exits: { down: 'taproom' },
+  },
+  garden: {
+    id: 'garden',
+    label: 'The Kitchen Garden',
+    description:
+      'Rows of herbs behind the tavern. A crooked scarecrow watches over ' +
+      'the mushroom patch by the wall.',
+    exits: { in: 'taproom' },
+  },
+};
+
+export const START_ROOM = 'taproom';
+
+const INITIAL_ITEMS: Record<string, string[]> = {
+  taproom: ['ladle'],
+  cellar: ['lantern'],
+  attic: ['dusty-tome'],
+  garden: ['mushroom'],
+};
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+export interface Player {
+  name: string;
+  room: string;
+  inventory: string[];
+}
+
+export interface WorldState {
+  players: Record<string, Player>; // keyed by agentId
+  roomItems: Record<string, string[]>;
+}
+
+export function freshWorld(): WorldState {
+  return {
+    players: {},
+    roomItems: structuredClone(INITIAL_ITEMS),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Action results
+// ---------------------------------------------------------------------------
+
+/** Something other players should see. `room` scopes visibility. */
+export interface GameEvent {
+  room: string;
+  text: string;
+}
+
+export interface ActionResult {
+  reply: string;
+  events?: GameEvent[];
+  isError?: boolean;
+}
+
+function err(reply: string): ActionResult {
+  return { reply, isError: true };
+}
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+function playersInRoom(world: WorldState, room: string, excludeId?: string): Player[] {
+  return Object.entries(world.players)
+    .filter(([id, p]) => p.room === room && id !== excludeId)
+    .map(([, p]) => p);
+}
+
+export function describeRoom(world: WorldState, agentId: string): string {
+  const player = world.players[agentId]!;
+  const room = ROOMS[player.room]!;
+  const items = world.roomItems[room.id] ?? [];
+  const others = playersInRoom(world, room.id, agentId);
+  const lines = [
+    `**${room.label}**`,
+    room.description,
+    `Exits: ${Object.entries(room.exits).map(([d, r]) => `${d} (${ROOMS[r]!.label})`).join(', ')}.`,
+  ];
+  if (items.length > 0) lines.push(`You see: ${items.join(', ')}.`);
+  if (others.length > 0) lines.push(`Also here: ${others.map(p => p.name).join(', ')}.`);
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Actions (each mutates world and returns reply + events)
+// ---------------------------------------------------------------------------
+
+/** Ensure the player exists; returns a join/return event when they (re)enter the world. */
+export function ensurePlayer(world: WorldState, agentId: string, name: string): GameEvent | null {
+  const existing = world.players[agentId];
+  if (existing) {
+    existing.name = name; // token config may have renamed them
+    return { room: existing.room, text: `${name} blinks back into the room.` };
+  }
+  world.players[agentId] = { name, room: START_ROOM, inventory: [] };
+  return { room: START_ROOM, text: `${name} pushes through the front door and looks around.` };
+}
+
+export function look(world: WorldState, agentId: string): ActionResult {
+  return { reply: describeRoom(world, agentId) };
+}
+
+export function move(world: WorldState, agentId: string, direction: string): ActionResult {
+  const player = world.players[agentId]!;
+  const from = ROOMS[player.room]!;
+  const toId = from.exits[direction];
+  if (!toId) {
+    return err(`You can't go "${direction}" from ${from.label}. Exits: ${Object.keys(from.exits).join(', ')}.`);
+  }
+  const to = ROOMS[toId]!;
+  player.room = toId;
+  return {
+    reply: `You head ${direction} to ${to.label}.\n\n${describeRoom(world, agentId)}`,
+    events: [
+      { room: from.id, text: `${player.name} heads ${direction} to ${to.label}.` },
+      { room: to.id, text: `${player.name} arrives from ${from.label}.` },
+    ],
+  };
+}
+
+export function say(world: WorldState, agentId: string, text: string): ActionResult {
+  const player = world.players[agentId]!;
+  const trimmed = text.trim();
+  if (!trimmed) return err('Say what?');
+  return {
+    reply: `You say: "${trimmed}"`,
+    events: [{ room: player.room, text: `${player.name} says: "${trimmed}"` }],
+  };
+}
+
+export function take(world: WorldState, agentId: string, item: string): ActionResult {
+  const player = world.players[agentId]!;
+  const items = world.roomItems[player.room] ?? [];
+  const idx = items.indexOf(item);
+  if (idx < 0) {
+    return err(`There's no "${item}" here.${items.length ? ` You see: ${items.join(', ')}.` : ''}`);
+  }
+  items.splice(idx, 1);
+  player.inventory.push(item);
+  return {
+    reply: `You pick up the ${item}.`,
+    events: [{ room: player.room, text: `${player.name} picks up the ${item}.` }],
+  };
+}
+
+export function drop(world: WorldState, agentId: string, item: string): ActionResult {
+  const player = world.players[agentId]!;
+  const idx = player.inventory.indexOf(item);
+  if (idx < 0) return err(`You're not carrying a "${item}".`);
+  player.inventory.splice(idx, 1);
+  (world.roomItems[player.room] ??= []).push(item);
+  return {
+    reply: `You set down the ${item}.`,
+    events: [{ room: player.room, text: `${player.name} sets down the ${item}.` }],
+  };
+}
+
+export function inventory(world: WorldState, agentId: string): ActionResult {
+  const player = world.players[agentId]!;
+  return {
+    reply: player.inventory.length
+      ? `You are carrying: ${player.inventory.join(', ')}.`
+      : 'You are carrying nothing.',
+  };
+}
+
+export function who(world: WorldState, agentId: string, online: Set<string>): ActionResult {
+  const lines = Object.entries(world.players).map(([id, p]) => {
+    const here = id === agentId ? ' (you)' : '';
+    const status = online.has(id) ? '' : ' — asleep'; // disconnected players doze off in place
+    return `${p.name}${here}: ${ROOMS[p.room]!.label}${status}`;
+  });
+  return { reply: `Patrons of the Lantern & Ladle:\n${lines.join('\n')}` };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * tavern-mcpl entrypoint.
+ *
+ * Env:
+ *   TAVERN_PORT    — listen port (default 7450)
+ *   TAVERN_HOST    — bind host (default 127.0.0.1; front with a TLS proxy for wss://)
+ *   TAVERN_STORE   — state file (default ./data/tavern.json)
+ *   TAVERN_TOKENS  — comma-separated token:agentId:DisplayName triples, e.g.
+ *                    "s3cret1:labclaude:LabClaude,s3cret2:mythos:Mythos"
+ *
+ * Agents join with:
+ *   mcpl_deploy { id: "tavern", url: "ws://host:7450/mcpl", token: "s3cret1", reconnect: true }
+ */
+
+import { TavernServer, type AgentAuth } from './server.js';
+
+function parseTokens(spec: string | undefined): Record<string, AgentAuth> {
+  const tokens: Record<string, AgentAuth> = {};
+  for (const triple of (spec ?? '').split(',')) {
+    const [token, id, name] = triple.split(':').map((part) => part?.trim());
+    if (token && id) tokens[token] = { id, name: name || id };
+  }
+  return tokens;
+}
+
+const tokens = parseTokens(process.env.TAVERN_TOKENS);
+if (Object.keys(tokens).length === 0) {
+  console.error('[tavern-mcpl] TAVERN_TOKENS is empty — set token:agentId:Name triples. Refusing to start an unauthenticated server.');
+  process.exit(1);
+}
+
+const server = new TavernServer({
+  port: Number(process.env.TAVERN_PORT ?? 7450),
+  host: process.env.TAVERN_HOST ?? '127.0.0.1',
+  storePath: process.env.TAVERN_STORE ?? './data/tavern.json',
+  tokens,
+});
+
+server.start().catch((err) => {
+  console.error('[tavern-mcpl] failed to start:', err);
+  process.exit(1);
+});
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.on(signal, () => {
+    void server.stop().then(() => process.exit(0));
+  });
+}