@nhtio/adk 0.1.0-master-f0aa531d

package/batteries/storage/opfs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"opfs.cjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#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 } 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 {\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   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string` or `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,\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    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    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  #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

@@ -0,0 +1,366 @@
+import { s as isInstanceOf } from "../../tool_registry-DqLOyGyG.mjs";
+import "../../guards.mjs";
+//#region src/batteries/storage/opfs/index.ts
+/**
+* Browser-only Origin Private File System storage for spooled artifacts.
+*
+* @module @nhtio/adk/batteries/storage/opfs
+*
+* @remarks
+* Opt-in **browser-only** storage battery backed by the
+* [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)
+* (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)
+* and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an
+* OPFS directory).
+*
+* The reader has two modes selected lazily on first method invocation based on the size of the
+* underlying file:
+*
+* - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the
+*   reader calls `file.text()` once, splits the content on `\n`, and caches lines + byte count.
+*   All subsequent calls resolve from memory.
+* - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the
+*   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte
+*   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —
+*   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.
+*   Caps RAM at one index + one line buffer regardless of file size.
+*
+* The store auto-selects its write API by execution scope:
+*
+* - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a
+*   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API
+*   available in workers and the fastest path for the spool-write hot path.
+* - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async
+*   stream API. Sync access handles are not exposed on the main thread.
+*
+* This module assumes a browser-equivalent runtime — `navigator.storage`,
+* `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not
+* be imported from Node code; do so and you will fail at resolve time when `navigator` is
+* referenced.
+*
+* @example
+* ```ts
+* import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'
+*
+* const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })
+* const reader = await store.write(callId, bytes)
+* const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact
+* const artifact = new Ctor(reader)
+* ```
+*/
+var DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024;
+var LF = 10;
+var isNonNegativeFiniteNumber = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+/**
+* Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,
+* `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).
+*
+* @remarks
+* The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker
+* scopes — calling it from the main thread throws. We pick the write strategy based on the
+* answer here.
+*
+* @internal
+*/
+var isWorkerScope = () => {
+	if (typeof WorkerGlobalScope === "undefined") return false;
+	return self instanceof WorkerGlobalScope;
+};
+/**
+* Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.
+*
+* @remarks
+* Constructor is **not** async — but the first method call awaits a private readiness promise
+* that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse
+* the cached state. This keeps construction call sites synchronous while still doing real I/O
+* lazily.
+*
+* All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract
+* supports both sync and async return; consumers of `SpooledArtifact` handle either.
+*/
+var OpfsSpoolReader = class OpfsSpoolReader {
+	#handle;
+	#threshold;
+	#ready;
+	constructor(handle, opts = {}) {
+		this.#handle = handle;
+		const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES;
+		if (typeof raw !== "number" || Number.isNaN(raw) || raw < 0) throw new TypeError(`OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`);
+		this.#threshold = raw;
+	}
+	/**
+	* Returns `true` if `value` is an {@link OpfsSpoolReader} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is an {@link OpfsSpoolReader} instance.
+	*/
+	static isOpfsSpoolReader(value) {
+		return isInstanceOf(value, "OpfsSpoolReader", OpfsSpoolReader);
+	}
+	async line(index) {
+		const state = await this.#load();
+		if (state.mode === "eager") return state.lines[index];
+		if (index < 0 || index >= state.offsets.length - 1) return void 0;
+		return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1]);
+	}
+	async byteLength() {
+		return (await this.#load()).bytes;
+	}
+	async lineCount() {
+		const state = await this.#load();
+		return state.mode === "eager" ? state.lines.length : state.offsets.length - 1;
+	}
+	/**
+	* Returns the full underlying content as a single decoded string, byte-faithful to the source.
+	*
+	* @remarks
+	* In **eager mode** the content is already cached at first-call load and this method is
+	* effectively a property access. In **streaming mode** there is no cache: the file is re-read
+	* (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`
+	* judiciously on large streaming-mode artifacts.
+	*/
+	async readAll() {
+		const state = await this.#load();
+		if (state.mode === "eager") return state.content;
+		return state.file.text();
+	}
+	/**
+	* Lazily initialise the reader's mode-specific state. Called by every public method; the
+	* promise is cached so the work runs at most once.
+	*/
+	#load() {
+		if (!this.#ready) this.#ready = this.#init();
+		return this.#ready;
+	}
+	async #init() {
+		const file = await this.#handle.getFile();
+		const bytes = file.size;
+		if (!isNonNegativeFiniteNumber(bytes)) throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`);
+		if (bytes < this.#threshold) {
+			const content = await file.text();
+			return {
+				mode: "eager",
+				lines: content === "" ? [] : content.split("\n"),
+				bytes,
+				content
+			};
+		}
+		return this.#buildStreamingIndex(file, bytes);
+	}
+	async #buildStreamingIndex(file, bytes) {
+		if (bytes === 0) return {
+			mode: "streaming",
+			file,
+			offsets: [0],
+			bytes
+		};
+		const offsets = [0];
+		let position = 0;
+		let lastByte = -1;
+		const reader = file.stream().getReader();
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				for (const byte of value) {
+					position++;
+					if (byte === LF) offsets.push(position);
+					lastByte = byte;
+				}
+			}
+		} finally {
+			reader.releaseLock();
+		}
+		if (lastByte === LF) offsets.push(position);
+		else if (offsets[offsets.length - 1] !== position) offsets.push(position);
+		return {
+			mode: "streaming",
+			file,
+			offsets,
+			bytes
+		};
+	}
+	/**
+	* Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8
+	* string, stripping a trailing `\n` if present.
+	*
+	* @remarks
+	* `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index
+	* brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the
+	* next line) and the `SpoolReader` contract returns lines *without* their trailing newline,
+	* so we strip a single trailing LF if present.
+	*/
+	async #readRange(file, start, end) {
+		if (start === end) return "";
+		const text = await file.slice(start, end).text();
+		if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) return text.slice(0, -1);
+		return text;
+	}
+};
+/**
+* "Give bytes, get a reader" persistence layer over an OPFS directory.
+*
+* @remarks
+* `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates
+* the file named `keyPrefix + callId`, then writes via the API matching the current scope:
+* a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on
+* the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.
+*
+* `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.
+*
+* The store is otherwise stateless — it owns no in-memory cache of writes. Multiple
+* `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.
+*
+* @example
+* ```ts
+* import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'
+*
+* const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })
+*
+* const bytes = await tool.executor(ctx)(args)
+* const reader = await store.write(callId, bytes)
+* const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact
+* const artifact = new Ctor(reader)
+* ```
+*/
+var OpfsSpoolStore = class OpfsSpoolStore {
+	#resolveRoot;
+	#prefix;
+	#defaultThreshold;
+	#root;
+	constructor(opts = {}) {
+		this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory());
+		this.#prefix = opts.keyPrefix ?? "";
+		this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES;
+	}
+	/**
+	* Returns `true` if `value` is an {@link OpfsSpoolStore} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is an {@link OpfsSpoolStore} instance.
+	*/
+	static isOpfsSpoolStore(value) {
+		return isInstanceOf(value, "OpfsSpoolStore", OpfsSpoolStore);
+	}
+	/**
+	* Persists `bytes` under `callId` and returns a reader bound to the stored key.
+	*
+	* @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.
+	* @param bytes - The bytes to store, as a `string` or `Uint8Array`.
+	* @param opts - Per-call override for `streamThresholdBytes`.
+	* @returns An {@link OpfsSpoolReader} over the stored bytes.
+	*/
+	async write(callId, bytes, opts) {
+		const name = this.#keyFor(callId);
+		const handle = await (await this.#getRoot()).getFileHandle(name, { create: true });
+		const payload = typeof bytes === "string" ? new TextEncoder().encode(bytes) : bytes;
+		if (isWorkerScope()) await this.#writeViaSyncHandle(handle, payload);
+		else await this.#writeViaWritable(handle, payload);
+		return new OpfsSpoolReader(handle, { streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold });
+	}
+	/**
+	* Returns a reader over the bytes previously written under `callId`.
+	*
+	* @remarks
+	* Returns `undefined` if the file does not exist.
+	*
+	* @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.
+	* @param opts - Per-call override for `streamThresholdBytes`.
+	* @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.
+	*/
+	async read(callId, opts) {
+		const name = this.#keyFor(callId);
+		const root = await this.#getRoot();
+		let handle;
+		try {
+			handle = await root.getFileHandle(name);
+		} catch (err) {
+			if (this.#isNotFoundError(err)) return void 0;
+			throw err;
+		}
+		return new OpfsSpoolReader(handle, { streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold });
+	}
+	/**
+	* Removes the entry under `callId`.
+	*
+	* @param callId - Identifier whose entry should be removed.
+	* @returns `true` if the entry existed and was removed; `false` if it didn't exist.
+	*/
+	async delete(callId) {
+		const name = this.#keyFor(callId);
+		const root = await this.#getRoot();
+		try {
+			await root.removeEntry(name);
+			return true;
+		} catch (err) {
+			if (this.#isNotFoundError(err)) return false;
+			throw err;
+		}
+	}
+	/**
+	* Returns `true` if a file is present under `callId`.
+	*
+	* @param callId - Identifier to test.
+	* @returns `true` when the file exists, `false` otherwise.
+	*/
+	async has(callId) {
+		const name = this.#keyFor(callId);
+		const root = await this.#getRoot();
+		try {
+			await root.getFileHandle(name);
+			return true;
+		} catch (err) {
+			if (this.#isNotFoundError(err)) return false;
+			throw err;
+		}
+	}
+	/**
+	* Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).
+	*
+	* @remarks
+	* Useful for tests or for callers that want to interact with the underlying OPFS directory
+	* directly.
+	*/
+	keyFor(callId) {
+		return this.#keyFor(callId);
+	}
+	#keyFor(callId) {
+		return this.#prefix + callId;
+	}
+	async #getRoot() {
+		if (!this.#root) this.#root = await this.#resolveRoot();
+		return this.#root;
+	}
+	async #writeViaSyncHandle(handle, payload) {
+		const sync = await handle.createSyncAccessHandle();
+		try {
+			sync.truncate(0);
+			sync.write(payload, { at: 0 });
+			sync.flush();
+		} finally {
+			sync.close();
+		}
+	}
+	async #writeViaWritable(handle, payload) {
+		const writable = await handle.createWritable();
+		try {
+			await writable.write(payload);
+		} finally {
+			await writable.close();
+		}
+	}
+	#isNotFoundError(err) {
+		if (err === null || typeof err !== "object") return false;
+		return err.name === "NotFoundError";
+	}
+};
+//#endregion
+export { OpfsSpoolReader, OpfsSpoolStore };
+
+//# sourceMappingURL=opfs.mjs.map

package/batteries/storage/opfs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"opfs.mjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#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 } 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 {\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   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string` or `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,\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    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    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  #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.cjs

@@ -0,0 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_batteries_storage_in_memory = require("./storage/in_memory.cjs");
+exports.InMemorySpoolReader = require_batteries_storage_in_memory.InMemorySpoolReader;
+exports.InMemorySpoolStore = require_batteries_storage_in_memory.InMemorySpoolStore;

package/batteries/storage.mjs

@@ -0,0 +1,2 @@
+import { InMemorySpoolReader, InMemorySpoolStore } from "./storage/in_memory.mjs";
+export { InMemorySpoolReader, InMemorySpoolStore };

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

@@ -0,0 +1,37 @@
+/**
+ * Pre-constructed tools for color conversion and palette-oriented calculations.
+ *
+ * @module @nhtio/adk/batteries/tools/color
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `color` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool } from "../../../common";
+/**
+ * Compute the WCAG 2.1 contrast ratio between two colours.
+ *
+ * @remarks
+ * Accepts hex (`#rgb`, `#rrggbb`), `rgb()`, `hsl()`, or one of the CSS / Material Design named
+ * colours. Reports the ratio and pass/fail against WCAG AA and AAA at both normal and large text
+ * sizes. If the foreground/background combination fails AA Normal (4.5:1), the tool suggests
+ * lightened or darkened variants that would pass.
+ */
+export declare const colorContrastTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Generate a colour palette from a base colour using a named harmony.
+ *
+ * @remarks
+ * Supported schemes: `complementary`, `analogous`, `triadic`, `split-complementary`,
+ * `monochromatic`. Each entry reports its hex, rgb, and hsl forms, plus the contrast ratio
+ * relative to the base colour.
+ */
+export declare const colorSchemeTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Lighten or darken a colour by a percentage of HSL lightness.
+ *
+ * @remarks
+ * `amount` is clamped to `[1, 100]`; `steps` is clamped to `[1, 10]`. With `steps > 1` the tool
+ * emits a ramp of progressively-adjusted colours, useful for generating tint/shade scales.
+ */
+export declare const colorAdjustTool: Tool<import("../../../common").SpooledArtifact>;