@kuralle-agents/cf-agent 0.5.0 → 0.6.0

package/README.md

@@ -19,6 +19,7 @@ Peers: `agents` (Cloudflare Agents SDK), `zod`.
 - **`KuralleAgent`** (alias `CfChatAgent`) — abstract base class; extend and implement `getAgents()` and `getDefaultAgentId()`.
 - **`BridgeSessionStore`** — bridges Kuralle `SessionStore` interface to CF's SQLite storage.
 - **`OrchestrationStore`** — Durable Object KV for orchestration state.
+- **`SqlPersistentMemoryStore`** — DO SQLite-backed `PersistentMemoryStore` for USER/MEMORY blocks.
 - **`createSSEResponse`** — helper for streaming SSE responses from Workers.
 
 ## Usage
@@ -64,6 +65,20 @@ tag = "v1"
 new_sqlite_classes = ["SupportAgent"]
 ```
 
+## Working memory blocks
+
+`KuralleAgent` wires `SqlPersistentMemoryStore` into `defaultWorkingMemoryStore` automatically via DO SQLite. Override in `getRuntimeConfig()` or disable by overriding `getWorkingMemoryStore()` to return `undefined`.
+
+```ts
+import { SqlPersistentMemoryStore } from '@kuralle-agents/cf-agent';
+
+protected getRuntimeConfig() {
+  return {
+    defaultWorkingMemoryStore: new SqlPersistentMemoryStore(this.getSql()),
+  };
+}
+```
+
 ## Flows and routing
 
 Attach `flows` for structured SOPs or `routes` + `routing: { mode: 'structured' }` for triage — same `defineAgent` primitive as Node/Bun. No runtime differences.

package/dist/KuralleAgent.d.ts

@@ -20,6 +20,7 @@
  */
 import { AIChatAgent } from '@cloudflare/ai-chat';
 import { type HarnessConfig } from '@kuralle-agents/core';
+import type { PersistentMemoryStore } from '@kuralle-agents/core';
 import type { StreamTextOnFinishCallback, ToolSet } from 'ai';
 import type { OnChatMessageOptions } from '@cloudflare/ai-chat';
 import type { StreamAdapterConfig } from './types.js';
@@ -64,6 +65,11 @@ export declare abstract class KuralleAgent<Env = unknown, State = unknown> exten
      * Optional: Configure which Kuralle events become data parts in the stream.
      */
     protected getStreamConfig(): Partial<StreamAdapterConfig>;
+    /**
+     * Optional: durable working-memory blocks backed by DO SQLite.
+     * When returned, wired into `HarnessConfig.defaultWorkingMemoryStore`.
+     */
+    protected getWorkingMemoryStore(): PersistentMemoryStore | undefined;
     /**
      * Get the SQL executor for the Durable Object.
      * CF's AIChatAgent exposes this.sql as a tagged template function.

package/dist/KuralleAgent.js

@@ -22,6 +22,7 @@ import { AIChatAgent } from '@cloudflare/ai-chat';
 import { createRuntime } from '@kuralle-agents/core';
 import { BridgeSessionStore } from './BridgeSessionStore.js';
 import { OrchestrationStore } from './OrchestrationStore.js';
+import { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
 import { createSSEResponse } from './StreamAdapter.js';
 import { DEFAULT_STREAM_CONFIG } from './types.js';
 import { durableAgentSurface } from './durable-agent-surface.js';
@@ -62,6 +63,13 @@ export class KuralleAgent extends AIChatAgent {
     getStreamConfig() {
         return {};
     }
+    /**
+     * Optional: durable working-memory blocks backed by DO SQLite.
+     * When returned, wired into `HarnessConfig.defaultWorkingMemoryStore`.
+     */
+    getWorkingMemoryStore() {
+        return new SqlPersistentMemoryStore(this.getSql());
+    }
     /**
      * Get the SQL executor for the Durable Object.
      * CF's AIChatAgent exposes this.sql as a tagged template function.
@@ -113,11 +121,15 @@ export class KuralleAgent extends AIChatAgent {
         });
         // Build runtime (fresh per request to pick up latest config)
         const extraConfig = this.getRuntimeConfig();
+        const workingMemoryStore = this.getWorkingMemoryStore();
         this.runtime = createRuntime({
             ...extraConfig,
             agents: this.getAgents(),
             defaultAgentId,
             sessionStore,
+            ...(workingMemoryStore && !extraConfig.defaultWorkingMemoryStore
+                ? { defaultWorkingMemoryStore: workingMemoryStore }
+                : {}),
         });
         const handle = this.runtime.run({
             input: lastUserMessage,

package/dist/SqlPersistentMemoryStore.d.ts

@@ -0,0 +1,12 @@
+import type { MemoryBlockScope, PersistentMemoryBlock, PersistentMemoryStore } from '@kuralle-agents/core';
+import type { SqlExecutor } from './types.js';
+export declare class SqlPersistentMemoryStore implements PersistentMemoryStore {
+    private sql;
+    private initialized;
+    constructor(sql: SqlExecutor);
+    private ensureTable;
+    loadBlock(scope: MemoryBlockScope, owner: string, key: string): Promise<PersistentMemoryBlock | null>;
+    saveBlock(block: PersistentMemoryBlock, owner: string): Promise<void>;
+    deleteBlock(scope: MemoryBlockScope, owner: string, key: string): Promise<void>;
+    listBlocks(scope: MemoryBlockScope, owner: string): Promise<string[]>;
+}

package/dist/SqlPersistentMemoryStore.js

@@ -0,0 +1,71 @@
+export class SqlPersistentMemoryStore {
+    sql;
+    initialized = false;
+    constructor(sql) {
+        this.sql = sql;
+    }
+    ensureTable() {
+        if (this.initialized) {
+            return;
+        }
+        this.sql `
+      CREATE TABLE IF NOT EXISTS working_memory_blocks (
+        scope TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        key TEXT NOT NULL,
+        content TEXT NOT NULL,
+        char_limit INTEGER NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scope, owner, key)
+      )
+    `;
+        this.initialized = true;
+    }
+    async loadBlock(scope, owner, key) {
+        this.ensureTable();
+        const rows = this.sql `
+      SELECT content, char_limit, updated_at
+      FROM working_memory_blocks
+      WHERE scope = ${scope} AND owner = ${owner} AND key = ${key}
+    `;
+        if (!rows || rows.length === 0) {
+            return null;
+        }
+        const row = rows[0];
+        return {
+            key,
+            scope,
+            content: row.content,
+            charLimit: row.char_limit,
+            updatedAt: row.updated_at,
+        };
+    }
+    async saveBlock(block, owner) {
+        this.ensureTable();
+        const updatedAt = block.updatedAt ?? new Date().toISOString();
+        this.sql `
+      INSERT INTO working_memory_blocks (scope, owner, key, content, char_limit, updated_at)
+      VALUES (${block.scope}, ${owner}, ${block.key}, ${block.content}, ${block.charLimit}, ${updatedAt})
+      ON CONFLICT(scope, owner, key) DO UPDATE SET
+        content = excluded.content,
+        char_limit = excluded.char_limit,
+        updated_at = excluded.updated_at
+    `;
+    }
+    async deleteBlock(scope, owner, key) {
+        this.ensureTable();
+        this.sql `
+      DELETE FROM working_memory_blocks
+      WHERE scope = ${scope} AND owner = ${owner} AND key = ${key}
+    `;
+    }
+    async listBlocks(scope, owner) {
+        this.ensureTable();
+        const rows = this.sql `
+      SELECT key FROM working_memory_blocks
+      WHERE scope = ${scope} AND owner = ${owner}
+      ORDER BY key
+    `;
+        return (rows ?? []).map((row) => row.key);
+    }
+}

package/dist/index.d.ts

@@ -26,6 +26,8 @@
 export { KuralleAgent, KuralleAgent as CfChatAgent } from './KuralleAgent.js';
 export { BridgeSessionStore } from './BridgeSessionStore.js';
 export { OrchestrationStore } from './OrchestrationStore.js';
+export { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
+export { createSqlExecutor } from './sqlExecutor.js';
 export { createSSEResponse } from './StreamAdapter.js';
 export type { StreamAdapterConfig, OrchestrationState, SqlExecutor, } from './types.js';
 export { DEFAULT_STREAM_CONFIG } from './types.js';

package/dist/index.js

@@ -26,5 +26,7 @@
 export { KuralleAgent, KuralleAgent as CfChatAgent } from './KuralleAgent.js';
 export { BridgeSessionStore } from './BridgeSessionStore.js';
 export { OrchestrationStore } from './OrchestrationStore.js';
+export { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
+export { createSqlExecutor } from './sqlExecutor.js';
 export { createSSEResponse } from './StreamAdapter.js';
 export { DEFAULT_STREAM_CONFIG } from './types.js';

package/dist/sqlExecutor.d.ts

@@ -0,0 +1,7 @@
+import type { SqlExecutor } from './types.js';
+type SqlStorageExec = {
+    exec: (query: string, ...params: unknown[]) => unknown;
+};
+/** Wrap DO `ctx.storage.sql.exec` as the tagged-template `SqlExecutor` shape. */
+export declare function createSqlExecutor(storageSql: SqlStorageExec): SqlExecutor;
+export {};

package/dist/sqlExecutor.js

@@ -0,0 +1,19 @@
+function rowsFromExecResult(result) {
+    if (result && typeof result === 'object') {
+        const cursor = result;
+        if (typeof cursor.toArray === 'function') {
+            return cursor.toArray();
+        }
+        if (Symbol.iterator in cursor) {
+            return [...result];
+        }
+    }
+    return [];
+}
+/** Wrap DO `ctx.storage.sql.exec` as the tagged-template `SqlExecutor` shape. */
+export function createSqlExecutor(storageSql) {
+    return ((strings, ...values) => {
+        const query = strings.reduce((acc, part, index) => acc + part + (index < values.length ? '?' : ''), '');
+        return rowsFromExecResult(storageSql.exec(query, ...values));
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-agents/cf-agent",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Kuralle agent integration for Cloudflare Workers with AIChatAgent",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,18 +22,20 @@
     "@cloudflare/ai-chat": "^0.1.8",
     "ai": "^6.0.90",
     "zod-to-json-schema": "^3.24.0",
-    "@kuralle-agents/core": "0.5.0",
-    "@kuralle-agents/realtime-audio": "0.5.0"
+    "@kuralle-agents/realtime-audio": "0.6.0",
+    "@kuralle-agents/core": "0.6.0"
   },
   "peerDependencies": {
     "agents": "^0.11.5",
     "zod": "^3.0.0",
-    "@kuralle-agents/voice-protocol": "0.5.0"
+    "@kuralle-agents/voice-protocol": "0.6.0"
   },
   "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.12.7",
     "agents": "^0.11.5",
     "typescript": "^5.7.0",
-    "@kuralle-agents/voice-protocol": "0.5.0"
+    "vitest": "^3.2.4",
+    "@kuralle-agents/voice-protocol": "0.6.0"
   },
   "engines": {
     "node": ">=20"
@@ -57,7 +59,8 @@
     "prebuild": "rm -rf dist",
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "bun test src/voice/__tests__ src/__tests__",
+    "test": "bun test src/voice/__tests__ src/__tests__ && vitest run --config vitest.config.ts",
+    "test:sql-memory-workers": "vitest run --config vitest.config.ts",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
   }