rice-node-sdk 1.0.5 → 1.0.7

package/README.md

@@ -266,15 +266,63 @@ 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.
 
 ### Available Imports
 
-- `rice-node-sdk/tools/anthropic`
-- `rice-node-sdk/tools/google`
-- `rice-node-sdk/tools/openai`
+- `rice-node-sdk/tools/anthropic` - Anthropic Claude format
+- `rice-node-sdk/tools/google` - Google Gemini format
+- `rice-node-sdk/tools/openai` - OpenAI function calling format
+- `rice-node-sdk/tools/vercel` - Vercel AI SDK format (with bound execute functions)
+
+### Example Usage (Vercel AI SDK)
+
+The Vercel AI SDK tools come with execute functions pre-bound to your StateClient, making integration seamless.
+
+```typescript
+import { generateText, stepCountIs } from "ai";
+import { google } from "@ai-sdk/google";
+import { Client, statetool } from "rice-node-sdk";
+
+const client = new Client({ runId: "my-agent-session" });
+await client.connect();
+
+// Create tools bound to your StateClient
+const tools = statetool.createVercelTools(client.state);
+
+// Use with generateText - tools are auto-executed!
+const result = await generateText({
+  model: google("gemini-2.0-flash"),
+  tools,
+  stopWhen: stepCountIs(5),
+  system: `You are an assistant with persistent memory.
+Use 'remember' to store facts and 'recall' to search memories.`,
+  prompt: "Remember that I prefer Python for ML projects.",
+});
+
+console.log(result.text);
+```
 
 ### Example Usage (Anthropic)
 
@@ -359,20 +407,27 @@ if (call) {
 
 ### Tools Included
 
-| Tool             | Purpose                                          | SDK Method                      |
-| ---------------- | ------------------------------------------------ | ------------------------------- |
-| `focus`          | Store information in short-term working memory   | `client.state.focus()`          |
-| `remember`       | Store information in long-term persistent memory | `client.state.commit()`         |
-| `recall`         | Retrieve relevant memories from long-term memory | `client.state.reminisce()`      |
-| `setVariable`    | Set a structured variable in working memory      | `client.state.setVariable()`    |
-| `getVariable`    | Get a structured variable from working memory    | `client.state.getVariable()`    |
-| `listVariables`  | List all variables in working memory             | `client.state.listVariables()`  |
-| `deleteVariable` | Delete a variable from working memory            | `client.state.deleteVariable()` |
-| `addGoal`        | Add a new goal to the agent's goal stack         | `client.state.addGoal()`        |
-| `updateGoal`     | Update the status of an existing goal            | `client.state.updateGoal()`     |
-| `listGoals`      | List all goals, optionally filtered by status    | `client.state.listGoals()`      |
-| `submitAction`   | Submit an action for execution and logging       | `client.state.submitAction()`   |
-| `getActionLog`   | Get the action log for the current run           | `client.state.getActionLog()`   |
+| Tool              | Purpose                                          | SDK Method                       |
+| ----------------- | ------------------------------------------------ | -------------------------------- |
+| `focus`           | Store information in short-term working memory   | `client.state.focus()`           |
+| `drift`           | Read current items from short-term memory        | `client.state.drift()`           |
+| `remember`        | Store information in long-term persistent memory | `client.state.commit()`          |
+| `recall`          | Retrieve relevant memories from long-term memory | `client.state.reminisce()`       |
+| `trigger`         | Trigger a registered skill or procedure          | `client.state.trigger()`         |
+| `setVariable`     | Set a structured variable in working memory      | `client.state.setVariable()`     |
+| `getVariable`     | Get a structured variable from working memory    | `client.state.getVariable()`     |
+| `listVariables`   | List all variables in working memory             | `client.state.listVariables()`   |
+| `deleteVariable`  | Delete a variable from working memory            | `client.state.deleteVariable()`  |
+| `defineConcept`   | Define a concept with JSON schema                | `client.state.defineConcept()`   |
+| `listConcepts`    | List all defined concepts                        | `client.state.listConcepts()`    |
+| `addGoal`         | Add a new goal to the agent's goal stack         | `client.state.addGoal()`         |
+| `updateGoal`      | Update the status of an existing goal            | `client.state.updateGoal()`      |
+| `listGoals`       | List all goals, optionally filtered by status    | `client.state.listGoals()`       |
+| `submitAction`    | Submit an action for execution and logging       | `client.state.submitAction()`    |
+| `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
 
@@ -454,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/index.d.ts

@@ -1474,6 +1474,7 @@ declare const _default: {
             };
         })[];
         execute: typeof import("./tools/execute").execute;
+        createVercelTools: typeof import("./tools/vercel").createStateTools;
     };
 };
 export default _default;

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/dist/state/tools.d.ts

@@ -1,4 +1,5 @@
 import { execute } from "../tools/execute";
+import { createStateTools } from "../tools/vercel";
 export declare const statetool: {
     google: ({
         name: string;
@@ -1463,4 +1464,5 @@ export declare const statetool: {
         };
     })[];
     execute: typeof execute;
+    createVercelTools: typeof createStateTools;
 };

package/dist/state/tools.js

@@ -5,9 +5,11 @@ const google_1 = require("../tools/google");
 const openai_1 = require("../tools/openai");
 const anthropic_1 = require("../tools/anthropic");
 const execute_1 = require("../tools/execute");
+const vercel_1 = require("../tools/vercel");
 exports.statetool = {
     google: google_1.state,
     openai: openai_1.state,
     anthropic: anthropic_1.state,
     execute: execute_1.execute,
+    createVercelTools: vercel_1.createStateTools,
 };

package/dist/tools/vercel.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Vercel AI SDK v6 compatible tool definitions for Rice State service.
+ *
+ * Usage with Vercel AI SDK:
+ * ```typescript
+ * import { generateText } from 'ai';
+ * import { createStateTools } from 'rice-node-sdk/tools/vercel';
+ *
+ * const tools = createStateTools(client.state);
+ * const result = await generateText({
+ *   model: yourModel,
+ *   tools,
+ *   prompt: 'Remember that I like TypeScript',
+ * });
+ * ```
+ */
+import { StateClient } from "../state";
+/**
+ * Creates Vercel AI SDK v6 compatible tools bound to a StateClient instance.
+ * Each tool uses the `tool()` helper from @ai-sdk/provider-utils for proper typing.
+ */
+export declare function createStateTools(client: StateClient): {
+    focus: import("@ai-sdk/provider-utils").Tool<{
+        content: string;
+    }, string>;
+    drift: import("@ai-sdk/provider-utils").Tool<Record<string, never>, any[]>;
+    recall: import("@ai-sdk/provider-utils").Tool<{
+        query: string;
+    }, any[]>;
+    remember: import("@ai-sdk/provider-utils").Tool<{
+        content: string;
+    }, boolean>;
+    trigger: import("@ai-sdk/provider-utils").Tool<{
+        skillName: string;
+    }, number>;
+    setVariable: import("@ai-sdk/provider-utils").Tool<{
+        name: string;
+        value: any;
+        source?: string;
+    }, boolean>;
+    getVariable: import("@ai-sdk/provider-utils").Tool<{
+        name: string;
+    }, any>;
+    listVariables: import("@ai-sdk/provider-utils").Tool<Record<string, never>, any[]>;
+    deleteVariable: import("@ai-sdk/provider-utils").Tool<{
+        name: string;
+    }, boolean>;
+    defineConcept: import("@ai-sdk/provider-utils").Tool<{
+        name: string;
+        schema: Record<string, any>;
+    }, boolean>;
+    listConcepts: import("@ai-sdk/provider-utils").Tool<Record<string, never>, any[]>;
+    addGoal: import("@ai-sdk/provider-utils").Tool<{
+        description: string;
+        priority?: string;
+        parentId?: string;
+    }, any>;
+    updateGoal: import("@ai-sdk/provider-utils").Tool<{
+        goalId: string;
+        status: string;
+    }, boolean>;
+    listGoals: import("@ai-sdk/provider-utils").Tool<{
+        statusFilter?: string;
+    }, any[]>;
+    submitAction: import("@ai-sdk/provider-utils").Tool<{
+        agentId: string;
+        actionType: string;
+        actionDetails: Record<string, any>;
+    }, any>;
+    getActionLog: import("@ai-sdk/provider-utils").Tool<{
+        limit?: number;
+        actionTypeFilter?: string;
+    }, any[]>;
+    runCycle: import("@ai-sdk/provider-utils").Tool<{
+        agentId: string;
+        candidates?: Array<{
+            actionType: string;
+            action: Record<string, any>;
+            score: number;
+            rationale: string;
+        }>;
+    }, any>;
+    getCycleHistory: import("@ai-sdk/provider-utils").Tool<{
+        limit?: number;
+    }, any[]>;
+};
+/**
+ * Tool names available in the state tools.
+ */
+export declare const stateToolNames: readonly ["focus", "drift", "recall", "remember", "trigger", "setVariable", "getVariable", "listVariables", "deleteVariable", "defineConcept", "listConcepts", "addGoal", "updateGoal", "listGoals", "submitAction", "getActionLog", "runCycle", "getCycleHistory"];
+export type StateToolName = (typeof stateToolNames)[number];

package/dist/tools/vercel.js

@@ -0,0 +1,343 @@
+"use strict";
+/**
+ * Vercel AI SDK v6 compatible tool definitions for Rice State service.
+ *
+ * Usage with Vercel AI SDK:
+ * ```typescript
+ * import { generateText } from 'ai';
+ * import { createStateTools } from 'rice-node-sdk/tools/vercel';
+ *
+ * const tools = createStateTools(client.state);
+ * const result = await generateText({
+ *   model: yourModel,
+ *   tools,
+ *   prompt: 'Remember that I like TypeScript',
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stateToolNames = void 0;
+exports.createStateTools = createStateTools;
+const provider_utils_1 = require("@ai-sdk/provider-utils");
+/**
+ * Creates Vercel AI SDK v6 compatible tools bound to a StateClient instance.
+ * Each tool uses the `tool()` helper from @ai-sdk/provider-utils for proper typing.
+ */
+function createStateTools(client) {
+    return {
+        // Core Memory Operations
+        focus: (0, provider_utils_1.tool)({
+            description: "Stores information in short-term working memory (Flux).",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    content: {
+                        type: "string",
+                        description: "The information to focus on.",
+                    },
+                },
+                required: ["content"],
+            }),
+            execute: async ({ content }) => client.focus(content),
+        }),
+        drift: (0, provider_utils_1.tool)({
+            description: "Reads the current items in short-term working memory (Flux).",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {},
+            }),
+            execute: async () => client.drift(),
+        }),
+        recall: (0, provider_utils_1.tool)({
+            description: "Recalls relevant memories from long-term memory based on a semantic query.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "The query to search for in memories.",
+                    },
+                },
+                required: ["query"],
+            }),
+            execute: async ({ query }) => client.reminisce(query),
+        }),
+        remember: (0, provider_utils_1.tool)({
+            description: "Stores information in long-term memory for future recall.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    content: {
+                        type: "string",
+                        description: "The information to remember.",
+                    },
+                },
+                required: ["content"],
+            }),
+            execute: async ({ content }) => client.commit(content, "Stored in long-term memory", {
+                action: "remember",
+            }),
+        }),
+        trigger: (0, provider_utils_1.tool)({
+            description: "Triggers a registered skill or procedure by name.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    skillName: {
+                        type: "string",
+                        description: "The name of the skill to trigger.",
+                    },
+                },
+                required: ["skillName"],
+            }),
+            execute: async ({ skillName }) => client.trigger(skillName),
+        }),
+        // Working Memory (Structured Variables)
+        setVariable: (0, provider_utils_1.tool)({
+            description: "Sets a structured variable in working memory.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "The name of the variable.",
+                    },
+                    value: {
+                        description: "The value to store (any JSON-serializable type).",
+                    },
+                    source: {
+                        type: "string",
+                        description: "Source: 'system', 'reasoning', 'retrieval', 'perception', or 'explicit'.",
+                    },
+                },
+                required: ["name", "value"],
+            }),
+            execute: async ({ name, value, source }) => client.setVariable(name, value, source),
+        }),
+        getVariable: (0, provider_utils_1.tool)({
+            description: "Gets a structured variable from working memory.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "The name of the variable to retrieve.",
+                    },
+                },
+                required: ["name"],
+            }),
+            execute: async ({ name }) => client.getVariable(name),
+        }),
+        listVariables: (0, provider_utils_1.tool)({
+            description: "Lists all variables in working memory.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {},
+            }),
+            execute: async () => client.listVariables(),
+        }),
+        deleteVariable: (0, provider_utils_1.tool)({
+            description: "Deletes a variable from working memory.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "The name of the variable to delete.",
+                    },
+                },
+                required: ["name"],
+            }),
+            execute: async ({ name }) => client.deleteVariable(name),
+        }),
+        // Concepts
+        defineConcept: (0, provider_utils_1.tool)({
+            description: "Defines a concept with a JSON schema for structured knowledge.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "The name of the concept.",
+                    },
+                    schema: {
+                        type: "object",
+                        description: "The JSON schema defining the concept structure.",
+                    },
+                },
+                required: ["name", "schema"],
+            }),
+            execute: async ({ name, schema }) => client.defineConcept(name, schema),
+        }),
+        listConcepts: (0, provider_utils_1.tool)({
+            description: "Lists all defined concepts and their schemas.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {},
+            }),
+            execute: async () => client.listConcepts(),
+        }),
+        // Goals
+        addGoal: (0, provider_utils_1.tool)({
+            description: "Adds a goal to the agent's goal stack.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    description: {
+                        type: "string",
+                        description: "Description of the goal.",
+                    },
+                    priority: {
+                        type: "string",
+                        enum: ["low", "medium", "high", "critical"],
+                        description: "Priority level of the goal.",
+                    },
+                    parentId: {
+                        type: "string",
+                        description: "Optional parent goal ID for hierarchical goals.",
+                    },
+                },
+                required: ["description"],
+            }),
+            execute: async ({ description, priority, parentId }) => client.addGoal(description, priority, parentId),
+        }),
+        updateGoal: (0, provider_utils_1.tool)({
+            description: "Updates a goal's status.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    goalId: {
+                        type: "string",
+                        description: "The ID of the goal to update.",
+                    },
+                    status: {
+                        type: "string",
+                        enum: ["active", "suspended", "achieved", "abandoned", "failed"],
+                        description: "New status for the goal.",
+                    },
+                },
+                required: ["goalId", "status"],
+            }),
+            execute: async ({ goalId, status }) => client.updateGoal(goalId, status),
+        }),
+        listGoals: (0, provider_utils_1.tool)({
+            description: "Lists all goals, optionally filtered by status.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    statusFilter: {
+                        type: "string",
+                        enum: ["active", "suspended", "achieved", "abandoned", "failed"],
+                        description: "Optional status to filter goals by.",
+                    },
+                },
+            }),
+            execute: async ({ statusFilter }) => client.listGoals(statusFilter),
+        }),
+        // Actions
+        submitAction: (0, provider_utils_1.tool)({
+            description: "Submits an action for execution and logging.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    agentId: {
+                        type: "string",
+                        description: "The ID of the agent submitting the action.",
+                    },
+                    actionType: {
+                        type: "string",
+                        enum: ["reason", "retrieve", "learn", "ground"],
+                        description: "Type of action.",
+                    },
+                    actionDetails: {
+                        type: "object",
+                        description: "The action details.",
+                    },
+                },
+                required: ["agentId", "actionType", "actionDetails"],
+            }),
+            execute: async ({ agentId, actionType, actionDetails }) => client.submitAction(agentId, actionType, actionDetails),
+        }),
+        getActionLog: (0, provider_utils_1.tool)({
+            description: "Gets the action log for the current run.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of entries to retrieve.",
+                    },
+                    actionTypeFilter: {
+                        type: "string",
+                        description: "Optional action type to filter by.",
+                    },
+                },
+            }),
+            execute: async ({ limit, actionTypeFilter }) => client.getActionLog(limit, actionTypeFilter),
+        }),
+        // Decision Cycles
+        runCycle: (0, provider_utils_1.tool)({
+            description: "Runs a decision cycle with optional action candidates.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    agentId: {
+                        type: "string",
+                        description: "The ID of the agent running the cycle.",
+                    },
+                    candidates: {
+                        type: "array",
+                        description: "Optional array of action candidates with scores.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                actionType: { type: "string" },
+                                action: { type: "object" },
+                                score: { type: "number" },
+                                rationale: { type: "string" },
+                            },
+                        },
+                    },
+                },
+                required: ["agentId"],
+            }),
+            execute: async ({ agentId, candidates }) => client.runCycle(agentId, candidates),
+        }),
+        getCycleHistory: (0, provider_utils_1.tool)({
+            description: "Gets the history of decision cycles for the current run.",
+            inputSchema: (0, provider_utils_1.jsonSchema)({
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of cycles to retrieve.",
+                    },
+                },
+            }),
+            execute: async ({ limit }) => client.getCycleHistory(limit),
+        }),
+    };
+}
+/**
+ * Tool names available in the state tools.
+ */
+exports.stateToolNames = [
+    "focus",
+    "drift",
+    "recall",
+    "remember",
+    "trigger",
+    "setVariable",
+    "getVariable",
+    "listVariables",
+    "deleteVariable",
+    "defineConcept",
+    "listConcepts",
+    "addGoal",
+    "updateGoal",
+    "listGoals",
+    "submitAction",
+    "getActionLog",
+    "runCycle",
+    "getCycleHistory",
+];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rice-node-sdk",
-    "version": "1.0.5",
+    "version": "1.0.7",
     "description": "SDK for Rice",
     "repository": {
         "type": "git",
@@ -29,6 +29,10 @@
             "types": "./dist/tools/openai.d.ts",
             "default": "./dist/tools/openai.js"
         },
+        "./tools/vercel": {
+            "types": "./dist/tools/vercel.d.ts",
+            "default": "./dist/tools/vercel.js"
+        },
         "./tools/execute": {
             "types": "./dist/tools/execute.d.ts",
             "default": "./dist/tools/execute.js"
@@ -56,6 +60,7 @@
         "long": "^5.2.3"
     },
     "devDependencies": {
+        "@ai-sdk/provider-utils": "^4.0.8",
         "@types/jest": "^30.0.0",
         "@types/node": "^20.0.0",
         "dotenv": "^17.2.3",
@@ -63,4 +68,4 @@
         "ts-jest": "^29.4.6",
         "typescript": "^5.3.0"
     }
-}
+}