rice-node-sdk 1.0.6 → 1.0.7

package/README.md

@@ -266,6 +266,25 @@ console.log(cycleResult.planningTimeMs);
 const history = await client.state.getCycleHistory(10);
 ```
 
+### Pub/Sub (Real-time Events)
+
+Subscribe to real-time events from the State service, such as variable updates or memory commits. This is useful for multi-agent coordination.
+
+```typescript
+// Subscribe to variable updates
+const stream = client.state.subscribe(["VariableUpdate"]);
+
+stream.on("data", (event) => {
+  console.log("Received event:", event.type);
+  if (event.type === "VariableUpdate") {
+    const variable = JSON.parse(event.payload);
+    console.log(`Variable ${variable.name} updated to:`, variable.value_json);
+  }
+});
+
+stream.on("error", (err) => console.error("Stream error:", err));
+```
+
 ## AI Tool Definitions
 
 The SDK provides pre-built tool definitions tailored for popular LLM providers. These tools map directly to State memory operations.
@@ -408,6 +427,7 @@ if (call) {
 | `getActionLog`    | Get the action log for the current run           | `client.state.getActionLog()`    |
 | `runCycle`        | Run a decision cycle with action candidates      | `client.state.runCycle()`        |
 | `getCycleHistory` | Get history of decision cycles                   | `client.state.getCycleHistory()` |
+| `subscribe`       | Subscribe to real-time state events              | `client.state.subscribe()`       |
 
 ## API Reference
 
@@ -489,8 +509,12 @@ interface StateClient {
   ): Promise<CycleResult>;
   getCycleHistory(limit?: number): Promise<CycleResult[]>;
 
+  // Events
+  subscribe(eventTypes?: string[]): NodeJS.EventEmitter;
+
   // Session Management
   setRunId(runId: string): void;
+
   deleteRun(): Promise<boolean>;
 
   // Skills

package/dist/state/index.d.ts

@@ -148,4 +148,13 @@ export declare class StateClient {
      * @returns A promise that resolves to an array of cycle records.
      */
     getCycleHistory(limit?: number): Promise<any[]>;
+    /**
+     * Subscribe to real-time events for the current run_id.
+     * Returns a gRPC ClientReadableStream that emits 'data', 'error', and 'end' events.
+     *
+     * usage:
+     * const stream = client.subscribe();
+     * stream.on('data', (event: any) => { ... });
+     */
+    subscribe(eventTypes?: string[]): any;
 }

package/dist/state/index.js

@@ -506,5 +506,25 @@ class StateClient {
             });
         });
     }
+    // ==========================================================================
+    // Events (Pub/Sub)
+    // ==========================================================================
+    /**
+     * Subscribe to real-time events for the current run_id.
+     * Returns a gRPC ClientReadableStream that emits 'data', 'error', and 'end' events.
+     *
+     * usage:
+     * const stream = client.subscribe();
+     * stream.on('data', (event: any) => { ... });
+     */
+    subscribe(eventTypes = []) {
+        const request = {
+            run_id: this.runId,
+            event_types: eventTypes,
+        };
+        // For streaming RPCs, we don't provide a callback.
+        // The call object itself is the stream.
+        return this.client.Subscribe(request, this.metadata);
+    }
 }
 exports.StateClient = StateClient;

package/dist/state/proto/state.proto

@@ -41,6 +41,9 @@ service Cortex {
 
   // Management
   rpc DeleteRun(RunRequest) returns (Ack);
+
+  // Events
+  rpc Subscribe(SubscribeRequest) returns (stream Event);
 }
 
 message FocusRequest {
@@ -292,3 +295,17 @@ message CycleHistoryRequest {
 message CycleHistoryResponse {
   repeated CycleResponse cycles = 1;
 }
+
+message SubscribeRequest {
+  string run_id = 1;
+  repeated string event_types = 2; // Optional filter e.g. ["Focus", "Commit"]
+}
+
+message Event {
+  string id = 1;
+  string type = 2; // "Focus", "Commit", "VariableUpdate", "GoalUpdate"
+  string run_id = 3;
+  string agent_id = 4;
+  string payload = 5; // JSON string of the object involved
+  string created_at = 6;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rice-node-sdk",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "description": "SDK for Rice",
     "repository": {
         "type": "git",