@whitesands/agent-player 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,938 @@
+// src/agent-server.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+// src/errors.ts
+var PlatformAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PlatformAuthError";
+  }
+};
+var ProtocolVersionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProtocolVersionError";
+  }
+};
+var TurnFailedError = class extends Error {
+  attempts;
+  constructor(message, attempts = []) {
+    super(message);
+    this.name = "TurnFailedError";
+    this.attempts = attempts;
+  }
+};
+var TurnTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TurnTimeoutError";
+  }
+};
+var ConnectionLostError = class extends Error {
+  constructor(message = "Connection to the platform was lost") {
+    super(message);
+    this.name = "ConnectionLostError";
+  }
+};
+
+// src/logger.ts
+function log(logger, level, message, extra) {
+  logger?.[level]?.(message, extra);
+}
+
+// src/platform-connection.ts
+import { randomUUID } from "crypto";
+import WebSocket from "ws";
+
+// src/protocol.ts
+var PROTOCOL_VERSION = 1;
+var SDK_VERSION = "0.1.0";
+var SESSION_RESUME_GRACE_MS = 3e4;
+var DEFAULT_AGENT_INSTRUCTIONS = [
+  "You are a remote game agent. Tools are provided by the game.",
+  "On every turn: call wait first. It blocks until the game grants your turn and then returns the current view from see.",
+  "After wait returns, call exactly one action tool (not see, not wait).",
+  "If an action tool returns an error, retry once with a corrected action. A second failure ends the turn as failed."
+].join("\n");
+function assertNever(value) {
+  throw new Error(`Unhandled protocol message: ${JSON.stringify(value)}`);
+}
+
+// src/ws-transport.ts
+var SessionMuxTransport = class {
+  onclose;
+  onerror;
+  onmessage;
+  sessionId;
+  sid;
+  sendEnvelope;
+  started = false;
+  closed = false;
+  constructor(sessionId, sendEnvelope) {
+    this.sid = sessionId;
+    this.sessionId = sessionId;
+    this.sendEnvelope = sendEnvelope;
+  }
+  async start() {
+    if (this.closed) throw new Error("Transport already closed");
+    this.started = true;
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.onclose?.();
+  }
+  async send(message) {
+    if (this.closed) throw new Error("Transport closed");
+    this.sendEnvelope({ type: "mcp", sessionId: this.sid, message });
+  }
+  /** Deliver an inbound MCP message from the platform. */
+  receive(message) {
+    if (this.closed || !this.started) return;
+    try {
+      this.onmessage?.(message);
+    } catch (error) {
+      this.onerror?.(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+};
+
+// src/platform-connection.ts
+var HEARTBEAT_MS = 15e3;
+var PONG_TIMEOUT_MS = 1e4;
+var MAX_RECONNECT_ATTEMPTS = 8;
+var PlatformConnection = class {
+  ws = null;
+  url;
+  platformKey;
+  clientId = randomUUID();
+  handlers;
+  logger;
+  pending = /* @__PURE__ */ new Map();
+  outbox = [];
+  accountName = null;
+  closed = false;
+  everConnected = false;
+  reconnecting = false;
+  reconnectAttempt = 0;
+  reconnectTimer;
+  heartbeat;
+  pongTimer;
+  pendingPong = null;
+  constructor(url, platformKey, handlers, logger) {
+    this.url = url;
+    this.platformKey = platformKey;
+    this.handlers = handlers;
+    this.logger = logger;
+  }
+  get connected() {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+  async connect() {
+    if (this.closed) throw new Error("Platform connection is closed");
+    if (this.connected && this.accountName) return this.accountName;
+    const account = await this.openSocket();
+    this.everConnected = true;
+    this.reconnectAttempt = 0;
+    return account;
+  }
+  send(envelope) {
+    if (this.connected && this.ws) {
+      this.ws.send(JSON.stringify(envelope));
+      return;
+    }
+    if (envelope.type === "mcp" || envelope.type === "ping") {
+      this.outbox.push(envelope);
+      return;
+    }
+    throw new Error("Not connected to platform");
+  }
+  waitForSessionEvent(sessionId, kind, timeoutMs = 15e3) {
+    const key = `session:${sessionId}:${kind}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(key);
+        reject(new Error(`Timed out waiting for session ${kind}`));
+      }, timeoutMs);
+      this.pending.set(key, {
+        resolve: (envelope) => {
+          clearTimeout(timer);
+          resolve(envelope);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+    });
+  }
+  createTransport(sessionId) {
+    return new SessionMuxTransport(sessionId, (envelope) => this.send(envelope));
+  }
+  async close() {
+    this.closed = true;
+    this.stopHeartbeat();
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = void 0;
+    this.reconnecting = false;
+    this.failWaiters(new Error("platform connection closed"));
+    if (!this.ws) return;
+    const ws = this.ws;
+    this.ws = null;
+    await new Promise((resolve) => {
+      ws.once("close", () => resolve());
+      ws.close();
+    });
+  }
+  openSocket() {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.url);
+      this.ws = ws;
+      let settled = false;
+      const fail = (error) => {
+        if (settled) return;
+        settled = true;
+        reject(error);
+      };
+      ws.on("open", () => {
+        ws.send(JSON.stringify({
+          type: "hello",
+          platformKey: this.platformKey,
+          clientId: this.clientId,
+          protocolVersion: PROTOCOL_VERSION,
+          sdkVersion: SDK_VERSION
+        }));
+      });
+      ws.on("message", (data) => {
+        let envelope;
+        try {
+          envelope = JSON.parse(data.toString());
+        } catch (error) {
+          const parsed = error instanceof Error ? error : new Error("Invalid platform message");
+          this.handlers.onError?.(parsed);
+          return;
+        }
+        if (!settled && (envelope.type === "hello_ok" || envelope.type === "hello_err")) {
+          settled = true;
+          if (envelope.type === "hello_err") {
+            const error = envelope.code === "PROTOCOL" ? new ProtocolVersionError(envelope.message) : new PlatformAuthError(envelope.message);
+            this.closed = true;
+            reject(error);
+            ws.close();
+            return;
+          }
+          this.accountName = envelope.accountName;
+          this.startHeartbeat();
+          this.flushOutbox();
+          resolve(envelope.accountName);
+          return;
+        }
+        if (envelope.type === "pong") {
+          if (this.pendingPong === envelope.id) {
+            this.pendingPong = null;
+            if (this.pongTimer) clearTimeout(this.pongTimer);
+            this.pongTimer = void 0;
+          }
+          return;
+        }
+        this.resolveSessionWaiter(envelope);
+        this.handlers.onEnvelope(envelope);
+      });
+      ws.on("error", (error) => {
+        this.handlers.onError?.(error);
+        fail(error);
+      });
+      ws.on("close", () => {
+        this.stopHeartbeat();
+        if (this.ws === ws) this.ws = null;
+        if (!settled) fail(new Error("platform connection closed before hello"));
+        if (this.closed || !this.everConnected) {
+          this.failWaiters(new Error("platform connection closed"));
+          return;
+        }
+        this.handlers.onDisconnect?.();
+        this.scheduleReconnect();
+      });
+    });
+  }
+  resolveSessionWaiter(envelope) {
+    if (envelope.type === "session_started" || envelope.type === "session_stopped") {
+      const kind = envelope.type === "session_started" ? "start" : "stop";
+      const waiter = this.pending.get(`session:${envelope.sessionId}:${kind}`);
+      if (!waiter) return;
+      this.pending.delete(`session:${envelope.sessionId}:${kind}`);
+      waiter.resolve(envelope);
+      return;
+    }
+    if (envelope.type === "session_resumed" || envelope.type === "resume_err") {
+      const waiter = this.pending.get(`session:${envelope.sessionId}:resume`);
+      if (!waiter) return;
+      this.pending.delete(`session:${envelope.sessionId}:resume`);
+      if (envelope.type === "resume_err") {
+        waiter.reject(new ConnectionLostError(envelope.message));
+        return;
+      }
+      waiter.resolve(envelope);
+    }
+  }
+  scheduleReconnect() {
+    if (this.closed || this.reconnecting) return;
+    if (this.reconnectAttempt >= MAX_RECONNECT_ATTEMPTS) {
+      this.closed = true;
+      const error = new ConnectionLostError("Could not reconnect to the platform");
+      this.handlers.onError?.(error);
+      this.failWaiters(error);
+      return;
+    }
+    const delay = Math.min(SESSION_RESUME_GRACE_MS, 250 * 2 ** this.reconnectAttempt);
+    this.reconnectAttempt += 1;
+    this.reconnecting = true;
+    log(this.logger, "warn", `platform connection dropped; retrying in ${delay}ms`);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = void 0;
+      void this.reconnect();
+    }, delay);
+    this.reconnectTimer.unref?.();
+  }
+  async reconnect() {
+    try {
+      await this.openSocket();
+      this.everConnected = true;
+      this.reconnectAttempt = 0;
+      this.reconnecting = false;
+      const sessions = this.handlers.sessions?.() ?? [];
+      for (const session of sessions) {
+        const resumed = this.waitForSessionEvent(session.sessionId, "resume");
+        this.send({
+          type: "resume_session",
+          sessionId: session.sessionId,
+          sessionToken: session.sessionToken
+        });
+        await resumed;
+      }
+      this.handlers.onReconnect?.();
+    } catch (error) {
+      this.reconnecting = false;
+      if (this.closed) return;
+      const wrapped = error instanceof Error ? error : new Error(String(error));
+      if (wrapped instanceof PlatformAuthError || wrapped instanceof ProtocolVersionError) {
+        this.closed = true;
+        this.handlers.onError?.(wrapped);
+        this.failWaiters(wrapped);
+        return;
+      }
+      this.scheduleReconnect();
+    }
+  }
+  flushOutbox() {
+    if (!this.ws || !this.connected) return;
+    const pending = this.outbox.splice(0, this.outbox.length);
+    for (const envelope of pending) {
+      this.ws.send(JSON.stringify(envelope));
+    }
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeat = setInterval(() => {
+      if (!this.connected) return;
+      const id = randomUUID();
+      this.pendingPong = id;
+      try {
+        this.send({ type: "ping", id });
+      } catch {
+        return;
+      }
+      this.pongTimer = setTimeout(() => {
+        if (this.pendingPong === id) {
+          log(this.logger, "warn", "platform heartbeat timed out");
+          this.ws?.terminate();
+        }
+      }, PONG_TIMEOUT_MS);
+      this.pongTimer.unref?.();
+    }, HEARTBEAT_MS);
+    this.heartbeat.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    if (this.pongTimer) clearTimeout(this.pongTimer);
+    this.heartbeat = void 0;
+    this.pongTimer = void 0;
+    this.pendingPong = null;
+  }
+  failWaiters(error) {
+    for (const [, waiter] of this.pending) waiter.reject(error);
+    this.pending.clear();
+  }
+};
+
+// src/reflect.ts
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+var SKIP = /* @__PURE__ */ new Set(["constructor"]);
+var SEE_DESCRIPTION = "Read the current game view for this player. Prefer wait, which returns this after the game grants a turn.";
+var WAIT_DESCRIPTION = "Block until the game calls turn() for this session, then return the current see() view.";
+function getParamNames(fn) {
+  const src = fn.toString().replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+  const header = src.match(/(?:async\s+)?(?:function\s*)?(?:\w*)\s*\(([^)]*)\)/) ?? src.match(/^(?:async\s*)?\(?([^)=]*)\)?\s*=>/);
+  if (!header) return [];
+  const raw = header[1]?.trim() ?? "";
+  if (!raw) return [];
+  return raw.split(",").map((part) => part.trim()).filter(Boolean).map((part) => {
+    const cleaned = part.replace(/\s*=\s*[^,]+$/, "").trim();
+    const name = cleaned.split(/[:\s]/)[0]?.replace(/^\.\.\./, "") ?? "";
+    return name;
+  }).filter((name) => name.length > 0 && name !== "this");
+}
+function collectMethodNames(instance) {
+  const names = /* @__PURE__ */ new Set();
+  let proto = Object.getPrototypeOf(instance);
+  while (proto && proto !== Object.prototype) {
+    for (const name of Object.getOwnPropertyNames(proto)) {
+      if (SKIP.has(name) || name.startsWith("_")) continue;
+      const desc = Object.getOwnPropertyDescriptor(proto, name);
+      if (!desc || typeof desc.value !== "function") continue;
+      names.add(name);
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return [...names].sort();
+}
+function readMetadata(instance) {
+  const ctor = instance.constructor;
+  return ctor.agent;
+}
+function toJsonSchema(schema) {
+  const json = zodToJsonSchema(schema, { target: "jsonSchema7", $refStrategy: "none" });
+  delete json.$schema;
+  return json;
+}
+function formatZodError(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "arguments";
+    return `${path}: ${issue.message}`;
+  }).join("; ");
+}
+function buildTool(instance, name, description, spec) {
+  const fn = instance[name];
+  if (typeof fn !== "function") {
+    throw new Error(`Expected method ${name}`);
+  }
+  const paramNames = spec?.args ? Object.keys(spec.args) : getParamNames(fn);
+  const shape = spec?.args ?? Object.fromEntries(paramNames.map((param) => [param, z.any()]));
+  const argsSchema = paramNames.length > 0 || spec?.args ? z.object(shape) : void 0;
+  const inputSchema = spec?.args && argsSchema ? toJsonSchema(argsSchema) : {
+    type: "object",
+    properties: Object.fromEntries(paramNames.map((param) => [param, {}])),
+    ...paramNames.length > 0 ? { required: paramNames } : {}
+  };
+  return {
+    name,
+    description,
+    paramNames,
+    ...argsSchema ? { argsSchema } : {},
+    descriptor: { name, description, inputSchema },
+    async invoke(args) {
+      let parsed = args ?? {};
+      if (argsSchema) {
+        const result = argsSchema.safeParse(args ?? {});
+        if (!result.success) {
+          throw new Error(formatZodError(result.error));
+        }
+        parsed = result.data;
+      }
+      const ordered = paramNames.map((param) => parsed[param]);
+      return await Promise.resolve(fn.apply(instance, ordered));
+    }
+  };
+}
+function reflectPlayer(instance) {
+  const names = collectMethodNames(instance);
+  if (!names.includes("see")) {
+    throw new Error("Player must implement a public see() method");
+  }
+  const metadata = readMetadata(instance);
+  const declared = metadata?.actions ?? {};
+  const className = instance.constructor?.name || "Player";
+  for (const name of Object.keys(declared)) {
+    if (!names.includes(name) || name === "see") {
+      throw new Error(`Declared action "${name}" is not a public method on ${className}`);
+    }
+  }
+  const see = buildTool(instance, "see", SEE_DESCRIPTION);
+  const actionNames = names.filter((name) => name !== "see");
+  const actions = actionNames.map((name) => {
+    const spec = declared[name];
+    const description = spec?.description ?? `Action: ${name}`;
+    return buildTool(instance, name, description, spec);
+  });
+  const wait = {
+    name: "wait",
+    description: WAIT_DESCRIPTION,
+    inputSchema: { type: "object", properties: {} }
+  };
+  return {
+    ...metadata?.description ? { description: metadata.description } : {},
+    see,
+    actions,
+    tools: [see.descriptor, ...actions.map((action) => action.descriptor), wait]
+  };
+}
+
+// src/session-mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+function jsonResult(payload, isError = false) {
+  return {
+    isError,
+    content: [{ type: "text", text: JSON.stringify(payload) }]
+  };
+}
+function toolError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return jsonResult({ error: message }, true);
+}
+function createSessionMcpServer(player, gate, options) {
+  const server = new McpServer(
+    { name: options?.name ?? "agent-player", version: SDK_VERSION },
+    { capabilities: { tools: {} } }
+  );
+  server.registerTool(
+    "see",
+    { description: player.see.description },
+    async () => {
+      try {
+        const view = await player.see.invoke({});
+        return jsonResult(view);
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+  server.registerTool(
+    "wait",
+    { description: WAIT_DESCRIPTION },
+    async () => {
+      try {
+        await gate.waitForTurn();
+        const view = await player.see.invoke({});
+        return jsonResult(view);
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+  for (const action of player.actions) {
+    const handler = async (args) => {
+      try {
+        const result = await action.invoke(args);
+        return jsonResult(result ?? { ok: true });
+      } catch (error) {
+        return toolError(error);
+      }
+    };
+    if (action.argsSchema) {
+      server.registerTool(
+        action.name,
+        {
+          description: action.description,
+          inputSchema: action.argsSchema.shape
+        },
+        async (args) => handler(args)
+      );
+    } else {
+      server.registerTool(
+        action.name,
+        { description: action.description },
+        async () => handler({})
+      );
+    }
+  }
+  return server;
+}
+
+// src/turn-gate.ts
+function abortError(signal) {
+  const reason = signal.reason;
+  if (reason instanceof Error) return reason;
+  if (typeof reason === "string" && reason.length > 0) return new Error(reason);
+  return new Error("turn aborted");
+}
+var TurnGate = class {
+  waitResolve = null;
+  waitPromise = null;
+  turnResolve = null;
+  turnReject = null;
+  turnPromise = null;
+  released = false;
+  /** Called by the wait tool. Blocks until turn() releases this session. */
+  async waitForTurn() {
+    if (this.released) {
+      this.released = false;
+      return;
+    }
+    if (!this.waitPromise) {
+      this.waitPromise = new Promise((resolve) => {
+        this.waitResolve = resolve;
+      });
+    }
+    await this.waitPromise;
+    this.waitPromise = null;
+    this.waitResolve = null;
+    this.released = false;
+  }
+  /**
+   * Unblock wait and wait for the platform's turn report.
+   * Rejects on timeout or abort; those do not produce a TurnOutcome.
+   */
+  async runTurn(options) {
+    if (this.turnPromise) {
+      throw new Error("turn() already in progress for this session");
+    }
+    if (options?.signal?.aborted) {
+      throw abortError(options.signal);
+    }
+    let timeoutId;
+    let onAbort;
+    const signal = options?.signal;
+    this.turnPromise = new Promise((resolve, reject) => {
+      this.turnResolve = resolve;
+      this.turnReject = reject;
+      if (options?.timeoutMs != null) {
+        timeoutId = setTimeout(() => {
+          this.rejectTurn(new TurnTimeoutError(`turn() timed out after ${options.timeoutMs}ms`));
+        }, options.timeoutMs);
+      }
+      if (signal) {
+        if (signal.aborted) {
+          this.rejectTurn(abortError(signal));
+          return;
+        }
+        onAbort = () => this.rejectTurn(abortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+    this.released = true;
+    const release = this.waitResolve;
+    this.waitResolve = null;
+    this.waitPromise = null;
+    release?.();
+    try {
+      return await this.turnPromise;
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+      this.turnPromise = null;
+      this.turnResolve = null;
+      this.turnReject = null;
+    }
+  }
+  /** Platform finished one action cycle (success or second failure). */
+  completeTurn(outcome) {
+    const resolve = this.turnResolve;
+    if (!resolve) return;
+    this.turnResolve = null;
+    this.turnReject = null;
+    resolve(outcome);
+  }
+  /** Fail an in-flight turn, for example when the connection cannot be resumed. */
+  failTurn(error) {
+    this.rejectTurn(error);
+  }
+  reset() {
+    this.waitResolve?.();
+    this.completeTurn({ ok: false, error: "session stopped" });
+    this.waitResolve = null;
+    this.waitPromise = null;
+    this.released = false;
+  }
+  rejectTurn(error) {
+    const reject = this.turnReject;
+    if (!reject) return;
+    this.turnResolve = null;
+    this.turnReject = null;
+    reject(error);
+  }
+};
+
+// src/agent-server.ts
+var DEFAULT_TURN_TIMEOUT_MS = 6e4;
+var DEFAULT_PLATFORM_URL = "ws://127.0.0.1:8787";
+var AgentServer = class {
+  options;
+  platformKey;
+  platformUrl;
+  logger;
+  connection = null;
+  sessions = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  inline;
+  started = false;
+  closing = false;
+  constructor(options = {}) {
+    const platformKey = options.platformKey ?? process.env.WSI_PLATFORM_KEY;
+    if (!options.inline && !platformKey) {
+      throw new Error("Set WSI_PLATFORM_KEY or pass platformKey, unless an inline platform is provided");
+    }
+    this.options = options;
+    this.platformKey = platformKey || "inline";
+    this.platformUrl = options.platformUrl ?? process.env.WSI_PLATFORM_URL ?? DEFAULT_PLATFORM_URL;
+    this.logger = options.logger;
+    this.inline = options.inline;
+    if (options.onEvent) this.listeners.add(options.onEvent);
+  }
+  /** Ensure the outbound platform connection. No-op for an inline platform. */
+  async connect() {
+    if (this.inline || this.started) {
+      this.started = true;
+      return;
+    }
+    this.connection = new PlatformConnection(this.platformUrl, this.platformKey, {
+      onEnvelope: (envelope) => this.handleEnvelope(envelope),
+      onDisconnect: () => this.emit({ type: "disconnected" }),
+      onReconnect: () => this.emit({ type: "reconnected" }),
+      onError: (error) => {
+        log(this.logger, "error", error.message);
+        if (error instanceof ConnectionLostError) this.failInflight(error);
+      },
+      sessions: () => [...this.sessions.values()].map((session) => ({
+        sessionId: session.id,
+        sessionToken: session.token
+      }))
+    }, this.logger);
+    await this.connection.connect();
+    this.started = true;
+  }
+  /**
+   * Reflect the player into tools, register a session, and return a handle.
+   * `turn()` on that handle lets the remote model act once.
+   */
+  async start(instance, options) {
+    await this.connect();
+    const reflected = reflectPlayer(instance);
+    const sessionId = randomUUID2();
+    const sessionToken = randomUUID2();
+    const gate = new TurnGate();
+    const name = options?.name ?? instance.constructor?.name ?? "player";
+    const server = createSessionMcpServer(reflected, gate, {
+      name: `agent-player:${name}`
+    });
+    const instructions = [this.options.instructions ?? DEFAULT_AGENT_INSTRUCTIONS, options?.instructions].filter((part) => Boolean(part && part.length > 0)).join("\n\n");
+    const listeners = /* @__PURE__ */ new Set();
+    const record = {
+      id: sessionId,
+      token: sessionToken,
+      name,
+      gate,
+      server,
+      transport: void 0,
+      listeners
+    };
+    const onTurnResult = (result) => {
+      gate.completeTurn(result);
+    };
+    const onEvent = (event) => this.emit(event);
+    if (this.inline) {
+      const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
+      await server.connect(serverTransport);
+      record.transport = serverTransport;
+      this.sessions.set(sessionId, record);
+      await this.inline.startSession({
+        sessionId,
+        sessionToken,
+        name,
+        tools: reflected.tools,
+        instructions,
+        ...options?.goal ? { goal: options.goal } : {},
+        ...this.logger ? { logger: this.logger } : {},
+        transport: clientTransport,
+        onTurnResult,
+        onEvent
+      });
+    } else {
+      if (!this.connection) throw new Error("Not connected");
+      const mux = this.connection.createTransport(sessionId);
+      await server.connect(mux);
+      record.transport = mux;
+      record.mux = mux;
+      this.sessions.set(sessionId, record);
+      const started = this.connection.waitForSessionEvent(sessionId, "start");
+      this.connection.send({
+        type: "start_session",
+        sessionId,
+        sessionToken,
+        name,
+        tools: reflected.tools,
+        instructions,
+        ...options?.goal ? { goal: options.goal } : {}
+      });
+      await started;
+    }
+    return {
+      sessionId,
+      turn: (turnOptions) => this.turn(sessionId, turnOptions),
+      stop: () => this.stopSession(sessionId),
+      on: (listener) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      }
+    };
+  }
+  /** Subscribe to every session plus connection events. Returns unsubscribe. */
+  on(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  async turn(sessionId, options) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error(`Unknown session ${sessionId}`);
+    const timeoutMs = options?.timeoutMs ?? this.options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+    let outcome;
+    try {
+      outcome = await session.gate.runTurn({
+        timeoutMs,
+        ...options?.signal ? { signal: options.signal } : {}
+      });
+    } catch (error) {
+      if (error instanceof ConnectionLostError) throw error;
+      throw error;
+    }
+    if (!outcome.ok) {
+      if (outcome.connectionLost) {
+        throw new ConnectionLostError(outcome.error ?? "Connection to the platform was lost");
+      }
+      throw new TurnFailedError(outcome.error ?? "turn failed", outcome.attemptDetails ?? []);
+    }
+    return {
+      action: outcome.action ?? "unknown",
+      args: outcome.args ?? {},
+      result: outcome.result,
+      attempts: outcome.attempts ?? 1,
+      usage: outcome.usage ?? { promptTokens: 0, completionTokens: 0 }
+    };
+  }
+  emit(event) {
+    for (const listener of this.listeners) listener(event);
+    if (event.type === "disconnected" || event.type === "reconnected") return;
+    const session = this.sessions.get(event.sessionId);
+    if (!session) return;
+    for (const listener of session.listeners) listener(event);
+  }
+  failInflight(error) {
+    for (const session of this.sessions.values()) {
+      session.gate.failTurn(error);
+    }
+  }
+  handleEnvelope(envelope) {
+    switch (envelope.type) {
+      case "mcp": {
+        const session = this.sessions.get(envelope.sessionId);
+        session?.mux?.receive(envelope.message);
+        return;
+      }
+      case "turn_result": {
+        const session = this.sessions.get(envelope.sessionId);
+        session?.gate.completeTurn(envelope);
+        return;
+      }
+      case "session_event": {
+        if (envelope.event === "action") {
+          this.emit({
+            type: "action",
+            sessionId: envelope.sessionId,
+            action: envelope.action ?? "unknown",
+            args: envelope.args ?? {}
+          });
+          return;
+        }
+        if (envelope.event === "retry") {
+          this.emit({
+            type: "retry",
+            sessionId: envelope.sessionId,
+            action: envelope.action ?? "unknown",
+            args: envelope.args ?? {},
+            error: envelope.error ?? "action failed"
+          });
+          return;
+        }
+        this.emit({
+          type: "turnFailed",
+          sessionId: envelope.sessionId,
+          error: envelope.error ?? "turn failed",
+          ...envelope.action ? { action: envelope.action } : {},
+          ...envelope.args ? { args: envelope.args } : {}
+        });
+        return;
+      }
+      case "error":
+        log(this.logger, "error", envelope.message);
+        return;
+      case "session_started":
+      case "session_stopped":
+      case "session_resumed":
+      case "resume_err":
+      case "hello_ok":
+      case "hello_err":
+      case "hello":
+      case "start_session":
+      case "stop_session":
+      case "ping":
+      case "pong":
+      case "resume_session":
+        return;
+      default: {
+        assertNever(envelope);
+      }
+    }
+  }
+  async stopSession(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.sessions.delete(sessionId);
+    session.gate.reset();
+    if (this.inline) {
+      await this.inline.stopSession(sessionId);
+    } else if (this.connection) {
+      const stopped = this.connection.waitForSessionEvent(sessionId, "stop").catch(() => null);
+      try {
+        this.connection.send({ type: "stop_session", sessionId });
+      } catch {
+      }
+      await stopped;
+    }
+    try {
+      await session.server.close();
+    } catch {
+    }
+  }
+  /** Stop every session and close the platform connection. */
+  async close() {
+    if (this.closing) return;
+    this.closing = true;
+    const ids = [...this.sessions.keys()];
+    for (const id of ids) {
+      await this.stopSession(id);
+    }
+    if (this.inline?.close) await this.inline.close();
+    if (this.connection) {
+      await this.connection.close();
+      this.connection = null;
+    }
+    this.started = false;
+    this.closing = false;
+  }
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+};
+export {
+  AgentServer,
+  ConnectionLostError,
+  DEFAULT_AGENT_INSTRUCTIONS,
+  PROTOCOL_VERSION,
+  PlatformAuthError,
+  ProtocolVersionError,
+  SDK_VERSION,
+  TurnFailedError,
+  TurnTimeoutError
+};
+//# sourceMappingURL=index.js.map