@chipzen-ai/bot 0.3.0

package/dist/bin.js

@@ -0,0 +1,2545 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+import path5 from "path";
+
+// src/run_external.ts
+import path2 from "path";
+import { pathToFileURL } from "url";
+
+// src/bot.ts
+var Bot = class {
+  /** Called once when the `match_start` message arrives. */
+  onMatchStart(_matchInfo) {
+  }
+  /**
+   * Called at the start of every hand with the raw `round_start` message.
+   *
+   * Override if you need the Layer 1 envelope (`round_id`,
+   * `round_number`) or the full Layer 2 `state` payload. For most bots,
+   * `onHandStart` is the simpler hook.
+   */
+  onRoundStart(_message) {
+  }
+  /**
+   * Called when the flop, turn, or river is dealt. Useful for triggering
+   * postflop planning *between* your turns rather than inside `decide`.
+   */
+  onPhaseChange(_message) {
+  }
+  /**
+   * Called after every participant's action is broadcast — yours and
+   * every opponent's. Use for opponent modeling, timing analysis, or
+   * stack tracking.
+   *
+   * This hook runs *before* the next `turn_request` is dispatched, and
+   * runs serially. Slow work here eats into your decide budget — see
+   * the DEV-MANUAL §6 for the "queue drain" failure mode.
+   */
+  onTurnResult(_message) {
+  }
+  /** Called when a hand ends (`round_result` message). */
+  onRoundResult(_message) {
+  }
+  /** Called once when the match ends. */
+  onMatchEnd(_results) {
+  }
+  /**
+   * Called after each `turn_action` is sent, with the wall-clock time
+   * `decide()` took in milliseconds.
+   *
+   * Default is a no-op. Override to track decision latency — useful for
+   * spotting when your bot is drifting toward the platform's turn-timeout
+   * budget. See chipzen-ai/chipzen-sdk#46.
+   */
+  onDecisionLatency(_latencyMs) {
+  }
+};
+
+// src/config.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var CONFIG_FILENAME = "chipzen.toml";
+var SECTION_NAME = "external_api";
+var ChipzenConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChipzenConfigError";
+  }
+};
+function searchPaths() {
+  const paths = [
+    path.join(process.cwd(), CONFIG_FILENAME),
+    path.join(os.homedir(), ".chipzen", CONFIG_FILENAME)
+  ];
+  if (process.platform !== "win32") {
+    paths.push(path.join("/etc/chipzen", CONFIG_FILENAME));
+  }
+  return paths;
+}
+function discoverConfigPath(paths) {
+  const candidates = paths ?? searchPaths();
+  for (const candidate of candidates) {
+    try {
+      if (fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function parseExternalApiSection(raw, filePath) {
+  const lines = raw.split(/\r?\n/);
+  let inSection = false;
+  let sawSection = false;
+  const values = {};
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i] ?? "";
+    const line = stripComment(rawLine).trim();
+    if (line === "") continue;
+    if (line.startsWith("[")) {
+      if (line.startsWith("[[")) {
+        const inner = line.slice(2, line.indexOf("]]"));
+        if (inner.trim() === SECTION_NAME) {
+          throw new ChipzenConfigError(
+            `${filePath}: [${SECTION_NAME}] must be a table (key=value pairs), got an array-of-tables ([[${SECTION_NAME}]]).`
+          );
+        }
+        inSection = false;
+        continue;
+      }
+      const closeIdx = line.indexOf("]");
+      if (closeIdx < 0) {
+        throw new ChipzenConfigError(
+          `${filePath}: malformed section header on line ${i + 1}: ${JSON.stringify(rawLine)}.`
+        );
+      }
+      const name = line.slice(1, closeIdx).trim();
+      inSection = name === SECTION_NAME;
+      if (inSection) sawSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    const eq = line.indexOf("=");
+    if (eq < 0) {
+      throw new ChipzenConfigError(
+        `${filePath}: Failed to parse line ${i + 1} in [${SECTION_NAME}]: ${JSON.stringify(rawLine)} (expected key = "value").`
+      );
+    }
+    const key = line.slice(0, eq).trim();
+    const valueText = line.slice(eq + 1).trim();
+    if (key === "") {
+      throw new ChipzenConfigError(
+        `${filePath}: Failed to parse line ${i + 1} in [${SECTION_NAME}]: empty key.`
+      );
+    }
+    if (key === "token" || key === "url" || key === "bot_id") {
+      const parsed = parseQuotedString(valueText);
+      if (parsed === null) {
+        const display = key === "bot_id" ? "bot_id" : key;
+        throw new ChipzenConfigError(
+          `${filePath}: [${SECTION_NAME}].${display} must be a string, got ${JSON.stringify(valueText)}.`
+        );
+      }
+      values[key] = parsed;
+    }
+  }
+  if (!sawSection) {
+    throw new ChipzenConfigError(
+      `${filePath} has no [${SECTION_NAME}] section. Add one with at least:
+
+  [${SECTION_NAME}]
+  token = "cz_extbot_..."
+`
+    );
+  }
+  return {
+    token: values.token ?? null,
+    url: values.url ?? null,
+    botId: values.bot_id ?? null
+  };
+}
+function stripComment(line) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === "#" && !inSingle && !inDouble) return line.slice(0, i);
+  }
+  return line;
+}
+function parseQuotedString(text) {
+  if (text.length < 2) return null;
+  const quote = text[0];
+  if (quote !== '"' && quote !== "'") return null;
+  if (text[text.length - 1] !== quote) return null;
+  const inner = text.slice(1, -1);
+  if (quote === "'") {
+    if (inner.includes("'")) return null;
+    return inner;
+  }
+  let out = "";
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (ch === "\\") {
+      const next = inner[i + 1];
+      if (next === '"' || next === "\\") {
+        out += next;
+        i++;
+        continue;
+      }
+      if (next === "n") {
+        out += "\n";
+        i++;
+        continue;
+      }
+      if (next === "t") {
+        out += "	";
+        i++;
+        continue;
+      }
+      out += ch;
+      continue;
+    }
+    if (ch === '"') return null;
+    out += ch;
+  }
+  return out;
+}
+function loadChipzenConfig(paths) {
+  const filePath = discoverConfigPath(paths);
+  if (filePath === null) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    throw new ChipzenConfigError(`Failed to read ${filePath}: ${err.message}`);
+  }
+  const { token, url, botId } = parseExternalApiSection(raw, filePath);
+  return { path: filePath, token, url, botId };
+}
+function resolveToken(opts) {
+  if (opts.explicitToken !== void 0 && opts.explicitToken !== null) {
+    return opts.explicitToken;
+  }
+  if (opts.explicitTicket !== void 0 && opts.explicitTicket !== null) {
+    return null;
+  }
+  if (opts.config && opts.config.token !== null) {
+    return opts.config.token;
+  }
+  return null;
+}
+function resolveUrl(opts) {
+  if (opts.explicitUrl !== void 0 && opts.explicitUrl !== null) {
+    return opts.explicitUrl;
+  }
+  if (opts.config && opts.config.url !== null) {
+    return opts.config.url;
+  }
+  return null;
+}
+
+// src/retry.ts
+var RetryPolicy = class {
+  maxReconnectAttempts;
+  initialBackoffMs;
+  maxBackoffMs;
+  backoffMultiplier;
+  constructor(options = {}) {
+    const maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+    const initialBackoffMs = options.initialBackoffMs ?? 500;
+    const maxBackoffMs = options.maxBackoffMs ?? 3e4;
+    const backoffMultiplier = options.backoffMultiplier ?? 2;
+    if (maxReconnectAttempts < 0) {
+      throw new Error(`maxReconnectAttempts must be >= 0, got ${maxReconnectAttempts}`);
+    }
+    if (initialBackoffMs < 0) {
+      throw new Error(`initialBackoffMs must be >= 0, got ${initialBackoffMs}`);
+    }
+    if (maxBackoffMs < initialBackoffMs) {
+      throw new Error(
+        `maxBackoffMs must be >= initialBackoffMs (${maxBackoffMs} < ${initialBackoffMs})`
+      );
+    }
+    if (backoffMultiplier < 1) {
+      throw new Error(`backoffMultiplier must be >= 1.0, got ${backoffMultiplier}`);
+    }
+    this.maxReconnectAttempts = maxReconnectAttempts;
+    this.initialBackoffMs = initialBackoffMs;
+    this.maxBackoffMs = maxBackoffMs;
+    this.backoffMultiplier = backoffMultiplier;
+  }
+  /**
+   * Return the delay (in ms) to wait **before** the given attempt.
+   *
+   * @param attempt 1-indexed attempt number. `attempt=1` is the first
+   *   reconnect after a drop, `attempt=2` the second, etc.
+   * @returns The delay in milliseconds, capped at `maxBackoffMs`.
+   * @throws Error if `attempt < 1`.
+   */
+  backoffMs(attempt) {
+    if (attempt < 1) {
+      throw new Error(`attempt must be >= 1, got ${attempt}`);
+    }
+    const raw = this.initialBackoffMs * this.backoffMultiplier ** (attempt - 1);
+    return Math.floor(Math.min(raw, this.maxBackoffMs));
+  }
+};
+var DEFAULT_RETRY_POLICY = new RetryPolicy();
+
+// src/connect.ts
+var ENV_NAMES = ["prod", "staging", "local"];
+var ENV_VAR_NAME = "CHIPZEN_ENV";
+var ENV_URL_TEMPLATES = {
+  prod: "wss://chipzen.ai/ws/external/bot/{botId}",
+  staging: "wss://staging.chipzen.ai/ws/external/bot/{botId}",
+  local: "ws://localhost:8001/ws/external/bot/{botId}"
+};
+function isEnvName(value) {
+  return ENV_NAMES.includes(value);
+}
+function resolveEnvName(explicitEnv, envVarValue) {
+  if (explicitEnv !== void 0 && explicitEnv !== null) {
+    if (!isEnvName(explicitEnv)) {
+      throw new Error(`Unknown env ${JSON.stringify(explicitEnv)}. Valid values: ${ENV_NAMES.join(", ")}.`);
+    }
+    return explicitEnv;
+  }
+  if (envVarValue) {
+    if (!isEnvName(envVarValue)) {
+      throw new Error(
+        `${ENV_VAR_NAME}=${JSON.stringify(envVarValue)} is not a recognized environment. Valid values: ${ENV_NAMES.join(", ")}.`
+      );
+    }
+    return envVarValue;
+  }
+  return "prod";
+}
+function urlForEnv(env, botId) {
+  return ENV_URL_TEMPLATES[env].replace("{botId}", botId);
+}
+function connectToChipzen(botId, env, options = {}) {
+  if (!botId || typeof botId !== "string") {
+    throw new Error(
+      "connectToChipzen() requires a non-empty botId string. Pass the external-API bot UUID issued by the Chipzen platform, e.g. connectToChipzen('abc123', 'prod')."
+    );
+  }
+  const resolvedEnv = resolveEnvName(env, process.env[ENV_VAR_NAME]);
+  const envDerivedUrl = urlForEnv(resolvedEnv, botId);
+  const config = options.config !== void 0 ? options.config : loadChipzenConfig();
+  const configUrl = resolveUrl({ explicitUrl: null, config });
+  let finalUrl;
+  let envForReturn;
+  if (configUrl === null) {
+    finalUrl = envDerivedUrl;
+    envForReturn = resolvedEnv;
+  } else {
+    finalUrl = configUrl;
+    envForReturn = null;
+  }
+  const token = resolveToken({ explicitToken: null, config });
+  const retryPolicy = options.retryPolicy ?? DEFAULT_RETRY_POLICY;
+  return {
+    url: finalUrl,
+    token,
+    retryPolicy,
+    env: envForReturn,
+    config: config ?? null
+  };
+}
+
+// src/external.ts
+import WebSocket2 from "ws";
+
+// src/client.ts
+import WebSocket from "ws";
+
+// src/models.ts
+var VALID_RANKS = /* @__PURE__ */ new Set([
+  "2",
+  "3",
+  "4",
+  "5",
+  "6",
+  "7",
+  "8",
+  "9",
+  "T",
+  "J",
+  "Q",
+  "K",
+  "A"
+]);
+var VALID_SUITS = /* @__PURE__ */ new Set(["h", "d", "c", "s"]);
+function cardFromString(s) {
+  if (typeof s !== "string" || s.length !== 2) {
+    throw new Error(`Invalid card string: ${JSON.stringify(s)} (expected 2 chars)`);
+  }
+  const rank = s[0];
+  const suit = s[1];
+  if (!VALID_RANKS.has(rank)) {
+    throw new Error(`Invalid card rank: ${JSON.stringify(rank)} in ${JSON.stringify(s)}`);
+  }
+  if (!VALID_SUITS.has(suit)) {
+    throw new Error(`Invalid card suit: ${JSON.stringify(suit)} in ${JSON.stringify(s)}`);
+  }
+  return { rank, suit };
+}
+var Action = class _Action {
+  constructor(action, amount) {
+    this.action = action;
+    this.amount = amount;
+    if (action === "raise") {
+      if (amount === void 0 || !Number.isFinite(amount) || amount < 0) {
+        throw new Error(
+          `Action.raiseTo requires a non-negative finite amount; got ${amount}`
+        );
+      }
+    } else if (amount !== void 0) {
+      throw new Error(
+        `Only raise actions take an amount; ${action} got amount=${amount}`
+      );
+    }
+  }
+  action;
+  amount;
+  static fold() {
+    return new _Action("fold");
+  }
+  static check() {
+    return new _Action("check");
+  }
+  static call() {
+    return new _Action("call");
+  }
+  static raiseTo(amount) {
+    return new _Action("raise", amount);
+  }
+  static allIn() {
+    return new _Action("all_in");
+  }
+  /**
+   * Serialize to the two-layer `turn_action` payload shape the server expects.
+   *
+   * Returns `{action, params}` where `params` carries the raise amount
+   * for `raise` and is empty for everything else.
+   */
+  toWire() {
+    const params = {};
+    if (this.action === "raise" && this.amount !== void 0) {
+      params.amount = this.amount;
+    }
+    return { action: this.action, params };
+  }
+};
+function parseGameState(message) {
+  const state = message?.state ?? {};
+  const holeStrs = state["your_hole_cards"] ?? [];
+  const boardStrs = state["board"] ?? [];
+  const validActions = message?.valid_actions ?? state["valid_actions"] ?? [];
+  const actionHistoryRaw = state["action_history"] ?? [];
+  return {
+    handNumber: numberOrZero(state["hand_number"]),
+    phase: state["phase"] ?? "preflop",
+    holeCards: holeStrs.map(cardFromString),
+    board: boardStrs.map(cardFromString),
+    pot: numberOrZero(state["pot"]),
+    yourStack: numberOrZero(state["your_stack"]),
+    opponentStacks: (state["opponent_stacks"] ?? []).map(Number),
+    yourSeat: numberOrZero(state["your_seat"]),
+    dealerSeat: numberOrZero(state["dealer_seat"]),
+    toCall: numberOrZero(state["to_call"]),
+    minRaise: numberOrZero(state["min_raise"]),
+    maxRaise: numberOrZero(state["max_raise"]),
+    validActions,
+    actionHistory: actionHistoryRaw.map(parseHistoryEntry),
+    roundId: message?.round_id ?? "",
+    requestId: message?.request_id ?? ""
+  };
+}
+function parseHistoryEntry(raw) {
+  const entry = {
+    seat: numberOrZero(raw.seat),
+    action: raw.action ?? ""
+  };
+  if (typeof raw.amount === "number") entry.amount = raw.amount;
+  if (typeof raw.is_timeout === "boolean") entry.isTimeout = raw.is_timeout;
+  return entry;
+}
+function numberOrZero(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+// package.json
+var package_default = {
+  name: "@chipzen-ai/bot",
+  version: "0.3.0",
+  description: "Build, test, and deploy poker bots for the Chipzen AI competition platform",
+  license: "Apache-2.0",
+  author: {
+    name: "Chipzen, Inc.",
+    email: "support@chipzen.ai"
+  },
+  homepage: "https://chipzen.ai",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/chipzen-ai/chipzen-sdk.git",
+    directory: "packages/javascript"
+  },
+  bugs: {
+    url: "https://github.com/chipzen-ai/chipzen-sdk/issues"
+  },
+  keywords: [
+    "poker",
+    "bot",
+    "ai",
+    "competition",
+    "chipzen",
+    "sdk",
+    "websocket"
+  ],
+  type: "module",
+  main: "./dist/index.cjs",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      require: "./dist/index.cjs"
+    }
+  },
+  bin: {
+    "chipzen-sdk": "./dist/bin.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  publishConfig: {
+    access: "public",
+    provenance: true
+  },
+  engines: {
+    node: ">=20"
+  },
+  dependencies: {
+    ws: "^8.18.0"
+  },
+  devDependencies: {
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.5.12",
+    tsup: "^8.3.0",
+    typescript: "^5.6.0",
+    vitest: "^2.1.0"
+  },
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit",
+    lint: "tsc --noEmit",
+    prepack: "pnpm build"
+  }
+};
+
+// src/version.ts
+var VERSION = package_default.version;
+
+// src/client.ts
+var BotDecisionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BotDecisionError";
+  }
+};
+var SUPPORTED_PROTOCOL_VERSIONS = ["1.0"];
+function _decide(bot, state, validActions, safeMode) {
+  const start = Date.now();
+  let action;
+  try {
+    action = bot.decide(state);
+    if (!(action instanceof Action)) {
+      if (!safeMode) {
+        throw new BotDecisionError(
+          `bot.decide() returned a non-Action value (${typeof action})`
+        );
+      }
+      action = _safeFallbackAction(validActions);
+    }
+  } catch (err) {
+    if (err instanceof BotDecisionError) throw err;
+    if (!safeMode) {
+      throw new BotDecisionError(err instanceof Error ? err.message : String(err));
+    }
+    action = _safeFallbackAction(validActions);
+  }
+  return { action, latencyMs: Date.now() - start };
+}
+async function _runSession(ws, bot, ctx, readerOverride) {
+  const reader = readerOverride ?? new _NodeWebSocketReader(ws);
+  const safeMode = ctx.safeMode ?? true;
+  const auth = {
+    type: "authenticate",
+    match_id: ctx.matchId,
+    client_name: ctx.clientName,
+    client_version: ctx.clientVersion
+  };
+  if (ctx.token) auth.token = ctx.token;
+  if (ctx.ticket) auth.ticket = ctx.ticket;
+  await sendJson(ws, auth);
+  const helloRaw = await reader.next();
+  if (!helloRaw) {
+    throw new Error("connection closed before server hello");
+  }
+  const hello = parseJson(helloRaw);
+  if (hello.type !== "hello") {
+    throw new Error(`expected server hello, got ${hello.type ?? "<no type>"}`);
+  }
+  await sendJson(ws, {
+    type: "hello",
+    match_id: ctx.matchId,
+    supported_versions: [...SUPPORTED_PROTOCOL_VERSIONS]
+  });
+  let lastSeq = 0;
+  for (; ; ) {
+    const raw = await reader.next();
+    if (raw === null) {
+      return null;
+    }
+    let msg;
+    try {
+      msg = parseJson(raw);
+    } catch {
+      continue;
+    }
+    if (typeof msg.seq === "number" && msg.seq <= lastSeq) {
+      continue;
+    }
+    if (typeof msg.seq === "number") lastSeq = msg.seq;
+    const type = msg.type;
+    switch (type) {
+      case "ping":
+        await sendJson(ws, { type: "pong", match_id: ctx.matchId });
+        break;
+      case "match_start":
+        bot.onMatchStart(msg);
+        break;
+      case "round_start":
+        bot.onRoundStart(msg);
+        break;
+      case "phase_change":
+        bot.onPhaseChange(msg);
+        break;
+      case "turn_result":
+        bot.onTurnResult(msg);
+        break;
+      case "round_result":
+        bot.onRoundResult(msg);
+        break;
+      case "turn_request": {
+        const requestId = msg.request_id ?? "";
+        const state = parseGameState(msg);
+        const { action, latencyMs } = _decide(
+          bot,
+          state,
+          msg.valid_actions,
+          safeMode
+        );
+        await sendJson(ws, {
+          type: "turn_action",
+          match_id: ctx.matchId,
+          request_id: requestId,
+          ...action.toWire()
+        });
+        bot.onDecisionLatency(latencyMs);
+        break;
+      }
+      case "action_rejected": {
+        const requestId = msg.request_id ?? "";
+        const validActions = msg.valid_actions ?? ["fold"];
+        const fallback = _safeFallbackAction(validActions);
+        await sendJson(ws, {
+          type: "turn_action",
+          match_id: ctx.matchId,
+          request_id: requestId,
+          ...fallback.toWire()
+        });
+        break;
+      }
+      case "reconnected": {
+        const pending = msg.pending_request;
+        if (pending && pending.type === "turn_request") {
+          const requestId = pending.request_id ?? "";
+          const { action, latencyMs } = _decide(
+            bot,
+            parseGameState(pending),
+            pending.valid_actions,
+            safeMode
+          );
+          await sendJson(ws, {
+            type: "turn_action",
+            match_id: ctx.matchId,
+            request_id: requestId,
+            ...action.toWire()
+          });
+          bot.onDecisionLatency(latencyMs);
+        }
+        break;
+      }
+      case "match_end":
+        bot.onMatchEnd(msg.results ?? msg);
+        return msg;
+      // clean exit — hand the match_end payload to the caller
+      case "error":
+        break;
+      default:
+        break;
+    }
+  }
+}
+var _NodeWebSocketReader = class {
+  queue = [];
+  waiters = [];
+  closed = false;
+  constructor(ws) {
+    ws.on("message", (data) => {
+      const msg = data.toString();
+      const w = this.waiters.shift();
+      if (w) w(msg);
+      else this.queue.push(msg);
+    });
+    ws.on("close", () => this._close());
+    ws.on("error", () => this._close());
+  }
+  async next() {
+    const queued = this.queue.shift();
+    if (queued !== void 0) return queued;
+    if (this.closed) return null;
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+  _close() {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length) {
+      const w = this.waiters.shift();
+      if (w) w(null);
+    }
+  }
+};
+function _safeFallbackAction(validActions) {
+  const valid = new Set(validActions ?? []);
+  if (valid.has("check")) return Action.check();
+  return Action.fold();
+}
+async function sendJson(ws, msg) {
+  const payload = JSON.stringify(msg);
+  const result = ws.send(payload);
+  if (result && typeof result.then === "function") {
+    await result;
+  }
+}
+function parseJson(raw) {
+  return JSON.parse(raw);
+}
+
+// src/external.ts
+var BOT_TOKEN_SUBPROTOCOL = "chipzen-bot-token";
+var LOBBY_RECV_TIMEOUT_MS = 2e3;
+var MATCH_DRAIN_GRACE_MS = 5e3;
+function botTokenSubprotocols(token) {
+  return [BOT_TOKEN_SUBPROTOCOL, token];
+}
+function normaliseBase(url) {
+  try {
+    const u = new URL(url);
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    const host = url.replace(/\/+$/, "");
+    return `wss://${host}`;
+  }
+}
+function resolveGatewayUrl(lobbyUrl, gatewayWsPath) {
+  if (gatewayWsPath.startsWith("ws://") || gatewayWsPath.startsWith("wss://")) {
+    const lobby = new URL(normaliseBase(lobbyUrl));
+    const gateway = new URL(gatewayWsPath);
+    const downgrade = lobby.protocol === "wss:" && gateway.protocol !== "wss:";
+    if (gateway.host !== lobby.host || downgrade) {
+      throw new Error(
+        `refusing gateway URL ${gatewayWsPath}: cross-origin or insecure relative to lobby ${lobby.protocol}//${lobby.host} (the bot token must not be sent to a different host or in cleartext)`
+      );
+    }
+    return gatewayWsPath;
+  }
+  return `${normaliseBase(lobbyUrl)}${gatewayWsPath}`;
+}
+function loads(raw) {
+  try {
+    const msg = JSON.parse(raw);
+    return msg !== null && typeof msg === "object" && !Array.isArray(msg) ? msg : {};
+  } catch {
+    return {};
+  }
+}
+function asFactory(bot) {
+  if (bot && typeof bot.decide === "function") {
+    const instance = bot;
+    return () => instance;
+  }
+  if (typeof bot === "function") {
+    return bot;
+  }
+  throw new TypeError(
+    `runExternalBot(bot=...) must be a Bot instance or a callable returning one, got ${typeof bot}.`
+  );
+}
+var MAX_WS_PAYLOAD = 2 ** 24;
+var defaultTransport = async (url, options) => {
+  const ws = new WebSocket2(url, options.subprotocols ?? [], {
+    headers: { "User-Agent": options.userAgent },
+    maxPayload: MAX_WS_PAYLOAD
+  });
+  await new Promise((resolve, reject) => {
+    const onOpen = () => {
+      ws.removeListener("error", onError);
+      resolve();
+    };
+    const onError = (err) => {
+      ws.removeListener("open", onOpen);
+      reject(err);
+    };
+    ws.once("open", onOpen);
+    ws.once("error", onError);
+  });
+  return {
+    send: (data) => ws.send(data),
+    reader: new _NodeWebSocketReader(ws),
+    close: () => {
+      if (ws.readyState !== WebSocket2.CLOSED && ws.readyState !== WebSocket2.CLOSING) {
+        ws.close();
+      }
+    }
+  };
+};
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function recvWithTimeout(reader, timeoutMs) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(void 0), timeoutMs);
+  });
+  try {
+    return await Promise.race([reader.next(), timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function playOneMatch(params) {
+  const { gatewayUrl, matchId, token, bot, policy, transport } = params;
+  let attempt = 0;
+  for (; ; ) {
+    let conn = null;
+    let reason;
+    try {
+      conn = await transport(gatewayUrl, {
+        userAgent: params.userAgent,
+        subprotocols: botTokenSubprotocols(token)
+      });
+      const end = await _runSession(
+        conn,
+        bot,
+        {
+          matchId,
+          token: null,
+          ticket: null,
+          clientName: params.clientName,
+          clientVersion: params.clientVersion,
+          safeMode: params.safeMode
+        },
+        conn.reader
+      );
+      if (end !== null) {
+        return end;
+      }
+      reason = "closed without match_end";
+    } catch (err) {
+      if (err instanceof BotDecisionError) {
+        throw err;
+      }
+      reason = err instanceof Error ? err.message || err.constructor.name : String(err);
+    } finally {
+      if (conn) conn.close();
+    }
+    attempt += 1;
+    if (attempt > policy.maxReconnectAttempts) {
+      return null;
+    }
+    await sleep(policy.backoffMs(attempt));
+  }
+}
+async function runLobbyOnce(p) {
+  const onMatchSettled = (end, err) => {
+    if (err !== void 0 && err !== null) {
+      if (err instanceof BotDecisionError) {
+        p.fatal.push(err);
+        p.stop.value = true;
+        return;
+      }
+      p.results.push({ matchId: null, end: null });
+    } else {
+      p.completed.value += 1;
+      p.results.push({
+        matchId: end?.match_id ?? null,
+        end: end ?? null
+      });
+    }
+    if (p.maxMatches !== null && p.completed.value >= p.maxMatches) {
+      p.stop.value = true;
+    }
+  };
+  const conn = await p.transport(p.lobbyUrl, { userAgent: p.userAgent });
+  try {
+    await conn.send(JSON.stringify({ type: "authenticate", token: p.token }));
+    while (!p.stop.value) {
+      const raw = await recvWithTimeout(conn.reader, LOBBY_RECV_TIMEOUT_MS);
+      if (raw === void 0) {
+        continue;
+      }
+      if (raw === null) {
+        return "closed";
+      }
+      const msg = loads(raw);
+      const mtype = msg.type;
+      if (mtype === "ping") {
+        await conn.send(JSON.stringify({ type: "pong" }));
+      } else if (mtype === "hello") {
+      } else if (mtype === "matched") {
+        let gatewayUrl;
+        try {
+          gatewayUrl = resolveGatewayUrl(p.lobbyUrl, msg.gateway_ws_url);
+        } catch {
+          continue;
+        }
+        const matchId = msg.match_id;
+        const task = { promise: Promise.resolve(), done: false };
+        task.promise = playOneMatch({
+          gatewayUrl,
+          matchId,
+          token: p.token,
+          bot: p.factory(),
+          policy: p.policy,
+          clientName: p.clientName,
+          clientVersion: p.clientVersion,
+          safeMode: p.safeMode,
+          userAgent: p.userAgent,
+          transport: p.transport
+        }).then(
+          (end) => {
+            task.done = true;
+            onMatchSettled(end, void 0);
+          },
+          (err) => {
+            task.done = true;
+            onMatchSettled(void 0, err);
+          }
+        );
+        p.matchTasks.push(task);
+      } else if (mtype === "evict") {
+        return "evicted";
+      }
+    }
+    return "stopped";
+  } finally {
+    conn.close();
+  }
+}
+async function drainMatches(matchTasks, grace = MATCH_DRAIN_GRACE_MS) {
+  if (matchTasks.length === 0) return;
+  const all = Promise.allSettled(matchTasks.map((t) => t.promise));
+  let timer;
+  const graceTimeout = new Promise((resolve) => {
+    timer = setTimeout(resolve, grace);
+  });
+  await Promise.race([all.then(() => void 0), graceTimeout]);
+  if (timer) clearTimeout(timer);
+  await all;
+}
+async function runExternalBot(bot, options = {}) {
+  const config = options.config !== void 0 ? options.config : loadChipzenConfig();
+  const transport = options.transport ?? defaultTransport;
+  const clientName = options.clientName ?? "chipzen-sdk-js";
+  const clientVersion = options.clientVersion ?? VERSION;
+  const safeMode = options.safeMode ?? true;
+  const maxMatches = options.maxMatches ?? null;
+  let lobbyUrl;
+  let policy;
+  let resolvedToken;
+  if (options.url !== void 0 && options.url !== null) {
+    lobbyUrl = options.url;
+    policy = options.retryPolicy ?? DEFAULT_RETRY_POLICY;
+    resolvedToken = resolveToken({ explicitToken: options.token, config });
+  } else {
+    const resolvedBotId = options.botId ?? (config ? config.botId : null);
+    if (!resolvedBotId) {
+      throw new Error(
+        "runExternalBot() needs a lobby URL. Pass url=..., or botId=... (or set [external_api].bot_id / url in chipzen.toml)."
+      );
+    }
+    const conn = connectToChipzen(resolvedBotId, options.env, {
+      retryPolicy: options.retryPolicy,
+      config
+    });
+    lobbyUrl = conn.url;
+    policy = conn.retryPolicy;
+    resolvedToken = options.token !== void 0 && options.token !== null ? options.token : conn.token;
+  }
+  if (!resolvedToken) {
+    throw new Error(
+      "runExternalBot() requires an external-API token (cz_extbot_...). Pass token=..., or set [external_api].token in chipzen.toml."
+    );
+  }
+  const userAgent = options.userAgent ?? `chipzen-sdk-js/${clientVersion}`;
+  const factory = asFactory(bot);
+  const results = [];
+  const stop = { value: false };
+  const fatal = [];
+  const matchTasks = [];
+  const completed = { value: 0 };
+  let consecutiveFailures = 0;
+  let everConnected = false;
+  let giveupExc = null;
+  const dropDoneTasks = () => {
+    for (let i = matchTasks.length - 1; i >= 0; i--) {
+      if (matchTasks[i].done) matchTasks.splice(i, 1);
+    }
+  };
+  while (!stop.value) {
+    let status = null;
+    try {
+      status = await runLobbyOnce({
+        lobbyUrl,
+        token: resolvedToken,
+        factory,
+        results,
+        matchTasks,
+        completed,
+        policy,
+        clientName,
+        clientVersion,
+        safeMode,
+        userAgent,
+        maxMatches,
+        stop,
+        fatal,
+        transport
+      });
+      everConnected = true;
+    } catch (err) {
+      consecutiveFailures += 1;
+      if (consecutiveFailures > policy.maxReconnectAttempts) {
+        if (!everConnected) {
+          giveupExc = err instanceof Error ? err : new Error(String(err));
+        }
+        break;
+      }
+      await sleep(policy.backoffMs(consecutiveFailures));
+      dropDoneTasks();
+      continue;
+    }
+    consecutiveFailures = 0;
+    if (status === "stopped" || status === "evicted" || fatal.length > 0) {
+      break;
+    }
+    consecutiveFailures += 1;
+    if (consecutiveFailures > policy.maxReconnectAttempts) {
+      break;
+    }
+    await sleep(policy.backoffMs(consecutiveFailures));
+    dropDoneTasks();
+  }
+  await drainMatches(matchTasks);
+  if (fatal.length > 0) {
+    throw fatal[0];
+  }
+  if (giveupExc !== null) {
+    throw giveupExc;
+  }
+  return results;
+}
+
+// src/run_external.ts
+function parseRunExternalArgs(args) {
+  const out = {
+    botFile: "",
+    env: null,
+    token: null,
+    botId: null,
+    botClass: null,
+    maxMatches: null,
+    safeMode: true
+  };
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const takeValue = (name) => {
+      const value = args[++i];
+      if (value === void 0) throw new Error(`${name} requires a value`);
+      return value;
+    };
+    switch (arg) {
+      case "--env": {
+        const value = takeValue("--env");
+        if (!ENV_NAMES.includes(value)) {
+          throw new Error(
+            `--env must be one of ${ENV_NAMES.join(", ")} (got ${JSON.stringify(value)})`
+          );
+        }
+        out.env = value;
+        break;
+      }
+      case "--token":
+        out.token = takeValue("--token");
+        break;
+      case "--bot-id":
+        out.botId = takeValue("--bot-id");
+        break;
+      case "--bot-class":
+        out.botClass = takeValue("--bot-class");
+        break;
+      case "--max-matches": {
+        const value = takeValue("--max-matches");
+        const n = Number.parseInt(value, 10);
+        if (!Number.isFinite(n)) {
+          throw new Error(`--max-matches must be an integer (got ${JSON.stringify(value)})`);
+        }
+        out.maxMatches = n;
+        break;
+      }
+      case "--no-safe-mode":
+        out.safeMode = false;
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        positionals.push(arg);
+        break;
+    }
+  }
+  const botFile = positionals[0];
+  if (!botFile) {
+    throw new Error("run-external requires a <bot-file> positional argument");
+  }
+  out.botFile = botFile;
+  return out;
+}
+async function loadBotModule(botFile) {
+  const abs = path2.resolve(botFile);
+  try {
+    const url = `${pathToFileURL(abs).href}?t=${Date.now()}`;
+    return await import(url);
+  } catch (err) {
+    throw new Error(`Failed to load ${botFile}: ${err.message}`);
+  }
+}
+function findBotSubclasses(module) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of Object.values(module)) {
+    if (typeof value !== "function") continue;
+    if (value === Bot) continue;
+    if (seen.has(value)) continue;
+    if (value.prototype instanceof Bot) {
+      seen.add(value);
+      found.push(value);
+    }
+  }
+  return found;
+}
+function selectBotClass(candidates, botClassName, botFile) {
+  if (botClassName !== null) {
+    const matches = candidates.filter((c) => c.name === botClassName);
+    if (matches.length === 0) {
+      const available = candidates.map((c) => c.name).join(", ") || "<none>";
+      throw new Error(
+        `No Bot subclass named ${JSON.stringify(botClassName)} in ${botFile}. Available subclasses: ${available}.`
+      );
+    }
+    return matches[0];
+  }
+  if (candidates.length === 0) {
+    throw new Error(
+      `No Bot subclass found in ${botFile}. Export a class that extends Bot (e.g. export class MyBot extends Bot { ... }).`
+    );
+  }
+  if (candidates.length > 1) {
+    const names = candidates.map((c) => c.name).join(", ");
+    throw new Error(
+      `Multiple Bot subclasses found in ${botFile}: ${names}. Pick one with --bot-class <name>.`
+    );
+  }
+  return candidates[0];
+}
+function resolveConnection(opts) {
+  const policy = opts.retryPolicy ?? DEFAULT_RETRY_POLICY;
+  const configUrl = opts.config ? opts.config.url : null;
+  if (configUrl !== null) {
+    const token2 = opts.token !== null ? opts.token : opts.config ? opts.config.token : null;
+    return { url: configUrl, token: token2, retryPolicy: policy, config: opts.config };
+  }
+  const botId = opts.botId ?? (opts.config ? opts.config.botId : null);
+  if (!botId) {
+    throw new Error(
+      "No lobby URL is configured. Either:\n  - Pass --bot-id <id> on the command line, or\n  - Set [external_api].bot_id in chipzen.toml, or\n  - Set [external_api].url in chipzen.toml for a verbatim URL."
+    );
+  }
+  const conn = connectToChipzen(botId, opts.env, {
+    retryPolicy: policy,
+    config: opts.config
+  });
+  const token = opts.token !== null ? opts.token : conn.token;
+  return { url: conn.url, token, retryPolicy: conn.retryPolicy, config: conn.config };
+}
+function printRunExternalHelp() {
+  console.log("Usage: chipzen-sdk run-external <bot-file> [options]");
+  console.log("");
+  console.log("Run a Chipzen external-API bot from a JavaScript file. Loads config");
+  console.log("from chipzen.toml, resolves the env-aware lobby URL, and plays via");
+  console.log("the SDK's runExternalBot() entry point.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --env <prod|staging|local>  Target environment. Defaults to $CHIPZEN_ENV, else prod.");
+  console.log("  --token <cz_extbot_...>      External-API token. Overrides [external_api].token.");
+  console.log("  --bot-id <uuid>              External-API bot UUID. Overrides [external_api].bot_id.");
+  console.log("  --bot-class <name>           Bot subclass to run when the file exports more than one.");
+  console.log("  --max-matches <int>          Stop after this many matches. Default: run until lobby closes.");
+  console.log("  --no-safe-mode               Let a decide() error crash the process (exit non-zero).");
+  console.log("");
+  console.log("Examples:");
+  console.log("  chipzen-sdk run-external my-bot.js");
+  console.log("  chipzen-sdk run-external my-bot.js --env staging");
+  console.log("  CHIPZEN_ENV=staging chipzen-sdk run-external my-bot.js");
+  console.log("  chipzen-sdk run-external my-bot.js --token cz_extbot_xyz --bot-id abc123");
+  console.log("  chipzen-sdk run-external my-bot.js --bot-class TightAggressive");
+}
+async function runExternalCli(args) {
+  if (args[0] === "--help" || args[0] === "-h") {
+    printRunExternalHelp();
+    return;
+  }
+  let parsed;
+  try {
+    parsed = parseRunExternalArgs(args);
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(2);
+  }
+  let config;
+  try {
+    config = loadChipzenConfig();
+  } catch (err) {
+    if (err instanceof ChipzenConfigError) {
+      console.error(`error: invalid chipzen.toml: ${err.message}`);
+      process.exit(2);
+    }
+    throw err;
+  }
+  let resolved;
+  try {
+    resolved = resolveConnection({
+      config,
+      env: parsed.env,
+      token: parsed.token,
+      botId: parsed.botId
+    });
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(2);
+  }
+  let module;
+  try {
+    module = await loadBotModule(parsed.botFile);
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(2);
+  }
+  let BotClass;
+  try {
+    BotClass = selectBotClass(findBotSubclasses(module), parsed.botClass, parsed.botFile);
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(2);
+  }
+  let botInstance;
+  try {
+    botInstance = new BotClass();
+  } catch (err) {
+    console.error(`error: failed to instantiate ${BotClass.name}: ${err.message}`);
+    process.exit(2);
+  }
+  console.error(`Connecting ${BotClass.name} -> ${resolved.url}`);
+  try {
+    await runExternalBot(botInstance, {
+      url: resolved.url,
+      token: resolved.token,
+      retryPolicy: resolved.retryPolicy,
+      config: resolved.config,
+      safeMode: parsed.safeMode,
+      maxMatches: parsed.maxMatches
+    });
+  } catch (err) {
+    console.error(`error: bot run failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/scaffold.ts
+import { promises as fs2 } from "fs";
+import path3 from "path";
+async function scaffoldBot(name, options = {}) {
+  if (!isValidProjectName(name)) {
+    throw new Error(
+      `Invalid project name: ${JSON.stringify(name)}. Use ASCII letters, digits, underscores, and dashes only.`
+    );
+  }
+  const parent = options.parentDir ?? process.cwd();
+  const projectDir = path3.join(parent, name);
+  try {
+    await fs2.access(projectDir);
+    throw new Error(`Directory already exists: ${projectDir}`);
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+  await fs2.mkdir(projectDir, { recursive: true });
+  await fs2.writeFile(path3.join(projectDir, "bot.js"), BOT_TEMPLATE, "utf-8");
+  await fs2.writeFile(path3.join(projectDir, "package.json"), packageJsonTemplate(name), "utf-8");
+  await fs2.writeFile(path3.join(projectDir, "Dockerfile"), DOCKERFILE_TEMPLATE, "utf-8");
+  await fs2.writeFile(path3.join(projectDir, ".dockerignore"), DOCKERIGNORE, "utf-8");
+  await fs2.writeFile(path3.join(projectDir, ".gitignore"), GITIGNORE, "utf-8");
+  await fs2.writeFile(path3.join(projectDir, "README.md"), readmeTemplate(name), "utf-8");
+  return projectDir;
+}
+function isValidProjectName(name) {
+  return /^[A-Za-z0-9_-]+$/.test(name);
+}
+var BOT_TEMPLATE = `// Chipzen starter bot \u2014 replace decide() with your strategy.
+// The SDK handles WebSocket, handshake, ping/pong, retries, and reconnect.
+
+import { Bot, Action, runBot } from "@chipzen-ai/bot";
+
+class MyBot extends Bot {
+  decide(state) {
+    // Return one of: Action.fold(), Action.check(), Action.call(),
+    // Action.raiseTo(amount), Action.allIn(). The chosen action's
+    // wire-form must be in state.validActions; raises must satisfy
+    // state.minRaise <= amount <= state.maxRaise.
+    if (state.validActions.includes("check")) return Action.check();
+    return Action.fold();
+  }
+}
+
+export async function main() {
+  const url = process.env.CHIPZEN_WS_URL ?? process.argv[2];
+  if (!url) {
+    console.error("error: CHIPZEN_WS_URL not set and no URL passed on the command line");
+    process.exit(1);
+  }
+  await runBot(url, new MyBot(), {
+    token: process.env.CHIPZEN_TOKEN ?? null,
+    ticket: process.env.CHIPZEN_TICKET ?? null,
+  });
+}
+
+// Run main() when this file is the entry point \u2014 covers both
+// \`node bot.js\` (Node sets import.meta.url to a file:// URL matching
+// argv[1]) and \`bun build --compile\` binaries (Bun sets
+// import.meta.main on the entry module). Importing from a test file
+// makes both checks false so MyBot can be exercised in isolation.
+if (import.meta.main || import.meta.url === \`file://\${process.argv[1]}\`) {
+  await main();
+}
+
+export { MyBot };
+`;
+function packageJsonTemplate(name) {
+  return JSON.stringify(
+    {
+      name,
+      version: "0.1.0",
+      private: true,
+      type: "module",
+      main: "bot.js",
+      scripts: {
+        start: "node bot.js"
+      },
+      dependencies: {
+        "@chipzen-ai/bot": "^0.2.0"
+      },
+      engines: {
+        node: ">=20"
+      }
+    },
+    null,
+    2
+  ) + "\n";
+}
+var DOCKERFILE_TEMPLATE = `# syntax=docker/dockerfile:1.7
+#
+# IP-protected Chipzen JavaScript bot image.
+#
+# Multi-stage build that bundles bot.js + the SDK into a single
+# statically-linked binary via \`bun build --compile\` in the builder
+# stage, then ships only that binary in the runtime stage. The runtime
+# image contains no readable .js source for your strategy code.
+#
+# See ../../IP-PROTECTION.md for what this protects (and what it doesn't).
+#
+# Build:   docker build -t my-bot:test .
+# Export:  docker save my-bot:test | gzip > my-bot.tar.gz
+#
+# Build context for this directory should be small (bot.js +
+# package.json + this file). The .dockerignore alongside this file
+# keeps node_modules, caches, and lockfile metadata out.
+
+# -----------------------------------------------------------------------------
+# Stage 1: Bun bundle + compile. The .js source lives only in this stage and
+# is discarded before the runtime stage starts.
+# -----------------------------------------------------------------------------
+# Base pinned by tag \u2014 Dependabot can rotate to digest pinning later. Tag:
+# oven/bun:1-debian (glibc-based; the runtime stage below also uses glibc
+# so the compiled binary's dynamic linker can find what it needs).
+FROM oven/bun:1-debian AS builder
+
+WORKDIR /build
+
+# Bring in the bot source + dependency manifest. Only these are copied \u2014
+# keep the build context narrow so the .dockerignore is the only allowlist.
+COPY package.json bot.js ./
+
+# Resolve @chipzen-ai/bot + ws so \`bun build\` can bundle them. We don't
+# need a lockfile committed; the registry pin in package.json is enough
+# for a fresh install at build time.
+RUN bun install --production
+
+# Compile bot.js -> /build/bot. \`--compile\` emits a single executable
+# that bundles the JS, all deps, and the Bun runtime statically.
+# \`--minify\` shrinks output; \`--sourcemap=none\` excludes maps so the
+# strategy isn't trivially readable from inside the binary.
+RUN bun build --compile --minify --sourcemap=none --target=bun-linux-x64 \\
+        bot.js --outfile=/build/bot \\
+    && rm bot.js \\
+    && rm -rf node_modules
+
+# -----------------------------------------------------------------------------
+# Stage 2: Runtime. Only the compiled binary + ENTRYPOINT.
+# No .js source for the bot's strategy is present.
+# -----------------------------------------------------------------------------
+# Base pinned by tag \u2014 Dependabot can rotate to digest pinning later. Tag:
+# debian:12-slim (matches the glibc the Bun --compile output expects).
+FROM debian:12-slim
+
+# CA certs are needed for outbound TLS (the platform's WebSocket
+# endpoint is wss://). dumb-init reaps any subprocesses cleanly on
+# container exit; tiny but useful.
+RUN apt-get update \\
+    && apt-get install -y --no-install-recommends ca-certificates dumb-init \\
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /bot
+
+# Copy ONLY the compiled binary from the builder stage.
+COPY --from=builder /build/bot /bot/bot
+RUN chmod +x /bot/bot
+
+# Run as non-root (defense in depth \u2014 the platform also applies seccomp
+# and cap-drop on top of this).
+RUN groupadd --system --gid 10001 bot \\
+    && useradd --system --uid 10001 --gid bot --home-dir /bot --shell /usr/sbin/nologin bot \\
+    && chown -R bot:bot /bot
+USER 10001
+
+ENTRYPOINT ["dumb-init", "/bot/bot"]
+`;
+var DOCKERIGNORE = `node_modules/
+.git/
+.gitignore
+.env
+.env.*
+*.md
+README*
+LICENSE*
+*.log
+coverage/
+.DS_Store
+`;
+var GITIGNORE = `node_modules/
+*.log
+.DS_Store
+.env
+.env.*
+coverage/
+dist/
+`;
+function readmeTemplate(name) {
+  return `# ${name}
+
+A poker bot for the [Chipzen](https://chipzen.ai) platform.
+
+## Quick start
+
+\`\`\`bash
+npm install
+\`\`\`
+
+Edit \`bot.js\` to implement your strategy in the \`decide()\` method.
+
+Validate before uploading:
+
+\`\`\`bash
+chipzen-sdk validate .
+\`\`\`
+
+Build and export the upload tarball:
+
+\`\`\`bash
+docker build -t ${name}:v1 .
+docker save ${name}:v1 | gzip > ${name}.tar.gz
+\`\`\`
+
+Then upload via the Chipzen platform UI.
+`;
+}
+
+// src/validate.ts
+import { execSync } from "child_process";
+import { promises as fs3 } from "fs";
+import path4 from "path";
+
+// src/conformance.ts
+var MATCH_ID = "m_conformance_test";
+var VALID_ACTION_KINDS = /* @__PURE__ */ new Set(["fold", "check", "call", "raise", "all_in"]);
+var _ScriptedReader = class {
+  constructor(messages) {
+    this.messages = messages;
+  }
+  messages;
+  index = 0;
+  async next() {
+    if (this.index >= this.messages.length) return null;
+    return this.messages[this.index++] ?? null;
+  }
+};
+var _CapturingSocket = class {
+  sent = [];
+  send(data) {
+    this.sent.push(data);
+  }
+  close() {
+  }
+};
+function serverHello() {
+  return {
+    type: "hello",
+    match_id: MATCH_ID,
+    seq: 1,
+    server_ts: "2026-04-13T14:30:05.123Z",
+    supported_versions: ["1.0"],
+    selected_version: "1.0",
+    game_type: "nlhe_6max",
+    capabilities: []
+  };
+}
+function matchStart() {
+  return {
+    type: "match_start",
+    match_id: MATCH_ID,
+    seq: 2,
+    server_ts: "2026-04-13T14:30:06.000Z",
+    seats: [
+      { seat: 0, participant_id: "p0", display_name: "You", is_self: true },
+      { seat: 1, participant_id: "p1", display_name: "Opp", is_self: false }
+    ],
+    game_config: {
+      variant: "nlhe",
+      starting_stack: 1e3,
+      small_blind: 5,
+      big_blind: 10,
+      ante: 0,
+      total_hands: 0
+    },
+    turn_timeout_ms: 5e3
+  };
+}
+function roundStart() {
+  return {
+    type: "round_start",
+    match_id: MATCH_ID,
+    seq: 3,
+    server_ts: "2026-04-13T14:30:07.000Z",
+    round_id: "r_1",
+    round_number: 1,
+    state: {
+      hand_number: 1,
+      dealer_seat: 0,
+      your_hole_cards: ["Ah", "Kd"],
+      stacks: [995, 990],
+      deck_commitment: ""
+    }
+  };
+}
+function turnRequest() {
+  return {
+    type: "turn_request",
+    match_id: MATCH_ID,
+    seq: 4,
+    server_ts: "2026-04-13T14:30:07.500Z",
+    seat: 0,
+    request_id: "req_1",
+    timeout_ms: 5e3,
+    valid_actions: ["fold", "call", "raise"],
+    state: {
+      hand_number: 1,
+      phase: "preflop",
+      board: [],
+      your_hole_cards: ["Ah", "Kd"],
+      pot: 15,
+      your_stack: 995,
+      opponent_stacks: [990],
+      to_call: 5,
+      min_raise: 20,
+      max_raise: 995,
+      action_history: []
+    }
+  };
+}
+function turnResult() {
+  return {
+    type: "turn_result",
+    match_id: MATCH_ID,
+    seq: 5,
+    server_ts: "2026-04-13T14:30:08.000Z",
+    is_timeout: false,
+    details: { seat: 0, action: "call", amount: 5 }
+  };
+}
+function roundResult() {
+  return {
+    type: "round_result",
+    match_id: MATCH_ID,
+    seq: 6,
+    server_ts: "2026-04-13T14:30:12.000Z",
+    round_id: "r_1",
+    round_number: 1,
+    result: {
+      hand_number: 1,
+      winner_seats: [0],
+      pot: 40,
+      payouts: [{ seat: 0, amount: 40 }],
+      showdown: [],
+      action_history: [],
+      stacks: [1020, 980],
+      deck_commitment: "",
+      deck_reveal: null
+    }
+  };
+}
+function matchEnd(seq = 7) {
+  return {
+    type: "match_end",
+    match_id: MATCH_ID,
+    seq,
+    server_ts: "2026-04-13T14:35:00.000Z",
+    reason: "complete",
+    results: [
+      { seat: 0, participant_id: "p0", rank: 1, score: 1020 },
+      { seat: 1, participant_id: "p1", rank: 2, score: 980 }
+    ]
+  };
+}
+function turnRequestN(seq, requestId) {
+  return { ...turnRequest(), seq, request_id: requestId };
+}
+function turnResultN(seq) {
+  return { ...turnResult(), seq };
+}
+function phaseChange(seq, phase, board) {
+  return {
+    type: "phase_change",
+    match_id: MATCH_ID,
+    seq,
+    server_ts: "2026-04-13T14:30:09.000Z",
+    state: { phase, board }
+  };
+}
+function roundResultN(seq) {
+  return { ...roundResult(), seq };
+}
+function actionRejected(seq, requestId = "req_1", remainingMs = 4e3) {
+  return {
+    type: "action_rejected",
+    match_id: MATCH_ID,
+    seq,
+    server_ts: "2026-04-13T14:30:08.000Z",
+    request_id: requestId,
+    reason: "invalid_action",
+    message: "action not in valid_actions",
+    remaining_ms: remainingMs,
+    valid_actions: ["check", "fold"]
+  };
+}
+function fullMatchScript() {
+  return [
+    serverHello(),
+    matchStart(),
+    roundStart(),
+    turnRequest(),
+    turnResult(),
+    roundResult(),
+    matchEnd()
+  ].map((m) => JSON.stringify(m));
+}
+function multiTurnScript() {
+  return [
+    serverHello(),
+    matchStart(),
+    roundStart(),
+    turnRequestN(4, "req_1"),
+    turnResultN(5),
+    phaseChange(6, "flop", ["2s", "7d", "Tc"]),
+    turnRequestN(7, "req_2"),
+    turnResultN(8),
+    phaseChange(9, "turn", ["2s", "7d", "Tc", "Kh"]),
+    turnRequestN(10, "req_3"),
+    turnResultN(11),
+    roundResultN(12),
+    matchEnd(13)
+  ].map((m) => JSON.stringify(m));
+}
+function actionRejectedScript() {
+  return [
+    serverHello(),
+    matchStart(),
+    roundStart(),
+    turnRequestN(4, "req_1"),
+    actionRejected(5, "req_1"),
+    turnResultN(6),
+    roundResultN(7),
+    matchEnd(8)
+  ].map((m) => JSON.stringify(m));
+}
+function retryStormScript() {
+  return [
+    serverHello(),
+    matchStart(),
+    roundStart(),
+    turnRequestN(4, "req_1"),
+    actionRejected(5, "req_1"),
+    actionRejected(6, "req_1"),
+    actionRejected(7, "req_1"),
+    turnResultN(8),
+    roundResultN(9),
+    matchEnd(10)
+  ].map((m) => JSON.stringify(m));
+}
+function classifyTurnAction(payload, expectedRequestId = "req_1") {
+  let msg;
+  try {
+    msg = JSON.parse(payload);
+  } catch (err) {
+    return { ok: false, message: `sent payload was not valid JSON: ${err.message}` };
+  }
+  if (msg.type !== "turn_action") {
+    return { ok: true, message: `non-action message (${JSON.stringify(msg.type)}) \u2014 ignored` };
+  }
+  if (msg.request_id !== expectedRequestId) {
+    return {
+      ok: false,
+      message: `turn_action request_id ${JSON.stringify(msg.request_id)} did not echo the server's ${JSON.stringify(expectedRequestId)} \u2014 the server uses request_id for correlation, idempotency, and action_rejected retries`
+    };
+  }
+  const params = msg.params ?? {};
+  const action = msg.action ?? params.action;
+  if (!action || !VALID_ACTION_KINDS.has(action)) {
+    return {
+      ok: false,
+      message: `turn_action action ${JSON.stringify(action)} is not in the legal set`
+    };
+  }
+  return { ok: true, message: `sent turn_action: action=${JSON.stringify(action)}` };
+}
+function extractTurnActions(sent) {
+  const out = [];
+  for (const payload of sent) {
+    try {
+      const parsed = JSON.parse(payload);
+      if (parsed.type === "turn_action") out.push(parsed);
+    } catch {
+    }
+  }
+  return out;
+}
+async function driveSession(bot, script, timeoutMs) {
+  const reader = new _ScriptedReader(script);
+  const socket = new _CapturingSocket();
+  try {
+    await withTimeout(
+      _runSession(
+        socket,
+        bot,
+        {
+          matchId: MATCH_ID,
+          token: "conformance",
+          ticket: null,
+          clientName: "chipzen-sdk-conformance",
+          clientVersion: "0.0.0"
+        },
+        reader
+      ),
+      timeoutMs
+    );
+    return { socket, error: null };
+  } catch (err) {
+    return { socket, error: err };
+  }
+}
+async function withTimeout(p, timeoutMs) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    );
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function runFullMatchScenario(bot, timeoutMs) {
+  const name = "connectivity_full_match";
+  const { socket, error } = await driveSession(bot, fullMatchScript(), timeoutMs);
+  if (error) {
+    if (error.message.startsWith("timed out")) {
+      return {
+        severity: "fail",
+        name,
+        message: `bot did not complete the canned full-match exchange within ${timeoutMs}ms \u2014 either decide() is too slow or the bot is hung waiting on something`
+      };
+    }
+    return {
+      severity: "fail",
+      name,
+      message: `bot raised ${error.constructor.name} during the canned exchange: ${error.message}`
+    };
+  }
+  if (socket.sent.length === 0) {
+    return {
+      severity: "fail",
+      name,
+      message: "bot did not send any messages during the canned exchange \u2014 at minimum the client should have sent authenticate / hello / turn_action"
+    };
+  }
+  const turnActions = extractTurnActions(socket.sent);
+  if (turnActions.length === 0) {
+    return {
+      severity: "fail",
+      name,
+      message: "bot completed the exchange but never sent a turn_action \u2014 decide() may have returned an unexpected value or the SDK's runner hit a fallback path"
+    };
+  }
+  const verdict = classifyTurnAction(JSON.stringify(turnActions[0]));
+  if (!verdict.ok) {
+    return { severity: "fail", name, message: verdict.message };
+  }
+  return {
+    severity: "pass",
+    name,
+    message: `completed handshake + 1 hand + match_end; ${verdict.message}`
+  };
+}
+async function runMultiTurnScenario(bot, timeoutMs) {
+  const name = "multi_turn_request_id_echo";
+  const { socket, error } = await driveSession(bot, multiTurnScript(), timeoutMs);
+  if (error) {
+    if (error.message.startsWith("timed out")) {
+      return {
+        severity: "fail",
+        name,
+        message: `bot did not complete the multi-turn exchange within ${timeoutMs}ms`
+      };
+    }
+    return {
+      severity: "fail",
+      name,
+      message: `bot raised ${error.constructor.name} during the multi-turn exchange: ${error.message}`
+    };
+  }
+  const turnActions = extractTurnActions(socket.sent);
+  const expectedIds = ["req_1", "req_2", "req_3"];
+  if (turnActions.length < expectedIds.length) {
+    return {
+      severity: "fail",
+      name,
+      message: `expected ${expectedIds.length} turn_actions across preflop/flop/turn, saw only ${turnActions.length} \u2014 bot stopped responding partway through the hand`
+    };
+  }
+  for (let i = 0; i < expectedIds.length; i++) {
+    const expectedId = expectedIds[i];
+    const verdict = classifyTurnAction(JSON.stringify(turnActions[i]), expectedId);
+    if (!verdict.ok) {
+      return {
+        severity: "fail",
+        name,
+        message: `turn ${i + 1} of 3 failed: ${verdict.message}`
+      };
+    }
+  }
+  return {
+    severity: "pass",
+    name,
+    message: `all ${expectedIds.length} turn_actions echoed request_id correctly across preflop/flop/turn`
+  };
+}
+async function runActionRejectedScenario(bot, timeoutMs) {
+  const name = "action_rejected_recovery";
+  const { socket, error } = await driveSession(bot, actionRejectedScript(), timeoutMs);
+  if (error) {
+    if (error.message.startsWith("timed out")) {
+      return {
+        severity: "fail",
+        name,
+        message: `bot did not complete the action_rejected scenario within ${timeoutMs}ms \u2014 the SDK's safe-fallback retry path may be hung`
+      };
+    }
+    return {
+      severity: "fail",
+      name,
+      message: `bot raised ${error.constructor.name} during action_rejected handling: ${error.message}`
+    };
+  }
+  const turnActions = extractTurnActions(socket.sent);
+  if (turnActions.length < 2) {
+    return {
+      severity: "fail",
+      name,
+      message: `expected 2 turn_actions (initial + safe-fallback retry), saw ${turnActions.length}; the SDK did not respond to the action_rejected message`
+    };
+  }
+  const retry = turnActions[1];
+  if (retry.request_id !== "req_1") {
+    return {
+      severity: "fail",
+      name,
+      message: `safe-fallback retry used request_id ${JSON.stringify(retry.request_id)} instead of the original "req_1" \u2014 server-side correlation will fail`
+    };
+  }
+  const retryParams = retry.params ?? {};
+  const retryAction = retry.action ?? retryParams.action;
+  if (retryAction !== "check" && retryAction !== "fold") {
+    return {
+      severity: "fail",
+      name,
+      message: `safe-fallback retry sent action ${JSON.stringify(retryAction)}; expected "check" or "fold" (the only universally-safe actions when valid_actions is unknown)`
+    };
+  }
+  return {
+    severity: "pass",
+    name,
+    message: `action_rejected handled cleanly: original action sent, retry sent ${JSON.stringify(retryAction)} with original request_id`
+  };
+}
+async function runRetryStormScenario(bot, timeoutMs) {
+  const name = "retry_storm_bounded";
+  const { socket, error } = await driveSession(bot, retryStormScript(), timeoutMs);
+  if (error) {
+    if (error.message.startsWith("timed out")) {
+      return {
+        severity: "fail",
+        name,
+        message: `bot did not complete the retry-storm scenario within ${timeoutMs}ms \u2014 the SDK may be stuck in a retry loop`
+      };
+    }
+    return {
+      severity: "fail",
+      name,
+      message: `bot raised ${error.constructor.name} during retry-storm handling: ${error.message}`
+    };
+  }
+  const turnActions = extractTurnActions(socket.sent);
+  const expectedCount = 4;
+  if (turnActions.length !== expectedCount) {
+    return {
+      severity: turnActions.length < expectedCount ? "fail" : "warn",
+      name,
+      message: `expected ${expectedCount} turn_actions (1 initial + 3 retries) under retry storm, saw ${turnActions.length} \u2014 the SDK's retry behavior may be unbounded or may have stopped responding`
+    };
+  }
+  return {
+    severity: "pass",
+    name,
+    message: `SDK responded to all 3 action_rejected messages with safe-fallback retries (${expectedCount} turn_actions total) and exited cleanly on match_end`
+  };
+}
+var SCENARIOS = [
+  { name: "connectivity_full_match", fn: runFullMatchScenario },
+  { name: "multi_turn_request_id_echo", fn: runMultiTurnScenario },
+  { name: "action_rejected_recovery", fn: runActionRejectedScenario },
+  { name: "retry_storm_bounded", fn: runRetryStormScenario }
+];
+async function runConformanceChecks(bot, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const results = [];
+  for (const { fn } of SCENARIOS) {
+    results.push(await fn(bot, timeoutMs));
+  }
+  return results;
+}
+
+// src/validate.ts
+var VALID_ACTION_KINDS2 = /* @__PURE__ */ new Set(["fold", "check", "call", "raise", "all_in"]);
+function isAction(v) {
+  if (!v || typeof v !== "object") return false;
+  const a = v;
+  if (typeof a.action !== "string" || !VALID_ACTION_KINDS2.has(a.action)) return false;
+  if (a.action === "raise") {
+    return typeof a.amount === "number" && Number.isFinite(a.amount) && a.amount >= 0;
+  }
+  return a.amount === void 0;
+}
+var DEFAULT_MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
+var DEFAULT_TIMEOUT_WARN_MS = 100;
+var PLATFORM_TIMEOUT_MS = 500;
+var ALLOWED_ENTRY_POINTS = ["bot.js", "bot.mjs", "bot.cjs", "main.js", "main.mjs"];
+var BLOCKED_MODULES = /* @__PURE__ */ new Set([
+  "node:child_process",
+  "child_process",
+  "node:cluster",
+  "cluster",
+  "node:dgram",
+  "dgram",
+  "node:dns",
+  "dns",
+  "node:net",
+  "net",
+  "node:tls",
+  "tls",
+  "node:repl",
+  "repl",
+  "node:vm",
+  "vm",
+  "node:worker_threads",
+  "worker_threads"
+]);
+var WARN_MODULES = /* @__PURE__ */ new Set(["node:fs", "fs", "node:fs/promises"]);
+async function validateBot(botPath, options = {}) {
+  const results = [];
+  const maxBytes = options.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
+  const timeoutWarn = options.timeoutWarnMs ?? DEFAULT_TIMEOUT_WARN_MS;
+  let stat;
+  try {
+    stat = await fs3.stat(botPath);
+  } catch {
+    results.push({
+      severity: "fail",
+      name: "file_structure",
+      message: `Path not found: ${botPath}`
+    });
+    return results;
+  }
+  if (!stat.isDirectory()) {
+    results.push({
+      severity: "fail",
+      name: "file_structure",
+      message: `Path is not a directory: ${botPath}`
+    });
+    return results;
+  }
+  results.push(...await checkDirectorySize(botPath, maxBytes));
+  results.push(
+    ...await checkDirectory(
+      botPath,
+      options.entryPoint,
+      timeoutWarn,
+      options.checkConnectivity ?? false,
+      options.conformanceTimeoutMs ?? 1e4
+    )
+  );
+  return results;
+}
+async function checkDirectorySize(dir, maxBytes) {
+  const total = await dirTotalBytes(dir);
+  const mb = total / (1024 * 1024);
+  const limitMb = maxBytes / (1024 * 1024);
+  if (total > maxBytes) {
+    return [
+      {
+        severity: "fail",
+        name: "size",
+        message: `Directory is ${mb.toFixed(1)} MB, exceeds ${limitMb.toFixed(0)} MB upload limit`
+      }
+    ];
+  }
+  return [
+    {
+      severity: "pass",
+      name: "size",
+      message: `Size OK (${mb.toFixed(1)} MB uncompressed / ${limitMb.toFixed(0)} MB limit)`
+    }
+  ];
+}
+async function checkDirectory(dir, entryPointOverride, timeoutWarnMs, checkConnectivity, conformanceTimeoutMs) {
+  const results = [];
+  const entry = await findEntryPoint(dir, entryPointOverride);
+  if (!entry) {
+    results.push({
+      severity: "fail",
+      name: "file_structure",
+      message: `No entry point found. Expected one of: ${ALLOWED_ENTRY_POINTS.join(", ")}`
+    });
+    return results;
+  }
+  results.push({
+    severity: "pass",
+    name: "file_structure",
+    message: `Entry point found: ${path4.basename(entry)}`
+  });
+  const syntaxResult = await checkSyntax(entry);
+  results.push(syntaxResult);
+  if (syntaxResult.severity === "fail") return results;
+  const source = await fs3.readFile(entry, "utf-8");
+  results.push(...checkImports(source, path4.basename(entry)));
+  const botClassResult = checkBotClass(source);
+  results.push(botClassResult);
+  if (botClassResult.severity === "fail") return results;
+  const botClassName = botClassResult.message.replace("Found bot class: ", "");
+  const decideResult = checkDecideMethod(source, botClassName);
+  results.push(decideResult);
+  if (decideResult.severity === "fail") return results;
+  results.push(
+    ...await smokeTest(entry, botClassName, timeoutWarnMs, checkConnectivity, conformanceTimeoutMs)
+  );
+  return results;
+}
+async function findEntryPoint(dir, override) {
+  const candidates = override ? [override] : ALLOWED_ENTRY_POINTS;
+  for (const name of candidates) {
+    const candidate = path4.join(dir, name);
+    try {
+      const s = await fs3.stat(candidate);
+      if (s.isFile()) return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+async function checkSyntax(filePath) {
+  try {
+    execSync(`node --check ${JSON.stringify(filePath)}`, {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 5e3
+    });
+    return { severity: "pass", name: "syntax", message: "Valid JavaScript syntax" };
+  } catch (err) {
+    const stderr = err.stderr?.toString() ?? String(err);
+    const firstLine = stderr.split("\n").find((l) => l.includes("SyntaxError")) ?? stderr.split("\n")[0] ?? stderr;
+    return {
+      severity: "fail",
+      name: "syntax",
+      message: `Syntax error: ${firstLine.trim()}`
+    };
+  }
+}
+function checkImports(source, filename) {
+  const results = [];
+  const importRe = /(?:from|import|require)\s*\(?\s*["']([^"']+)["']/g;
+  const found = /* @__PURE__ */ new Set();
+  let m;
+  while ((m = importRe.exec(source)) !== null) {
+    if (m[1]) found.add(m[1]);
+  }
+  const blocked = [];
+  const warned = [];
+  for (const mod of found) {
+    if (BLOCKED_MODULES.has(mod)) blocked.push(mod);
+    else if (WARN_MODULES.has(mod)) warned.push(mod);
+  }
+  if (blocked.length) {
+    results.push({
+      severity: "fail",
+      name: "imports",
+      message: `Blocked imports detected in ${filename}: ${blocked.join(", ")}`
+    });
+  } else {
+    results.push({
+      severity: "pass",
+      name: "imports",
+      message: "No blocked imports detected"
+    });
+  }
+  for (const w of warned) {
+    results.push({
+      severity: "warn",
+      name: "imports",
+      message: `Imports ${JSON.stringify(w)} \u2014 usable but the platform sandbox restricts what it can do`
+    });
+  }
+  return results;
+}
+function checkBotClass(source) {
+  const m = /class\s+([A-Za-z_$][A-Za-z0-9_$]*)\s+extends\s+(?:Bot|ChipzenBot)\b/.exec(source);
+  if (!m || !m[1]) {
+    return {
+      severity: "fail",
+      name: "bot_class",
+      message: "No class extending Bot (or ChipzenBot) found in entry point"
+    };
+  }
+  return {
+    severity: "pass",
+    name: "bot_class",
+    message: `Found bot class: ${m[1]}`
+  };
+}
+function checkDecideMethod(source, className) {
+  const classBlock = extractClassBlock(source, className);
+  if (!classBlock) {
+    return {
+      severity: "fail",
+      name: "decide_method",
+      message: `Could not isolate ${className}'s class body for decide() check`
+    };
+  }
+  if (!/\bdecide\s*\(/.test(stripComments(classBlock))) {
+    return {
+      severity: "fail",
+      name: "decide_method",
+      message: `${className} does not implement decide()`
+    };
+  }
+  return {
+    severity: "pass",
+    name: "decide_method",
+    message: `${className}.decide() implemented`
+  };
+}
+function extractClassBlock(source, className) {
+  const start = source.search(new RegExp(`class\\s+${className}\\s+extends\\s+(?:Bot|ChipzenBot)\\b`));
+  if (start < 0) return null;
+  const braceIdx = source.indexOf("{", start);
+  if (braceIdx < 0) return null;
+  let depth = 1;
+  for (let i = braceIdx + 1; i < source.length; i++) {
+    if (source[i] === "{") depth++;
+    else if (source[i] === "}") {
+      depth--;
+      if (depth === 0) return source.slice(braceIdx + 1, i);
+    }
+  }
+  return null;
+}
+async function smokeTest(entry, className, timeoutWarnMs, checkConnectivity, conformanceTimeoutMs) {
+  const results = [];
+  let mod;
+  try {
+    const url = new URL(`file://${path4.resolve(entry)}`).toString();
+    mod = await import(url);
+  } catch (err) {
+    results.push({
+      severity: "fail",
+      name: "smoke_test",
+      message: `Failed to import bot: ${err.message}`
+    });
+    return results;
+  }
+  const Cls = mod[className];
+  if (typeof Cls !== "function") {
+    results.push({
+      severity: "fail",
+      name: "smoke_test",
+      message: `Bot class ${className} not exported from entry point \u2014 add \`export { ${className} }\``
+    });
+    return results;
+  }
+  let bot;
+  try {
+    bot = new Cls();
+  } catch (err) {
+    results.push({
+      severity: "fail",
+      name: "smoke_test",
+      message: `${className}() constructor threw: ${err.message}`
+    });
+    return results;
+  }
+  const mockState = mockGameState();
+  const start = performance.now();
+  let action;
+  try {
+    action = bot.decide(mockState);
+  } catch (err) {
+    results.push({
+      severity: "fail",
+      name: "smoke_test",
+      message: `${className}.decide() threw: ${err.message}`
+    });
+    return results;
+  }
+  const elapsedMs = performance.now() - start;
+  if (!isAction(action)) {
+    results.push({
+      severity: "fail",
+      name: "smoke_test",
+      message: `${className}.decide() returned ${describe(action)} \u2014 expected an Action`
+    });
+    return results;
+  }
+  results.push({
+    severity: "pass",
+    name: "smoke_test",
+    message: `decide() returned ${action.action} successfully`
+  });
+  if (elapsedMs > PLATFORM_TIMEOUT_MS) {
+    results.push({
+      severity: "fail",
+      name: "timeout",
+      message: `decide() took ${elapsedMs.toFixed(1)} ms \u2014 exceeds platform default ${PLATFORM_TIMEOUT_MS} ms`
+    });
+  } else if (elapsedMs > timeoutWarnMs) {
+    results.push({
+      severity: "warn",
+      name: "timeout",
+      message: `decide() took ${elapsedMs.toFixed(1)} ms \u2014 over the warn threshold of ${timeoutWarnMs} ms`
+    });
+  } else {
+    results.push({
+      severity: "pass",
+      name: "timeout",
+      message: `decide() completed in ${elapsedMs.toFixed(1)} ms`
+    });
+  }
+  if (checkConnectivity) {
+    const conformance = await runConformanceChecks(bot, {
+      timeoutMs: conformanceTimeoutMs
+    });
+    results.push(...conformance);
+  }
+  return results;
+}
+function mockGameState() {
+  return {
+    handNumber: 1,
+    phase: "preflop",
+    holeCards: [
+      { rank: "A", suit: "h" },
+      { rank: "K", suit: "d" }
+    ],
+    board: [],
+    pot: 150,
+    yourStack: 9900,
+    opponentStacks: [9850],
+    yourSeat: 0,
+    dealerSeat: 0,
+    toCall: 50,
+    minRaise: 200,
+    maxRaise: 9900,
+    validActions: ["fold", "call", "raise"],
+    actionHistory: [],
+    roundId: "",
+    requestId: ""
+  };
+}
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+function describe(v) {
+  if (v === null) return "null";
+  if (v === void 0) return "undefined";
+  return `${typeof v} ${JSON.stringify(v)}`;
+}
+async function dirTotalBytes(dir) {
+  let total = 0;
+  const entries = await fs3.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path4.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      total += await dirTotalBytes(full);
+    } else if (entry.isFile()) {
+      const s = await fs3.stat(full);
+      total += s.size;
+    }
+  }
+  return total;
+}
+
+// src/cli.ts
+var COMMANDS = {
+  init: "Scaffold a new bot project from a starter template",
+  validate: "Run pre-upload checks: size, syntax, imports, smoke test, timeout",
+  "run-external": "Run a bot on the external-API remote-play path (lobby -> matched -> play)"
+};
+async function main(argv = process.argv.slice(2)) {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    printHelp();
+    process.exit(argv.length === 0 ? 1 : 0);
+  }
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "init":
+      await initCli(rest);
+      return;
+    case "validate":
+      await validateCli(rest);
+      return;
+    case "run-external":
+      await runExternalCli(rest);
+      return;
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.error("");
+      printHelp();
+      process.exit(1);
+  }
+}
+function printHelp() {
+  console.log("Chipzen Poker Bot SDK");
+  console.log("");
+  console.log("Usage: chipzen-sdk <command> [options]");
+  console.log("");
+  console.log("Commands:");
+  for (const [name, desc] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(14)} ${desc}`);
+  }
+  console.log("");
+  console.log("Run 'chipzen-sdk <command> --help' for details on a specific command.");
+}
+async function initCli(args) {
+  if (args[0] === "--help" || args[0] === "-h") {
+    console.log("Usage: chipzen-sdk init <name> [--dir <parent>]");
+    console.log("");
+    console.log("Scaffold a new Chipzen bot project under <parent>/<name>.");
+    console.log("Default parent is the current directory.");
+    return;
+  }
+  const { values, positionals } = parseArgs({
+    args,
+    options: { dir: { type: "string" } },
+    allowPositionals: true
+  });
+  const name = positionals[0];
+  if (!name) {
+    console.error("error: chipzen-sdk init requires a <name> positional argument");
+    process.exit(2);
+  }
+  try {
+    const created = await scaffoldBot(name, { parentDir: values.dir });
+    console.log(`Created bot project: ${created}`);
+    console.log("");
+    console.log("Next steps:");
+    console.log(`  cd ${name}`);
+    console.log("  npm install");
+    console.log("  # Edit bot.js to implement your strategy");
+    console.log("  chipzen-sdk validate .");
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(1);
+  }
+}
+async function validateCli(args) {
+  if (args[0] === "--help" || args[0] === "-h") {
+    console.log("Usage: chipzen-sdk validate <path> [options]");
+    console.log("");
+    console.log("Pre-upload validation. Checks performed:");
+    console.log("  size            Directory size within upload limits");
+    console.log("  file_structure  Entry point file (bot.js / bot.mjs / bot.cjs / main.js)");
+    console.log("  syntax          Valid JavaScript via `node --check`");
+    console.log("  imports         No blocked sandbox modules; warn on fs/fs-promises");
+    console.log("  bot_class       Class extending Bot or ChipzenBot exists");
+    console.log("  decide_method   Bot class implements decide()");
+    console.log("  smoke_test      Bot can be instantiated; decide() returns an Action");
+    console.log("  timeout         decide() completes within time limits");
+    console.log("");
+    console.log("With --check-connectivity, four protocol scenarios also run:");
+    console.log("  connectivity_full_match    Drive 1 canned match end-to-end");
+    console.log("  multi_turn_request_id_echo Drive 3 turn_requests across phases");
+    console.log("                             and verify request_id echo on each");
+    console.log("  action_rejected_recovery   Verify safe-fallback retry on rejection");
+    console.log("  retry_storm_bounded        Verify reactive response to 3 back-to-back");
+    console.log("                             action_rejected messages");
+    console.log("");
+    console.log("The validator is a courtesy linter -- the authoritative gate is");
+    console.log("server-side seccomp + cap-drop on the bot container.");
+    console.log("");
+    console.log("Options:");
+    console.log("  --entry-point <name>      Override entry-point filename");
+    console.log(`  --max-size-mb <int>       Max upload size in MB (default: ${DEFAULT_MAX_UPLOAD_BYTES / (1024 * 1024)})`);
+    console.log(`  --timeout-warn-ms <int>   Warn-threshold for decide() in ms (default: ${DEFAULT_TIMEOUT_WARN_MS})`);
+    console.log("  --check-connectivity      Run the 4 protocol-conformance scenarios");
+    console.log("  --no-color                Disable colored output");
+    return;
+  }
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      "entry-point": { type: "string" },
+      "max-size-mb": { type: "string" },
+      "timeout-warn-ms": { type: "string" },
+      "check-connectivity": { type: "boolean" },
+      "no-color": { type: "boolean" }
+    },
+    allowPositionals: true
+  });
+  const target = positionals[0];
+  if (!target) {
+    console.error("error: chipzen-sdk validate requires a <path> positional argument");
+    process.exit(2);
+  }
+  const maxBytes = values["max-size-mb"] ? parseInt(values["max-size-mb"], 10) * 1024 * 1024 : DEFAULT_MAX_UPLOAD_BYTES;
+  const timeoutWarn = values["timeout-warn-ms"] ? parseInt(values["timeout-warn-ms"], 10) : DEFAULT_TIMEOUT_WARN_MS;
+  const results = await validateBot(path5.resolve(target), {
+    entryPoint: values["entry-point"],
+    maxUploadBytes: maxBytes,
+    timeoutWarnMs: timeoutWarn,
+    checkConnectivity: values["check-connectivity"] ?? false
+  });
+  printResults(results, !values["no-color"]);
+  if (results.some((r) => r.severity === "fail")) process.exit(1);
+}
+function printResults(results, color) {
+  const supportsColor = color && process.stdout.isTTY;
+  const GREEN = supportsColor ? "\x1B[92m" : "";
+  const YELLOW = supportsColor ? "\x1B[93m" : "";
+  const RED = supportsColor ? "\x1B[91m" : "";
+  const RESET = supportsColor ? "\x1B[0m" : "";
+  console.log("");
+  console.log("Chipzen Bot Validation");
+  console.log("=".repeat(50));
+  for (const r of results) {
+    const icon = r.severity === "pass" ? `${GREEN}PASS${RESET}` : r.severity === "warn" ? `${YELLOW}WARN${RESET}` : `${RED}FAIL${RESET}`;
+    console.log(`  [${icon}] ${r.name}: ${r.message}`);
+  }
+  console.log("");
+  const fails = results.filter((r) => r.severity === "fail").length;
+  if (fails > 0) {
+    console.log(`${RED}${fails} check${fails === 1 ? "" : "s"} failed.${RESET}`);
+  } else {
+    console.log(`${GREEN}All checks passed! Your bot is ready to upload.${RESET}`);
+  }
+}
+
+// src/bin.ts
+main().catch((err) => {
+  console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+  process.exit(1);
+});
+//# sourceMappingURL=bin.js.map