@kuralle-agents/core 0.4.1 → 0.6.0

package/guides/TOOLS.md

@@ -2,6 +2,74 @@
 
 Kuralle tools use the Vercel AI SDK `tool(...)` API. Tools are how agents read data, write state, and trigger flow transitions.
 
+## Durable agent tools
+
+Agent-level `tools` is a `Record<string, AnyTool>` from `defineTool` — every call is journaled (exactly-once on replay). Flow nodes use `buildToolSet({ ... })` for model-visible schema; executors come from the agent registry and flow-local tools.
+
+For third-party AI SDK tools, use `wrapAiSdkTool(name, aiTool)` — it captures `execute` and routes through the same journal:
+
+```ts
+import { defineTool, wrapAiSdkTool } from '@kuralle-agents/core';
+import { tool } from 'ai';
+
+const native = defineTool({ name: 'lookup', description: '...', input: z.object({ id: z.string() }), execute: async ({ id }) => ({ id }) });
+
+const sdk = tool({ description: 'Legacy SDK tool', inputSchema: z.object({ id: z.string() }), execute: async ({ id }) => ({ id }) });
+
+const agent = defineAgent({
+  id: 'a',
+  model,
+  tools: { lookup: native, legacy: wrapAiSdkTool('legacy', sdk) },
+});
+```
+
+## Agent workspace
+
+Set `workspace` to a portable `FileSystem` (from `@kuralle-agents/fs`) to auto-register the durable `workspace` tool (`ls`, `cat`, `grep`, `find`, `read`, `write`, `edit`). The same instance is exposed on `RunContext.fs` for flow `action` nodes.
+
+**Read-only by default** (ADR 0006): a bare `FileSystem` is mounted read-only and exposed in `globalTools` (safe for every speaking turn). Pass `{ fs, readOnly: false }` for a writable scratchpad — the executor is registered, but the tool is **not** auto-added to `globalTools` (mutating tools stay flow-gated).
+
+```ts
+import { InMemoryFs } from '@kuralle-agents/fs';
+
+const agent = defineAgent({
+  id: 'kb',
+  model,
+  workspace: new InMemoryFs({ '/docs/faq.md': '# FAQ' }),
+});
+
+// Writable scratchpad (not in globalTools):
+// workspace: { fs: new InMemoryFs({ '/scratch': '' }), readOnly: false },
+```
+
+Requires `@kuralle-agents/fs` when using `workspace`.
+
+## Working memory blocks
+
+Cross-session markdown blocks (`USER`, `MEMORY`, …) via `agent.memory.workingMemory`. Blocks load at session start, inject into the system prompt, and are editable with the auto-registered `memory_block` tool.
+
+```ts
+import { defineAgent, FilePersistentMemoryStore } from '@kuralle-agents/core';
+
+const agent = defineAgent({
+  id: 'support',
+  model,
+  memory: {
+    workingMemory: {
+      store: new FilePersistentMemoryStore(),
+      autoLoad: [
+        { scope: 'user', key: 'USER', template: 'name:\npreferences:' },
+        { scope: 'agent', key: 'MEMORY' },
+      ],
+    },
+  },
+});
+```
+
+On Workers, pass an explicit `store` (or `HarnessConfig.defaultWorkingMemoryStore`). Semantic recall (`preload` / `ingest`) is unchanged — working memory is an additional axis.
+
+See [examples/agents/working-memory.ts](../examples/agents/working-memory.ts) for a live cross-session demo.
+
 ## Tool Basics
 
 ```ts
@@ -70,8 +138,7 @@ const lead = defineAgent({
   instructions:
     'Research assistant. Use consult_weather for weather questions. Combine answers clearly.',
   model,
-  tools: buildToolSet({ consult_weather: consultWeather }),
-  effectTools: { consult_weather: consultWeather },
+  tools: { consult_weather: consultWeather },
 });
 
 const runtime = createRuntime({

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -72,6 +72,10 @@
       "types": "./dist/memory/index.d.ts",
       "default": "./dist/memory/index.js"
     },
+    "./memory/testing": {
+      "types": "./dist/memory/blocks/testing.d.ts",
+      "default": "./dist/memory/blocks/testing.js"
+    },
     "./foundation": {
       "types": "./dist/foundation/index.d.ts",
       "default": "./dist/foundation/index.js"
@@ -90,14 +94,16 @@
     "zod": "^3.0.0"
   },
   "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.12.7",
     "@ai-sdk/openai": "^3.0.0",
     "@types/node": "^20.11.0",
     "ai": "^6.0.0",
     "bun-types": "^1.3.0",
     "dotenv": "^16.4.0",
     "typescript": "^5.3.0",
+    "vitest": "^3.2.4",
     "zod": "^3.23.0",
-    "@kuralle-agents/realtime-audio": "0.4.1"
+    "@kuralle-agents/realtime-audio": "0.6.0"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",
@@ -108,7 +114,10 @@
     "build": "tsc -p tsconfig.json",
     "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
     "clean": "rm -rf dist",
-    "test": "bun test test",
+    "test": "bun test ./test && vitest run --config vitest.config.ts",
+    "test:journal-key-workers": "vitest run --config vitest.config.ts",
+    "test:workspace-autoregister": "bun test ./test/core-workspace/workspace-autoregister.test.ts",
+    "test:skill-wire": "bun test ./test/core-skills/skill-wire.test.ts",
     "smoke:textdriver": "bun test ./test/core-channel/textdriver.smoke.ts",
     "smoke:flow": "bun test ./test/core-flow/flow.smoke.ts",
     "smoke:agent": "bun test ./test/core-agent/agent.smoke.ts",