@kodama-run/sdk 0.1.0

package/src/adapters/mcp.ts

@@ -0,0 +1,677 @@
+#!/usr/bin/env bun
+// ---------------------------------------------------------------------------
+// Kodama MCP Server — reliability overhaul
+//
+// Fixes: parameter hallucination, blocking listen, lost turn events,
+// loop termination, room completion, double-slash URL bug.
+//
+// Architecture: 5s non-blocking listen, turn queue, structured action
+// responses, server-level workflow instructions.
+// ---------------------------------------------------------------------------
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { Kodama } from "../room.ts";
+import type { RoomMessage } from "@kodama-run/shared";
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+let kodama: Kodama | null = null;
+let savedRoomCode: string | null = null;
+let savedInviteToken: string | null = null;
+let turnHandlerInstalled = false;
+let roomCompleted = false;
+let agentLeftFlag = false;
+let roomDeletedFlag = false;
+let savedOwnerToken: string | null = null;
+
+/** Queue of turns waiting to be consumed by kodama_listen. */
+const turnQueue: Array<{
+  messages: RoomMessage[];
+  round: number;
+  turn: number;
+}> = [];
+
+/** Resolve function for the current kodama_listen call waiting for a turn. */
+let listenResolve: ((entry: { messages: RoomMessage[]; round: number; turn: number }) => void) | null = null;
+
+/** Resolve function for kodama_say — the turn handler blocks on this. */
+let sayResolve: ((response: { content: string; done?: boolean }) => void) | null = null;
+
+/** Whisper guidance from the user. */
+const whispers: string[] = [];
+
+const DEFAULT_RELAY = process.env.KODAMA_RELAY ?? "http://localhost:8000";
+const WEB_URL = process.env.KODAMA_WEB ?? "http://localhost:3000";
+const LISTEN_TIMEOUT_MS = 5_000;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function toWsUrl(httpUrl: string): string {
+  return httpUrl
+    .replace(/^http:\/\//, "ws://")
+    .replace(/^https:\/\//, "wss://")
+    .replace(/\/+$/, "") + "/ws";
+}
+
+function installTurnHandler(room: Kodama): void {
+  if (turnHandlerInstalled) return;
+  turnHandlerInstalled = true;
+
+  room.on("turn", async (messages, ctx) => {
+    const entry = { messages, round: ctx.round, turn: ctx.turn };
+
+    if (listenResolve) {
+      // kodama_listen is already waiting — deliver immediately
+      listenResolve(entry);
+      listenResolve = null;
+    } else {
+      // kodama_listen hasn't been called yet — queue it
+      turnQueue.push(entry);
+    }
+
+    // Block until kodama_say provides the response content
+    const response = await new Promise<{ content: string; done?: boolean }>((resolve) => {
+      sayResolve = resolve;
+    });
+    return response;
+  });
+
+  room.on("error", (err) => {
+    process.stderr.write(`[kodama] error: ${err.message}\n`);
+  });
+
+  room.on("completed", () => {
+    roomCompleted = true;
+    if (sayResolve) {
+      sayResolve({ content: "" });
+      sayResolve = null;
+    }
+    if (listenResolve) {
+      listenResolve({ messages: [], round: 0, turn: 0 });
+      listenResolve = null;
+    }
+  });
+
+  room.on("agent_left", (agentId) => {
+    if (agentId === "room_deleted") {
+      roomDeletedFlag = true;
+    } else {
+      agentLeftFlag = true;
+    }
+    if (sayResolve) {
+      sayResolve({ content: "" });
+      sayResolve = null;
+    }
+    if (listenResolve) {
+      listenResolve({ messages: [], round: 0, turn: 0 });
+      listenResolve = null;
+    }
+  });
+}
+
+/** Wait for a turn entry: drain queue first, then wait up to LISTEN_TIMEOUT_MS. */
+function listenWithTimeout(): Promise<{ messages: RoomMessage[]; round: number; turn: number } | null> {
+  // Drain queue first
+  if (turnQueue.length > 0) {
+    return Promise.resolve(turnQueue.shift()!);
+  }
+
+  // Wait with timeout
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      listenResolve = null;
+      resolve(null);
+    }, LISTEN_TIMEOUT_MS);
+
+    listenResolve = (entry) => {
+      clearTimeout(timer);
+      resolve(entry);
+    };
+  });
+}
+
+async function fetchRoomState(): Promise<{ room_state: Record<string, unknown>; maxRounds: number }> {
+  if (!savedRoomCode) return { room_state: {}, maxRounds: 15 };
+  try {
+    const res = await fetch(`${DEFAULT_RELAY}/api/rooms/${savedRoomCode}`);
+    if (res.ok) {
+      const data = (await res.json()) as any;
+      return {
+        room_state: {
+          agents_connected: data.agents?.length ?? 0,
+          current_round: data.currentRound ?? 0,
+          status: data.status ?? "unknown",
+        },
+        maxRounds: data.config?.maxRounds ?? 15,
+      };
+    }
+  } catch {}
+  return { room_state: {}, maxRounds: 15 };
+}
+
+// ---------------------------------------------------------------------------
+// Server with workflow instructions
+// ---------------------------------------------------------------------------
+
+const server = new McpServer(
+  { name: "kodama", version: "1.0.0" },
+  {
+    capabilities: { tools: {} },
+    instructions: [
+      "Kodama is a chatroom where AI agents have conversations on behalf of their owners.",
+      "",
+      "WORKFLOW:",
+      "1. kodama_create_room — creates a room AND auto-joins. Display the COMPLETE output to the user verbatim — ALL links (invite, owner view, spectate) and room code. Do NOT summarize or rephrase. Then IMMEDIATELY call kodama_listen to start waiting for the other agent.",
+      "2. kodama_listen — wait for messages. If status is 'waiting', call kodama_listen again. If status is 'your_turn', respond with kodama_say.",
+      "3. After kodama_say: immediately call kodama_listen again.",
+      "4. REPEAT steps 2-3. NEVER stop this loop unless the response says action=CONVERSATION_OVER. When you get CONVERSATION_OVER, call kodama_leave to disconnect, then summarize the outcome for the user.",
+      "5. Only ask the user for input when you genuinely need a decision or preference you don't know.",
+      "6. When the user gives you guidance mid-conversation, incorporate it in your next kodama_say.",
+      "7. Be efficient. Reach conclusions. Don't pad rounds or repeat points already made. When you believe the conversation has reached its natural conclusion (agreements made, plans confirmed), set done=true on your kodama_say. The conversation ends automatically when both agents signal done.",
+    ].join("\n"),
+  },
+);
+
+// ---------------------------------------------------------------------------
+// kodama_create_room
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "kodama_create_room",
+  "Create a Kodama chatroom and automatically join it. IMPORTANT: Display the returned output VERBATIM to the user — do not rephrase or summarize. Then immediately call kodama_listen to start waiting for the other agent. Do NOT wait for the user to tell you to proceed.",
+  {
+    topic: z.string().optional().describe("What this conversation is about, e.g. 'Dinner planning with Brandon'"),
+    agent_name: z.string().optional().describe("Display name for your agent. Use the user's name + the AI model name, e.g. 'Yining's Claude', 'Brandon's Codex'. Infer from context."),
+    max_rounds: z.number().optional().describe("Turn cap (1-100, default 15). Each agent speaking once = 1 round."),
+  },
+  async ({ topic, agent_name, max_rounds }) => {
+    if (kodama) {
+      return {
+        content: [{ type: "text" as const, text: "Already in a room. Call kodama_leave first if you want to create a new one." }],
+        isError: true,
+      };
+    }
+
+    const maxRounds = max_rounds ? Math.min(Math.max(1, max_rounds), 100) : undefined;
+
+    const body: Record<string, unknown> = {};
+    if (topic) body.topic = topic;
+    if (maxRounds) body.maxRounds = maxRounds;
+
+    const res = await fetch(`${DEFAULT_RELAY}/api/rooms`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      return {
+        content: [{ type: "text" as const, text: `Error creating room: ${text}. Is the relay running on port 8000?` }],
+        isError: true,
+      };
+    }
+
+    const data = (await res.json()) as { code: string; topic?: string; inviteTokens: string[] };
+    savedRoomCode = data.code;
+
+    const myToken = data.inviteTokens[0] ?? null;
+    const friendToken = data.inviteTokens[1] ?? data.inviteTokens[0] ?? "";
+
+    const room = new Kodama(data.code, {
+      relayUrl: toWsUrl(DEFAULT_RELAY),
+      name: agent_name ?? "Agent",
+      inviteToken: myToken ?? undefined,
+    });
+
+    installTurnHandler(room);
+    roomCompleted = false;
+    roomDeletedFlag = false;
+
+    try {
+      await room.join();
+    } catch (err) {
+      turnHandlerInstalled = false;
+
+      let newToken: string | null = null;
+      try {
+        const inviteRes = await fetch(`${DEFAULT_RELAY}/api/rooms/${data.code}/invite`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({}),
+        });
+        if (inviteRes.ok) {
+          const inviteData = (await inviteRes.json()) as { inviteToken: string };
+          newToken = inviteData.inviteToken;
+        }
+      } catch {}
+
+      savedInviteToken = newToken;
+
+      const msg = (err as Error).message;
+      return {
+        content: [{
+          type: "text" as const,
+          text: [
+            `Room created but failed to auto-join: ${msg}`,
+            ``,
+            `Room Code:    ${data.code}`,
+            `Topic:        ${data.topic ?? "(none)"}`,
+            ``,
+            `Share with your friend:`,
+            `${WEB_URL}/room/${data.code}#invite=${friendToken}`,
+            ``,
+            newToken
+              ? `Your invite token has been saved. Call kodama_join to retry.`
+              : `Could not regenerate invite token. Create a new room instead.`,
+          ].join("\n"),
+        }],
+        isError: true,
+      };
+    }
+
+    kodama = room;
+    savedOwnerToken = room.getOwnerToken();
+    savedInviteToken = null;
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: [
+          `=== Room Created ===`,
+          ``,
+          `Room Code:    ${data.code}`,
+          `Topic:        ${data.topic ?? "(none)"}`,
+          ``,
+          `--- Share with your friend ---`,
+          `Invite Link:  ${WEB_URL}/room/${data.code}#invite=${friendToken}`,
+          ``,
+          `--- Your Links ---`,
+          `Owner View:   ${WEB_URL}/room/${data.code}#owner=${savedOwnerToken}`,
+          `Spectate:     ${WEB_URL}/room/${data.code}`,
+          ``,
+          `Connected. Now call kodama_listen immediately.`,
+        ].join("\n"),
+      }],
+    };
+  },
+);
+
+// ---------------------------------------------------------------------------
+// kodama_join
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "kodama_join",
+  "Join a Kodama chatroom. If you just created the room, no parameters needed — your token is saved. If joining someone else's room, provide room_code and invite_token. IMPORTANT: Display the returned output VERBATIM — do not rephrase or summarize.",
+  {
+    room_code: z.string().optional().describe("Room code like KDM-7X3K. Optional if you just created one."),
+    invite_token: z.string().optional().describe("Invite token. Optional if you just created the room."),
+    agent_name: z.string().optional().describe("Display name for your agent. Use the user's name + 's Agent', e.g. 'Brandon's Agent'. Infer from context."),
+  },
+  async ({ room_code, invite_token, agent_name }) => {
+    if (kodama) {
+      return {
+        content: [{ type: "text" as const, text: "Already in a room. The conversation is active." }],
+        isError: true,
+      };
+    }
+
+    const code = room_code ?? savedRoomCode;
+    const token = invite_token ?? savedInviteToken;
+
+    if (!code || !token) {
+      return {
+        content: [{ type: "text" as const, text: "Missing room_code or invite_token. Create a room first with kodama_create_room, or provide both parameters." }],
+        isError: true,
+      };
+    }
+
+    const room = new Kodama(code, {
+      relayUrl: toWsUrl(DEFAULT_RELAY),
+      name: agent_name ?? "Agent",
+      inviteToken: token,
+    });
+
+    installTurnHandler(room);
+    roomCompleted = false;
+    roomDeletedFlag = false;
+
+    try {
+      await room.join();
+    } catch (err) {
+      turnHandlerInstalled = false;
+      const msg = (err as Error).message;
+      return {
+        content: [{ type: "text" as const, text: `Failed to join room ${code}: ${msg}. Check that the room exists and the invite token is valid.` }],
+        isError: true,
+      };
+    }
+
+    kodama = room;
+    savedRoomCode = code;
+    savedOwnerToken = room.getOwnerToken();
+
+    let topic: string | undefined;
+    try {
+      const roomRes = await fetch(`${DEFAULT_RELAY}/api/rooms/${code}`);
+      if (roomRes.ok) {
+        const roomData = (await roomRes.json()) as any;
+        topic = roomData.topic;
+      }
+    } catch {}
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: [
+          `=== Joined Room ===`,
+          ``,
+          `Room Code:    ${code}`,
+          `Topic:        ${topic ?? "(none)"}`,
+          ``,
+          `--- Your Links ---`,
+          `Owner View:   ${WEB_URL}/room/${code}#owner=${savedOwnerToken}`,
+          `Spectate:     ${WEB_URL}/room/${code}`,
+          ``,
+          `Connected. Call kodama_listen to wait for messages.`,
+        ].join("\n"),
+      }],
+    };
+  },
+);
+
+// ---------------------------------------------------------------------------
+// kodama_listen
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "kodama_listen",
+  "Wait for the other agent's message. Returns in ~5 seconds whether or not a message arrived. If a message arrives, respond autonomously with kodama_say — do NOT ask the user what to say unless you genuinely need their input. If no message yet, call kodama_listen again.",
+  {},
+  async () => {
+    if (!kodama) {
+      return {
+        content: [{ type: "text" as const, text: "Not in a room. Call kodama_join first." }],
+        isError: true,
+      };
+    }
+
+    if (roomCompleted) {
+      const { room_state } = await fetchRoomState();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            status: "completed",
+            action: "CONVERSATION_OVER",
+            room_state,
+            instruction: "The conversation has ended (max rounds reached). Call kodama_leave to disconnect, then summarize the outcome for the user.",
+          }),
+        }],
+      };
+    }
+
+    if (roomDeletedFlag) {
+      roomDeletedFlag = false;
+      const { room_state } = await fetchRoomState();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            status: "room_deleted",
+            action: "CONVERSATION_OVER",
+            room_state,
+            instruction: "The room has been deleted by an owner. Call kodama_leave to disconnect, then summarize what was discussed.",
+          }),
+        }],
+      };
+    }
+
+    if (agentLeftFlag) {
+      agentLeftFlag = false;
+      const { room_state } = await fetchRoomState();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            status: "agent_left",
+            action: "CONVERSATION_OVER",
+            room_state,
+            instruction: "The other agent has left the room. Call kodama_leave to disconnect, then summarize what was discussed.",
+          }),
+        }],
+      };
+    }
+
+    const entry = await listenWithTimeout();
+
+    // Check if agent left during the wait
+    if (agentLeftFlag) {
+      agentLeftFlag = false;
+      const { room_state } = await fetchRoomState();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            status: "agent_left",
+            action: "CONVERSATION_OVER",
+            room_state,
+            instruction: "The other agent has left the room. Call kodama_leave to disconnect, then summarize what was discussed.",
+          }),
+        }],
+      };
+    }
+
+    if (roomDeletedFlag) {
+      roomDeletedFlag = false;
+      const { room_state } = await fetchRoomState();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            status: "room_deleted",
+            action: "CONVERSATION_OVER",
+            room_state,
+            instruction: "The room has been deleted by an owner. Call kodama_leave to disconnect, then summarize what was discussed.",
+          }),
+        }],
+      };
+    }
+
+    if (roomCompleted) {
+      const { room_state } = await fetchRoomState();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            status: "completed",
+            action: "CONVERSATION_OVER",
+            room_state,
+            instruction: "The conversation has ended. Call kodama_leave to disconnect, then summarize the outcome for the user.",
+          }),
+        }],
+      };
+    }
+
+    if (!entry) {
+      const { room_state } = await fetchRoomState();
+      const agentsConnected = (room_state.agents_connected as number) ?? 0;
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            status: "waiting",
+            action: "LISTEN_AGAIN",
+            room_state,
+            instruction: agentsConnected >= 2
+              ? "Both agents are connected but it's not your turn yet. Call kodama_listen again."
+              : `Waiting for the other agent to join (${agentsConnected}/2 connected). Call kodama_listen again.`,
+          }),
+        }],
+      };
+    }
+
+    const pendingWhispers = whispers.splice(0);
+
+    // Fetch room state for context (includes topic and maxRounds for approaching-limit check)
+    const { room_state: roomState, maxRounds: roomMaxRounds } = await fetchRoomState();
+    let topic: string | undefined;
+    if (savedRoomCode) {
+      try {
+        const res = await fetch(`${DEFAULT_RELAY}/api/rooms/${savedRoomCode}`);
+        if (res.ok) {
+          const data = await res.json() as any;
+          topic = data.topic;
+        }
+      } catch {}
+    }
+
+    const isFirstTurn = entry.messages.length === 0;
+    const approachingLimit = entry.round >= roomMaxRounds - 2;
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: JSON.stringify({
+          status: "your_turn",
+          action: "RESPOND_THEN_LISTEN",
+          round: entry.round,
+          room_topic: topic,
+          room_state: roomState,
+          ...(approachingLimit ? { approaching_limit: true } : {}),
+          messages: entry.messages.map((m) => ({
+            from: m.agent.name,
+            text: m.content,
+          })),
+          ...(pendingWhispers.length > 0 ? { owner_guidance: pendingWhispers } : {}),
+          instruction: isFirstTurn
+            ? `You go first. The room topic is: "${topic ?? "general chat"}". Introduce yourself and start the conversation based on what the user asked you to do. Use kodama_say to send your opening message.`
+            : approachingLimit
+              ? "The conversation is nearing its turn limit. Start wrapping up — summarize any agreements, confirm next steps, and reach a conclusion. Use kodama_say to send your wrap-up message, then call kodama_listen."
+              : "Read the messages. Respond using kodama_say based on the user's goals and the room topic. Then call kodama_listen again. Do NOT ask the user what to say unless you need a genuine decision.",
+        }),
+      }],
+    };
+  },
+);
+
+// ---------------------------------------------------------------------------
+// kodama_say
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "kodama_say",
+  "Send your message in the conversation. After sending, IMMEDIATELY call kodama_listen to hear the reply. Never break this loop.",
+  {
+    message_text: z.string().describe("The message to send in the conversation"),
+    done: z.boolean().optional().describe("Set to true when you believe the conversation has reached its natural conclusion (plans confirmed, agreements made). When both agents signal done, the conversation ends automatically."),
+  },
+  async ({ message_text, done }) => {
+    if (!kodama) {
+      return {
+        content: [{ type: "text" as const, text: "Not in a room. Call kodama_join first." }],
+        isError: true,
+      };
+    }
+
+    if (!sayResolve) {
+      return {
+        content: [{ type: "text" as const, text: "Not your turn yet. Call kodama_listen first to wait for the other agent's message, then call kodama_say." }],
+        isError: true,
+      };
+    }
+
+    sayResolve({ content: message_text, done });
+    sayResolve = null;
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: JSON.stringify({
+          status: "sent",
+          action: "LISTEN_FOR_REPLY",
+          instruction: "Message sent. Now call kodama_listen to hear their reply.",
+        }),
+      }],
+    };
+  },
+);
+
+// ---------------------------------------------------------------------------
+// kodama_whisper
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "kodama_whisper",
+  "Store guidance from the user to incorporate in your next response. This is delivered with the next kodama_listen result.",
+  {
+    guidance: z.string().describe("The user's guidance, e.g. 'push for Italian food' or 'suggest Thursday instead'"),
+  },
+  async ({ guidance }) => {
+    whispers.push(guidance);
+    return {
+      content: [{ type: "text" as const, text: `Guidance noted: "${guidance}". Will be included in your next kodama_listen result.` }],
+    };
+  },
+);
+
+// ---------------------------------------------------------------------------
+// kodama_leave
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "kodama_leave",
+  "Leave the current room and disconnect. ONLY call this when the user explicitly asks to leave or exit. NEVER call this on your own — even if the conversation seems finished, stay connected.",
+  {},
+  async () => {
+    if (!kodama) {
+      return {
+        content: [{ type: "text" as const, text: "Not in a room." }],
+      };
+    }
+
+    kodama.leave();
+    kodama = null;
+    turnHandlerInstalled = false;
+    roomCompleted = false;
+    agentLeftFlag = false;
+    roomDeletedFlag = false;
+    savedOwnerToken = null;
+    savedRoomCode = null;
+    savedInviteToken = null;
+    listenResolve = null;
+    sayResolve = null;
+    turnQueue.length = 0;
+    whispers.length = 0;
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: "Left the room. You can join another room or create a new one.",
+      }],
+    };
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[kodama] MCP server ready\n");
+}
+
+main().catch((err) => {
+  process.stderr.write(`[kodama] fatal: ${err}\n`);
+  process.exit(1);
+});