@vibevibes/runtime 0.2.0

package/src/protocol.ts

@@ -0,0 +1,324 @@
+/**
+ * Protocol experience support.
+ *
+ * Loads experiences defined as manifest.json + subprocess tool handler.
+ * The subprocess communicates via newline-delimited JSON over stdin/stdout.
+ */
+
+import { spawn, type ChildProcess } from "child_process";
+import * as path from "path";
+import * as fs from "fs";
+import type { ExperienceModule, ToolDef, ToolCtx, ToolEvent } from "@vibevibes/sdk";
+
+// ── Manifest types ──────────────────────────────────────────────────────
+
+export interface ProtocolManifest {
+  id: string;
+  version: string;
+  title: string;
+  description?: string;
+  initialState?: Record<string, any>;
+  tools: ProtocolToolDef[];
+  toolProcess: { command: string; args?: string[] };
+  agents?: Array<{
+    role: string;
+    systemPrompt: string;
+    allowedTools?: string[];
+    autoSpawn?: boolean;
+    maxInstances?: number;
+  }>;
+  observe?: { exclude?: string[]; include?: string[] };
+  canvas?: string;
+  netcode?: "default" | "tick";
+  tickRateMs?: number;
+  streams?: Array<{
+    name: string;
+    input_schema: Record<string, any>;
+    rateLimit?: number;
+  }>;
+  roomConfig?: {
+    schema: Record<string, any>;
+    defaults?: Record<string, any>;
+    presets?: Record<string, Record<string, any>>;
+    description?: string;
+  };
+}
+
+interface ProtocolToolDef {
+  name: string;
+  description: string;
+  input_schema: Record<string, any>;
+  risk?: "low" | "medium" | "high";
+}
+
+// ── JSON-RPC request/response ───────────────────────────────────────────
+
+interface RpcRequest {
+  id: string;
+  method: "tool" | "observe" | "stream" | "init" | "ping";
+  params: Record<string, any>;
+}
+
+interface RpcResponse {
+  id: string;
+  result?: Record<string, any>;
+  error?: { message: string; code?: string };
+}
+
+// ── Subprocess executor ─────────────────────────────────────────────────
+
+export class SubprocessExecutor {
+  private proc: ChildProcess | null = null;
+  private pending = new Map<string, {
+    resolve: (res: RpcResponse) => void;
+    reject: (err: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+  }>();
+  private buffer = "";
+  private seq = 0;
+  private command: string;
+  private args: string[];
+  private cwd: string;
+  private restarting = false;
+
+  constructor(command: string, args: string[], cwd: string) {
+    this.command = command;
+    this.args = args;
+    this.cwd = cwd;
+  }
+
+  start(): void {
+    if (this.proc) return;
+
+    this.proc = spawn(this.command, this.args, {
+      cwd: this.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+
+    this.proc.stdout!.on("data", (chunk: Buffer) => {
+      this.buffer += chunk.toString();
+      this.processBuffer();
+    });
+
+    this.proc.stderr!.on("data", (chunk: Buffer) => {
+      const msg = chunk.toString().trim();
+      if (msg) console.error(`[protocol:${this.command}] ${msg}`);
+    });
+
+    this.proc.on("exit", (code) => {
+      console.warn(`[protocol] Tool process exited with code ${code}`);
+      this.proc = null;
+      // Reject all pending requests
+      for (const [id, p] of this.pending) {
+        p.reject(new Error(`Tool process exited (code ${code})`));
+        clearTimeout(p.timer);
+      }
+      this.pending.clear();
+      this.buffer = "";
+
+      // Auto-restart after a short delay
+      if (!this.restarting) {
+        this.restarting = true;
+        setTimeout(() => {
+          this.restarting = false;
+          try { this.start(); } catch {}
+        }, 1000);
+      }
+    });
+
+    this.proc.on("error", (err) => {
+      console.error(`[protocol] Failed to spawn tool process: ${err.message}`);
+    });
+  }
+
+  stop(): void {
+    this.restarting = true; // Prevent auto-restart
+    if (this.proc) {
+      this.proc.kill();
+      this.proc = null;
+    }
+    for (const [, p] of this.pending) {
+      p.reject(new Error("Executor stopped"));
+      clearTimeout(p.timer);
+    }
+    this.pending.clear();
+  }
+
+  private processBuffer(): void {
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const response: RpcResponse = JSON.parse(trimmed);
+        const pending = this.pending.get(response.id);
+        if (pending) {
+          clearTimeout(pending.timer);
+          this.pending.delete(response.id);
+          pending.resolve(response);
+        }
+      } catch {
+        console.warn(`[protocol] Invalid JSON from tool process: ${trimmed.slice(0, 200)}`);
+      }
+    }
+  }
+
+  async send(method: RpcRequest["method"], params: Record<string, any>, timeoutMs = 10000): Promise<RpcResponse> {
+    if (!this.proc?.stdin?.writable) {
+      throw new Error("Tool process not running");
+    }
+
+    const id = `req-${++this.seq}`;
+    const request: RpcRequest = { id, method, params };
+
+    return new Promise<RpcResponse>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Tool process timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      try {
+        this.proc!.stdin!.write(JSON.stringify(request) + "\n");
+      } catch (err) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+
+  get running(): boolean {
+    return this.proc !== null && !this.proc.killed;
+  }
+}
+
+// ── Load a protocol experience ──────────────────────────────────────────
+
+export function isProtocolExperience(entryPath: string): boolean {
+  return entryPath.endsWith("manifest.json");
+}
+
+export function loadProtocolManifest(manifestPath: string): ProtocolManifest {
+  const raw = fs.readFileSync(manifestPath, "utf-8");
+  const manifest: ProtocolManifest = JSON.parse(raw);
+
+  if (!manifest.id) throw new Error("manifest.json: id is required");
+  if (!manifest.version) throw new Error("manifest.json: version is required");
+  if (!manifest.title) throw new Error("manifest.json: title is required");
+  if (!manifest.toolProcess) throw new Error("manifest.json: toolProcess is required");
+  if (!Array.isArray(manifest.tools)) throw new Error("manifest.json: tools must be an array");
+
+  return manifest;
+}
+
+/**
+ * Create a synthetic ExperienceModule from a protocol manifest.
+ * Tool handlers proxy calls to the subprocess executor.
+ */
+export function createProtocolModule(
+  manifest: ProtocolManifest,
+  executor: SubprocessExecutor,
+  manifestDir: string,
+): ExperienceModule & { initialState?: Record<string, any>; _executor: SubprocessExecutor; _canvasPath?: string } {
+
+  // Create tool defs with handlers that proxy to the subprocess
+  const tools: ToolDef[] = manifest.tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    // Use a plain object as input_schema with a parse method for compatibility
+    input_schema: createJsonSchemaValidator(t.input_schema),
+    risk: (t.risk || "low") as "low" | "medium" | "high",
+    capabilities_required: ["state.write"],
+    handler: async (ctx: ToolCtx, input: Record<string, any>) => {
+      const response = await executor.send("tool", {
+        tool: t.name,
+        input,
+        state: ctx.state,
+        actorId: ctx.actorId,
+        roomId: ctx.roomId,
+        timestamp: ctx.timestamp,
+      });
+
+      if (response.error) {
+        throw new Error(response.error.message);
+      }
+
+      if (response.result?.state) {
+        ctx.setState(response.result.state);
+      }
+
+      return response.result?.output ?? {};
+    },
+  }));
+
+  // Build observe function if manifest specifies observation config
+  let observe: ExperienceModule["observe"] | undefined;
+  if (manifest.observe) {
+    const { exclude, include } = manifest.observe;
+    observe = (state: Record<string, any>, _event: ToolEvent | null, _actorId: string) => {
+      if (include) {
+        const filtered: Record<string, any> = {};
+        for (const key of include) {
+          if (key in state) filtered[key] = state[key];
+        }
+        return filtered;
+      }
+      if (exclude) {
+        const filtered = { ...state };
+        for (const key of exclude) {
+          delete filtered[key];
+        }
+        return filtered;
+      }
+      return state;
+    };
+  }
+
+  // Resolve canvas path
+  const canvasFile = manifest.canvas || "index.html";
+  const canvasPath = path.resolve(manifestDir, canvasFile);
+  const hasCanvas = fs.existsSync(canvasPath);
+
+  return {
+    manifest: {
+      id: manifest.id,
+      version: manifest.version,
+      title: manifest.title,
+      description: manifest.description || "",
+      requested_capabilities: ["state.write"],
+      agentSlots: manifest.agents,
+      participantSlots: manifest.agents?.map((a) => ({ ...a, type: "ai" as const })),
+      netcode: manifest.netcode,
+      tickRateMs: manifest.tickRateMs,
+    },
+    Canvas: (() => null) as any, // Protocol experiences use HTML canvas, not React
+    tools,
+    observe,
+    initialState: manifest.initialState ?? {},
+    _executor: executor,
+    _canvasPath: hasCanvas ? canvasPath : undefined,
+  };
+}
+
+/**
+ * Create a minimal Zod-compatible validator from a JSON Schema.
+ * Only needs .parse() for the server's input validation.
+ */
+function createJsonSchemaValidator(schema: Record<string, any>): any {
+  return {
+    parse: (input: unknown) => {
+      // Basic type validation for protocol experiences
+      if (schema.type === "object" && typeof input !== "object") {
+        throw new Error("Expected object input");
+      }
+      return input;
+    },
+    // Expose the raw JSON Schema for tool listing
+    _jsonSchema: schema,
+  };
+}