pyyol 1.2.0

package/dist/runtime.js

@@ -0,0 +1,372 @@
+import { SDK_VERSION } from "./server.js";
+import { Tracer } from "./telemetry.js";
+// Frame types — byte-identical to the Go gateway (internal/agentgw/frame.go).
+const HELLO = "hello", REGISTERED = "registered", PONG = "pong";
+const INITIALIZE = "initialize", TURN = "turn", EVENT = "event", GAME_END = "game_end", ERROR = "error";
+const REGISTER = "register", PING = "ping", RESPONSE = "response";
+export const PROTOCOL_VERSION = "1.0";
+/** POST {apiUrl}/v1/auth/refresh {refresh_token} → {access, refresh} or null.
+ *  A non-200 (refresh token expired/revoked) → null → terminal (must re-login). */
+async function defaultRefreshHttp(apiUrl, refreshToken) {
+    try {
+        const res = await fetch(apiUrl.replace(/\/$/, "") + "/v1/auth/refresh", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ refresh_token: refreshToken }),
+        });
+        if (!res.ok)
+            return null;
+        const j = (await res.json().catch(() => null));
+        if (!j?.dashboard_token)
+            return null;
+        return { access: j.dashboard_token, refresh: j.refresh_token ?? "" };
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeMove(game, move) {
+    if (!move || typeof move !== "object")
+        return String(move);
+    const m = move;
+    if ("card" in m)
+        return `card ${m.card}${m.round !== undefined ? ` (round ${m.round})` : ""}`;
+    if ("action" in m)
+        return `${m.action}${m.target !== undefined ? ` → ${m.target}` : ""}`;
+    return JSON.stringify(m);
+}
+function summarizeResult(result) {
+    if (!result || typeof result !== "object")
+        return "game finished";
+    const outer = result;
+    // The gateway may nest the outcome under `result` (with a viewer-relative winner
+    // label like "you"/"opponent"/"tie"); unwrap it like the Python SDK does.
+    const inner = (outer.result && typeof outer.result === "object" ? outer.result : outer);
+    const bits = [];
+    if (inner.winner !== undefined && inner.winner !== null)
+        bits.push(`winner: ${inner.winner}`);
+    for (const k of ["coins_delta", "your_coins", "coins"]) {
+        if (inner[k]) {
+            bits.push(`${k}=${inner[k]}`);
+            break;
+        }
+    }
+    return "game finished" + (bits.length ? " · " + bits.join(" · ") : "");
+}
+/** Terminal connector failure (e.g. auth rejected) — not retried. */
+export class ConnectorError extends Error {
+}
+/** Internal: the access token was just refreshed; reconnect immediately with the
+ *  new token (not a transport error, so no backoff / scary log). */
+class RefreshRetry extends Error {
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Parse a dotted version into a comparable number array; unparseable ⇒ [0] so a
+ *  garbage latest_sdk never triggers a spurious nudge. */
+function versionParts(v) {
+    const core = v.trim().replace(/^v/, "").split(/[-+]/)[0];
+    const parts = core.split(".").map((p) => Number(p));
+    return parts.some((n) => !Number.isFinite(n)) ? [0] : parts;
+}
+/** True if a is strictly older than b (numeric field-by-field). */
+function isOlder(a, b) {
+    const pa = versionParts(a);
+    const pb = versionParts(b);
+    const n = Math.max(pa.length, pb.length);
+    for (let i = 0; i < n; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y;
+    }
+    return false;
+}
+export class RuntimeConnector {
+    agent;
+    opts;
+    stopped = false;
+    nudged = false; // print the "upgrade available" notice at most once
+    registered = false; // true once this session's register succeeded
+    refreshAttempts = 0; // per-connection guard against a refresh loop
+    // Opt-in Pyyol Lens telemetry (no-op unless PYYOL_LENS_ENDPOINT+KEY set).
+    // Correlated to the match trace so the agent's model/tool calls render with
+    // the platform's authoritative gateway spans.
+    tracer;
+    constructor(agent, opts) {
+        this.agent = agent;
+        this.opts = opts;
+        this.tracer = Tracer.fromEnv({ agentId: opts.agentId, service: opts.name });
+    }
+    /** The gateway echoes the newest published version on the registered frame.
+     *  Print a one-line upgrade hint at most once (not on every reconnect). */
+    maybeNudge(latest) {
+        if (this.nudged || typeof latest !== "string" || !latest)
+            return;
+        if (isOlder(SDK_VERSION, latest)) {
+            this.nudged = true;
+            const notify = this.opts.onNotice ?? ((m) => console.warn(m));
+            notify(`a new pyyol ${latest} is available (you have ${SDK_VERSION}) — upgrade with \`npm update pyyol\``);
+        }
+    }
+    /** Connect and serve until stopped, reconnecting with exponential backoff. */
+    async run() {
+        let backoff = 1000;
+        const maxBackoff = this.opts.maxBackoffMs ?? 30000;
+        while (!this.stopped) {
+            try {
+                await this.session();
+                backoff = 1000;
+                if (this.opts.reconnect === false)
+                    return;
+            }
+            catch (e) {
+                if (e instanceof RefreshRetry) {
+                    // Token was just refreshed — reconnect right away with the new one, no
+                    // backoff and no "connection lost" noise (even in one-shot mode).
+                    this.feed("reauth", "access token refreshed — reconnecting");
+                    backoff = 1000;
+                    continue;
+                }
+                if (e instanceof ConnectorError)
+                    throw e; // terminal (auth) — don't spin
+                if (this.opts.reconnect === false || this.stopped)
+                    throw e;
+                // Surface the retry so a bad/absent network doesn't look like a frozen
+                // terminal (the reason is often "can't reach the platform").
+                this.feed("reconnecting", `${e.message} — retrying in ${Math.round(backoff / 1000)}s`);
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, maxBackoff);
+            }
+        }
+    }
+    stop() {
+        this.stopped = true;
+        void this.tracer.close();
+    }
+    /** Emit a live-feed line to the CLI/console, if a sink was provided. */
+    feed(kind, detail) {
+        this.opts.onFeed?.(kind, detail);
+    }
+    /** Warn (once) when connecting over cleartext ws:// to a non-local host — the
+     *  register token is sent in the clear (mirrors the Python connector). */
+    securityCheck() {
+        try {
+            const u = new URL(this.opts.url);
+            if (u.protocol === "ws:") {
+                const h = u.hostname.toLowerCase();
+                if (!(h === "localhost" || h === "127.0.0.1" || h === "::1" || h.endsWith(".localhost"))) {
+                    // Security warning goes straight to stderr — NOT through onNotice, which is
+                    // reserved for the SDK upgrade nudge (a host app may route that to its UI).
+                    console.warn(`WARNING: connecting over insecure ws:// to ${h} — your token is sent in cleartext; use wss://`);
+                }
+            }
+        }
+        catch {
+            /* unparseable url — the connect below will surface it */
+        }
+    }
+    /** One connection lifetime: resolves on a clean stop, rejects on transport loss. */
+    /** Spend the refresh token for a fresh access token; returns true on success
+     *  (opts.token rotated + persisted). Bounded per connection to avoid a loop. */
+    async tryRefresh() {
+        const rt = this.opts.refreshToken;
+        const api = this.opts.apiUrl;
+        if (!rt || !api || this.refreshAttempts >= 2)
+            return false;
+        this.refreshAttempts++;
+        let pair;
+        try {
+            pair = await (this.opts.refreshHttp ?? defaultRefreshHttp)(api, rt);
+        }
+        catch {
+            return false;
+        }
+        if (!pair?.access)
+            return false;
+        this.opts.token = pair.access;
+        if (pair.refresh)
+            this.opts.refreshToken = pair.refresh;
+        if (this.opts.onTokens) {
+            try {
+                await this.opts.onTokens(pair.access, this.opts.refreshToken ?? "");
+            }
+            catch {
+                /* persistence is best-effort */
+            }
+        }
+        return true;
+    }
+    session() {
+        this.securityCheck();
+        this.registered = false;
+        const WS = this.opts.WebSocketImpl ?? globalThis.WebSocket;
+        if (!WS)
+            throw new ConnectorError("no WebSocket implementation (Node >=22 or pass WebSocketImpl)");
+        let host = this.opts.url;
+        try {
+            host = new URL(this.opts.url).host;
+        }
+        catch { /* keep raw */ }
+        this.feed("connecting", host);
+        const ws = new WS(this.opts.url);
+        return new Promise((resolve, reject) => {
+            let hb;
+            let settled = false;
+            let opened = false;
+            let queue = Promise.resolve(); // serialize frame dispatch (FIFO)
+            const send = (f) => ws.send(JSON.stringify(f));
+            // Bound the OPENING handshake — the WHATWG WebSocket has no connect timeout, so
+            // a dead-air link (accepts TCP, never upgrades) would hang forever. On timeout
+            // we fail with a transient error → run() reconnects.
+            const openTimer = setTimeout(() => {
+                if (!opened)
+                    fail(new Error("connect timed out (platform unreachable)"));
+            }, this.opts.connectTimeoutMs ?? 10000);
+            // Liveness watchdog — a window with zero frames means the link is (half-)dead.
+            // Rearmed on every received frame below; a healthy socket sees gateway PINGs
+            // well inside the window, so it only fires when the link has actually gone away.
+            const hbMs = this.opts.heartbeatMs ?? 10000;
+            const liveWindow = this.opts.livenessTimeoutMs ?? Math.max(30000, hbMs * 3);
+            let liveTimer;
+            const armLive = () => {
+                if (liveTimer)
+                    clearTimeout(liveTimer);
+                liveTimer = setTimeout(() => fail(new Error("liveness timeout — no frames received (link half-open?)")), liveWindow);
+            };
+            const cleanup = () => {
+                clearTimeout(openTimer);
+                if (liveTimer)
+                    clearTimeout(liveTimer);
+                if (hb)
+                    clearInterval(hb);
+                try {
+                    ws.close();
+                }
+                catch { /* already closing */ }
+            };
+            const fail = (e) => { if (!settled) {
+                settled = true;
+                cleanup();
+                reject(e);
+            } };
+            const done = () => { if (!settled) {
+                settled = true;
+                cleanup();
+                resolve();
+            } };
+            armLive(); // start the clock now; the first HELLO should arrive promptly
+            ws.addEventListener("open", () => { opened = true; });
+            ws.addEventListener("message", (ev) => {
+                armLive(); // any frame (of any type) proves the link is alive → reset
+                let frame;
+                try {
+                    frame = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+                }
+                catch {
+                    return;
+                }
+                // Chain onto the queue so frames are handled strictly one-at-a-time, in
+                // arrival order — responses can't be sent out of order under a burst.
+                queue = queue.then(async () => {
+                    if (settled)
+                        return;
+                    try {
+                        await this.dispatch(frame, send, () => {
+                            hb = setInterval(() => send({ t: PING }), this.opts.heartbeatMs ?? 10000);
+                        });
+                    }
+                    catch (e) {
+                        fail(e instanceof Error ? e : new Error(String(e)));
+                    }
+                });
+            });
+            ws.addEventListener("close", () => {
+                // Drain any queued frame dispatches BEFORE settling, so a close that arrives
+                // right after the last frame doesn't cut off its handling (e.g. a final turn
+                // response). In one-shot mode (or after stop()) a close is a clean end;
+                // otherwise it is a transport loss that run() turns into a reconnect.
+                queue = queue.then(() => {
+                    if (this.stopped || this.opts.reconnect === false)
+                        done();
+                    else
+                        fail(new Error("connection closed"));
+                });
+            });
+            ws.addEventListener("error", () => { });
+        });
+    }
+    async dispatch(frame, send, onRegistered) {
+        switch (frame.t) {
+            case HELLO:
+                send({
+                    t: REGISTER, agent_id: this.opts.agentId ?? "", token: this.opts.token ?? "",
+                    agent_name: this.opts.name ?? "pyyol-agent", version: this.opts.version ?? "1.0.0",
+                    games: this.opts.games ?? [], sdk_version: SDK_VERSION, sdk_language: "js",
+                });
+                break;
+            case REGISTERED:
+                this.registered = true;
+                this.refreshAttempts = 0; // a good register clears the refresh guard
+                this.maybeNudge(frame.latest_sdk);
+                this.feed("connected", `as ${frame.agent_id ?? this.opts.agentId ?? ""} · games=${(this.opts.games ?? []).join(",")}`);
+                onRegistered();
+                break;
+            case ERROR:
+                if (!this.registered) {
+                    // Register rejected — almost always an expired access token. If we hold a
+                    // refresh token, spend it and reconnect; only terminal when refresh fails.
+                    if (await this.tryRefresh())
+                        throw new RefreshRetry();
+                    throw new ConnectorError(`register rejected: ${frame.error} (${frame.reason ?? ""})`);
+                }
+                // Mid-session gateway error — surface it, not terminal (mirrors Python).
+                this.feed("error", `${frame.error} (${frame.reason ?? ""})`);
+                break;
+            case PING:
+                send({ t: PONG, id: frame.id ?? "" });
+                break;
+            case PONG:
+                break;
+            case TURN: {
+                const view = frame.payload ?? {};
+                // Bracket the developer's handler in a Lens span; inside decideTurn the
+                // author can reach it via pyyol.currentSpan() to record model/tool calls.
+                const { status, body } = await this.tracer.runTurn({
+                    matchId: view.match_id ?? "",
+                    game: view.game ?? "",
+                    round: Number(view.round ?? 0) || 0,
+                    agentId: this.opts.agentId,
+                }, () => this.agent.decideTurn(view));
+                if (status === 200) {
+                    send({ t: RESPONSE, id: frame.id ?? "", payload: body });
+                    this.feed("turn", summarizeMove(frame.payload?.game ?? "", body));
+                }
+                else {
+                    send({ t: RESPONSE, id: frame.id ?? "", error: body?.error ?? "handler_error" });
+                }
+                break;
+            }
+            case INITIALIZE: {
+                const ack = await this.agent.ackInitialize(frame.payload ?? {});
+                send({ t: RESPONSE, id: frame.id ?? "", payload: ack });
+                break;
+            }
+            case EVENT:
+                await this.agent.notifyEvent({
+                    match_id: frame.match_id ?? "", game: frame.game ?? "",
+                    seq: frame.seq ?? 0, type: frame.kind ?? "", payload: frame.payload,
+                });
+                this.feed("event", `${frame.kind ?? "event"}${frame.seq !== undefined ? ` seq=${frame.seq}` : ""}`);
+                break;
+            case GAME_END:
+                await this.agent.notifyGameEnd({
+                    match_id: frame.match_id ?? "", game: frame.game ?? "", result: frame.payload,
+                });
+                this.feed("game_end", summarizeResult(frame.payload));
+                break;
+            default:
+                break;
+        }
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The Pyyol agent server.
+ *
+ * You register decision handlers; the SDK owns the wire protocol — routing,
+ * signature verification, replay protection, payload parsing, and response
+ * serialization. It contains no game strategy: your turn handler returns the move.
+ *
+ *     import { Agent } from "pyyol";
+ *
+ *     const agent = new Agent({ secret: process.env.PYYOL_SECRET });
+ *     agent.onTurn("goofspiel", (v) => ({ round: v.round, card: Math.min(...v.legal_actions) }));
+ *     agent.serve(9099);
+ *
+ * Routes served (base path comes from your manifest `endpoint.url`; the rest are
+ * its siblings): GET /health, POST /handshake, /initialize, <endpoint> (turn),
+ * /event, /game-end.
+ */
+import { createServer } from "node:http";
+import { EventNotification, GameEndNotification, InitializeRequest, Move, TurnView } from "./models.js";
+import { Headers } from "./signing.js";
+import { SDK_VERSION } from "./version.js";
+export { SDK_VERSION };
+export interface AgentOptions {
+    /** Manifest endpoint secret — the shared key the platform signs with. When set
+     *  (recommended) every POST is signature-verified with replay protection. */
+    secret?: string;
+    supportedGames?: string[];
+    name?: string;
+    skewSeconds?: number;
+    /** Force verification on/off; defaults to on iff a secret is set. */
+    verify?: boolean;
+}
+export interface DispatchResult {
+    status: number;
+    body: Record<string, unknown>;
+}
+type TurnHandler = (view: TurnView) => Move | Promise<Move>;
+export declare class Agent {
+    readonly secret: string;
+    readonly supportedGames: string[];
+    readonly name: string;
+    private skew;
+    private verify;
+    private replay;
+    private turnHandlers;
+    private defaultTurn?;
+    private initHandler?;
+    private eventHandler?;
+    private gameEndHandler?;
+    constructor(opts?: AgentOptions);
+    /** Register the per-turn decision handler. Pass a game to scope it, or omit for
+     *  a catch-all used when no game-specific handler is set. */
+    onTurn(game: string | TurnHandler, handler?: TurnHandler): this;
+    onInitialize(fn: (r: InitializeRequest) => unknown): this;
+    onEvent(fn: (n: EventNotification) => unknown): this;
+    onGameEnd(fn: (n: GameEndNotification) => unknown): this;
+    /** Route one request and return `{ status, body }`. Framework-agnostic — call it
+     *  from the built-in server or any web framework you already run. `path` must be
+     *  the request path as received (no query). */
+    handle(method: string, path: string, headers: Headers, body: Buffer): Promise<DispatchResult>;
+    private handleTurn;
+    /** Run the turn handler for a raw view dict; returns `{status, body}`. */
+    decideTurn(view: Record<string, unknown>): Promise<DispatchResult>;
+    /** Run the initialize handler and return the ack object. */
+    ackInitialize(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    notifyEvent(data: Record<string, unknown>): Promise<void>;
+    notifyGameEnd(data: Record<string, unknown>): Promise<void>;
+    /** Connect to the platform and serve matches over an outbound WebSocket — the
+     *  Beta local-runtime path (no inbound endpoint; works behind NAT). Blocks
+     *  until stopped; reconnects automatically. */
+    run(opts: import("./runtime.js").RuntimeOptions): Promise<void>;
+    /** Run an HTTP server until the process exits. Zero dependencies. */
+    serve(port?: number, host?: string): ReturnType<typeof createServer>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,YAAY,EAAmC,MAAM,WAAW,CAAC;AAC1E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,IAAI,EAEJ,QAAQ,EAET,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,OAAO,EAAiD,MAAM,cAAc,CAAC;AAItF,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B;iFAC6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,KAAK,WAAW,GAAG,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5D,qBAAa,KAAK;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,WAAW,CAAC,CAAuD;IAC3E,OAAO,CAAC,YAAY,CAAC,CAAuD;IAC5E,OAAO,CAAC,cAAc,CAAC,CAAyD;gBAEpE,IAAI,GAAE,YAAiB;IAQnC;iEAC6D;IAC7D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAK/D,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,iBAAiB,KAAK,OAAO,GAAG,IAAI;IACzD,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,iBAAiB,KAAK,OAAO,GAAG,IAAI;IACpD,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,OAAO,GAAG,IAAI;IAExD;;mDAE+C;IACzC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YAwCrF,UAAU;IAexB,0EAA0E;IAC1E,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAGlE,4DAA4D;IACtD,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI9E,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAGzD,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE;;mDAE+C;IACzC,GAAG,CAAC,IAAI,EAAE,OAAO,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASrE,qEAAqE;IACrE,KAAK,CAAC,IAAI,SAAO,EAAE,IAAI,SAAc,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC;CAmBxE"}

package/dist/server.js

@@ -0,0 +1,174 @@
+/**
+ * The Pyyol agent server.
+ *
+ * You register decision handlers; the SDK owns the wire protocol — routing,
+ * signature verification, replay protection, payload parsing, and response
+ * serialization. It contains no game strategy: your turn handler returns the move.
+ *
+ *     import { Agent } from "pyyol";
+ *
+ *     const agent = new Agent({ secret: process.env.PYYOL_SECRET });
+ *     agent.onTurn("goofspiel", (v) => ({ round: v.round, card: Math.min(...v.legal_actions) }));
+ *     agent.serve(9099);
+ *
+ * Routes served (base path comes from your manifest `endpoint.url`; the rest are
+ * its siblings): GET /health, POST /handshake, /initialize, <endpoint> (turn),
+ * /event, /game-end.
+ */
+import { createServer } from "node:http";
+import { SUPPORTED_GAMES, parseView, } from "./models.js";
+import { ReplayGuard, VerificationError, verifyRequest } from "./signing.js";
+// Single source of truth: the generated version.ts (from package.json). Imported
+// for local use below and re-exported so `import { SDK_VERSION } from "pyyol"` works.
+import { SDK_VERSION } from "./version.js";
+export { SDK_VERSION };
+export class Agent {
+    secret;
+    supportedGames;
+    name;
+    skew;
+    verify;
+    replay = new ReplayGuard();
+    turnHandlers = new Map();
+    defaultTurn;
+    initHandler;
+    eventHandler;
+    gameEndHandler;
+    constructor(opts = {}) {
+        this.secret = opts.secret ?? "";
+        this.supportedGames = opts.supportedGames ?? [...SUPPORTED_GAMES];
+        this.name = opts.name ?? "pyyol-agent";
+        this.skew = opts.skewSeconds ?? 300;
+        this.verify = opts.verify ?? Boolean(this.secret);
+    }
+    /** Register the per-turn decision handler. Pass a game to scope it, or omit for
+     *  a catch-all used when no game-specific handler is set. */
+    onTurn(game, handler) {
+        if (typeof game === "function")
+            this.defaultTurn = game;
+        else if (handler)
+            this.turnHandlers.set(game, handler);
+        return this;
+    }
+    onInitialize(fn) { this.initHandler = fn; return this; }
+    onEvent(fn) { this.eventHandler = fn; return this; }
+    onGameEnd(fn) { this.gameEndHandler = fn; return this; }
+    /** Route one request and return `{ status, body }`. Framework-agnostic — call it
+     *  from the built-in server or any web framework you already run. `path` must be
+     *  the request path as received (no query). */
+    async handle(method, path, headers, body) {
+        method = method.toUpperCase();
+        const suffix = path.replace(/\/+$/, "").split("/").pop() ?? "";
+        // Health is an unauthenticated liveness probe — never signature-checked.
+        if (method === "GET" && suffix === "health") {
+            return { status: 200, body: { status: "healthy", agent: this.name, version: SDK_VERSION } };
+        }
+        if (method !== "POST")
+            return { status: 405, body: { error: "method_not_allowed" } };
+        if (this.verify) {
+            try {
+                verifyRequest(this.secret, headers, method, path, body, { skewSeconds: this.skew, replayGuard: this.replay });
+            }
+            catch (e) {
+                const reason = e instanceof VerificationError ? e.reason : "bad_signature";
+                return { status: 401, body: { error: "unauthorized", reason } };
+            }
+        }
+        const data = loadJson(body);
+        if (suffix === "handshake") {
+            return { status: 200, body: { accepted: true, sdkVersion: SDK_VERSION, supportedGames: this.supportedGames } };
+        }
+        if (suffix === "initialize") {
+            const ack = this.initHandler ? await this.initHandler(data) : undefined;
+            if (ack && typeof ack === "object")
+                return { status: 200, body: ack };
+            return { status: 200, body: { ready: true, display_name: this.name } };
+        }
+        if (suffix === "event") {
+            if (this.eventHandler)
+                await this.eventHandler(data);
+            return { status: 200, body: { ok: true } };
+        }
+        if (suffix === "game-end") {
+            if (this.gameEndHandler)
+                await this.gameEndHandler(data);
+            return { status: 200, body: { ok: true } };
+        }
+        return this.handleTurn(data);
+    }
+    async handleTurn(data) {
+        const game = typeof data.game === "string" ? data.game : "";
+        const handler = this.turnHandlers.get(game) ?? this.defaultTurn;
+        if (!handler)
+            return { status: 501, body: { error: "no_turn_handler", game } };
+        try {
+            const move = await handler(parseView(data));
+            return { status: 200, body: move ?? {} };
+        }
+        catch {
+            return { status: 500, body: { error: "handler_error" } };
+        }
+    }
+    // --- shared handler invocation (used by both the HTTP path and the socket
+    // RuntimeConnector, so both transports run identical decision logic) ---
+    /** Run the turn handler for a raw view dict; returns `{status, body}`. */
+    decideTurn(view) {
+        return this.handleTurn(view);
+    }
+    /** Run the initialize handler and return the ack object. */
+    async ackInitialize(data) {
+        const ack = this.initHandler ? await this.initHandler(data) : undefined;
+        return ack && typeof ack === "object" ? ack : { ready: true, display_name: this.name };
+    }
+    async notifyEvent(data) {
+        if (this.eventHandler)
+            await this.eventHandler(data);
+    }
+    async notifyGameEnd(data) {
+        if (this.gameEndHandler)
+            await this.gameEndHandler(data);
+    }
+    /** Connect to the platform and serve matches over an outbound WebSocket — the
+     *  Beta local-runtime path (no inbound endpoint; works behind NAT). Blocks
+     *  until stopped; reconnects automatically. */
+    async run(opts) {
+        const { RuntimeConnector } = await import("./runtime.js");
+        await new RuntimeConnector(this, {
+            name: this.name,
+            games: this.supportedGames,
+            ...opts,
+        }).run();
+    }
+    /** Run an HTTP server until the process exits. Zero dependencies. */
+    serve(port = 9099, host = "127.0.0.1") {
+        const server = createServer((req, res) => {
+            const chunks = [];
+            req.on("data", (c) => chunks.push(c));
+            req.on("end", async () => {
+                const body = Buffer.concat(chunks);
+                const path = (req.url ?? "/").split("?")[0];
+                const { status, body: payload } = await this.handle(req.method ?? "GET", path, req.headers, body);
+                const out = Buffer.from(JSON.stringify(payload));
+                res.writeHead(status, { "Content-Type": "application/json", "Content-Length": String(out.length) });
+                res.end(out);
+            });
+        });
+        server.listen(port, host, () => {
+            // eslint-disable-next-line no-console
+            console.log(`pyyol agent "${this.name}" listening on http://${host}:${port} (verify=${this.verify})`);
+        });
+        return server;
+    }
+}
+function loadJson(body) {
+    if (!body || body.length === 0)
+        return {};
+    try {
+        const obj = JSON.parse(body.toString("utf8"));
+        return obj && typeof obj === "object" ? obj : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=server.js.map