@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/filesystem/index.js

@@ -1,62 +1,60 @@
-import { safePathJoin, PathTraversalError, assertNoSymlinkEscape } from '../chunk-HS7AVXTF.js';
-import '../chunk-RIAM53CP.js';
-import '../chunk-ZZMZWBR6.js';
-import '../chunk-D4CUGAKZ.js';
-import '../chunk-XEQ3TM66.js';
+import { safePathJoin, PathTraversalError, assertNoSymlinkEscape } from '../chunk-EH6XD3FY.js';
+import '../chunk-UKMBRMGT.js';
+import { TheokitAgentError } from '../chunk-ALUN2B4W.js';
+import '../chunk-CZJ6Q7CW.js';
 import { readFile, mkdir, writeFile, readdir, stat } from 'fs/promises';
 import { dirname } from 'path';
 
 // src/filesystem/types.ts
-var FilesystemSecurityError = class extends Error {
+var FilesystemSecurityError = class extends TheokitAgentError {
+  name = "FilesystemSecurityError";
   code = "filesystem_security";
   constructor(message) {
-    super(message);
-    this.name = "FilesystemSecurityError";
+    super(message, { code: "filesystem_security", isRetryable: false });
   }
 };
-var FilesystemReadOnlyError = class extends Error {
+var FilesystemReadOnlyError = class extends TheokitAgentError {
+  name = "FilesystemReadOnlyError";
   code = "filesystem_readonly";
   constructor(message) {
-    super(message);
-    this.name = "FilesystemReadOnlyError";
+    super(message, { code: "filesystem_readonly", isRetryable: false });
   }
 };
-var FileNotFoundError = class extends Error {
+var FileNotFoundError = class extends TheokitAgentError {
   constructor(path) {
-    super(`File not found: ${path}`);
+    super(`File not found: ${path}`, { code: "filesystem_not_found", isRetryable: false });
     this.path = path;
-    this.name = "FileNotFoundError";
   }
   path;
+  name = "FileNotFoundError";
   code = "filesystem_not_found";
 };
-var FilesystemError = class extends Error {
+var FilesystemError = class extends TheokitAgentError {
   constructor(path, cause) {
     super(
       `Filesystem operation failed on "${path}": ${cause?.message ?? cause}`,
-      {
-        cause
-      }
+      { cause, code: "filesystem_io", isRetryable: true }
     );
     this.path = path;
-    this.name = "FilesystemError";
   }
   path;
+  name = "FilesystemError";
   code = "filesystem_io";
 };
-var StaleFileError = class extends Error {
+var StaleFileError = class extends TheokitAgentError {
   constructor(path, expectedMtime, actualMtime) {
     super(
-      `Stale write to "${path}": expected mtime ${expectedMtime}, found ${actualMtime} (file changed since last read \u2014 re-read before writing)`
+      `Stale write to "${path}": expected mtime ${expectedMtime}, found ${actualMtime} (file changed since last read \u2014 re-read before writing)`,
+      { code: "filesystem_stale", isRetryable: false }
     );
     this.path = path;
     this.expectedMtime = expectedMtime;
     this.actualMtime = actualMtime;
-    this.name = "StaleFileError";
   }
   path;
   expectedMtime;
   actualMtime;
+  name = "StaleFileError";
   code = "filesystem_stale";
 };
 var FilesystemBackend = class {

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":"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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"]}
+{"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\nimport { TheokitAgentError } from \"../errors.js\";\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 TheokitAgentError {\n  override readonly name = \"FilesystemSecurityError\";\n  override readonly code = \"filesystem_security\" as const;\n  constructor(message: string) {\n    // not retryable: a path outside the root stays outside it\n    super(message, { code: \"filesystem_security\", isRetryable: false });\n  }\n}\n\n/** A write was attempted on a read-only backend. */\nexport class FilesystemReadOnlyError extends TheokitAgentError {\n  override readonly name = \"FilesystemReadOnlyError\";\n  override readonly code = \"filesystem_readonly\" as const;\n  constructor(message: string) {\n    // not retryable: the backend does not become writable\n    super(message, { code: \"filesystem_readonly\", isRetryable: false });\n  }\n}\n\n/** A read/stat targeted a path that does not exist. */\nexport class FileNotFoundError extends TheokitAgentError {\n  override readonly name = \"FileNotFoundError\";\n  override readonly code = \"filesystem_not_found\" as const;\n  constructor(public readonly path: string) {\n    // not retryable: a missing file is a fact about the request, not a transient condition\n    super(`File not found: ${path}`, { code: \"filesystem_not_found\", isRetryable: false });\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 TheokitAgentError {\n  override readonly name = \"FilesystemError\";\n  override readonly code = \"filesystem_io\" as const;\n  constructor(\n    public readonly path: string,\n    cause: unknown,\n  ) {\n    // retryable: a lower-level I/O failure CAN be transient — EBUSY, EAGAIN, a full disk that frees\n    super(\n      `Filesystem operation failed on \"${path}\": ${(cause as { message?: string })?.message ?? cause}`,\n      { cause, code: \"filesystem_io\", isRetryable: true },\n    );\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 TheokitAgentError {\n  override readonly name = \"StaleFileError\";\n  override 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    // not retryable: the caller must re-read first; retrying the same write reproduces the conflict\n    super(\n      `Stale write to \"${path}\": expected mtime ${expectedMtime}, found ${actualMtime} ` +\n        `(file changed since last read — re-read before writing)`,\n      { code: \"filesystem_stale\", isRetryable: false },\n    );\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/types.d.cts

@@ -17,6 +17,7 @@
  *
  * @public
  */
+import { TheokitAgentError } from "../errors.js";
 /** Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32). */
 export interface FileStat {
     readonly size: number;
@@ -51,18 +52,21 @@ export interface FilesystemConfig {
     readonly readOnly?: boolean;
 }
 /** A path escaped the backend's `basePath` (traversal or symlink). */
-export declare class FilesystemSecurityError extends Error {
+export declare class FilesystemSecurityError extends TheokitAgentError {
+    readonly name = "FilesystemSecurityError";
     readonly code: "filesystem_security";
     constructor(message: string);
 }
 /** A write was attempted on a read-only backend. */
-export declare class FilesystemReadOnlyError extends Error {
+export declare class FilesystemReadOnlyError extends TheokitAgentError {
+    readonly name = "FilesystemReadOnlyError";
     readonly code: "filesystem_readonly";
     constructor(message: string);
 }
 /** A read/stat targeted a path that does not exist. */
-export declare class FileNotFoundError extends Error {
+export declare class FileNotFoundError extends TheokitAgentError {
     readonly path: string;
+    readonly name = "FileNotFoundError";
     readonly code: "filesystem_not_found";
     constructor(path: string);
 }
@@ -72,8 +76,9 @@ export declare class FileNotFoundError extends Error {
  * `EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,
  * untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).
  */
-export declare class FilesystemError extends Error {
+export declare class FilesystemError extends TheokitAgentError {
     readonly path: string;
+    readonly name = "FilesystemError";
     readonly code: "filesystem_io";
     constructor(path: string, cause: unknown);
 }
@@ -81,10 +86,11 @@ export declare class FilesystemError extends Error {
  * SE32 — a write's `expectedMtime` did not match the file's current mtime: the
  * file changed since it was last read, so the write would silently clobber.
  */
-export declare class StaleFileError extends Error {
+export declare class StaleFileError extends TheokitAgentError {
     readonly path: string;
     readonly expectedMtime: number;
     readonly actualMtime: number;
+    readonly name = "StaleFileError";
     readonly code: "filesystem_stale";
     constructor(path: string, expectedMtime: number, actualMtime: number);
 }

package/dist/filesystem/types.d.ts

@@ -17,6 +17,7 @@
  *
  * @public
  */
+import { TheokitAgentError } from "../errors.js";
 /** Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32). */
 export interface FileStat {
     readonly size: number;
@@ -51,18 +52,21 @@ export interface FilesystemConfig {
     readonly readOnly?: boolean;
 }
 /** A path escaped the backend's `basePath` (traversal or symlink). */
-export declare class FilesystemSecurityError extends Error {
+export declare class FilesystemSecurityError extends TheokitAgentError {
+    readonly name = "FilesystemSecurityError";
     readonly code: "filesystem_security";
     constructor(message: string);
 }
 /** A write was attempted on a read-only backend. */
-export declare class FilesystemReadOnlyError extends Error {
+export declare class FilesystemReadOnlyError extends TheokitAgentError {
+    readonly name = "FilesystemReadOnlyError";
     readonly code: "filesystem_readonly";
     constructor(message: string);
 }
 /** A read/stat targeted a path that does not exist. */
-export declare class FileNotFoundError extends Error {
+export declare class FileNotFoundError extends TheokitAgentError {
     readonly path: string;
+    readonly name = "FileNotFoundError";
     readonly code: "filesystem_not_found";
     constructor(path: string);
 }
@@ -72,8 +76,9 @@ export declare class FileNotFoundError extends Error {
  * `EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,
  * untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).
  */
-export declare class FilesystemError extends Error {
+export declare class FilesystemError extends TheokitAgentError {
     readonly path: string;
+    readonly name = "FilesystemError";
     readonly code: "filesystem_io";
     constructor(path: string, cause: unknown);
 }
@@ -81,10 +86,11 @@ export declare class FilesystemError extends Error {
  * SE32 — a write's `expectedMtime` did not match the file's current mtime: the
  * file changed since it was last read, so the write would silently clobber.
  */
-export declare class StaleFileError extends Error {
+export declare class StaleFileError extends TheokitAgentError {
     readonly path: string;
     readonly expectedMtime: number;
     readonly actualMtime: number;
+    readonly name = "StaleFileError";
     readonly code: "filesystem_stale";
     constructor(path: string, expectedMtime: number, actualMtime: number);
 }

package/dist/{fork-agent-RSV4E3EA.js → fork-agent-S2EPIML7.js}

@@ -1,5 +1,5 @@
 import { isCodePlugin } from './chunk-2SFBB54R.js';
-import { withToolWhitelist } from './chunk-7AD3ZTZL.js';
+import { withToolWhitelist } from './chunk-SAGRF4IB.js';
 
 // src/internal/runtime/lifecycle/fork-agent.ts
 function filterMemoryPlugins(plugins) {
@@ -57,5 +57,5 @@ function extractUsage(result) {
 }
 
 export { filterMemoryPlugins, forkAgentImpl };
-//# sourceMappingURL=fork-agent-RSV4E3EA.js.map
-//# sourceMappingURL=fork-agent-RSV4E3EA.js.map
+//# sourceMappingURL=fork-agent-S2EPIML7.js.map
+//# sourceMappingURL=fork-agent-S2EPIML7.js.map

package/dist/fork-agent-S2EPIML7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/lifecycle/fork-agent.ts"],"names":[],"mappings":";;;;AA0DO,SAAS,oBACd,OAAA,EACwD;AACxD,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,OAAO,GAAG,OAAO,MAAA;AACpC,EAAA,MAAM,aAAa,OAAA,CAAQ,MAAA;AAAA,IACzB,CAAC,CAAA,KAAgD,YAAA,CAAa,CAAC,CAAA,IAAK,EAAE,IAAA,KAAS;AAAA,GACjF;AACA,EAAA,OAAO,UAAA,CAAW,MAAA,GAAS,CAAA,GAAI,UAAA,GAAa,MAAA;AAC9C;AASA,eAAsB,aAAA,CACpB,MAAA,EACA,OAAA,EACA,IAAA,EACqB;AACrB,EAAA,MAAM,gBAAgB,MAAA,CAAO,OAAA;AAG7B,EAAA,MAAM,aAAA,GAAgB,mBAAA,CAAoB,aAAA,CAAc,OAAkB,CAAA;AAE1E,EAAA,MAAM,WAAA,GAA4B;AAAA,IAChC,GAAG,aAAA;AAAA;AAAA,IAEH,OAAA,EAAS,MAAA;AAAA,IACT,MAAA,EAAQ,MAAA;AAAA;AAAA,IAER,OAAA,EAAS,aAAA;AAAA,IACT,YAAA,EACE,QAAQ,YAAA,KACP,OAAO,cAAc,YAAA,KAAiB,QAAA,GAAW,cAAc,YAAA,GAAe,MAAA,CAAA;AAAA,IACjF,QAAA,EAAU;AAAA,MACR,GAAI,aAAA,CAAc,QAAA,IAAY,EAAC;AAAA,MAC/B,UAAA,EAAY,QAAQ,UAAA,IAAc,MAAA;AAAA,MAClC,eAAe,MAAA,CAAO;AAAA;AACxB,GACF;AAEA,EAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,MAAA,CAAO,WAAW,CAAA;AAC1C,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,iBAAA,CAAkB,OAAA,CAAQ,YAAA,EAAc,YAAY;AAC/D,MAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,IAAA,CAAK,QAAQ,MAAM,CAAA;AAC1C,MAAA,MAAM,MAAA,GAAS,MAAM,GAAA,CAAI,IAAA,EAAK;AAC9B,MAAA,OAAO;AAAA,QACL,QAAQ,MAAA,CAAO,MAAA;AAAA,QACf,WAAW,EAAC;AAAA,QACZ,KAAA,EAAO,aAAa,MAAM;AAAA,OAC5B;AAAA,IACF,CAAC,CAAA;AAAA,EACH,CAAA,SAAE;AACA,IAAA,MAAM,KAAK,OAAA,EAAQ;AAAA,EACrB;AACF;AAEA,SAAS,aAAa,MAAA,EAAgE;AACpF,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,KAAW,IAAA,EAAM;AACjD,IAAA,OAAO,EAAE,WAAA,EAAa,CAAA,EAAG,YAAA,EAAc,CAAA,EAAE;AAAA,EAC3C;AACA,EAAA,MAAM,QAAS,MAAA,CAA+B,KAAA;AAC9C,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,IAAA,EAAM;AAC/C,IAAA,OAAO,EAAE,WAAA,EAAa,CAAA,EAAG,YAAA,EAAc,CAAA,EAAE;AAAA,EAC3C;AACA,EAAA,MAAM,CAAA,GAAI,KAAA;AACV,EAAA,OAAO;AAAA,IACL,aAAa,OAAO,CAAA,CAAE,WAAA,KAAgB,QAAA,GAAW,EAAE,WAAA,GAAc,CAAA;AAAA,IACjE,cAAc,OAAO,CAAA,CAAE,YAAA,KAAiB,QAAA,GAAW,EAAE,YAAA,GAAe;AAAA,GACtE;AACF","file":"fork-agent-S2EPIML7.js","sourcesContent":["/**\n * Fork agent primitive (T1.2, ADRs D110-D114).\n *\n * `forkAgentImpl(parent, options, deps)` creates a short-lived auxiliary\n * agent that inherits the parent's credentials and **byte-identical**\n * system prompt (D112 — cache hit) but runs with a reduced tool\n * whitelist enforced via `AsyncLocalStorage` (D111). Memory plugins\n * (`kind: \"memory\"`) are preserved so memory writes carry provenance\n * (D114 + EC-B fix); general/model-provider plugins are dropped because\n * the fork has its own `PluginManager.initialize` and double-registering\n * is redundant.\n *\n * @internal\n */\n\nimport type { AgentOptions, SDKAgent } from \"../../../types/agent.js\";\n// ForkOptions/ForkResult live in the leaf `types/fork.ts` (arch-review ADR 0001)\n// so `types/agent.ts` can reference them without importing this implementation\n// module (which would form a type-only cycle). Re-exported here for back-compat.\nimport type { ForkOptions, ForkResult } from \"../../../types/fork.js\";\nimport { withToolWhitelist } from \"../../concurrency/async-local-storage.js\";\nimport { isCodePlugin } from \"../../plugins/plugin-guards.js\";\nimport type { Plugin } from \"../../plugins/types.js\";\n\nexport type { ForkOptions, ForkResult } from \"../../../types/fork.js\";\n\n/**\n * Injected dependency contract — keeps fork-agent acyclic with `Agent`.\n *\n * @internal\n */\nexport interface ForkDeps {\n  create: (options: AgentOptions) => Promise<SDKAgent>;\n}\n\n/**\n * Parent shape required by the fork. Any `SDKAgent` plus a `readonly options`\n * accessor (LocalAgent exposes it via the public getter added in T4.3).\n *\n * @internal\n */\nexport interface ForkParent {\n  readonly agentId: string;\n  readonly options: AgentOptions;\n}\n\n/**\n * Preserve memory plugins (kind: \"memory\") so the fork can write memory\n * with provenance (D114). Drop other kinds — the fork's own\n * `PluginManager` will re-initialize from `forkOptions.plugins`, and\n * general/model-provider re-registration is redundant.\n *\n * EC-B (edge-case review): without this filter, every fork would lose\n * memory writeability when callers use the v1.3 `plugins: Plugin[]`\n * shape (D98).\n *\n * @internal\n */\nexport function filterMemoryPlugins(\n  plugins: unknown,\n): Array<Extract<Plugin, { kind: \"memory\" }>> | undefined {\n  if (!Array.isArray(plugins)) return undefined;\n  const memoryOnly = plugins.filter(\n    (p): p is Extract<Plugin, { kind: \"memory\" }> => isCodePlugin(p) && p.kind === \"memory\",\n  );\n  return memoryOnly.length > 0 ? memoryOnly : undefined;\n}\n\n/**\n * Run a forked sub-agent. Inherits parent credentials and system prompt\n * byte-identical (D112), enforces `allowedTools` via AsyncLocalStorage\n * (D111), disposes the auxiliary agent in `finally` regardless of outcome.\n *\n * @internal\n */\nexport async function forkAgentImpl(\n  parent: ForkParent,\n  options: ForkOptions,\n  deps: ForkDeps,\n): Promise<ForkResult> {\n  const parentOptions = parent.options;\n  // EC-B fix: preserve memory plugins so fork can attribute memory writes;\n  // drop general/model-provider plugins (redundant per-fork re-init).\n  const memoryPlugins = filterMemoryPlugins(parentOptions.plugins as unknown);\n\n  const forkOptions: AgentOptions = {\n    ...parentOptions,\n    // Strip fields that don't survive fork:\n    agentId: undefined,\n    skills: undefined,\n    // Override:\n    plugins: memoryPlugins as unknown as AgentOptions[\"plugins\"],\n    systemPrompt:\n      options.systemPrompt ??\n      (typeof parentOptions.systemPrompt === \"string\" ? parentOptions.systemPrompt : undefined),\n    metadata: {\n      ...(parentOptions.metadata ?? {}),\n      forkOrigin: options.forkOrigin ?? \"fork\",\n      parentAgentId: parent.agentId,\n    },\n  };\n\n  const fork = await deps.create(forkOptions);\n  try {\n    return await withToolWhitelist(options.allowedTools, async () => {\n      const run = await fork.send(options.prompt);\n      const result = await run.wait();\n      return {\n        result: result.result,\n        toolCalls: [],\n        usage: extractUsage(result),\n      };\n    });\n  } finally {\n    await fork.dispose();\n  }\n}\n\nfunction extractUsage(result: unknown): { inputTokens: number; outputTokens: number } {\n  if (typeof result !== \"object\" || result === null) {\n    return { inputTokens: 0, outputTokens: 0 };\n  }\n  const usage = (result as { usage?: unknown }).usage;\n  if (typeof usage !== \"object\" || usage === null) {\n    return { inputTokens: 0, outputTokens: 0 };\n  }\n  const u = usage as { inputTokens?: number; outputTokens?: number };\n  return {\n    inputTokens: typeof u.inputTokens === \"number\" ? u.inputTokens : 0,\n    outputTokens: typeof u.outputTokens === \"number\" ? u.outputTokens : 0,\n  };\n}\n"]}

package/dist/{fork-agent-Y2IK2RYU.cjs → fork-agent-WAEQI2DL.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkBV2MWEMV_cjs = require('./chunk-BV2MWEMV.cjs');
-var chunkVJ26EKGJ_cjs = require('./chunk-VJ26EKGJ.cjs');
+var chunkIJ7M6GOG_cjs = require('./chunk-IJ7M6GOG.cjs');
 
 // src/internal/runtime/lifecycle/fork-agent.ts
 function filterMemoryPlugins(plugins) {
@@ -30,7 +30,7 @@ async function forkAgentImpl(parent, options, deps) {
   };
   const fork = await deps.create(forkOptions);
   try {
-    return await chunkVJ26EKGJ_cjs.withToolWhitelist(options.allowedTools, async () => {
+    return await chunkIJ7M6GOG_cjs.withToolWhitelist(options.allowedTools, async () => {
       const run = await fork.send(options.prompt);
       const result = await run.wait();
       return {
@@ -60,5 +60,5 @@ function extractUsage(result) {
 
 exports.filterMemoryPlugins = filterMemoryPlugins;
 exports.forkAgentImpl = forkAgentImpl;
-//# sourceMappingURL=fork-agent-Y2IK2RYU.cjs.map
-//# sourceMappingURL=fork-agent-Y2IK2RYU.cjs.map
+//# sourceMappingURL=fork-agent-WAEQI2DL.cjs.map
+//# sourceMappingURL=fork-agent-WAEQI2DL.cjs.map

package/dist/fork-agent-WAEQI2DL.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/lifecycle/fork-agent.ts"],"names":["isCodePlugin","withToolWhitelist"],"mappings":";;;;;;AA0DO,SAAS,oBACd,OAAA,EACwD;AACxD,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,OAAO,GAAG,OAAO,MAAA;AACpC,EAAA,MAAM,aAAa,OAAA,CAAQ,MAAA;AAAA,IACzB,CAAC,CAAA,KAAgDA,8BAAA,CAAa,CAAC,CAAA,IAAK,EAAE,IAAA,KAAS;AAAA,GACjF;AACA,EAAA,OAAO,UAAA,CAAW,MAAA,GAAS,CAAA,GAAI,UAAA,GAAa,MAAA;AAC9C;AASA,eAAsB,aAAA,CACpB,MAAA,EACA,OAAA,EACA,IAAA,EACqB;AACrB,EAAA,MAAM,gBAAgB,MAAA,CAAO,OAAA;AAG7B,EAAA,MAAM,aAAA,GAAgB,mBAAA,CAAoB,aAAA,CAAc,OAAkB,CAAA;AAE1E,EAAA,MAAM,WAAA,GAA4B;AAAA,IAChC,GAAG,aAAA;AAAA;AAAA,IAEH,OAAA,EAAS,MAAA;AAAA,IACT,MAAA,EAAQ,MAAA;AAAA;AAAA,IAER,OAAA,EAAS,aAAA;AAAA,IACT,YAAA,EACE,QAAQ,YAAA,KACP,OAAO,cAAc,YAAA,KAAiB,QAAA,GAAW,cAAc,YAAA,GAAe,MAAA,CAAA;AAAA,IACjF,QAAA,EAAU;AAAA,MACR,GAAI,aAAA,CAAc,QAAA,IAAY,EAAC;AAAA,MAC/B,UAAA,EAAY,QAAQ,UAAA,IAAc,MAAA;AAAA,MAClC,eAAe,MAAA,CAAO;AAAA;AACxB,GACF;AAEA,EAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,MAAA,CAAO,WAAW,CAAA;AAC1C,EAAA,IAAI;AACF,IAAA,OAAO,MAAMC,mCAAA,CAAkB,OAAA,CAAQ,YAAA,EAAc,YAAY;AAC/D,MAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,IAAA,CAAK,QAAQ,MAAM,CAAA;AAC1C,MAAA,MAAM,MAAA,GAAS,MAAM,GAAA,CAAI,IAAA,EAAK;AAC9B,MAAA,OAAO;AAAA,QACL,QAAQ,MAAA,CAAO,MAAA;AAAA,QACf,WAAW,EAAC;AAAA,QACZ,KAAA,EAAO,aAAa,MAAM;AAAA,OAC5B;AAAA,IACF,CAAC,CAAA;AAAA,EACH,CAAA,SAAE;AACA,IAAA,MAAM,KAAK,OAAA,EAAQ;AAAA,EACrB;AACF;AAEA,SAAS,aAAa,MAAA,EAAgE;AACpF,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,KAAW,IAAA,EAAM;AACjD,IAAA,OAAO,EAAE,WAAA,EAAa,CAAA,EAAG,YAAA,EAAc,CAAA,EAAE;AAAA,EAC3C;AACA,EAAA,MAAM,QAAS,MAAA,CAA+B,KAAA;AAC9C,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,IAAA,EAAM;AAC/C,IAAA,OAAO,EAAE,WAAA,EAAa,CAAA,EAAG,YAAA,EAAc,CAAA,EAAE;AAAA,EAC3C;AACA,EAAA,MAAM,CAAA,GAAI,KAAA;AACV,EAAA,OAAO;AAAA,IACL,aAAa,OAAO,CAAA,CAAE,WAAA,KAAgB,QAAA,GAAW,EAAE,WAAA,GAAc,CAAA;AAAA,IACjE,cAAc,OAAO,CAAA,CAAE,YAAA,KAAiB,QAAA,GAAW,EAAE,YAAA,GAAe;AAAA,GACtE;AACF","file":"fork-agent-WAEQI2DL.cjs","sourcesContent":["/**\n * Fork agent primitive (T1.2, ADRs D110-D114).\n *\n * `forkAgentImpl(parent, options, deps)` creates a short-lived auxiliary\n * agent that inherits the parent's credentials and **byte-identical**\n * system prompt (D112 — cache hit) but runs with a reduced tool\n * whitelist enforced via `AsyncLocalStorage` (D111). Memory plugins\n * (`kind: \"memory\"`) are preserved so memory writes carry provenance\n * (D114 + EC-B fix); general/model-provider plugins are dropped because\n * the fork has its own `PluginManager.initialize` and double-registering\n * is redundant.\n *\n * @internal\n */\n\nimport type { AgentOptions, SDKAgent } from \"../../../types/agent.js\";\n// ForkOptions/ForkResult live in the leaf `types/fork.ts` (arch-review ADR 0001)\n// so `types/agent.ts` can reference them without importing this implementation\n// module (which would form a type-only cycle). Re-exported here for back-compat.\nimport type { ForkOptions, ForkResult } from \"../../../types/fork.js\";\nimport { withToolWhitelist } from \"../../concurrency/async-local-storage.js\";\nimport { isCodePlugin } from \"../../plugins/plugin-guards.js\";\nimport type { Plugin } from \"../../plugins/types.js\";\n\nexport type { ForkOptions, ForkResult } from \"../../../types/fork.js\";\n\n/**\n * Injected dependency contract — keeps fork-agent acyclic with `Agent`.\n *\n * @internal\n */\nexport interface ForkDeps {\n  create: (options: AgentOptions) => Promise<SDKAgent>;\n}\n\n/**\n * Parent shape required by the fork. Any `SDKAgent` plus a `readonly options`\n * accessor (LocalAgent exposes it via the public getter added in T4.3).\n *\n * @internal\n */\nexport interface ForkParent {\n  readonly agentId: string;\n  readonly options: AgentOptions;\n}\n\n/**\n * Preserve memory plugins (kind: \"memory\") so the fork can write memory\n * with provenance (D114). Drop other kinds — the fork's own\n * `PluginManager` will re-initialize from `forkOptions.plugins`, and\n * general/model-provider re-registration is redundant.\n *\n * EC-B (edge-case review): without this filter, every fork would lose\n * memory writeability when callers use the v1.3 `plugins: Plugin[]`\n * shape (D98).\n *\n * @internal\n */\nexport function filterMemoryPlugins(\n  plugins: unknown,\n): Array<Extract<Plugin, { kind: \"memory\" }>> | undefined {\n  if (!Array.isArray(plugins)) return undefined;\n  const memoryOnly = plugins.filter(\n    (p): p is Extract<Plugin, { kind: \"memory\" }> => isCodePlugin(p) && p.kind === \"memory\",\n  );\n  return memoryOnly.length > 0 ? memoryOnly : undefined;\n}\n\n/**\n * Run a forked sub-agent. Inherits parent credentials and system prompt\n * byte-identical (D112), enforces `allowedTools` via AsyncLocalStorage\n * (D111), disposes the auxiliary agent in `finally` regardless of outcome.\n *\n * @internal\n */\nexport async function forkAgentImpl(\n  parent: ForkParent,\n  options: ForkOptions,\n  deps: ForkDeps,\n): Promise<ForkResult> {\n  const parentOptions = parent.options;\n  // EC-B fix: preserve memory plugins so fork can attribute memory writes;\n  // drop general/model-provider plugins (redundant per-fork re-init).\n  const memoryPlugins = filterMemoryPlugins(parentOptions.plugins as unknown);\n\n  const forkOptions: AgentOptions = {\n    ...parentOptions,\n    // Strip fields that don't survive fork:\n    agentId: undefined,\n    skills: undefined,\n    // Override:\n    plugins: memoryPlugins as unknown as AgentOptions[\"plugins\"],\n    systemPrompt:\n      options.systemPrompt ??\n      (typeof parentOptions.systemPrompt === \"string\" ? parentOptions.systemPrompt : undefined),\n    metadata: {\n      ...(parentOptions.metadata ?? {}),\n      forkOrigin: options.forkOrigin ?? \"fork\",\n      parentAgentId: parent.agentId,\n    },\n  };\n\n  const fork = await deps.create(forkOptions);\n  try {\n    return await withToolWhitelist(options.allowedTools, async () => {\n      const run = await fork.send(options.prompt);\n      const result = await run.wait();\n      return {\n        result: result.result,\n        toolCalls: [],\n        usage: extractUsage(result),\n      };\n    });\n  } finally {\n    await fork.dispose();\n  }\n}\n\nfunction extractUsage(result: unknown): { inputTokens: number; outputTokens: number } {\n  if (typeof result !== \"object\" || result === null) {\n    return { inputTokens: 0, outputTokens: 0 };\n  }\n  const usage = (result as { usage?: unknown }).usage;\n  if (typeof usage !== \"object\" || usage === null) {\n    return { inputTokens: 0, outputTokens: 0 };\n  }\n  const u = usage as { inputTokens?: number; outputTokens?: number };\n  return {\n    inputTokens: typeof u.inputTokens === \"number\" ? u.inputTokens : 0,\n    outputTokens: typeof u.outputTokens === \"number\" ? u.outputTokens : 0,\n  };\n}\n"]}

package/dist/fs-session-store-77JU46UZ.js

@@ -0,0 +1,10 @@
+export { FsSessionStore } from './chunk-AAEZSPTC.js';
+import './chunk-VE6DFSKU.js';
+import './chunk-JOFVLOFY.js';
+import './chunk-TA3K7SBK.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-3JHIFQ4I.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=fs-session-store-77JU46UZ.js.map
+//# sourceMappingURL=fs-session-store-77JU46UZ.js.map

package/dist/{fs-session-store-NM6YSTE2.js.map → fs-session-store-77JU46UZ.js.map}

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

package/dist/fs-session-store-E4U3P56L.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+var chunk7FDKWDA2_cjs = require('./chunk-7FDKWDA2.cjs');
+require('./chunk-Z3NTRKIC.cjs');
+require('./chunk-GZV6AVRL.cjs');
+require('./chunk-BJUJT5ED.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-JLRLCBJ4.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "FsSessionStore", {
+  enumerable: true,
+  get: function () { return chunk7FDKWDA2_cjs.FsSessionStore; }
+});
+//# sourceMappingURL=fs-session-store-E4U3P56L.cjs.map
+//# sourceMappingURL=fs-session-store-E4U3P56L.cjs.map

package/dist/{fs-session-store-4PIHT5UX.cjs.map → fs-session-store-E4U3P56L.cjs.map}

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

package/dist/generate-object-BXV7BZRP.js

@@ -0,0 +1,7 @@
+export { GenerateObjectError, generateObjectImpl } from './chunk-44I6UYVH.js';
+import './chunk-47TF32NQ.js';
+import './chunk-7I5Z3UBJ.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=generate-object-BXV7BZRP.js.map
+//# sourceMappingURL=generate-object-BXV7BZRP.js.map

package/dist/{generate-object-GUNAUVBX.js.map → generate-object-BXV7BZRP.js.map}

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

package/dist/generate-object-YBI2TDJ3.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkQWD4RDZ3_cjs = require('./chunk-QWD4RDZ3.cjs');
+require('./chunk-7JJ3A6AT.cjs');
+require('./chunk-AA27GEYS.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "GenerateObjectError", {
+  enumerable: true,
+  get: function () { return chunkQWD4RDZ3_cjs.GenerateObjectError; }
+});
+Object.defineProperty(exports, "generateObjectImpl", {
+  enumerable: true,
+  get: function () { return chunkQWD4RDZ3_cjs.generateObjectImpl; }
+});
+//# sourceMappingURL=generate-object-YBI2TDJ3.cjs.map
+//# sourceMappingURL=generate-object-YBI2TDJ3.cjs.map

package/dist/{generate-object-R7HTMW7F.cjs.map → generate-object-YBI2TDJ3.cjs.map}

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

package/dist/generate-object.d.ts

@@ -1,4 +1,5 @@
 import type { z as ZodNamespace, ZodType } from "zod";
+import { StructuredOutputError } from "./errors.js";
 import type { AgentOptions, LocalOptions, ModelSelection, SDKAgent } from "./types/agent.js";
 import type { ProviderRoutingSettings } from "./types/providers.js";
 /**
@@ -78,11 +79,8 @@ export interface GenerateObjectResult<T> {
  *
  * @public
  */
-export declare class GenerateObjectError extends Error {
+export declare class GenerateObjectError extends StructuredOutputError {
     readonly name = "GenerateObjectError";
-    readonly code: "no_tool_call" | "parse_failed";
-    readonly cause?: unknown;
-    constructor(code: "no_tool_call" | "parse_failed", message: string, cause?: unknown);
 }
 interface GenerateObjectDeps {
     create: (options: AgentOptions) => Promise<SDKAgent>;

package/dist/index-manager-DXR2RSFI.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+var chunk2NE7DTOK_cjs = require('./chunk-2NE7DTOK.cjs');
+require('./chunk-GHX4P3V2.cjs');
+require('./chunk-LHSWHYF3.cjs');
+require('./chunk-KRD3GQAA.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-LKFET5A3.cjs');
+require('./chunk-7A6535RA.cjs');
+require('./chunk-SA6K24NB.cjs');
+require('./chunk-GZV6AVRL.cjs');
+require('./chunk-A4RAL2ER.cjs');
+require('./chunk-DQZU7JK6.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-JLRLCBJ4.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "IndexManager", {
+  enumerable: true,
+  get: function () { return chunk2NE7DTOK_cjs.IndexManager; }
+});
+//# sourceMappingURL=index-manager-DXR2RSFI.cjs.map
+//# sourceMappingURL=index-manager-DXR2RSFI.cjs.map

package/dist/{index-manager-2SRX45WJ.cjs.map → index-manager-DXR2RSFI.cjs.map}

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

package/dist/index-manager-QH6OXEV5.js

@@ -0,0 +1,17 @@
+export { IndexManager } from './chunk-2ZLVT7H3.js';
+import './chunk-H73MEMQB.js';
+import './chunk-UNK4HNJH.js';
+import './chunk-KVNWIAO4.js';
+import './chunk-FD2UT76F.js';
+import './chunk-WFC26L6Y.js';
+import './chunk-EH6XD3FY.js';
+import './chunk-UKMBRMGT.js';
+import './chunk-JOFVLOFY.js';
+import './chunk-WE22OXQA.js';
+import './chunk-6PWOWXMC.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-3JHIFQ4I.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=index-manager-QH6OXEV5.js.map
+//# sourceMappingURL=index-manager-QH6OXEV5.js.map

package/dist/{index-manager-SP4ISSDX.js.map → index-manager-QH6OXEV5.js.map}

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