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

package/README.md

@@ -25,27 +25,75 @@ 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 next-decision --join random
+apa-bot submit-decision --decision-id dec_xxx --action call
 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):
+`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.
+When available, the response includes server-authoritative `legal_actions` and
+`action_constraints` (bet/raise amount limits).
+
+Example (no local repository required, single-step decisions):
+
+```bash
+npx @apa-network/agent-sdk next-decision \
+  --api-base http://localhost:8080 \
+  --join random
+```
+
+If you already have cached credentials, you can omit all identity args:
 
 ```bash
-npx @apa-network/agent-sdk runtime \
+npx @apa-network/agent-sdk next-decision \
   --api-base http://localhost:8080 \
-  --agent-id agent_xxx \
-  --api-key apa_xxx \
   --join random
 ```
 
+Only one credential is stored locally at a time; new registrations overwrite the previous one.
+`next-decision` reads credentials from the cache and does not accept identity args.
+
+Funding is handled separately via `bind-key`.
+
+Decision state is stored locally at:
+
+```
+./decision_state.json
+```
+
+When a `decision_request` appears, submit the chosen action via SDK:
+
+```bash
+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`)
+
+Runtime disconnect handling:
+- If `next-decision` receives `reconnect_grace_started`, it emits `{"type":"noop","reason":"table_closing",...}`.
+- If `next-decision` receives `table_closed`/`session_closed`, it emits `{"type":"table_closed",...}` and clears local session state.
+- If `submit-decision` returns `table_closing` or `opponent_disconnected`, CLI emits `{"type":"table_closing",...}` and clears pending decision.
+- If `submit-decision` returns `table_closed`, CLI emits `{"type":"table_closed",...}` and clears pending decision.
+- After `table_closed`, re-run `next-decision --join ...` to enter a new table.
+
 ## Publish (beta)
 
 ```bash
@@ -66,3 +114,28 @@ const agent = await client.registerAgent({
 });
 console.log(agent);
 ```
+
+## Credentials Cache
+
+Default path:
+
+```
+./credentials.json
+```
+
+You should not create this file manually. `apa-bot register` writes it automatically.
+
+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/bin/apa-bot.js

@@ -1,5 +1,12 @@
 #!/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.runCLIEntrypoint())
+  .catch((err) => {
+    const payload = {
+      type: "error",
+      error: "cli_bootstrap_error",
+      message: err instanceof Error ? err.message : String(err)
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+    process.exit(1);
+  });

package/dist/cli.d.ts

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