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

package/README.md

@@ -40,6 +40,8 @@ apa-bot doctor
 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.
+When available, the response includes server-authoritative `legal_actions` and
+`action_constraints` (bet/raise amount limits).
 
 Example (no local repository required, single-step decisions):
 
@@ -74,6 +76,17 @@ When a `decision_request` appears, submit the chosen action via SDK:
 apa-bot submit-decision --decision-id <decision_id> --action call --thought-log "safe"
 ```
 
+For `bet`/`raise`, include `--amount` within the provided constraints:
+
+```bash
+apa-bot submit-decision --decision-id <decision_id> --action raise --amount 300 --thought-log "value raise"
+```
+
+`submit-decision` performs local hard validation:
+- rejects illegal actions for the current decision (`action_not_legal`)
+- rejects missing amount for `bet`/`raise` (`amount_required_for_bet_or_raise`)
+- rejects out-of-range amounts (`amount_out_of_range`)
+
 ## Publish (beta)
 
 ```bash

package/dist/cli.js

@@ -82,6 +82,43 @@ function claimCodeFromUrl(raw) {
 function emit(message) {
     process.stdout.write(`${JSON.stringify(message)}\n`);
 }
+function readLegalActions(state) {
+    const raw = state["legal_actions"];
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw;
+}
+function readActionConstraints(state) {
+    const raw = state["action_constraints"];
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    const src = raw;
+    const out = {};
+    const bet = src["bet"];
+    if (bet && typeof bet === "object") {
+        const b = bet;
+        const min = Number(b["min"]);
+        const max = Number(b["max"]);
+        if (Number.isFinite(min) && Number.isFinite(max)) {
+            out.bet = { min, max };
+        }
+    }
+    const raise = src["raise"];
+    if (raise && typeof raise === "object") {
+        const r = raise;
+        const minTo = Number(r["min_to"]);
+        const maxTo = Number(r["max_to"]);
+        if (Number.isFinite(minTo) && Number.isFinite(maxTo)) {
+            out.raise = { min_to: minTo, max_to: maxTo };
+        }
+    }
+    if (!out.bet && !out.raise) {
+        return undefined;
+    }
+    return out;
+}
 function parseAction(raw) {
     if (raw === "fold" || raw === "check" || raw === "call" || raw === "raise" || raw === "bet") {
         return raw;
@@ -285,21 +322,31 @@ async function runNextDecision(args) {
             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)}`;
+            const legalActions = readLegalActions(data);
+            const actionConstraints = readActionConstraints(data);
             pendingDecision = {
                 decision_id: decisionID,
                 session_id: sessionId,
                 request_id: reqID,
                 turn_id: String(data.turn_id || ""),
                 callback_url: callbackURL,
+                legal_actions: legalActions,
+                action_constraints: actionConstraints,
                 created_at: new Date().toISOString()
             };
-            emit({
+            const payload = {
                 type: "decision_request",
                 decision_id: decisionID,
                 session_id: sessionId,
-                legal_actions: ["fold", "check", "call", "raise", "bet"],
                 state: data
-            });
+            };
+            if (legalActions.length > 0) {
+                payload.legal_actions = legalActions;
+            }
+            if (actionConstraints) {
+                payload.action_constraints = actionConstraints;
+            }
+            emit(payload);
             decided = true;
             return true;
         });
@@ -339,6 +386,24 @@ async function runSubmitDecision(args) {
     if (pending.decision_id !== decisionID) {
         throw new Error("decision_id_mismatch (run apa-bot next-decision)");
     }
+    const legalActions = pending.legal_actions || [];
+    if (legalActions.length > 0 && !legalActions.includes(action)) {
+        throw new Error("action_not_legal");
+    }
+    if ((action === "bet" || action === "raise") && amount === undefined) {
+        throw new Error("amount_required_for_bet_or_raise");
+    }
+    const constraints = pending.action_constraints;
+    if (action === "bet" && amount !== undefined && constraints?.bet) {
+        if (amount < constraints.bet.min || amount > constraints.bet.max) {
+            throw new Error("amount_out_of_range");
+        }
+    }
+    if (action === "raise" && amount !== undefined && constraints?.raise) {
+        if (amount < constraints.raise.min_to || amount > constraints.raise.max_to) {
+            throw new Error("amount_out_of_range");
+        }
+    }
     const client = new APAHttpClient({ apiBase });
     try {
         const result = await client.submitAction({

package/dist/cli.next_decision.e2e.test.js

@@ -88,7 +88,8 @@ test("next-decision creates session, emits decision_request (without protocol fi
             if (url === `${apiBase}/agent/sessions/sess_1/events` && method === "GET") {
                 return sseResponse([
                     "id: 101\nevent: message\ndata: {\"event\":\"state_snapshot\",\"data\":{\"turn_id\":\"turn_1\",",
-                    "\"my_seat\":0,\"current_actor_seat\":0}}\n\n"
+                    "\"my_seat\":0,\"current_actor_seat\":0,\"legal_actions\":[\"check\",\"bet\"],",
+                    "\"action_constraints\":{\"bet\":{\"min\":100,\"max\":1200}}}}\n\n"
                 ]);
             }
             throw new Error(`unexpected fetch: ${method} ${url}`);
@@ -112,6 +113,8 @@ test("next-decision creates session, emits decision_request (without protocol fi
         assert.ok(typeof decision?.decision_id === "string");
         assert.equal(decision?.turn_id, undefined);
         assert.equal(decision?.callback_url, undefined);
+        assert.deepEqual(decision?.legal_actions, ["check", "bet"]);
+        assert.deepEqual(decision?.action_constraints, { bet: { min: 100, max: 1200 } });
         const state = await loadDecisionState();
         assert.equal(state.session_id, "sess_1");
         assert.equal(state.stream_url, `${apiBase}/agent/sessions/sess_1/events`);
@@ -120,6 +123,8 @@ test("next-decision creates session, emits decision_request (without protocol fi
         assert.equal(state.pending_decision?.session_id, "sess_1");
         assert.equal(state.pending_decision?.callback_url, `${apiBase}/agent/sessions/sess_1/actions`);
         assert.equal(state.pending_decision?.turn_id, "turn_1");
+        assert.deepEqual(state.pending_decision?.legal_actions, ["check", "bet"]);
+        assert.deepEqual(state.pending_decision?.action_constraints, { bet: { min: 100, max: 1200 } });
         const created = calls.find((c) => c.url === `${apiBase}/agent/sessions` && c.method === "POST");
         assert.ok(created);
     });
@@ -153,7 +158,8 @@ test("next-decision recovers from 409 and reuses existing session from response
             }
             if (url === `${apiBase}/agent/sessions/sess_conflict/events` && method === "GET") {
                 return sseResponse([
-                    "id: 202\nevent: message\ndata: {\"event\":\"state_snapshot\",\"data\":{\"turn_id\":\"turn_2\",\"my_seat\":1,\"current_actor_seat\":1}}\n\n"
+                    "id: 202\nevent: message\ndata: {\"event\":\"state_snapshot\",\"data\":{\"turn_id\":\"turn_2\",\"my_seat\":1,\"current_actor_seat\":1,",
+                    "\"legal_actions\":[\"fold\",\"call\",\"raise\"],\"action_constraints\":{\"raise\":{\"min_to\":300,\"max_to\":1500}}}}\n\n"
                 ]);
             }
             throw new Error(`unexpected fetch: ${method} ${url}`);
@@ -182,6 +188,8 @@ test("next-decision recovers from 409 and reuses existing session from response
         assert.equal(state.last_event_id, "202");
         assert.equal(state.pending_decision?.session_id, "sess_conflict");
         assert.equal(state.pending_decision?.turn_id, "turn_2");
+        assert.deepEqual(state.pending_decision?.legal_actions, ["fold", "call", "raise"]);
+        assert.deepEqual(state.pending_decision?.action_constraints, { raise: { min_to: 300, max_to: 1500 } });
     });
 });
 test("submit-decision uses pending decision metadata and clears pending entry", async () => {
@@ -220,7 +228,7 @@ test("submit-decision uses pending decision metadata and clears pending entry",
             if (url === `${apiBase}/agent/sessions/sess_1/events` && method === "GET") {
                 return sseResponse([
                     "id: 301\nevent: message\ndata: {\"event\":\"state_snapshot\",\"data\":{\"turn_id\":\"turn_3\",",
-                    "\"my_seat\":0,\"current_actor_seat\":0}}\n\n"
+                    "\"my_seat\":0,\"current_actor_seat\":0,\"legal_actions\":[\"call\"]}}\n\n"
                 ]);
             }
             if (url === `${apiBase}/agent/sessions/sess_1/actions` && method === "POST") {
@@ -248,3 +256,109 @@ test("submit-decision uses pending decision metadata and clears pending entry",
         assert.equal(finalState.pending_decision, undefined);
     });
 });
+test("submit-decision blocks bet/raise without amount locally", async () => {
+    await withTempCwd(async () => {
+        const apiBase = "http://mock.local/api";
+        await saveCredential({
+            api_base: apiBase,
+            agent_name: "BotA",
+            agent_id: "agent_1",
+            api_key: "apa_1"
+        });
+        const calls = [];
+        const originalFetch = globalThis.fetch;
+        const stdout = captureStdout();
+        globalThis.fetch = (async (input, init) => {
+            const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            const method = init?.method || "GET";
+            calls.push({ url, method, headers: init?.headers, body: typeof init?.body === "string" ? init.body : undefined });
+            if (url === `${apiBase}/agents/me` && method === "GET") {
+                return jsonResponse({ status: "claimed", balance_cc: 10000 });
+            }
+            if (url === `${apiBase}/public/rooms` && method === "GET") {
+                return jsonResponse({ items: [{ id: "room_low", min_buyin_cc: 1000, name: "Low" }] });
+            }
+            if (url === `${apiBase}/agent/sessions` && method === "POST") {
+                return jsonResponse({ session_id: "sess_2", stream_url: "/api/agent/sessions/sess_2/events" });
+            }
+            if (url === `${apiBase}/agent/sessions/sess_2/events` && method === "GET") {
+                return sseResponse([
+                    "id: 401\nevent: message\ndata: {\"event\":\"state_snapshot\",\"data\":{\"turn_id\":\"turn_4\",",
+                    "\"my_seat\":0,\"current_actor_seat\":0,\"legal_actions\":[\"bet\"],\"action_constraints\":{\"bet\":{\"min\":100,\"max\":500}}}}\n\n"
+                ]);
+            }
+            throw new Error(`unexpected fetch: ${method} ${url}`);
+        });
+        try {
+            await runCLI(["next-decision", "--api-base", apiBase, "--join", "random", "--timeout-ms", "2000"]);
+            const state = await loadDecisionState();
+            const decisionID = state.pending_decision?.decision_id;
+            assert.ok(decisionID);
+            await assert.rejects(async () => runCLI(["submit-decision", "--api-base", apiBase, "--decision-id", decisionID, "--action", "bet"]), /amount_required_for_bet_or_raise/);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+            stdout.restore();
+        }
+        const actionCall = calls.find((c) => c.url.includes("/actions") && c.method === "POST");
+        assert.equal(actionCall, undefined);
+    });
+});
+test("submit-decision blocks out-of-range amount locally", async () => {
+    await withTempCwd(async () => {
+        const apiBase = "http://mock.local/api";
+        await saveCredential({
+            api_base: apiBase,
+            agent_name: "BotA",
+            agent_id: "agent_1",
+            api_key: "apa_1"
+        });
+        const calls = [];
+        const originalFetch = globalThis.fetch;
+        const stdout = captureStdout();
+        globalThis.fetch = (async (input, init) => {
+            const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+            const method = init?.method || "GET";
+            calls.push({ url, method, headers: init?.headers, body: typeof init?.body === "string" ? init.body : undefined });
+            if (url === `${apiBase}/agents/me` && method === "GET") {
+                return jsonResponse({ status: "claimed", balance_cc: 10000 });
+            }
+            if (url === `${apiBase}/public/rooms` && method === "GET") {
+                return jsonResponse({ items: [{ id: "room_low", min_buyin_cc: 1000, name: "Low" }] });
+            }
+            if (url === `${apiBase}/agent/sessions` && method === "POST") {
+                return jsonResponse({ session_id: "sess_3", stream_url: "/api/agent/sessions/sess_3/events" });
+            }
+            if (url === `${apiBase}/agent/sessions/sess_3/events` && method === "GET") {
+                return sseResponse([
+                    "id: 501\nevent: message\ndata: {\"event\":\"state_snapshot\",\"data\":{\"turn_id\":\"turn_5\",",
+                    "\"my_seat\":0,\"current_actor_seat\":0,\"legal_actions\":[\"raise\"],\"action_constraints\":{\"raise\":{\"min_to\":300,\"max_to\":600}}}}\n\n"
+                ]);
+            }
+            throw new Error(`unexpected fetch: ${method} ${url}`);
+        });
+        try {
+            await runCLI(["next-decision", "--api-base", apiBase, "--join", "random", "--timeout-ms", "2000"]);
+            const state = await loadDecisionState();
+            const decisionID = state.pending_decision?.decision_id;
+            assert.ok(decisionID);
+            await assert.rejects(async () => runCLI([
+                "submit-decision",
+                "--api-base",
+                apiBase,
+                "--decision-id",
+                decisionID,
+                "--action",
+                "raise",
+                "--amount",
+                "700"
+            ]), /amount_out_of_range/);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+            stdout.restore();
+        }
+        const actionCall = calls.find((c) => c.url.includes("/actions") && c.method === "POST");
+        assert.equal(actionCall, undefined);
+    });
+});

package/dist/loop/decision_state.d.ts

@@ -10,6 +10,17 @@ export type DecisionState = {
         request_id: string;
         turn_id: string;
         callback_url: string;
+        legal_actions?: string[];
+        action_constraints?: {
+            bet?: {
+                min: number;
+                max: number;
+            };
+            raise?: {
+                min_to: number;
+                max_to: number;
+            };
+        };
         created_at: string;
     };
     updated_at?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apa-network/agent-sdk",
-  "version": "0.2.0-beta.8",
+  "version": "0.2.0-beta.9",
   "description": "APA Agent SDK and CLI",
   "type": "module",
   "bin": {