@kuralle-agents/fs 0.10.0 → 0.12.0

package/README.md

@@ -78,19 +78,125 @@ Writable workspaces are not auto-exposed in `globalTools` (ADR 0006); register t
 
 Mark a mount read-only with a `readOnly: true` property on the backend instance (e.g. `KnowledgeFs`). `CompositeFileSystem.readOnly` is `true` only when every mount is read-only.
 
+The `workspace` tool caps its output (read ≤2000 lines / 50KB with `offset`/`limit`, grep ≤200 hits, lines ≤500 chars) and marks truncation with `truncated: true`. `edit` throws on an ambiguous match — pass `replaceAll: true` for multi-match replaces.
+
+## Skills (SKILL.md folders on the filesystem)
+
+Skills live on any `FileSystem` as `SKILL.md` folders following the [agentskills.io](https://agentskills.io) spec. `fsSkillStore` discovers them and implements the core `SkillStoreLike`, so it drops straight into `AgentConfig.skills` — progressive disclosure (metadata in the prompt, body + `references/` loaded on demand) is handled by the runtime.
+
+```ts
+import { InMemoryFs, fsSkillStore, defineSkill } from '@kuralle-agents/fs';
+
+const fs = new InMemoryFs({
+  '/skills/refunds/SKILL.md': '---\nname: refunds\ndescription: Handle refunds.\n---\n\n# Refunds\n...',
+  '/skills/refunds/references/policy.md': '# Policy\n30-day window.',
+});
+
+const agent = defineAgent({
+  id: 'support',
+  model,
+  instructions: 'Load a skill when it fits the task.',
+  workspace: fs,
+  skills: fsSkillStore(fs), // gives the agent load_skill + read_skill_resource
+});
+```
+
+`defineSkill({ name, description, instructions, resources })` builds an inline skill without a filesystem.
+
+## Persistent workspaces (`SqlFileSystem`, platform-chosen)
+
+`InMemoryFs` is ephemeral. For a workspace that survives restarts — so agent files, skills, and the durable tool journal agree across process boundaries — use `SqlFileSystem`, a drop-in `FileSystem` over any SQL handle (+ optional blob store for large files). Pick the backend your platform gives you:
+
+```ts
+// Cloudflare (Durable Object SQLite or D1) — Workers-clean, no adapter
+import { sqlFileSystem, r2BlobStore } from '@kuralle-agents/fs';
+const fs = sqlFileSystem(this.ctx.storage.sql, { blobs: r2BlobStore(env.BUCKET) });
+// or:  sqlFileSystem(env.DB)   // D1
+
+// Node (built-in node:sqlite, Node >= 22.5)
+import { nodeSqlFileSystem } from '@kuralle-agents/fs/node';
+const fs = nodeSqlFileSystem('/data/agent.db');
+
+// Bun / anything — wrap the SQLite handle in a 3-line SqlBackend
+import { sqlFileSystem, type SqlBackend } from '@kuralle-agents/fs';
+import { Database } from 'bun:sqlite';
+const db = new Database('/data/agent.db');
+const backend: SqlBackend = { query: (s, ...p) => db.query(s).all(...p) as never, run: (s, ...p) => { db.query(s).run(...p); } };
+const fs = sqlFileSystem(backend);
+
+// Serverless / edge (Vercel) — hosted SQLite (Turso / libSQL) over a
+// zero-dependency fetch-only backend: no @libsql/client, no native binary, no
+// bundler banner. Optional — nothing here requires Turso; on-disk SQLite above
+// is equally first-class.
+import { sqlFileSystem, libsqlHttpBackend } from '@kuralle-agents/fs';
+const fs2 = sqlFileSystem(libsqlHttpBackend({ url: env.TURSO_DATABASE_URL, authToken: env.TURSO_AUTH_TOKEN }));
+
+// then, exactly as with InMemoryFs:
+const agent = defineAgent({ id: 'a', model, workspace: fs, skills: fsSkillStore(fs) });
+```
+
+`SqlFileSystem` is a proven drop-in for `InMemoryFs` (same behavior + error codes, verified by a shared conformance suite) and is verified on real Cloudflare workerd over a Durable Object's `ctx.storage.sql`. Large files (≥ `inlineThreshold`, default 1.5MB) spill to the `BlobStore` (R2); everything else stores inline. See `examples/persistent-workspace.ts` and ADR-0013.
+
+**No storage is enforced or bundled by default.** A workspace is opt-in (agents have none unless you set `workspace`), and the backend is entirely yours: in-memory, on-disk SQLite, DO SQLite, D1, hosted libSQL, or any object satisfying the two-method `SqlBackend`. Turso is one option, not a requirement — `@kuralle-agents/fs` has **no** `@libsql/client` dependency (the fetch-only `libsqlHttpBackend` needs only `fetch`).
+
+## Open Knowledge Format (OKF)
+
+An [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundle is *just markdown + YAML frontmatter + files* — knowledge concepts (tables, metrics, runbooks) that cross-link into a graph. Because it's a directory of files, a kuralle `workspace` **is** an OKF consumption agent with no adapter: the agent navigates `index.md` → concept → bundle-relative links via `ls`/`read`/`grep`.
+
+```ts
+import { okfBundleToFs, listOkfConcepts, createFsTool, defineAgent } from '@kuralle-agents/fs'; // createFsTool/defineAgent from core
+
+const fs = okfBundleToFs({
+  '/index.md': '# Sales\n* [Orders](/tables/orders.md)',
+  '/tables/orders.md': '---\ntype: BigQuery Table\ntitle: Orders\n---\n# Schema\n...',
+});
+const concepts = await listOkfConcepts(fs); // [{ id, type, title, links, ... }]
+const agent = defineAgent({ id: 'analyst', model, workspace: fs, tools: { workspace: createFsTool({ fs }) } });
+```
+
+`parseOkfConcept`, `listOkfConcepts`, and `okfBundleToFs` implement the permissive OKF consumption model (spec §9): only `type` is required, unknown fields/broken links are tolerated. See `examples/okf-knowledge-agent.ts` (live navigation) and `examples/okf-benchmark.ts` (progressive-disclosure vs whole-dump).
+
+## Shell (`@kuralle-agents/fs/shell`, `/node`, `/cloudflare`)
+
+A workspace can carry a `Shell` alongside its `FileSystem`; the runtime then exposes a durable `bash` tool. Three backends mirror flue's model:
+
+```ts
+import { virtualShell } from '@kuralle-agents/fs/shell'; // just-bash over an in-memory fs — Node / CF container
+import { nodeShell } from '@kuralle-agents/fs/node';     // real host shell (env-allowlisted, tree-kill)
+import { cloudflareShell } from '@kuralle-agents/fs/cloudflare'; // wraps a @cloudflare/sandbox DO stub
+
+const { fs, shell } = virtualShell({ initialFiles: { '/data.txt': 'hi' } });
+const agent = defineAgent({ id: 'coder', model, workspace: { fs, shell, readOnly: false } });
+```
+
+The `bash` tool is registered into the **executor** surface only — a shell is never auto-exposed to the model; opt in per node or via `agent.tools`. Portability note: `virtualShell` pulls `just-bash` and is **not** on the root export (its `turndown` transitive is not workerd-clean); the root `@kuralle-agents/fs` stays Workers-clean, and the Cloudflare-edge shell is `cloudflareShell` (a Sandbox Durable Object), not `virtualShell`.
+
+fs and shell tools are **non-replayed** (`replay: false`): they always execute fresh rather than return a stale durable-journal result — at-least-once, always-fresh (see ADR-0012).
+
 ## API
 
 - `FileSystem` — async POSIX-ish interface (types live in `@kuralle-agents/core`, re-exported here)
 - `InMemoryFs` — in-memory tree, seed with `new InMemoryFs({ '/path': 'content' })`
 - `CompositeFileSystem` — path-routed mount table over multiple `FileSystem` backends
-- `createFsTool` — durable workspace tool factory
+- `createFsTool` — durable, capped, read-only-by-default workspace tool factory
+- `SqlFileSystem`, `sqlFileSystem` (DO SQLite / D1 auto-detect), `r2BlobStore`, `nodeSqlFileSystem` (`/node`) — persistent, platform-chosen backends
+- `fsSkillStore`, `defineSkill`, `parseSkillFrontmatter` — SKILL.md skills on a filesystem
+- `okfBundleToFs`, `listOkfConcepts`, `parseOkfConcept` — Open Knowledge Format (OKF v0.1) bundles
+- `virtualShell` / `bashShell` (`/shell`), `nodeShell` (`/node`), `cloudflareShell` (`/cloudflare`) — `Shell` backends
 - `path-utils`, `encoding` — portable helpers (no Node built-ins)
 
 ## Examples
 
 ```bash
 bun packages/kuralle-fs/examples/kb-agent.ts
+bun packages/kuralle-fs/examples/skills-on-fs.ts   # deterministic, no key
 KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/composite-workspace.ts
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/workspace-skills-shell.ts  # live: model uses bash + a fs skill
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/okf-knowledge-agent.ts     # live: agent navigates an OKF bundle
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/okf-benchmark.ts           # benchmark: progressive vs whole-dump
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/skill-latency-spike.ts     # benchmark: with vs without skills
+bun packages/kuralle-fs/examples/persistent-workspace.ts   # SqlFileSystem: file+skill survive a restart
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/persistent-workspace-live.ts  # live: model writes, fresh runtime reads back
 ```
 
 ## License

package/dist/bash-shell.d.ts

@@ -0,0 +1,15 @@
+import type { Shell } from '@kuralle-agents/core';
+export interface BashLike {
+    exec(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    getCwd(): string;
+    fs: unknown;
+}
+export declare function bashShell(bash: BashLike): Shell;

package/dist/bash-shell.js

@@ -0,0 +1,46 @@
+function abortError() {
+    return new DOMException('Aborted', 'AbortError');
+}
+function composeSignals(timeoutMs, signal) {
+    if (timeoutMs === undefined && signal === undefined)
+        return undefined;
+    if (timeoutMs === undefined)
+        return signal;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (signal === undefined)
+        return timeoutSignal;
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([signal, timeoutSignal]);
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal.addEventListener('abort', onAbort, { once: true });
+    timeoutSignal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted || timeoutSignal.aborted)
+        onAbort();
+    return controller.signal;
+}
+export function bashShell(bash) {
+    return {
+        cwd: bash.getCwd(),
+        async exec(command, options) {
+            if (options?.signal?.aborted)
+                throw abortError();
+            const mergedSignal = composeSignals(options?.timeoutMs, options?.signal);
+            if (mergedSignal?.aborted)
+                throw abortError();
+            const result = await bash.exec(command, {
+                cwd: options?.cwd,
+                env: options?.env,
+                signal: mergedSignal,
+            });
+            if (options?.signal?.aborted)
+                throw abortError();
+            return {
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode,
+            };
+        },
+    };
+}

package/dist/cloudflare/cf-shell.d.ts

@@ -0,0 +1,16 @@
+import type { Shell } from '@kuralle-agents/core';
+export interface CloudflareSandboxStub {
+    exec(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeout?: number;
+    }): Promise<{
+        success: boolean;
+        stdout: string;
+        stderr: string;
+        exitCode?: number;
+    }>;
+}
+export declare function cloudflareShell(stub: CloudflareSandboxStub, opts?: {
+    cwd?: string;
+}): Shell;

package/dist/cloudflare/cf-shell.js

@@ -0,0 +1,28 @@
+function abortError() {
+    return new DOMException('Aborted', 'AbortError');
+}
+export function cloudflareShell(stub, opts) {
+    const defaultCwd = opts?.cwd;
+    return {
+        cwd: defaultCwd,
+        async exec(command, options) {
+            if (options?.signal?.aborted)
+                throw abortError();
+            const timeout = options?.timeoutMs !== undefined
+                ? Math.ceil(options.timeoutMs / 1000)
+                : undefined;
+            const result = await stub.exec(command, {
+                cwd: options?.cwd ?? defaultCwd,
+                env: options?.env,
+                timeout,
+            });
+            if (options?.signal?.aborted)
+                throw abortError();
+            return {
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode ?? (result.success ? 0 : 1),
+            };
+        },
+    };
+}

package/dist/define-skill.d.ts

@@ -0,0 +1,7 @@
+import type { SkillLike } from '@kuralle-agents/core';
+export declare function defineSkill(opts: {
+    name: string;
+    description: string;
+    instructions: string;
+    resources?: Record<string, string>;
+}): SkillLike;

package/dist/define-skill.js

@@ -0,0 +1,8 @@
+export function defineSkill(opts) {
+    return {
+        name: opts.name,
+        description: opts.description,
+        body: opts.instructions,
+        resources: opts.resources,
+    };
+}

package/dist/fs-skill-store.d.ts

@@ -0,0 +1,4 @@
+import type { FileSystem, SkillStoreLike } from '@kuralle-agents/core';
+export declare function fsSkillStore(fs: FileSystem, opts?: {
+    root?: string;
+}): SkillStoreLike;

package/dist/fs-skill-store.js

@@ -0,0 +1,101 @@
+import { parseSkillFrontmatter } from './skill-frontmatter.js';
+const DEFAULT_ROOT = '/skills';
+export function fsSkillStore(fs, opts) {
+    const root = opts?.root ?? DEFAULT_ROOT;
+    return {
+        async list() {
+            const metas = [];
+            let entries;
+            try {
+                entries = await fs.readdir(root);
+            }
+            catch {
+                return metas;
+            }
+            for (const entry of entries) {
+                const entryPath = fs.resolvePath(root, entry);
+                let stat;
+                try {
+                    stat = await fs.stat(entryPath);
+                }
+                catch {
+                    continue;
+                }
+                if (stat.type !== 'directory')
+                    continue;
+                const skillPath = fs.resolvePath(root, `${entry}/SKILL.md`);
+                if (!(await fs.exists(skillPath)))
+                    continue;
+                try {
+                    const content = await fs.readFile(skillPath);
+                    const parsed = parseSkillFrontmatter(content, { path: skillPath });
+                    metas.push({ name: parsed.name, description: parsed.description });
+                }
+                catch (err) {
+                    console.warn(`[skills] Skipping ${skillPath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            return metas.sort((a, b) => a.name.localeCompare(b.name));
+        },
+        async loadBody(name) {
+            const folder = await findSkillFolder(fs, root, name);
+            if (!folder) {
+                throw new Error(`[skills] Skill "${name}" not found.`);
+            }
+            const skillPath = fs.resolvePath(root, `${folder}/SKILL.md`);
+            const content = await fs.readFile(skillPath);
+            const parsed = parseSkillFrontmatter(content, { path: skillPath });
+            return parsed.body;
+        },
+        async loadResource(name, path) {
+            const folder = await findSkillFolder(fs, root, name);
+            if (!folder) {
+                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 resourcePath = fs.resolvePath(root, `${folder}/${normalized}`);
+            if (!(await fs.exists(resourcePath))) {
+                const err = new Error(`ENOENT: [skills] Resource "${normalized}" not found for skill "${name}".`);
+                throw err;
+            }
+            return fs.readFile(resourcePath);
+        },
+    };
+}
+async function findSkillFolder(fs, root, name) {
+    let entries;
+    try {
+        entries = await fs.readdir(root);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const entryPath = fs.resolvePath(root, entry);
+        let stat;
+        try {
+            stat = await fs.stat(entryPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.type !== 'directory')
+            continue;
+        const skillPath = fs.resolvePath(root, `${entry}/SKILL.md`);
+        if (!(await fs.exists(skillPath)))
+            continue;
+        try {
+            const content = await fs.readFile(skillPath);
+            const parsed = parseSkillFrontmatter(content, { path: skillPath });
+            if (parsed.name === name)
+                return entry;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -4,3 +4,12 @@ export { CompositeFileSystem, type CompositeFileSystemConfig } from './composite
 export { normalizePath, validatePath, dirname, resolvePath, joinPath, resolveSymlinkTarget, createGlobMatcher, sortPaths, MAX_SYMLINK_DEPTH, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, SYMLINK_MODE, } from './path-utils.js';
 export { toBuffer, fromBuffer, getEncoding } from './encoding.js';
 export { createFsTool } from './tool.js';
+export { parseSkillFrontmatter, type ParsedSkill } from './skill-frontmatter.js';
+export { fsSkillStore } from './fs-skill-store.js';
+export { defineSkill } from './define-skill.js';
+export { parseOkfConcept, listOkfConcepts, okfBundleToFs, type OkfConcept, } from './okf.js';
+export { SqlFileSystem, type SqlFileSystemOptions } from './sql/sql-fs.js';
+export type { SqlBackend, BlobStore, SqlParam } from './sql/types.js';
+export { sqlFileSystem, toSqlBackend, type SqlSource, type SqlStorageLike, type D1DatabaseLike, type SqlFileSystemFactoryOptions, } from './sql/factory.js';
+export { r2BlobStore, type R2Bucketish } from './sql/r2-blob.js';
+export { libsqlHttpBackend, type LibsqlHttpOptions } from './sql/libsql-http.js';

package/dist/index.js

@@ -3,3 +3,15 @@ export { CompositeFileSystem } from './composite-fs.js';
 export { normalizePath, validatePath, dirname, resolvePath, joinPath, resolveSymlinkTarget, createGlobMatcher, sortPaths, MAX_SYMLINK_DEPTH, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, SYMLINK_MODE, } from './path-utils.js';
 export { toBuffer, fromBuffer, getEncoding } from './encoding.js';
 export { createFsTool } from './tool.js';
+export { parseSkillFrontmatter } from './skill-frontmatter.js';
+export { fsSkillStore } from './fs-skill-store.js';
+export { defineSkill } from './define-skill.js';
+export { parseOkfConcept, listOkfConcepts, okfBundleToFs, } from './okf.js';
+export { SqlFileSystem } from './sql/sql-fs.js';
+export { sqlFileSystem, toSqlBackend, } from './sql/factory.js';
+export { r2BlobStore } from './sql/r2-blob.js';
+export { libsqlHttpBackend } from './sql/libsql-http.js';
+// NOTE: shell backends (bashShell/virtualShell) live at the `@kuralle-agents/fs/shell`
+// subpath, NOT the root — they pull `just-bash`, whose browser bundle depends on
+// `turndown` and is not workerd-clean. Keeping them off the root export preserves the
+// root package's Cloudflare Workers portability.

package/dist/node/index.d.ts

@@ -0,0 +1,2 @@
+export { nodeShell } from './node-shell.js';
+export { nodeSqlFileSystem } from './node-sql-fs.js';

package/dist/node/index.js

@@ -0,0 +1,3 @@
+// `@kuralle-agents/fs/node` — Node-platform backends (node:child_process, node:sqlite).
+export { nodeShell } from './node-shell.js';
+export { nodeSqlFileSystem } from './node-sql-fs.js';

package/dist/node/node-shell.d.ts

@@ -0,0 +1,5 @@
+import type { Shell } from '@kuralle-agents/core';
+export declare function nodeShell(opts?: {
+    cwd?: string;
+    env?: Record<string, string>;
+}): Shell;

package/dist/node/node-shell.js

@@ -0,0 +1,180 @@
+import { spawn, spawnSync } from 'node:child_process';
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+const KILL_GRACE_MS = 2000;
+const DEFAULT_LOCAL_ENV_ALLOWLIST = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'HOSTNAME',
+    'SHELL',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'TERM',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+];
+let resolvedShell;
+function resolveShell() {
+    if (resolvedShell === undefined) {
+        if (process.platform === 'win32') {
+            resolvedShell = true;
+        }
+        else {
+            const probe = spawnSync('bash', ['-c', 'command -v bash'], {
+                encoding: 'utf8',
+            });
+            const found = probe.status === 0 ? probe.stdout.trim() : '';
+            resolvedShell = found.startsWith('/') ? found : true;
+        }
+    }
+    return resolvedShell;
+}
+function abortError() {
+    return new DOMException('Aborted', 'AbortError');
+}
+function composeSignals(timeoutMs, signal) {
+    if (timeoutMs === undefined && signal === undefined)
+        return undefined;
+    if (timeoutMs === undefined)
+        return signal;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (signal === undefined)
+        return timeoutSignal;
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([signal, timeoutSignal]);
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal.addEventListener('abort', onAbort, { once: true });
+    timeoutSignal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted || timeoutSignal.aborted)
+        onAbort();
+    return controller.signal;
+}
+function resolveBaseEnv(userEnv) {
+    const base = {};
+    for (const key of DEFAULT_LOCAL_ENV_ALLOWLIST) {
+        const value = process.env[key];
+        if (value !== undefined)
+            base[key] = value;
+    }
+    if (!userEnv)
+        return base;
+    for (const [key, value] of Object.entries(userEnv)) {
+        if (value === undefined)
+            delete base[key];
+        else
+            base[key] = value;
+    }
+    return base;
+}
+function execShell(command, opts) {
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            cwd: opts.cwd,
+            env: opts.env,
+            shell: resolveShell(),
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let truncated = false;
+        let settled = false;
+        let killTimer;
+        const killTree = (sig) => {
+            if (child.pid === undefined)
+                return;
+            try {
+                process.kill(-child.pid, sig);
+            }
+            catch {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    // Already gone.
+                }
+            }
+        };
+        const onAbort = () => {
+            killTree('SIGTERM');
+            killTimer = setTimeout(() => killTree('SIGKILL'), KILL_GRACE_MS);
+            killTimer.unref();
+        };
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            opts.signal?.removeEventListener('abort', onAbort);
+            resolve(result);
+        };
+        if (opts.signal?.aborted) {
+            onAbort();
+        }
+        else {
+            opts.signal?.addEventListener('abort', onAbort, { once: true });
+        }
+        const onData = (chunk, target) => {
+            if (target === 'stdout')
+                stdout += chunk;
+            else
+                stderr += chunk;
+            if (!truncated && stdout.length + stderr.length > MAX_OUTPUT_BYTES) {
+                truncated = true;
+                killTree('SIGTERM');
+            }
+        };
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => onData(chunk, 'stdout'));
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => onData(chunk, 'stderr'));
+        child.once('error', (err) => {
+            killTree('SIGTERM');
+            settle({
+                stdout,
+                stderr: stderr || String(err.message ?? err),
+                exitCode: 1,
+            });
+        });
+        child.once('close', (code) => {
+            if (truncated) {
+                settle({
+                    stdout,
+                    stderr: `${stderr}\n[kuralle] local exec output exceeded ${MAX_OUTPUT_BYTES} bytes; process tree killed`,
+                    exitCode: 1,
+                });
+                return;
+            }
+            settle({ stdout, stderr, exitCode: code ?? 1 });
+        });
+    });
+}
+export function nodeShell(opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const baseEnv = resolveBaseEnv(opts?.env);
+    return {
+        cwd,
+        async exec(command, options) {
+            if (options?.signal?.aborted)
+                throw abortError();
+            const mergedSignal = composeSignals(options?.timeoutMs, options?.signal);
+            if (mergedSignal?.aborted)
+                throw abortError();
+            const result = await execShell(command, {
+                cwd: options?.cwd ?? cwd,
+                env: options?.env ? { ...baseEnv, ...options.env } : baseEnv,
+                signal: mergedSignal,
+            });
+            if (options?.signal?.aborted)
+                throw abortError();
+            return result;
+        },
+    };
+}

package/dist/node/node-sql-fs.d.ts

@@ -0,0 +1,7 @@
+import { SqlFileSystem } from '../sql/sql-fs.js';
+import type { SqlFileSystemFactoryOptions } from '../sql/factory.js';
+/**
+ * A SqlFileSystem persisted to a SQLite file on disk (or `:memory:`). Uses the
+ * built-in `node:sqlite` — no external dependency.
+ */
+export declare function nodeSqlFileSystem(dbPath: string, options?: SqlFileSystemFactoryOptions): SqlFileSystem;

package/dist/node/node-sql-fs.js

@@ -0,0 +1,26 @@
+// `nodeSqlFileSystem` — a persistent SqlFileSystem on the Node platform, backed
+// by the built-in `node:sqlite` (Node >= 22.5). Node-only; lives behind the
+// `@kuralle-agents/fs/node` subpath.
+import { DatabaseSync } from 'node:sqlite';
+import { SqlFileSystem } from '../sql/sql-fs.js';
+// node:sqlite's SQLInputValue excludes `boolean`; coerce to 0/1 (SqlFileSystem
+// never binds booleans, but the SqlBackend contract permits them).
+function coerce(params) {
+    return params.map((p) => (typeof p === 'boolean' ? (p ? 1 : 0) : p));
+}
+function nodeSqlBackend(db) {
+    return {
+        query: (sql, ...params) => db.prepare(sql).all(...coerce(params)),
+        run: (sql, ...params) => {
+            db.prepare(sql).run(...coerce(params));
+        },
+    };
+}
+/**
+ * A SqlFileSystem persisted to a SQLite file on disk (or `:memory:`). Uses the
+ * built-in `node:sqlite` — no external dependency.
+ */
+export function nodeSqlFileSystem(dbPath, options) {
+    const db = new DatabaseSync(dbPath);
+    return new SqlFileSystem({ backend: nodeSqlBackend(db), ...options });
+}

package/dist/okf.d.ts

@@ -0,0 +1,25 @@
+import type { FileSystem } from '@kuralle-agents/core';
+export interface OkfConcept {
+    /** Concept ID = file path minus `.md` (spec §2). */
+    id: string;
+    /** REQUIRED per spec §4.1 / §9. */
+    type: string;
+    title?: string;
+    description?: string;
+    resource?: string;
+    tags?: string[];
+    timestamp?: string;
+    body: string;
+    /** Bundle-relative links to other concepts (the graph edges, §5). */
+    links: string[];
+}
+/** Parse one OKF concept document. Throws only when `type` is missing (the sole hard rule, §9). */
+export declare function parseOkfConcept(content: string, id: string): OkfConcept;
+/**
+ * List every concept in a bundle (skips reserved index.md/log.md). Permissive
+ * per §9: a concept whose frontmatter is unparseable or lacks `type` is skipped,
+ * not fatal — a partially-generated bundle stays consumable.
+ */
+export declare function listOkfConcepts(fs: FileSystem, root?: string): Promise<OkfConcept[]>;
+/** Build an OKF bundle into an InMemoryFs from a `{ path: content }` map. */
+export declare function okfBundleToFs(files: Record<string, string>, mountRoot?: string): FileSystem;