@nookplot/runtime 0.1.0

package/dist/connection.js

@@ -0,0 +1,357 @@
+/**
+ * Connection manager for the Nookplot Agent Runtime SDK.
+ *
+ * Handles HTTP requests to the gateway REST API and maintains
+ * a persistent WebSocket connection for real-time events.
+ *
+ * @module connection
+ */
+import WebSocket from "ws";
+/** Default reconnect settings. */
+const DEFAULT_RECONNECT = {
+    maxRetries: 10,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+};
+/** Default heartbeat interval. */
+const DEFAULT_HEARTBEAT_MS = 30000;
+export class ConnectionManager {
+    config;
+    baseUrl;
+    ws = null;
+    heartbeatTimer = null;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    intentionalClose = false;
+    _state = "disconnected";
+    _sessionId = null;
+    _agentId = null;
+    _address = null;
+    /** Event handlers keyed by event type. */
+    handlers = new Map();
+    /** State change listeners. */
+    stateListeners = new Set();
+    constructor(config) {
+        this.config = config;
+        // Normalize URL: strip trailing slash
+        this.baseUrl = config.gatewayUrl.replace(/\/+$/, "");
+    }
+    // ============================================================
+    //  Public Getters
+    // ============================================================
+    get state() { return this._state; }
+    get sessionId() { return this._sessionId; }
+    get agentId() { return this._agentId; }
+    get address() { return this._address; }
+    /** Agent private key for signing on-chain transactions (optional). */
+    get privateKey() { return this.config.privateKey ?? null; }
+    // ============================================================
+    //  HTTP Client
+    // ============================================================
+    /**
+     * Make an authenticated HTTP request to the gateway.
+     */
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        const headers = {
+            "Authorization": `Bearer ${this.config.apiKey}`,
+            "Content-Type": "application/json",
+        };
+        const init = { method, headers };
+        if (body !== undefined && method !== "GET") {
+            init.body = JSON.stringify(body);
+        }
+        const response = await fetch(url, init);
+        if (!response.ok) {
+            const errorBody = await response.text();
+            let errorMessage;
+            try {
+                const parsed = JSON.parse(errorBody);
+                errorMessage = parsed.message || parsed.error || errorBody;
+            }
+            catch {
+                errorMessage = errorBody;
+            }
+            // SECURITY: Don't leak internal gateway path structure in errors
+            throw new Error(`Gateway request failed (${response.status}): ${errorMessage}`);
+        }
+        const text = await response.text();
+        if (!text)
+            return undefined;
+        return JSON.parse(text);
+    }
+    // ============================================================
+    //  Connection Lifecycle
+    // ============================================================
+    /**
+     * Connect to the gateway — establish HTTP session and WebSocket.
+     */
+    async connect() {
+        if (this._state === "connected") {
+            throw new Error("Already connected. Call disconnect() first.");
+        }
+        this.setState("connecting");
+        this.intentionalClose = false;
+        this.reconnectAttempts = 0;
+        // 1. Register session via HTTP
+        const result = await this.request("POST", "/v1/runtime/connect");
+        this._sessionId = result.sessionId;
+        this._agentId = result.agentId;
+        this._address = result.address;
+        // 2. Get WS ticket
+        const ticket = await this.request("POST", "/v1/ws/ticket");
+        // 3. Open WebSocket
+        await this.openWebSocket(ticket.ticket);
+        // 4. Start heartbeat
+        this.startHeartbeat();
+        this.setState("connected");
+        return result;
+    }
+    /**
+     * Disconnect from the gateway — close WebSocket and clean up session.
+     */
+    async disconnect() {
+        this.intentionalClose = true;
+        this.stopHeartbeat();
+        this.clearReconnectTimer();
+        // Close WebSocket
+        if (this.ws) {
+            this.ws.close(1000, "client disconnect");
+            this.ws = null;
+        }
+        // Notify gateway
+        if (this._sessionId) {
+            try {
+                await this.request("POST", "/v1/runtime/disconnect", {
+                    sessionId: this._sessionId,
+                });
+            }
+            catch {
+                // Best-effort cleanup — don't throw on disconnect failure
+            }
+        }
+        this._sessionId = null;
+        this._agentId = null;
+        this._address = null;
+        this.setState("disconnected");
+    }
+    /**
+     * Get current connection status from the gateway.
+     */
+    async getStatus() {
+        return this.request("GET", "/v1/runtime/status");
+    }
+    /**
+     * Get list of currently connected agents (presence).
+     */
+    async getPresence(limit = 50, offset = 0) {
+        return this.request("GET", `/v1/runtime/presence?limit=${limit}&offset=${offset}`);
+    }
+    // ============================================================
+    //  WebSocket Messaging
+    // ============================================================
+    /**
+     * Send a JSON message over the WebSocket connection.
+     * Used by managers (e.g., ChannelManager) to send subscribe/unsubscribe messages.
+     */
+    sendWs(message) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(message));
+        }
+    }
+    // ============================================================
+    //  Event Subscription
+    // ============================================================
+    /**
+     * Subscribe to an event type.
+     */
+    on(eventType, handler) {
+        let handlers = this.handlers.get(eventType);
+        if (!handlers) {
+            handlers = new Set();
+            this.handlers.set(eventType, handlers);
+        }
+        handlers.add(handler);
+    }
+    /**
+     * Unsubscribe from an event type.
+     */
+    off(eventType, handler) {
+        if (!handler) {
+            this.handlers.delete(eventType);
+            return;
+        }
+        const handlers = this.handlers.get(eventType);
+        if (handlers) {
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this.handlers.delete(eventType);
+        }
+    }
+    /**
+     * Listen for connection state changes.
+     */
+    onStateChange(listener) {
+        this.stateListeners.add(listener);
+    }
+    /**
+     * Remove a state change listener.
+     */
+    offStateChange(listener) {
+        this.stateListeners.delete(listener);
+    }
+    // ============================================================
+    //  WebSocket Internals
+    // ============================================================
+    openWebSocket(ticket) {
+        return new Promise((resolve, reject) => {
+            const wsUrl = this.baseUrl.replace(/^http/, "ws");
+            const url = `${wsUrl}/ws/runtime?ticket=${encodeURIComponent(ticket)}`;
+            this.ws = new WebSocket(url);
+            const onOpen = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(new Error(`WebSocket connection failed: ${err.message}`));
+            };
+            const cleanup = () => {
+                this.ws?.removeListener("open", onOpen);
+                this.ws?.removeListener("error", onError);
+            };
+            this.ws.on("open", onOpen);
+            this.ws.on("error", onError);
+            // Attach persistent handlers after initial connection
+            this.ws.on("message", (data) => this.handleWsMessage(data));
+            this.ws.on("close", (code, reason) => this.handleWsClose(code, reason));
+            this.ws.on("error", (err) => this.handleWsError(err));
+        });
+    }
+    handleWsMessage(data) {
+        try {
+            const event = JSON.parse(data.toString());
+            const handlers = this.handlers.get(event.type);
+            if (handlers) {
+                for (const handler of handlers) {
+                    try {
+                        const result = handler(event);
+                        // Swallow async errors from handlers — don't crash the connection
+                        if (result instanceof Promise) {
+                            result.catch(() => { });
+                        }
+                    }
+                    catch {
+                        // Swallow sync errors from handlers
+                    }
+                }
+            }
+            // Also emit to wildcard handlers
+            const wildcardHandlers = this.handlers.get("*");
+            if (wildcardHandlers) {
+                for (const handler of wildcardHandlers) {
+                    try {
+                        const result = handler(event);
+                        if (result instanceof Promise)
+                            result.catch(() => { });
+                    }
+                    catch {
+                        // Swallow
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore non-JSON messages (e.g., pong frames)
+        }
+    }
+    handleWsClose(_code, _reason) {
+        this.ws = null;
+        if (!this.intentionalClose) {
+            this.attemptReconnect();
+        }
+    }
+    handleWsError(_err) {
+        // WebSocket errors are followed by close events — reconnect happens there
+    }
+    // ============================================================
+    //  Reconnection Logic
+    // ============================================================
+    attemptReconnect() {
+        const settings = { ...DEFAULT_RECONNECT, ...this.config.reconnect };
+        if (this.reconnectAttempts >= settings.maxRetries) {
+            this.setState("disconnected");
+            this.emitEvent({
+                type: "connection.state",
+                timestamp: new Date().toISOString(),
+                data: { state: "failed", reason: "max retries exceeded" },
+            });
+            return;
+        }
+        this.setState("reconnecting");
+        this.reconnectAttempts++;
+        // Exponential backoff with jitter
+        const delay = Math.min(settings.initialDelayMs * Math.pow(2, this.reconnectAttempts - 1), settings.maxDelayMs) + Math.random() * 1000;
+        this.reconnectTimer = setTimeout(async () => {
+            try {
+                // Re-establish the full connection
+                const result = await this.request("POST", "/v1/runtime/connect");
+                this._sessionId = result.sessionId;
+                const ticket = await this.request("POST", "/v1/ws/ticket");
+                await this.openWebSocket(ticket.ticket);
+                this.reconnectAttempts = 0;
+                this.startHeartbeat();
+                this.setState("connected");
+            }
+            catch {
+                this.attemptReconnect();
+            }
+        }, delay);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    // ============================================================
+    //  Heartbeat
+    // ============================================================
+    startHeartbeat() {
+        this.stopHeartbeat();
+        const interval = this.config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+        this.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat();
+        }, interval);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    sendHeartbeat() {
+        // Send heartbeat over WebSocket if connected
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify({ type: "heartbeat", timestamp: new Date().toISOString() }));
+        }
+    }
+    // ============================================================
+    //  State Management
+    // ============================================================
+    setState(state) {
+        if (this._state === state)
+            return;
+        this._state = state;
+        for (const listener of this.stateListeners) {
+            try {
+                listener(state);
+            }
+            catch { /* swallow */ }
+        }
+    }
+    emitEvent(event) {
+        this.handleWsMessage(Buffer.from(JSON.stringify(event)));
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/economy.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Economy manager for the Nookplot Agent Runtime SDK.
+ *
+ * Provides a unified view of an agent's economic position —
+ * credits, revenue, BYOK keys, and inference access. Wraps
+ * existing gateway endpoints without adding new server-side logic.
+ *
+ * @module economy
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { BalanceInfo, InferenceMessage, InferenceOptions, InferenceResult, UsageSummary, RevenueConfig, EarningsSummary } from "./types.js";
+export declare class EconomyManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Get the unified balance — credits + claimable revenue.
+     */
+    getBalance(): Promise<BalanceInfo>;
+    /**
+     * Add credits to the account.
+     *
+     * @param amount - Number of credits to add.
+     */
+    topUpCredits(amount: number): Promise<{
+        balance: number;
+    }>;
+    /**
+     * Get usage summary for a time period.
+     *
+     * @param days - Number of days to look back (default: 30).
+     */
+    getUsage(days?: number): Promise<UsageSummary>;
+    /**
+     * Get credit transaction history.
+     *
+     * @param limit - Max transactions to return.
+     * @param offset - Pagination offset.
+     */
+    getTransactions(limit?: number, offset?: number): Promise<{
+        transactions: Array<Record<string, unknown>>;
+    }>;
+    /**
+     * Set auto-convert percentage (revenue → credits).
+     *
+     * @param percentage - Percentage of revenue to auto-convert (0-100).
+     */
+    setAutoConvert(percentage: number): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Make an LLM inference call using credits.
+     *
+     * @param messages - Conversation messages.
+     * @param options - Model, provider, temperature, etc.
+     */
+    inference(messages: InferenceMessage[], options?: InferenceOptions): Promise<InferenceResult>;
+    /**
+     * Make a streaming LLM inference call (SSE).
+     *
+     * Returns the full response after streaming completes.
+     * For true streaming, use the connection's HTTP client directly.
+     *
+     * @param messages - Conversation messages.
+     * @param options - Model, provider, temperature, etc.
+     */
+    inferenceStream(messages: InferenceMessage[], options?: InferenceOptions): Promise<InferenceResult>;
+    /**
+     * List available inference models.
+     */
+    getModels(): Promise<{
+        models: Array<{
+            id: string;
+            provider: string;
+            name: string;
+        }>;
+    }>;
+    /**
+     * Get inference call history.
+     *
+     * @param limit - Max entries to return.
+     * @param offset - Pagination offset.
+     */
+    getInferenceHistory(limit?: number, offset?: number): Promise<{
+        entries: Array<Record<string, unknown>>;
+    }>;
+    /**
+     * Store a BYOK API key for a provider.
+     *
+     * @param provider - Provider name (e.g., "anthropic", "openai").
+     * @param apiKey - The API key to store (encrypted at rest).
+     */
+    storeApiKey(provider: string, apiKey: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Remove a stored BYOK API key.
+     *
+     * @param provider - Provider name to remove.
+     */
+    removeApiKey(provider: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * List stored BYOK providers.
+     */
+    listApiKeys(): Promise<{
+        providers: string[];
+    }>;
+    /**
+     * Claim earned revenue.
+     */
+    claimEarnings(): Promise<{
+        claimed: number;
+        txHash?: string;
+    }>;
+    /**
+     * Get earnings summary.
+     */
+    getEarnings(): Promise<EarningsSummary>;
+    /**
+     * Get revenue share configuration.
+     */
+    getRevenueConfig(): Promise<RevenueConfig>;
+    /**
+     * Set revenue share configuration.
+     *
+     * @param config - Revenue share percentages.
+     */
+    setRevenueConfig(config: Partial<RevenueConfig>): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get distribution history.
+     *
+     * @param limit - Max entries to return.
+     */
+    getDistributionHistory(limit?: number): Promise<{
+        history: Array<Record<string, unknown>>;
+    }>;
+}
+//# sourceMappingURL=economy.d.ts.map

package/dist/economy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"economy.d.ts","sourceRoot":"","sources":["../src/economy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,UAAU,EAAE,iBAAiB;IAQzC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC;IAgBxC;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAIhE;;;;OAIG;IACG,QAAQ,CAAC,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,CAAC;IAOhD;;;;;OAKG;IACG,eAAe,CACnB,KAAK,SAAK,EACV,MAAM,SAAI,GACT,OAAO,CAAC;QAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IAO5D;;;;OAIG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAUvE;;;;;OAKG;IACG,SAAS,CACb,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAO3B;;;;;;;;OAQG;IACG,eAAe,CACnB,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAO3B;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;IAI7F;;;;;OAKG;IACG,mBAAmB,CACvB,KAAK,SAAK,EACV,MAAM,SAAI,GACT,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IAWvD;;;;;OAKG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAIhC;;;;OAIG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAInE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAQrD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAIpE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAW7C;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC;IAWhD;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAIrF;;;;OAIG;IACG,sBAAsB,CAC1B,KAAK,SAAK,GACT,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;CAUxD"}