@kuralle-agents/core 0.5.0 → 0.6.0

package/dist/runtime/grounding/defaultStoreRegistry.js

@@ -0,0 +1,10 @@
+let nodeDefaultStoreFactory;
+export function registerNodeDefaultWorkingMemoryStore(factory) {
+    nodeDefaultStoreFactory = factory;
+}
+export function getNodeDefaultWorkingMemoryStore() {
+    if (typeof process === 'undefined' || !process.versions?.node) {
+        return undefined;
+    }
+    return nodeDefaultStoreFactory;
+}

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

@@ -1,5 +1,6 @@
 export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } from './knowledge.js';
 export { buildMemoryService, resetMissingUserIdWarningsForTests, runMemoryIngest, warnMissingUserId, } from './memory.js';
+export { wireWorkingMemory, loadWorkingMemoryBlocks, formatWorkingMemorySection, resolveWorkingMemoryStore, resolveWorkingMemoryOwner, type LoadedWorkingMemoryBlock, type WiredWorkingMemory, } from './workingMemory.js';
 export { runGatherPhase, type GatherResult, type GatherScope } from './gather.js';
 export { resolveNodeGatherScope } from './nodeScope.js';
 export { createInMemoryKnowledgeConfig, createInMemoryKnowledgeRetriever, type InMemoryKnowledgeDocument, } from './inMemoryKnowledge.js';

package/dist/runtime/grounding/index.js

@@ -1,5 +1,6 @@
 export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } from './knowledge.js';
 export { buildMemoryService, resetMissingUserIdWarningsForTests, runMemoryIngest, warnMissingUserId, } from './memory.js';
+export { wireWorkingMemory, loadWorkingMemoryBlocks, formatWorkingMemorySection, resolveWorkingMemoryStore, resolveWorkingMemoryOwner, } from './workingMemory.js';
 export { runGatherPhase } from './gather.js';
 export { resolveNodeGatherScope } from './nodeScope.js';
 export { createInMemoryKnowledgeConfig, createInMemoryKnowledgeRetriever, } from './inMemoryKnowledge.js';

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

@@ -0,0 +1,19 @@
+import type { AgentConfig } from '../../types/agentConfig.js';
+import type { WorkingMemoryBlockSpec, WorkingMemoryConfig } from '../../types/grounding.js';
+import type { Session } from '../../types/session.js';
+import type { AnyTool } from '../../types/effectTool.js';
+import { type MemoryBlockScope, type PersistentMemoryStore } from '../../memory/blocks/types.js';
+export interface LoadedWorkingMemoryBlock {
+    scope: MemoryBlockScope;
+    key: string;
+    content: string;
+}
+export interface WiredWorkingMemory {
+    promptSection: string | undefined;
+    memoryBlockTool: AnyTool;
+}
+export declare function resolveWorkingMemoryStore(config: WorkingMemoryConfig, harnessDefault?: PersistentMemoryStore): PersistentMemoryStore;
+export declare function resolveWorkingMemoryOwner(scope: MemoryBlockScope, agentId: string, userId: string | undefined): string;
+export declare function loadWorkingMemoryBlocks(store: PersistentMemoryStore, autoLoad: WorkingMemoryBlockSpec[], resolveOwner: (scope: MemoryBlockScope) => string): Promise<LoadedWorkingMemoryBlock[]>;
+export declare function formatWorkingMemorySection(blocks: LoadedWorkingMemoryBlock[], autoLoad: WorkingMemoryBlockSpec[]): string | undefined;
+export declare function wireWorkingMemory(agent: AgentConfig, session: Session, harnessDefaultStore?: PersistentMemoryStore): Promise<WiredWorkingMemory | undefined>;

package/dist/runtime/grounding/workingMemory.js

@@ -0,0 +1,80 @@
+import { buildMemoryBlockTool } from '../../memory/blocks/memoryBlockTool.js';
+import { DEFAULT_AUTO_LOAD_BLOCKS, DEFAULT_BLOCK_CHAR_LIMIT, } from '../../memory/blocks/types.js';
+import { wrapAiSdkTool } from '../../tools/effect/wrapAiSdkTool.js';
+import { getNodeDefaultWorkingMemoryStore } from './defaultStoreRegistry.js';
+export function resolveWorkingMemoryStore(config, harnessDefault) {
+    if (config.store) {
+        return config.store;
+    }
+    if (harnessDefault) {
+        return harnessDefault;
+    }
+    const factory = getNodeDefaultWorkingMemoryStore();
+    if (factory) {
+        return factory();
+    }
+    throw new Error('[Kuralle] agent.memory.workingMemory requires a store. Pass workingMemory.store, ' +
+        'HarnessConfig.defaultWorkingMemoryStore, or import FilePersistentMemoryStore on Node.');
+}
+export function resolveWorkingMemoryOwner(scope, agentId, userId) {
+    return scope === 'agent' ? agentId : (userId ?? 'anonymous');
+}
+export async function loadWorkingMemoryBlocks(store, autoLoad, resolveOwner) {
+    const loaded = [];
+    for (const spec of autoLoad) {
+        const owner = resolveOwner(spec.scope);
+        const block = await store.loadBlock(spec.scope, owner, spec.key);
+        let content = block?.content?.trim() ?? '';
+        if (!content && spec.template) {
+            content = spec.template.trim();
+        }
+        if (content) {
+            loaded.push({ scope: spec.scope, key: spec.key, content });
+        }
+    }
+    return loaded;
+}
+export function formatWorkingMemorySection(blocks, autoLoad) {
+    if (autoLoad.length === 0) {
+        return undefined;
+    }
+    const byKey = new Map(blocks.map((b) => [`${b.scope}/${b.key}`, b]));
+    // Directive (Mastra-informed): the model must proactively maintain these blocks
+    // via the `memory_block` tool, not just read them. Rendered even when blocks are
+    // empty so a first-time conversation knows the capability exists.
+    const lines = [
+        '## Working memory',
+        '',
+        'You keep durable notes about the user and conversation in the blocks below, persisted across sessions. Use the `memory_block` tool to keep them current:',
+        '- When the user shares a durable fact or preference (name, account details, preferences, anything that may be referenced again), call `memory_block` with action `add`, the relevant block, and a short factual entry. Store proactively — if unsure whether it will matter later, store it.',
+        '- Answer questions about stored information from these blocks first; you do NOT need to call the tool to read them.',
+        '- Do not announce that you are saving, and do not call the tool when nothing relevant changed.',
+        '',
+    ];
+    for (const spec of autoLoad) {
+        const block = byKey.get(`${spec.scope}/${spec.key}`);
+        lines.push(`### ${spec.key} (${spec.scope})`);
+        lines.push(block?.content?.trim() || '(empty — add entries here as you learn them)');
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+export async function wireWorkingMemory(agent, session, harnessDefaultStore) {
+    const config = agent.memory?.workingMemory;
+    if (!config) {
+        return undefined;
+    }
+    const store = resolveWorkingMemoryStore(config, harnessDefaultStore);
+    const autoLoad = config.autoLoad ?? DEFAULT_AUTO_LOAD_BLOCKS;
+    const charLimit = config.defaultCharLimit ?? DEFAULT_BLOCK_CHAR_LIMIT;
+    const resolveOwner = (scope) => resolveWorkingMemoryOwner(scope, agent.id, session.userId);
+    const loaded = await loadWorkingMemoryBlocks(store, autoLoad, resolveOwner);
+    const promptSection = formatWorkingMemorySection(loaded, autoLoad);
+    const memoryBlockTool = wrapAiSdkTool('memory_block', buildMemoryBlockTool({
+        store,
+        resolveOwner,
+        charLimit,
+        scanForInjection: config.scanForInjection,
+    }));
+    return { promptSection, memoryBlockTool };
+}

package/dist/runtime/resolveAgentWorkspace.d.ts

@@ -0,0 +1,10 @@
+import type { FileSystem } from '../types/filesystem.js';
+export type AgentWorkspaceConfig = FileSystem | {
+    fs: FileSystem;
+    readOnly?: boolean;
+};
+export interface ResolvedAgentWorkspace {
+    fs: FileSystem;
+    readOnly: boolean;
+}
+export declare function resolveAgentWorkspace(workspace: AgentWorkspaceConfig | undefined): ResolvedAgentWorkspace | undefined;

package/dist/runtime/resolveAgentWorkspace.js

@@ -0,0 +1,9 @@
+export function resolveAgentWorkspace(workspace) {
+    if (!workspace) {
+        return undefined;
+    }
+    if (typeof workspace === 'object' && workspace !== null && 'fs' in workspace) {
+        return { fs: workspace.fs, readOnly: workspace.readOnly !== false };
+    }
+    return { fs: workspace, readOnly: true };
+}

package/dist/skills/SkillsCapability.d.ts

@@ -0,0 +1,10 @@
+import type { Capability, CapabilityAction, PromptSection, ToolDeclaration } from '../capabilities/index.js';
+import type { SkillMeta, SkillStoreLike } from '../types/skills.js';
+export declare class SkillsCapability implements Capability {
+    private readonly store;
+    private readonly metas;
+    constructor(store: SkillStoreLike, metas: SkillMeta[]);
+    getTools(): ToolDeclaration[];
+    getPromptSections(): PromptSection[];
+    processToolResult(_toolName: string, _args: unknown, _result: unknown): CapabilityAction | null;
+}

package/dist/skills/SkillsCapability.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export class SkillsCapability {
+    store;
+    metas;
+    constructor(store, metas) {
+        this.store = store;
+        this.metas = metas;
+    }
+    getTools() {
+        return [
+            {
+                name: 'load_skill',
+                description: "Load a skill's full instructions by name when the task matches its description.",
+                parameters: z.object({
+                    name: z.string().describe('Skill name from the available skills list'),
+                }),
+                execute: async (args) => ({
+                    body: await this.store.loadBody(args.name),
+                }),
+            },
+            {
+                name: 'read_skill_resource',
+                description: 'Read a bundled resource file from a skill (reference docs, checklists, etc.).',
+                parameters: z.object({
+                    name: z.string().describe('Skill name'),
+                    path: z.string().describe('Relative resource path within the skill folder'),
+                }),
+                execute: async (args) => ({
+                    content: await this.store.loadResource(args.name, args.path),
+                }),
+            },
+        ];
+    }
+    getPromptSections() {
+        if (!this.metas.length)
+            return [];
+        const lines = this.metas.map((m) => `- ${m.name}: ${m.description}`).join('\n');
+        return [
+            {
+                role: 'context',
+                content: [
+                    '## Available skills',
+                    'Load a skill with load_skill when its description matches the task:',
+                    lines,
+                ].join('\n'),
+            },
+        ];
+    }
+    processToolResult(_toolName, _args, _result) {
+        return null;
+    }
+}

package/dist/skills/collectSkills.d.ts

@@ -0,0 +1,17 @@
+import type { AnyTool } from '../types/effectTool.js';
+import type { SkillLike, SkillSource, SkillStoreLike } from '../types/skills.js';
+export interface SkillWireAgent {
+    skills?: SkillSource;
+    tools?: Record<string, AnyTool>;
+    globalTools?: Record<string, AnyTool>;
+    flows?: Array<{
+        name: string;
+    }>;
+}
+export declare function isSkillStore(value: SkillSource): value is SkillStoreLike;
+export declare function collectRegisteredNames(agent: SkillWireAgent): Set<string>;
+export declare function validateSkillAllowedTools(skills: SkillLike[], registered: Set<string>): void;
+export declare function prepareSkillStore(source: SkillSource): Promise<{
+    store: SkillStoreLike;
+    skills: SkillLike[];
+}>;

package/dist/skills/collectSkills.js

@@ -0,0 +1,56 @@
+import { InlineSkillStore } from './inlineSkillStore.js';
+export function isSkillStore(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        'list' in value &&
+        typeof value.list === 'function');
+}
+async function collectSkillsFromSource(source) {
+    if (!isSkillStore(source)) {
+        return Array.isArray(source) ? source : [source];
+    }
+    if (typeof source.getAllSkills === 'function') {
+        const all = source.getAllSkills();
+        return Array.isArray(all) ? all : await all;
+    }
+    if (typeof source.loadAllSkills === 'function') {
+        return source.loadAllSkills();
+    }
+    const metas = await source.list();
+    const skills = [];
+    for (const meta of metas) {
+        const body = await source.loadBody(meta.name);
+        skills.push({ name: meta.name, description: meta.description, body });
+    }
+    return skills;
+}
+export function collectRegisteredNames(agent) {
+    const names = new Set();
+    for (const [key, tool] of Object.entries(agent.tools ?? {})) {
+        names.add(tool.name ?? key);
+    }
+    for (const [key, tool] of Object.entries(agent.globalTools ?? {})) {
+        names.add(tool.name ?? key);
+    }
+    for (const flow of agent.flows ?? []) {
+        names.add(flow.name);
+    }
+    return names;
+}
+export function validateSkillAllowedTools(skills, registered) {
+    for (const skill of skills) {
+        for (const toolName of skill.allowedTools ?? []) {
+            if (!registered.has(toolName)) {
+                throw new Error(`skill ${skill.name}: unknown tool ${toolName}`);
+            }
+        }
+    }
+}
+export async function prepareSkillStore(source) {
+    if (isSkillStore(source)) {
+        return { store: source, skills: await collectSkillsFromSource(source) };
+    }
+    const skills = Array.isArray(source) ? source : [source];
+    return { store: new InlineSkillStore(skills), skills };
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,5 @@
+export { SkillsCapability } from './SkillsCapability.js';
+export { wireAgentSkills } from './wireAgentSkills.js';
+export type { WiredAgentSkills } from './wireAgentSkills.js';
+export { collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, type SkillWireAgent, } from './collectSkills.js';
+export { InlineSkillStore } from './inlineSkillStore.js';

package/dist/skills/index.js

@@ -0,0 +1,4 @@
+export { SkillsCapability } from './SkillsCapability.js';
+export { wireAgentSkills } from './wireAgentSkills.js';
+export { collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, } from './collectSkills.js';
+export { InlineSkillStore } from './inlineSkillStore.js';

package/dist/skills/inlineSkillStore.d.ts

@@ -0,0 +1,9 @@
+import type { SkillLike, SkillMeta, SkillStoreLike } from '../types/skills.js';
+export declare class InlineSkillStore implements SkillStoreLike {
+    private readonly byName;
+    constructor(skills: SkillLike[]);
+    list(): Promise<SkillMeta[]>;
+    loadBody(name: string): Promise<string>;
+    loadResource(name: string, path: string): Promise<string | Uint8Array>;
+    getAllSkills(): SkillLike[];
+}

package/dist/skills/inlineSkillStore.js

@@ -0,0 +1,37 @@
+export class InlineSkillStore {
+    byName;
+    constructor(skills) {
+        this.byName = new Map(skills.map((s) => [s.name, s]));
+    }
+    async list() {
+        return [...this.byName.values()].map((s) => ({
+            name: s.name,
+            description: s.description,
+        }));
+    }
+    async loadBody(name) {
+        const skill = this.byName.get(name);
+        if (!skill) {
+            throw new Error(`[skills] Skill "${name}" not found.`);
+        }
+        return skill.body;
+    }
+    async loadResource(name, path) {
+        const skill = this.byName.get(name);
+        if (!skill) {
+            throw new Error(`[skills] Skill "${name}" not found.`);
+        }
+        const normalized = path.trim().replace(/^\.?\//, '');
+        if (normalized.includes('..') || normalized.startsWith('/')) {
+            throw new Error(`[skills] Invalid resource path "${path}".`);
+        }
+        const content = skill.resources?.[normalized];
+        if (content === undefined) {
+            throw new Error(`[skills] Resource "${normalized}" not found for skill "${name}".`);
+        }
+        return content;
+    }
+    getAllSkills() {
+        return [...this.byName.values()];
+    }
+}

package/dist/skills/wireAgentSkills.d.ts

@@ -0,0 +1,10 @@
+import { type AnyTool } from '../types/effectTool.js';
+import type { PromptSection } from '../capabilities/index.js';
+import { type SkillWireAgent } from './collectSkills.js';
+import { SkillsCapability } from './SkillsCapability.js';
+export interface WiredAgentSkills {
+    capability: SkillsCapability;
+    tools: Record<string, AnyTool>;
+    promptSections: PromptSection[];
+}
+export declare function wireAgentSkills(agent: SkillWireAgent): Promise<WiredAgentSkills | undefined>;

package/dist/skills/wireAgentSkills.js

@@ -0,0 +1,25 @@
+import { defineTool } from '../types/effectTool.js';
+import { collectRegisteredNames, prepareSkillStore, validateSkillAllowedTools, } from './collectSkills.js';
+import { SkillsCapability } from './SkillsCapability.js';
+export async function wireAgentSkills(agent) {
+    if (!agent.skills)
+        return undefined;
+    const { store, skills } = await prepareSkillStore(agent.skills);
+    validateSkillAllowedTools(skills, collectRegisteredNames(agent));
+    const metas = await store.list();
+    const capability = new SkillsCapability(store, metas);
+    const tools = {};
+    for (const decl of capability.getTools()) {
+        tools[decl.name] = defineTool({
+            name: decl.name,
+            description: decl.description,
+            input: decl.parameters,
+            execute: async (args) => decl.execute(args),
+        });
+    }
+    return {
+        capability,
+        tools,
+        promptSections: capability.getPromptSections(),
+    };
+}

package/dist/tools/effect/defineTool.js

@@ -25,7 +25,7 @@ export function toolToAiSdk(def) {
 // `buildToolSet` produces a model-facing ToolSet whose entries are schema-only
 // (`toolToAiSdk` strips `execute`). Stash the raw effect tools (with executors),
 // keyed by the returned ToolSet, so a flow node can recover its executors for
-// in-flow execution without separately registering them on `agent.effectTools`
+// in-flow execution without separately registering them on `agent.tools`.
 // (see `resolveReplyNode`). The WeakMap is GC-friendly and invisible to callers.
 const rawToolsBySet = new WeakMap();
 export function buildToolSet(tools) {

package/dist/tools/effect/index.d.ts

@@ -1,4 +1,5 @@
 export { defineTool, toolToAiSdk, buildToolSet } from './defineTool.js';
+export { wrapAiSdkTool } from './wrapAiSdkTool.js';
 export { CoreToolExecutor } from './ToolExecutor.js';
 export type { CoreToolExecutorConfig, CoreExecuteArgs } from './ToolExecutor.js';
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';

package/dist/tools/effect/index.js

@@ -1,4 +1,5 @@
 export { defineTool, toolToAiSdk, buildToolSet } from './defineTool.js';
+export { wrapAiSdkTool } from './wrapAiSdkTool.js';
 export { CoreToolExecutor } from './ToolExecutor.js';
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';
 export { validateAndSanitize, validateOutput, ToolValidationError } from './schema.js';

package/dist/tools/effect/wrapAiSdkTool.d.ts

@@ -0,0 +1,3 @@
+import type { Tool as AiTool } from 'ai';
+import type { AnyTool } from '../../types/effectTool.js';
+export declare function wrapAiSdkTool(name: string, aiTool: AiTool): AnyTool;

package/dist/tools/effect/wrapAiSdkTool.js

@@ -0,0 +1,12 @@
+export function wrapAiSdkTool(name, aiTool) {
+    const exec = aiTool.execute;
+    if (typeof exec !== 'function') {
+        throw new Error(`wrapAiSdkTool("${name}"): AI SDK tool has no execute; use defineTool for schema-only tools.`);
+    }
+    return {
+        name,
+        description: aiTool.description ?? name,
+        input: aiTool.inputSchema,
+        execute: (args, ctx) => exec(args, ctx),
+    };
+}

package/dist/tools/fs/createFsTool.d.ts

@@ -0,0 +1,30 @@
+import type { AnyTool } from '../../types/effectTool.js';
+import { type FileSystem } from '../../types/filesystem.js';
+export interface CreateFsToolOptions {
+    fs: FileSystem;
+    readOnly?: boolean;
+    timeoutMs?: number;
+}
+export interface GrepHit {
+    path: string;
+    line: number;
+    text: string;
+}
+export interface FsSearchHit {
+    slug: string;
+    chunkIndex: number;
+    text: string;
+}
+export interface FsWithSearch extends FileSystem {
+    search?(pattern: string, opts?: {
+        limit?: number;
+        path?: string;
+    }): Promise<FsSearchHit[]>;
+}
+/**
+ * One durable `workspace` tool over a {@link FileSystem} (ls/cat/grep/find/read/write/edit).
+ * Lives in core (not `@kuralle-agents/fs`) because it needs only `defineTool` + the
+ * `FileSystem` interface — both core-owned — so the runtime can auto-register it with a
+ * static import and no core->fs dependency (RFC-02 §5.2). `@kuralle-agents/fs` re-exports it.
+ */
+export declare function createFsTool(opts: CreateFsToolOptions): AnyTool;

package/dist/tools/fs/createFsTool.js

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+import { defineTool } from '../effect/defineTool.js';
+import { fsErrorCode } from '../../types/filesystem.js';
+const DEFAULT_READ_ONLY = true;
+const workspaceInput = z.object({
+    op: z.enum(['ls', 'cat', 'grep', 'find', 'read', 'write', 'edit']),
+    path: z.string().optional(),
+    pattern: z.string().optional(),
+    root: z.string().optional(),
+    glob: z.string().optional(),
+    flags: z.string().optional(),
+    content: z.string().optional(),
+    find: z.string().optional(),
+    replace: z.string().optional(),
+});
+function normalizeFsPath(path, fallback = '/') {
+    if (!path || path.trim() === '')
+        return fallback;
+    return path;
+}
+function requireField(args, field, op) {
+    const value = args[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`EINVAL: missing ${String(field)} for workspace op '${op}'`);
+    }
+    return value;
+}
+function eroFs(path) {
+    return new Error(`EROFS: read-only filesystem, write '${path}'`);
+}
+function assertWritable(readOnly, path) {
+    if (readOnly)
+        throw eroFs(path);
+}
+async function listFiles(fs, root) {
+    const normalized = root === '' ? '/' : root;
+    const out = [];
+    const stack = [normalized];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (!(await fs.exists(dir))) {
+            throw new Error(`ENOENT: no such file or directory, find '${dir}'`);
+        }
+        const stat = await fs.stat(dir);
+        if (stat.type !== 'directory') {
+            out.push(dir);
+            continue;
+        }
+        const entries = await fs.readdirWithFileTypes(dir);
+        for (const entry of entries) {
+            const child = fs.resolvePath(dir, entry.name);
+            if (entry.type === 'directory') {
+                stack.push(child);
+            }
+            else {
+                out.push(child);
+            }
+        }
+    }
+    return out.sort();
+}
+async function grepFiles(fs, pattern, root, flags) {
+    let re;
+    try {
+        re = new RegExp(pattern, flags?.includes('i') ? 'i' : undefined);
+    }
+    catch {
+        throw new Error(`EINVAL: invalid grep pattern '${pattern}'`);
+    }
+    const searchable = fs;
+    if (searchable.search) {
+        const coarse = await searchable.search(pattern, { limit: 500, path: root });
+        const slugs = [...new Set(coarse.map((hit) => hit.slug))];
+        const hits = [];
+        for (const filePath of slugs) {
+            let content;
+            try {
+                content = await fs.readFile(filePath);
+            }
+            catch (err) {
+                if (fsErrorCode(err) === 'EISDIR')
+                    continue;
+                throw err;
+            }
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                if (re.test(lines[i])) {
+                    hits.push({ path: filePath, line: i + 1, text: lines[i] });
+                }
+            }
+        }
+        return hits;
+    }
+    const candidates = await listFiles(fs, root);
+    const hits = [];
+    for (const filePath of candidates) {
+        let content;
+        try {
+            content = await fs.readFile(filePath);
+        }
+        catch (err) {
+            if (fsErrorCode(err) === 'EISDIR')
+                continue;
+            throw err;
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (re.test(lines[i])) {
+                hits.push({ path: filePath, line: i + 1, text: lines[i] });
+            }
+        }
+    }
+    return hits;
+}
+/**
+ * One durable `workspace` tool over a {@link FileSystem} (ls/cat/grep/find/read/write/edit).
+ * Lives in core (not `@kuralle-agents/fs`) because it needs only `defineTool` + the
+ * `FileSystem` interface — both core-owned — so the runtime can auto-register it with a
+ * static import and no core->fs dependency (RFC-02 §5.2). `@kuralle-agents/fs` re-exports it.
+ */
+export function createFsTool(opts) {
+    const { fs, readOnly = DEFAULT_READ_ONLY, timeoutMs } = opts;
+    return defineTool({
+        name: 'workspace',
+        description: 'Explore and edit the agent workspace. Ops: ls, cat, grep, find, read, write, edit.',
+        timeoutMs,
+        input: workspaceInput,
+        execute: async (args) => {
+            switch (args.op) {
+                case 'ls': {
+                    const path = normalizeFsPath(args.path);
+                    const entries = await fs.readdirWithFileTypes(path);
+                    return {
+                        op: args.op,
+                        ok: true,
+                        path,
+                        entries,
+                    };
+                }
+                case 'cat':
+                case 'read': {
+                    const path = requireField(args, 'path', args.op);
+                    const content = await fs.readFile(path);
+                    return { op: args.op, ok: true, path, content };
+                }
+                case 'find': {
+                    const root = normalizeFsPath(args.root);
+                    const glob = requireField(args, 'glob', args.op);
+                    const paths = await fs.glob(glob);
+                    const rooted = paths.filter((p) => {
+                        const normalizedRoot = root === '/' ? '/' : root.replace(/\/$/, '');
+                        return p === normalizedRoot || p.startsWith(`${normalizedRoot}/`);
+                    });
+                    return {
+                        op: args.op,
+                        ok: true,
+                        root,
+                        glob,
+                        paths: rooted,
+                    };
+                }
+                case 'grep': {
+                    const pattern = requireField(args, 'pattern', args.op);
+                    const path = normalizeFsPath(args.path);
+                    const hits = await grepFiles(fs, pattern, path, args.flags);
+                    return {
+                        op: args.op,
+                        ok: true,
+                        pattern,
+                        path,
+                        hits,
+                    };
+                }
+                case 'write': {
+                    const path = requireField(args, 'path', args.op);
+                    const content = requireField(args, 'content', args.op);
+                    assertWritable(readOnly, path);
+                    await fs.writeFile(path, content);
+                    return { op: args.op, ok: true, path };
+                }
+                case 'edit': {
+                    const path = requireField(args, 'path', args.op);
+                    const find = requireField(args, 'find', args.op);
+                    const replace = requireField(args, 'replace', args.op);
+                    assertWritable(readOnly, path);
+                    const current = await fs.readFile(path);
+                    if (!current.includes(find)) {
+                        throw new Error(`ENOENT: find string not found in file, edit '${path}'`);
+                    }
+                    const next = current.replace(find, replace);
+                    await fs.writeFile(path, next);
+                    return { op: args.op, ok: true, path };
+                }
+                default: {
+                    throw new Error(`EINVAL: unknown workspace op '${String(args.op)}'`);
+                }
+            }
+        },
+    });
+}