@kuralle-agents/core 0.4.1 → 0.6.0

package/README.md

@@ -41,7 +41,7 @@ const agent = defineAgent({
   instructions: 'You are a helpful support agent.',
   model: openai('gpt-4o-mini'),
   tools: buildToolSet({ echo }),   // model-visible
-  effectTools: { echo },           // durable executor
+  tools: { echo },           // durable executor
 });
 
 const runtime = createRuntime({ agents: [agent], defaultAgentId: 'support' });
@@ -130,9 +130,18 @@ const runtime = createRuntime({
 });
 ```
 
-## HTTP streaming
+## HTTP streaming (web)
 
-`TurnHandle` exposes `handle.toResponseStream('sse')` for HTTP transports — or use `@kuralle-agents/hono-server` for a ready-made Hono router.
+For React/web consumers, return a native AI SDK `UIMessageStream` — `useChat` works with no bridge:
+
+```ts
+const handle = runtime.run({ input: 'Hello', sessionId: 'demo' });
+return handle.toUIMessageStreamResponse({ sessionId: 'demo' });
+```
+
+Kuralle orchestration events (flow telemetry, safety blocks, interactive choices) arrive as typed `data-kuralle-*` parts. Import `KuralleUIMessage` and `KuralleDataParts` for compile-time-safe `message.parts` and `useChat({ onData })` handlers.
+
+For non-UI consumers (curl, custom transports), use `handle.toResponseStream('sse')` to emit raw `HarnessStreamPart` JSON-SSE. Or use `@kuralle-agents/hono-server` — `POST /api/chat/sse` defaults to native `UIMessageStream`; append `?format=raw` for the legacy wire.
 
 ## Related
 

package/dist/ai-sdk/uiMessageStream.d.ts

@@ -0,0 +1,51 @@
+import { type UIMessage } from 'ai';
+import type { ConversationOutcome } from '../outcomes/types.js';
+import type { ChoiceOption } from '../types/selection.js';
+import type { HarnessStreamPart } from '../types/stream.js';
+export type KuralleMetadata = {
+    sessionId?: string;
+};
+export type KuralleDataParts = {
+    'kuralle-node': {
+        event: 'enter' | 'exit';
+        node: string;
+    };
+    'kuralle-flow': {
+        event: 'enter' | 'transition' | 'end';
+        flow?: string;
+        from?: string;
+        to?: string;
+        reason?: string;
+    };
+    'kuralle-handoff': {
+        targetAgent: string;
+        reason?: string;
+    };
+    'kuralle-interactive': {
+        nodeId: string;
+        prompt: string;
+        options: ChoiceOption[];
+    };
+    'kuralle-safety': {
+        kind: 'safety-blocked' | 'pipeline-validation-block';
+        moderator?: string;
+        rationale: string;
+        userFacingMessage?: string;
+    };
+    'kuralle-outcome': {
+        outcome: ConversationOutcome;
+    };
+    'kuralle-control': {
+        event: 'interrupted' | 'paused';
+        reason?: string;
+        waitingFor?: string;
+    };
+    'kuralle-custom': {
+        name: string;
+        data: unknown;
+    };
+};
+export type KuralleUIMessage = UIMessage<KuralleMetadata, KuralleDataParts>;
+export declare function harnessToUIMessageStream(source: AsyncIterable<HarnessStreamPart>, opts?: {
+    sessionId?: string;
+}): ReadableStream;

package/dist/ai-sdk/uiMessageStream.js

@@ -0,0 +1,164 @@
+import { createUIMessageStream, generateId, } from 'ai';
+function writeHarnessPart(part, writer) {
+    switch (part.type) {
+        case 'text-start':
+            writer.write({ type: 'text-start', id: part.id });
+            break;
+        case 'text-delta':
+            writer.write({ type: 'text-delta', id: part.id, delta: part.delta });
+            break;
+        case 'text-end':
+            writer.write({ type: 'text-end', id: part.id });
+            break;
+        case 'text-cancel':
+            writer.write({ type: 'text-end', id: part.id });
+            break;
+        case 'tool-call':
+            writer.write({
+                type: 'tool-input-available',
+                toolCallId: part.toolCallId ?? generateId(),
+                toolName: part.toolName,
+                input: part.args,
+            });
+            break;
+        case 'tool-result':
+            writer.write({
+                type: 'tool-output-available',
+                toolCallId: part.toolCallId ?? 'unknown',
+                output: part.result,
+            });
+            break;
+        case 'node-enter':
+            writer.write({
+                type: 'data-kuralle-node',
+                data: { event: 'enter', node: part.nodeName },
+                transient: true,
+            });
+            break;
+        case 'node-exit':
+            writer.write({
+                type: 'data-kuralle-node',
+                data: { event: 'exit', node: part.nodeName },
+                transient: true,
+            });
+            break;
+        case 'flow-enter':
+            writer.write({
+                type: 'data-kuralle-flow',
+                data: { event: 'enter', flow: part.flow },
+                transient: true,
+            });
+            break;
+        case 'flow-end':
+            writer.write({
+                type: 'data-kuralle-flow',
+                data: { event: 'end', flow: part.flow, reason: part.reason },
+                transient: true,
+            });
+            break;
+        case 'flow-transition':
+            writer.write({
+                type: 'data-kuralle-flow',
+                data: { event: 'transition', from: part.from, to: part.to },
+                transient: true,
+            });
+            break;
+        case 'handoff':
+            writer.write({
+                type: 'data-kuralle-handoff',
+                id: generateId(),
+                data: { targetAgent: part.targetAgent, reason: part.reason },
+            });
+            break;
+        case 'interactive':
+            writer.write({
+                type: 'data-kuralle-interactive',
+                id: part.nodeId,
+                data: { nodeId: part.nodeId, prompt: part.prompt, options: part.options },
+            });
+            break;
+        case 'safety-blocked':
+            writer.write({
+                type: 'data-kuralle-safety',
+                id: generateId(),
+                data: {
+                    kind: 'safety-blocked',
+                    moderator: part.moderator,
+                    rationale: part.rationale,
+                    userFacingMessage: part.userFacingMessage,
+                },
+            });
+            break;
+        case 'pipeline-validation-block':
+            writer.write({
+                type: 'data-kuralle-safety',
+                id: generateId(),
+                data: {
+                    kind: 'pipeline-validation-block',
+                    rationale: part.rationale,
+                    userFacingMessage: part.userFacingMessage,
+                },
+            });
+            break;
+        case 'conversation-outcome':
+            writer.write({
+                type: 'data-kuralle-outcome',
+                id: generateId(),
+                data: { outcome: part.outcome },
+            });
+            break;
+        case 'interrupted':
+            writer.write({
+                type: 'data-kuralle-control',
+                data: { event: 'interrupted', reason: part.reason },
+                transient: true,
+            });
+            break;
+        case 'paused':
+            writer.write({
+                type: 'data-kuralle-control',
+                data: { event: 'paused', waitingFor: part.waitingFor },
+                transient: true,
+            });
+            break;
+        case 'custom':
+            writer.write({
+                type: 'data-kuralle-custom',
+                data: { name: part.name, data: part.data },
+                transient: true,
+            });
+            break;
+        case 'error':
+            throw new Error(part.error);
+        case 'done':
+        case 'turn-end':
+            break;
+    }
+}
+export function harnessToUIMessageStream(source, opts) {
+    return createUIMessageStream({
+        execute: async ({ writer }) => {
+            let doneSessionId = opts?.sessionId;
+            if (doneSessionId) {
+                writer.write({
+                    type: 'start',
+                    messageMetadata: { sessionId: doneSessionId },
+                });
+            }
+            for await (const part of source) {
+                if (part.type === 'done' && part.sessionId) {
+                    doneSessionId = doneSessionId ?? part.sessionId;
+                }
+                else {
+                    writeHarnessPart(part, writer);
+                }
+            }
+            if (doneSessionId) {
+                writer.write({
+                    type: 'finish',
+                    messageMetadata: { sessionId: doneSessionId },
+                });
+            }
+        },
+    });
+}

package/dist/events/TurnHandle.js

@@ -1,3 +1,5 @@
+import { createUIMessageStreamResponse } from 'ai';
+import { harnessToUIMessageStream } from '../ai-sdk/uiMessageStream.js';
 export function createEventBus() {
     const events = [];
     const waiters = [];
@@ -48,6 +50,11 @@ export function createTurnHandle(options) {
         toResponseStream(format = 'sse') {
             return createResponseStream(bus.events(), format);
         },
+        toUIMessageStreamResponse(opts) {
+            return createUIMessageStreamResponse({
+                stream: harnessToUIMessageStream(bus.events(), opts),
+            });
+        },
         cancel(reason) {
             abortController.abort(reason);
             bus.close();

package/dist/flow/nodeBuilders.d.ts

@@ -8,7 +8,7 @@ export declare function buildNodePrompt(node: ReplyNode, state: FlowState): stri
  *  agent's base instructions (persona / safety / grounding) prefix the node's
  *  own instructions. Node instructions layer ON TOP — they never replace the
  *  base. Base resolves against the current state so dynamic base prompts work. */
-export declare function composeSystem(base: Instructions | undefined, nodeSystem: string, state: FlowState): string;
+export declare function composeSystem(base: Instructions | undefined, nodeSystem: string, state: FlowState, skillPrompt?: string, workingMemoryPrompt?: string): string;
 export declare function resolveReplyNode(node: ReplyNode, state: FlowState, options?: {
     freeConversation?: boolean;
 }): ResolvedNode;

package/dist/flow/nodeBuilders.js

@@ -19,9 +19,11 @@ export function buildNodePrompt(node, state) {
  *  agent's base instructions (persona / safety / grounding) prefix the node's
  *  own instructions. Node instructions layer ON TOP — they never replace the
  *  base. Base resolves against the current state so dynamic base prompts work. */
-export function composeSystem(base, nodeSystem, state) {
+export function composeSystem(base, nodeSystem, state, skillPrompt, workingMemoryPrompt) {
     const baseText = base ? resolveInstructions(base, state) : '';
-    return [baseText, nodeSystem].filter((s) => s && s.trim()).join('\n\n');
+    return [baseText, skillPrompt, workingMemoryPrompt, nodeSystem]
+        .filter((s) => s && s.trim())
+        .join('\n\n');
 }
 function buildNodeTools(node, state) {
     if (!node.tools) {
@@ -39,7 +41,7 @@ export function resolveReplyNode(node, state, options) {
         prompt: buildNodePrompt(node, state),
         tools,
         // Recover the raw executors from the node's `buildToolSet` tools so they run
-        // in-flow (with run context) — without also needing `agent.effectTools`.
+        // in-flow (with run context) — without also needing `agent.tools`.
         localTools: rawToolsFromSet(tools),
         ...(options?.freeConversation && { freeConversation: true }),
     };

package/dist/index.d.ts

@@ -47,8 +47,11 @@ export type { MemoryEntry, SearchMemoryRequest, SearchMemoryResponse, MemoryInge
 export { InMemoryMemoryService } from './memory/index.js';
 export { preloadMemoryContext } from './memory/index.js';
 export { extractMemories } from './memory/index.js';
-export type { PersistentMemoryStore, PersistentMemoryBlock, PersistentMemoryConfig, MemoryBlockScope, } from './memory/index.js';
-export { FilePersistentMemoryStore, scanMemoryWrite, buildMemoryBlockTool, DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './memory/index.js';
+export type { PersistentMemoryStore, PersistentMemoryBlock, PersistentMemoryConfig, MemoryBlockScope, WorkingMemoryBlockSpec, WorkingMemoryConfig, } from './memory/index.js';
+export { FilePersistentMemoryStore, InMemoryPersistentMemoryStore, RoutedPersistentMemoryStore, TieredPersistentMemoryStore, scanMemoryWrite, buildMemoryBlockTool, DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './memory/index.js';
+export type { RoutedPersistentMemoryStoreConfig, MemoryRouteFn, } from './memory/index.js';
+export { wireWorkingMemory, loadWorkingMemoryBlocks, formatWorkingMemorySection, resolveWorkingMemoryStore, } from './runtime/grounding/workingMemory.js';
+export { resolveAgentWorkspace, type ResolvedAgentWorkspace, } from './runtime/resolveAgentWorkspace.js';
 export { DEFAULT_CONTEXT_BUDGET, VOICE_CONTEXT_BUDGET, computeMessageHistoryBudget, truncateToTokenBudget, formatMemoryWithBudget, estimateTokenCount, ContextBudget, } from './runtime/ContextBudget.js';
 export type { ContextBudgetConfig } from './runtime/ContextBudget.js';
 export { TokenAccumulator } from './runtime/TokenAccumulator.js';
@@ -67,16 +70,23 @@ export type { Hooks } from './types/hooks.js';
 export type { HarnessHooks } from './types/runtime.js';
 export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, } from './authoring/index.js';
 export { defineTool } from './types/effectTool.js';
-export { buildToolSet, toolToAiSdk, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
+export { fsErrorCode } from './types/filesystem.js';
+export { createFsTool } from './tools/fs/createFsTool.js';
+export type { CreateFsToolOptions, GrepHit } from './tools/fs/createFsTool.js';
+export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
+export type { WiredAgentSkills, SkillWireAgent } from './skills/index.js';
+export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export type { Tool as EffectTool } from './types/effectTool.js';
 export type { AgentRoute } from './types/processors.js';
-export type { AgentConfig, Instructions } from './types/agentConfig.js';
+export type { AgentConfig, AgentWorkspaceConfig, Instructions } from './types/agentConfig.js';
 export type { Flow, FlowNode, Transition, CollectNode, DecideNode, ConfirmGate, NodeGrounding, } from './types/flow.js';
 export { parseConfirmation } from './flow/confirmParse.js';
 export type { ConfirmVerdict } from './flow/confirmParse.js';
 export type { Route } from './types/route.js';
 export type { TurnHandle } from './types/stream.js';
 export type { HarnessStreamPart } from './types/stream.js';
+export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
+export type { KuralleMetadata, KuralleDataParts, KuralleUIMessage, } from './ai-sdk/uiMessageStream.js';
 export type { ChoiceOption, ResolvedSelection } from './types/selection.js';
 export type { RunState, StepRecord } from './runtime/durable/types.js';
 export type { RunStore } from './runtime/durable/RunStore.js';

package/dist/index.js

@@ -29,7 +29,9 @@ export { getTemplate, registerTemplate, listTemplates, getAllTemplates } from '.
 export { InMemoryMemoryService } from './memory/index.js';
 export { preloadMemoryContext } from './memory/index.js';
 export { extractMemories } from './memory/index.js';
-export { FilePersistentMemoryStore, scanMemoryWrite, buildMemoryBlockTool, DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './memory/index.js';
+export { FilePersistentMemoryStore, InMemoryPersistentMemoryStore, RoutedPersistentMemoryStore, TieredPersistentMemoryStore, scanMemoryWrite, buildMemoryBlockTool, DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './memory/index.js';
+export { wireWorkingMemory, loadWorkingMemoryBlocks, formatWorkingMemorySection, resolveWorkingMemoryStore, } from './runtime/grounding/workingMemory.js';
+export { resolveAgentWorkspace, } from './runtime/resolveAgentWorkspace.js';
 export { DEFAULT_CONTEXT_BUDGET, VOICE_CONTEXT_BUDGET, computeMessageHistoryBudget, truncateToTokenBudget, formatMemoryWithBudget, estimateTokenCount, ContextBudget, } from './runtime/ContextBudget.js';
 export { TokenAccumulator } from './runtime/TokenAccumulator.js';
 export { handoffFilters, removeToolHistory, keepRecentMessages, removeKeys, composeFilters, } from './runtime/handoffFilters.js';
@@ -38,6 +40,10 @@ export { CapabilityHost, TriageCapability, ExtractionCapability, HandoffCapabili
 export { filterAuditEntries } from './audit/index.js';
 export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, } from './authoring/index.js';
 export { defineTool } from './types/effectTool.js';
-export { buildToolSet, toolToAiSdk, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
+export { fsErrorCode } from './types/filesystem.js';
+export { createFsTool } from './tools/fs/createFsTool.js';
+export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
+export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export { parseConfirmation } from './flow/confirmParse.js';
+export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';

package/dist/memory/blocks/FilePersistentMemoryStore.d.ts

@@ -1,4 +1,4 @@
-import { type PersistentMemoryStore, type PersistentMemoryBlock, type MemoryBlockScope } from './types.js';
+import type { PersistentMemoryStore, PersistentMemoryBlock, MemoryBlockScope } from './types.js';
 export interface FilePersistentMemoryStoreOptions {
     /** Root directory. Defaults to `KURALLE_MEMORY_DIR` or `~/.kuralle/memories`. */
     rootDir?: string;

package/dist/memory/blocks/FilePersistentMemoryStore.js

@@ -9,6 +9,13 @@
  *
  * Defaults to `process.env.KURALLE_MEMORY_DIR ?? <homedir>/.kuralle/memories`.
  *
+ * Relationship to `AgentConfig.workspace` (RFC-02): this store persists long-term
+ * memory *blocks* on the local Node filesystem via `node:fs`. It is not a
+ * portable `FileSystem` backend and is not wired into the agent workspace tool.
+ * Use `@kuralle-agents/fs` (`InMemoryFs`, `KnowledgeFs`, …) for model-visible
+ * workspace exploration; keep `FilePersistentMemoryStore` for durable USER/AGENT
+ * markdown blocks when running on Node.
+ *
  * Atomicity: writes go to a sibling `.tmp` file then `rename` over the
  * target. `rename` is atomic on POSIX within a single filesystem;
  * Windows is best-effort.
@@ -21,6 +28,7 @@
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { registerNodeDefaultWorkingMemoryStore } from '../../runtime/grounding/defaultStoreRegistry.js';
 export class FilePersistentMemoryStore {
     rootDir;
     constructor(opts = {}) {
@@ -111,3 +119,4 @@ export class FilePersistentMemoryStore {
 function isNodeError(err) {
     return typeof err === 'object' && err !== null && 'code' in err;
 }
+registerNodeDefaultWorkingMemoryStore(() => new FilePersistentMemoryStore());

package/dist/memory/blocks/InMemoryPersistentMemoryStore.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryBlockScope, PersistentMemoryBlock, PersistentMemoryStore } from './types.js';
+export declare class InMemoryPersistentMemoryStore implements PersistentMemoryStore {
+    private readonly blocks;
+    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/memory/blocks/InMemoryPersistentMemoryStore.js

@@ -0,0 +1,25 @@
+function blockKey(scope, owner, key) {
+    return `${scope}:${owner}:${key}`;
+}
+export class InMemoryPersistentMemoryStore {
+    blocks = new Map();
+    async loadBlock(scope, owner, key) {
+        return this.blocks.get(blockKey(scope, owner, key)) ?? null;
+    }
+    async saveBlock(block, owner) {
+        this.blocks.set(blockKey(block.scope, owner, block.key), {
+            ...block,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async deleteBlock(scope, owner, key) {
+        this.blocks.delete(blockKey(scope, owner, key));
+    }
+    async listBlocks(scope, owner) {
+        const prefix = `${scope}:${owner}:`;
+        return [...this.blocks.keys()]
+            .filter((k) => k.startsWith(prefix))
+            .map((k) => k.slice(prefix.length))
+            .sort();
+    }
+}

package/dist/memory/blocks/RoutedPersistentMemoryStore.d.ts

@@ -0,0 +1,18 @@
+import type { MemoryBlockScope, PersistentMemoryBlock, PersistentMemoryStore } from './types.js';
+export type MemoryRouteFn = (scope: MemoryBlockScope, owner: string) => PersistentMemoryStore;
+export interface RoutedPersistentMemoryStoreConfig {
+    routes: Partial<Record<MemoryBlockScope, PersistentMemoryStore>>;
+    default?: PersistentMemoryStore;
+    route?: MemoryRouteFn;
+}
+export declare class RoutedPersistentMemoryStore implements PersistentMemoryStore {
+    private readonly routes;
+    private readonly defaultStore?;
+    private readonly routeFn?;
+    constructor(config: RoutedPersistentMemoryStoreConfig);
+    private resolve;
+    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/memory/blocks/RoutedPersistentMemoryStore.js

@@ -0,0 +1,35 @@
+export class RoutedPersistentMemoryStore {
+    routes;
+    defaultStore;
+    routeFn;
+    constructor(config) {
+        this.routes = config.routes;
+        this.defaultStore = config.default;
+        this.routeFn = config.route;
+    }
+    resolve(scope, owner) {
+        if (this.routeFn) {
+            return this.routeFn(scope, owner);
+        }
+        const byScope = this.routes[scope];
+        if (byScope) {
+            return byScope;
+        }
+        if (this.defaultStore) {
+            return this.defaultStore;
+        }
+        throw new Error(`No PersistentMemoryStore route for scope=${scope}`);
+    }
+    async loadBlock(scope, owner, key) {
+        return this.resolve(scope, owner).loadBlock(scope, owner, key);
+    }
+    async saveBlock(block, owner) {
+        await this.resolve(block.scope, owner).saveBlock(block, owner);
+    }
+    async deleteBlock(scope, owner, key) {
+        await this.resolve(scope, owner).deleteBlock(scope, owner, key);
+    }
+    async listBlocks(scope, owner) {
+        return this.resolve(scope, owner).listBlocks(scope, owner);
+    }
+}

package/dist/memory/blocks/TieredPersistentMemoryStore.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryBlockScope, PersistentMemoryBlock, PersistentMemoryStore } from './types.js';
+export declare class TieredPersistentMemoryStore implements PersistentMemoryStore {
+    private readonly cache;
+    private readonly durable;
+    constructor(cache: PersistentMemoryStore, durable: PersistentMemoryStore);
+    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/memory/blocks/TieredPersistentMemoryStore.js

@@ -0,0 +1,30 @@
+export class TieredPersistentMemoryStore {
+    cache;
+    durable;
+    constructor(cache, durable) {
+        this.cache = cache;
+        this.durable = durable;
+    }
+    async loadBlock(scope, owner, key) {
+        const cached = await this.cache.loadBlock(scope, owner, key);
+        if (cached) {
+            return cached;
+        }
+        const fromDurable = await this.durable.loadBlock(scope, owner, key);
+        if (fromDurable) {
+            await this.cache.saveBlock(fromDurable, owner);
+        }
+        return fromDurable;
+    }
+    async saveBlock(block, owner) {
+        await this.durable.saveBlock(block, owner);
+        await this.cache.saveBlock(block, owner);
+    }
+    async deleteBlock(scope, owner, key) {
+        await this.durable.deleteBlock(scope, owner, key);
+        await this.cache.deleteBlock(scope, owner, key);
+    }
+    async listBlocks(scope, owner) {
+        return this.durable.listBlocks(scope, owner);
+    }
+}

package/dist/memory/blocks/memoryBlockTool.d.ts

@@ -21,7 +21,7 @@ export declare function buildMemoryBlockTool(opts: MemoryBlockToolOptions): impo
     empty: boolean;
     updatedAt?: undefined;
     chars?: undefined;
-    readonly error?: undefined;
+    error?: undefined;
     message?: undefined;
     ok?: undefined;
     removed?: undefined;
@@ -38,7 +38,7 @@ export declare function buildMemoryBlockTool(opts: MemoryBlockToolOptions): impo
     updatedAt: string | undefined;
     chars: number;
     empty?: undefined;
-    readonly error?: undefined;
+    error?: undefined;
     message?: undefined;
     ok?: undefined;
     removed?: undefined;
@@ -75,7 +75,7 @@ export declare function buildMemoryBlockTool(opts: MemoryBlockToolOptions): impo
     empty?: undefined;
     updatedAt?: undefined;
     chars?: undefined;
-    readonly error?: undefined;
+    error?: undefined;
     message?: undefined;
     remainingChars?: undefined;
     pattern?: undefined;
@@ -92,7 +92,7 @@ export declare function buildMemoryBlockTool(opts: MemoryBlockToolOptions): impo
     empty?: undefined;
     updatedAt?: undefined;
     chars?: undefined;
-    readonly error?: undefined;
+    error?: undefined;
     message?: undefined;
     note?: undefined;
     pattern?: undefined;
@@ -143,7 +143,7 @@ export declare function buildMemoryBlockTool(opts: MemoryBlockToolOptions): impo
     content?: undefined;
     empty?: undefined;
     updatedAt?: undefined;
-    readonly error?: undefined;
+    error?: undefined;
     message?: undefined;
     removed?: undefined;
     note?: undefined;

package/dist/memory/blocks/testing.d.ts

@@ -0,0 +1,11 @@
+import type { PersistentMemoryStore } from './types.js';
+export type PersistentMemoryStoreFactory = () => PersistentMemoryStore | Promise<PersistentMemoryStore>;
+export type PersistentMemoryDurabilityFactory = () => {
+    storeA: PersistentMemoryStore;
+    storeB: PersistentMemoryStore;
+} | Promise<{
+    storeA: PersistentMemoryStore;
+    storeB: PersistentMemoryStore;
+}>;
+export declare function runPersistentMemoryStoreContract(factory: PersistentMemoryStoreFactory): void;
+export declare function runPersistentMemoryDurabilityContract(factory: PersistentMemoryDurabilityFactory): void;

package/dist/memory/blocks/testing.js

@@ -0,0 +1,59 @@
+/// <reference types="bun-types" />
+import { describe, test, expect, beforeEach } from 'bun:test';
+const sampleBlock = (overrides = {}) => ({
+    key: 'USER',
+    scope: 'user',
+    content: 'name: Maya\nprefers: vegetarian',
+    charLimit: 1000,
+    ...overrides,
+});
+export function runPersistentMemoryStoreContract(factory) {
+    describe('PersistentMemoryStore contract', () => {
+        let store;
+        beforeEach(async () => {
+            store = await factory();
+        });
+        test('loadBlock returns null for missing block', async () => {
+            expect(await store.loadBlock('user', 'alice', 'USER')).toBeNull();
+        });
+        test('saveBlock + loadBlock round-trips', async () => {
+            const block = sampleBlock();
+            await store.saveBlock(block, 'maya@example.com');
+            const loaded = await store.loadBlock('user', 'maya@example.com', 'USER');
+            expect(loaded).not.toBeNull();
+            expect(loaded.content).toBe(block.content);
+            expect(loaded.scope).toBe('user');
+            expect(loaded.key).toBe('USER');
+            expect(typeof loaded.updatedAt).toBe('string');
+        });
+        test('listBlocks returns keys within scope+owner', async () => {
+            await store.saveBlock(sampleBlock({ key: 'USER' }), 'bob');
+            await store.saveBlock(sampleBlock({ key: 'preferences', content: 'dark mode' }), 'bob');
+            await store.saveBlock(sampleBlock({ key: 'MEMORY', scope: 'agent', content: 'notes' }), 'bob');
+            expect((await store.listBlocks('user', 'bob')).sort()).toEqual([
+                'USER',
+                'preferences',
+            ]);
+            expect(await store.listBlocks('agent', 'bob')).toEqual(['MEMORY']);
+        });
+        test('listBlocks returns empty array when none exist', async () => {
+            expect(await store.listBlocks('user', 'never-existed')).toEqual([]);
+        });
+        test('deleteBlock removes block; no-op when missing', async () => {
+            await store.saveBlock(sampleBlock({ key: 'ephemeral' }), 'dave');
+            await store.deleteBlock('user', 'dave', 'ephemeral');
+            expect(await store.loadBlock('user', 'dave', 'ephemeral')).toBeNull();
+            await store.deleteBlock('user', 'dave', 'ephemeral');
+        });
+    });
+}
+export function runPersistentMemoryDurabilityContract(factory) {
+    describe('PersistentMemoryStore durability', () => {
+        test('store B reads block written by store A', async () => {
+            const { storeA, storeB } = await factory();
+            await storeA.saveBlock(sampleBlock({ content: 'durable payload' }), 'owner-1');
+            const loaded = await storeB.loadBlock('user', 'owner-1', 'USER');
+            expect(loaded?.content).toBe('durable payload');
+        });
+    });
+}