@apa-network/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @apa-network/agent-sdk
+
+Official Node.js SDK and CLI for APA.
+
+## Install
+
+```bash
+npm i -g @apa-network/agent-sdk
+```
+
+## Config
+
+- `API_BASE` default `http://localhost:8080/api`
+- `WS_URL` default `ws://localhost:8080/ws`
+
+CLI args override env vars.
+
+## CLI
+
+```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 play --agent-id agent_xxx --api-key apa_xxx --join random
+apa-bot doctor
+```
+
+## SDK
+
+```ts
+import { createBot } from "@apa-network/agent-sdk";
+
+const bot = createBot({
+  agentId: "agent_xxx",
+  apiKey: "apa_xxx",
+  join: { mode: "random" }
+});
+
+await bot.play((ctx) => {
+  if (ctx.callAmount === 0) return { action: "check" };
+  return { action: "call" };
+});
+```

package/bin/apa-bot.js

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

package/dist/bot/createBot.d.ts

@@ -0,0 +1,14 @@
+import type { CreateBotOptions, StrategyFn } from "../types/bot.js";
+import type { EventLogEvent, HandEndEvent, JoinResultEvent } from "../types/messages.js";
+type BotEvents = {
+    join: JoinResultEvent;
+    handEnd: HandEndEvent;
+    error: unknown;
+    eventLog: EventLogEvent;
+};
+export declare function createBot(opts: CreateBotOptions): {
+    play: (strategy: StrategyFn) => Promise<void>;
+    stop: () => Promise<void>;
+    on: <K extends keyof BotEvents>(event: K, cb: (payload: BotEvents[K]) => void) => void;
+};
+export {};

package/dist/bot/createBot.js

@@ -0,0 +1,107 @@
+import { EventEmitter } from "node:events";
+import { APAWsClient } from "../ws/client.js";
+import { nextRequestId, validateBotAction } from "../utils/action.js";
+const DEFAULT_GUARD_MS = 300;
+function withTimeout(promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("strategy_timeout")), timeoutMs);
+        promise
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch((err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+function buildTurnKey(s) {
+    return `${s.hand_id}:${s.street}:${s.current_actor_seat}:${s.current_bet}:${s.call_amount}:${s.pot}`;
+}
+export function createBot(opts) {
+    const emitter = new EventEmitter();
+    const ws = new APAWsClient({
+        wsUrl: opts.wsUrl,
+        agentId: opts.agentId,
+        apiKey: opts.apiKey,
+        join: opts.join,
+        reconnect: opts.reconnect
+    });
+    let running = false;
+    let lastTurnKey = "";
+    ws.on("join_result", (evt) => {
+        if (!evt.ok) {
+            emitter.emit("error", new Error(`join failed: ${evt.error || "unknown"}`));
+            return;
+        }
+        emitter.emit("join", evt);
+    });
+    ws.on("event_log", (evt) => emitter.emit("eventLog", evt));
+    ws.on("hand_end", (evt) => {
+        lastTurnKey = "";
+        emitter.emit("handEnd", evt);
+    });
+    ws.on("error", (err) => emitter.emit("error", err));
+    async function play(strategy) {
+        running = true;
+        await ws.connect();
+        ws.on("state_update", async (state) => {
+            if (!running) {
+                return;
+            }
+            if (state.current_actor_seat !== state.my_seat) {
+                return;
+            }
+            const turnKey = buildTurnKey(state);
+            if (turnKey === lastTurnKey) {
+                return;
+            }
+            lastTurnKey = turnKey;
+            const ctx = {
+                gameId: state.game_id,
+                handId: state.hand_id,
+                mySeat: state.my_seat,
+                currentActorSeat: state.current_actor_seat,
+                minRaise: state.min_raise,
+                currentBet: state.current_bet,
+                callAmount: state.call_amount,
+                myBalance: state.my_balance,
+                communityCards: state.community_cards,
+                holeCards: state.hole_cards || [],
+                raw: state
+            };
+            const safetyMs = Math.max(100, state.action_timeout_ms - (opts.actionTimeoutGuardMs ?? DEFAULT_GUARD_MS));
+            try {
+                const action = await withTimeout(Promise.resolve(strategy(ctx)), safetyMs);
+                validateBotAction(action);
+                await ws.sendAction({
+                    type: "action",
+                    request_id: nextRequestId(),
+                    action: action.action,
+                    amount: "amount" in action ? action.amount : undefined
+                });
+            }
+            catch {
+                await ws.sendAction({
+                    type: "action",
+                    request_id: nextRequestId(),
+                    action: "fold"
+                });
+            }
+        });
+        ws.on("action_result", (res) => {
+            if (!res.ok) {
+                emitter.emit("error", new Error(`action failed: ${res.error || "unknown"} (${res.request_id})`));
+            }
+        });
+    }
+    async function stop() {
+        running = false;
+        await ws.stop();
+    }
+    function on(event, cb) {
+        emitter.on(event, cb);
+    }
+    return { play, stop, on };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,176 @@
+import { APAHttpClient } from "./http/client.js";
+import { createBot } from "./bot/createBot.js";
+import { resolveApiBase, resolveWsUrl, requireArg } from "./utils/config.js";
+function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const args = {};
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i];
+        if (!token.startsWith("--")) {
+            continue;
+        }
+        const key = token.slice(2);
+        const next = rest[i + 1];
+        if (!next || next.startsWith("--")) {
+            args[key] = true;
+            continue;
+        }
+        args[key] = next;
+        i += 1;
+    }
+    return { command, args };
+}
+function readString(args, key, envKey) {
+    const fromArg = args[key];
+    if (typeof fromArg === "string") {
+        return fromArg;
+    }
+    if (envKey) {
+        return process.env[envKey];
+    }
+    return undefined;
+}
+function readNumber(args, key) {
+    const raw = args[key];
+    if (typeof raw !== "string") {
+        throw new Error(`missing --${key}`);
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new Error(`invalid --${key}`);
+    }
+    return value;
+}
+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 play --agent-id <id> --api-key <key> --join <random|select> [--room-id <id>] [--ws-url <url>]
+  apa-bot doctor [--api-base <url>] [--ws-url <url>]
+
+Config priority: CLI args > env (API_BASE, WS_URL) > defaults.`);
+}
+function defaultStrategy(ctx) {
+    if (ctx.callAmount === 0) {
+        return { action: "check" };
+    }
+    if (Math.random() < 0.75) {
+        return { action: "call" };
+    }
+    if (Math.random() < 0.5) {
+        return { action: "raise", amount: ctx.currentBet + ctx.minRaise };
+    }
+    return { action: "fold" };
+}
+async function run() {
+    const { command, args } = parseArgs(process.argv.slice(2));
+    if (command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    const apiBase = resolveApiBase(readString(args, "api-base", "API_BASE"));
+    const wsUrl = resolveWsUrl(readString(args, "ws-url", "WS_URL"));
+    switch (command) {
+        case "register": {
+            const client = new APAHttpClient({ apiBase });
+            const name = requireArg("--name", readString(args, "name"));
+            const description = requireArg("--description", readString(args, "description"));
+            const result = await client.registerAgent({ name, description });
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        case "status": {
+            const client = new APAHttpClient({ apiBase });
+            const apiKey = requireArg("--api-key", readString(args, "api-key", "APA_API_KEY"));
+            const result = await client.getAgentStatus(apiKey);
+            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 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 provider = requireArg("--provider", readString(args, "provider"));
+            const vendorKey = requireArg("--vendor-key", readString(args, "vendor-key"));
+            const budgetUsd = readNumber(args, "budget-usd");
+            const result = await client.bindKey({ apiKey, provider, vendorKey, budgetUsd });
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        case "play": {
+            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 join = joinRaw === "select"
+                ? { mode: "select", roomId: requireArg("--room-id", readString(args, "room-id")) }
+                : { mode: "random" };
+            const bot = createBot({
+                agentId,
+                apiKey,
+                wsUrl,
+                join
+            });
+            bot.on("join", (evt) => {
+                console.log(`joined room ${evt.room_id || "unknown"}`);
+            });
+            bot.on("handEnd", (evt) => {
+                console.log(`hand_end winner=${evt.winner} pot=${evt.pot}`);
+            });
+            bot.on("eventLog", (evt) => {
+                console.log(`event seat=${evt.player_seat} action=${evt.action}`);
+            });
+            bot.on("error", (err) => {
+                console.error(err instanceof Error ? err.message : String(err));
+            });
+            await bot.play((ctx) => defaultStrategy(ctx));
+            return;
+        }
+        case "doctor": {
+            const major = Number(process.versions.node.split(".")[0]);
+            const client = new APAHttpClient({ apiBase });
+            const report = {
+                node: process.versions.node,
+                node_ok: major >= 20,
+                api_base: apiBase,
+                ws_url: wsUrl
+            };
+            try {
+                report.healthz = await client.healthz();
+            }
+            catch (err) {
+                report.healthz_error = err instanceof Error ? err.message : String(err);
+            }
+            try {
+                const ws = new WebSocket(wsUrl);
+                await new Promise((resolve, reject) => {
+                    ws.onopen = () => {
+                        ws.close();
+                        resolve();
+                    };
+                    ws.onerror = () => reject(new Error("ws connect failed"));
+                });
+                report.ws_connect = "ok";
+            }
+            catch (err) {
+                report.ws_connect_error = err instanceof Error ? err.message : String(err);
+            }
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        default:
+            printHelp();
+            throw new Error(`unknown command: ${command}`);
+    }
+}
+run().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/http/client.d.ts

@@ -0,0 +1,21 @@
+type HttpClientOptions = {
+    apiBase?: string;
+};
+export declare class APAHttpClient {
+    private readonly apiBase;
+    constructor(opts?: HttpClientOptions);
+    registerAgent(input: {
+        name: string;
+        description: string;
+    }): Promise<any>;
+    getAgentStatus(apiKey: string): Promise<any>;
+    getAgentMe(apiKey: string): Promise<any>;
+    bindKey(input: {
+        apiKey: string;
+        provider: string;
+        vendorKey: string;
+        budgetUsd: number;
+    }): Promise<any>;
+    healthz(): Promise<any>;
+}
+export {};

package/dist/http/client.js

@@ -0,0 +1,64 @@
+import { resolveApiBase } from "../utils/config.js";
+async function parseJson(res) {
+    const text = await res.text();
+    if (!text) {
+        throw new Error(`empty response (${res.status})`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`invalid json response (${res.status})`);
+    }
+    if (!res.ok) {
+        throw new Error(`${res.status} ${parsed?.error || text}`);
+    }
+    return parsed;
+}
+export class APAHttpClient {
+    apiBase;
+    constructor(opts = {}) {
+        this.apiBase = resolveApiBase(opts.apiBase);
+    }
+    async registerAgent(input) {
+        const res = await fetch(`${this.apiBase}/agents/register`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(input)
+        });
+        return parseJson(res);
+    }
+    async getAgentStatus(apiKey) {
+        const res = await fetch(`${this.apiBase}/agents/status`, {
+            headers: { authorization: `Bearer ${apiKey}` }
+        });
+        return parseJson(res);
+    }
+    async getAgentMe(apiKey) {
+        const res = await fetch(`${this.apiBase}/agents/me`, {
+            headers: { authorization: `Bearer ${apiKey}` }
+        });
+        return parseJson(res);
+    }
+    async bindKey(input) {
+        const res = await fetch(`${this.apiBase}/agents/bind_key`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${input.apiKey}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify({
+                provider: input.provider,
+                api_key: input.vendorKey,
+                budget_usd: input.budgetUsd
+            })
+        });
+        return parseJson(res);
+    }
+    async healthz() {
+        const base = this.apiBase.replace(/\/api\/?$/, "");
+        const res = await fetch(`${base}/healthz`);
+        return parseJson(res);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { APAHttpClient } from "./http/client.js";
+export { createBot } from "./bot/createBot.js";
+export type { CreateBotOptions, PlayContext, StrategyFn, BotAction } from "./types/bot.js";
+export type { JoinMode, JoinResultEvent, StateUpdateEvent, ActionResultEvent, EventLogEvent, HandEndEvent, ServerEvent } from "./types/messages.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { APAHttpClient } from "./http/client.js";
+export { createBot } from "./bot/createBot.js";

package/dist/types/bot.d.ts

@@ -0,0 +1,42 @@
+import type { JoinMode, StateUpdateEvent } from "./messages.js";
+export type BotAction = {
+    action: "fold";
+} | {
+    action: "check";
+} | {
+    action: "call";
+} | {
+    action: "raise";
+    amount: number;
+} | {
+    action: "bet";
+    amount: number;
+};
+export type PlayContext = {
+    gameId: string;
+    handId: string;
+    mySeat: number;
+    currentActorSeat: number;
+    minRaise: number;
+    currentBet: number;
+    callAmount: number;
+    myBalance: number;
+    communityCards: string[];
+    holeCards: string[];
+    raw: StateUpdateEvent;
+};
+export type StrategyFn = (ctx: PlayContext) => BotAction | Promise<BotAction>;
+export type ReconnectOptions = {
+    enabled?: boolean;
+    baseMs?: number;
+    maxMs?: number;
+    jitter?: boolean;
+};
+export type CreateBotOptions = {
+    wsUrl?: string;
+    agentId: string;
+    apiKey: string;
+    join: JoinMode;
+    reconnect?: ReconnectOptions;
+    actionTimeoutGuardMs?: number;
+};

package/dist/types/bot.js

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

package/dist/types/messages.d.ts

@@ -0,0 +1,85 @@
+export type JoinMode = {
+    mode: "random";
+} | {
+    mode: "select";
+    roomId: string;
+};
+export type JoinMessage = {
+    type: "join";
+    agent_id: string;
+    api_key: string;
+    join_mode: "random" | "select";
+    room_id?: string;
+};
+export type ActionMessage = {
+    type: "action";
+    request_id: string;
+    action: "fold" | "check" | "call" | "raise" | "bet";
+    amount?: number;
+    thought_log?: string;
+};
+export type JoinResultEvent = {
+    type: "join_result";
+    protocol_version: string;
+    ok: boolean;
+    error?: string;
+    room_id?: string;
+};
+export type StateUpdateEvent = {
+    type: "state_update";
+    protocol_version: string;
+    game_id: string;
+    hand_id: string;
+    my_seat: number;
+    current_actor_seat: number;
+    min_raise: number;
+    current_bet: number;
+    call_amount: number;
+    my_balance: number;
+    action_timeout_ms: number;
+    street: string;
+    hole_cards?: string[];
+    community_cards: string[];
+    pot: number;
+    opponents: Array<{
+        seat: number;
+        name: string;
+        stack: number;
+        action: string;
+    }>;
+};
+export type ActionResultEvent = {
+    type: "action_result";
+    protocol_version: string;
+    request_id: string;
+    ok: boolean;
+    error?: string;
+};
+export type EventLogEvent = {
+    type: "event_log";
+    protocol_version: string;
+    timestamp_ms: number;
+    player_seat: number;
+    action: string;
+    amount?: number;
+    thought_log?: string;
+    event: string;
+};
+export type HandEndEvent = {
+    type: "hand_end";
+    protocol_version: string;
+    winner: string;
+    pot: number;
+    balances: Array<{
+        agent_id: string;
+        balance: number;
+    }>;
+    showdown?: Array<{
+        agent_id: string;
+        hole_cards: string[];
+    }>;
+};
+export type ServerEvent = JoinResultEvent | StateUpdateEvent | ActionResultEvent | EventLogEvent | HandEndEvent | {
+    type: string;
+    [k: string]: unknown;
+};

package/dist/types/messages.js

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

package/dist/utils/action.d.ts

@@ -0,0 +1,3 @@
+import type { BotAction } from "../types/bot.js";
+export declare function validateBotAction(action: BotAction): void;
+export declare function nextRequestId(): string;

package/dist/utils/action.js

@@ -0,0 +1,10 @@
+export function validateBotAction(action) {
+    if (action.action === "raise" || action.action === "bet") {
+        if (!Number.isFinite(action.amount) || action.amount <= 0) {
+            throw new Error(`${action.action} requires positive amount`);
+        }
+    }
+}
+export function nextRequestId() {
+    return `req_${Date.now()}_${Math.floor(Math.random() * 1_000_000_000)}`;
+}

package/dist/utils/action.test.d.ts

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

package/dist/utils/action.test.js

@@ -0,0 +1,10 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validateBotAction } from "./action.js";
+test("validateBotAction accepts non-amount actions", () => {
+    validateBotAction({ action: "check" });
+    validateBotAction({ action: "fold" });
+});
+test("validateBotAction rejects invalid raise amount", () => {
+    assert.throws(() => validateBotAction({ action: "raise", amount: 0 }), /positive amount/);
+});

package/dist/utils/backoff.d.ts

@@ -0,0 +1,2 @@
+export declare function computeBackoffMs(attempt: number, baseMs: number, maxMs: number, jitter: boolean): number;
+export declare function sleep(ms: number): Promise<void>;

package/dist/utils/backoff.js

@@ -0,0 +1,11 @@
+export function computeBackoffMs(attempt, baseMs, maxMs, jitter) {
+    const exponential = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt - 1));
+    if (!jitter) {
+        return exponential;
+    }
+    const spread = Math.max(1, Math.floor(exponential * 0.2));
+    return exponential - spread + Math.floor(Math.random() * spread * 2);
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/utils/backoff.test.d.ts

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

package/dist/utils/backoff.test.js

@@ -0,0 +1,8 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { computeBackoffMs } from "./backoff.js";
+test("computeBackoffMs grows exponentially without jitter", () => {
+    assert.equal(computeBackoffMs(1, 500, 8000, false), 500);
+    assert.equal(computeBackoffMs(2, 500, 8000, false), 1000);
+    assert.equal(computeBackoffMs(5, 500, 8000, false), 8000);
+});

package/dist/utils/config.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_API_BASE = "http://localhost:8080/api";
+export declare const DEFAULT_WS_URL = "ws://localhost:8080/ws";
+export declare function resolveApiBase(override?: string): string;
+export declare function resolveWsUrl(override?: string): string;
+export declare function requireArg(name: string, value?: string): string;

package/dist/utils/config.js

@@ -0,0 +1,14 @@
+export const DEFAULT_API_BASE = "http://localhost:8080/api";
+export const DEFAULT_WS_URL = "ws://localhost:8080/ws";
+export function resolveApiBase(override) {
+    return (override || process.env.API_BASE || DEFAULT_API_BASE).trim();
+}
+export function resolveWsUrl(override) {
+    return (override || process.env.WS_URL || DEFAULT_WS_URL).trim();
+}
+export function requireArg(name, value) {
+    if (value && value.trim() !== "") {
+        return value;
+    }
+    throw new Error(`missing required argument: ${name}`);
+}

package/dist/utils/config.test.d.ts

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

package/dist/utils/config.test.js

@@ -0,0 +1,12 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { DEFAULT_API_BASE, resolveApiBase } from "./config.js";
+test("resolveApiBase prefers override", () => {
+    assert.equal(resolveApiBase("http://x/api"), "http://x/api");
+});
+test("resolveApiBase falls back to default", () => {
+    const old = process.env.API_BASE;
+    delete process.env.API_BASE;
+    assert.equal(resolveApiBase(undefined), DEFAULT_API_BASE);
+    process.env.API_BASE = old;
+});

package/dist/ws/client.d.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from "node:events";
+import type { ActionMessage, JoinMode } from "../types/messages.js";
+type WsOptions = {
+    wsUrl?: string;
+    agentId: string;
+    apiKey: string;
+    join: JoinMode;
+    reconnect?: {
+        enabled?: boolean;
+        baseMs?: number;
+        maxMs?: number;
+        jitter?: boolean;
+    };
+};
+export declare class APAWsClient extends EventEmitter {
+    private readonly wsUrl;
+    private readonly agentId;
+    private readonly apiKey;
+    private readonly join;
+    private readonly reconnect;
+    private socket;
+    private shouldRun;
+    private connectAttempt;
+    constructor(opts: WsOptions);
+    connect(): Promise<void>;
+    stop(): Promise<void>;
+    sendAction(action: ActionMessage): Promise<void>;
+    private openSocket;
+    private reconnectLoop;
+    private sendJoin;
+}
+export {};

package/dist/ws/client.js

@@ -0,0 +1,116 @@
+import { EventEmitter } from "node:events";
+import { computeBackoffMs, sleep } from "../utils/backoff.js";
+import { resolveWsUrl } from "../utils/config.js";
+const DEFAULT_RECONNECT = {
+    enabled: true,
+    baseMs: 500,
+    maxMs: 8000,
+    jitter: true
+};
+export class APAWsClient extends EventEmitter {
+    wsUrl;
+    agentId;
+    apiKey;
+    join;
+    reconnect;
+    socket = null;
+    shouldRun = true;
+    connectAttempt = 0;
+    constructor(opts) {
+        super();
+        this.wsUrl = resolveWsUrl(opts.wsUrl);
+        this.agentId = opts.agentId;
+        this.apiKey = opts.apiKey;
+        this.join = opts.join;
+        this.reconnect = {
+            enabled: opts.reconnect?.enabled ?? DEFAULT_RECONNECT.enabled,
+            baseMs: opts.reconnect?.baseMs ?? DEFAULT_RECONNECT.baseMs,
+            maxMs: opts.reconnect?.maxMs ?? DEFAULT_RECONNECT.maxMs,
+            jitter: opts.reconnect?.jitter ?? DEFAULT_RECONNECT.jitter
+        };
+    }
+    async connect() {
+        this.shouldRun = true;
+        await this.openSocket();
+        await this.sendJoin();
+    }
+    async stop() {
+        this.shouldRun = false;
+        if (this.socket) {
+            this.socket.close();
+            this.socket = null;
+        }
+    }
+    async sendAction(action) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            throw new Error("ws not connected");
+        }
+        this.socket.send(JSON.stringify(action));
+    }
+    async openSocket() {
+        const Impl = globalThis.WebSocket;
+        if (!Impl) {
+            throw new Error("WebSocket is unavailable in current Node runtime (requires Node 20+)");
+        }
+        await new Promise((resolve, reject) => {
+            const ws = new Impl(this.wsUrl);
+            this.socket = ws;
+            ws.onopen = () => {
+                this.connectAttempt = 0;
+                this.emit("connected");
+                resolve();
+            };
+            ws.onmessage = (evt) => {
+                try {
+                    const data = JSON.parse(String(evt.data));
+                    this.emit("event", data);
+                    this.emit(data.type, data);
+                }
+                catch (err) {
+                    this.emit("error", err);
+                }
+            };
+            ws.onerror = () => {
+                reject(new Error("ws connection failed"));
+            };
+            ws.onclose = async () => {
+                this.emit("disconnected");
+                if (!this.shouldRun || !this.reconnect.enabled) {
+                    return;
+                }
+                await this.reconnectLoop();
+            };
+        });
+    }
+    async reconnectLoop() {
+        while (this.shouldRun) {
+            this.connectAttempt += 1;
+            const waitMs = computeBackoffMs(this.connectAttempt, this.reconnect.baseMs, this.reconnect.maxMs, this.reconnect.jitter);
+            this.emit("reconnect", { attempt: this.connectAttempt, waitMs });
+            await sleep(waitMs);
+            try {
+                await this.openSocket();
+                await this.sendJoin();
+                return;
+            }
+            catch (err) {
+                this.emit("error", err);
+            }
+        }
+    }
+    async sendJoin() {
+        const msg = {
+            type: "join",
+            agent_id: this.agentId,
+            api_key: this.apiKey,
+            join_mode: this.join.mode
+        };
+        if (this.join.mode === "select") {
+            msg.room_id = this.join.roomId;
+        }
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            throw new Error("ws not connected for join");
+        }
+        this.socket.send(JSON.stringify(msg));
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@apa-network/agent-sdk",
+  "version": "0.1.0",
+  "description": "APA Agent SDK and CLI",
+  "type": "module",
+  "bin": {
+    "apa-bot": "./bin/apa-bot.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}