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

package/dist/cli.js

@@ -1,10 +1,14 @@
 import { APAHttpClient } from "./http/client.js";
 import { resolveApiBase, requireArg } from "./utils/config.js";
-import readline from "node:readline";
+import { defaultCredentialPath, 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 = {};
-    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 +34,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,207 +51,480 @@ 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 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.`);
 }
+async function requireApiKey(apiBase) {
+    const cached = await loadCredential(apiBase, undefined);
+    if (!cached?.api_key) {
+        const path = defaultCredentialPath();
+        throw new Error(`api_key_not_found for api_base=${apiBase} (run apa-bot register). path=${path}`);
+    }
+    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`);
 }
-async function parseSSE(url, lastEventId, onEvent) {
+function toErrorPayload(err) {
+    const apiErr = err;
+    const code = apiErr?.code || "cli_error";
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        type: "error",
+        error: code,
+        message
+    };
+}
+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;
+    }
+    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;
 }
-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
-        })
+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 };
+}
+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 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");
+    }
+    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 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
+        };
     });
-    if (!createRes.ok) {
-        const body = await createRes.text();
-        throw new Error(`create_session_failed_${createRes.status}:${body}`);
-    }
-    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}`;
-    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)
-            return;
-        try {
-            const msg = JSON.parse(trimmed);
-            if (msg.type === "stop") {
-                stopRequested = true;
-                return;
+    const sessionId = String(session.session_id || "");
+    const streamURL = String(session.stream_url || "");
+    const resolvedStreamURL = resolveStreamURL(apiBase, streamURL);
+    await saveDecisionState({
+        session_id: sessionId,
+        stream_url: resolvedStreamURL,
+        last_event_id: "",
+        last_turn_id: ""
+    });
+    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();
+    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);
             }
-            if (msg.type !== "decision_response") {
-                return;
+            catch {
+                return false;
             }
-            const decision = msg;
-            const pendingTurn = pending.get(decision.request_id);
-            if (!pendingTurn) {
-                return;
+            const evType = envelope?.event || evt.event;
+            const data = envelope?.data || {};
+            if (evType === "session_closed" || evType === "table_closed") {
+                await saveDecisionState({
+                    session_id: "",
+                    stream_url: "",
+                    last_event_id: "",
+                    last_turn_id: "",
+                    pending_decision: undefined
+                });
+                emit({ type: "table_closed", session_id: sessionId, reason: data?.reason || "table_closed" });
+                decided = true;
+                return true;
             }
-            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();
+            if (evType === "reconnect_grace_started") {
+                emit({
+                    type: "noop",
+                    reason: "table_closing",
+                    event: evType,
+                    session_id: sessionId,
+                    disconnected_agent_id: data?.disconnected_agent_id,
+                    deadline_ts: data?.deadline_ts
+                });
+                decided = true;
+                return true;
             }
-            catch {
-                actionBody = {};
+            if (evType === "opponent_forfeited") {
+                emit({
+                    type: "noop",
+                    reason: "table_closing",
+                    event: evType,
+                    session_id: sessionId
+                });
+                decided = true;
+                return true;
             }
-            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)
-            });
-        }
-    });
-    emit({ type: "ready", session_id: sessionId, stream_url: streamURL });
-    while (!stopRequested) {
-        try {
-            lastEventId = await parseSSE(streamURL, 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 !== "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)) {
-                    return;
-                }
-                seenTurns.add(turnID);
-                const reqID = `req_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
-                pending.set(reqID, { turnID });
+            if (evType !== "state_snapshot") {
+                return false;
+            }
+            const tableStatus = String(data?.table_status || "active");
+            if (tableStatus === "closing") {
                 emit({
-                    type: "decision_request",
-                    request_id: reqID,
+                    type: "noop",
+                    reason: "table_closing",
+                    event: evType,
                     session_id: sessionId,
-                    turn_id: turnID,
-                    legal_actions: ["fold", "check", "call", "raise", "bet"],
-                    state: data
+                    close_reason: data?.close_reason,
+                    reconnect_deadline_ts: data?.reconnect_deadline_ts
                 });
-            });
+                decided = true;
+                return true;
+            }
+            if (tableStatus === "closed") {
+                await saveDecisionState({
+                    session_id: "",
+                    stream_url: "",
+                    last_event_id: "",
+                    last_turn_id: "",
+                    pending_decision: undefined
+                });
+                emit({
+                    type: "table_closed",
+                    session_id: sessionId,
+                    reason: data?.close_reason || "table_closed"
+                });
+                decided = true;
+                return true;
+            }
+            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)}`;
+            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()
+            };
+            const payload = {
+                type: "decision_request",
+                decision_id: decisionID,
+                session_id: sessionId,
+                state: data
+            };
+            if (legalActions.length > 0) {
+                payload.legal_actions = legalActions;
+            }
+            if (actionConstraints) {
+                payload.action_constraints = actionConstraints;
+            }
+            emit(payload);
+            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 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");
         }
-        catch (err) {
-            emit({
-                type: "stream_error",
-                error: err instanceof Error ? err.message : String(err)
+    }
+    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({
+            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" ||
+            apiErr?.code === "table_closing" ||
+            apiErr?.code === "table_closed" ||
+            apiErr?.code === "opponent_disconnected") {
+            await saveDecisionState({
+                ...state,
+                pending_decision: undefined
             });
-            if (stopRequested) {
-                break;
+            if (apiErr?.code === "table_closed") {
+                emit({
+                    type: "table_closed",
+                    decision_id: decisionID,
+                    error: apiErr.code,
+                    message: "table closed; re-join matchmaking"
+                });
             }
-            await new Promise((resolve) => setTimeout(resolve, 500));
+            else if (apiErr?.code === "table_closing" || apiErr?.code === "opponent_disconnected") {
+                emit({
+                    type: "table_closing",
+                    decision_id: decisionID,
+                    error: apiErr.code,
+                    message: "table is closing; pause and fetch new decision later"
+                });
+            }
+            else {
+                emit({
+                    type: "stale_decision",
+                    decision_id: decisionID,
+                    error: apiErr.code,
+                    message: "decision expired; run apa-bot next-decision again"
+                });
+            }
+            return;
         }
+        throw err;
     }
-    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));
+export async function runCLI(argv = process.argv.slice(2)) {
+    const { command, args } = parseArgs(argv);
     if (command === "help" || command === "--help" || command === "-h") {
         printHelp();
         return;
@@ -256,26 +536,35 @@ 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;
         }
-        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 +589,12 @@ 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 "next-decision": {
+            await runNextDecision(args);
+            return;
+        }
+        case "submit-decision": {
+            await runSubmitDecision(args);
             return;
         }
         default:
@@ -320,7 +602,12 @@ async function run() {
             throw new Error(`unknown command: ${command}`);
     }
 }
-run().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-});
+export async function runCLIEntrypoint(argv = process.argv.slice(2)) {
+    try {
+        await runCLI(argv);
+    }
+    catch (err) {
+        emit(toErrorPayload(err));
+        process.exitCode = 1;
+    }
+}