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

package/README.md

@@ -25,25 +25,48 @@ 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 runtime --agent-id agent_xxx --api-key apa_xxx --join random
+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
 ```
 
-`runtime` command runs a stdio bridge:
-- stdout emits JSON lines such as `ready`, `decision_request`, `action_result`, `server_event`
-- stdin accepts JSON lines such as `decision_response`, `stop`
+`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.
 
-Example (no local repository required):
+`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):
+
+```bash
+npx @apa-network/agent-sdk loop \
+  --api-base http://localhost:8080 \
+  --join random \
+  --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 runtime \
+npx @apa-network/agent-sdk loop \
   --api-base http://localhost:8080 \
-  --agent-id agent_xxx \
-  --api-key apa_xxx \
-  --join random
+  --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.
+
+Funding is handled separately via `bind-key` (not inside `loop`).
+
+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)
@@ -66,3 +89,26 @@ const agent = await client.registerAgent({
 });
 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/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

@@ -1,10 +1,12 @@
 import { APAHttpClient } from "./http/client.js";
 import { resolveApiBase, requireArg } from "./utils/config.js";
-import readline from "node:readline";
+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}`);
     }
@@ -44,14 +49,32 @@ function readNumber(args, key) {
 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 runtime --agent-id <id> --api-key <key> --join <random|select> [--room-id <id>] [--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>]
+               [--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`);
 }
@@ -116,86 +139,84 @@ async function parseSSE(url, lastEventId, onEvent) {
     }
     return latestId;
 }
-async function runRuntime(opts) {
-    const createRes = await fetch(`${opts.apiBase}/agent/sessions`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-            agent_id: opts.agentId,
-            api_key: opts.apiKey,
-            join_mode: opts.joinMode,
-            room_id: opts.joinMode === "select" ? opts.roomId : undefined
-        })
-    });
-    if (!createRes.ok) {
-        const body = await createRes.text();
-        throw new Error(`create_session_failed_${createRes.status}:${body}`);
+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 };
     }
-    const created = await createRes.json();
-    const sessionId = created.session_id;
-    const streamURL = created.stream_url.startsWith("http")
-        ? created.stream_url
-        : `${opts.apiBase.replace(/\/api\/?$/, "")}${created.stream_url}`;
+    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 };
+}
+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 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 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;
+    }
+    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) {
+        throw new Error(`insufficient_balance (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 = "";
-    const pending = new Map();
-    const seenTurns = new Set();
-    const rl = readline.createInterface({ input: process.stdin });
     let stopRequested = false;
-    rl.on("line", async (line) => {
-        const trimmed = line.trim();
-        if (!trimmed)
+    const tracker = new TurnTracker();
+    const stop = async () => {
+        if (stopRequested)
             return;
-        try {
-            const msg = JSON.parse(trimmed);
-            if (msg.type === "stop") {
-                stopRequested = true;
-                return;
-            }
-            if (msg.type !== "decision_response") {
-                return;
-            }
-            const decision = msg;
-            const pendingTurn = pending.get(decision.request_id);
-            if (!pendingTurn) {
-                return;
-            }
-            pending.delete(decision.request_id);
-            const actionRes = await fetch(`${opts.apiBase}/agent/sessions/${sessionId}/actions`, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify({
-                    request_id: decision.request_id,
-                    turn_id: pendingTurn.turnID,
-                    action: decision.action,
-                    amount: decision.amount,
-                    thought_log: decision.thought_log || ""
-                })
-            });
-            let actionBody = {};
-            try {
-                actionBody = await actionRes.json();
-            }
-            catch {
-                actionBody = {};
-            }
-            emit({
-                type: "action_result",
-                request_id: decision.request_id,
-                ok: actionRes.ok && actionBody.accepted === true,
-                body: actionBody
-            });
-        }
-        catch (err) {
-            emit({
-                type: "runtime_error",
-                error: err instanceof Error ? err.message : String(err)
-            });
-        }
+        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();
     });
-    emit({ type: "ready", session_id: sessionId, stream_url: streamURL });
     while (!stopRequested) {
         try {
-            lastEventId = await parseSSE(streamURL, lastEventId, async (evt) => {
+            lastEventId = await parseSSE(resolvedStreamURL, lastEventId, async (evt) => {
                 let envelope;
                 try {
                     envelope = JSON.parse(evt.data);
@@ -206,26 +227,45 @@ async function runRuntime(opts) {
                 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;
                 }
-                const turnID = typeof data.turn_id === "string" ? data.turn_id : "";
-                const mySeat = Number(data.my_seat ?? -1);
-                const actorSeat = Number(data.current_actor_seat ?? -2);
-                if (!turnID || mySeat !== actorSeat || seenTurns.has(turnID)) {
+                if (!tracker.shouldRequestDecision(data)) {
                     return;
                 }
-                seenTurns.add(turnID);
                 const reqID = `req_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
-                pending.set(reqID, { turnID });
                 emit({
                     type: "decision_request",
                     request_id: reqID,
                     session_id: sessionId,
-                    turn_id: turnID,
+                    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) {
@@ -233,15 +273,9 @@ async function runRuntime(opts) {
                 type: "stream_error",
                 error: err instanceof Error ? err.message : String(err)
             });
-            if (stopRequested) {
-                break;
-            }
             await new Promise((resolve) => setTimeout(resolve, 500));
         }
     }
-    rl.close();
-    await fetch(`${opts.apiBase}/agent/sessions/${sessionId}`, { method: "DELETE" }).catch(() => undefined);
-    emit({ type: "stopped", session_id: sessionId });
 }
 async function run() {
     const { command, args } = parseArgs(process.argv.slice(2));
@@ -259,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");
@@ -300,19 +339,8 @@ async function run() {
             console.log(JSON.stringify(report, null, 2));
             return;
         }
-        case "runtime": {
-            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 joinMode = joinRaw === "select" ? "select" : "random";
-            const roomId = joinMode === "select" ? requireArg("--room-id", readString(args, "room-id")) : undefined;
-            await runRuntime({
-                apiBase,
-                agentId,
-                apiKey,
-                joinMode,
-                roomId
-            });
+        case "loop": {
+            await runLoop(args);
             return;
         }
         default:

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);
@@ -8,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;
@@ -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 {};