@kuralle-agents/core 0.5.0 → 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' });

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,10 +70,15 @@ 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';

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,7 +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');
+        });
+    });
+}

package/dist/memory/index.d.ts

@@ -4,7 +4,11 @@ export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
 export { preloadMemoryContext } from './preloadMemory.js';
 export { extractMemories } from './utils.js';
 export type { PersistentMemoryStore, PersistentMemoryBlock, PersistentMemoryConfig, MemoryBlockScope, } from './blocks/types.js';
+export type { WorkingMemoryBlockSpec, WorkingMemoryConfig } from '../types/grounding.js';
 export { DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './blocks/types.js';
+export { InMemoryPersistentMemoryStore } from './blocks/InMemoryPersistentMemoryStore.js';
 export { FilePersistentMemoryStore, type FilePersistentMemoryStoreOptions, } from './blocks/FilePersistentMemoryStore.js';
+export { RoutedPersistentMemoryStore, type RoutedPersistentMemoryStoreConfig, type MemoryRouteFn, } from './blocks/RoutedPersistentMemoryStore.js';
+export { TieredPersistentMemoryStore } from './blocks/TieredPersistentMemoryStore.js';
 export { scanMemoryWrite, type SafetyScanResult } from './blocks/safetyScanner.js';
 export { buildMemoryBlockTool, type MemoryBlockToolOptions } from './blocks/memoryBlockTool.js';

package/dist/memory/index.js

@@ -2,6 +2,9 @@ export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
 export { preloadMemoryContext } from './preloadMemory.js';
 export { extractMemories } from './utils.js';
 export { DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './blocks/types.js';
+export { InMemoryPersistentMemoryStore } from './blocks/InMemoryPersistentMemoryStore.js';
 export { FilePersistentMemoryStore, } from './blocks/FilePersistentMemoryStore.js';
+export { RoutedPersistentMemoryStore, } from './blocks/RoutedPersistentMemoryStore.js';
+export { TieredPersistentMemoryStore } from './blocks/TieredPersistentMemoryStore.js';
 export { scanMemoryWrite } from './blocks/safetyScanner.js';
 export { buildMemoryBlockTool } from './blocks/memoryBlockTool.js';

package/dist/runtime/Runtime.d.ts

@@ -13,6 +13,7 @@ import type { ConversationOutcome, ConversationOutcomeMarkedBy } from '../outcom
 import type { selectHostTarget } from './select.js';
 import type { KnowledgeProviderConfig } from '../types/voice.js';
 import type { MemoryService as V1MemoryService } from '../memory/MemoryService.js';
+import type { PersistentMemoryStore } from '../memory/blocks/types.js';
 export interface HarnessConfig {
     agents: AgentConfig[];
     defaultAgentId: string;
@@ -26,6 +27,8 @@ export interface HarnessConfig {
     tools?: Record<string, AnyTool>;
     knowledge?: KnowledgeProviderConfig;
     memoryService?: V1MemoryService;
+    /** Default store for `agent.memory.workingMemory` when `workingMemory.store` is omitted. */
+    defaultWorkingMemoryStore?: PersistentMemoryStore;
 }
 export interface RunOptions {
     sessionId?: string;

package/dist/runtime/Runtime.js

@@ -5,6 +5,8 @@ import { TextDriver } from './channels/TextDriver.js';
 import { createRunContext } from './ctx.js';
 import { createEventBus, createTurnHandle } from '../events/TurnHandle.js';
 import { CoreToolExecutor } from '../tools/effect/index.js';
+import { createFsTool } from '../tools/fs/createFsTool.js';
+import { wireAgentSkills } from '../skills/wireAgentSkills.js';
 import { hostLoop } from './hostLoop.js';
 import { isDegradableRuntimeError } from '../flow/degradableErrors.js';
 import { SAFE_DEGRADED_MESSAGE } from '../flow/degrade.js';
@@ -14,7 +16,8 @@ import { SessionRunStore } from './durable/SessionRunStore.js';
 import { loadRecordedSteps } from './durable/replay.js';
 import { markSessionOutcome } from './outcomeMarking.js';
 import { resolveAgentPolicies } from './policies/resolvePolicies.js';
-import { buildAutoRetrieveProvider, buildKnowledgeProvider, buildMemoryService, runMemoryIngest, } from './grounding/index.js';
+import { buildAutoRetrieveProvider, buildKnowledgeProvider, buildMemoryService, runMemoryIngest, wireWorkingMemory, } from './grounding/index.js';
+import { resolveAgentWorkspace } from './resolveAgentWorkspace.js';
 import { SessionMutex } from './SessionMutex.js';
 export class Runtime {
     config;
@@ -62,16 +65,38 @@ export class Runtime {
                 sessionStore: this.sessionStore,
             });
             const policies = resolveAgentPolicies(opened.agent);
-            const effectTools = {
+            const agentTools = {
                 ...(this.config.tools ?? {}),
-                ...(opened.agent.effectTools ?? {}),
+                ...(opened.agent.tools ?? {}),
                 // Global tools (ADR 0001) are model-visible in speaking turns via the
                 // drivers; register their executors here too so a model call can actually
                 // run them. Visibility stays gated (not exposed during collect extraction).
                 ...(opened.agent.globalTools ?? {}),
             };
+            const resolvedWorkspace = resolveAgentWorkspace(opened.agent.workspace);
+            if (resolvedWorkspace) {
+                agentTools.workspace = createFsTool({
+                    fs: resolvedWorkspace.fs,
+                    readOnly: resolvedWorkspace.readOnly,
+                });
+            }
+            const wiredWorkingMemory = await wireWorkingMemory(opened.agent, opened.session, this.config.defaultWorkingMemoryStore);
+            if (wiredWorkingMemory) {
+                agentTools.memory_block = wiredWorkingMemory.memoryBlockTool;
+            }
+            let skillPrompt;
+            let skillTools = {};
+            if (opened.agent.skills) {
+                const wired = await wireAgentSkills(opened.agent);
+                if (wired) {
+                    skillTools = wired.tools;
+                    Object.assign(agentTools, wired.tools);
+                    skillPrompt = wired.promptSections.map((s) => s.content).join('\n\n');
+                }
+            }
+            const workspaceTool = agentTools.workspace;
             const toolExecutor = new CoreToolExecutor({
-                tools: effectTools,
+                tools: agentTools,
                 enforcer: policies.enforcer,
                 agentId: opened.agent.id,
                 onInterim: (message) => {
@@ -111,11 +136,23 @@ export class Runtime {
                 memoryService: this.config.memoryService
                     ? buildMemoryService(this.config.memoryService, opened.agent)
                     : undefined,
+                fs: resolvedWorkspace?.fs,
             });
             // Agent base layer (ADR 0001): composed into every node turn by the drivers.
             runCtx.baseInstructions = opened.agent.instructions;
-            runCtx.globalTools = opened.agent.globalTools;
+            runCtx.globalTools = {
+                ...(opened.agent.globalTools ?? {}),
+                ...(workspaceTool && resolvedWorkspace?.readOnly !== false
+                    ? { workspace: workspaceTool }
+                    : {}),
+                ...skillTools,
+            };
             runCtx.outOfBandControl = opened.agent.experimental?.outOfBandControl ?? false;
+            runCtx.skillPrompt = skillPrompt;
+            runCtx.workingMemoryPrompt = wiredWorkingMemory?.promptSection;
+            runCtx.workingMemoryTools = wiredWorkingMemory
+                ? { memory_block: wiredWorkingMemory.memoryBlockTool }
+                : undefined;
             await this.hooks?.onStart?.(runCtx);
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;
@@ -160,6 +197,11 @@ export class Runtime {
                         runCtx.memoryService = this.config.memoryService
                             ? buildMemoryService(this.config.memoryService, target)
                             : undefined;
+                        const targetWorkingMemory = await wireWorkingMemory(target, opened.session, this.config.defaultWorkingMemoryStore);
+                        runCtx.workingMemoryPrompt = targetWorkingMemory?.promptSection;
+                        runCtx.workingMemoryTools = targetWorkingMemory
+                            ? { memory_block: targetWorkingMemory.memoryBlockTool }
+                            : undefined;
                         await runCtx.runStore.putRunState(runCtx.runState);
                         continue;
                     }

package/dist/runtime/agentReply.js

@@ -1,3 +1,4 @@
+import { buildToolSet } from '../tools/effect/defineTool.js';
 export function buildAgentReplyNode(agent) {
     const label = agent.name ?? agent.id;
     const instructions = agent.instructions ??
@@ -6,7 +7,7 @@ export function buildAgentReplyNode(agent) {
         kind: 'reply',
         id: `${agent.id}__host`,
         instructions,
-        tools: agent.tools,
+        tools: agent.tools ? buildToolSet(agent.tools) : undefined,
         model: agent.model,
     };
 }

package/dist/runtime/channels/TextDriver.js

@@ -38,7 +38,7 @@ export class TextDriver {
         const out = { text: '', toolResults: [] };
         const model = replyNode.model ?? ctx.model;
         const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
-        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
         const messages = [...ctx.runState.messages];
         const aiTools = this.resolveTools(node, ctx);
@@ -137,7 +137,7 @@ export class TextDriver {
         return runSilentExtraction(node, ctx, ctx.controlModel, resolveMaxSteps(ctx.limits, this.maxSteps));
     }
     async runStructured(node, ctx) {
-        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         return resolveStructuredDecide(node, ctx, system);
     }
     async awaitUser(ctx) {
@@ -149,6 +149,7 @@ export class TextDriver {
         const merged = {
             ...this.toolDefs,
             ...(ctx.globalTools ?? {}),
+            ...(ctx.workingMemoryTools ?? {}),
             ...(resolved.localTools ?? {}),
         };
         const aiTools = { ...resolved.tools };

package/dist/runtime/channels/VoiceDriver.js

@@ -63,9 +63,9 @@ export class VoiceDriver {
         const gather = await runGatherPhase(ctx, scope);
         const out = { text: '', toolResults: [] };
         const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
-        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
-        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}) }, { siloFlowControl: ctx.outOfBandControl && !node.freeConversation });
+        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}), ...(ctx.workingMemoryTools ?? {}) }, { siloFlowControl: ctx.outOfBandControl && !node.freeConversation });
         const toolCallsMade = [];
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         const mode = resolveStreamMode(ctx, node);
@@ -139,7 +139,7 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         return resolveStructuredDecide(node, ctx, system);
     }
     // Non-speaking collect extraction: uses the shared text-model extraction path

package/dist/runtime/channels/extractionTurn.js

@@ -15,7 +15,7 @@ import { buildNodePrompt, composeSystem } from '../../flow/nodeBuilders.js';
 export async function runSilentExtraction(node, ctx, model, maxSteps) {
     const replyNode = node.node;
     const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
-    const system = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
+    const system = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
     const messages = [...ctx.runState.messages];
     const aiTools = resolveExtractionTools(node);
     const out = { text: '', toolResults: [] };

package/dist/runtime/ctx.d.ts

@@ -6,6 +6,7 @@ import type { RefinementCapability } from '../capabilities/RefinementCapability.
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { InputProcessor, OutputProcessor } from '../types/processors.js';
 import type { Limits } from '../types/guardrails.js';
+import type { FileSystem } from '../types/filesystem.js';
 import type { RunState, StepRecord } from './durable/types.js';
 import type { RunStore } from './durable/RunStore.js';
 interface EffectClock {
@@ -29,6 +30,7 @@ export interface CtxDeps {
     limits?: Limits;
     autoRetrieve?: AutoRetrieveProvider;
     memoryService?: MemoryService;
+    fs?: FileSystem;
     bargeIn?: AbortSignal;
     abortSignal?: AbortSignal;
     clock?: EffectClock;

package/dist/runtime/ctx.js

@@ -108,6 +108,7 @@ function makeCtx(deps) {
         limits: deps.limits,
         autoRetrieve: deps.autoRetrieve,
         memoryService: deps.memoryService,
+        fs: deps.fs,
         bargeIn: deps.bargeIn,
         abortSignal: deps.abortSignal,
         turnInputConsumed: false,

package/dist/runtime/grounding/defaultStoreRegistry.d.ts

@@ -0,0 +1,3 @@
+import type { PersistentMemoryStore } from '../../memory/blocks/types.js';
+export declare function registerNodeDefaultWorkingMemoryStore(factory: () => PersistentMemoryStore): void;
+export declare function getNodeDefaultWorkingMemoryStore(): (() => PersistentMemoryStore) | undefined;