@kodama-run/sdk 0.1.0

package/src/room.ts

@@ -0,0 +1,399 @@
+import type {
+  Room,
+  RoomMessage,
+  ServerMessage,
+  AgentCard,
+  RoomSummary,
+} from "@kodama-run/shared";
+import { createAgentCard } from "@kodama-run/shared";
+import { KodamaCrypto } from "./crypto.ts";
+import { PermissionChecker } from "./permissions.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TurnContext {
+  round: number;
+  turn: number;
+  room: Room;
+}
+
+export interface KodamaOptions {
+  relayUrl?: string;
+  name?: string;
+  description?: string;
+  password?: string;
+  inviteToken?: string;
+  permissions?: PermissionChecker;
+}
+
+type TurnHandler = (
+  messages: RoomMessage[],
+  context: TurnContext,
+) => Promise<string | { content: string; done?: boolean }> | string | { content: string; done?: boolean };
+type WhisperHandler = (msg: string) => void;
+type ErrorHandler = (err: Error) => void;
+type PauseHandler = () => Promise<string>;
+type CompletedHandler = (summary: RoomSummary) => void;
+type AgentLeftHandler = (agentId: string) => void;
+
+interface EventHandlers {
+  turn?: TurnHandler;
+  whisper?: WhisperHandler;
+  error?: ErrorHandler;
+  pause?: PauseHandler;
+  completed?: CompletedHandler;
+  agent_left?: AgentLeftHandler;
+}
+
+// ---------------------------------------------------------------------------
+// Reconnection constants
+// ---------------------------------------------------------------------------
+
+const INITIAL_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+const MAX_RECONNECT_ATTEMPTS = 10;
+
+// ---------------------------------------------------------------------------
+// Kodama — main SDK entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * The primary class users interact with. 4-line onboarding:
+ *
+ * ```ts
+ * const room = new Kodama('KDM-7X3K')
+ * room.on('turn', async (messages) => 'response')
+ * room.join()
+ * ```
+ */
+export class Kodama {
+  private readonly roomCode: string;
+  private readonly relayUrl: string;
+  private readonly agentName: string;
+  private readonly description: string;
+  private readonly password?: string;
+  private readonly inviteToken?: string;
+  private readonly permissions: PermissionChecker;
+
+  private handlers: EventHandlers = {};
+  private ownerToken: string | null = null;
+  private ws: WebSocket | null = null;
+  private encryptionKey: string | null = null;
+  private agentId: string | null = null;
+  private roomState: Room | null = null;
+  private messages: RoomMessage[] = [];
+  private reconnectAttempts = 0;
+  private closed = false;
+
+  // Join promise management
+  private joinResolve: (() => void) | null = null;
+  private joinReject: ((err: Error) => void) | null = null;
+
+  constructor(roomCode: string, options?: KodamaOptions) {
+    this.roomCode = roomCode;
+    this.relayUrl = options?.relayUrl ?? "ws://localhost:8000/ws";
+    this.agentName = options?.name ?? "Kodama Agent";
+    this.description = options?.description ?? "";
+    this.password = options?.password;
+    this.inviteToken = options?.inviteToken;
+    this.permissions = options?.permissions ?? new PermissionChecker();
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Register an event handler. Chainable.
+   */
+  on(event: "turn", handler: TurnHandler): this;
+  on(event: "whisper", handler: WhisperHandler): this;
+  on(event: "error", handler: ErrorHandler): this;
+  on(event: "pause", handler: PauseHandler): this;
+  on(event: "completed", handler: CompletedHandler): this;
+  on(event: "agent_left", handler: AgentLeftHandler): this;
+  on(event: string, handler: (...args: any[]) => any): this {
+    (this.handlers as any)[event] = handler;
+    return this;
+  }
+
+  /**
+   * Connect to the relay and join the room.
+   * Resolves when the server confirms the join ("joined" event).
+   */
+  async join(): Promise<void> {
+    this.closed = false;
+    this.encryptionKey = await KodamaCrypto.generateKey();
+
+    return new Promise<void>((resolve, reject) => {
+      this.joinResolve = resolve;
+      this.joinReject = reject;
+      this.connect();
+    });
+  }
+
+  /**
+   * Leave the room and close the WebSocket.
+   */
+  leave(): void {
+    this.closed = true;
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ action: "leave" }));
+      this.ws.close();
+    }
+    this.ws = null;
+  }
+
+  /**
+   * Return the session encryption key (for URL fragment sharing).
+   */
+  getEncryptionKey(): string | null {
+    return this.encryptionKey;
+  }
+
+  /**
+   * Return the owner token received on join (for whisper endpoints).
+   */
+  getOwnerToken(): string | null {
+    return this.ownerToken;
+  }
+
+  /**
+   * Return current room state.
+   */
+  getRoom(): Room | null {
+    return this.roomState;
+  }
+
+  // -----------------------------------------------------------------------
+  // WebSocket lifecycle
+  // -----------------------------------------------------------------------
+
+  private connect(): void {
+    const ws = new WebSocket(this.relayUrl);
+    this.ws = ws;
+
+    ws.addEventListener("open", () => {
+      this.reconnectAttempts = 0;
+
+      const card: AgentCard = {
+        name: this.agentName,
+        description: this.description || `Kodama agent: ${this.agentName}`,
+        skills: ["conversation"],
+        version: "0.1.0",
+      };
+
+      ws.send(
+        JSON.stringify({
+          action: "join",
+          roomCode: this.roomCode,
+          agentName: this.agentName,
+          password: this.password,
+          inviteToken: this.inviteToken,
+          card,
+        }),
+      );
+    });
+
+    ws.addEventListener("message", (event) => {
+      try {
+        const data: ServerMessage = JSON.parse(
+          typeof event.data === "string" ? event.data : "",
+        );
+        this.handleServerMessage(data);
+      } catch (err) {
+        this.handlers.error?.(
+          err instanceof Error ? err : new Error(String(err)),
+        );
+      }
+    });
+
+    ws.addEventListener("close", () => {
+      if (!this.closed) {
+        this.attemptReconnect();
+      }
+    });
+
+    ws.addEventListener("error", (event) => {
+      const err = new Error("WebSocket error");
+      this.handlers.error?.(err);
+      // If we're still joining, reject
+      if (this.joinReject) {
+        this.joinReject(err);
+        this.joinResolve = null;
+        this.joinReject = null;
+      }
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Message handling
+  // -----------------------------------------------------------------------
+
+  private handleServerMessage(msg: ServerMessage): void {
+    switch (msg.event) {
+      case "joined":
+        this.agentId = msg.agentId;
+        this.ownerToken = msg.ownerToken ?? null;
+        // Construct a minimal Room state from the join response
+        this.roomState = {
+          code: msg.room,
+          config: {
+            maxAgents: 2,
+            maxRounds: 10,
+            turnTimeout: 90,
+            recording: false,
+          },
+          agents: msg.agents,
+          currentTurn: 0,
+          currentRound: 1,
+          status: "active",
+          createdAt: new Date(),
+        } as Room;
+
+        if (this.joinResolve) {
+          this.joinResolve();
+          this.joinResolve = null;
+          this.joinReject = null;
+        }
+        break;
+
+      case "message":
+        this.messages.push(msg.message);
+        break;
+
+      case "your_turn":
+        this.handleTurn(msg.turn, msg.round);
+        break;
+
+      case "error":
+        const error = new Error(`[${msg.code}] ${msg.message}`);
+        this.handlers.error?.(error);
+        // If still joining, reject
+        if (this.joinReject) {
+          this.joinReject(error);
+          this.joinResolve = null;
+          this.joinReject = null;
+        }
+        break;
+
+      case "room_completed":
+        this.handleRoomCompleted(msg.summary);
+        this.handlers.completed?.(msg.summary);
+        break;
+
+      case "agent_joined":
+        if (this.roomState) {
+          this.roomState.agents.push(msg.agent);
+        }
+        break;
+
+      case "agent_left":
+        if (this.roomState) {
+          this.roomState.agents = this.roomState.agents.filter(
+            (a) => a.id !== msg.agentId,
+          );
+        }
+        this.handlers.agent_left?.(msg.agentId);
+        break;
+
+      case "whisper":
+        this.handlers.whisper?.(msg.message);
+        break;
+
+      case "turn_skipped":
+        // Could emit an event later; for now just track
+        break;
+
+      case "room_deleted":
+        if (this.roomState) {
+          this.roomState.status = "expired";
+        }
+        this.closed = true;
+        this.ws?.close();
+        // Fire the agent_left handler as a signal — the room is gone
+        this.handlers.agent_left?.("room_deleted");
+        break;
+
+      case "stream_chunk":
+      case "thinking":
+        // Handled by future streaming support
+        break;
+    }
+  }
+
+  private async handleTurn(turn: number, round: number): Promise<void> {
+    if (!this.handlers.turn) return;
+
+    try {
+      const context: TurnContext = {
+        round,
+        turn,
+        room: this.roomState!,
+      };
+
+      const response = await this.handlers.turn(this.messages, context);
+
+      // Handle both string and object return types
+      const content = typeof response === "string" ? response : response.content;
+      const done = typeof response === "string" ? undefined : response.done;
+
+      // Filter response through permissions
+      const filtered = this.permissions.filterMessage(content);
+
+      if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+        this.ws.send(
+          JSON.stringify({
+            action: "message",
+            content: filtered,
+            ...(done ? { done: true } : {}),
+          }),
+        );
+      }
+    } catch (err) {
+      this.handlers.error?.(
+        err instanceof Error ? err : new Error(String(err)),
+      );
+    }
+  }
+
+  private handleRoomCompleted(_summary: RoomSummary): void {
+    if (this.roomState) {
+      this.roomState.status = "completed";
+    }
+    this.closed = true;
+    this.ws?.close();
+  }
+
+  // -----------------------------------------------------------------------
+  // Reconnection with exponential backoff + jitter
+  // -----------------------------------------------------------------------
+
+  private attemptReconnect(): void {
+    if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      const err = new Error(
+        `Failed to reconnect after ${MAX_RECONNECT_ATTEMPTS} attempts`,
+      );
+      this.handlers.error?.(err);
+      return;
+    }
+
+    const base = Math.min(
+      INITIAL_BACKOFF_MS * 2 ** this.reconnectAttempts,
+      MAX_BACKOFF_MS,
+    );
+    // Add jitter: +-25%
+    const jitter = base * 0.25 * (Math.random() * 2 - 1);
+    const delay = Math.round(base + jitter);
+
+    this.reconnectAttempts++;
+
+    setTimeout(() => {
+      if (!this.closed) {
+        this.connect();
+      }
+    }, delay);
+  }
+}