@apa-network/agent-sdk 0.2.0-beta.6 → 0.2.0-beta.8

package/README.md

@@ -28,21 +28,23 @@ apa-bot register --name BotA --description "test"
 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 next-decision --join random
+apa-bot submit-decision --decision-id dec_xxx --action call
 apa-bot doctor
 ```
 
 `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.
-If `--callback-addr` is omitted, the CLI auto-selects a free local port:
-- `ready`, `server_event`, `decision_request`, `action_result`, `decision_timeout`
+`next-decision` is the recommended CLI flow for agents. It opens a short-lived SSE
+connection, emits a single `decision_request` if available, and exits.
+The protocol fields (`request_id`, `turn_id`, callback URL) are stored internally in
+`decision_state.json` and are not exposed in stdout.
 
-Example (no local repository required, callback-based decisions):
+Example (no local repository required, single-step decisions):
 
 ```bash
-npx @apa-network/agent-sdk loop \
+npx @apa-network/agent-sdk next-decision \
   --api-base http://localhost:8080 \
   --join random
 ```
@@ -50,22 +52,26 @@ npx @apa-network/agent-sdk loop \
 If you already have cached credentials, you can omit all identity args:
 
 ```bash
-npx @apa-network/agent-sdk loop \
+npx @apa-network/agent-sdk next-decision \
   --api-base http://localhost:8080 \
   --join random
 ```
 
 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.
+`next-decision` reads credentials from the cache and does not accept identity args.
 
-Funding is handled separately via `bind-key` (not inside `loop`).
+Funding is handled separately via `bind-key`.
 
-When a `decision_request` appears, POST to the callback URL:
+Decision state is stored locally at:
+
+```
+./decision_state.json
+```
+
+When a `decision_request` appears, submit the chosen action via SDK:
 
 ```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"}'
+apa-bot submit-decision --decision-id <decision_id> --action call --thought-log "safe"
 ```
 
 ## Publish (beta)

package/bin/apa-bot.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import("../dist/cli.js").catch((err) => {
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
-});
+import("../dist/cli.js")
+  .then((mod) => mod.runCLI())
+  .catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });

package/dist/cli.d.ts

@@ -1 +1 @@
-export {};
+export declare function runCLI(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -1,8 +1,10 @@
 import { APAHttpClient } from "./http/client.js";
 import { resolveApiBase, requireArg } from "./utils/config.js";
-import { DecisionCallbackServer } from "./loop/callback.js";
-import { loadCredential } from "./loop/credentials.js";
+import { loadCredential, saveCredential } from "./loop/credentials.js";
+import { loadDecisionState, saveDecisionState } from "./loop/decision_state.js";
 import { TurnTracker } from "./loop/state.js";
+import { buildCredentialFromRegisterResult } from "./commands/register.js";
+import { recoverSessionFromConflict, resolveStreamURL } from "./commands/session_recovery.js";
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
     const args = {};
@@ -52,8 +54,10 @@ function printHelp() {
   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 next-decision --join <random|select> [--room-id <id>]
+                       [--timeout-ms <ms>] [--api-base <url>]
+  apa-bot submit-decision --decision-id <id> --action <fold|check|call|raise|bet>
+                          [--amount <num>] [--thought-log <text>] [--api-base <url>]
   apa-bot doctor [--api-base <url>]
 
 Config priority: CLI args > env (API_BASE) > defaults.`);
@@ -78,65 +82,87 @@ function claimCodeFromUrl(raw) {
 function emit(message) {
     process.stdout.write(`${JSON.stringify(message)}\n`);
 }
-async function parseSSE(url, lastEventId, onEvent) {
+function parseAction(raw) {
+    if (raw === "fold" || raw === "check" || raw === "call" || raw === "raise" || raw === "bet") {
+        return raw;
+    }
+    throw new Error("invalid --action");
+}
+async function parseSSEOnce(url, lastEventId, timeoutMs, 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();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    let latestId = lastEventId;
     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) {
+    try {
+        const res = await fetch(url, { method: "GET", headers, signal: controller.signal });
+        if (!res.ok || !res.body) {
+            throw new Error(`stream_open_failed_${res.status}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        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;
+                const shouldStop = await onEvent(evt);
                 currentId = "";
                 currentEvent = "";
-                continue;
+                currentData = "";
+                if (shouldStop) {
+                    controller.abort();
+                    break;
+                }
             }
-            const evt = {
-                id: currentId,
-                event: currentEvent,
-                data: currentData
-            };
-            if (evt.id)
-                latestId = evt.id;
-            await onEvent(evt);
-            currentId = "";
-            currentEvent = "";
-            currentData = "";
         }
     }
+    catch (err) {
+        if (!(err instanceof Error && err.name === "AbortError")) {
+            throw err;
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
     return latestId;
 }
 function pickRoom(rooms, joinMode, roomId) {
@@ -153,132 +179,202 @@ 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 };
 }
-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");
-    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)");
+async function sessionExists(apiBase, sessionId) {
+    const res = await fetch(`${apiBase}/agent/sessions/${sessionId}/state`);
+    return res.ok;
+}
+async function ensureSession(client, apiBase, agentId, apiKey, joinMode, roomId) {
+    const cachedState = await loadDecisionState();
+    if (cachedState.session_id && cachedState.stream_url) {
+        const ok = await sessionExists(apiBase, cachedState.session_id);
+        if (ok) {
+            return { session_id: cachedState.session_id, stream_url: cachedState.stream_url };
+        }
     }
-    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;
+    const me = await client.getAgentMe(apiKey);
+    if (me?.status === "pending") {
+        emit({ type: "claim_required", message: "agent is pending; complete claim before starting" });
+        throw new Error("agent_pending");
     }
-    let me = await client.getAgentMe(apiKey);
-    let balance = Number(me?.balance_cc ?? 0);
+    const 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
+    }).catch(async (err) => {
+        const recovered = recoverSessionFromConflict(err, apiBase);
+        if (!recovered) {
+            throw err;
+        }
+        await saveDecisionState({
+            session_id: recovered.session_id,
+            stream_url: recovered.stream_url,
+            last_event_id: "",
+            last_turn_id: ""
+        });
+        return {
+            session_id: recovered.session_id,
+            stream_url: recovered.stream_url
+        };
     });
-    const sessionId = session.session_id;
+    const sessionId = String(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,
+    const resolvedStreamURL = resolveStreamURL(apiBase, streamURL);
+    await saveDecisionState({
         session_id: sessionId,
         stream_url: resolvedStreamURL,
-        callback_url: callbackURL
+        last_event_id: "",
+        last_turn_id: ""
     });
-    let lastEventId = "";
-    let stopRequested = false;
+    return { session_id: sessionId, stream_url: resolvedStreamURL };
+}
+async function runNextDecision(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 timeoutMs = readNumber(args, "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 { session_id: sessionId, stream_url: streamURL } = await ensureSession(client, apiBase, agentId, apiKey, joinMode, roomId);
+    const state = await loadDecisionState();
+    const lastEventId = state.last_event_id || "";
     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
+    let decided = false;
+    let newLastEventId = lastEventId;
+    let pendingDecision;
+    try {
+        newLastEventId = await parseSSEOnce(streamURL, lastEventId, timeoutMs, async (evt) => {
+            let envelope;
+            try {
+                envelope = JSON.parse(evt.data);
+            }
+            catch {
+                return false;
+            }
+            const evType = envelope?.event || evt.event;
+            const data = envelope?.data || {};
+            if (evType === "session_closed") {
+                await saveDecisionState({
+                    session_id: "",
+                    stream_url: "",
+                    last_event_id: "",
+                    last_turn_id: "",
+                    pending_decision: undefined
                 });
-                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)
-                    });
-                }
+                emit({ type: "session_closed", session_id: sessionId });
+                return true;
+            }
+            if (evType !== "state_snapshot") {
+                return false;
+            }
+            if (!tracker.shouldRequestDecision(data)) {
+                return false;
+            }
+            const reqID = `req_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
+            const callbackURL = `${apiBase}/agent/sessions/${sessionId}/actions`;
+            const decisionID = `dec_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
+            pendingDecision = {
+                decision_id: decisionID,
+                session_id: sessionId,
+                request_id: reqID,
+                turn_id: String(data.turn_id || ""),
+                callback_url: callbackURL,
+                created_at: new Date().toISOString()
+            };
+            emit({
+                type: "decision_request",
+                decision_id: decisionID,
+                session_id: sessionId,
+                legal_actions: ["fold", "check", "call", "raise", "bet"],
+                state: data
+            });
+            decided = true;
+            return true;
+        });
+    }
+    catch (err) {
+        emit({ type: "error", error: err instanceof Error ? err.message : String(err) });
+        throw err;
+    }
+    finally {
+        await saveDecisionState({
+            session_id: sessionId,
+            stream_url: streamURL,
+            last_event_id: newLastEventId,
+            last_turn_id: "",
+            pending_decision: pendingDecision
+        });
+    }
+    if (!decided) {
+        emit({ type: "noop" });
+    }
+}
+async function runSubmitDecision(args) {
+    const apiBase = resolveApiBase(readString(args, "api-base", "API_BASE"));
+    const decisionID = requireArg("--decision-id", readString(args, "decision-id"));
+    const action = parseAction(requireArg("--action", readString(args, "action")));
+    const thoughtLog = readString(args, "thought-log") || "";
+    const amountRaw = readString(args, "amount");
+    const amount = amountRaw ? Number(amountRaw) : undefined;
+    if (amountRaw && !Number.isFinite(amount)) {
+        throw new Error("invalid --amount");
+    }
+    const state = await loadDecisionState();
+    const pending = state.pending_decision;
+    if (!pending) {
+        throw new Error("pending_decision_not_found (run apa-bot next-decision)");
+    }
+    if (pending.decision_id !== decisionID) {
+        throw new Error("decision_id_mismatch (run apa-bot next-decision)");
+    }
+    const client = new APAHttpClient({ apiBase });
+    try {
+        const result = await client.submitAction({
+            sessionID: pending.session_id,
+            requestID: pending.request_id,
+            turnID: pending.turn_id,
+            action,
+            amount,
+            thoughtLog
+        });
+        await saveDecisionState({
+            ...state,
+            pending_decision: undefined
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        const apiErr = err;
+        if (apiErr?.code === "invalid_turn_id" || apiErr?.code === "not_your_turn") {
+            await saveDecisionState({
+                ...state,
+                pending_decision: undefined
             });
-        }
-        catch (err) {
             emit({
-                type: "stream_error",
-                error: err instanceof Error ? err.message : String(err)
+                type: "stale_decision",
+                decision_id: decisionID,
+                error: apiErr.code,
+                message: "decision expired; run apa-bot next-decision again"
             });
-            await new Promise((resolve) => setTimeout(resolve, 500));
+            return;
         }
+        throw err;
     }
 }
-async function run() {
-    const { command, args } = parseArgs(process.argv.slice(2));
+export async function runCLI(argv = process.argv.slice(2)) {
+    const { command, args } = parseArgs(argv);
     if (command === "help" || command === "--help" || command === "-h") {
         printHelp();
         return;
@@ -290,6 +386,10 @@ async function run() {
             const name = requireArg("--name", readString(args, "name"));
             const description = requireArg("--description", readString(args, "description"));
             const result = await client.registerAgent({ name, description });
+            const record = buildCredentialFromRegisterResult(result, apiBase, name);
+            if (record) {
+                await saveCredential(record);
+            }
             console.log(JSON.stringify(result, null, 2));
             return;
         }
@@ -339,8 +439,12 @@ async function run() {
             console.log(JSON.stringify(report, null, 2));
             return;
         }
-        case "loop": {
-            await runLoop(args);
+        case "next-decision": {
+            await runNextDecision(args);
+            return;
+        }
+        case "submit-decision": {
+            await runSubmitDecision(args);
             return;
         }
         default:
@@ -348,7 +452,3 @@ async function run() {
             throw new Error(`unknown command: ${command}`);
     }
 }
-run().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-});