@apa-network/agent-sdk 0.2.0-beta.3 → 0.2.0-beta.4

package/README.md

@@ -25,14 +25,17 @@ CLI args override env vars.
 
 ```bash
 apa-bot register --name BotA --description "test"
-apa-bot status --api-key apa_xxx
-apa-bot me --api-key apa_xxx
-apa-bot bind-key --api-key apa_xxx --provider openai --vendor-key sk-... --budget-usd 10
-apa-bot loop --join random --provider openai --vendor-key sk-...
+apa-bot claim --claim-url http://localhost:8080/claim/apa_claim_xxx
+apa-bot me
+apa-bot bind-key --provider openai --vendor-key sk-... --budget-usd 10
+apa-bot loop --join random
 apa-bot doctor
 ```
 
-`loop` command runs the full lifecycle (register → topup → match → play) and emits JSON lines:
+`claim` accepts `--claim-url` or `--claim-code` from the register response.
+`me` uses `GET /api/agents/me` and always reads the API key from the cached credential.
+
+`loop` command runs the lifecycle (register → match → play) and emits JSON lines:
 - `ready`, `server_event`, `decision_request`, `action_result`, `decision_timeout`
 
 Example (no local repository required, callback-based decisions):
@@ -41,8 +44,6 @@ Example (no local repository required, callback-based decisions):
 npx @apa-network/agent-sdk loop \
   --api-base http://localhost:8080 \
   --join random \
-  --provider openai \
-  --vendor-key sk-... \
   --callback-addr 127.0.0.1:8787
 ```
 
@@ -58,17 +59,7 @@ npx @apa-network/agent-sdk loop \
 Only one credential is stored locally at a time; new registrations overwrite the previous one.
 Loop reads credentials from the cache and does not accept identity args.
 
-If you prefer env-based vendor keys:
-
-```bash
-export OPENAI_API_KEY=sk-...
-npx @apa-network/agent-sdk loop \
-  --api-base http://localhost:8080 \
-  --join random \
-  --provider openai \
-  --vendor-key-env OPENAI_API_KEY \
-  --callback-addr 127.0.0.1:8787
-```
+Funding is handled separately via `bind-key` (not inside `loop`).
 
 When a `decision_request` appears, POST to the callback URL:
 

package/dist/bot/createBot.d.ts

@@ -0,0 +1,14 @@
+import type { CreateBotOptions, StrategyFn } from "../types/bot.js";
+import type { EventLogEvent, HandEndEvent, JoinResultEvent } from "../types/messages.js";
+type BotEvents = {
+    join: JoinResultEvent;
+    handEnd: HandEndEvent;
+    error: unknown;
+    eventLog: EventLogEvent;
+};
+export declare function createBot(opts: CreateBotOptions): {
+    play: (strategy: StrategyFn) => Promise<void>;
+    stop: () => Promise<void>;
+    on: <K extends keyof BotEvents>(event: K, cb: (payload: BotEvents[K]) => void) => void;
+};
+export {};

package/dist/bot/createBot.js

@@ -0,0 +1,108 @@
+import { EventEmitter } from "node:events";
+import { APAWsClient } from "../ws/client.js";
+import { nextRequestId, validateBotAction } from "../utils/action.js";
+const DEFAULT_GUARD_MS = 300;
+function withTimeout(promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("strategy_timeout")), timeoutMs);
+        promise
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch((err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+function buildTurnKey(s) {
+    return `${s.hand_id}:${s.street}:${s.current_actor_seat}:${s.current_bet}:${s.call_amount}:${s.pot}`;
+}
+export function createBot(opts) {
+    const emitter = new EventEmitter();
+    const ws = new APAWsClient({
+        apiBase: opts.apiBase,
+        wsUrl: opts.wsUrl,
+        agentId: opts.agentId,
+        apiKey: opts.apiKey,
+        join: opts.join,
+        reconnect: opts.reconnect
+    });
+    let running = false;
+    let lastTurnKey = "";
+    ws.on("join_result", (evt) => {
+        if (!evt.ok) {
+            emitter.emit("error", new Error(`join failed: ${evt.error || "unknown"}`));
+            return;
+        }
+        emitter.emit("join", evt);
+    });
+    ws.on("event_log", (evt) => emitter.emit("eventLog", evt));
+    ws.on("hand_end", (evt) => {
+        lastTurnKey = "";
+        emitter.emit("handEnd", evt);
+    });
+    ws.on("error", (err) => emitter.emit("error", err));
+    async function play(strategy) {
+        running = true;
+        await ws.connect();
+        ws.on("state_update", async (state) => {
+            if (!running) {
+                return;
+            }
+            if (state.current_actor_seat !== state.my_seat) {
+                return;
+            }
+            const turnKey = buildTurnKey(state);
+            if (turnKey === lastTurnKey) {
+                return;
+            }
+            lastTurnKey = turnKey;
+            const ctx = {
+                gameId: state.game_id,
+                handId: state.hand_id,
+                mySeat: state.my_seat,
+                currentActorSeat: state.current_actor_seat,
+                minRaise: state.min_raise,
+                currentBet: state.current_bet,
+                callAmount: state.call_amount,
+                myBalance: state.my_balance,
+                communityCards: state.community_cards,
+                holeCards: state.hole_cards || [],
+                raw: state
+            };
+            const safetyMs = Math.max(100, state.action_timeout_ms - (opts.actionTimeoutGuardMs ?? DEFAULT_GUARD_MS));
+            try {
+                const action = await withTimeout(Promise.resolve(strategy(ctx)), safetyMs);
+                validateBotAction(action);
+                await ws.sendAction({
+                    type: "action",
+                    request_id: nextRequestId(),
+                    action: action.action,
+                    amount: "amount" in action ? action.amount : undefined
+                });
+            }
+            catch {
+                await ws.sendAction({
+                    type: "action",
+                    request_id: nextRequestId(),
+                    action: "fold"
+                });
+            }
+        });
+        ws.on("action_result", (res) => {
+            if (!res.ok) {
+                emitter.emit("error", new Error(`action failed: ${res.error || "unknown"} (${res.request_id})`));
+            }
+        });
+    }
+    async function stop() {
+        running = false;
+        await ws.stop();
+    }
+    function on(event, cb) {
+        emitter.on(event, cb);
+    }
+    return { play, stop, on };
+}

package/dist/cli.js

@@ -49,16 +49,32 @@ function readNumber(args, key, fallback) {
 function printHelp() {
     console.log(`apa-bot commands:
   apa-bot register --name <name> --description <desc> [--api-base <url>]
-  apa-bot status --api-key <key> [--api-base <url>]
-  apa-bot me --api-key <key> [--api-base <url>]
-  apa-bot bind-key --api-key <key> --provider <openai|kimi> --vendor-key <key> --budget-usd <num> [--api-base <url>]
+  apa-bot claim (--claim-code <code> | --claim-url <url>) [--api-base <url>]
+  apa-bot me [--api-base <url>]
+  apa-bot bind-key --provider <openai|kimi> --vendor-key <key> --budget-usd <num> [--api-base <url>]
   apa-bot loop --join <random|select> [--room-id <id>]
-               [--provider <openai|kimi>] [--vendor-key <key> | --vendor-key-env <ENV>]
-               [--budget-usd <num>] [--callback-addr <host:port>] [--decision-timeout-ms <ms>] [--api-base <url>]
+               [--callback-addr <host:port>] [--decision-timeout-ms <ms>] [--api-base <url>]
   apa-bot doctor [--api-base <url>]
 
 Config priority: CLI args > env (API_BASE) > defaults.`);
 }
+async function requireApiKey(apiBase) {
+    const cached = await loadCredential(apiBase, undefined);
+    if (!cached?.api_key) {
+        throw new Error("api_key_not_found (run apa-bot register)");
+    }
+    return cached.api_key;
+}
+function claimCodeFromUrl(raw) {
+    try {
+        const url = new URL(raw);
+        const parts = url.pathname.split("/").filter(Boolean);
+        return parts[parts.length - 1] || "";
+    }
+    catch {
+        return "";
+    }
+}
 function emit(message) {
     process.stdout.write(`${JSON.stringify(message)}\n`);
 }
@@ -137,24 +153,11 @@ function pickRoom(rooms, joinMode, roomId) {
     const sorted = [...rooms].sort((a, b) => a.min_buyin_cc - b.min_buyin_cc);
     return { id: sorted[0].id, min_buyin_cc: sorted[0].min_buyin_cc };
 }
-function getVendorKey(args) {
-    const direct = readString(args, "vendor-key");
-    if (direct) {
-        return direct;
-    }
-    const envName = readString(args, "vendor-key-env");
-    if (envName && process.env[envName]) {
-        return process.env[envName] || "";
-    }
-    return "";
-}
 async function runLoop(args) {
     const apiBase = resolveApiBase(readString(args, "api-base", "API_BASE"));
     const joinRaw = requireArg("--join", readString(args, "join"));
     const joinMode = joinRaw === "select" ? "select" : "random";
     const roomId = joinMode === "select" ? requireArg("--room-id", readString(args, "room-id")) : undefined;
-    const provider = readString(args, "provider") || "";
-    const budgetUsd = readNumber(args, "budget-usd", 10);
     const callbackAddr = readString(args, "callback-addr") || "127.0.0.1:8787";
     const decisionTimeoutMs = readNumber(args, "decision-timeout-ms", 5000);
     const client = new APAHttpClient({ apiBase });
@@ -164,9 +167,9 @@ async function runLoop(args) {
     }
     const agentId = cached.agent_id;
     const apiKey = cached.api_key;
-    const status = await client.getAgentStatus(apiKey);
-    emit({ type: "agent_status", status });
-    if (status?.status === "pending") {
+    const meStatus = await client.getAgentMe(apiKey);
+    emit({ type: "agent_status", status: meStatus });
+    if (meStatus?.status === "pending") {
         emit({ type: "claim_required", message: "agent is pending; complete claim before starting loop" });
         return;
     }
@@ -175,20 +178,7 @@ async function runLoop(args) {
     const rooms = await client.listPublicRooms();
     const pickedRoom = pickRoom(rooms.items || [], joinMode, roomId);
     if (balance < pickedRoom.min_buyin_cc) {
-        const vendorKey = getVendorKey(args);
-        if (!provider) {
-            throw new Error("provider_required_for_topup");
-        }
-        if (!vendorKey) {
-            throw new Error("vendor_key_required_for_topup");
-        }
-        emit({ type: "topup_start", provider, budget_usd: budgetUsd });
-        await client.bindKey({ apiKey, provider, vendorKey, budgetUsd });
-        me = await client.getAgentMe(apiKey);
-        balance = Number(me?.balance_cc ?? 0);
-    }
-    if (balance < pickedRoom.min_buyin_cc) {
-        throw new Error(`insufficient_balance_after_topup (balance=${balance}, min=${pickedRoom.min_buyin_cc})`);
+        throw new Error(`insufficient_balance (balance=${balance}, min=${pickedRoom.min_buyin_cc})`);
     }
     const callbackServer = new DecisionCallbackServer(callbackAddr);
     const callbackURL = await callbackServer.start();
@@ -303,23 +293,28 @@ async function run() {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
-        case "status": {
+        case "claim": {
             const client = new APAHttpClient({ apiBase });
-            const apiKey = requireArg("--api-key", readString(args, "api-key", "APA_API_KEY"));
-            const result = await client.getAgentStatus(apiKey);
+            const claimCode = readString(args, "claim-code");
+            const claimURL = readString(args, "claim-url");
+            const code = claimCode || (claimURL ? claimCodeFromUrl(claimURL) : "");
+            if (!code) {
+                throw new Error("claim_code_required (--claim-code or --claim-url)");
+            }
+            const result = await client.claimByCode(code);
             console.log(JSON.stringify(result, null, 2));
             return;
         }
         case "me": {
             const client = new APAHttpClient({ apiBase });
-            const apiKey = requireArg("--api-key", readString(args, "api-key", "APA_API_KEY"));
+            const apiKey = await requireApiKey(apiBase);
             const result = await client.getAgentMe(apiKey);
             console.log(JSON.stringify(result, null, 2));
             return;
         }
         case "bind-key": {
             const client = new APAHttpClient({ apiBase });
-            const apiKey = requireArg("--api-key", readString(args, "api-key", "APA_API_KEY"));
+            const apiKey = await requireApiKey(apiBase);
             const provider = requireArg("--provider", readString(args, "provider"));
             const vendorKey = requireArg("--vendor-key", readString(args, "vendor-key"));
             const budgetUsd = readNumber(args, "budget-usd");

package/dist/http/client.d.ts

@@ -27,7 +27,7 @@ export declare class APAHttpClient {
         name: string;
         description: string;
     }): Promise<any>;
-    getAgentStatus(apiKey: string): Promise<any>;
+    claimByCode(claimCode: string): Promise<any>;
     getAgentMe(apiKey: string): Promise<any>;
     bindKey(input: {
         apiKey: string;

package/dist/http/client.js

@@ -39,10 +39,9 @@ export class APAHttpClient {
         });
         return parseJson(res);
     }
-    async getAgentStatus(apiKey) {
-        const res = await fetch(`${this.apiBase}/agents/status`, {
-            headers: { authorization: `Bearer ${apiKey}` }
-        });
+    async claimByCode(claimCode) {
+        const base = this.apiBase.replace(/\/api\/?$/, "");
+        const res = await fetch(`${base}/claim/${encodeURIComponent(claimCode)}`);
         return parseJson(res);
     }
     async getAgentMe(apiKey) {

package/dist/types/bot.d.ts

@@ -0,0 +1,43 @@
+import type { JoinMode, StateUpdateEvent } from "./messages.js";
+export type BotAction = {
+    action: "fold";
+} | {
+    action: "check";
+} | {
+    action: "call";
+} | {
+    action: "raise";
+    amount: number;
+} | {
+    action: "bet";
+    amount: number;
+};
+export type PlayContext = {
+    gameId: string;
+    handId: string;
+    mySeat: number;
+    currentActorSeat: number;
+    minRaise: number;
+    currentBet: number;
+    callAmount: number;
+    myBalance: number;
+    communityCards: string[];
+    holeCards: string[];
+    raw: StateUpdateEvent;
+};
+export type StrategyFn = (ctx: PlayContext) => BotAction | Promise<BotAction>;
+export type ReconnectOptions = {
+    enabled?: boolean;
+    baseMs?: number;
+    maxMs?: number;
+    jitter?: boolean;
+};
+export type CreateBotOptions = {
+    apiBase?: string;
+    wsUrl?: string;
+    agentId: string;
+    apiKey: string;
+    join: JoinMode;
+    reconnect?: ReconnectOptions;
+    actionTimeoutGuardMs?: number;
+};

package/dist/types/bot.js

@@ -0,0 +1 @@
+export {};

package/dist/types/messages.d.ts

@@ -0,0 +1,85 @@
+export type JoinMode = {
+    mode: "random";
+} | {
+    mode: "select";
+    roomId: string;
+};
+export type JoinMessage = {
+    type: "join";
+    agent_id: string;
+    api_key: string;
+    join_mode: "random" | "select";
+    room_id?: string;
+};
+export type ActionMessage = {
+    type: "action";
+    request_id: string;
+    action: "fold" | "check" | "call" | "raise" | "bet";
+    amount?: number;
+    thought_log?: string;
+};
+export type JoinResultEvent = {
+    type: "join_result";
+    protocol_version: string;
+    ok: boolean;
+    error?: string;
+    room_id?: string;
+};
+export type StateUpdateEvent = {
+    type: "state_update";
+    protocol_version: string;
+    game_id: string;
+    hand_id: string;
+    my_seat: number;
+    current_actor_seat: number;
+    min_raise: number;
+    current_bet: number;
+    call_amount: number;
+    my_balance: number;
+    action_timeout_ms: number;
+    street: string;
+    hole_cards?: string[];
+    community_cards: string[];
+    pot: number;
+    opponents: Array<{
+        seat: number;
+        name: string;
+        stack: number;
+        action: string;
+    }>;
+};
+export type ActionResultEvent = {
+    type: "action_result";
+    protocol_version: string;
+    request_id: string;
+    ok: boolean;
+    error?: string;
+};
+export type EventLogEvent = {
+    type: "event_log";
+    protocol_version: string;
+    timestamp_ms: number;
+    player_seat: number;
+    action: string;
+    amount?: number;
+    thought_log?: string;
+    event: string;
+};
+export type HandEndEvent = {
+    type: "hand_end";
+    protocol_version: string;
+    winner: string;
+    pot: number;
+    balances: Array<{
+        agent_id: string;
+        balance: number;
+    }>;
+    showdown?: Array<{
+        agent_id: string;
+        hole_cards: string[];
+    }>;
+};
+export type ServerEvent = JoinResultEvent | StateUpdateEvent | ActionResultEvent | EventLogEvent | HandEndEvent | {
+    type: string;
+    [k: string]: unknown;
+};

package/dist/types/messages.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/action.d.ts

@@ -0,0 +1,3 @@
+import type { BotAction } from "../types/bot.js";
+export declare function validateBotAction(action: BotAction): void;
+export declare function nextRequestId(): string;

package/dist/utils/action.js

@@ -0,0 +1,10 @@
+export function validateBotAction(action) {
+    if (action.action === "raise" || action.action === "bet") {
+        if (!Number.isFinite(action.amount) || action.amount <= 0) {
+            throw new Error(`${action.action} requires positive amount`);
+        }
+    }
+}
+export function nextRequestId() {
+    return `req_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
+}

package/dist/utils/action.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/action.test.js

@@ -0,0 +1,10 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validateBotAction } from "./action.js";
+test("validateBotAction accepts non-amount actions", () => {
+    validateBotAction({ action: "check" });
+    validateBotAction({ action: "fold" });
+});
+test("validateBotAction rejects invalid raise amount", () => {
+    assert.throws(() => validateBotAction({ action: "raise", amount: 0 }), /positive amount/);
+});

package/dist/utils/backoff.d.ts

@@ -0,0 +1,2 @@
+export declare function computeBackoffMs(attempt: number, baseMs: number, maxMs: number, jitter: boolean): number;
+export declare function sleep(ms: number): Promise<void>;

package/dist/utils/backoff.js

@@ -0,0 +1,11 @@
+export function computeBackoffMs(attempt, baseMs, maxMs, jitter) {
+    const exponential = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt - 1));
+    if (!jitter) {
+        return exponential;
+    }
+    const spread = Math.max(1, Math.floor(exponential * 0.2));
+    return exponential - spread + Math.floor(Math.random() * spread * 2);
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/utils/backoff.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/backoff.test.js

@@ -0,0 +1,8 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { computeBackoffMs } from "./backoff.js";
+test("computeBackoffMs grows exponentially without jitter", () => {
+    assert.equal(computeBackoffMs(1, 500, 8000, false), 500);
+    assert.equal(computeBackoffMs(2, 500, 8000, false), 1000);
+    assert.equal(computeBackoffMs(5, 500, 8000, false), 8000);
+});

package/dist/ws/client.d.ts

@@ -0,0 +1,38 @@
+import { EventEmitter } from "node:events";
+import type { ActionMessage, JoinMode } from "../types/messages.js";
+type WsOptions = {
+    apiBase?: string;
+    wsUrl?: string;
+    agentId: string;
+    apiKey: string;
+    join: JoinMode;
+    reconnect?: {
+        enabled?: boolean;
+        baseMs?: number;
+        maxMs?: number;
+        jitter?: boolean;
+    };
+};
+export declare class APAWsClient extends EventEmitter {
+    private readonly apiBase;
+    private readonly agentId;
+    private readonly apiKey;
+    private readonly join;
+    private readonly reconnect;
+    private shouldRun;
+    private connectAttempt;
+    private sessionId;
+    private tableId;
+    private roomId;
+    private turnId;
+    private streamAbort;
+    constructor(opts: WsOptions);
+    connect(): Promise<void>;
+    stop(): Promise<void>;
+    sendAction(action: ActionMessage): Promise<void>;
+    private openSessionAndStream;
+    private readEventStream;
+    private handleEnvelope;
+    private reconnectLoop;
+}
+export {};

package/dist/ws/client.js

@@ -0,0 +1,274 @@
+import { EventEmitter } from "node:events";
+import { computeBackoffMs, sleep } from "../utils/backoff.js";
+import { resolveApiBase } from "../utils/config.js";
+const DEFAULT_RECONNECT = {
+    enabled: true,
+    baseMs: 500,
+    maxMs: 8000,
+    jitter: true
+};
+function apiOrigin(apiBase) {
+    return apiBase.replace(/\/api\/?$/, "");
+}
+export class APAWsClient extends EventEmitter {
+    apiBase;
+    agentId;
+    apiKey;
+    join;
+    reconnect;
+    shouldRun = true;
+    connectAttempt = 0;
+    sessionId = "";
+    tableId = "";
+    roomId = "";
+    turnId = "";
+    streamAbort = null;
+    constructor(opts) {
+        super();
+        this.apiBase = resolveApiBase(opts.apiBase);
+        this.agentId = opts.agentId;
+        this.apiKey = opts.apiKey;
+        this.join = opts.join;
+        this.reconnect = {
+            enabled: opts.reconnect?.enabled ?? DEFAULT_RECONNECT.enabled,
+            baseMs: opts.reconnect?.baseMs ?? DEFAULT_RECONNECT.baseMs,
+            maxMs: opts.reconnect?.maxMs ?? DEFAULT_RECONNECT.maxMs,
+            jitter: opts.reconnect?.jitter ?? DEFAULT_RECONNECT.jitter
+        };
+    }
+    async connect() {
+        this.shouldRun = true;
+        await this.openSessionAndStream();
+    }
+    async stop() {
+        this.shouldRun = false;
+        if (this.streamAbort) {
+            this.streamAbort.abort();
+            this.streamAbort = null;
+        }
+        if (this.sessionId) {
+            try {
+                await fetch(`${this.apiBase}/agent/sessions/${this.sessionId}`, { method: "DELETE" });
+            }
+            catch {
+                // ignore best-effort close
+            }
+        }
+    }
+    async sendAction(action) {
+        if (!this.sessionId) {
+            throw new Error("session not created");
+        }
+        if (!this.turnId) {
+            throw new Error("turn_id unavailable");
+        }
+        const res = await fetch(`${this.apiBase}/agent/sessions/${this.sessionId}/actions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                request_id: action.request_id,
+                turn_id: this.turnId,
+                action: action.action,
+                amount: action.amount,
+                thought_log: action.thought_log
+            })
+        });
+        const payload = await res.json().catch(() => ({}));
+        const evt = {
+            type: "action_result",
+            protocol_version: "",
+            request_id: action.request_id,
+            ok: res.ok && payload.accepted !== false,
+            error: payload.reason
+        };
+        this.emit("action_result", evt);
+    }
+    async openSessionAndStream() {
+        const createRes = await fetch(`${this.apiBase}/agent/sessions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                agent_id: this.agentId,
+                api_key: this.apiKey,
+                join_mode: this.join.mode,
+                room_id: this.join.mode === "select" ? this.join.roomId : undefined
+            })
+        });
+        if (!createRes.ok) {
+            throw new Error(`create session failed (${createRes.status})`);
+        }
+        const created = await createRes.json();
+        this.sessionId = created.session_id;
+        this.tableId = created.table_id || "";
+        this.roomId = created.room_id || "";
+        this.connectAttempt = 0;
+        this.emit("connected");
+        this.emit("join_result", {
+            type: "join_result",
+            protocol_version: "",
+            ok: true,
+            room_id: this.roomId
+        });
+        await this.readEventStream(created.stream_url);
+    }
+    async readEventStream(streamPath) {
+        const origin = apiOrigin(this.apiBase);
+        const url = streamPath.startsWith("http") ? streamPath : `${origin}${streamPath}`;
+        this.streamAbort = new AbortController();
+        try {
+            const res = await fetch(url, {
+                method: "GET",
+                headers: { accept: "text/event-stream" },
+                signal: this.streamAbort.signal
+            });
+            if (!res.ok || !res.body) {
+                throw new Error(`stream open failed (${res.status})`);
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            let currentData = "";
+            while (this.shouldRun) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const rawLine of lines) {
+                    const line = rawLine.trimEnd();
+                    if (line.startsWith("data: ")) {
+                        currentData = line.slice(6);
+                        continue;
+                    }
+                    if (line === "") {
+                        if (!currentData) {
+                            continue;
+                        }
+                        this.handleEnvelope(currentData);
+                        currentData = "";
+                    }
+                }
+            }
+            this.emit("disconnected");
+            if (this.shouldRun && this.reconnect.enabled) {
+                await this.reconnectLoop();
+            }
+        }
+        catch (err) {
+            if (!this.shouldRun) {
+                return;
+            }
+            this.emit("error", err);
+            if (this.reconnect.enabled) {
+                await this.reconnectLoop();
+            }
+        }
+    }
+    handleEnvelope(payloadText) {
+        let envelope;
+        try {
+            envelope = JSON.parse(payloadText);
+        }
+        catch (err) {
+            this.emit("error", err);
+            return;
+        }
+        const evt = envelope?.event;
+        const data = envelope?.data || {};
+        if (evt === "turn_started") {
+            this.turnId = data.turn_id || "";
+            return;
+        }
+        if (evt === "state_snapshot") {
+            this.turnId = data.turn_id || this.turnId;
+            const seats = Array.isArray(data.seats) ? data.seats : [];
+            const me = seats.find((s) => s.seat_id === data.my_seat) || {};
+            const currentBet = seats.reduce((m, s) => Math.max(m, Number(s.street_contribution || 0)), 0);
+            const serverEvt = {
+                type: "state_update",
+                protocol_version: "",
+                game_id: this.tableId,
+                hand_id: data.hand_id || "",
+                my_seat: data.my_seat ?? 0,
+                current_actor_seat: data.current_actor_seat ?? 0,
+                min_raise: 0,
+                current_bet: currentBet,
+                call_amount: Number(me.to_call || 0),
+                my_balance: Number(data.my_balance || 0),
+                action_timeout_ms: Number(data.action_timeout_ms || 5000),
+                street: data.street || "preflop",
+                hole_cards: data.my_hole_cards || [],
+                community_cards: data.community_cards || [],
+                pot: Number(data.pot || 0),
+                opponents: seats
+                    .filter((s) => s.seat_id !== data.my_seat)
+                    .map((s) => ({
+                    seat: Number(s.seat_id),
+                    name: String(s.agent_id || ""),
+                    stack: Number(s.stack || 0),
+                    action: String(s.last_action || "")
+                }))
+            };
+            this.emit("event", serverEvt);
+            this.emit("state_update", serverEvt);
+            return;
+        }
+        if (evt === "action_accepted") {
+            const serverEvt = {
+                type: "action_result",
+                protocol_version: "",
+                request_id: data.request_id || "",
+                ok: true
+            };
+            this.emit("event", serverEvt);
+            this.emit("action_result", serverEvt);
+            return;
+        }
+        if (evt === "action_rejected") {
+            const serverEvt = {
+                type: "action_result",
+                protocol_version: "",
+                request_id: data.request_id || "",
+                ok: false,
+                error: data.reason || "invalid_action"
+            };
+            this.emit("event", serverEvt);
+            this.emit("action_result", serverEvt);
+            return;
+        }
+        if (evt === "hand_end") {
+            const serverEvt = {
+                type: "hand_end",
+                protocol_version: "",
+                winner: data.winner || "",
+                pot: Number(data.pot || 0),
+                balances: data.balances || [],
+                showdown: data.showdown || []
+            };
+            this.emit("event", serverEvt);
+            this.emit("hand_end", serverEvt);
+            return;
+        }
+        if (evt === "session_closed") {
+            this.emit("disconnected");
+            return;
+        }
+    }
+    async reconnectLoop() {
+        while (this.shouldRun) {
+            this.connectAttempt += 1;
+            const waitMs = computeBackoffMs(this.connectAttempt, this.reconnect.baseMs, this.reconnect.maxMs, this.reconnect.jitter);
+            this.emit("reconnect", { attempt: this.connectAttempt, waitMs });
+            await sleep(waitMs);
+            try {
+                await this.openSessionAndStream();
+                return;
+            }
+            catch (err) {
+                this.emit("error", err);
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apa-network/agent-sdk",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.4",
   "description": "APA Agent SDK and CLI",
   "type": "module",
   "bin": {
@@ -29,4 +29,4 @@
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2"
   }
-}
+}