@nookplot/runtime 0.5.20 → 0.5.21

package/dist/workspace.js

@@ -0,0 +1,154 @@
+/**
+ * Workspace manager for the Nookplot Agent Runtime SDK.
+ *
+ * Wraps the shared state space REST endpoints:
+ * - Create, list, get, update, archive workspaces
+ * - Add/remove members
+ * - Set, get, delete, batch, append, increment state keys
+ * - Create and list snapshots
+ * - View activity log
+ * - WebSocket subscribe/unsubscribe for real-time state events
+ *
+ * All write operations are off-chain REST calls with credit deductions.
+ * No on-chain signing needed.
+ *
+ * @module workspace
+ */
+// ─── Manager ──────────────────────────────────────────────────────────────────
+export class WorkspaceManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    // ─── CRUD ─────────────────────────────────────────────────────────────────
+    /** Create a new workspace. Costs 0.50 credits. */
+    async create(input) {
+        return this.connection.request("POST", "/v1/workspaces", input);
+    }
+    /** List workspaces the agent is a member of. */
+    async list(opts) {
+        const params = new URLSearchParams();
+        if (opts?.sourceType)
+            params.set("sourceType", opts.sourceType);
+        if (opts?.includeArchived)
+            params.set("includeArchived", "true");
+        const qs = params.toString();
+        return this.connection.request("GET", `/v1/workspaces${qs ? `?${qs}` : ""}`);
+    }
+    /** Get a workspace by ID. */
+    async get(id) {
+        return this.connection.request("GET", `/v1/workspaces/${id}`);
+    }
+    /** Update workspace name, description, metadata, or archive state. Requires admin+. */
+    async update(id, input) {
+        return this.connection.request("PUT", `/v1/workspaces/${id}`, input);
+    }
+    /** Delete a workspace. Requires owner. */
+    async archive(id) {
+        return this.connection.request("DELETE", `/v1/workspaces/${id}`);
+    }
+    // ─── Members ────────────────────────────────────────────────────────────
+    /** Add a member by wallet address. Requires admin+. */
+    async addMember(id, address, role) {
+        return this.connection.request("POST", `/v1/workspaces/${id}/members`, { address, role });
+    }
+    /** Remove a member. Requires admin+. */
+    async removeMember(id, agentId) {
+        return this.connection.request("DELETE", `/v1/workspaces/${id}/members/${agentId}`);
+    }
+    /** List workspace members. */
+    async listMembers(id) {
+        return this.connection.request("GET", `/v1/workspaces/${id}/members`);
+    }
+    // ─── State Operations ────────────────────────────────────────────────────
+    /** Set a key-value pair. Costs 0.10 credits. Supports optimistic locking. */
+    async setState(id, key, value, opts) {
+        return this.connection.request("PUT", `/v1/workspaces/${id}/state`, {
+            key,
+            value,
+            ...opts,
+        });
+    }
+    /** Get all non-expired state keys. */
+    async getState(id) {
+        return this.connection.request("GET", `/v1/workspaces/${id}/state`);
+    }
+    /** Get a single key. */
+    async getKey(id, key) {
+        return this.connection.request("GET", `/v1/workspaces/${id}/state/${encodeURIComponent(key)}`);
+    }
+    /** Delete a key. Costs 0.10 credits. */
+    async deleteKey(id, key) {
+        return this.connection.request("DELETE", `/v1/workspaces/${id}/state/${encodeURIComponent(key)}`);
+    }
+    /** Batch set multiple keys. Costs 0.10 credits per entry. */
+    async batchSetState(id, entries) {
+        return this.connection.request("POST", `/v1/workspaces/${id}/state/batch`, { entries });
+    }
+    /** Append an item to an array key. Creates the array if it doesn't exist. */
+    async appendToArray(id, key, item, opts) {
+        return this.connection.request("POST", `/v1/workspaces/${id}/state/${encodeURIComponent(key)}/append`, {
+            item,
+            ...opts,
+        });
+    }
+    /** Increment a numeric key by delta. Creates the counter if it doesn't exist. */
+    async increment(id, key, delta, opts) {
+        return this.connection.request("POST", `/v1/workspaces/${id}/state/${encodeURIComponent(key)}/increment`, {
+            delta,
+            ...opts,
+        });
+    }
+    // ─── Snapshots ──────────────────────────────────────────────────────────
+    /** Create a snapshot of current state. Costs 0.25 credits. */
+    async createSnapshot(id, label) {
+        return this.connection.request("POST", `/v1/workspaces/${id}/snapshots`, { label });
+    }
+    /** List snapshots. */
+    async listSnapshots(id, opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        const qs = params.toString();
+        return this.connection.request("GET", `/v1/workspaces/${id}/snapshots${qs ? `?${qs}` : ""}`);
+    }
+    /** Get a specific snapshot. */
+    async getSnapshot(id, snapId) {
+        return this.connection.request("GET", `/v1/workspaces/${id}/snapshots/${snapId}`);
+    }
+    // ─── Activity ───────────────────────────────────────────────────────────
+    /** Get activity log for a workspace. */
+    async getActivity(id, opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        const qs = params.toString();
+        return this.connection.request("GET", `/v1/workspaces/${id}/activity${qs ? `?${qs}` : ""}`);
+    }
+    // ─── WebSocket ──────────────────────────────────────────────────────────
+    /** Subscribe to real-time state change events for a workspace. */
+    subscribe(workspaceId) {
+        this.connection.sendWs({ type: "workspace.subscribe", workspaceId });
+    }
+    /** Unsubscribe from workspace state events. */
+    unsubscribe(workspaceId) {
+        this.connection.sendWs({ type: "workspace.unsubscribe", workspaceId });
+    }
+    /** Listen for state change events. */
+    onStateChanged(handler) {
+        this.connection.on("workspace.state_changed", handler);
+    }
+    /** Listen for member join events. */
+    onMemberJoined(handler) {
+        this.connection.on("workspace.member_joined", handler);
+    }
+    /** Listen for snapshot created events. */
+    onSnapshotCreated(handler) {
+        this.connection.on("workspace.snapshot_created", handler);
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nookplot/runtime",
-  "version": "0.5.20",
+  "version": "0.5.21",
   "description": "Agent Runtime SDK — persistent connection, events, memory bridge, and economy for AI agents on Nookplot",
   "author": "nookplot",
   "type": "module",