@theokit/sdk 4.53.0 → 4.54.0

package/dist/filesystem/index.cjs

@@ -1,9 +1,10 @@
 'use strict';
 
-var chunkYTO5BRBD_cjs = require('../chunk-YTO5BRBD.cjs');
+var chunkR3UPQFKK_cjs = require('../chunk-R3UPQFKK.cjs');
 require('../chunk-VKJ7V7EB.cjs');
-require('../chunk-2YGIBOUH.cjs');
-require('../chunk-SXSPMRSV.cjs');
+require('../chunk-K3FW2XZD.cjs');
+require('../chunk-JTB5Q42C.cjs');
+require('../chunk-NUKRL3I6.cjs');
 var promises = require('fs/promises');
 var path = require('path');
 
@@ -167,17 +168,17 @@ var LocalFilesystem = class extends FilesystemBackend {
   resolve(path) {
     let abs;
     try {
-      abs = chunkYTO5BRBD_cjs.safePathJoin(this._basePath, path);
+      abs = chunkR3UPQFKK_cjs.safePathJoin(this._basePath, path);
     } catch (err) {
-      if (err instanceof chunkYTO5BRBD_cjs.PathTraversalError) {
+      if (err instanceof chunkR3UPQFKK_cjs.PathTraversalError) {
         throw new FilesystemSecurityError(`Path escapes basePath: ${path}`);
       }
       throw err;
     }
     try {
-      chunkYTO5BRBD_cjs.assertNoSymlinkEscape(abs, this._basePath);
+      chunkR3UPQFKK_cjs.assertNoSymlinkEscape(abs, this._basePath);
     } catch (err) {
-      if (err instanceof chunkYTO5BRBD_cjs.PathTraversalError) {
+      if (err instanceof chunkR3UPQFKK_cjs.PathTraversalError) {
         throw new FilesystemSecurityError(`Path escapes basePath via symlink: ${path}`);
       }
       throw err;

package/dist/filesystem/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/filesystem/types.ts","../../src/filesystem/local-filesystem.ts"],"names":["fsReadFile","path","mkdir","dirname","fsWriteFile","readdir","fsStat","safePathJoin","PathTraversalError","assertNoSymlinkEscape"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Filesystem backend protocol — a pluggable file *storage* provider for agent\n * tools, the storage-side twin of {@link SandboxBackend} (execution-side).\n *\n * SE31 (a peer framework Workspaces comparison). Mirrors `SandboxBackend`'s shape: a small\n * set of abstract methods (`readFile` / `writeFile` / `stat` / `list`) with\n * `exists()` derived on the base class, a boundary `basePath`, a `readOnly`\n * flag, and typed errors. Unlike `SandboxBackend` (whose file ops shell out via\n * `execute`, requiring command execution and giving NO structured `stat`), a\n * `FilesystemBackend` serves a *filesystem-only* workspace with no sandbox and\n * exposes a real `stat().mtimeMs` — the primitive SE32's read-before-write\n * safety compares against. See ADR 0011.\n *\n * New backends (S3, GCS, in-memory) implement the four abstract methods; higher\n * level helpers derive on the base. This is the backend *seam* — it does NOT\n * ship agent-facing tools nor a bundled workspace (bring-your-own-tools stands).\n *\n * @public\n */\n\n/** Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32). */\nexport interface FileStat {\n  readonly size: number;\n  readonly mtimeMs: number;\n  readonly isFile: boolean;\n  readonly isDirectory: boolean;\n}\n\n/** Options a write may carry. SE32 adds `expectedMtime` (stale-write guard). */\nexport interface WriteFileOptions {\n  /**\n   * SE32 — when set, the write fails with {@link StaleFileError} if the file's\n   * current `mtimeMs` differs (someone changed it since it was last read).\n   */\n  readonly expectedMtime?: number;\n}\n\nexport interface FilesystemConfig {\n  /** Boundary root. Every path is resolved within it; escapes are rejected. */\n  readonly basePath?: string;\n  /** When true, every write throws {@link FilesystemReadOnlyError}. */\n  readonly readOnly?: boolean;\n}\n\n/** A path escaped the backend's `basePath` (traversal or symlink). */\nexport class FilesystemSecurityError extends Error {\n  readonly code = \"filesystem_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemSecurityError\";\n  }\n}\n\n/** A write was attempted on a read-only backend. */\nexport class FilesystemReadOnlyError extends Error {\n  readonly code = \"filesystem_readonly\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemReadOnlyError\";\n  }\n}\n\n/** A read/stat targeted a path that does not exist. */\nexport class FileNotFoundError extends Error {\n  readonly code = \"filesystem_not_found\" as const;\n  constructor(public readonly path: string) {\n    super(`File not found: ${path}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n\n/**\n * A filesystem I/O operation failed for a reason other than not-found /\n * read-only / stale / security (e.g. `ENOTDIR` — a path component is a file, or\n * `EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,\n * untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).\n */\nexport class FilesystemError extends Error {\n  readonly code = \"filesystem_io\" as const;\n  constructor(\n    public readonly path: string,\n    cause: unknown,\n  ) {\n    super(\n      `Filesystem operation failed on \"${path}\": ${(cause as { message?: string })?.message ?? cause}`,\n      {\n        cause,\n      },\n    );\n    this.name = \"FilesystemError\";\n  }\n}\n\n/**\n * SE32 — a write's `expectedMtime` did not match the file's current mtime: the\n * file changed since it was last read, so the write would silently clobber.\n */\nexport class StaleFileError extends Error {\n  readonly code = \"filesystem_stale\" as const;\n  constructor(\n    public readonly path: string,\n    public readonly expectedMtime: number,\n    public readonly actualMtime: number,\n  ) {\n    super(\n      `Stale write to \"${path}\": expected mtime ${expectedMtime}, found ${actualMtime} ` +\n        `(file changed since last read — re-read before writing)`,\n    );\n    this.name = \"StaleFileError\";\n  }\n}\n\n/**\n * Pluggable filesystem backend. Implement the four abstract methods; `exists()`\n * and the `readOnly`/`basePath` accessors derive on the base class.\n *\n * @public\n */\nexport abstract class FilesystemBackend {\n  protected readonly _basePath: string;\n  protected readonly _readOnly: boolean;\n\n  constructor(config: FilesystemConfig = {}) {\n    this._basePath = config.basePath ?? process.cwd();\n    this._readOnly = config.readOnly ?? false;\n  }\n\n  /** Read a boundary-relative file as UTF-8. Throws {@link FileNotFoundError}. */\n  abstract readFile(path: string): Promise<string>;\n\n  /**\n   * Write UTF-8 content to a boundary-relative path (creating parents). Returns\n   * the new {@link FileStat}. Throws {@link FilesystemReadOnlyError} on a\n   * read-only backend and {@link StaleFileError} when `opts.expectedMtime`\n   * mismatches (SE32).\n   */\n  abstract writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat>;\n\n  /** Structured metadata for a path. Throws {@link FileNotFoundError}. */\n  abstract stat(path: string): Promise<FileStat>;\n\n  /** Directory entry names (not recursive). Throws {@link FileNotFoundError}. */\n  abstract list(path: string): Promise<string[]>;\n\n  /** Derived — true iff `stat(path)` resolves (absent ⇒ false). */\n  async exists(path: string): Promise<boolean> {\n    try {\n      await this.stat(path);\n      return true;\n    } catch (err) {\n      if (err instanceof FileNotFoundError) return false;\n      throw err;\n    }\n  }\n\n  /** Throw {@link FilesystemReadOnlyError} when the backend is read-only. */\n  protected assertWritable(): void {\n    if (this._readOnly) {\n      throw new FilesystemReadOnlyError(`Filesystem is read-only (basePath: ${this._basePath})`);\n    }\n  }\n\n  get readOnly(): boolean {\n    return this._readOnly;\n  }\n\n  get basePath(): string {\n    return this._basePath;\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one. A resolver runs at tool-execution\n * time (the request scope), so multi-tenant / multi-role agents get a distinct\n * root or permission set per request without a shared mutable backend.\n *\n * @public\n */\nexport type FilesystemProvider<Ctx = unknown> =\n  | FilesystemBackend\n  | ((ctx: Ctx) => FilesystemBackend | Promise<FilesystemBackend>);\n\n/** Resolve a {@link FilesystemProvider} to a concrete backend for `ctx`. */\nexport async function resolveFilesystem<Ctx>(\n  provider: FilesystemProvider<Ctx>,\n  ctx: Ctx,\n): Promise<FilesystemBackend> {\n  return provider instanceof FilesystemBackend ? provider : provider(ctx);\n}\n","/**\n * LocalFilesystem — a {@link FilesystemBackend} over the local process\n * filesystem (`node:fs/promises`), boundary-enforced against `basePath`.\n *\n * **This is NOT an isolation boundary** (same OS, same user). Its safety\n * affordances are path-boundary enforcement (traversal + symlink escape,\n * reusing the core `internal/security/path-guard` primitives) and the optional\n * `readOnly` flag. For untrusted code, run it inside a container/VM sandbox.\n *\n * The check-then-use gap between `assertNoSymlinkEscape` and the subsequent\n * `fs` call is a known TOCTOU: a local attacker could atomically swap an\n * in-boundary symlink after the check. Closing it needs `O_NOFOLLOW`, which\n * Node's `fs/promises` does not expose — accepted for same-user local contexts.\n *\n * SE31 (a peer framework Workspaces comparison). See ADR 0011.\n *\n * @public\n */\n\nimport {\n  readFile as fsReadFile,\n  stat as fsStat,\n  writeFile as fsWriteFile,\n  mkdir,\n  readdir,\n} from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport {\n  assertNoSymlinkEscape,\n  PathTraversalError,\n  safePathJoin,\n} from \"../internal/security/path-guard.js\";\nimport {\n  FileNotFoundError,\n  type FileStat,\n  FilesystemBackend,\n  type FilesystemConfig,\n  FilesystemError,\n  FilesystemSecurityError,\n  StaleFileError,\n  type WriteFileOptions,\n} from \"./types.js\";\n\nexport class LocalFilesystem extends FilesystemBackend {\n  constructor(config: FilesystemConfig = {}) {\n    super(config);\n  }\n\n  async readFile(path: string): Promise<string> {\n    const abs = this.resolve(path);\n    try {\n      return await fsReadFile(abs, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  async writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat> {\n    // Security boundary FIRST (a traversal path on a read-only backend must\n    // report the security error, not the read-only one — fail-clear).\n    const abs = this.resolve(path);\n    this.assertWritable();\n    // SE32 — stale-write guard: if the caller passed the mtime it last read,\n    // reject when the file changed underneath it (never a silent clobber).\n    if (opts?.expectedMtime !== undefined) {\n      await this.assertNotStale(path, abs, opts.expectedMtime);\n    }\n    try {\n      await mkdir(dirname(abs), { recursive: true });\n      await fsWriteFile(abs, content, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n    return this.statAbs(abs, path);\n  }\n\n  async stat(path: string): Promise<FileStat> {\n    const abs = this.resolve(path);\n    return this.statAbs(abs, path);\n  }\n\n  async list(path: string): Promise<string[]> {\n    const abs = this.resolve(path);\n    try {\n      return await readdir(abs);\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  private async statAbs(abs: string, relPath: string): Promise<FileStat> {\n    try {\n      const s = await fsStat(abs);\n      return {\n        size: s.size,\n        mtimeMs: s.mtimeMs,\n        isFile: s.isFile(),\n        isDirectory: s.isDirectory(),\n      };\n    } catch (err) {\n      throw this.mapError(err, relPath);\n    }\n  }\n\n  /** SE32 — compare the on-disk mtime against the caller's expected value. */\n  private async assertNotStale(relPath: string, abs: string, expectedMtime: number): Promise<void> {\n    let current: number | undefined;\n    try {\n      current = (await fsStat(abs)).mtimeMs;\n    } catch (err) {\n      // A brand-new file (does not exist yet) cannot be stale — allow the write.\n      if ((err as { code?: string }).code === \"ENOENT\") return;\n      throw this.mapError(err, relPath);\n    }\n    if (current !== expectedMtime) {\n      throw new StaleFileError(relPath, expectedMtime, current);\n    }\n  }\n\n  /**\n   * Resolve a boundary-relative path to an absolute one, rejecting lexical\n   * traversal (`..`, absolute, NUL) and symlink escape — both reusing the core\n   * path-guard primitives, remapped to {@link FilesystemSecurityError}.\n   */\n  private resolve(path: string): string {\n    let abs: string;\n    try {\n      abs = safePathJoin(this._basePath, path);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath: ${path}`);\n      }\n      throw err;\n    }\n    try {\n      assertNoSymlinkEscape(abs, this._basePath);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath via symlink: ${path}`);\n      }\n      throw err;\n    }\n    return abs;\n  }\n\n  private mapError(err: unknown, path: string): Error {\n    if (\n      err instanceof FilesystemSecurityError ||\n      err instanceof FilesystemError ||\n      err instanceof FileNotFoundError ||\n      err instanceof StaleFileError\n    ) {\n      return err;\n    }\n    if ((err as { code?: string }).code === \"ENOENT\") return new FileNotFoundError(path);\n    // ENOTDIR (a path component is a file), EACCES, ENOSPC, … — never leak a\n    // raw untyped Node SystemError (Rule 8); wrap with the original as cause.\n    return new FilesystemError(path, err);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/filesystem/types.ts","../../src/filesystem/local-filesystem.ts"],"names":["fsReadFile","path","mkdir","dirname","fsWriteFile","readdir","fsStat","safePathJoin","PathTraversalError","assertNoSymlinkEscape"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Filesystem backend protocol — a pluggable file *storage* provider for agent\n * tools, the storage-side twin of {@link SandboxBackend} (execution-side).\n *\n * SE31 (a peer framework Workspaces comparison). Mirrors `SandboxBackend`'s shape: a small\n * set of abstract methods (`readFile` / `writeFile` / `stat` / `list`) with\n * `exists()` derived on the base class, a boundary `basePath`, a `readOnly`\n * flag, and typed errors. Unlike `SandboxBackend` (whose file ops shell out via\n * `execute`, requiring command execution and giving NO structured `stat`), a\n * `FilesystemBackend` serves a *filesystem-only* workspace with no sandbox and\n * exposes a real `stat().mtimeMs` — the primitive SE32's read-before-write\n * safety compares against. See ADR 0011.\n *\n * New backends (S3, GCS, in-memory) implement the four abstract methods; higher\n * level helpers derive on the base. This is the backend *seam* — it does NOT\n * ship agent-facing tools nor a bundled workspace (bring-your-own-tools stands).\n *\n * @public\n */\n\n/** Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32). */\nexport interface FileStat {\n  readonly size: number;\n  readonly mtimeMs: number;\n  readonly isFile: boolean;\n  readonly isDirectory: boolean;\n}\n\n/** Options a write may carry. SE32 adds `expectedMtime` (stale-write guard). */\nexport interface WriteFileOptions {\n  /**\n   * SE32 — when set, the write fails with {@link StaleFileError} if the file's\n   * current `mtimeMs` differs (someone changed it since it was last read).\n   */\n  readonly expectedMtime?: number;\n}\n\n/**\n * Construction options shared by every {@link FilesystemBackend}.\n *\n * `basePath` is resolved ONCE, at construction, and defaults to `process.cwd()`. Omitting it does\n * not mean \"no boundary\" — it means the boundary is wherever the process happened to be standing,\n * which is rarely what the caller intended and never what a reviewer can verify. Pass it explicitly.\n *\n * The boundary rejects lexical traversal AND symlink escape, raising\n * {@link FilesystemSecurityError}. It is a boundary, not a sandbox: it constrains paths this\n * backend resolves, and constrains nothing else the process can do. For untrusted code, run it in a\n * container or VM.\n */\nexport interface FilesystemConfig {\n  /** Boundary root. Every path is resolved within it; escapes are rejected. */\n  readonly basePath?: string;\n  /** When true, every write throws {@link FilesystemReadOnlyError}. */\n  readonly readOnly?: boolean;\n}\n\n/** A path escaped the backend's `basePath` (traversal or symlink). */\nexport class FilesystemSecurityError extends Error {\n  readonly code = \"filesystem_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemSecurityError\";\n  }\n}\n\n/** A write was attempted on a read-only backend. */\nexport class FilesystemReadOnlyError extends Error {\n  readonly code = \"filesystem_readonly\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemReadOnlyError\";\n  }\n}\n\n/** A read/stat targeted a path that does not exist. */\nexport class FileNotFoundError extends Error {\n  readonly code = \"filesystem_not_found\" as const;\n  constructor(public readonly path: string) {\n    super(`File not found: ${path}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n\n/**\n * A filesystem I/O operation failed for a reason other than not-found /\n * read-only / stale / security (e.g. `ENOTDIR` — a path component is a file, or\n * `EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,\n * untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).\n */\nexport class FilesystemError extends Error {\n  readonly code = \"filesystem_io\" as const;\n  constructor(\n    public readonly path: string,\n    cause: unknown,\n  ) {\n    super(\n      `Filesystem operation failed on \"${path}\": ${(cause as { message?: string })?.message ?? cause}`,\n      {\n        cause,\n      },\n    );\n    this.name = \"FilesystemError\";\n  }\n}\n\n/**\n * SE32 — a write's `expectedMtime` did not match the file's current mtime: the\n * file changed since it was last read, so the write would silently clobber.\n */\nexport class StaleFileError extends Error {\n  readonly code = \"filesystem_stale\" as const;\n  constructor(\n    public readonly path: string,\n    public readonly expectedMtime: number,\n    public readonly actualMtime: number,\n  ) {\n    super(\n      `Stale write to \"${path}\": expected mtime ${expectedMtime}, found ${actualMtime} ` +\n        `(file changed since last read — re-read before writing)`,\n    );\n    this.name = \"StaleFileError\";\n  }\n}\n\n/**\n * Pluggable filesystem backend. Implement the four abstract methods; `exists()`\n * and the `readOnly`/`basePath` accessors derive on the base class.\n *\n * @public\n */\nexport abstract class FilesystemBackend {\n  protected readonly _basePath: string;\n  protected readonly _readOnly: boolean;\n\n  constructor(config: FilesystemConfig = {}) {\n    this._basePath = config.basePath ?? process.cwd();\n    this._readOnly = config.readOnly ?? false;\n  }\n\n  /** Read a boundary-relative file as UTF-8. Throws {@link FileNotFoundError}. */\n  abstract readFile(path: string): Promise<string>;\n\n  /**\n   * Write UTF-8 content to a boundary-relative path (creating parents). Returns\n   * the new {@link FileStat}. Throws {@link FilesystemReadOnlyError} on a\n   * read-only backend and {@link StaleFileError} when `opts.expectedMtime`\n   * mismatches (SE32).\n   */\n  abstract writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat>;\n\n  /** Structured metadata for a path. Throws {@link FileNotFoundError}. */\n  abstract stat(path: string): Promise<FileStat>;\n\n  /** Directory entry names (not recursive). Throws {@link FileNotFoundError}. */\n  abstract list(path: string): Promise<string[]>;\n\n  /** Derived — true iff `stat(path)` resolves (absent ⇒ false). */\n  async exists(path: string): Promise<boolean> {\n    try {\n      await this.stat(path);\n      return true;\n    } catch (err) {\n      if (err instanceof FileNotFoundError) return false;\n      throw err;\n    }\n  }\n\n  /** Throw {@link FilesystemReadOnlyError} when the backend is read-only. */\n  protected assertWritable(): void {\n    if (this._readOnly) {\n      throw new FilesystemReadOnlyError(`Filesystem is read-only (basePath: ${this._basePath})`);\n    }\n  }\n\n  get readOnly(): boolean {\n    return this._readOnly;\n  }\n\n  get basePath(): string {\n    return this._basePath;\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one. A resolver runs at tool-execution\n * time (the request scope), so multi-tenant / multi-role agents get a distinct\n * root or permission set per request without a shared mutable backend.\n *\n * @public\n */\nexport type FilesystemProvider<Ctx = unknown> =\n  | FilesystemBackend\n  | ((ctx: Ctx) => FilesystemBackend | Promise<FilesystemBackend>);\n\n/** Resolve a {@link FilesystemProvider} to a concrete backend for `ctx`. */\nexport async function resolveFilesystem<Ctx>(\n  provider: FilesystemProvider<Ctx>,\n  ctx: Ctx,\n): Promise<FilesystemBackend> {\n  return provider instanceof FilesystemBackend ? provider : provider(ctx);\n}\n","/**\n * LocalFilesystem — a {@link FilesystemBackend} over the local process\n * filesystem (`node:fs/promises`), boundary-enforced against `basePath`.\n *\n * **This is NOT an isolation boundary** (same OS, same user). Its safety\n * affordances are path-boundary enforcement (traversal + symlink escape,\n * reusing the core `internal/security/path-guard` primitives) and the optional\n * `readOnly` flag. For untrusted code, run it inside a container/VM sandbox.\n *\n * The check-then-use gap between `assertNoSymlinkEscape` and the subsequent\n * `fs` call is a known TOCTOU: a local attacker could atomically swap an\n * in-boundary symlink after the check. Closing it needs `O_NOFOLLOW`, which\n * Node's `fs/promises` does not expose — accepted for same-user local contexts.\n *\n * SE31 (a peer framework Workspaces comparison). See ADR 0011.\n *\n * @public\n */\n\nimport {\n  readFile as fsReadFile,\n  stat as fsStat,\n  writeFile as fsWriteFile,\n  mkdir,\n  readdir,\n} from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport {\n  assertNoSymlinkEscape,\n  PathTraversalError,\n  safePathJoin,\n} from \"../internal/security/path-guard.js\";\nimport {\n  FileNotFoundError,\n  type FileStat,\n  FilesystemBackend,\n  type FilesystemConfig,\n  FilesystemError,\n  FilesystemSecurityError,\n  StaleFileError,\n  type WriteFileOptions,\n} from \"./types.js\";\n\n/**\n * {@link FilesystemBackend} over the real filesystem (`node:fs/promises`), with every path resolved\n * inside `basePath` and escapes rejected.\n *\n * ```ts\n * const fs = new LocalFilesystem({ basePath: \"/srv/workspace\", readOnly: false });\n * await fs.writeFile(\"notes/today.md\", \"hello\");   // /srv/workspace/notes/today.md\n * await fs.readFile(\"../../etc/passwd\");           // FilesystemSecurityError\n * ```\n *\n * Two things a caller gets wrong. First, the default `basePath` is `process.cwd()` — see\n * {@link FilesystemConfig}. Second, the security boundary is checked BEFORE the read-only flag, on\n * purpose: a traversal path against a read-only backend reports the security error, not the\n * read-only one, so the more serious condition is the one you see.\n *\n * Errors are normalised — a missing file, a stale `expectedMtime`, a boundary escape and a write to\n * a read-only backend each raise their own typed error rather than a raw `ENOENT`-shaped one.\n */\nexport class LocalFilesystem extends FilesystemBackend {\n  constructor(config: FilesystemConfig = {}) {\n    super(config);\n  }\n\n  async readFile(path: string): Promise<string> {\n    const abs = this.resolve(path);\n    try {\n      return await fsReadFile(abs, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  async writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat> {\n    // Security boundary FIRST (a traversal path on a read-only backend must\n    // report the security error, not the read-only one — fail-clear).\n    const abs = this.resolve(path);\n    this.assertWritable();\n    // SE32 — stale-write guard: if the caller passed the mtime it last read,\n    // reject when the file changed underneath it (never a silent clobber).\n    if (opts?.expectedMtime !== undefined) {\n      await this.assertNotStale(path, abs, opts.expectedMtime);\n    }\n    try {\n      await mkdir(dirname(abs), { recursive: true });\n      await fsWriteFile(abs, content, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n    return this.statAbs(abs, path);\n  }\n\n  async stat(path: string): Promise<FileStat> {\n    const abs = this.resolve(path);\n    return this.statAbs(abs, path);\n  }\n\n  async list(path: string): Promise<string[]> {\n    const abs = this.resolve(path);\n    try {\n      return await readdir(abs);\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  private async statAbs(abs: string, relPath: string): Promise<FileStat> {\n    try {\n      const s = await fsStat(abs);\n      return {\n        size: s.size,\n        mtimeMs: s.mtimeMs,\n        isFile: s.isFile(),\n        isDirectory: s.isDirectory(),\n      };\n    } catch (err) {\n      throw this.mapError(err, relPath);\n    }\n  }\n\n  /** SE32 — compare the on-disk mtime against the caller's expected value. */\n  private async assertNotStale(relPath: string, abs: string, expectedMtime: number): Promise<void> {\n    let current: number | undefined;\n    try {\n      current = (await fsStat(abs)).mtimeMs;\n    } catch (err) {\n      // A brand-new file (does not exist yet) cannot be stale — allow the write.\n      if ((err as { code?: string }).code === \"ENOENT\") return;\n      throw this.mapError(err, relPath);\n    }\n    if (current !== expectedMtime) {\n      throw new StaleFileError(relPath, expectedMtime, current);\n    }\n  }\n\n  /**\n   * Resolve a boundary-relative path to an absolute one, rejecting lexical\n   * traversal (`..`, absolute, NUL) and symlink escape — both reusing the core\n   * path-guard primitives, remapped to {@link FilesystemSecurityError}.\n   */\n  private resolve(path: string): string {\n    let abs: string;\n    try {\n      abs = safePathJoin(this._basePath, path);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath: ${path}`);\n      }\n      throw err;\n    }\n    try {\n      assertNoSymlinkEscape(abs, this._basePath);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath via symlink: ${path}`);\n      }\n      throw err;\n    }\n    return abs;\n  }\n\n  private mapError(err: unknown, path: string): Error {\n    if (\n      err instanceof FilesystemSecurityError ||\n      err instanceof FilesystemError ||\n      err instanceof FileNotFoundError ||\n      err instanceof StaleFileError\n    ) {\n      return err;\n    }\n    if ((err as { code?: string }).code === \"ENOENT\") return new FileNotFoundError(path);\n    // ENOTDIR (a path component is a file), EACCES, ENOSPC, … — never leak a\n    // raw untyped Node SystemError (Rule 8); wrap with the original as cause.\n    return new FilesystemError(path, err);\n  }\n}\n"]}

package/dist/filesystem/index.js

@@ -1,7 +1,8 @@
-import { safePathJoin, PathTraversalError, assertNoSymlinkEscape } from '../chunk-XWCTBGYK.js';
+import { safePathJoin, PathTraversalError, assertNoSymlinkEscape } from '../chunk-QARJGQSA.js';
 import '../chunk-RIAM53CP.js';
-import '../chunk-HI4ZW62S.js';
-import '../chunk-4X3SBHPK.js';
+import '../chunk-IDCKSLYH.js';
+import '../chunk-T7XEKOVW.js';
+import '../chunk-T7O6K6PX.js';
 import { readFile, mkdir, writeFile, readdir, stat } from 'fs/promises';
 import { dirname } from 'path';
 

package/dist/filesystem/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/filesystem/types.ts","../../src/filesystem/local-filesystem.ts"],"names":["fsReadFile","fsWriteFile","fsStat"],"mappings":";;;;;;;;AA6CO,IAAM,uBAAA,GAAN,cAAsC,KAAA,CAAM;AAAA,EACxC,IAAA,GAAO,qBAAA;AAAA,EAChB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,yBAAA;AAAA,EACd;AACF;AAGO,IAAM,uBAAA,GAAN,cAAsC,KAAA,CAAM;AAAA,EACxC,IAAA,GAAO,qBAAA;AAAA,EAChB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,yBAAA;AAAA,EACd;AACF;AAGO,IAAM,iBAAA,GAAN,cAAgC,KAAA,CAAM;AAAA,EAE3C,YAA4B,IAAA,EAAc;AACxC,IAAA,KAAA,CAAM,CAAA,gBAAA,EAAmB,IAAI,CAAA,CAAE,CAAA;AADL,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAE1B,IAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AAAA,EACd;AAAA,EAH4B,IAAA;AAAA,EADnB,IAAA,GAAO,sBAAA;AAKlB;AAQO,IAAM,eAAA,GAAN,cAA8B,KAAA,CAAM;AAAA,EAEzC,WAAA,CACkB,MAChB,KAAA,EACA;AACA,IAAA,KAAA;AAAA,MACE,CAAA,gCAAA,EAAmC,IAAI,CAAA,GAAA,EAAO,KAAA,EAAgC,WAAW,KAAK,CAAA,CAAA;AAAA,MAC9F;AAAA,QACE;AAAA;AACF,KACF;AARgB,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAShB,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AAAA,EACd;AAAA,EAVkB,IAAA;AAAA,EAFT,IAAA,GAAO,eAAA;AAalB;AAMO,IAAM,cAAA,GAAN,cAA6B,KAAA,CAAM;AAAA,EAExC,WAAA,CACkB,IAAA,EACA,aAAA,EACA,WAAA,EAChB;AACA,IAAA,KAAA;AAAA,MACE,CAAA,gBAAA,EAAmB,IAAI,CAAA,kBAAA,EAAqB,aAAa,WAAW,WAAW,CAAA,6DAAA;AAAA,KAEjF;AAPgB,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AACA,IAAA,IAAA,CAAA,aAAA,GAAA,aAAA;AACA,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AAMhB,IAAA,IAAA,CAAK,IAAA,GAAO,gBAAA;AAAA,EACd;AAAA,EATkB,IAAA;AAAA,EACA,aAAA;AAAA,EACA,WAAA;AAAA,EAJT,IAAA,GAAO,kBAAA;AAYlB;AAQO,IAAe,oBAAf,MAAiC;AAAA,EACnB,SAAA;AAAA,EACA,SAAA;AAAA,EAEnB,WAAA,CAAY,MAAA,GAA2B,EAAC,EAAG;AACzC,IAAA,IAAA,CAAK,SAAA,GAAY,MAAA,CAAO,QAAA,IAAY,OAAA,CAAQ,GAAA,EAAI;AAChD,IAAA,IAAA,CAAK,SAAA,GAAY,OAAO,QAAA,IAAY,KAAA;AAAA,EACtC;AAAA;AAAA,EAoBA,MAAM,OAAO,IAAA,EAAgC;AAC3C,IAAA,IAAI;AACF,MAAA,MAAM,IAAA,CAAK,KAAK,IAAI,CAAA;AACpB,MAAA,OAAO,IAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,IAAI,GAAA,YAAe,mBAAmB,OAAO,KAAA;AAC7C,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF;AAAA;AAAA,EAGU,cAAA,GAAuB;AAC/B,IAAA,IAAI,KAAK,SAAA,EAAW;AAClB,MAAA,MAAM,IAAI,uBAAA,CAAwB,CAAA,mCAAA,EAAsC,IAAA,CAAK,SAAS,CAAA,CAAA,CAAG,CAAA;AAAA,IAC3F;AAAA,EACF;AAAA,EAEA,IAAI,QAAA,GAAoB;AACtB,IAAA,OAAO,IAAA,CAAK,SAAA;AAAA,EACd;AAAA,EAEA,IAAI,QAAA,GAAmB;AACrB,IAAA,OAAO,IAAA,CAAK,SAAA;AAAA,EACd;AACF;AAcA,eAAsB,iBAAA,CACpB,UACA,GAAA,EAC4B;AAC5B,EAAA,OAAO,QAAA,YAAoB,iBAAA,GAAoB,QAAA,GAAW,QAAA,CAAS,GAAG,CAAA;AACxE;;;AChJO,IAAM,eAAA,GAAN,cAA8B,iBAAA,CAAkB;AAAA,EACrD,WAAA,CAAY,MAAA,GAA2B,EAAC,EAAG;AACzC,IAAA,KAAA,CAAM,MAAM,CAAA;AAAA,EACd;AAAA,EAEA,MAAM,SAAS,IAAA,EAA+B;AAC5C,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,CAAQ,IAAI,CAAA;AAC7B,IAAA,IAAI;AACF,MAAA,OAAO,MAAMA,QAAA,CAAW,GAAA,EAAK,OAAO,CAAA;AAAA,IACtC,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,QAAA,CAAS,GAAA,EAAK,IAAI,CAAA;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,MAAM,SAAA,CAAU,IAAA,EAAc,OAAA,EAAiB,IAAA,EAA4C;AAGzF,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,CAAQ,IAAI,CAAA;AAC7B,IAAA,IAAA,CAAK,cAAA,EAAe;AAGpB,IAAA,IAAI,IAAA,EAAM,kBAAkB,MAAA,EAAW;AACrC,MAAA,MAAM,IAAA,CAAK,cAAA,CAAe,IAAA,EAAM,GAAA,EAAK,KAAK,aAAa,CAAA;AAAA,IACzD;AACA,IAAA,IAAI;AACF,MAAA,MAAM,MAAM,OAAA,CAAQ,GAAG,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAC7C,MAAA,MAAMC,SAAA,CAAY,GAAA,EAAK,OAAA,EAAS,OAAO,CAAA;AAAA,IACzC,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,QAAA,CAAS,GAAA,EAAK,IAAI,CAAA;AAAA,IAC/B;AACA,IAAA,OAAO,IAAA,CAAK,OAAA,CAAQ,GAAA,EAAK,IAAI,CAAA;AAAA,EAC/B;AAAA,EAEA,MAAM,KAAK,IAAA,EAAiC;AAC1C,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,CAAQ,IAAI,CAAA;AAC7B,IAAA,OAAO,IAAA,CAAK,OAAA,CAAQ,GAAA,EAAK,IAAI,CAAA;AAAA,EAC/B;AAAA,EAEA,MAAM,KAAK,IAAA,EAAiC;AAC1C,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,CAAQ,IAAI,CAAA;AAC7B,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,QAAQ,GAAG,CAAA;AAAA,IAC1B,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,QAAA,CAAS,GAAA,EAAK,IAAI,CAAA;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,MAAc,OAAA,CAAQ,GAAA,EAAa,OAAA,EAAoC;AACrE,IAAA,IAAI;AACF,MAAA,MAAM,CAAA,GAAI,MAAMC,IAAA,CAAO,GAAG,CAAA;AAC1B,MAAA,OAAO;AAAA,QACL,MAAM,CAAA,CAAE,IAAA;AAAA,QACR,SAAS,CAAA,CAAE,OAAA;AAAA,QACX,MAAA,EAAQ,EAAE,MAAA,EAAO;AAAA,QACjB,WAAA,EAAa,EAAE,WAAA;AAAY,OAC7B;AAAA,IACF,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,QAAA,CAAS,GAAA,EAAK,OAAO,CAAA;AAAA,IAClC;AAAA,EACF;AAAA;AAAA,EAGA,MAAc,cAAA,CAAe,OAAA,EAAiB,GAAA,EAAa,aAAA,EAAsC;AAC/F,IAAA,IAAI,OAAA;AACJ,IAAA,IAAI;AACF,MAAA,OAAA,GAAA,CAAW,MAAMA,IAAA,CAAO,GAAG,CAAA,EAAG,OAAA;AAAA,IAChC,SAAS,GAAA,EAAK;AAEZ,MAAA,IAAK,GAAA,CAA0B,SAAS,QAAA,EAAU;AAClD,MAAA,MAAM,IAAA,CAAK,QAAA,CAAS,GAAA,EAAK,OAAO,CAAA;AAAA,IAClC;AACA,IAAA,IAAI,YAAY,aAAA,EAAe;AAC7B,MAAA,MAAM,IAAI,cAAA,CAAe,OAAA,EAAS,aAAA,EAAe,OAAO,CAAA;AAAA,IAC1D;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOQ,QAAQ,IAAA,EAAsB;AACpC,IAAA,IAAI,GAAA;AACJ,IAAA,IAAI;AACF,MAAA,GAAA,GAAM,YAAA,CAAa,IAAA,CAAK,SAAA,EAAW,IAAI,CAAA;AAAA,IACzC,SAAS,GAAA,EAAK;AACZ,MAAA,IAAI,eAAe,kBAAA,EAAoB;AACrC,QAAA,MAAM,IAAI,uBAAA,CAAwB,CAAA,uBAAA,EAA0B,IAAI,CAAA,CAAE,CAAA;AAAA,MACpE;AACA,MAAA,MAAM,GAAA;AAAA,IACR;AACA,IAAA,IAAI;AACF,MAAA,qBAAA,CAAsB,GAAA,EAAK,KAAK,SAAS,CAAA;AAAA,IAC3C,SAAS,GAAA,EAAK;AACZ,MAAA,IAAI,eAAe,kBAAA,EAAoB;AACrC,QAAA,MAAM,IAAI,uBAAA,CAAwB,CAAA,mCAAA,EAAsC,IAAI,CAAA,CAAE,CAAA;AAAA,MAChF;AACA,MAAA,MAAM,GAAA;AAAA,IACR;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA,EAEQ,QAAA,CAAS,KAAc,IAAA,EAAqB;AAClD,IAAA,IACE,eAAe,uBAAA,IACf,GAAA,YAAe,mBACf,GAAA,YAAe,iBAAA,IACf,eAAe,cAAA,EACf;AACA,MAAA,OAAO,GAAA;AAAA,IACT;AACA,IAAA,IAAK,IAA0B,IAAA,KAAS,QAAA,EAAU,OAAO,IAAI,kBAAkB,IAAI,CAAA;AAGnF,IAAA,OAAO,IAAI,eAAA,CAAgB,IAAA,EAAM,GAAG,CAAA;AAAA,EACtC;AACF","file":"index.js","sourcesContent":["/**\n * Filesystem backend protocol — a pluggable file *storage* provider for agent\n * tools, the storage-side twin of {@link SandboxBackend} (execution-side).\n *\n * SE31 (a peer framework Workspaces comparison). Mirrors `SandboxBackend`'s shape: a small\n * set of abstract methods (`readFile` / `writeFile` / `stat` / `list`) with\n * `exists()` derived on the base class, a boundary `basePath`, a `readOnly`\n * flag, and typed errors. Unlike `SandboxBackend` (whose file ops shell out via\n * `execute`, requiring command execution and giving NO structured `stat`), a\n * `FilesystemBackend` serves a *filesystem-only* workspace with no sandbox and\n * exposes a real `stat().mtimeMs` — the primitive SE32's read-before-write\n * safety compares against. See ADR 0011.\n *\n * New backends (S3, GCS, in-memory) implement the four abstract methods; higher\n * level helpers derive on the base. This is the backend *seam* — it does NOT\n * ship agent-facing tools nor a bundled workspace (bring-your-own-tools stands).\n *\n * @public\n */\n\n/** Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32). */\nexport interface FileStat {\n  readonly size: number;\n  readonly mtimeMs: number;\n  readonly isFile: boolean;\n  readonly isDirectory: boolean;\n}\n\n/** Options a write may carry. SE32 adds `expectedMtime` (stale-write guard). */\nexport interface WriteFileOptions {\n  /**\n   * SE32 — when set, the write fails with {@link StaleFileError} if the file's\n   * current `mtimeMs` differs (someone changed it since it was last read).\n   */\n  readonly expectedMtime?: number;\n}\n\nexport interface FilesystemConfig {\n  /** Boundary root. Every path is resolved within it; escapes are rejected. */\n  readonly basePath?: string;\n  /** When true, every write throws {@link FilesystemReadOnlyError}. */\n  readonly readOnly?: boolean;\n}\n\n/** A path escaped the backend's `basePath` (traversal or symlink). */\nexport class FilesystemSecurityError extends Error {\n  readonly code = \"filesystem_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemSecurityError\";\n  }\n}\n\n/** A write was attempted on a read-only backend. */\nexport class FilesystemReadOnlyError extends Error {\n  readonly code = \"filesystem_readonly\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemReadOnlyError\";\n  }\n}\n\n/** A read/stat targeted a path that does not exist. */\nexport class FileNotFoundError extends Error {\n  readonly code = \"filesystem_not_found\" as const;\n  constructor(public readonly path: string) {\n    super(`File not found: ${path}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n\n/**\n * A filesystem I/O operation failed for a reason other than not-found /\n * read-only / stale / security (e.g. `ENOTDIR` — a path component is a file, or\n * `EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,\n * untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).\n */\nexport class FilesystemError extends Error {\n  readonly code = \"filesystem_io\" as const;\n  constructor(\n    public readonly path: string,\n    cause: unknown,\n  ) {\n    super(\n      `Filesystem operation failed on \"${path}\": ${(cause as { message?: string })?.message ?? cause}`,\n      {\n        cause,\n      },\n    );\n    this.name = \"FilesystemError\";\n  }\n}\n\n/**\n * SE32 — a write's `expectedMtime` did not match the file's current mtime: the\n * file changed since it was last read, so the write would silently clobber.\n */\nexport class StaleFileError extends Error {\n  readonly code = \"filesystem_stale\" as const;\n  constructor(\n    public readonly path: string,\n    public readonly expectedMtime: number,\n    public readonly actualMtime: number,\n  ) {\n    super(\n      `Stale write to \"${path}\": expected mtime ${expectedMtime}, found ${actualMtime} ` +\n        `(file changed since last read — re-read before writing)`,\n    );\n    this.name = \"StaleFileError\";\n  }\n}\n\n/**\n * Pluggable filesystem backend. Implement the four abstract methods; `exists()`\n * and the `readOnly`/`basePath` accessors derive on the base class.\n *\n * @public\n */\nexport abstract class FilesystemBackend {\n  protected readonly _basePath: string;\n  protected readonly _readOnly: boolean;\n\n  constructor(config: FilesystemConfig = {}) {\n    this._basePath = config.basePath ?? process.cwd();\n    this._readOnly = config.readOnly ?? false;\n  }\n\n  /** Read a boundary-relative file as UTF-8. Throws {@link FileNotFoundError}. */\n  abstract readFile(path: string): Promise<string>;\n\n  /**\n   * Write UTF-8 content to a boundary-relative path (creating parents). Returns\n   * the new {@link FileStat}. Throws {@link FilesystemReadOnlyError} on a\n   * read-only backend and {@link StaleFileError} when `opts.expectedMtime`\n   * mismatches (SE32).\n   */\n  abstract writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat>;\n\n  /** Structured metadata for a path. Throws {@link FileNotFoundError}. */\n  abstract stat(path: string): Promise<FileStat>;\n\n  /** Directory entry names (not recursive). Throws {@link FileNotFoundError}. */\n  abstract list(path: string): Promise<string[]>;\n\n  /** Derived — true iff `stat(path)` resolves (absent ⇒ false). */\n  async exists(path: string): Promise<boolean> {\n    try {\n      await this.stat(path);\n      return true;\n    } catch (err) {\n      if (err instanceof FileNotFoundError) return false;\n      throw err;\n    }\n  }\n\n  /** Throw {@link FilesystemReadOnlyError} when the backend is read-only. */\n  protected assertWritable(): void {\n    if (this._readOnly) {\n      throw new FilesystemReadOnlyError(`Filesystem is read-only (basePath: ${this._basePath})`);\n    }\n  }\n\n  get readOnly(): boolean {\n    return this._readOnly;\n  }\n\n  get basePath(): string {\n    return this._basePath;\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one. A resolver runs at tool-execution\n * time (the request scope), so multi-tenant / multi-role agents get a distinct\n * root or permission set per request without a shared mutable backend.\n *\n * @public\n */\nexport type FilesystemProvider<Ctx = unknown> =\n  | FilesystemBackend\n  | ((ctx: Ctx) => FilesystemBackend | Promise<FilesystemBackend>);\n\n/** Resolve a {@link FilesystemProvider} to a concrete backend for `ctx`. */\nexport async function resolveFilesystem<Ctx>(\n  provider: FilesystemProvider<Ctx>,\n  ctx: Ctx,\n): Promise<FilesystemBackend> {\n  return provider instanceof FilesystemBackend ? provider : provider(ctx);\n}\n","/**\n * LocalFilesystem — a {@link FilesystemBackend} over the local process\n * filesystem (`node:fs/promises`), boundary-enforced against `basePath`.\n *\n * **This is NOT an isolation boundary** (same OS, same user). Its safety\n * affordances are path-boundary enforcement (traversal + symlink escape,\n * reusing the core `internal/security/path-guard` primitives) and the optional\n * `readOnly` flag. For untrusted code, run it inside a container/VM sandbox.\n *\n * The check-then-use gap between `assertNoSymlinkEscape` and the subsequent\n * `fs` call is a known TOCTOU: a local attacker could atomically swap an\n * in-boundary symlink after the check. Closing it needs `O_NOFOLLOW`, which\n * Node's `fs/promises` does not expose — accepted for same-user local contexts.\n *\n * SE31 (a peer framework Workspaces comparison). See ADR 0011.\n *\n * @public\n */\n\nimport {\n  readFile as fsReadFile,\n  stat as fsStat,\n  writeFile as fsWriteFile,\n  mkdir,\n  readdir,\n} from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport {\n  assertNoSymlinkEscape,\n  PathTraversalError,\n  safePathJoin,\n} from \"../internal/security/path-guard.js\";\nimport {\n  FileNotFoundError,\n  type FileStat,\n  FilesystemBackend,\n  type FilesystemConfig,\n  FilesystemError,\n  FilesystemSecurityError,\n  StaleFileError,\n  type WriteFileOptions,\n} from \"./types.js\";\n\nexport class LocalFilesystem extends FilesystemBackend {\n  constructor(config: FilesystemConfig = {}) {\n    super(config);\n  }\n\n  async readFile(path: string): Promise<string> {\n    const abs = this.resolve(path);\n    try {\n      return await fsReadFile(abs, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  async writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat> {\n    // Security boundary FIRST (a traversal path on a read-only backend must\n    // report the security error, not the read-only one — fail-clear).\n    const abs = this.resolve(path);\n    this.assertWritable();\n    // SE32 — stale-write guard: if the caller passed the mtime it last read,\n    // reject when the file changed underneath it (never a silent clobber).\n    if (opts?.expectedMtime !== undefined) {\n      await this.assertNotStale(path, abs, opts.expectedMtime);\n    }\n    try {\n      await mkdir(dirname(abs), { recursive: true });\n      await fsWriteFile(abs, content, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n    return this.statAbs(abs, path);\n  }\n\n  async stat(path: string): Promise<FileStat> {\n    const abs = this.resolve(path);\n    return this.statAbs(abs, path);\n  }\n\n  async list(path: string): Promise<string[]> {\n    const abs = this.resolve(path);\n    try {\n      return await readdir(abs);\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  private async statAbs(abs: string, relPath: string): Promise<FileStat> {\n    try {\n      const s = await fsStat(abs);\n      return {\n        size: s.size,\n        mtimeMs: s.mtimeMs,\n        isFile: s.isFile(),\n        isDirectory: s.isDirectory(),\n      };\n    } catch (err) {\n      throw this.mapError(err, relPath);\n    }\n  }\n\n  /** SE32 — compare the on-disk mtime against the caller's expected value. */\n  private async assertNotStale(relPath: string, abs: string, expectedMtime: number): Promise<void> {\n    let current: number | undefined;\n    try {\n      current = (await fsStat(abs)).mtimeMs;\n    } catch (err) {\n      // A brand-new file (does not exist yet) cannot be stale — allow the write.\n      if ((err as { code?: string }).code === \"ENOENT\") return;\n      throw this.mapError(err, relPath);\n    }\n    if (current !== expectedMtime) {\n      throw new StaleFileError(relPath, expectedMtime, current);\n    }\n  }\n\n  /**\n   * Resolve a boundary-relative path to an absolute one, rejecting lexical\n   * traversal (`..`, absolute, NUL) and symlink escape — both reusing the core\n   * path-guard primitives, remapped to {@link FilesystemSecurityError}.\n   */\n  private resolve(path: string): string {\n    let abs: string;\n    try {\n      abs = safePathJoin(this._basePath, path);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath: ${path}`);\n      }\n      throw err;\n    }\n    try {\n      assertNoSymlinkEscape(abs, this._basePath);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath via symlink: ${path}`);\n      }\n      throw err;\n    }\n    return abs;\n  }\n\n  private mapError(err: unknown, path: string): Error {\n    if (\n      err instanceof FilesystemSecurityError ||\n      err instanceof FilesystemError ||\n      err instanceof FileNotFoundError ||\n      err instanceof StaleFileError\n    ) {\n      return err;\n    }\n    if ((err as { code?: string }).code === \"ENOENT\") return new FileNotFoundError(path);\n    // ENOTDIR (a path component is a file), EACCES, ENOSPC, … — never leak a\n    // raw untyped Node SystemError (Rule 8); wrap with the original as cause.\n    return new FilesystemError(path, err);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/filesystem/types.ts","../../src/filesystem/local-filesystem.ts"],"names":["fsReadFile","fsWriteFile","fsStat"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Filesystem backend protocol — a pluggable file *storage* provider for agent\n * tools, the storage-side twin of {@link SandboxBackend} (execution-side).\n *\n * SE31 (a peer framework Workspaces comparison). Mirrors `SandboxBackend`'s shape: a small\n * set of abstract methods (`readFile` / `writeFile` / `stat` / `list`) with\n * `exists()` derived on the base class, a boundary `basePath`, a `readOnly`\n * flag, and typed errors. Unlike `SandboxBackend` (whose file ops shell out via\n * `execute`, requiring command execution and giving NO structured `stat`), a\n * `FilesystemBackend` serves a *filesystem-only* workspace with no sandbox and\n * exposes a real `stat().mtimeMs` — the primitive SE32's read-before-write\n * safety compares against. See ADR 0011.\n *\n * New backends (S3, GCS, in-memory) implement the four abstract methods; higher\n * level helpers derive on the base. This is the backend *seam* — it does NOT\n * ship agent-facing tools nor a bundled workspace (bring-your-own-tools stands).\n *\n * @public\n */\n\n/** Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32). */\nexport interface FileStat {\n  readonly size: number;\n  readonly mtimeMs: number;\n  readonly isFile: boolean;\n  readonly isDirectory: boolean;\n}\n\n/** Options a write may carry. SE32 adds `expectedMtime` (stale-write guard). */\nexport interface WriteFileOptions {\n  /**\n   * SE32 — when set, the write fails with {@link StaleFileError} if the file's\n   * current `mtimeMs` differs (someone changed it since it was last read).\n   */\n  readonly expectedMtime?: number;\n}\n\n/**\n * Construction options shared by every {@link FilesystemBackend}.\n *\n * `basePath` is resolved ONCE, at construction, and defaults to `process.cwd()`. Omitting it does\n * not mean \"no boundary\" — it means the boundary is wherever the process happened to be standing,\n * which is rarely what the caller intended and never what a reviewer can verify. Pass it explicitly.\n *\n * The boundary rejects lexical traversal AND symlink escape, raising\n * {@link FilesystemSecurityError}. It is a boundary, not a sandbox: it constrains paths this\n * backend resolves, and constrains nothing else the process can do. For untrusted code, run it in a\n * container or VM.\n */\nexport interface FilesystemConfig {\n  /** Boundary root. Every path is resolved within it; escapes are rejected. */\n  readonly basePath?: string;\n  /** When true, every write throws {@link FilesystemReadOnlyError}. */\n  readonly readOnly?: boolean;\n}\n\n/** A path escaped the backend's `basePath` (traversal or symlink). */\nexport class FilesystemSecurityError extends Error {\n  readonly code = \"filesystem_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemSecurityError\";\n  }\n}\n\n/** A write was attempted on a read-only backend. */\nexport class FilesystemReadOnlyError extends Error {\n  readonly code = \"filesystem_readonly\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"FilesystemReadOnlyError\";\n  }\n}\n\n/** A read/stat targeted a path that does not exist. */\nexport class FileNotFoundError extends Error {\n  readonly code = \"filesystem_not_found\" as const;\n  constructor(public readonly path: string) {\n    super(`File not found: ${path}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n\n/**\n * A filesystem I/O operation failed for a reason other than not-found /\n * read-only / stale / security (e.g. `ENOTDIR` — a path component is a file, or\n * `EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,\n * untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).\n */\nexport class FilesystemError extends Error {\n  readonly code = \"filesystem_io\" as const;\n  constructor(\n    public readonly path: string,\n    cause: unknown,\n  ) {\n    super(\n      `Filesystem operation failed on \"${path}\": ${(cause as { message?: string })?.message ?? cause}`,\n      {\n        cause,\n      },\n    );\n    this.name = \"FilesystemError\";\n  }\n}\n\n/**\n * SE32 — a write's `expectedMtime` did not match the file's current mtime: the\n * file changed since it was last read, so the write would silently clobber.\n */\nexport class StaleFileError extends Error {\n  readonly code = \"filesystem_stale\" as const;\n  constructor(\n    public readonly path: string,\n    public readonly expectedMtime: number,\n    public readonly actualMtime: number,\n  ) {\n    super(\n      `Stale write to \"${path}\": expected mtime ${expectedMtime}, found ${actualMtime} ` +\n        `(file changed since last read — re-read before writing)`,\n    );\n    this.name = \"StaleFileError\";\n  }\n}\n\n/**\n * Pluggable filesystem backend. Implement the four abstract methods; `exists()`\n * and the `readOnly`/`basePath` accessors derive on the base class.\n *\n * @public\n */\nexport abstract class FilesystemBackend {\n  protected readonly _basePath: string;\n  protected readonly _readOnly: boolean;\n\n  constructor(config: FilesystemConfig = {}) {\n    this._basePath = config.basePath ?? process.cwd();\n    this._readOnly = config.readOnly ?? false;\n  }\n\n  /** Read a boundary-relative file as UTF-8. Throws {@link FileNotFoundError}. */\n  abstract readFile(path: string): Promise<string>;\n\n  /**\n   * Write UTF-8 content to a boundary-relative path (creating parents). Returns\n   * the new {@link FileStat}. Throws {@link FilesystemReadOnlyError} on a\n   * read-only backend and {@link StaleFileError} when `opts.expectedMtime`\n   * mismatches (SE32).\n   */\n  abstract writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat>;\n\n  /** Structured metadata for a path. Throws {@link FileNotFoundError}. */\n  abstract stat(path: string): Promise<FileStat>;\n\n  /** Directory entry names (not recursive). Throws {@link FileNotFoundError}. */\n  abstract list(path: string): Promise<string[]>;\n\n  /** Derived — true iff `stat(path)` resolves (absent ⇒ false). */\n  async exists(path: string): Promise<boolean> {\n    try {\n      await this.stat(path);\n      return true;\n    } catch (err) {\n      if (err instanceof FileNotFoundError) return false;\n      throw err;\n    }\n  }\n\n  /** Throw {@link FilesystemReadOnlyError} when the backend is read-only. */\n  protected assertWritable(): void {\n    if (this._readOnly) {\n      throw new FilesystemReadOnlyError(`Filesystem is read-only (basePath: ${this._basePath})`);\n    }\n  }\n\n  get readOnly(): boolean {\n    return this._readOnly;\n  }\n\n  get basePath(): string {\n    return this._basePath;\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one. A resolver runs at tool-execution\n * time (the request scope), so multi-tenant / multi-role agents get a distinct\n * root or permission set per request without a shared mutable backend.\n *\n * @public\n */\nexport type FilesystemProvider<Ctx = unknown> =\n  | FilesystemBackend\n  | ((ctx: Ctx) => FilesystemBackend | Promise<FilesystemBackend>);\n\n/** Resolve a {@link FilesystemProvider} to a concrete backend for `ctx`. */\nexport async function resolveFilesystem<Ctx>(\n  provider: FilesystemProvider<Ctx>,\n  ctx: Ctx,\n): Promise<FilesystemBackend> {\n  return provider instanceof FilesystemBackend ? provider : provider(ctx);\n}\n","/**\n * LocalFilesystem — a {@link FilesystemBackend} over the local process\n * filesystem (`node:fs/promises`), boundary-enforced against `basePath`.\n *\n * **This is NOT an isolation boundary** (same OS, same user). Its safety\n * affordances are path-boundary enforcement (traversal + symlink escape,\n * reusing the core `internal/security/path-guard` primitives) and the optional\n * `readOnly` flag. For untrusted code, run it inside a container/VM sandbox.\n *\n * The check-then-use gap between `assertNoSymlinkEscape` and the subsequent\n * `fs` call is a known TOCTOU: a local attacker could atomically swap an\n * in-boundary symlink after the check. Closing it needs `O_NOFOLLOW`, which\n * Node's `fs/promises` does not expose — accepted for same-user local contexts.\n *\n * SE31 (a peer framework Workspaces comparison). See ADR 0011.\n *\n * @public\n */\n\nimport {\n  readFile as fsReadFile,\n  stat as fsStat,\n  writeFile as fsWriteFile,\n  mkdir,\n  readdir,\n} from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport {\n  assertNoSymlinkEscape,\n  PathTraversalError,\n  safePathJoin,\n} from \"../internal/security/path-guard.js\";\nimport {\n  FileNotFoundError,\n  type FileStat,\n  FilesystemBackend,\n  type FilesystemConfig,\n  FilesystemError,\n  FilesystemSecurityError,\n  StaleFileError,\n  type WriteFileOptions,\n} from \"./types.js\";\n\n/**\n * {@link FilesystemBackend} over the real filesystem (`node:fs/promises`), with every path resolved\n * inside `basePath` and escapes rejected.\n *\n * ```ts\n * const fs = new LocalFilesystem({ basePath: \"/srv/workspace\", readOnly: false });\n * await fs.writeFile(\"notes/today.md\", \"hello\");   // /srv/workspace/notes/today.md\n * await fs.readFile(\"../../etc/passwd\");           // FilesystemSecurityError\n * ```\n *\n * Two things a caller gets wrong. First, the default `basePath` is `process.cwd()` — see\n * {@link FilesystemConfig}. Second, the security boundary is checked BEFORE the read-only flag, on\n * purpose: a traversal path against a read-only backend reports the security error, not the\n * read-only one, so the more serious condition is the one you see.\n *\n * Errors are normalised — a missing file, a stale `expectedMtime`, a boundary escape and a write to\n * a read-only backend each raise their own typed error rather than a raw `ENOENT`-shaped one.\n */\nexport class LocalFilesystem extends FilesystemBackend {\n  constructor(config: FilesystemConfig = {}) {\n    super(config);\n  }\n\n  async readFile(path: string): Promise<string> {\n    const abs = this.resolve(path);\n    try {\n      return await fsReadFile(abs, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  async writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat> {\n    // Security boundary FIRST (a traversal path on a read-only backend must\n    // report the security error, not the read-only one — fail-clear).\n    const abs = this.resolve(path);\n    this.assertWritable();\n    // SE32 — stale-write guard: if the caller passed the mtime it last read,\n    // reject when the file changed underneath it (never a silent clobber).\n    if (opts?.expectedMtime !== undefined) {\n      await this.assertNotStale(path, abs, opts.expectedMtime);\n    }\n    try {\n      await mkdir(dirname(abs), { recursive: true });\n      await fsWriteFile(abs, content, \"utf-8\");\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n    return this.statAbs(abs, path);\n  }\n\n  async stat(path: string): Promise<FileStat> {\n    const abs = this.resolve(path);\n    return this.statAbs(abs, path);\n  }\n\n  async list(path: string): Promise<string[]> {\n    const abs = this.resolve(path);\n    try {\n      return await readdir(abs);\n    } catch (err) {\n      throw this.mapError(err, path);\n    }\n  }\n\n  private async statAbs(abs: string, relPath: string): Promise<FileStat> {\n    try {\n      const s = await fsStat(abs);\n      return {\n        size: s.size,\n        mtimeMs: s.mtimeMs,\n        isFile: s.isFile(),\n        isDirectory: s.isDirectory(),\n      };\n    } catch (err) {\n      throw this.mapError(err, relPath);\n    }\n  }\n\n  /** SE32 — compare the on-disk mtime against the caller's expected value. */\n  private async assertNotStale(relPath: string, abs: string, expectedMtime: number): Promise<void> {\n    let current: number | undefined;\n    try {\n      current = (await fsStat(abs)).mtimeMs;\n    } catch (err) {\n      // A brand-new file (does not exist yet) cannot be stale — allow the write.\n      if ((err as { code?: string }).code === \"ENOENT\") return;\n      throw this.mapError(err, relPath);\n    }\n    if (current !== expectedMtime) {\n      throw new StaleFileError(relPath, expectedMtime, current);\n    }\n  }\n\n  /**\n   * Resolve a boundary-relative path to an absolute one, rejecting lexical\n   * traversal (`..`, absolute, NUL) and symlink escape — both reusing the core\n   * path-guard primitives, remapped to {@link FilesystemSecurityError}.\n   */\n  private resolve(path: string): string {\n    let abs: string;\n    try {\n      abs = safePathJoin(this._basePath, path);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath: ${path}`);\n      }\n      throw err;\n    }\n    try {\n      assertNoSymlinkEscape(abs, this._basePath);\n    } catch (err) {\n      if (err instanceof PathTraversalError) {\n        throw new FilesystemSecurityError(`Path escapes basePath via symlink: ${path}`);\n      }\n      throw err;\n    }\n    return abs;\n  }\n\n  private mapError(err: unknown, path: string): Error {\n    if (\n      err instanceof FilesystemSecurityError ||\n      err instanceof FilesystemError ||\n      err instanceof FileNotFoundError ||\n      err instanceof StaleFileError\n    ) {\n      return err;\n    }\n    if ((err as { code?: string }).code === \"ENOENT\") return new FileNotFoundError(path);\n    // ENOTDIR (a path component is a file), EACCES, ENOSPC, … — never leak a\n    // raw untyped Node SystemError (Rule 8); wrap with the original as cause.\n    return new FilesystemError(path, err);\n  }\n}\n"]}

package/dist/filesystem/local-filesystem.d.cts

@@ -17,6 +17,24 @@
  * @public
  */
 import { type FileStat, FilesystemBackend, type FilesystemConfig, type WriteFileOptions } from "./types.js";
+/**
+ * {@link FilesystemBackend} over the real filesystem (`node:fs/promises`), with every path resolved
+ * inside `basePath` and escapes rejected.
+ *
+ * ```ts
+ * const fs = new LocalFilesystem({ basePath: "/srv/workspace", readOnly: false });
+ * await fs.writeFile("notes/today.md", "hello");   // /srv/workspace/notes/today.md
+ * await fs.readFile("../../etc/passwd");           // FilesystemSecurityError
+ * ```
+ *
+ * Two things a caller gets wrong. First, the default `basePath` is `process.cwd()` — see
+ * {@link FilesystemConfig}. Second, the security boundary is checked BEFORE the read-only flag, on
+ * purpose: a traversal path against a read-only backend reports the security error, not the
+ * read-only one, so the more serious condition is the one you see.
+ *
+ * Errors are normalised — a missing file, a stale `expectedMtime`, a boundary escape and a write to
+ * a read-only backend each raise their own typed error rather than a raw `ENOENT`-shaped one.
+ */
 export declare class LocalFilesystem extends FilesystemBackend {
     constructor(config?: FilesystemConfig);
     readFile(path: string): Promise<string>;

package/dist/filesystem/local-filesystem.d.ts

@@ -17,6 +17,24 @@
  * @public
  */
 import { type FileStat, FilesystemBackend, type FilesystemConfig, type WriteFileOptions } from "./types.js";
+/**
+ * {@link FilesystemBackend} over the real filesystem (`node:fs/promises`), with every path resolved
+ * inside `basePath` and escapes rejected.
+ *
+ * ```ts
+ * const fs = new LocalFilesystem({ basePath: "/srv/workspace", readOnly: false });
+ * await fs.writeFile("notes/today.md", "hello");   // /srv/workspace/notes/today.md
+ * await fs.readFile("../../etc/passwd");           // FilesystemSecurityError
+ * ```
+ *
+ * Two things a caller gets wrong. First, the default `basePath` is `process.cwd()` — see
+ * {@link FilesystemConfig}. Second, the security boundary is checked BEFORE the read-only flag, on
+ * purpose: a traversal path against a read-only backend reports the security error, not the
+ * read-only one, so the more serious condition is the one you see.
+ *
+ * Errors are normalised — a missing file, a stale `expectedMtime`, a boundary escape and a write to
+ * a read-only backend each raise their own typed error rather than a raw `ENOENT`-shaped one.
+ */
 export declare class LocalFilesystem extends FilesystemBackend {
     constructor(config?: FilesystemConfig);
     readFile(path: string): Promise<string>;

package/dist/filesystem/types.d.cts

@@ -32,6 +32,18 @@ export interface WriteFileOptions {
      */
     readonly expectedMtime?: number;
 }
+/**
+ * Construction options shared by every {@link FilesystemBackend}.
+ *
+ * `basePath` is resolved ONCE, at construction, and defaults to `process.cwd()`. Omitting it does
+ * not mean "no boundary" — it means the boundary is wherever the process happened to be standing,
+ * which is rarely what the caller intended and never what a reviewer can verify. Pass it explicitly.
+ *
+ * The boundary rejects lexical traversal AND symlink escape, raising
+ * {@link FilesystemSecurityError}. It is a boundary, not a sandbox: it constrains paths this
+ * backend resolves, and constrains nothing else the process can do. For untrusted code, run it in a
+ * container or VM.
+ */
 export interface FilesystemConfig {
     /** Boundary root. Every path is resolved within it; escapes are rejected. */
     readonly basePath?: string;

package/dist/filesystem/types.d.ts

@@ -32,6 +32,18 @@ export interface WriteFileOptions {
      */
     readonly expectedMtime?: number;
 }
+/**
+ * Construction options shared by every {@link FilesystemBackend}.
+ *
+ * `basePath` is resolved ONCE, at construction, and defaults to `process.cwd()`. Omitting it does
+ * not mean "no boundary" — it means the boundary is wherever the process happened to be standing,
+ * which is rarely what the caller intended and never what a reviewer can verify. Pass it explicitly.
+ *
+ * The boundary rejects lexical traversal AND symlink escape, raising
+ * {@link FilesystemSecurityError}. It is a boundary, not a sandbox: it constrains paths this
+ * backend resolves, and constrains nothing else the process can do. For untrusted code, run it in a
+ * container or VM.
+ */
 export interface FilesystemConfig {
     /** Boundary root. Every path is resolved within it; escapes are rejected. */
     readonly basePath?: string;

package/dist/fs-session-store-3MOJQGP2.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkYPJ5NH5N_cjs = require('./chunk-YPJ5NH5N.cjs');
+require('./chunk-4I55V454.cjs');
+require('./chunk-JHPGF3FP.cjs');
+require('./chunk-2ADR2GSO.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-I6TGFUCO.cjs');
+require('./chunk-K3FW2XZD.cjs');
+require('./chunk-JTB5Q42C.cjs');
+require('./chunk-NUKRL3I6.cjs');
+
+
+
+Object.defineProperty(exports, "FsSessionStore", {
+  enumerable: true,
+  get: function () { return chunkYPJ5NH5N_cjs.FsSessionStore; }
+});
+//# sourceMappingURL=fs-session-store-3MOJQGP2.cjs.map
+//# sourceMappingURL=fs-session-store-3MOJQGP2.cjs.map

package/dist/{fs-session-store-VXXDIBGM.cjs.map → fs-session-store-3MOJQGP2.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"fs-session-store-VXXDIBGM.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"fs-session-store-3MOJQGP2.cjs"}

package/dist/fs-session-store-IN7JTTXD.js

@@ -0,0 +1,11 @@
+export { FsSessionStore } from './chunk-GJ6RK75E.js';
+import './chunk-44JAAH4X.js';
+import './chunk-DZBSJX6J.js';
+import './chunk-CV7XMBHP.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-VF7EWVDG.js';
+import './chunk-IDCKSLYH.js';
+import './chunk-T7XEKOVW.js';
+import './chunk-T7O6K6PX.js';
+//# sourceMappingURL=fs-session-store-IN7JTTXD.js.map
+//# sourceMappingURL=fs-session-store-IN7JTTXD.js.map

package/dist/{fs-session-store-LIKYT24K.js.map → fs-session-store-IN7JTTXD.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"fs-session-store-LIKYT24K.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"fs-session-store-IN7JTTXD.js"}

package/dist/generate-object-N5MDZUJI.js

@@ -0,0 +1,8 @@
+export { GenerateObjectError, generateObjectImpl } from './chunk-QRSUA2CV.js';
+import './chunk-AEOZTXVW.js';
+import './chunk-4VPXM6UU.js';
+import './chunk-IDCKSLYH.js';
+import './chunk-T7XEKOVW.js';
+import './chunk-T7O6K6PX.js';
+//# sourceMappingURL=generate-object-N5MDZUJI.js.map
+//# sourceMappingURL=generate-object-N5MDZUJI.js.map

package/dist/{generate-object-TVQCW2IZ.js.map → generate-object-N5MDZUJI.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"generate-object-TVQCW2IZ.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"generate-object-N5MDZUJI.js"}

package/dist/generate-object-PGSP5U7N.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+var chunkP6A3M6VD_cjs = require('./chunk-P6A3M6VD.cjs');
+require('./chunk-QDED6YO6.cjs');
+require('./chunk-WJVHMTKB.cjs');
+require('./chunk-K3FW2XZD.cjs');
+require('./chunk-JTB5Q42C.cjs');
+require('./chunk-NUKRL3I6.cjs');
+
+
+
+Object.defineProperty(exports, "GenerateObjectError", {
+  enumerable: true,
+  get: function () { return chunkP6A3M6VD_cjs.GenerateObjectError; }
+});
+Object.defineProperty(exports, "generateObjectImpl", {
+  enumerable: true,
+  get: function () { return chunkP6A3M6VD_cjs.generateObjectImpl; }
+});
+//# sourceMappingURL=generate-object-PGSP5U7N.cjs.map
+//# sourceMappingURL=generate-object-PGSP5U7N.cjs.map

package/dist/{generate-object-E465DX5I.cjs.map → generate-object-PGSP5U7N.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"generate-object-E465DX5I.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"generate-object-PGSP5U7N.cjs"}

package/dist/generate-object.d.ts

@@ -89,5 +89,25 @@ interface GenerateObjectDeps {
     /** Hard-delete the transient agent from the registry after dispose. */
     delete: (agentId: string) => Promise<void>;
 }
+/**
+ * Implementation of `Agent.generateObject`. Receives the `Agent.create`
+ * factory as a callback to keep the dependency graph acyclic (mirrors the
+ * AgentBuilder pattern in D25 / agent.ts injection).
+ *
+ * Algorithm:
+ *   1. Convert the consumer's Zod schema to JSON Schema.
+ *   2. Build a single synthetic `output` CustomTool whose handler captures
+ *      the raw input and short-circuits the agent loop. The handler
+ *      THROWS a sentinel so the loop terminates immediately without a
+ *      second LLM round-trip.
+ *   3. Create ONE transient agent (per the entire generateObject call,
+ *      not per retry — EC-3). Each retry re-sends through the same agent,
+ *      driving fresh LLM rounds.
+ *   4. On each attempt, send a wrapper prompt instructing the model to
+ *      call the `output` tool. Capture the raw input via the sentinel.
+ *   5. Parse the raw input via schema.parse. On success, return typed.
+ *      On failure, retry until the budget is exhausted.
+ *   6. Always dispose the transient agent in `finally`.
+ */
 export declare function generateObjectImpl<T extends ZodType>(options: GenerateObjectOptions<T>, deps: GenerateObjectDeps): Promise<GenerateObjectResult<ZodNamespace.infer<T>>>;
 export {};

package/dist/index-manager-NG5YENWO.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+var chunk5UOVYM3P_cjs = require('./chunk-5UOVYM3P.cjs');
+require('./chunk-GHX4P3V2.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-R3UPQFKK.cjs');
+require('./chunk-VKJ7V7EB.cjs');
+require('./chunk-SKXBJ2NU.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-I6TGFUCO.cjs');
+require('./chunk-K3FW2XZD.cjs');
+require('./chunk-JTB5Q42C.cjs');
+require('./chunk-NUKRL3I6.cjs');
+
+
+
+Object.defineProperty(exports, "IndexManager", {
+  enumerable: true,
+  get: function () { return chunk5UOVYM3P_cjs.IndexManager; }
+});
+//# sourceMappingURL=index-manager-NG5YENWO.cjs.map
+//# sourceMappingURL=index-manager-NG5YENWO.cjs.map

package/dist/{index-manager-HGGL4DD5.cjs.map → index-manager-NG5YENWO.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index-manager-HGGL4DD5.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index-manager-NG5YENWO.cjs"}

package/dist/index-manager-ZMRJ6ZII.js

@@ -0,0 +1,13 @@
+export { IndexManager } from './chunk-DAPSQZT4.js';
+import './chunk-H73MEMQB.js';
+import './chunk-FD2UT76F.js';
+import './chunk-QARJGQSA.js';
+import './chunk-RIAM53CP.js';
+import './chunk-CQ2TQ32Y.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-VF7EWVDG.js';
+import './chunk-IDCKSLYH.js';
+import './chunk-T7XEKOVW.js';
+import './chunk-T7O6K6PX.js';
+//# sourceMappingURL=index-manager-ZMRJ6ZII.js.map
+//# sourceMappingURL=index-manager-ZMRJ6ZII.js.map

package/dist/{index-manager-EA6FGIQG.js.map → index-manager-ZMRJ6ZII.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index-manager-EA6FGIQG.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index-manager-ZMRJ6ZII.js"}