@theokit/sdk 4.50.0 → 4.51.0

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\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":";;;;;;;;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"]}

package/dist/{index-manager-YFFEPISE.cjs → index-manager-34ELCOAP.cjs}

@@ -1,12 +1,13 @@
 'use strict';
 
-var chunkGH52NOCL_cjs = require('./chunk-GH52NOCL.cjs');
+var chunkRWMNTFHZ_cjs = require('./chunk-RWMNTFHZ.cjs');
 require('./chunk-2RW7K6FN.cjs');
 require('./chunk-MUUQ2WFJ.cjs');
 require('./chunk-BV42CCRP.cjs');
 require('./chunk-YLQQX5W2.cjs');
 require('./chunk-NETYW4V3.cjs');
-require('./chunk-XA3TSBAH.cjs');
+require('./chunk-XABN5HY6.cjs');
+require('./chunk-VKJ7V7EB.cjs');
 require('./chunk-YULF6FPB.cjs');
 require('./chunk-ZHPET3LZ.cjs');
 
@@ -14,7 +15,7 @@ require('./chunk-ZHPET3LZ.cjs');
 
 Object.defineProperty(exports, "IndexManager", {
   enumerable: true,
-  get: function () { return chunkGH52NOCL_cjs.IndexManager; }
+  get: function () { return chunkRWMNTFHZ_cjs.IndexManager; }
 });
-//# sourceMappingURL=index-manager-YFFEPISE.cjs.map
-//# sourceMappingURL=index-manager-YFFEPISE.cjs.map
+//# sourceMappingURL=index-manager-34ELCOAP.cjs.map
+//# sourceMappingURL=index-manager-34ELCOAP.cjs.map

package/dist/{index-manager-YFFEPISE.cjs.map → index-manager-34ELCOAP.cjs.map}

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

package/dist/index-manager-OMJVYS2U.js

@@ -0,0 +1,12 @@
+export { IndexManager } from './chunk-E54KDYOE.js';
+import './chunk-OXNYIMZZ.js';
+import './chunk-FD2UT76F.js';
+import './chunk-2WB6EIYW.js';
+import './chunk-2XLKLVVR.js';
+import './chunk-VQFSEKU5.js';
+import './chunk-JGYYNDAZ.js';
+import './chunk-RIAM53CP.js';
+import './chunk-MRKSSN36.js';
+import './chunk-PBML2FHN.js';
+//# sourceMappingURL=index-manager-OMJVYS2U.js.map
+//# sourceMappingURL=index-manager-OMJVYS2U.js.map

package/dist/{index-manager-X5IPG2JL.js.map → index-manager-OMJVYS2U.js.map}

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

package/dist/index.cjs

@@ -5,12 +5,12 @@ var chunkUJMEWGO6_cjs = require('./chunk-UJMEWGO6.cjs');
 var chunk57KX5WTP_cjs = require('./chunk-57KX5WTP.cjs');
 var chunkGC44RATP_cjs = require('./chunk-GC44RATP.cjs');
 require('./chunk-WIGJGFH4.cjs');
-var chunkJO76RWCA_cjs = require('./chunk-JO76RWCA.cjs');
+var chunk72HEBGWN_cjs = require('./chunk-72HEBGWN.cjs');
 require('./chunk-RBQYHEZD.cjs');
 require('./chunk-PNVDQL5Y.cjs');
-var chunk74VVGK7P_cjs = require('./chunk-74VVGK7P.cjs');
-var chunkTSK4VVBW_cjs = require('./chunk-TSK4VVBW.cjs');
-require('./chunk-FAUKVJCC.cjs');
+var chunkWUUSAMFC_cjs = require('./chunk-WUUSAMFC.cjs');
+var chunkF7OBYH2X_cjs = require('./chunk-F7OBYH2X.cjs');
+require('./chunk-UQHIEUDY.cjs');
 require('./chunk-BV2MWEMV.cjs');
 var chunkKCQUYQ3V_cjs = require('./chunk-KCQUYQ3V.cjs');
 require('./chunk-BUUUWQMB.cjs');
@@ -19,10 +19,10 @@ var chunkQFFNMJAS_cjs = require('./chunk-QFFNMJAS.cjs');
 require('./chunk-4JBHSLQO.cjs');
 require('./chunk-HLNLYLNN.cjs');
 require('./chunk-FZ4YMZA3.cjs');
-var chunkGH52NOCL_cjs = require('./chunk-GH52NOCL.cjs');
+var chunkRWMNTFHZ_cjs = require('./chunk-RWMNTFHZ.cjs');
 require('./chunk-HECR7KF5.cjs');
 require('./chunk-BBZYXVLZ.cjs');
-require('./chunk-UU7MAO2D.cjs');
+require('./chunk-OKLYRPKL.cjs');
 require('./chunk-6X2HUT4A.cjs');
 require('./chunk-7PESI6YD.cjs');
 require('./chunk-S4Q5OMIK.cjs');
@@ -49,13 +49,14 @@ var chunkVYHJZVL5_cjs = require('./chunk-VYHJZVL5.cjs');
 var chunkGLEKLAUW_cjs = require('./chunk-GLEKLAUW.cjs');
 require('./chunk-4JRRFRV4.cjs');
 require('./chunk-C6Y6CWYD.cjs');
-require('./chunk-64TJCXY5.cjs');
-require('./chunk-XA3TSBAH.cjs');
+require('./chunk-3G6ZDZ6L.cjs');
+require('./chunk-XABN5HY6.cjs');
+require('./chunk-VKJ7V7EB.cjs');
 require('./chunk-BRHRQOJA.cjs');
 var chunkYULF6FPB_cjs = require('./chunk-YULF6FPB.cjs');
 var chunkZHPET3LZ_cjs = require('./chunk-ZHPET3LZ.cjs');
-var zod = require('zod');
 var crypto = require('crypto');
+var zod = require('zod');
 var promises = require('fs/promises');
 var path = require('path');
 var fs = require('fs');
@@ -63,8 +64,8 @@ var fs = require('fs');
 // src/agent-factory.ts
 function createAgentFactory(common) {
   return {
-    forSession: (agentId, overrides) => chunkTSK4VVBW_cjs.Agent.create(mergeAgentOptions(common, overrides, agentId)),
-    getOrCreate: (agentId, overrides) => chunkTSK4VVBW_cjs.Agent.getOrCreate(agentId, mergeAgentOptions(common, overrides, agentId))
+    forSession: (agentId, overrides) => chunkF7OBYH2X_cjs.Agent.create(mergeAgentOptions(common, overrides, agentId)),
+    getOrCreate: (agentId, overrides) => chunkF7OBYH2X_cjs.Agent.getOrCreate(agentId, mergeAgentOptions(common, overrides, agentId))
   };
 }
 function mergeAgentOptions(common, overrides, agentId) {
@@ -103,6 +104,39 @@ var AgentFactory = class {
   }
 };
 
+// src/approval-policy.ts
+var BY_MODE = {
+  ask: { outcome: "ask", reason: "mode-ask" },
+  "never-ask": { outcome: "allow", reason: "mode-never-ask" },
+  "refuse-all": { outcome: "deny", reason: "mode-refuse-all" }
+};
+function decideApproval(input) {
+  const { tool } = input;
+  if ((input.denied ?? []).includes(tool)) {
+    return { outcome: "deny", reason: "explicitly-denied", tool };
+  }
+  if ((input.allowed ?? []).includes(tool)) {
+    return { outcome: "allow", reason: "explicitly-allowed", tool };
+  }
+  const fromMode = BY_MODE[input.mode];
+  return { outcome: fromMode.outcome, reason: fromMode.reason, tool };
+}
+
+// src/blast-radius.ts
+function evaluateBlastRadius(input) {
+  const { scope, reversible } = input.action;
+  if (scope.length === 0) {
+    return { outcome: "refuse", reason: "scope-undeclared", scope };
+  }
+  if (!input.granted.includes(scope)) {
+    return { outcome: "refuse", reason: "scope-not-granted", scope };
+  }
+  if (!reversible && !(input.irreversibleAllowed ?? []).includes(scope)) {
+    return { outcome: "require-approval", reason: "irreversible", scope };
+  }
+  return { outcome: "allow", reason: "within-granted-scope", scope };
+}
+
 // src/internal/budget/calendar-window.ts
 function startOfDayUtc(now = /* @__PURE__ */ new Date()) {
   return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
@@ -568,6 +602,18 @@ var Skill = class {
     return createSkill(spec);
   }
 };
+function describeCredential(input) {
+  const secret = (input.value ?? "").trim();
+  if (secret.length === 0) {
+    return { provider: input.provider, present: false, source: input.source };
+  }
+  return {
+    provider: input.provider,
+    present: true,
+    source: input.source,
+    fingerprint: crypto.createHash("sha256").update(secret).digest("hex").slice(0, 8)
+  };
+}
 
 // src/define-provider.ts
 function defineProvider(profile, opts) {
@@ -967,7 +1013,7 @@ function foldLayers(entries, accumulatingKeys = []) {
   return combined;
 }
 function diaryPath(cwd) {
-  return path.join(chunkGH52NOCL_cjs.memoryDir(cwd), "dream-diary.md");
+  return path.join(chunkRWMNTFHZ_cjs.memoryDir(cwd), "dream-diary.md");
 }
 function renderDiaryEntry(entry) {
   const stamp = new Date(entry.timestampMs).toISOString();
@@ -1114,7 +1160,7 @@ async function runInner(options) {
   const now = options.now ?? Date.now;
   const timestampMs = now();
   try {
-    const facts = await chunkGH52NOCL_cjs.readFactsFromMarkdown(options.cwd);
+    const facts = await chunkRWMNTFHZ_cjs.readFactsFromMarkdown(options.cwd);
     if (facts.length === 0) {
       return emptyResult("skipped");
     }
@@ -1148,7 +1194,7 @@ async function runInner(options) {
 }
 async function writeConsolidatedNotes(cwd, clusters, timestampMs) {
   if (clusters.length === 0) return 0;
-  const notesDir = path.join(chunkGH52NOCL_cjs.memoryDir(cwd), "notes");
+  const notesDir = path.join(chunkRWMNTFHZ_cjs.memoryDir(cwd), "notes");
   await promises.mkdir(notesDir, { recursive: true });
   const isoSlug = new Date(timestampMs).toISOString().replace(/[^\dT]/g, "-");
   const file = path.join(notesDir, `dreamed-${isoSlug}.md`);
@@ -1214,8 +1260,8 @@ var Memory = {
       openArgs.embedding = await resolveEmbedding(opts.embedding, peer.MEMORY_EMBEDDING_ADAPTERS);
       return await peer.IndexManager.open(openArgs);
     }
-    const { IndexManager } = await import('./index-manager-YFFEPISE.cjs');
-    openArgs.embedding = await resolveEmbedding(opts.embedding, chunkTSK4VVBW_cjs.MEMORY_EMBEDDING_ADAPTERS);
+    const { IndexManager } = await import('./index-manager-34ELCOAP.cjs');
+    openArgs.embedding = await resolveEmbedding(opts.embedding, chunkF7OBYH2X_cjs.MEMORY_EMBEDDING_ADAPTERS);
     return await IndexManager.open(openArgs);
   },
   /**
@@ -1226,7 +1272,7 @@ var Memory = {
    */
   async runDreamingSweep(opts) {
     const peer = await tryLoadSdkMemoryPeer();
-    const catalog = peer !== null ? peer.MEMORY_EMBEDDING_ADAPTERS : chunkTSK4VVBW_cjs.MEMORY_EMBEDDING_ADAPTERS;
+    const catalog = peer !== null ? peer.MEMORY_EMBEDDING_ADAPTERS : chunkF7OBYH2X_cjs.MEMORY_EMBEDDING_ADAPTERS;
     const sweepArgs = await buildDreamingSweepArgs(opts, catalog);
     const result = peer !== null ? (
       // biome-ignore lint/suspicious/noExplicitAny: peer is dynamically loaded — structural compat ensured by sdk-memory
@@ -1292,9 +1338,9 @@ function extractRawId(id, expectedAdapterId) {
   return id.slice(prefix.length);
 }
 async function readAllSqliteFacts(cwd) {
-  const dbPath = chunkGH52NOCL_cjs.defaultIndexPath(cwd);
+  const dbPath = chunkRWMNTFHZ_cjs.defaultIndexPath(cwd);
   if (!fs.existsSync(dbPath)) return [];
-  const db = await chunkGH52NOCL_cjs.openMemoryDb({ filePath: dbPath });
+  const db = await chunkRWMNTFHZ_cjs.openMemoryDb({ filePath: dbPath });
   try {
     const stmt = db.prepare("SELECT id, path, source, start_line, end_line, text FROM chunks");
     const rows = stmt.all();
@@ -1313,7 +1359,7 @@ function nfcEqual(a, b) {
 }
 async function migrateSqliteToLance(opts) {
   const cwd = opts.cwd;
-  const finalPath = chunkGH52NOCL_cjs.lanceStoragePath(cwd);
+  const finalPath = chunkRWMNTFHZ_cjs.lanceStoragePath(cwd);
   const newPath = path.join(cwd, ".theokit", "memory", "lance-new");
   const rawLog = opts.logger ?? ((m) => console.log(m));
   const log = (m) => rawLog(chunkZHPET3LZ_cjs.redactSecrets(m));
@@ -1357,7 +1403,7 @@ async function migrateSqliteToLance(opts) {
   };
   fs.mkdirSync(newPath, { recursive: true });
   log(`Writing Lance index to ${newPath} ...`);
-  const lance = await chunkGH52NOCL_cjs.LanceIndex.open({
+  const lance = await chunkRWMNTFHZ_cjs.LanceIndex.open({
     cwd,
     embedding: placeholderEmbedding,
     storagePath: newPath
@@ -1755,6 +1801,28 @@ function applySecurityFloor(input) {
   return input.layers[input.override] ?? tightenOnly(input, baseline(input));
 }
 
+// src/session-guard.ts
+var LiveSessionError = class extends chunkYULF6FPB_cjs.TheokitAgentError {
+  name = "LiveSessionError";
+  sessionId;
+  reason;
+  constructor(sessionId, reason) {
+    super(
+      reason === "session-is-live" ? `refusing to destroy session ${sessionId}: it is live \u2014 another process is probably still appending to it. Switch to another session first.` : `refusing to destroy session ${sessionId}: the set of live sessions could not be determined, so this cannot be shown to be safe. Resolve that before deleting.`
+    );
+    this.sessionId = sessionId;
+    this.reason = reason;
+  }
+};
+function guardSessionDestruction(sessionId, live) {
+  if (live === void 0) {
+    throw new LiveSessionError(sessionId, "liveness-undetermined");
+  }
+  if (live.includes(sessionId)) {
+    throw new LiveSessionError(sessionId, "session-is-live");
+  }
+}
+
 // src/session-scope.ts
 function scopedConversationId(scope, id) {
   return `${scope}__${id}`;
@@ -1768,7 +1836,7 @@ function isBuiltAgent(m) {
   return typeof m.send === "function";
 }
 async function materialize(def, index) {
-  const { Agent: Agent2 } = await import('./agent-JA4ILE5O.cjs');
+  const { Agent: Agent2 } = await import('./agent-B2WU3JP6.cjs');
   return Agent2.create({
     // `AgentDefinition.model` admits the sentinel `'inherit'`, which is not a model id. Inheriting
     // here means "declare nothing and let the default apply" — forwarding the literal would create
@@ -1800,13 +1868,13 @@ function createSquad(options) {
   };
 }
 async function buildPipeline(agents, nome) {
-  let builder = chunkJO76RWCA_cjs.Workflow.create({ name: nome ?? "squad" });
+  let builder = chunk72HEBGWN_cjs.Workflow.create({ name: nome ?? "squad" });
   for (let i = 0; i < agents.length; i++) {
     const member = agents[i];
     if (member === void 0) continue;
     const agent = isBuiltAgent(member) ? member : await materialize(member, i);
     const opts = i > 0 ? { origin: { kind: "peer", from: `agent-${i - 1}` } } : void 0;
-    builder = builder.then(chunkJO76RWCA_cjs.agentStep(`agent-${i}`, agent, (prev) => String(prev), opts));
+    builder = builder.then(chunk72HEBGWN_cjs.agentStep(`agent-${i}`, agent, (prev) => String(prev), opts));
   }
   return builder.commit();
 }
@@ -1910,7 +1978,7 @@ var FIXTURE_USER = {
 };
 var FIXTURE_MODELS = [
   {
-    id: chunkTSK4VVBW_cjs.DEFAULT_AGENTIC_MODEL_ID,
+    id: chunkF7OBYH2X_cjs.DEFAULT_AGENTIC_MODEL_ID,
     name: "Gemini 2.0 Flash",
     displayName: "Gemini 2.0 Flash",
     parameters: [
@@ -2113,7 +2181,7 @@ var Theokit = class {
         envVars: p.envVars
       }));
     },
-    embeddingAdapters: () => Object.entries(chunkTSK4VVBW_cjs.MEMORY_EMBEDDING_ADAPTERS).map(([id, adapter]) => ({
+    embeddingAdapters: () => Object.entries(chunkF7OBYH2X_cjs.MEMORY_EMBEDDING_ADAPTERS).map(([id, adapter]) => ({
       id,
       transport: adapter.transport,
       defaultModel: adapter.defaultModel
@@ -2145,7 +2213,7 @@ function resolveLocalProviderBaseUrl(providerName, fallback) {
   return fallback;
 }
 async function executeCatalogRequest(request) {
-  const apiKey = chunkTSK4VVBW_cjs.resolveApiKey(request.apiKey);
+  const apiKey = chunkF7OBYH2X_cjs.resolveApiKey(request.apiKey);
   if (apiKey === void 0) {
     throw new chunkYULF6FPB_cjs.AuthenticationError("Missing API key", { code: "missing_api_key" });
   }
@@ -2158,6 +2226,23 @@ async function executeCatalogRequest(request) {
   return chunkQFFNMJAS_cjs.httpRequest(request.path, { apiKey });
 }
 
+// src/tool-blast-radius.ts
+var DECLARED = /* @__PURE__ */ Symbol.for("@theokit/sdk.blastRadius");
+function withBlastRadius(tool, action) {
+  return Object.defineProperty(tool, DECLARED, {
+    value: action,
+    // `enumerable: false` is defensive and NOT load-bearing — checked, not assumed. Flipping it to
+    // true leaves every case green, because the symbol key already excludes this from `Object.keys`
+    // and `JSON.stringify`. It stays because a future string-keyed variant would need it, and the
+    // next reader should not have to discover that the flag has no test behind it.
+    enumerable: false,
+    configurable: true
+  });
+}
+function describeAction(tool) {
+  return tool[DECLARED];
+}
+
 // src/trajectory-helpers.ts
 function toShareGptTrajectory(result, options) {
   if (!result.ok) return null;
@@ -2303,35 +2388,35 @@ Object.defineProperty(exports, "GenerateObjectError", {
 });
 Object.defineProperty(exports, "Cron", {
   enumerable: true,
-  get: function () { return chunk74VVGK7P_cjs.Cron; }
+  get: function () { return chunkWUUSAMFC_cjs.Cron; }
 });
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkTSK4VVBW_cjs.Agent; }
+  get: function () { return chunkF7OBYH2X_cjs.Agent; }
 });
 Object.defineProperty(exports, "AgentBuilder", {
   enumerable: true,
-  get: function () { return chunkTSK4VVBW_cjs.AgentBuilder; }
+  get: function () { return chunkF7OBYH2X_cjs.AgentBuilder; }
 });
 Object.defineProperty(exports, "Tool", {
   enumerable: true,
-  get: function () { return chunkTSK4VVBW_cjs.Tool; }
+  get: function () { return chunkF7OBYH2X_cjs.Tool; }
 });
 Object.defineProperty(exports, "ToolError", {
   enumerable: true,
-  get: function () { return chunkTSK4VVBW_cjs.ToolError; }
+  get: function () { return chunkF7OBYH2X_cjs.ToolError; }
 });
 Object.defineProperty(exports, "UsageAccumulator", {
   enumerable: true,
-  get: function () { return chunkTSK4VVBW_cjs.UsageAccumulator; }
+  get: function () { return chunkF7OBYH2X_cjs.UsageAccumulator; }
 });
 Object.defineProperty(exports, "computeCost", {
   enumerable: true,
-  get: function () { return chunkTSK4VVBW_cjs.computeCost; }
+  get: function () { return chunkF7OBYH2X_cjs.computeCost; }
 });
 Object.defineProperty(exports, "getPricingEntry", {
   enumerable: true,
-  get: function () { return chunkTSK4VVBW_cjs.getPricingEntry; }
+  get: function () { return chunkF7OBYH2X_cjs.getPricingEntry; }
 });
 Object.defineProperty(exports, "emitRunEvent", {
   enumerable: true,
@@ -2418,6 +2503,7 @@ exports.Budget = Budget;
 exports.EventBus = EventBus;
 exports.JobQueue = JobQueue;
 exports.LayerOrderError = LayerOrderError;
+exports.LiveSessionError = LiveSessionError;
 exports.Memory = Memory;
 exports.NoopMemoryProvider = NoopMemoryProvider;
 exports.PermissionEngine = PermissionEngine;
@@ -2440,9 +2526,14 @@ exports.applySecurityFloor = applySecurityFloor;
 exports.auditEnvReachability = auditEnvReachability;
 exports.chargeAndCheckThresholds = chargeAndCheckThresholds;
 exports.createCounterBudgetTracker = createCounterBudgetTracker;
+exports.decideApproval = decideApproval;
+exports.describeAction = describeAction;
+exports.describeCredential = describeCredential;
 exports.estimateTokens = estimateTokens;
+exports.evaluateBlastRadius = evaluateBlastRadius;
 exports.extractRawId = extractRawId;
 exports.foldLayers = foldLayers;
+exports.guardSessionDestruction = guardSessionDestruction;
 exports.inferApiMode = inferApiMode;
 exports.loadProjectEnv = loadProjectEnv;
 exports.migrateSqliteToLance = migrateSqliteToLance2;
@@ -2458,5 +2549,6 @@ exports.scopedConversationId = scopedConversationId;
 exports.sessionScopePrefix = sessionScopePrefix;
 exports.toShareGptTrajectory = toShareGptTrajectory;
 exports.verifyLayerOrdering = verifyLayerOrdering;
+exports.withBlastRadius = withBlastRadius;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map