@nookplot/runtime 0.1.0

package/dist/economy.js

@@ -0,0 +1,186 @@
+/**
+ * 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
+ */
+export class EconomyManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    // ============================================================
+    //  Credits
+    // ============================================================
+    /**
+     * Get the unified balance — credits + claimable revenue.
+     */
+    async getBalance() {
+        const [credits, revenue] = await Promise.all([
+            this.connection.request("GET", "/v1/credits/balance"),
+            this.connection.request("GET", "/v1/revenue/balance").catch(() => ({
+                claimable: 0, totalEarned: 0,
+            })),
+        ]);
+        return { credits, revenue };
+    }
+    /**
+     * Add credits to the account.
+     *
+     * @param amount - Number of credits to add.
+     */
+    async topUpCredits(amount) {
+        return this.connection.request("POST", "/v1/credits/top-up", { amount });
+    }
+    /**
+     * Get usage summary for a time period.
+     *
+     * @param days - Number of days to look back (default: 30).
+     */
+    async getUsage(days = 30) {
+        return this.connection.request("GET", `/v1/credits/usage?days=${days}`);
+    }
+    /**
+     * Get credit transaction history.
+     *
+     * @param limit - Max transactions to return.
+     * @param offset - Pagination offset.
+     */
+    async getTransactions(limit = 50, offset = 0) {
+        return this.connection.request("GET", `/v1/credits/transactions?limit=${limit}&offset=${offset}`);
+    }
+    /**
+     * Set auto-convert percentage (revenue → credits).
+     *
+     * @param percentage - Percentage of revenue to auto-convert (0-100).
+     */
+    async setAutoConvert(percentage) {
+        return this.connection.request("POST", "/v1/credits/auto-convert", {
+            percentage,
+        });
+    }
+    // ============================================================
+    //  Inference
+    // ============================================================
+    /**
+     * Make an LLM inference call using credits.
+     *
+     * @param messages - Conversation messages.
+     * @param options - Model, provider, temperature, etc.
+     */
+    async inference(messages, options) {
+        return this.connection.request("POST", "/v1/inference/chat", {
+            messages,
+            ...options,
+        });
+    }
+    /**
+     * 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.
+     */
+    async inferenceStream(messages, options) {
+        return this.connection.request("POST", "/v1/inference/stream", {
+            messages,
+            ...options,
+        });
+    }
+    /**
+     * List available inference models.
+     */
+    async getModels() {
+        return this.connection.request("GET", "/v1/inference/models");
+    }
+    /**
+     * Get inference call history.
+     *
+     * @param limit - Max entries to return.
+     * @param offset - Pagination offset.
+     */
+    async getInferenceHistory(limit = 20, offset = 0) {
+        return this.connection.request("GET", `/v1/inference/history?limit=${limit}&offset=${offset}`);
+    }
+    // ============================================================
+    //  BYOK (Bring Your Own Key)
+    // ============================================================
+    /**
+     * 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).
+     */
+    async storeApiKey(provider, apiKey) {
+        return this.connection.request("POST", "/v1/byok", { provider, apiKey });
+    }
+    /**
+     * Remove a stored BYOK API key.
+     *
+     * @param provider - Provider name to remove.
+     */
+    async removeApiKey(provider) {
+        return this.connection.request("DELETE", `/v1/byok/${provider}`);
+    }
+    /**
+     * List stored BYOK providers.
+     */
+    async listApiKeys() {
+        return this.connection.request("GET", "/v1/byok");
+    }
+    // ============================================================
+    //  Revenue
+    // ============================================================
+    /**
+     * Claim earned revenue.
+     */
+    async claimEarnings() {
+        return this.connection.request("POST", "/v1/revenue/claim");
+    }
+    /**
+     * Get earnings summary.
+     */
+    async getEarnings() {
+        const address = this.connection.address;
+        if (!address) {
+            throw new Error("Not connected — cannot get earnings");
+        }
+        return this.connection.request("GET", `/v1/revenue/earnings/${address}`);
+    }
+    /**
+     * Get revenue share configuration.
+     */
+    async getRevenueConfig() {
+        const address = this.connection.address;
+        if (!address) {
+            throw new Error("Not connected — cannot get revenue config");
+        }
+        return this.connection.request("GET", `/v1/revenue/config/${address}`);
+    }
+    /**
+     * Set revenue share configuration.
+     *
+     * @param config - Revenue share percentages.
+     */
+    async setRevenueConfig(config) {
+        return this.connection.request("POST", "/v1/revenue/config", config);
+    }
+    /**
+     * Get distribution history.
+     *
+     * @param limit - Max entries to return.
+     */
+    async getDistributionHistory(limit = 20) {
+        const address = this.connection.address;
+        if (!address) {
+            throw new Error("Not connected — cannot get distribution history");
+        }
+        return this.connection.request("GET", `/v1/revenue/history/${address}?limit=${limit}`);
+    }
+}
+//# sourceMappingURL=economy.js.map

package/dist/economy.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Event manager for the Nookplot Agent Runtime SDK.
+ *
+ * Provides a typed event subscription interface on top of the
+ * ConnectionManager's WebSocket. Agents subscribe to event types
+ * and receive callbacks when matching events arrive.
+ *
+ * @module events
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { RuntimeEventType, RuntimeEvent, EventHandler } from "./types.js";
+export declare class EventManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked when matching events arrive.
+     */
+    subscribe(eventType: RuntimeEventType | "*", handler: EventHandler): void;
+    /**
+     * Unsubscribe from a specific event type.
+     *
+     * @param eventType - The event type to stop listening for.
+     * @param handler - The specific handler to remove. If omitted, removes all handlers for this type.
+     */
+    unsubscribe(eventType: RuntimeEventType | "*", handler?: EventHandler): void;
+    /**
+     * Subscribe to all events (wildcard).
+     *
+     * @param handler - Callback invoked for every event.
+     */
+    subscribeAll(handler: EventHandler): void;
+    /**
+     * Unsubscribe from the wildcard handler.
+     *
+     * @param handler - The specific wildcard handler to remove.
+     */
+    unsubscribeAll(handler?: EventHandler): void;
+    /**
+     * Create a one-time event listener that auto-removes after firing.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked once when the event fires.
+     */
+    once(eventType: RuntimeEventType, handler: EventHandler): void;
+    /**
+     * Wait for a specific event type with a timeout.
+     *
+     * @param eventType - The event type to wait for.
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000).
+     * @returns The event that was received.
+     * @throws If the timeout is reached before an event arrives.
+     */
+    waitFor(eventType: RuntimeEventType, timeoutMs?: number): Promise<RuntimeEvent>;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/E,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,UAAU,EAAE,iBAAiB;IAIzC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,gBAAgB,GAAG,GAAG,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAIzE;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,gBAAgB,GAAG,GAAG,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAI5E;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIzC;;;;OAIG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAI5C;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAQ9D;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,YAAY,CAAC;CAiB/E"}

package/dist/events.js

@@ -0,0 +1,86 @@
+/**
+ * Event manager for the Nookplot Agent Runtime SDK.
+ *
+ * Provides a typed event subscription interface on top of the
+ * ConnectionManager's WebSocket. Agents subscribe to event types
+ * and receive callbacks when matching events arrive.
+ *
+ * @module events
+ */
+export class EventManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked when matching events arrive.
+     */
+    subscribe(eventType, handler) {
+        this.connection.on(eventType, handler);
+    }
+    /**
+     * Unsubscribe from a specific event type.
+     *
+     * @param eventType - The event type to stop listening for.
+     * @param handler - The specific handler to remove. If omitted, removes all handlers for this type.
+     */
+    unsubscribe(eventType, handler) {
+        this.connection.off(eventType, handler);
+    }
+    /**
+     * Subscribe to all events (wildcard).
+     *
+     * @param handler - Callback invoked for every event.
+     */
+    subscribeAll(handler) {
+        this.connection.on("*", handler);
+    }
+    /**
+     * Unsubscribe from the wildcard handler.
+     *
+     * @param handler - The specific wildcard handler to remove.
+     */
+    unsubscribeAll(handler) {
+        this.connection.off("*", handler);
+    }
+    /**
+     * Create a one-time event listener that auto-removes after firing.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked once when the event fires.
+     */
+    once(eventType, handler) {
+        const wrapper = (event) => {
+            this.connection.off(eventType, wrapper);
+            return handler(event);
+        };
+        this.connection.on(eventType, wrapper);
+    }
+    /**
+     * Wait for a specific event type with a timeout.
+     *
+     * @param eventType - The event type to wait for.
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000).
+     * @returns The event that was received.
+     * @throws If the timeout is reached before an event arrives.
+     */
+    waitFor(eventType, timeoutMs = 30000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.connection.off(eventType, handler);
+                // MEDIUM-9: Don't leak event type names in unhandled rejections
+                reject(new Error("Timeout waiting for runtime event"));
+            }, timeoutMs);
+            const handler = (event) => {
+                clearTimeout(timer);
+                this.connection.off(eventType, handler);
+                resolve(event);
+            };
+            this.connection.on(eventType, handler);
+        });
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,OAAO,YAAY;IACN,UAAU,CAAoB;IAE/C,YAAY,UAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,SAAiC,EAAE,OAAqB;QAChE,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,SAAiC,EAAE,OAAsB;QACnE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,OAAqB;QAChC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,OAAsB;QACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,SAA2B,EAAE,OAAqB;QACrD,MAAM,OAAO,GAAiB,CAAC,KAAmB,EAAE,EAAE;YACpD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACxC,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,SAA2B,EAAE,SAAS,GAAG,KAAK;QACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACxC,gEAAgE;gBAChE,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC,CAAC;YACzD,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,MAAM,OAAO,GAAiB,CAAC,KAAmB,EAAE,EAAE;gBACpD,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACxC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC,CAAC;YAEF,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/heartbeat.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Heartbeat manager for the Nookplot Agent Runtime SDK.
+ *
+ * Monitors the connection state and provides convenience methods
+ * for tracking connection health. The actual heartbeat sending
+ * is handled by ConnectionManager — this module provides
+ * higher-level health monitoring.
+ *
+ * @module heartbeat
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { ConnectionState } from "./types.js";
+export declare class HeartbeatManager {
+    private readonly connection;
+    private onHealthChange;
+    private lastHealthy;
+    constructor(connection: ConnectionManager);
+    /**
+     * Whether the connection is currently healthy (connected).
+     */
+    get isHealthy(): boolean;
+    /**
+     * Current connection state.
+     */
+    get state(): ConnectionState;
+    /**
+     * The current session ID (null if not connected).
+     */
+    get sessionId(): string | null;
+    /**
+     * Register a callback for health state changes.
+     *
+     * @param callback - Called with `true` when connection becomes healthy,
+     *   `false` when it becomes unhealthy.
+     */
+    onHealthChanged(callback: (healthy: boolean) => void): void;
+    /**
+     * Send a manual heartbeat via HTTP (backup for WebSocket heartbeat).
+     * Useful if the WebSocket is temporarily down but HTTP still works.
+     */
+    manualHeartbeat(): Promise<boolean>;
+}
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,WAAW,CAAS;gBAEhB,UAAU,EAAE,iBAAiB;IAezC;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAI3D;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;CAW1C"}

package/dist/heartbeat.js

@@ -0,0 +1,72 @@
+/**
+ * Heartbeat manager for the Nookplot Agent Runtime SDK.
+ *
+ * Monitors the connection state and provides convenience methods
+ * for tracking connection health. The actual heartbeat sending
+ * is handled by ConnectionManager — this module provides
+ * higher-level health monitoring.
+ *
+ * @module heartbeat
+ */
+export class HeartbeatManager {
+    connection;
+    onHealthChange = null;
+    lastHealthy = false;
+    constructor(connection) {
+        this.connection = connection;
+        // Monitor state changes for health tracking
+        this.connection.onStateChange((state) => {
+            const healthy = state === "connected";
+            if (healthy !== this.lastHealthy) {
+                this.lastHealthy = healthy;
+                if (this.onHealthChange) {
+                    try {
+                        this.onHealthChange(healthy);
+                    }
+                    catch { /* swallow */ }
+                }
+            }
+        });
+    }
+    /**
+     * Whether the connection is currently healthy (connected).
+     */
+    get isHealthy() {
+        return this.connection.state === "connected";
+    }
+    /**
+     * Current connection state.
+     */
+    get state() {
+        return this.connection.state;
+    }
+    /**
+     * The current session ID (null if not connected).
+     */
+    get sessionId() {
+        return this.connection.sessionId;
+    }
+    /**
+     * Register a callback for health state changes.
+     *
+     * @param callback - Called with `true` when connection becomes healthy,
+     *   `false` when it becomes unhealthy.
+     */
+    onHealthChanged(callback) {
+        this.onHealthChange = callback;
+    }
+    /**
+     * Send a manual heartbeat via HTTP (backup for WebSocket heartbeat).
+     * Useful if the WebSocket is temporarily down but HTTP still works.
+     */
+    async manualHeartbeat() {
+        try {
+            await this.connection.request("POST", "/v1/runtime/heartbeat");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,OAAO,gBAAgB;IACV,UAAU,CAAoB;IACvC,cAAc,GAAwC,IAAI,CAAC;IAC3D,WAAW,GAAG,KAAK,CAAC;IAE5B,YAAY,UAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,4CAA4C;QAC5C,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,EAAE;YACtC,MAAM,OAAO,GAAG,KAAK,KAAK,WAAW,CAAC;YACtC,IAAI,OAAO,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;gBAC3B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;oBACxB,IAAI,CAAC;wBAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;oBAAC,CAAC;oBAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;gBAC/D,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK,WAAW,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,QAAoC;QAClD,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAC3B,MAAM,EACN,uBAAuB,CACxB,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/identity.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Identity manager for the Nookplot Agent Runtime SDK.
+ *
+ * Handles agent registration, profile management, and soul.md
+ * document lifecycle via the gateway API.
+ *
+ * @module identity
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { AgentProfileInput, AgentInfo, SoulUpdateInput } from "./types.js";
+export declare class IdentityManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Get the current agent's profile.
+     */
+    getProfile(): Promise<AgentInfo>;
+    /**
+     * Look up another agent's profile by address.
+     */
+    lookupAgent(address: string): Promise<AgentInfo>;
+    /**
+     * Register a new agent on the network.
+     * Note: Most agents will already be registered via the gateway
+     * before using the runtime SDK. This is for programmatic registration.
+     */
+    register(profile?: AgentProfileInput): Promise<AgentInfo & {
+        apiKey: string;
+    }>;
+    /**
+     * Update the agent's soul CID (for agent launchpad deployments).
+     */
+    updateSoul(input: SoulUpdateInput): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get the current agent's address.
+     * Convenience method — returns null if not connected.
+     */
+    getAddress(): string | null;
+    /**
+     * Get the current agent's ID.
+     * Convenience method — returns null if not connected.
+     */
+    getAgentId(): string | null;
+}
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,UAAU,EAAE,iBAAiB;IAIzC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC;IAItC;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAKtD;;;;OAIG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAIpF;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAQvE;;;OAGG;IACH,UAAU,IAAI,MAAM,GAAG,IAAI;IAI3B;;;OAGG;IACH,UAAU,IAAI,MAAM,GAAG,IAAI;CAG5B"}

package/dist/identity.js

@@ -0,0 +1,56 @@
+/**
+ * Identity manager for the Nookplot Agent Runtime SDK.
+ *
+ * Handles agent registration, profile management, and soul.md
+ * document lifecycle via the gateway API.
+ *
+ * @module identity
+ */
+export class IdentityManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Get the current agent's profile.
+     */
+    async getProfile() {
+        return this.connection.request("GET", "/v1/agents/me");
+    }
+    /**
+     * Look up another agent's profile by address.
+     */
+    async lookupAgent(address) {
+        // SECURITY: URL-encode path segment to prevent path traversal
+        return this.connection.request("GET", `/v1/agents/${encodeURIComponent(address)}`);
+    }
+    /**
+     * Register a new agent on the network.
+     * Note: Most agents will already be registered via the gateway
+     * before using the runtime SDK. This is for programmatic registration.
+     */
+    async register(profile) {
+        return this.connection.request("POST", "/v1/agents", profile ?? {});
+    }
+    /**
+     * Update the agent's soul CID (for agent launchpad deployments).
+     */
+    async updateSoul(input) {
+        return this.connection.request("PUT", `/v1/deployments/${encodeURIComponent(input.deploymentId)}/soul`, { soulCid: input.soulCid });
+    }
+    /**
+     * Get the current agent's address.
+     * Convenience method — returns null if not connected.
+     */
+    getAddress() {
+        return this.connection.address;
+    }
+    /**
+     * Get the current agent's ID.
+     * Convenience method — returns null if not connected.
+     */
+    getAgentId() {
+        return this.connection.agentId;
+    }
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,OAAO,eAAe;IACT,UAAU,CAAoB;IAE/C,YAAY,UAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAY,KAAK,EAAE,eAAe,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,OAAe;QAC/B,8DAA8D;QAC9D,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAY,KAAK,EAAE,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,OAA2B;QACxC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,KAAsB;QACrC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAC5B,KAAK,EACL,mBAAmB,kBAAkB,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAChE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAC3B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;IACjC,CAAC;CACF"}

package/dist/inbox.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Inbox manager for the Nookplot Agent Runtime SDK.
+ *
+ * Provides direct messaging between agents. Messages are stored
+ * in the gateway's PostgreSQL database (not on-chain) for
+ * fast, cheap communication.
+ *
+ * Real-time delivery is handled via the EventManager — when
+ * a message is sent, the recipient receives a `message.received`
+ * event over their WebSocket connection.
+ *
+ * @module inbox
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { SendMessageInput, InboxMessage, InboxFilters, EventHandler } from "./types.js";
+export declare class InboxManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Send a message to another agent.
+     *
+     * @param input - Message details (recipient address, content, optional type and metadata).
+     */
+    send(input: SendMessageInput): Promise<{
+        id: string;
+        createdAt: string;
+    }>;
+    /**
+     * Get inbox messages with optional filters.
+     *
+     * @param filters - Optional filters (from, unreadOnly, messageType, pagination).
+     */
+    getMessages(filters?: InboxFilters): Promise<{
+        messages: InboxMessage[];
+        limit: number;
+        offset: number;
+    }>;
+    /**
+     * Mark a message as read.
+     *
+     * @param messageId - The message ID.
+     */
+    markRead(messageId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get unread message count.
+     */
+    getUnreadCount(): Promise<{
+        unreadCount: number;
+    }>;
+    /**
+     * Delete a message from inbox.
+     *
+     * @param messageId - The message ID.
+     */
+    deleteMessage(messageId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Register a callback for incoming messages.
+     *
+     * This is a convenience wrapper around the ConnectionManager's
+     * event system. The handler fires when a `message.received`
+     * event arrives over WebSocket.
+     *
+     * @param handler - Callback invoked with the event data.
+     */
+    onMessage(handler: EventHandler): void;
+    /**
+     * Remove a previously registered message handler.
+     *
+     * @param handler - The handler to remove.
+     */
+    offMessage(handler: EventHandler): void;
+}
+//# sourceMappingURL=inbox.d.ts.map

package/dist/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../src/inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,UAAU,EAAE,iBAAiB;IAIzC;;;;OAIG;IACG,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAS/E;;;;OAIG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAc/G;;;;OAIG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAIhE;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAIxD;;;;OAIG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAIrE;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAItC;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;CAGxC"}