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

package/README.md

@@ -28,22 +28,54 @@ 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 loop --join random --provider openai --vendor-key sk-...
 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`
+`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):
+Example (no local repository required, callback-based decisions):
 
 ```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 \
+  --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)
@@ -66,3 +98,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/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}`);
     }
@@ -47,7 +52,9 @@ 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 runtime --agent-id <id> --api-key <key> --join <random|select> [--room-id <id>] [--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>]
   apa-bot doctor [--api-base <url>]
 
 Config priority: CLI args > env (API_BASE) > defaults.`);
@@ -116,86 +123,110 @@ 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 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 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 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 = "";
-    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 +237,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 +283,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));
@@ -300,19 +344,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);
@@ -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/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;
+}

package/dist/loop/callback.js

@@ -0,0 +1,94 @@
+import http from "node:http";
+import { URL } from "node:url";
+export class DecisionCallbackServer {
+    addr;
+    decisions = new Map();
+    server = null;
+    callbackURL = "";
+    constructor(addr) {
+        this.addr = addr;
+    }
+    async start() {
+        if (this.server) {
+            return this.callbackURL;
+        }
+        const [host, portRaw] = this.addr.split(":");
+        const port = Number(portRaw);
+        if (!host || !Number.isFinite(port) || port <= 0) {
+            throw new Error(`invalid callback addr: ${this.addr}`);
+        }
+        this.server = http.createServer(this.handleRequest.bind(this));
+        await new Promise((resolve, reject) => {
+            this.server?.once("error", reject);
+            this.server?.listen(port, host, () => resolve());
+        });
+        this.callbackURL = `http://${host}:${port}/decision`;
+        return this.callbackURL;
+    }
+    async stop() {
+        const entries = [...this.decisions.values()];
+        this.decisions.clear();
+        for (const pending of entries) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error("callback_server_stopped"));
+        }
+        if (!this.server) {
+            return;
+        }
+        const s = this.server;
+        this.server = null;
+        await new Promise((resolve) => s.close(() => resolve()));
+    }
+    waitForDecision(requestID, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.decisions.delete(requestID);
+                reject(new Error("decision_timeout"));
+            }, timeoutMs);
+            this.decisions.set(requestID, { resolve, reject, timeout });
+        });
+    }
+    async handleRequest(req, res) {
+        const method = req.method || "";
+        const url = new URL(req.url || "/", "http://localhost");
+        if (method === "GET" && url.pathname === "/healthz") {
+            this.reply(res, 200, { ok: true });
+            return;
+        }
+        if (method !== "POST" || url.pathname !== "/decision") {
+            this.reply(res, 404, { error: "not_found" });
+            return;
+        }
+        let body = "";
+        req.setEncoding("utf8");
+        for await (const chunk of req) {
+            body += chunk;
+        }
+        let payload = null;
+        try {
+            payload = JSON.parse(body);
+        }
+        catch {
+            this.reply(res, 400, { error: "invalid_json" });
+            return;
+        }
+        if (!payload || typeof payload.request_id !== "string" || typeof payload.action !== "string") {
+            this.reply(res, 400, { error: "invalid_payload" });
+            return;
+        }
+        const pending = this.decisions.get(payload.request_id);
+        if (!pending) {
+            this.reply(res, 409, { error: "request_not_pending" });
+            return;
+        }
+        this.decisions.delete(payload.request_id);
+        clearTimeout(pending.timeout);
+        pending.resolve(payload);
+        this.reply(res, 200, { ok: true });
+    }
+    reply(res, status, payload) {
+        res.statusCode = status;
+        res.setHeader("content-type", "application/json");
+        res.end(`${JSON.stringify(payload)}\n`);
+    }
+}

package/dist/loop/callback.test.d.ts

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

package/dist/loop/callback.test.js

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { DecisionCallbackServer } from "./callback.js";
+test("callback server receives decision and resolves pending request", async (t) => {
+    const server = new DecisionCallbackServer("127.0.0.1:18787");
+    let callbackURL = "";
+    try {
+        callbackURL = await server.start();
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : "";
+        if (code === "EPERM" || code === "EACCES") {
+            t.skip("listen not permitted in this environment");
+            return;
+        }
+        throw err;
+    }
+    const decisionPromise = server.waitForDecision("req_1", 2000);
+    const res = await fetch(callbackURL, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            request_id: "req_1",
+            action: "call",
+            thought_log: "ok"
+        })
+    });
+    assert.equal(res.status, 200);
+    const decision = await decisionPromise;
+    assert.equal(decision.request_id, "req_1");
+    assert.equal(decision.action, "call");
+    await server.stop();
+});

package/dist/loop/credentials.d.ts

@@ -0,0 +1,10 @@
+export type AgentCredential = {
+    api_base: string;
+    agent_name: string;
+    agent_id: string;
+    api_key: string;
+    updated_at: string;
+};
+export declare function defaultCredentialPath(): string;
+export declare function loadCredential(apiBase: string, _agentName: string | undefined, filePath?: string): Promise<AgentCredential | null>;
+export declare function saveCredential(record: Omit<AgentCredential, "updated_at">, filePath?: string): Promise<void>;

package/dist/loop/credentials.js

@@ -0,0 +1,61 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const STORE_VERSION = 2;
+export function defaultCredentialPath() {
+    return path.join(os.homedir(), ".config", "apa", "credentials.json");
+}
+export async function loadCredential(apiBase, _agentName, filePath = defaultCredentialPath()) {
+    const store = await readStore(filePath);
+    if (!store.credential) {
+        return null;
+    }
+    if (store.credential.api_base !== apiBase) {
+        return null;
+    }
+    return store.credential;
+}
+export async function saveCredential(record, filePath = defaultCredentialPath()) {
+    const store = await readStore(filePath);
+    store.credential = {
+        ...record,
+        updated_at: new Date().toISOString()
+    };
+    await writeStore(store, filePath);
+}
+async function readStore(filePath) {
+    let raw = "";
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (isENOENT(err)) {
+            return { version: STORE_VERSION };
+        }
+        throw err;
+    }
+    if (!raw.trim()) {
+        return { version: STORE_VERSION };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { version: STORE_VERSION };
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return { version: STORE_VERSION };
+    }
+    if (parsed.credential && typeof parsed.credential === "object") {
+        return { version: STORE_VERSION, credential: parsed.credential };
+    }
+    return { version: STORE_VERSION };
+}
+async function writeStore(store, filePath) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+}
+function isENOENT(err) {
+    return Boolean(err && typeof err === "object" && err.code === "ENOENT");
+}

package/dist/loop/credentials.test.d.ts

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

package/dist/loop/credentials.test.js

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { loadCredential, saveCredential } from "./credentials.js";
+test("saveCredential and loadCredential roundtrip", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "apa-sdk-creds-"));
+    const filePath = path.join(dir, "credentials.json");
+    await saveCredential({
+        api_base: "http://localhost:8080/api",
+        agent_name: "BotA",
+        agent_id: "agent_1",
+        api_key: "apa_1"
+    }, filePath);
+    const loaded = await loadCredential("http://localhost:8080/api", "BotA", filePath);
+    assert.ok(loaded);
+    assert.equal(loaded?.agent_id, "agent_1");
+    assert.equal(loaded?.api_key, "apa_1");
+});
+test("loadCredential without agentName returns single match for api base", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "apa-sdk-creds-"));
+    const filePath = path.join(dir, "credentials.json");
+    await saveCredential({
+        api_base: "http://localhost:8080/api",
+        agent_name: "BotA",
+        agent_id: "agent_1",
+        api_key: "apa_1"
+    }, filePath);
+    const loaded = await loadCredential("http://localhost:8080/api", undefined, filePath);
+    assert.ok(loaded);
+    assert.equal(loaded?.agent_name, "BotA");
+});

package/dist/loop/state.d.ts

@@ -0,0 +1,9 @@
+export type TurnState = {
+    turn_id?: string;
+    my_seat?: number;
+    current_actor_seat?: number;
+};
+export declare class TurnTracker {
+    private readonly seenTurns;
+    shouldRequestDecision(state: TurnState): boolean;
+}

package/dist/loop/state.js

@@ -0,0 +1,16 @@
+export class TurnTracker {
+    seenTurns = new Set();
+    shouldRequestDecision(state) {
+        const turnID = typeof state.turn_id === "string" ? state.turn_id : "";
+        const mySeat = Number(state.my_seat ?? -1);
+        const actorSeat = Number(state.current_actor_seat ?? -2);
+        if (!turnID || mySeat !== actorSeat) {
+            return false;
+        }
+        if (this.seenTurns.has(turnID)) {
+            return false;
+        }
+        this.seenTurns.add(turnID);
+        return true;
+    }
+}

package/dist/loop/state.test.d.ts

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

package/dist/loop/state.test.js

@@ -0,0 +1,14 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { TurnTracker } from "./state.js";
+test("TurnTracker requests exactly once for my new turn", () => {
+    const tracker = new TurnTracker();
+    const state = { turn_id: "turn_1", my_seat: 0, current_actor_seat: 0 };
+    assert.equal(tracker.shouldRequestDecision(state), true);
+    assert.equal(tracker.shouldRequestDecision(state), false);
+});
+test("TurnTracker ignores opponent turn", () => {
+    const tracker = new TurnTracker();
+    const state = { turn_id: "turn_2", my_seat: 0, current_actor_seat: 1 };
+    assert.equal(tracker.shouldRequestDecision(state), false);
+});

package/package.json

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