bizhawk_ping

Instructions

Implementation Reference

• src/tools.ts:48-59 (registration)

  The tool 'bizhawk_ping' is registered in the TOOLS array with its name, description, and inputSchema (no parameters).

  const TOOLS: Tool[] = [
    // ── Connectivity & introspection ────────────────────────────────────────
  
    {
      name: "bizhawk_ping",
      description:
        "PURPOSE: Verify that the BizHawk Lua bridge is connected and responding to RPC over the TCP socket. " +
        "USAGE: Call this once at start-of-session before issuing other tool calls; if it succeeds, every other tool will work. " +
        "BEHAVIOR: No side effects — pure liveness probe. Times out after ~10 seconds with a clear error if BizHawk isn't running, isn't pointed at the right host:port, or hasn't loaded lua/bridge.lua via Tools → Lua Console. " +
        "RETURNS: The literal string 'pong' on success.",
      inputSchema: { type: "object", properties: {} },
    },

• src/tools.ts:496-499 (handler)

  The handler for 'bizhawk_ping' — calls bh.call('ping') and returns the result (expects literal string 'pong' on success).

  case "bizhawk_ping": {
    const r = await bh.call<string>("ping");
    return ok(r);
  }

• src/tools.ts:58-58 (schema)

  Input schema for bizhawk_ping: empty object — no parameters required.

  inputSchema: { type: "object", properties: {} },

• src/bizhawk.ts:235-264 (helper)

  The call() method on BizhawkServer that enqueues a command (including 'ping') and sends it over TCP to the Lua bridge.

  async call<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<T> {
    return new Promise<T>((resolve, reject) => {
      const id = this.nextId++;
      const pending: PendingCmd = {
        id,
        method,
        params,
        resolve: (r) => resolve(r as T),
        reject,
      };
  
      const timer = setTimeout(() => {
        // Drop from queue if still waiting; from inflight if already sent.
        this.queue   = this.queue.filter((p) => p.id !== id);
        this.inflight.delete(id);
        if (this.inflight.size === 0) this.awaitingResult = false;
        reject(new Error(
          `BizHawk call "${method}" timed out (${this.timeoutMs}ms) — ` +
          `is the bridge.lua script still polling?`,
        ));
      }, this.timeoutMs);
  
      // Wrap so the timer always clears
      const origResolve = pending.resolve, origReject = pending.reject;
      pending.resolve = (r) => { clearTimeout(timer); origResolve(r); };
      pending.reject  = (e) => { clearTimeout(timer); origReject(e); };
  
      this.queue.push(pending);
    });
  }