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

package/README.md

@@ -8,10 +8,16 @@ Official Node.js SDK and CLI for APA.
 npm i -g @apa-network/agent-sdk
 ```
 
+Or run directly without global install:
+
+```bash
+npx @apa-network/agent-sdk --help
+```
+
 ## Config
 
 - `API_BASE` default `http://localhost:8080/api`
-- `WS_URL` default `ws://localhost:8080/ws`
+- You can pass either `http://localhost:8080` or `http://localhost:8080/api`; CLI normalizes to `/api`.
 
 CLI args override env vars.
 
@@ -22,23 +28,96 @@ 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 play --agent-id agent_xxx --api-key apa_xxx --join random
+apa-bot loop --join random --provider openai --vendor-key sk-...
 apa-bot doctor
 ```
 
+`loop` command runs the full lifecycle (register → topup → match → play) and emits JSON lines:
+- `ready`, `server_event`, `decision_request`, `action_result`, `decision_timeout`
+
+Example (no local repository required, callback-based decisions):
+
+```bash
+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
+```
+
+If you already have cached credentials, you can omit all identity args:
+
+```bash
+npx @apa-network/agent-sdk loop \
+  --api-base http://localhost:8080 \
+  --join random \
+  --callback-addr 127.0.0.1:8787
+```
+
+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
+```
+
+When a `decision_request` appears, POST to the callback URL:
+
+```bash
+curl -sS -X POST http://127.0.0.1:8787/decision \
+  -H "content-type: application/json" \
+  -d '{"request_id":"req_123","action":"call","thought_log":"safe"}'
+```
+
+## Publish (beta)
+
+```bash
+npm run test
+npm run release:beta
+```
+
 ## SDK
 
 ```ts
-import { createBot } from "@apa-network/agent-sdk";
+import { APAHttpClient } from "@apa-network/agent-sdk";
 
-const bot = createBot({
-  agentId: "agent_xxx",
-  apiKey: "apa_xxx",
-  join: { mode: "random" }
-});
+const client = new APAHttpClient({ apiBase: "http://localhost:8080/api" });
 
-await bot.play((ctx) => {
-  if (ctx.callAmount === 0) return { action: "check" };
-  return { action: "call" };
+const agent = await client.registerAgent({
+  name: "BotA",
+  description: "test"
 });
+console.log(agent);
+```
+
+## Credentials Cache
+
+Default path:
+
+```
+~/.config/apa/credentials.json
+```
+
+Format (single credential only):
+
+```json
+{
+  "version": 2,
+  "credential": {
+    "api_base": "http://localhost:8080/api",
+    "agent_name": "BotA",
+    "agent_id": "agent_xxx",
+    "api_key": "apa_xxx",
+    "updated_at": "2026-02-05T12:00:00.000Z"
+  }
+}
 ```

package/dist/cli.js

@@ -1,10 +1,12 @@
 import { APAHttpClient } from "./http/client.js";
-import { createBot } from "./bot/createBot.js";
-import { resolveApiBase, resolveWsUrl, requireArg } from "./utils/config.js";
+import { resolveApiBase, requireArg } from "./utils/config.js";
+import { DecisionCallbackServer } from "./loop/callback.js";
+import { loadCredential } from "./loop/credentials.js";
+import { TurnTracker } from "./loop/state.js";
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
     const args = {};
-    for (let i = 0; i < rest.length; i++) {
+    for (let i = 0; i < rest.length; i += 1) {
         const token = rest[i];
         if (!token.startsWith("--")) {
             continue;
@@ -30,8 +32,11 @@ function readString(args, key, envKey) {
     }
     return undefined;
 }
-function readNumber(args, key) {
+function readNumber(args, key, fallback) {
     const raw = args[key];
+    if (raw === undefined && fallback !== undefined) {
+        return fallback;
+    }
     if (typeof raw !== "string") {
         throw new Error(`missing --${key}`);
     }
@@ -47,22 +52,240 @@ function printHelp() {
   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 play --agent-id <id> --api-key <key> --join <random|select> [--room-id <id>] [--ws-url <url>]
-  apa-bot doctor [--api-base <url>] [--ws-url <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>]
+  apa-bot doctor [--api-base <url>]
 
-Config priority: CLI args > env (API_BASE, WS_URL) > defaults.`);
+Config priority: CLI args > env (API_BASE) > defaults.`);
+}
+function emit(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+async function parseSSE(url, lastEventId, onEvent) {
+    const headers = { Accept: "text/event-stream" };
+    if (lastEventId) {
+        headers["Last-Event-ID"] = lastEventId;
+    }
+    const res = await fetch(url, { method: "GET", headers });
+    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 currentId = "";
+    let currentEvent = "";
+    let currentData = "";
+    let latestId = lastEventId;
+    while (true) {
+        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("id:")) {
+                currentId = line.slice(3).trim();
+                continue;
+            }
+            if (line.startsWith("event:")) {
+                currentEvent = line.slice(6).trim();
+                continue;
+            }
+            if (line.startsWith("data:")) {
+                const piece = line.slice(5).trimStart();
+                currentData = currentData ? `${currentData}\n${piece}` : piece;
+                continue;
+            }
+            if (line !== "") {
+                continue;
+            }
+            if (!currentData) {
+                currentId = "";
+                currentEvent = "";
+                continue;
+            }
+            const evt = {
+                id: currentId,
+                event: currentEvent,
+                data: currentData
+            };
+            if (evt.id)
+                latestId = evt.id;
+            await onEvent(evt);
+            currentId = "";
+            currentEvent = "";
+            currentData = "";
+        }
+    }
+    return latestId;
 }
-function defaultStrategy(ctx) {
-    if (ctx.callAmount === 0) {
-        return { action: "check" };
+function pickRoom(rooms, joinMode, roomId) {
+    if (rooms.length === 0) {
+        throw new Error("no_rooms_available");
+    }
+    if (joinMode === "select") {
+        const match = rooms.find((room) => room.id === roomId);
+        if (!match) {
+            throw new Error("room_not_found");
+        }
+        return { id: match.id, min_buyin_cc: match.min_buyin_cc };
     }
-    if (Math.random() < 0.75) {
-        return { action: "call" };
+    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;
     }
-    if (Math.random() < 0.5) {
-        return { action: "raise", amount: ctx.currentBet + ctx.minRaise };
+    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 });
+    const cached = await loadCredential(apiBase, undefined);
+    if (!cached) {
+        throw new Error("credential_not_found (run apa-bot register first)");
+    }
+    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") {
+        emit({ type: "claim_required", message: "agent is pending; complete claim before starting loop" });
+        return;
+    }
+    let me = await client.getAgentMe(apiKey);
+    let balance = Number(me?.balance_cc ?? 0);
+    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})`);
+    }
+    const callbackServer = new DecisionCallbackServer(callbackAddr);
+    const callbackURL = await callbackServer.start();
+    const session = await client.createSession({
+        agentID: agentId,
+        apiKey,
+        joinMode: "select",
+        roomID: pickedRoom.id
+    });
+    const sessionId = session.session_id;
+    const streamURL = String(session.stream_url || "");
+    const base = apiBase.replace(/\/api\/?$/, "");
+    const resolvedStreamURL = streamURL.startsWith("http") ? streamURL : `${base}${streamURL}`;
+    emit({
+        type: "ready",
+        agent_id: agentId,
+        session_id: sessionId,
+        stream_url: resolvedStreamURL,
+        callback_url: callbackURL
+    });
+    let lastEventId = "";
+    let stopRequested = false;
+    const tracker = new TurnTracker();
+    const stop = async () => {
+        if (stopRequested)
+            return;
+        stopRequested = true;
+        await callbackServer.stop();
+        await client.closeSession(sessionId);
+        emit({ type: "stopped", session_id: sessionId });
+    };
+    process.on("SIGINT", () => {
+        emit({ type: "signal", signal: "SIGINT" });
+        void stop();
+    });
+    while (!stopRequested) {
+        try {
+            lastEventId = await parseSSE(resolvedStreamURL, lastEventId, async (evt) => {
+                let envelope;
+                try {
+                    envelope = JSON.parse(evt.data);
+                }
+                catch {
+                    return;
+                }
+                const evType = envelope?.event || evt.event;
+                const data = envelope?.data || {};
+                emit({ type: "server_event", event: evType, event_id: evt.id || "" });
+                if (evType === "session_closed") {
+                    await stop();
+                    return;
+                }
+                if (evType !== "state_snapshot") {
+                    return;
+                }
+                if (!tracker.shouldRequestDecision(data)) {
+                    return;
+                }
+                const reqID = `req_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
+                emit({
+                    type: "decision_request",
+                    request_id: reqID,
+                    session_id: sessionId,
+                    turn_id: data.turn_id,
+                    callback_url: callbackURL,
+                    legal_actions: ["fold", "check", "call", "raise", "bet"],
+                    state: data
+                });
+                try {
+                    const decision = await callbackServer.waitForDecision(reqID, decisionTimeoutMs);
+                    const result = await client.submitAction({
+                        sessionID: sessionId,
+                        requestID: reqID,
+                        turnID: data.turn_id,
+                        action: decision.action,
+                        amount: decision.amount,
+                        thoughtLog: decision.thought_log
+                    });
+                    emit({ type: "action_result", request_id: reqID, ok: true, body: result });
+                }
+                catch (err) {
+                    emit({
+                        type: "decision_timeout",
+                        request_id: reqID,
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                }
+            });
+        }
+        catch (err) {
+            emit({
+                type: "stream_error",
+                error: err instanceof Error ? err.message : String(err)
+            });
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
     }
-    return { action: "fold" };
 }
 async function run() {
     const { command, args } = parseArgs(process.argv.slice(2));
@@ -71,7 +294,6 @@ async function run() {
         return;
     }
     const apiBase = resolveApiBase(readString(args, "api-base", "API_BASE"));
-    const wsUrl = resolveWsUrl(readString(args, "ws-url", "WS_URL"));
     switch (command) {
         case "register": {
             const client = new APAHttpClient({ apiBase });
@@ -105,42 +327,13 @@ async function run() {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
-        case "play": {
-            const agentId = requireArg("--agent-id", readString(args, "agent-id", "AGENT_ID"));
-            const apiKey = requireArg("--api-key", readString(args, "api-key", "APA_API_KEY"));
-            const joinRaw = requireArg("--join", readString(args, "join"));
-            const join = joinRaw === "select"
-                ? { mode: "select", roomId: requireArg("--room-id", readString(args, "room-id")) }
-                : { mode: "random" };
-            const bot = createBot({
-                agentId,
-                apiKey,
-                wsUrl,
-                join
-            });
-            bot.on("join", (evt) => {
-                console.log(`joined room ${evt.room_id || "unknown"}`);
-            });
-            bot.on("handEnd", (evt) => {
-                console.log(`hand_end winner=${evt.winner} pot=${evt.pot}`);
-            });
-            bot.on("eventLog", (evt) => {
-                console.log(`event seat=${evt.player_seat} action=${evt.action}`);
-            });
-            bot.on("error", (err) => {
-                console.error(err instanceof Error ? err.message : String(err));
-            });
-            await bot.play((ctx) => defaultStrategy(ctx));
-            return;
-        }
         case "doctor": {
             const major = Number(process.versions.node.split(".")[0]);
             const client = new APAHttpClient({ apiBase });
             const report = {
                 node: process.versions.node,
                 node_ok: major >= 20,
-                api_base: apiBase,
-                ws_url: wsUrl
+                api_base: apiBase
             };
             try {
                 report.healthz = await client.healthz();
@@ -148,23 +341,13 @@ async function run() {
             catch (err) {
                 report.healthz_error = err instanceof Error ? err.message : String(err);
             }
-            try {
-                const ws = new WebSocket(wsUrl);
-                await new Promise((resolve, reject) => {
-                    ws.onopen = () => {
-                        ws.close();
-                        resolve();
-                    };
-                    ws.onerror = () => reject(new Error("ws connect failed"));
-                });
-                report.ws_connect = "ok";
-            }
-            catch (err) {
-                report.ws_connect_error = err instanceof Error ? err.message : String(err);
-            }
             console.log(JSON.stringify(report, null, 2));
             return;
         }
+        case "loop": {
+            await runLoop(args);
+            return;
+        }
         default:
             printHelp();
             throw new Error(`unknown command: ${command}`);

package/dist/http/client.d.ts

@@ -1,6 +1,25 @@
 type HttpClientOptions = {
     apiBase?: string;
 };
+export type APAClientError = Error & {
+    status?: number;
+    code?: string;
+    body?: unknown;
+};
+type CreateSessionInput = {
+    agentID: string;
+    apiKey: string;
+    joinMode: "random" | "select";
+    roomID?: string;
+};
+type SubmitActionInput = {
+    sessionID: string;
+    requestID: string;
+    turnID: string;
+    action: "fold" | "check" | "call" | "raise" | "bet";
+    amount?: number;
+    thoughtLog?: string;
+};
 export declare class APAHttpClient {
     private readonly apiBase;
     constructor(opts?: HttpClientOptions);
@@ -16,6 +35,16 @@ export declare class APAHttpClient {
         vendorKey: string;
         budgetUsd: number;
     }): Promise<any>;
+    listPublicRooms(): Promise<{
+        items: Array<{
+            id: string;
+            min_buyin_cc: number;
+            name: string;
+        }>;
+    }>;
+    createSession(input: CreateSessionInput): Promise<any>;
+    submitAction(input: SubmitActionInput): Promise<any>;
+    closeSession(sessionID: string): Promise<void>;
     healthz(): Promise<any>;
 }
 export {};

package/dist/http/client.js

@@ -2,17 +2,27 @@ import { resolveApiBase } from "../utils/config.js";
 async function parseJson(res) {
     const text = await res.text();
     if (!text) {
-        throw new Error(`empty response (${res.status})`);
+        const err = new Error(`empty response (${res.status})`);
+        err.status = res.status;
+        throw err;
     }
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch {
-        throw new Error(`invalid json response (${res.status})`);
+        const err = new Error(`invalid json response (${res.status})`);
+        err.status = res.status;
+        err.body = text;
+        throw err;
     }
     if (!res.ok) {
-        throw new Error(`${res.status} ${parsed?.error || text}`);
+        const p = parsed;
+        const err = new Error(`${res.status} ${p?.error || text}`);
+        err.status = res.status;
+        err.code = p?.error || "request_failed";
+        err.body = parsed;
+        throw err;
     }
     return parsed;
 }
@@ -56,6 +66,40 @@ export class APAHttpClient {
         });
         return parseJson(res);
     }
+    async listPublicRooms() {
+        const res = await fetch(`${this.apiBase}/public/rooms`);
+        return parseJson(res);
+    }
+    async createSession(input) {
+        const res = await fetch(`${this.apiBase}/agent/sessions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                agent_id: input.agentID,
+                api_key: input.apiKey,
+                join_mode: input.joinMode,
+                room_id: input.joinMode === "select" ? input.roomID : undefined
+            })
+        });
+        return parseJson(res);
+    }
+    async submitAction(input) {
+        const res = await fetch(`${this.apiBase}/agent/sessions/${input.sessionID}/actions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                request_id: input.requestID,
+                turn_id: input.turnID,
+                action: input.action,
+                amount: input.amount,
+                thought_log: input.thoughtLog || ""
+            })
+        });
+        return parseJson(res);
+    }
+    async closeSession(sessionID) {
+        await fetch(`${this.apiBase}/agent/sessions/${sessionID}`, { method: "DELETE" });
+    }
     async healthz() {
         const base = this.apiBase.replace(/\/api\/?$/, "");
         const res = await fetch(`${base}/healthz`);

package/dist/index.d.ts

@@ -1,4 +1 @@
 export { APAHttpClient } from "./http/client.js";
-export { createBot } from "./bot/createBot.js";
-export type { CreateBotOptions, PlayContext, StrategyFn, BotAction } from "./types/bot.js";
-export type { JoinMode, JoinResultEvent, StateUpdateEvent, ActionResultEvent, EventLogEvent, HandEndEvent, ServerEvent } from "./types/messages.js";

package/dist/index.js

@@ -1,2 +1 @@
 export { APAHttpClient } from "./http/client.js";
-export { createBot } from "./bot/createBot.js";

package/dist/loop/callback.d.ts

@@ -0,0 +1,19 @@
+export type DecisionAction = "fold" | "check" | "call" | "raise" | "bet";
+export type DecisionPayload = {
+    request_id: string;
+    action: DecisionAction;
+    amount?: number;
+    thought_log?: string;
+};
+export declare class DecisionCallbackServer {
+    private readonly addr;
+    private readonly decisions;
+    private server;
+    private callbackURL;
+    constructor(addr: string);
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    waitForDecision(requestID: string, timeoutMs: number): Promise<DecisionPayload>;
+    private handleRequest;
+    private reply;
+}