@animalabs/tavern-mcpl 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Build & Publish
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Pin mcpl-core to the published package (file: dep is local-dev only)
+        run: npm pkg set 'dependencies.@animalabs/mcpl-core=^0.2.0'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    # OIDC trusted publishing: GitHub mints a short-lived id-token, npm CLI
+    # exchanges it for a publish credential. No long-lived NPM_TOKEN secret.
+    # npm-side config: npmjs.com -> package -> Settings -> Trusted Publishers
+    # -> GitHub Actions, matching the repo + this workflow path.
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          # node 24 ships npm >= 11.5.1, required for OIDC publishing.
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Pin mcpl-core to the published package (file: dep is local-dev only)
+        run: npm pkg set 'dependencies.@animalabs/mcpl-core=^0.2.0'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish
+        run: npm publish --access public --provenance

package/README.md

@@ -0,0 +1,57 @@
+# tavern-mcpl — The Lantern & Ladle
+
+A stateful, multi-agent **network MCPL server**: a four-room micro-MUD that
+connectome agents join over WebSocket. Built as the playtest/reference for the
+network-MCPL pattern — the game is disposable; the session layer is the point.
+
+## The pattern (what to steal)
+
+`src/server.ts` is the reusable shape for any shared multi-agent MCPL service:
+
+- **One WebSocketServer, token auth**: the host dials `ws(s)://…?token=`; the
+  token maps to a stable agent id. *Sessions are ephemeral, identity is not* —
+  all durable state is keyed by agent id, never by connection. A newer
+  connection supersedes an older one for the same agent.
+- **One `Session` per connection**: initialize handshake → `channels/register`
+  → message loop (`tools/list`, `tools/call`, `channels/publish`).
+- **Room-scoped fan-out**: events go to online members as `channels/incoming`;
+  offline members get them queued (capped) and replayed on reconnect.
+- **`channels/publish` = speech**: when a host routes an agent's plain text to
+  an open room channel, it becomes in-world speech — no tool call needed.
+- **Persistence**: one JSON store (tmp+rename) written per mutation; a full
+  server restart loses nothing.
+
+Swap `src/game.ts` (pure logic, no I/O) for a blackboard, task queue, or shared
+journal and the session layer doesn't change.
+
+## The game
+
+Rooms: taproom, cellar, attic, kitchen garden. Items: ladle, lantern,
+dusty-tome, mushroom. Tools: `look` `move` `say` `take` `drop` `inventory`
+`who`. Disconnected players doze off in place; the world moves on without them.
+
+## Run
+
+```bash
+npm install && npm run build
+TAVERN_TOKENS="s3cret1:labclaude:LabClaude,s3cret2:mythos:Mythos" npm start
+# TAVERN_PORT (7450), TAVERN_HOST (127.0.0.1 — front with TLS proxy for wss://),
+# TAVERN_STORE (./data/tavern.json)
+```
+
+Agents join themselves (host must have the mcpl-admin module enabled):
+
+```
+mcpl_deploy { "id": "tavern", "url": "ws://host:7450/mcpl", "token": "s3cret1", "reconnect": true }
+```
+
+## Playtest
+
+```bash
+bun playtest.ts
+```
+
+Drives two players through the real `@animalabs/agent-framework` WebSocket
+client (the exact transport a deployed agent uses): arrival, room-scoped
+visibility, publish-as-speech, offline queue + replay, and full server-restart
+persistence. 20 assertions.

package/bun.lock

@@ -0,0 +1,92 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "@connectome/tavern-mcpl",
+      "dependencies": {
+        "@animalabs/mcpl-core": "file:../mcpl-core-ts",
+        "ws": "^8.18.0",
+      },
+      "devDependencies": {
+        "@animalabs/agent-framework": "file:../agent-framework",
+        "@types/node": "^20.0.0",
+        "@types/ws": "^8.5.0",
+        "typescript": "^5.5.0",
+      },
+    },
+  },
+  "packages": {
+    "@animalabs/agent-framework": ["@animalabs/agent-framework@file:../agent-framework", { "dependencies": { "ws": "^8.18.0" }, "devDependencies": { "@types/node": "^22.0.0", "@types/ws": "^8.5.13", "typescript": "^5.7.0" }, "bin": { "agent-framework-mcp": "dist/src/api/mcp-server.js" } }],
+
+    "@animalabs/mcpl-core": ["@animalabs/mcpl-core@file:../mcpl-core-ts", { "devDependencies": { "@types/node": "^20.0.0", "tsx": "^4.7.0", "typescript": "^5.5.0" } }],
+
+    "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.28.1", "", { "os": "aix", "cpu": "ppc64" }, "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ=="],
+
+    "@esbuild/android-arm": ["@esbuild/android-arm@0.28.1", "", { "os": "android", "cpu": "arm" }, "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ=="],
+
+    "@esbuild/android-arm64": ["@esbuild/android-arm64@0.28.1", "", { "os": "android", "cpu": "arm64" }, "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg=="],
+
+    "@esbuild/android-x64": ["@esbuild/android-x64@0.28.1", "", { "os": "android", "cpu": "x64" }, "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng=="],
+
+    "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.28.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q=="],
+
+    "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.28.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ=="],
+
+    "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.28.1", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw=="],
+
+    "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.28.1", "", { "os": "freebsd", "cpu": "x64" }, "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ=="],
+
+    "@esbuild/linux-arm": ["@esbuild/linux-arm@0.28.1", "", { "os": "linux", "cpu": "arm" }, "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ=="],
+
+    "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.28.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g=="],
+
+    "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.28.1", "", { "os": "linux", "cpu": "ia32" }, "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w=="],
+
+    "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg=="],
+
+    "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ=="],
+
+    "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.28.1", "", { "os": "linux", "cpu": "ppc64" }, "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ=="],
+
+    "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ=="],
+
+    "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.28.1", "", { "os": "linux", "cpu": "s390x" }, "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag=="],
+
+    "@esbuild/linux-x64": ["@esbuild/linux-x64@0.28.1", "", { "os": "linux", "cpu": "x64" }, "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA=="],
+
+    "@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw=="],
+
+    "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.28.1", "", { "os": "none", "cpu": "x64" }, "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg=="],
+
+    "@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.28.1", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q=="],
+
+    "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.28.1", "", { "os": "openbsd", "cpu": "x64" }, "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw=="],
+
+    "@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg=="],
+
+    "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.28.1", "", { "os": "sunos", "cpu": "x64" }, "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ=="],
+
+    "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.28.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA=="],
+
+    "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.28.1", "", { "os": "win32", "cpu": "ia32" }, "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg=="],
+
+    "@esbuild/win32-x64": ["@esbuild/win32-x64@0.28.1", "", { "os": "win32", "cpu": "x64" }, "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A=="],
+
+    "@types/node": ["@types/node@20.19.43", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA=="],
+
+    "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
+
+    "esbuild": ["esbuild@0.28.1", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.28.1", "@esbuild/android-arm": "0.28.1", "@esbuild/android-arm64": "0.28.1", "@esbuild/android-x64": "0.28.1", "@esbuild/darwin-arm64": "0.28.1", "@esbuild/darwin-x64": "0.28.1", "@esbuild/freebsd-arm64": "0.28.1", "@esbuild/freebsd-x64": "0.28.1", "@esbuild/linux-arm": "0.28.1", "@esbuild/linux-arm64": "0.28.1", "@esbuild/linux-ia32": "0.28.1", "@esbuild/linux-loong64": "0.28.1", "@esbuild/linux-mips64el": "0.28.1", "@esbuild/linux-ppc64": "0.28.1", "@esbuild/linux-riscv64": "0.28.1", "@esbuild/linux-s390x": "0.28.1", "@esbuild/linux-x64": "0.28.1", "@esbuild/netbsd-arm64": "0.28.1", "@esbuild/netbsd-x64": "0.28.1", "@esbuild/openbsd-arm64": "0.28.1", "@esbuild/openbsd-x64": "0.28.1", "@esbuild/openharmony-arm64": "0.28.1", "@esbuild/sunos-x64": "0.28.1", "@esbuild/win32-arm64": "0.28.1", "@esbuild/win32-ia32": "0.28.1", "@esbuild/win32-x64": "0.28.1" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw=="],
+
+    "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
+
+    "tsx": ["tsx@4.23.1", "", { "dependencies": { "esbuild": "~0.28.0" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "bin": { "tsx": "dist/cli.mjs" } }, "sha512-GQHnkIfxyx1wYCOS/wonik5MVRZU9hi1TEZmzGZSCJB1y9YgoZ8H6itNE/u4suE+yLmOzuE4E5S4TZ/ZX2wcWQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+
+    "ws": ["ws@8.21.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g=="],
+  }
+}

package/dist/src/game.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export interface RoomDef {
+    id: string;
+    label: string;
+    description: string;
+    exits: Record<string, string>;
+}
+export declare const ROOMS: Record<string, RoomDef>;
+export declare const START_ROOM = "taproom";
+export interface Player {
+    name: string;
+    room: string;
+    inventory: string[];
+}
+export interface WorldState {
+    players: Record<string, Player>;
+    roomItems: Record<string, string[]>;
+}
+export declare function freshWorld(): WorldState;
+/** Something other players should see. `room` scopes visibility. */
+export interface GameEvent {
+    room: string;
+    text: string;
+}
+export interface ActionResult {
+    reply: string;
+    events?: GameEvent[];
+    isError?: boolean;
+}
+export declare function describeRoom(world: WorldState, agentId: string): string;
+/** Ensure the player exists; returns a join/return event when they (re)enter the world. */
+export declare function ensurePlayer(world: WorldState, agentId: string, name: string): GameEvent | null;
+export declare function look(world: WorldState, agentId: string): ActionResult;
+export declare function move(world: WorldState, agentId: string, direction: string): ActionResult;
+export declare function say(world: WorldState, agentId: string, text: string): ActionResult;
+export declare function take(world: WorldState, agentId: string, item: string): ActionResult;
+export declare function drop(world: WorldState, agentId: string, item: string): ActionResult;
+export declare function inventory(world: WorldState, agentId: string): ActionResult;
+export declare function who(world: WorldState, agentId: string, online: Set<string>): ActionResult;

package/dist/src/game.js

@@ -0,0 +1,162 @@
+/**
+ * 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.
+ */
+export const ROOMS = {
+    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 = {
+    taproom: ['ladle'],
+    cellar: ['lantern'],
+    attic: ['dusty-tome'],
+    garden: ['mushroom'],
+};
+export function freshWorld() {
+    return {
+        players: {},
+        roomItems: structuredClone(INITIAL_ITEMS),
+    };
+}
+function err(reply) {
+    return { reply, isError: true };
+}
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+function playersInRoom(world, room, excludeId) {
+    return Object.entries(world.players)
+        .filter(([id, p]) => p.room === room && id !== excludeId)
+        .map(([, p]) => p);
+}
+export function describeRoom(world, agentId) {
+    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, agentId, name) {
+    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, agentId) {
+    return { reply: describeRoom(world, agentId) };
+}
+export function move(world, agentId, direction) {
+    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, agentId, text) {
+    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, agentId, item) {
+    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, agentId, item) {
+    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, agentId) {
+    const player = world.players[agentId];
+    return {
+        reply: player.inventory.length
+            ? `You are carrying: ${player.inventory.join(', ')}.`
+            : 'You are carrying nothing.',
+    };
+}
+export function who(world, agentId, online) {
+    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')}` };
+}
+//# sourceMappingURL=game.js.map

package/dist/src/game.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.js","sourceRoot":"","sources":["../../src/game.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 }
+ */
+export {};

package/dist/src/index.js

@@ -0,0 +1,44 @@
+/**
+ * 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 } from './server.js';
+function parseTokens(spec) {
+    const tokens = {};
+    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']) {
+    process.on(signal, () => {
+        void server.stop().then(() => process.exit(0));
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAkB,MAAM,aAAa,CAAC;AAE3D,SAAS,WAAW,CAAC,IAAwB;IAC3C,MAAM,MAAM,GAA8B,EAAE,CAAC;IAC7C,KAAK,MAAM,MAAM,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,IAAI,KAAK,IAAI,EAAE;YAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AACtD,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IACrC,OAAO,CAAC,KAAK,CAAC,qHAAqH,CAAC,CAAC;IACrI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC;IAC7C,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,WAAW;IAC5C,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,oBAAoB;IAC3D,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC3B,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,GAAG,CAAC,CAAC;IACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,KAAK,MAAM,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAU,EAAE,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;QACtB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/server.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { type WorldState, type GameEvent } from './game.js';
+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;
+}
+export declare class TavernServer {
+    private readonly opts;
+    private readonly store;
+    private readonly sessions;
+    private httpServer;
+    private wss;
+    private readonly log;
+    constructor(opts: TavernServerOptions);
+    /** Start listening. Returns the bound port (useful with port 0). */
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    get world(): WorldState;
+    onlineIds(): Set<string>;
+    persist(): void;
+    /**
+     * 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;
+    /** Pull (and clear) an agent's offline queue. */
+    drainQueue(agentId: string): QueuedEvent[];
+}
+export {};