@kuralle-agents/core 0.5.0 → 0.6.0

package/dist/types/agentConfig.d.ts

@@ -1,4 +1,4 @@
-import type { LanguageModel, ToolSet } from 'ai';
+import type { LanguageModel } from 'ai';
 import type { AgentPrompt } from '../prompts/AgentPrompt.js';
 import type { Flow } from './flow.js';
 import type { Route, RoutingPolicy } from './route.js';
@@ -7,6 +7,12 @@ import type { AgentKnowledge, AgentMemory } from './grounding.js';
 import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { AnyTool } from './effectTool.js';
+import type { FileSystem } from './filesystem.js';
+import type { SkillSource } from './skills.js';
+export type AgentWorkspaceConfig = FileSystem | {
+    fs: FileSystem;
+    readOnly?: boolean;
+};
 export type Instructions = string | AgentPrompt | ((ctx: {
     state: Record<string, unknown>;
 }) => Instructions | Promise<Instructions>);
@@ -20,8 +26,8 @@ export interface AgentConfig {
      *  temperature 0 for determinism. Defaults to `model` (the speaker) when unset.
      *  Set this to pin control to a reliable provider independent of the speaker. */
     controlModel?: LanguageModel;
-    tools?: ToolSet;
-    effectTools?: Record<string, AnyTool>;
+    /** Durable, model-callable effect tools (exactly-once on replay). Wrap raw AI SDK tools with wrapAiSdkTool(). */
+    tools?: Record<string, AnyTool>;
     /** Safe, always-available tools made model-visible in EVERY speaking node turn
      *  (the agent "base layer", ADR 0001) — e.g. a returns/FAQ knowledge-base
      *  lookup the user might ask for mid-flow. This is an explicit allow-list:
@@ -45,5 +51,12 @@ export interface AgentConfig {
         /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1). Default OFF. */
         outOfBandControl?: boolean;
     };
+    /** Portable workspace filesystem; auto-registers the durable `workspace` tool when set.
+     *  Defaults to read-only; pass `{ fs, readOnly: false }` for write/edit. Read-only workspaces
+     *  are exposed in globalTools (ADR 0001); read-write ones are executor-only. */
+    workspace?: AgentWorkspaceConfig;
+    /** Bundled procedural skills (Anthropic Agent Skill model): Level-1 name+description in prompt,
+     *  body via `load_skill`, resources via `read_skill_resource`. Scripts = `allowedTools` only. */
+    skills?: SkillSource;
 }
 export declare function defineAgent(config: AgentConfig): AgentConfig;

package/dist/types/filesystem.d.ts

@@ -0,0 +1,85 @@
+export type FileSystemEntryType = 'file' | 'directory' | 'symlink';
+export type BufferEncoding = 'utf8' | 'utf-8' | 'ascii' | 'binary' | 'base64' | 'hex' | 'latin1';
+export type FileContent = string | Uint8Array;
+export interface FsStat {
+    type: FileSystemEntryType;
+    size: number;
+    mtime: Date;
+    mode?: number;
+}
+export interface FileSystemDirent {
+    name: string;
+    type: FileSystemEntryType;
+}
+export interface MkdirOptions {
+    recursive?: boolean;
+}
+export interface RmOptions {
+    recursive?: boolean;
+    force?: boolean;
+}
+export interface CpOptions {
+    recursive?: boolean;
+}
+export interface FileSystem {
+    readFile(path: string): Promise<string>;
+    readFileBytes(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    writeFileBytes(path: string, content: Uint8Array): Promise<void>;
+    appendFile(path: string, content: string | Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<FileSystemDirent[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    resolvePath(base: string, path: string): string;
+    glob(pattern: string): Promise<string[]>;
+}
+export interface ReadFileOptions {
+    encoding?: BufferEncoding | null;
+}
+export interface WriteFileOptions {
+    encoding?: BufferEncoding;
+}
+export interface FileEntry {
+    type: 'file';
+    content: string | Uint8Array;
+    mode: number;
+    mtime: Date;
+}
+export interface DirectoryEntry {
+    type: 'directory';
+    mode: number;
+    mtime: Date;
+}
+export interface SymlinkEntry {
+    type: 'symlink';
+    target: string;
+    mode: number;
+    mtime: Date;
+}
+export interface LazyFileEntry {
+    type: 'file';
+    lazy: () => string | Uint8Array | Promise<string | Uint8Array>;
+    mode: number;
+    mtime: Date;
+}
+export type FsEntry = FileEntry | LazyFileEntry | DirectoryEntry | SymlinkEntry;
+export interface FileInit {
+    content: FileContent;
+    mode?: number;
+    mtime?: Date;
+}
+export type LazyFileProvider = () => string | Uint8Array | Promise<string | Uint8Array>;
+export type InitialFiles = Record<string, FileContent | FileInit | LazyFileProvider>;
+export interface FsError extends Error {
+    code?: string;
+}
+export declare function fsErrorCode(err: unknown): string | undefined;

package/dist/types/filesystem.js

@@ -0,0 +1,6 @@
+export function fsErrorCode(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const match = err.message.match(/^([A-Z]+):/);
+    return match?.[1];
+}

package/dist/types/grounding.d.ts

@@ -1,7 +1,17 @@
+import type { MemoryBlockScope, PersistentMemoryConfig } from '../memory/blocks/types.js';
 export interface AgentKnowledge {
     autoRetrieve?: boolean;
     sources?: string[];
 }
+export interface WorkingMemoryBlockSpec {
+    scope: MemoryBlockScope;
+    key: string;
+    /** Seed content when the block is missing or empty (persisted on first write, not on read). */
+    template?: string;
+}
+export interface WorkingMemoryConfig extends Omit<PersistentMemoryConfig, 'autoLoad'> {
+    autoLoad?: WorkingMemoryBlockSpec[];
+}
 export interface AgentMemory {
     preload?: {
         enabled?: boolean;
@@ -10,4 +20,6 @@ export interface AgentMemory {
     ingest?: {
         enabled?: boolean;
     };
+    /** Persistent markdown blocks (USER/MEMORY) loaded at session start and editable via memory_block. */
+    workingMemory?: WorkingMemoryConfig;
 }

package/dist/types/index.d.ts

@@ -2,6 +2,8 @@ export * from './selection.js';
 export * from './telemetry.js';
 export * from './processors.js';
 export * from './agentConfig.js';
+export * from './filesystem.js';
+export * from './skills.js';
 export * from './flow.js';
 export * from './session.js';
 export * from './tool.js';

package/dist/types/index.js

@@ -2,6 +2,8 @@ export * from './selection.js';
 export * from './telemetry.js';
 export * from './processors.js';
 export * from './agentConfig.js';
+export * from './filesystem.js';
+export * from './skills.js';
 export * from './flow.js';
 export * from './session.js';
 export * from './tool.js';

package/dist/types/run-context.d.ts

@@ -8,6 +8,7 @@ import type { RefinementCapability } from '../capabilities/RefinementCapability.
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
+import type { FileSystem } from './filesystem.js';
 import type { Instructions } from './agentConfig.js';
 import type { AgentKnowledgeOverrides, SourceRef } from './voice.js';
 export interface GatherScope {
@@ -85,6 +86,14 @@ export interface RunContext {
      *  in every speaking turn. */
     baseInstructions?: Instructions;
     globalTools?: Record<string, AnyTool>;
+    /** Level-1 skill metadata injected by `SkillsCapability` when `AgentConfig.skills` is set. */
+    skillPrompt?: string;
+    /** Frozen persistent memory blocks loaded at session start (`AgentMemory.workingMemory`). */
+    workingMemoryPrompt?: string;
+    /** Model-visible tools from working memory wiring (not in globalTools — mutating but scoped). */
+    workingMemoryTools?: Record<string, AnyTool>;
+    /** Agent workspace filesystem (same instance as `AgentConfig.workspace`). */
+    fs?: FileSystem;
     tool(name: string, args: unknown, options?: {
         toolCallId?: string;
         def?: AnyTool;
@@ -104,6 +113,6 @@ export interface RunContext {
     now(): Promise<number>;
     uuid(): Promise<string>;
 }
-export type ActionContext = Pick<RunContext, 'tool' | 'approve' | 'signal' | 'now' | 'uuid' | 'emit'>;
-export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit'>;
+export type ActionContext = Pick<RunContext, 'tool' | 'approve' | 'signal' | 'now' | 'uuid' | 'emit' | 'fs'>;
+export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit' | 'fs'>;
 export type { ModelMessage };

package/dist/types/skills.d.ts

@@ -0,0 +1,19 @@
+export interface SkillMeta {
+    name: string;
+    description: string;
+}
+export interface SkillLike {
+    name: string;
+    description: string;
+    body: string;
+    resources?: Record<string, string | Uint8Array>;
+    allowedTools?: string[];
+}
+export interface SkillStoreLike {
+    list(): Promise<SkillMeta[]>;
+    loadBody(name: string): Promise<string>;
+    loadResource(name: string, path: string): Promise<string | Uint8Array>;
+    getAllSkills?(): SkillLike[] | Promise<SkillLike[]>;
+    loadAllSkills?(): Promise<SkillLike[]>;
+}
+export type SkillSource = SkillLike | SkillLike[] | SkillStoreLike;

package/dist/types/skills.js

@@ -0,0 +1 @@
+export {};

package/guides/AGENTS.md

@@ -16,7 +16,7 @@ const model = openai('gpt-4o-mini');
 | Fields | Effect |
 |--------|--------|
 | `id`, `model`, `instructions` | Base conversational agent |
-| `tools`, `effectTools` | Tool access during free conversation and flow nodes |
+| `tools`, `globalTools` | Durable tool access during free conversation and flow nodes |
 | `flows` | Structured multi-step SOPs (`defineFlow` + node builders) |
 | `routes`, `routing` | Route to flows or specialist agents |
 | `agents` | Nested sub-agent configs for composition |
@@ -210,8 +210,7 @@ const lead = defineAgent({
   instructions:
     'Research assistant. Use consult_weather for weather and consult_news for news. Combine answers clearly.',
   model,
-  tools: buildToolSet(tools),
-  effectTools: tools,
+  tools: tools,
 });
 
 const runtime = createRuntime({

package/guides/FLOWS.md

@@ -29,7 +29,7 @@ const collectDate = defineTool({
 const greeting = reply({
   id: 'greeting',
   instructions: 'Welcome. What date would you like to book?',
-  tools: { collect_date: collectDate }, // wire via effectTools + ToolSet in production
+  tools: { collect_date: collectDate }, // wire via tools + ToolSet in production
   next: (turn) => {
     const r = turn.toolResults.find((t) => t.name === 'collect_date');
     return r?.result ? { goto: confirm, data: r.result as Record<string, unknown> } : 'stay';
@@ -46,7 +46,7 @@ const agent = defineAgent({
   id: 'booking',
   instructions: 'You are a booking assistant.',
   model,
-  effectTools: { collect_date: collectDate },
+  tools: { collect_date: collectDate },
   flows: [
     defineFlow({
       name: 'booking',

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.5.0",
+  "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.5.0"
+    "@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",