@nhtio/adk 1.20260607.2 → 1.20260609.1

package/batteries/storage/opfs.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"opfs.cjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  readonly kind: 'file'\n  readonly name: string\n  getFile(): Promise<OpfsFile>\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  readonly kind: 'directory'\n  readonly name: string\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  readonly size: number\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  text(): Promise<string>\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"opfs.cjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  /** Discriminant: always `'file'`. */\n  readonly kind: 'file'\n  /** The entry's name. */\n  readonly name: string\n  /** Resolve a readable {@link OpfsFile} snapshot of the handle's contents. */\n  getFile(): Promise<OpfsFile>\n  /** Open a writable stream that replaces the file's contents. */\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  /** Discriminant: always `'directory'`. */\n  readonly kind: 'directory'\n  /** The directory's name. */\n  readonly name: string\n  /** Resolve a child file handle, optionally creating it. */\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  /** Resolve a child directory handle, optionally creating it. */\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  /** Remove a child entry, optionally recursively. */\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  /** Append/write a chunk to the stream. */\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  /** Flush and close the stream, committing the written contents. */\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  /** Byte length of the blob. */\n  readonly size: number\n  /** Return a sub-range of the blob as a new blob. */\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  /** Read the blob's contents as text. */\n  text(): Promise<string>\n  /** Open a readable byte stream over the blob. */\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  /** The file's name. */\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  /** Acquire a reader over the stream. */\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  /** Read the next chunk, or signal end-of-stream with `done: true`. */\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  /** Release the reader's lock on the stream. */\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":"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"}

package/batteries/storage/opfs.mjs

@@ -1,4 +1,4 @@
-import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 //#region src/batteries/storage/opfs/index.ts
 /**

package/batteries/storage/opfs.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"opfs.mjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  readonly kind: 'file'\n  readonly name: string\n  getFile(): Promise<OpfsFile>\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  readonly kind: 'directory'\n  readonly name: string\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  readonly size: number\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  text(): Promise<string>\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"opfs.mjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  /** Discriminant: always `'file'`. */\n  readonly kind: 'file'\n  /** The entry's name. */\n  readonly name: string\n  /** Resolve a readable {@link OpfsFile} snapshot of the handle's contents. */\n  getFile(): Promise<OpfsFile>\n  /** Open a writable stream that replaces the file's contents. */\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  /** Discriminant: always `'directory'`. */\n  readonly kind: 'directory'\n  /** The directory's name. */\n  readonly name: string\n  /** Resolve a child file handle, optionally creating it. */\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  /** Resolve a child directory handle, optionally creating it. */\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  /** Remove a child entry, optionally recursively. */\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  /** Append/write a chunk to the stream. */\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  /** Flush and close the stream, committing the written contents. */\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  /** Byte length of the blob. */\n  readonly size: number\n  /** Return a sub-range of the blob as a new blob. */\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  /** Read the blob's contents as text. */\n  text(): Promise<string>\n  /** Open a readable byte stream over the blob. */\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  /** The file's name. */\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  /** Acquire a reader over the stream. */\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  /** Read the next chunk, or signal end-of-stream with `done: true`. */\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  /** Release the reader's lock on the stream. */\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":"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"}

package/batteries/tools/_shared/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Cross-battery helpers shared by the configured HTTP tool batteries (SearXNG, Scrapper, …).
+ *
+ * @module @nhtio/adk/batteries/tools/_shared
+ *
+ * @remarks
+ * These are internal building blocks for the *factory-style* tool batteries — the ones that talk
+ * to a configured HTTP instance behind custom auth and expose input/output middleware pipelines.
+ * Rather than each battery carry its own copy, the common machinery lives here:
+ *
+ * - {@link resolveArtifact} / {@link resolveArtifactSync} — turn an {@link ArtifactResolver}
+ *   (a constructor, a sync resolver, or an async / dynamic-import resolver) into the **sync**
+ *   `() => SpooledArtifactConstructor` that `Tool.artifactConstructor` requires. Mirrors the vector
+ *   battery's `resolveClientCtor`.
+ * - {@link resolveHeaders} — collapse a static header object or a (sync/async) resolver into a
+ *   plain header record for one request (refreshable-auth friendly).
+ * - {@link runInputPipeline} / {@link runOutputPipeline} — the onion middleware runners (fresh
+ *   runner per call, short-circuit + non-terminal detection), generic over the context type.
+ *
+ * This module imports harness primitives only through their specific subpath barrels
+ * (`@nhtio/adk/spooled_artifact`, `@nhtio/adk/forge`, `@nhtio/adk/guards`) per the batteries
+ * barrel-only rule.
+ */
+import { Middleware } from '@nhtio/middleware';
+import type { NextFn } from '@nhtio/middleware';
+import type { SpooledArtifactConstructor } from "../../../forge";
+/** A static set of request headers (used for custom instance authentication). */
+export type ToolHeaders = Record<string, string>;
+/**
+ * A resolver returning request headers, sync or async. Use this form when the auth token is
+ * refreshable — the resolver runs on every request, so a fresh token can be minted per call.
+ */
+export type ToolHeadersResolver = () => ToolHeaders | Promise<ToolHeaders>;
+/**
+ * Resolve the configured headers (a static object or a sync/async resolver) for a single request.
+ *
+ * @param headers - The static header record, the resolver, or `undefined`.
+ * @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).
+ */
+export declare const resolveHeaders: (headers: ToolHeaders | ToolHeadersResolver | undefined) => Promise<ToolHeaders>;
+/** Convenience alias for the spooled-artifact constructor a tool wraps its output in. */
+export type SpooledArtifactCtor = SpooledArtifactConstructor;
+/**
+ * The artifact configuration accepted by a factory: a constructor, a sync resolver, or an async /
+ * dynamic-import resolver (which may yield a module namespace whose `default` is the constructor).
+ *
+ * @remarks
+ * Mirrors the vector battery's `client` resolver and `Tool.artifactConstructor`'s indirection. The
+ * async form lets a consumer `() => import('@nhtio/adk/spooled_artifact').then(m => m.SpooledMarkdownArtifact)`
+ * so the artifact class never enters their static module graph.
+ */
+export type ArtifactResolver = SpooledArtifactCtor | (() => SpooledArtifactCtor | {
+    default: SpooledArtifactCtor;
+}) | (() => Promise<SpooledArtifactCtor | {
+    default: SpooledArtifactCtor;
+}>);
+/** The sync subset of {@link ArtifactResolver} — a constructor or a sync resolver (no Promise). */
+export type SyncArtifactResolver = SpooledArtifactCtor | (() => SpooledArtifactCtor | {
+    default: SpooledArtifactCtor;
+});
+/**
+ * Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that
+ * `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both
+ * invoke it synchronously, so an async resolver cannot be passed straight through).
+ *
+ * @remarks
+ * A bare constructor is itself a function, so it is distinguished from a resolver via
+ * `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator
+ * uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.
+ *
+ * @param resolver - The artifact configuration. When `undefined`, callers should fall back to
+ *   their own default (this function rejects `undefined` so the default lives with the caller).
+ * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+ * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+ */
+export declare const resolveArtifact: (resolver: ArtifactResolver, onInvalid: (reason: string) => never) => Promise<() => SpooledArtifactCtor>;
+/**
+ * Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and
+ * throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the
+ * compile-time narrowing.
+ *
+ * @param resolver - A constructor or a sync resolver.
+ * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+ * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+ */
+export declare const resolveArtifactSync: (resolver: SyncArtifactResolver, onInvalid: (reason: string) => never) => (() => SpooledArtifactCtor);
+/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */
+export declare const isShortCircuit: (value: unknown) => value is {
+    result: string;
+};
+/**
+ * Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the
+ * internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result
+ * (skipping the HTTP request entirely — e.g. a cache hit).
+ *
+ * @returns A function that, when called with a result string, throws the short-circuit sentinel.
+ */
+export declare const makeShortCircuit: () => ((result: string) => never);
+/** A generic onion middleware stage over a mutable context `C`. */
+export type MiddlewareFn<C> = (ctx: C, next: NextFn) => void | Promise<void>;
+/**
+ * Run an input pipeline over `ctx`. Returns the short-circuit string when a stage short-circuited,
+ * or `undefined` when the pipeline reached its terminal handler. A non-terminal pipeline (a stage
+ * that neither called `next()` nor short-circuited) throws — the caller converts it to an
+ * `Error:` string.
+ *
+ * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+ * @param ctx - The mutable input context handed to each stage.
+ * @param label - Battery name, used in the non-terminal error message.
+ * @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.
+ */
+export declare const runInputPipeline: <C>(mw: Middleware<MiddlewareFn<C>>, ctx: C, label: string) => Promise<string | undefined>;
+/**
+ * Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A
+ * non-terminal pipeline (no `next()`) throws.
+ *
+ * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+ * @param ctx - The mutable output context handed to each stage.
+ * @param label - Battery name, used in the non-terminal error message.
+ */
+export declare const runOutputPipeline: <C>(mw: Middleware<MiddlewareFn<C>>, ctx: C, label: string) => Promise<void>;

package/batteries/tools/_shared.cjs

@@ -0,0 +1,157 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
+const require_spooled_artifact = require("../../spooled_artifact-DX8LLyUX.js");
+require("../../guards.cjs");
+require("../../spooled_artifact.cjs");
+//#region src/batteries/tools/_shared/index.ts
+/**
+* Resolve the configured headers (a static object or a sync/async resolver) for a single request.
+*
+* @param headers - The static header record, the resolver, or `undefined`.
+* @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).
+*/
+var resolveHeaders = async (headers) => {
+	if (typeof headers === "function") return { ...await headers() };
+	return { ...headers ?? {} };
+};
+/** Unwrap a resolved value that may be a module namespace whose `default` is the constructor. */
+var unwrapDefault = (value) => {
+	if (require_tool_registry.isObject(value) && "default" in value) {
+		const def = value.default;
+		if (require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(def)) return def;
+	}
+	return value;
+};
+/**
+* Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that
+* `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both
+* invoke it synchronously, so an async resolver cannot be passed straight through).
+*
+* @remarks
+* A bare constructor is itself a function, so it is distinguished from a resolver via
+* `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator
+* uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.
+*
+* @param resolver - The artifact configuration. When `undefined`, callers should fall back to
+*   their own default (this function rejects `undefined` so the default lives with the caller).
+* @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+* @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+*/
+var resolveArtifact = async (resolver, onInvalid) => {
+	if (require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolver)) {
+		const ctor = resolver;
+		return () => ctor;
+	}
+	if (typeof resolver !== "function") onInvalid("artifact must be a SpooledArtifact constructor or a resolver returning one");
+	let resolved;
+	try {
+		resolved = await resolver();
+	} catch (err) {
+		onInvalid(`artifact resolver threw: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	}
+	resolved = unwrapDefault(resolved);
+	if (!require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolved)) onInvalid("artifact resolver did not resolve to a SpooledArtifact constructor");
+	const ctor = resolved;
+	return () => ctor;
+};
+/**
+* Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and
+* throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the
+* compile-time narrowing.
+*
+* @param resolver - A constructor or a sync resolver.
+* @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+* @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+*/
+var resolveArtifactSync = (resolver, onInvalid) => {
+	if (require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolver)) {
+		const ctor = resolver;
+		return () => ctor;
+	}
+	if (typeof resolver !== "function") onInvalid("artifact must be a SpooledArtifact constructor or a resolver returning one");
+	let resolved;
+	try {
+		resolved = resolver();
+	} catch (err) {
+		onInvalid(`artifact resolver threw: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	}
+	if (require_tool_registry.isInstanceOf(resolved, "Promise", Promise)) onInvalid("artifact resolver is async; use the async factory variant for dynamic-import resolvers");
+	resolved = unwrapDefault(resolved);
+	if (!require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolved)) onInvalid("artifact resolver did not resolve to a SpooledArtifact constructor");
+	const ctor = resolved;
+	return () => ctor;
+};
+/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */
+var SHORT_CIRCUIT = Symbol("adk.tools.shortCircuit");
+/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */
+var isShortCircuit = (value) => require_tool_registry.isObject(value) && value[SHORT_CIRCUIT] === true;
+/**
+* Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the
+* internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result
+* (skipping the HTTP request entirely — e.g. a cache hit).
+*
+* @returns A function that, when called with a result string, throws the short-circuit sentinel.
+*/
+var makeShortCircuit = () => {
+	return (result) => {
+		throw {
+			[SHORT_CIRCUIT]: true,
+			result
+		};
+	};
+};
+/**
+* Run an input pipeline over `ctx`. Returns the short-circuit string when a stage short-circuited,
+* or `undefined` when the pipeline reached its terminal handler. A non-terminal pipeline (a stage
+* that neither called `next()` nor short-circuited) throws — the caller converts it to an
+* `Error:` string.
+*
+* @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+* @param ctx - The mutable input context handed to each stage.
+* @param label - Battery name, used in the non-terminal error message.
+* @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.
+*/
+var runInputPipeline = async (mw, ctx, label) => {
+	let reached = false;
+	let caught;
+	await mw.runner().errorHandler(async (error) => {
+		caught = error;
+	}).finalHandler(async () => {
+		reached = true;
+	}).run((fn, next) => Promise.resolve(fn(ctx, next)));
+	if (caught !== void 0) {
+		if (isShortCircuit(caught)) return caught.result;
+		throw caught;
+	}
+	if (!reached) throw new Error(`${label} input pipeline did not call next() and did not short-circuit.`);
+};
+/**
+* Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A
+* non-terminal pipeline (no `next()`) throws.
+*
+* @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+* @param ctx - The mutable output context handed to each stage.
+* @param label - Battery name, used in the non-terminal error message.
+*/
+var runOutputPipeline = async (mw, ctx, label) => {
+	let reached = false;
+	let caught;
+	await mw.runner().errorHandler(async (error) => {
+		caught = error;
+	}).finalHandler(async () => {
+		reached = true;
+	}).run((fn, next) => Promise.resolve(fn(ctx, next)));
+	if (caught !== void 0) throw caught;
+	if (!reached) throw new Error(`${label} output pipeline did not call next().`);
+};
+//#endregion
+exports.isShortCircuit = isShortCircuit;
+exports.makeShortCircuit = makeShortCircuit;
+exports.resolveArtifact = resolveArtifact;
+exports.resolveArtifactSync = resolveArtifactSync;
+exports.resolveHeaders = resolveHeaders;
+exports.runInputPipeline = runInputPipeline;
+exports.runOutputPipeline = runOutputPipeline;
+
+//# sourceMappingURL=_shared.cjs.map

package/batteries/tools/_shared.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.cjs","names":[],"sources":["../../../src/batteries/tools/_shared/index.ts"],"sourcesContent":["/**\n * Cross-battery helpers shared by the configured HTTP tool batteries (SearXNG, Scrapper, …).\n *\n * @module @nhtio/adk/batteries/tools/_shared\n *\n * @remarks\n * These are internal building blocks for the *factory-style* tool batteries — the ones that talk\n * to a configured HTTP instance behind custom auth and expose input/output middleware pipelines.\n * Rather than each battery carry its own copy, the common machinery lives here:\n *\n * - {@link resolveArtifact} / {@link resolveArtifactSync} — turn an {@link ArtifactResolver}\n *   (a constructor, a sync resolver, or an async / dynamic-import resolver) into the **sync**\n *   `() => SpooledArtifactConstructor` that `Tool.artifactConstructor` requires. Mirrors the vector\n *   battery's `resolveClientCtor`.\n * - {@link resolveHeaders} — collapse a static header object or a (sync/async) resolver into a\n *   plain header record for one request (refreshable-auth friendly).\n * - {@link runInputPipeline} / {@link runOutputPipeline} — the onion middleware runners (fresh\n *   runner per call, short-circuit + non-terminal detection), generic over the context type.\n *\n * This module imports harness primitives only through their specific subpath barrels\n * (`@nhtio/adk/spooled_artifact`, `@nhtio/adk/forge`, `@nhtio/adk/guards`) per the batteries\n * barrel-only rule.\n */\n\nimport { Middleware } from '@nhtio/middleware'\nimport { SpooledArtifact } from '@nhtio/adk/spooled_artifact'\nimport { isError, isObject, isInstanceOf } from '@nhtio/adk/guards'\nimport type { NextFn } from '@nhtio/middleware'\nimport type { SpooledArtifactConstructor } from '@nhtio/adk/forge'\n\n// ── Header resolution ────────────────────────────────────────────────────────\n\n/** A static set of request headers (used for custom instance authentication). */\nexport type ToolHeaders = Record<string, string>\n\n/**\n * A resolver returning request headers, sync or async. Use this form when the auth token is\n * refreshable — the resolver runs on every request, so a fresh token can be minted per call.\n */\nexport type ToolHeadersResolver = () => ToolHeaders | Promise<ToolHeaders>\n\n/**\n * Resolve the configured headers (a static object or a sync/async resolver) for a single request.\n *\n * @param headers - The static header record, the resolver, or `undefined`.\n * @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).\n */\nexport const resolveHeaders = async (\n  headers: ToolHeaders | ToolHeadersResolver | undefined\n): Promise<ToolHeaders> => {\n  if (typeof headers === 'function') return { ...(await headers()) }\n  return { ...(headers ?? {}) }\n}\n\n// ── Artifact resolver ────────────────────────────────────────────────────────\n\n/** Convenience alias for the spooled-artifact constructor a tool wraps its output in. */\nexport type SpooledArtifactCtor = SpooledArtifactConstructor\n\n/**\n * The artifact configuration accepted by a factory: a constructor, a sync resolver, or an async /\n * dynamic-import resolver (which may yield a module namespace whose `default` is the constructor).\n *\n * @remarks\n * Mirrors the vector battery's `client` resolver and `Tool.artifactConstructor`'s indirection. The\n * async form lets a consumer `() => import('@nhtio/adk/spooled_artifact').then(m => m.SpooledMarkdownArtifact)`\n * so the artifact class never enters their static module graph.\n */\nexport type ArtifactResolver =\n  | SpooledArtifactCtor\n  | (() => SpooledArtifactCtor | { default: SpooledArtifactCtor })\n  | (() => Promise<SpooledArtifactCtor | { default: SpooledArtifactCtor }>)\n\n/** The sync subset of {@link ArtifactResolver} — a constructor or a sync resolver (no Promise). */\nexport type SyncArtifactResolver =\n  | SpooledArtifactCtor\n  | (() => SpooledArtifactCtor | { default: SpooledArtifactCtor })\n\n/** Unwrap a resolved value that may be a module namespace whose `default` is the constructor. */\nconst unwrapDefault = (value: unknown): unknown => {\n  if (isObject(value) && 'default' in value) {\n    const def = (value as { default?: unknown }).default\n    if (SpooledArtifact.isSpooledArtifactConstructor(def)) return def\n  }\n  return value\n}\n\n/**\n * Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that\n * `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both\n * invoke it synchronously, so an async resolver cannot be passed straight through).\n *\n * @remarks\n * A bare constructor is itself a function, so it is distinguished from a resolver via\n * `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator\n * uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.\n *\n * @param resolver - The artifact configuration. When `undefined`, callers should fall back to\n *   their own default (this function rejects `undefined` so the default lives with the caller).\n * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.\n * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.\n */\nexport const resolveArtifact = async (\n  resolver: ArtifactResolver,\n  onInvalid: (reason: string) => never\n): Promise<() => SpooledArtifactCtor> => {\n  // A constructor: hand back a thunk that returns it.\n  if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {\n    const ctor = resolver\n    return () => ctor\n  }\n  // Otherwise it must be a resolver function.\n  if (typeof resolver !== 'function') {\n    onInvalid('artifact must be a SpooledArtifact constructor or a resolver returning one')\n  }\n  let resolved: unknown\n  try {\n    resolved = await (resolver as () => unknown)()\n  } catch (err) {\n    onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`)\n  }\n  resolved = unwrapDefault(resolved)\n  if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) {\n    onInvalid('artifact resolver did not resolve to a SpooledArtifact constructor')\n  }\n  const ctor = resolved as SpooledArtifactCtor\n  return () => ctor\n}\n\n/**\n * Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and\n * throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the\n * compile-time narrowing.\n *\n * @param resolver - A constructor or a sync resolver.\n * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.\n * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.\n */\nexport const resolveArtifactSync = (\n  resolver: SyncArtifactResolver,\n  onInvalid: (reason: string) => never\n): (() => SpooledArtifactCtor) => {\n  if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {\n    const ctor = resolver\n    return () => ctor\n  }\n  if (typeof resolver !== 'function') {\n    onInvalid('artifact must be a SpooledArtifact constructor or a resolver returning one')\n  }\n  let resolved: unknown\n  try {\n    resolved = (resolver as () => unknown)()\n  } catch (err) {\n    onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`)\n  }\n  if (isInstanceOf(resolved, 'Promise', Promise)) {\n    onInvalid(\n      'artifact resolver is async; use the async factory variant for dynamic-import resolvers'\n    )\n  }\n  resolved = unwrapDefault(resolved)\n  if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) {\n    onInvalid('artifact resolver did not resolve to a SpooledArtifact constructor')\n  }\n  const ctor = resolved as SpooledArtifactCtor\n  return () => ctor\n}\n\n// ── Middleware pipeline runners ──────────────────────────────────────────────\n\n/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */\nconst SHORT_CIRCUIT = Symbol('adk.tools.shortCircuit')\n\ninterface ShortCircuitSignal {\n  [SHORT_CIRCUIT]: true\n  result: string\n}\n\n/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */\nexport const isShortCircuit = (value: unknown): value is { result: string } =>\n  isObject(value) && (value as Record<symbol, unknown>)[SHORT_CIRCUIT] === true\n\n/**\n * Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the\n * internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result\n * (skipping the HTTP request entirely — e.g. a cache hit).\n *\n * @returns A function that, when called with a result string, throws the short-circuit sentinel.\n */\nexport const makeShortCircuit = (): ((result: string) => never) => {\n  return (result: string): never => {\n    const signal: ShortCircuitSignal = { [SHORT_CIRCUIT]: true, result }\n    throw signal\n  }\n}\n\n/** A generic onion middleware stage over a mutable context `C`. */\nexport type MiddlewareFn<C> = (ctx: C, next: NextFn) => void | Promise<void>\n\n/**\n * Run an input pipeline over `ctx`. Returns the short-circuit string when a stage short-circuited,\n * or `undefined` when the pipeline reached its terminal handler. A non-terminal pipeline (a stage\n * that neither called `next()` nor short-circuited) throws — the caller converts it to an\n * `Error:` string.\n *\n * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).\n * @param ctx - The mutable input context handed to each stage.\n * @param label - Battery name, used in the non-terminal error message.\n * @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.\n */\nexport const runInputPipeline = async <C>(\n  mw: Middleware<MiddlewareFn<C>>,\n  ctx: C,\n  label: string\n): Promise<string | undefined> => {\n  let reached = false\n  let caught: unknown\n  await mw\n    .runner()\n    .errorHandler(async (error: unknown) => {\n      caught = error\n    })\n    .finalHandler(async () => {\n      reached = true\n    })\n    .run((fn, next) => Promise.resolve(fn(ctx, next)))\n\n  if (caught !== undefined) {\n    if (isShortCircuit(caught)) return caught.result\n    throw caught\n  }\n  if (!reached) {\n    throw new Error(`${label} input pipeline did not call next() and did not short-circuit.`)\n  }\n  return undefined\n}\n\n/**\n * Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A\n * non-terminal pipeline (no `next()`) throws.\n *\n * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).\n * @param ctx - The mutable output context handed to each stage.\n * @param label - Battery name, used in the non-terminal error message.\n */\nexport const runOutputPipeline = async <C>(\n  mw: Middleware<MiddlewareFn<C>>,\n  ctx: C,\n  label: string\n): Promise<void> => {\n  let reached = false\n  let caught: unknown\n  await mw\n    .runner()\n    .errorHandler(async (error: unknown) => {\n      caught = error\n    })\n    .finalHandler(async () => {\n      reached = true\n    })\n    .run((fn, next) => Promise.resolve(fn(ctx, next)))\n\n  if (caught !== undefined) throw caught\n  if (!reached) throw new Error(`${label} output pipeline did not call next().`)\n}\n"],"mappings":";;;;;;;;;;;;;AA+CA,IAAa,iBAAiB,OAC5B,YACyB;CACzB,IAAI,OAAO,YAAY,YAAY,OAAO,EAAE,GAAI,MAAM,QAAQ,EAAG;CACjE,OAAO,EAAE,GAAI,WAAW,CAAC,EAAG;AAC9B;;AA2BA,IAAM,iBAAiB,UAA4B;CACjD,IAAI,sBAAA,SAAS,KAAK,KAAK,aAAa,OAAO;EACzC,MAAM,MAAO,MAAgC;EAC7C,IAAI,yBAAA,gBAAgB,6BAA6B,GAAG,GAAG,OAAO;CAChE;CACA,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,IAAa,kBAAkB,OAC7B,UACA,cACuC;CAEvC,IAAI,yBAAA,gBAAgB,6BAA6B,QAAQ,GAAG;EAC1D,MAAM,OAAO;EACb,aAAa;CACf;CAEA,IAAI,OAAO,aAAa,YACtB,UAAU,4EAA4E;CAExF,IAAI;CACJ,IAAI;EACF,WAAW,MAAO,SAA2B;CAC/C,SAAS,KAAK;EACZ,UAAU,4BAA4B,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GAAG;CAClF;CACA,WAAW,cAAc,QAAQ;CACjC,IAAI,CAAC,yBAAA,gBAAgB,6BAA6B,QAAQ,GACxD,UAAU,oEAAoE;CAEhF,MAAM,OAAO;CACb,aAAa;AACf;;;;;;;;;;AAWA,IAAa,uBACX,UACA,cACgC;CAChC,IAAI,yBAAA,gBAAgB,6BAA6B,QAAQ,GAAG;EAC1D,MAAM,OAAO;EACb,aAAa;CACf;CACA,IAAI,OAAO,aAAa,YACtB,UAAU,4EAA4E;CAExF,IAAI;CACJ,IAAI;EACF,WAAY,SAA2B;CACzC,SAAS,KAAK;EACZ,UAAU,4BAA4B,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GAAG;CAClF;CACA,IAAI,sBAAA,aAAa,UAAU,WAAW,OAAO,GAC3C,UACE,wFACF;CAEF,WAAW,cAAc,QAAQ;CACjC,IAAI,CAAC,yBAAA,gBAAgB,6BAA6B,QAAQ,GACxD,UAAU,oEAAoE;CAEhF,MAAM,OAAO;CACb,aAAa;AACf;;AAKA,IAAM,gBAAgB,OAAO,wBAAwB;;AAQrD,IAAa,kBAAkB,UAC7B,sBAAA,SAAS,KAAK,KAAM,MAAkC,mBAAmB;;;;;;;;AAS3E,IAAa,yBAAsD;CACjE,QAAQ,WAA0B;EAEhC,MAAM;IADgC,gBAAgB;GAAM;EACtD;CACR;AACF;;;;;;;;;;;;AAgBA,IAAa,mBAAmB,OAC9B,IACA,KACA,UACgC;CAChC,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,GACH,OAAO,EACP,aAAa,OAAO,UAAmB;EACtC,SAAS;CACX,CAAC,EACA,aAAa,YAAY;EACxB,UAAU;CACZ,CAAC,EACA,KAAK,IAAI,SAAS,QAAQ,QAAQ,GAAG,KAAK,IAAI,CAAC,CAAC;CAEnD,IAAI,WAAW,KAAA,GAAW;EACxB,IAAI,eAAe,MAAM,GAAG,OAAO,OAAO;EAC1C,MAAM;CACR;CACA,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,GAAG,MAAM,+DAA+D;AAG5F;;;;;;;;;AAUA,IAAa,oBAAoB,OAC/B,IACA,KACA,UACkB;CAClB,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,GACH,OAAO,EACP,aAAa,OAAO,UAAmB;EACtC,SAAS;CACX,CAAC,EACA,aAAa,YAAY;EACxB,UAAU;CACZ,CAAC,EACA,KAAK,IAAI,SAAS,QAAQ,QAAQ,GAAG,KAAK,IAAI,CAAC,CAAC;CAEnD,IAAI,WAAW,KAAA,GAAW,MAAM;CAChC,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,GAAG,MAAM,sCAAsC;AAC/E"}