@kodama-run/sdk 0.1.0

package/src/adapters/openclaw.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env bun
+
+import { Kodama } from "../room.ts";
+import type { RoomMessage } from "@kodama-run/shared";
+
+// ---------------------------------------------------------------------------
+// Types for OpenClaw skill interface
+// ---------------------------------------------------------------------------
+
+interface SkillContext {
+  /** OpenClaw provides this — agent context, memory, etc. */
+  [key: string]: unknown;
+}
+
+interface KodamaSkillOptions {
+  relayUrl?: string;
+  agentName?: string;
+}
+
+type ActionParams =
+  | { action: "create"; relay_url?: string; password?: string }
+  | { action: "join"; code: string; name?: string; relay_url?: string }
+  | { action: "respond"; content: string }
+  | { action: "leave" };
+
+// ---------------------------------------------------------------------------
+// State machine: idle → joined → in_turn → idle
+// ---------------------------------------------------------------------------
+
+type SkillState = "idle" | "joined" | "in_turn";
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createKodamaSkill(options?: KodamaSkillOptions) {
+  const defaultRelay = options?.relayUrl ?? "http://localhost:8000";
+  const defaultName = options?.agentName ?? "OpenClaw Agent";
+
+  let agent: Kodama | null = null;
+  let state: SkillState = "idle";
+  let turnResolve: ((messages: RoomMessage[]) => void) | null = null;
+  let respondResolve: ((messages: RoomMessage[]) => void) | null = null;
+
+  return {
+    name: "kodama",
+    description:
+      "Join a Kodama negotiation room to converse with other agents. " +
+      "Actions: create, join, respond, leave.",
+
+    parameters: {
+      type: "object",
+      required: ["action"],
+      properties: {
+        action: {
+          type: "string",
+          enum: ["create", "join", "respond", "leave"],
+          description: "The operation to perform.",
+        },
+        code: { type: "string", description: "Room code (for join)." },
+        name: { type: "string", description: "Agent display name (for join)." },
+        relay_url: { type: "string", description: "Relay URL override." },
+        password: { type: "string", description: "Room password (for create/join)." },
+        content: { type: "string", description: "Message content (for respond)." },
+      },
+    },
+
+    async execute(params: ActionParams, _context?: SkillContext) {
+      switch (params.action) {
+        // -----------------------------------------------------------------
+        // CREATE — call the relay HTTP API to create a new room
+        // -----------------------------------------------------------------
+        case "create": {
+          const relay = params.relay_url ?? defaultRelay;
+          const body: Record<string, unknown> = {};
+          if (params.password) body.password = params.password;
+
+          const res = await fetch(`${relay}/api/rooms`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+          });
+
+          if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Failed to create room (HTTP ${res.status}): ${text}`);
+          }
+
+          const data = (await res.json()) as { code: string };
+          const wsBase = relay
+            .replace(/^http:\/\//, "ws://")
+            .replace(/^https:\/\//, "wss://");
+
+          return {
+            code: data.code,
+            relay_ws: `${wsBase}/ws`,
+            password: params.password ?? null,
+          };
+        }
+
+        // -----------------------------------------------------------------
+        // JOIN — connect to a room and wait for the first turn
+        // -----------------------------------------------------------------
+        case "join": {
+          if (state !== "idle") {
+            throw new Error(`Cannot join: already in state "${state}". Leave first.`);
+          }
+
+          const relay = params.relay_url ?? defaultRelay;
+          const wsUrl = relay.startsWith("ws")
+            ? relay
+            : relay.replace(/^http:\/\//, "ws://").replace(/^https:\/\//, "wss://") + "/ws";
+
+          agent = new Kodama(params.code, {
+            relayUrl: wsUrl,
+            name: params.name ?? defaultName,
+          });
+
+          agent.on("error", (err) => {
+            // Surface errors to any pending promise
+            turnResolve = null;
+            respondResolve = null;
+            throw err;
+          });
+
+          agent.on("turn", (messages) => {
+            state = "in_turn";
+            // If we're waiting for a turn (from join or respond), resolve it
+            if (turnResolve) {
+              turnResolve(messages);
+              turnResolve = null;
+            }
+            if (respondResolve) {
+              respondResolve(messages);
+              respondResolve = null;
+            }
+
+            // Return a promise that blocks until the agent calls respond()
+            return new Promise<string>((resolve) => {
+              // Stash resolve so respond() can call it
+              (agent as any).__respondResolve = resolve;
+            });
+          });
+
+          await agent.join();
+          state = "joined";
+
+          // Wait for the first turn signal
+          const messages = await new Promise<RoomMessage[]>((resolve) => {
+            turnResolve = resolve;
+          });
+
+          return {
+            status: "joined",
+            room: params.code,
+            messages: messages.map((m) => ({
+              agent: m.agent.name,
+              content: m.content,
+              round: m.round,
+              turn: m.turn,
+            })),
+          };
+        }
+
+        // -----------------------------------------------------------------
+        // RESPOND — send a message and wait for the next turn (or completion)
+        // -----------------------------------------------------------------
+        case "respond": {
+          if (state !== "in_turn" || !agent) {
+            throw new Error(`Cannot respond: not in a turn (state="${state}").`);
+          }
+
+          const resolve = (agent as any).__respondResolve as
+            | ((v: string) => void)
+            | undefined;
+          if (!resolve) {
+            throw new Error("No pending turn to respond to.");
+          }
+
+          // Resolve the turn handler promise so the SDK sends the message
+          resolve(params.content);
+          (agent as any).__respondResolve = null;
+          state = "joined";
+
+          // Wait for the next turn or room completion
+          const room = agent.getRoom();
+          if (room?.status === "completed") {
+            return { status: "completed" };
+          }
+
+          const messages = await new Promise<RoomMessage[]>((resolve) => {
+            turnResolve = resolve;
+          });
+
+          return {
+            status: "your_turn",
+            messages: messages.map((m) => ({
+              agent: m.agent.name,
+              content: m.content,
+              round: m.round,
+              turn: m.turn,
+            })),
+          };
+        }
+
+        // -----------------------------------------------------------------
+        // LEAVE — disconnect from the room
+        // -----------------------------------------------------------------
+        case "leave": {
+          if (agent) {
+            agent.leave();
+            agent = null;
+          }
+          state = "idle";
+          turnResolve = null;
+          respondResolve = null;
+          return { status: "left" };
+        }
+
+        default:
+          throw new Error(`Unknown action: ${(params as any).action}`);
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Default skill instance
+// ---------------------------------------------------------------------------
+
+export const kodamaSkill = createKodamaSkill();

package/src/crypto.ts

@@ -0,0 +1,102 @@
+/**
+ * AES-256-GCM encryption via Web Crypto API (Excalidraw pattern).
+ *
+ * Keys are exported/imported as base64 strings for easy sharing
+ * (e.g. via URL fragment).
+ */
+
+const ALGO = "AES-GCM";
+const KEY_LENGTH = 256;
+const IV_LENGTH = 12; // 96-bit IV recommended for GCM
+
+function toBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+function fromBase64(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+export class KodamaCrypto {
+  /**
+   * Generate a new AES-256-GCM key and export as base64.
+   */
+  static async generateKey(): Promise<string> {
+    const key = await crypto.subtle.generateKey(
+      { name: ALGO, length: KEY_LENGTH },
+      true, // extractable
+      ["encrypt", "decrypt"],
+    );
+    const raw = await crypto.subtle.exportKey("raw", key);
+    return toBase64(raw);
+  }
+
+  /**
+   * Encrypt plaintext with AES-256-GCM.
+   * Returns base64-encoded ciphertext and IV.
+   */
+  static async encrypt(
+    keyBase64: string,
+    plaintext: string,
+  ): Promise<{ ciphertext: string; iv: string }> {
+    const key = await KodamaCrypto.importKey(keyBase64);
+    const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+    const encoded = new TextEncoder().encode(plaintext);
+
+    const cipherBuffer = await crypto.subtle.encrypt(
+      { name: ALGO, iv },
+      key,
+      encoded,
+    );
+
+    return {
+      ciphertext: toBase64(cipherBuffer),
+      iv: toBase64(iv.buffer),
+    };
+  }
+
+  /**
+   * Decrypt AES-256-GCM ciphertext back to plaintext.
+   */
+  static async decrypt(
+    keyBase64: string,
+    ciphertextBase64: string,
+    ivBase64: string,
+  ): Promise<string> {
+    const key = await KodamaCrypto.importKey(keyBase64);
+    const iv = fromBase64(ivBase64);
+    const ciphertext = fromBase64(ciphertextBase64);
+
+    const plainBuffer = await crypto.subtle.decrypt(
+      { name: ALGO, iv: iv as BufferSource },
+      key,
+      ciphertext as BufferSource,
+    );
+
+    return new TextDecoder().decode(plainBuffer);
+  }
+
+  /**
+   * Import a base64 key string as a CryptoKey.
+   */
+  private static async importKey(keyBase64: string): Promise<CryptoKey> {
+    const raw = fromBase64(keyBase64);
+    return crypto.subtle.importKey(
+      "raw",
+      raw as BufferSource,
+      { name: ALGO, length: KEY_LENGTH },
+      false,
+      ["encrypt", "decrypt"],
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { Kodama } from "./room.ts";
+export type { KodamaOptions, TurnContext } from "./room.ts";
+export { KodamaCrypto } from "./crypto.ts";
+export { PermissionChecker } from "./permissions.ts";
+export type { PermissionConfig } from "./permissions.ts";
+
+// MCP adapter — standalone stdio server, not a library import.
+// Run directly:  bun packages/sdk/src/adapters/mcp.ts
+// See:           ./adapters/mcp.ts

package/src/permissions.ts

@@ -0,0 +1,160 @@
+import { readFile } from "node:fs/promises";
+import { AUTO_DENY_PATTERNS } from "@kodama-run/shared";
+
+export interface PermissionConfig {
+  allow?: string[];
+  deny?: string[];
+}
+
+/**
+ * Convert a glob pattern to a RegExp.
+ *   ** = any path (including slashes)
+ *   *  = any non-slash segment
+ *   .  = literal dot
+ */
+function globToRegex(pattern: string): RegExp {
+  let re = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === "*" && pattern[i + 1] === "*") {
+      // ** matches anything including path separators
+      re += ".*";
+      i += 2;
+      // Skip trailing slash after ** (e.g. **/)
+      if (pattern[i] === "/") i++;
+    } else if (ch === "*") {
+      // * matches anything except /
+      re += "[^/]*";
+      i++;
+    } else if (ch === "?") {
+      re += "[^/]";
+      i++;
+    } else if (ch === ".") {
+      re += "\\.";
+      i++;
+    } else {
+      re += ch;
+      i++;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function matchesAny(filePath: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => globToRegex(pattern).test(filePath));
+}
+
+/**
+ * Enforces .kodama permission files.
+ *
+ * - If an explicit allow list exists, a file must match allow AND not match deny.
+ * - If no allow list, allow everything except deny.
+ * - AUTO_DENY_PATTERNS are always appended to the deny list.
+ */
+export class PermissionChecker {
+  private readonly allowPatterns: string[] | null;
+  private readonly denyPatterns: string[];
+
+  constructor(config?: PermissionConfig) {
+    this.allowPatterns = config?.allow?.length ? config.allow : null;
+    this.denyPatterns = [...(config?.deny ?? []), ...AUTO_DENY_PATTERNS];
+  }
+
+  /**
+   * Check if a file path is allowed by the permission rules.
+   * Tests against the basename for deny patterns that don't contain slashes,
+   * and against the full path for patterns that do.
+   */
+  isAllowed(filePath: string): boolean {
+    // Check deny list — match against full path AND basename
+    const basename = filePath.split("/").pop() ?? filePath;
+    for (const pattern of this.denyPatterns) {
+      // If pattern has no slash, match against basename; otherwise match full path
+      if (!pattern.includes("/")) {
+        if (globToRegex(pattern).test(basename)) return false;
+      } else {
+        if (globToRegex(pattern).test(filePath)) return false;
+      }
+    }
+
+    // If allow list exists, file must match at least one allow pattern
+    if (this.allowPatterns !== null) {
+      return matchesAny(filePath, this.allowPatterns);
+    }
+
+    return true;
+  }
+
+  /**
+   * Content-level message filtering (pass-through for now).
+   */
+  filterMessage(content: string): string {
+    return content;
+  }
+
+  /**
+   * Parse a simple YAML permission file format.
+   *
+   * Expected format:
+   * ```
+   * allow:
+   *   - src/**
+   *   - docs/*.md
+   * deny:
+   *   - "*.log"
+   *   - tmp/**
+   * ```
+   */
+  static fromYaml(content: string): PermissionChecker {
+    const lines = content.split("\n");
+    const allow: string[] = [];
+    const deny: string[] = [];
+    let currentSection: "allow" | "deny" | null = null;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed === "allow:") {
+        currentSection = "allow";
+      } else if (trimmed === "deny:") {
+        currentSection = "deny";
+      } else if (trimmed.startsWith("- ") && currentSection) {
+        // Strip the "- " prefix and any surrounding quotes
+        let value = trimmed.slice(2).trim();
+        if (
+          (value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))
+        ) {
+          value = value.slice(1, -1);
+        }
+        if (currentSection === "allow") {
+          allow.push(value);
+        } else {
+          deny.push(value);
+        }
+      } else if (trimmed !== "" && !trimmed.startsWith("#")) {
+        // Non-empty, non-comment line that isn't a list item — reset section
+        currentSection = null;
+      }
+    }
+
+    return new PermissionChecker({
+      allow: allow.length > 0 ? allow : undefined,
+      deny: deny.length > 0 ? deny : undefined,
+    });
+  }
+
+  /**
+   * Read a .kodama permission file and return a checker.
+   * Returns a permissive default if the file doesn't exist.
+   */
+  static async fromFile(path: string): Promise<PermissionChecker> {
+    try {
+      const content = await readFile(path, "utf-8");
+      return PermissionChecker.fromYaml(content);
+    } catch {
+      // File doesn't exist or can't be read — return permissive default
+      return new PermissionChecker();
+    }
+  }
+}