@theokit/sdk 5.11.1 → 5.12.0

package/dist/{chunk-GMSRRJ53.js → chunk-EEK7S77K.js}

@@ -1,5 +1,5 @@
 import { resolveChildEnv } from './chunk-HKCKOAIO.js';
-import { TheokitAgentError, ConfigurationError } from './chunk-B5MHRQJZ.js';
+import { TheokitAgentError, ConfigurationError } from './chunk-TNFOU6SB.js';
 import { execFile } from 'child_process';
 import { mkdir, writeFile } from 'fs/promises';
 import { dirname } from 'path';
@@ -161,5 +161,5 @@ var LocalSandbox = class extends SandboxBackend {
 };
 
 export { LocalSandbox, SandboxBackend, SandboxNotAvailableError, SandboxSecurityError, resolveSandbox, shellEscapePosix };
-//# sourceMappingURL=chunk-GMSRRJ53.js.map
-//# sourceMappingURL=chunk-GMSRRJ53.js.map
+//# sourceMappingURL=chunk-EEK7S77K.js.map
+//# sourceMappingURL=chunk-EEK7S77K.js.map

package/dist/{chunk-GMSRRJ53.js.map → chunk-EEK7S77K.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/sandbox/shell-escape.ts","../src/sandbox/types.ts","../src/sandbox/local-sandbox.ts"],"names":["fsWriteFile"],"mappings":"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","file":"chunk-GMSRRJ53.js","sourcesContent":["/**\n * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`\n * command string. `execute` runs via `/bin/sh -c`, so any untrusted value\n * (repo URL, ref, path) MUST be quoted to prevent command injection.\n *\n * @internal\n */\n\n/** Wrap `arg` in single quotes, escaping embedded single quotes (`'\\''`). */\nexport function shellEscapePosix(arg: string): string {\n  return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n}\n","/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nimport { ConfigurationError, TheokitAgentError } from \"../errors.js\";\nimport type { EnvPolicy } from \"../types/env-policy.js\";\nimport { shellEscapePosix } from \"./shell-escape.js\";\n\n/**\n * What a {@link SandboxBackend} returns for one command.\n *\n * `exitCode` is a coarse signal rather than the child's real exit status: the backends in this\n * package report `0` on success, `124` on timeout, and `1` for everything else — including a command\n * that exited with its own non-zero code. Read `timedOut` to tell a killed command from a failed one,\n * and `stderr` for the reason; branching on a specific exit code will not work here.\n *\n * `stdout` and `stderr` are truncated independently at `SandboxConfig.maxOutputBytes`, with a\n * trailing `...(truncated)` marker. Neither is safe to parse as a complete document without checking\n * for it.\n */\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\n/**\n * Construction-time settings shared by every {@link SandboxBackend}. All fields are optional and the\n * base constructor fills them in, so `{}` is a valid config: `workDir` `/tmp`, `timeoutMs` 30000,\n * `maxOutputBytes` 5 MiB, `env` `\"inherit-scrubbed\"`.\n *\n * `workDir` is the child process's cwd and the base a relative `uploadFile` path resolves against. It\n * is not a boundary — under `LocalSandbox` nothing stops a command, or an absolute path, from leaving\n * it. Only `LinuxSandbox` makes it enforceable.\n *\n * `timeoutMs` is the default for every call; `execute(command, { timeoutMs })` overrides it per\n * command. On expiry the child is killed and the result carries `timedOut: true` with `exitCode`\n * 124 — the partial output collected so far is still returned.\n */\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n  /**\n   * #54 — env inherit/scrub policy for the executed command's child process.\n   * Defaults to `\"inherit-scrubbed\"` (drop secret-like vars: `*KEY*`, `*SECRET*`,\n   * `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Pass `\"all\"` to restore full inheritance\n   * or `\"core\"` for a minimal safe allowlist.\n   */\n  env?: EnvPolicy;\n}\n\n/**\n * A backend refused a command on policy grounds — the environment works, and it said no. Carries a\n * stable `code: \"sandbox_security\"` for callers that prefer not to match on the class.\n *\n * Nothing in this package throws it, which is worth knowing before you write a `catch` for it:\n * `LocalSandbox` and `LinuxSandbox` report a refusal through {@link ExecuteResult} (non-zero\n * `exitCode`, reason on `stderr`), and a write blocked under confinement surfaces as a plain `Error`\n * from `uploadFile`. This type exists so a custom backend that must reject a command BEFORE spawning\n * anything — a container or VM runner enforcing its own policy — can do so in the protocol's\n * vocabulary instead of inventing an error of its own.\n */\nexport class SandboxSecurityError extends TheokitAgentError {\n  override readonly name = \"SandboxSecurityError\";\n  override readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    // not retryable: a refused command is refused every time; retrying re-asks the same question\n    super(message, { code: \"sandbox_security\", isRetryable: false });\n  }\n}\n\n/**\n * A backend cannot be used at all: its runtime is missing or unusable. The distinction from\n * {@link SandboxSecurityError} is which side failed — there the sandbox worked and denied the\n * command, here there is no sandbox. Carries `code: \"sandbox_not_available\"`.\n *\n * Nothing in this package throws it either, and that is a position rather than an oversight:\n * `createSandboxBackend` treats a missing bubblewrap as a degradation, warns once, and hands back an\n * unconfined `LocalSandbox`. Throw this instead from a backend that must never silently run outside\n * its isolation.\n */\nexport class SandboxNotAvailableError extends TheokitAgentError {\n  override readonly name = \"SandboxNotAvailableError\";\n  override readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    // not retryable: a missing runtime does not appear on a second attempt\n    super(message, { code: \"sandbox_not_available\", isRetryable: false });\n  }\n}\n\n/**\n * The execution capability handed to an agent tool, and the extension point for new environments.\n *\n * A backend implements exactly two methods, `execute` and `uploadFile`. Everything else here —\n * `readFile`, `glob`, `grep`, `listDir` — is derived from `execute` by shelling out `cat`, `find`,\n * `grep` and `ls`, so a subclass that overrides `execute` alone inherits confined reads, searches and\n * listings for free. It does not inherit confined writes: `writeFile` delegates to `uploadFile`, and\n * that is the second override `LinuxSandbox` needs.\n *\n * Choosing one: `LocalSandbox` runs the command on the host with no isolation and suits code you\n * already trust; `LinuxSandbox` adds kernel confinement where bubblewrap is available;\n * `createSandboxBackend` probes and picks between them, and is the right entry point unless you have\n * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this\n * package does not ship — write it against these two methods.\n *\n * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a\n * backend whose `execute` is not a POSIX shell must override them as well.\n */\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n      // #54 — preserve the env policy so backends can scrub secrets.\n      env: config.env ?? \"inherit-scrubbed\",\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    this.assertCommandRan(\"glob\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    // `grep` exits 1 for NO MATCH and >= 2 for an error, so a 1 is an answer and is not asserted on.\n    if (result.exitCode !== 1) this.assertCommandRan(\"grep\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    this.assertCommandRan(\"listDir\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  /**\n   * Turns \"the command did not run\" into an error instead of an empty array.\n   *\n   * `glob`, `grep` and `listDir` used to `return []` on any non-zero exit, so a search that could not\n   * run reported the same thing as a search that found nothing — opposite facts, one normal and one\n   * meaning the agent is looking at a filesystem it cannot read. That is the failure mode a backend\n   * whose `execute` is not a POSIX shell hits, which this class's own docblock warns about in prose\n   * and could not enforce.\n   *\n   * A genuine no-match is still `[]`: `find` exits 0 with empty output, and `grep`'s exit 1 is\n   * checked by its caller before this is reached.\n   */\n  private assertCommandRan(operation: string, result: ExecuteResult): void {\n    if (result.exitCode === 0) return;\n    throw new ConfigurationError(\n      `${operation} failed (exit ${String(result.exitCode)}): ${result.stderr.trim() || \"no stderr\"}. ` +\n        `The derived helpers shell out to POSIX \\`cat\\`/\\`find\\`/\\`grep\\`/\\`ls\\` — a backend whose ` +\n        `execute() is not a POSIX shell must override them.`,\n      { code: \"sandbox_derived_helper_failed\" },\n    );\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return shellEscapePosix(arg);\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one — mirrors `FilesystemProvider` / `InteractiveProvider`.\n * A resolver runs at tool-execution time (request scope), so a multi-tenant / multi-role agent gets a\n * distinct sandbox per request without a shared mutable one. This is how a tool takes execution as an\n * INJECTED capability: the same tool runs on a local sandbox, a container/E2B backend (cluster/web), or\n * any future backend, with no direct `child_process` import.\n *\n * @public\n */\nexport type SandboxProvider<Ctx = unknown> =\n  | SandboxBackend\n  | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);\n\n/** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */\nexport async function resolveSandbox<Ctx>(\n  provider: SandboxProvider<Ctx>,\n  ctx: Ctx,\n): Promise<SandboxBackend> {\n  return provider instanceof SandboxBackend ? provider : provider(ctx);\n}\n","/**\n * LocalSandbox — subprocess-based execution. **This is NOT an isolation\n * boundary.** It runs the command via `/bin/sh -c` in the SAME OS as the host\n * with the host's filesystem and network fully reachable — it provides NO\n * process, filesystem, or network isolation. Its only safety affordances are:\n *   - a wall-clock timeout (kills a runaway command),\n *   - an output-size cap (bounds memory), and\n *   - env scrubbing (#54): secret-like parent env vars (`*KEY*`/`*SECRET*`/\n *     `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`) are dropped from the child by default\n *     (`SandboxConfig.env`), so a shell tool cannot exfiltrate host secrets via\n *     the environment.\n *\n * For real isolation (untrusted code), use a container/VM backend — NOT this.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { resolveChildEnv } from \"../internal/runtime/lifecycle/env-policy.js\";\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\n/**\n * Runs a command with `/bin/sh -c` on the host. NOT an isolation boundary — the\n * module note above states exactly what it does and does not protect.\n *\n *   const sandbox = new LocalSandbox({ workDir: \"/srv/repo\", timeoutMs: 10_000 });\n *   const { stdout, exitCode, timedOut } = await sandbox.execute(\"ls -1\");\n *\n * Needs a POSIX host with `/bin/sh`. Every helper inherited from\n * {@link SandboxBackend} — `readFile`, `glob`, `grep`, `listDir` — is built on\n * this `execute`, so they inherit that requirement too.\n *\n * How it fails: `execute` NEVER rejects. Every outcome, including a failure to\n * spawn, comes back as an {@link ExecuteResult}; read `timedOut` first\n * (`true` implies `exitCode` 124) and `stderr` for the reason. `uploadFile` DOES\n * reject, with the raw `node:fs` error, on a bad path or missing permission.\n *\n * Traps:\n *  - `exitCode` is not the child's exit code. It is 0, 124 (timed out) or 1 — a\n *    command that exits 3 is reported as 1, so branching on a specific code does\n *    not work here.\n *  - Output beyond `maxOutputBytes` (default 5 MiB) makes Node kill the child.\n *    The result is `exitCode: 1` and `timedOut: false`, with the cut stream\n *    carrying the `...(truncated)` marker described on `ExecuteResult` (#363).\n *    Since `exitCode` is 1 either way, that marker is what tells a lost-output\n *    result from a command that genuinely failed.\n *  - `uploadFile` resolves a relative path against `workDir` but does not contain\n *    it: an absolute path, or one containing `..`, writes wherever the process\n *    can. `workDir` is a starting directory, not a jail.\n *  - Secret-like parent env vars are dropped by default. Passing\n *    `env: \"all\"` in {@link SandboxConfig} puts the host's API keys back within\n *    reach of any command the agent runs.\n */\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n          // #54 — scrub secret-like host env vars from the child by default.\n          env: resolveChildEnv({ policy: this.config.env }),\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    // #363 — the ONLY reliable signal that output was lost. Node caps the buffer AT `maxBuffer`, so\n    // for ASCII output the string comes back exactly at the cap and `truncateOutput`'s `> max` test\n    // never fires; a length comparison cannot tell a cut document from a complete one that happens\n    // to be that long. The child being killed for overflow can.\n    const overflowed =\n      error !== null && (error as { code?: unknown }).code === \"ERR_CHILD_PROCESS_STDIO_MAXBUFFER\";\n    return {\n      stdout: this.markIfCut(this.truncateOutput(stdout), overflowed),\n      stderr: this.markIfCut(this.truncateOutput(stderr), overflowed),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  /**\n   * Append the `...(truncated)` marker `ExecuteResult` tells callers to branch on, when the child\n   * was killed for exceeding `maxOutputBytes` and this stream is the one sitting at the cap.\n   *\n   * `truncateOutput` has already run, so an output it marked is left alone rather than marked\n   * twice. Node does not say WHICH stream overflowed, so the stream at the cap is the one that\n   * lost data — the other, being shorter, is complete.\n   */\n  private markIfCut(output: string, overflowed: boolean): string {\n    if (!overflowed) return output;\n    if (output.endsWith(\"...(truncated)\")) return output;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    return Buffer.byteLength(output) >= max ? `${output}\\n...(truncated)` : output;\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n"]}
+{"version":3,"sources":["../src/sandbox/shell-escape.ts","../src/sandbox/types.ts","../src/sandbox/local-sandbox.ts"],"names":["fsWriteFile"],"mappings":"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","file":"chunk-EEK7S77K.js","sourcesContent":["/**\n * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`\n * command string. `execute` runs via `/bin/sh -c`, so any untrusted value\n * (repo URL, ref, path) MUST be quoted to prevent command injection.\n *\n * @internal\n */\n\n/** Wrap `arg` in single quotes, escaping embedded single quotes (`'\\''`). */\nexport function shellEscapePosix(arg: string): string {\n  return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n}\n","/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nimport { ConfigurationError, TheokitAgentError } from \"../errors.js\";\nimport type { EnvPolicy } from \"../types/env-policy.js\";\nimport { shellEscapePosix } from \"./shell-escape.js\";\n\n/**\n * What a {@link SandboxBackend} returns for one command.\n *\n * `exitCode` is a coarse signal rather than the child's real exit status: the backends in this\n * package report `0` on success, `124` on timeout, and `1` for everything else — including a command\n * that exited with its own non-zero code. Read `timedOut` to tell a killed command from a failed one,\n * and `stderr` for the reason; branching on a specific exit code will not work here.\n *\n * `stdout` and `stderr` are truncated independently at `SandboxConfig.maxOutputBytes`, with a\n * trailing `...(truncated)` marker. Neither is safe to parse as a complete document without checking\n * for it.\n */\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\n/**\n * Construction-time settings shared by every {@link SandboxBackend}. All fields are optional and the\n * base constructor fills them in, so `{}` is a valid config: `workDir` `/tmp`, `timeoutMs` 30000,\n * `maxOutputBytes` 5 MiB, `env` `\"inherit-scrubbed\"`.\n *\n * `workDir` is the child process's cwd and the base a relative `uploadFile` path resolves against. It\n * is not a boundary — under `LocalSandbox` nothing stops a command, or an absolute path, from leaving\n * it. Only `LinuxSandbox` makes it enforceable.\n *\n * `timeoutMs` is the default for every call; `execute(command, { timeoutMs })` overrides it per\n * command. On expiry the child is killed and the result carries `timedOut: true` with `exitCode`\n * 124 — the partial output collected so far is still returned.\n */\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n  /**\n   * #54 — env inherit/scrub policy for the executed command's child process.\n   * Defaults to `\"inherit-scrubbed\"` (drop secret-like vars: `*KEY*`, `*SECRET*`,\n   * `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Pass `\"all\"` to restore full inheritance\n   * or `\"core\"` for a minimal safe allowlist.\n   */\n  env?: EnvPolicy;\n}\n\n/**\n * A backend refused a command on policy grounds — the environment works, and it said no. Carries a\n * stable `code: \"sandbox_security\"` for callers that prefer not to match on the class.\n *\n * Nothing in this package throws it, which is worth knowing before you write a `catch` for it:\n * `LocalSandbox` and `LinuxSandbox` report a refusal through {@link ExecuteResult} (non-zero\n * `exitCode`, reason on `stderr`), and a write blocked under confinement surfaces as a plain `Error`\n * from `uploadFile`. This type exists so a custom backend that must reject a command BEFORE spawning\n * anything — a container or VM runner enforcing its own policy — can do so in the protocol's\n * vocabulary instead of inventing an error of its own.\n */\nexport class SandboxSecurityError extends TheokitAgentError {\n  override readonly name = \"SandboxSecurityError\";\n  override readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    // not retryable: a refused command is refused every time; retrying re-asks the same question\n    super(message, { code: \"sandbox_security\", isRetryable: false });\n  }\n}\n\n/**\n * A backend cannot be used at all: its runtime is missing or unusable. The distinction from\n * {@link SandboxSecurityError} is which side failed — there the sandbox worked and denied the\n * command, here there is no sandbox. Carries `code: \"sandbox_not_available\"`.\n *\n * Nothing in this package throws it either, and that is a position rather than an oversight:\n * `createSandboxBackend` treats a missing bubblewrap as a degradation, warns once, and hands back an\n * unconfined `LocalSandbox`. Throw this instead from a backend that must never silently run outside\n * its isolation.\n */\nexport class SandboxNotAvailableError extends TheokitAgentError {\n  override readonly name = \"SandboxNotAvailableError\";\n  override readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    // not retryable: a missing runtime does not appear on a second attempt\n    super(message, { code: \"sandbox_not_available\", isRetryable: false });\n  }\n}\n\n/**\n * The execution capability handed to an agent tool, and the extension point for new environments.\n *\n * A backend implements exactly two methods, `execute` and `uploadFile`. Everything else here —\n * `readFile`, `glob`, `grep`, `listDir` — is derived from `execute` by shelling out `cat`, `find`,\n * `grep` and `ls`, so a subclass that overrides `execute` alone inherits confined reads, searches and\n * listings for free. It does not inherit confined writes: `writeFile` delegates to `uploadFile`, and\n * that is the second override `LinuxSandbox` needs.\n *\n * Choosing one: `LocalSandbox` runs the command on the host with no isolation and suits code you\n * already trust; `LinuxSandbox` adds kernel confinement where bubblewrap is available;\n * `createSandboxBackend` probes and picks between them, and is the right entry point unless you have\n * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this\n * package does not ship — write it against these two methods.\n *\n * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a\n * backend whose `execute` is not a POSIX shell must override them as well.\n */\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n      // #54 — preserve the env policy so backends can scrub secrets.\n      env: config.env ?? \"inherit-scrubbed\",\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    this.assertCommandRan(\"glob\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    // `grep` exits 1 for NO MATCH and >= 2 for an error, so a 1 is an answer and is not asserted on.\n    if (result.exitCode !== 1) this.assertCommandRan(\"grep\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    this.assertCommandRan(\"listDir\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  /**\n   * Turns \"the command did not run\" into an error instead of an empty array.\n   *\n   * `glob`, `grep` and `listDir` used to `return []` on any non-zero exit, so a search that could not\n   * run reported the same thing as a search that found nothing — opposite facts, one normal and one\n   * meaning the agent is looking at a filesystem it cannot read. That is the failure mode a backend\n   * whose `execute` is not a POSIX shell hits, which this class's own docblock warns about in prose\n   * and could not enforce.\n   *\n   * A genuine no-match is still `[]`: `find` exits 0 with empty output, and `grep`'s exit 1 is\n   * checked by its caller before this is reached.\n   */\n  private assertCommandRan(operation: string, result: ExecuteResult): void {\n    if (result.exitCode === 0) return;\n    throw new ConfigurationError(\n      `${operation} failed (exit ${String(result.exitCode)}): ${result.stderr.trim() || \"no stderr\"}. ` +\n        `The derived helpers shell out to POSIX \\`cat\\`/\\`find\\`/\\`grep\\`/\\`ls\\` — a backend whose ` +\n        `execute() is not a POSIX shell must override them.`,\n      { code: \"sandbox_derived_helper_failed\" },\n    );\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return shellEscapePosix(arg);\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one — mirrors `FilesystemProvider` / `InteractiveProvider`.\n * A resolver runs at tool-execution time (request scope), so a multi-tenant / multi-role agent gets a\n * distinct sandbox per request without a shared mutable one. This is how a tool takes execution as an\n * INJECTED capability: the same tool runs on a local sandbox, a container/E2B backend (cluster/web), or\n * any future backend, with no direct `child_process` import.\n *\n * @public\n */\nexport type SandboxProvider<Ctx = unknown> =\n  | SandboxBackend\n  | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);\n\n/** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */\nexport async function resolveSandbox<Ctx>(\n  provider: SandboxProvider<Ctx>,\n  ctx: Ctx,\n): Promise<SandboxBackend> {\n  return provider instanceof SandboxBackend ? provider : provider(ctx);\n}\n","/**\n * LocalSandbox — subprocess-based execution. **This is NOT an isolation\n * boundary.** It runs the command via `/bin/sh -c` in the SAME OS as the host\n * with the host's filesystem and network fully reachable — it provides NO\n * process, filesystem, or network isolation. Its only safety affordances are:\n *   - a wall-clock timeout (kills a runaway command),\n *   - an output-size cap (bounds memory), and\n *   - env scrubbing (#54): secret-like parent env vars (`*KEY*`/`*SECRET*`/\n *     `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`) are dropped from the child by default\n *     (`SandboxConfig.env`), so a shell tool cannot exfiltrate host secrets via\n *     the environment.\n *\n * For real isolation (untrusted code), use a container/VM backend — NOT this.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { resolveChildEnv } from \"../internal/runtime/lifecycle/env-policy.js\";\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\n/**\n * Runs a command with `/bin/sh -c` on the host. NOT an isolation boundary — the\n * module note above states exactly what it does and does not protect.\n *\n *   const sandbox = new LocalSandbox({ workDir: \"/srv/repo\", timeoutMs: 10_000 });\n *   const { stdout, exitCode, timedOut } = await sandbox.execute(\"ls -1\");\n *\n * Needs a POSIX host with `/bin/sh`. Every helper inherited from\n * {@link SandboxBackend} — `readFile`, `glob`, `grep`, `listDir` — is built on\n * this `execute`, so they inherit that requirement too.\n *\n * How it fails: `execute` NEVER rejects. Every outcome, including a failure to\n * spawn, comes back as an {@link ExecuteResult}; read `timedOut` first\n * (`true` implies `exitCode` 124) and `stderr` for the reason. `uploadFile` DOES\n * reject, with the raw `node:fs` error, on a bad path or missing permission.\n *\n * Traps:\n *  - `exitCode` is not the child's exit code. It is 0, 124 (timed out) or 1 — a\n *    command that exits 3 is reported as 1, so branching on a specific code does\n *    not work here.\n *  - Output beyond `maxOutputBytes` (default 5 MiB) makes Node kill the child.\n *    The result is `exitCode: 1` and `timedOut: false`, with the cut stream\n *    carrying the `...(truncated)` marker described on `ExecuteResult` (#363).\n *    Since `exitCode` is 1 either way, that marker is what tells a lost-output\n *    result from a command that genuinely failed.\n *  - `uploadFile` resolves a relative path against `workDir` but does not contain\n *    it: an absolute path, or one containing `..`, writes wherever the process\n *    can. `workDir` is a starting directory, not a jail.\n *  - Secret-like parent env vars are dropped by default. Passing\n *    `env: \"all\"` in {@link SandboxConfig} puts the host's API keys back within\n *    reach of any command the agent runs.\n */\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n          // #54 — scrub secret-like host env vars from the child by default.\n          env: resolveChildEnv({ policy: this.config.env }),\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    // #363 — the ONLY reliable signal that output was lost. Node caps the buffer AT `maxBuffer`, so\n    // for ASCII output the string comes back exactly at the cap and `truncateOutput`'s `> max` test\n    // never fires; a length comparison cannot tell a cut document from a complete one that happens\n    // to be that long. The child being killed for overflow can.\n    const overflowed =\n      error !== null && (error as { code?: unknown }).code === \"ERR_CHILD_PROCESS_STDIO_MAXBUFFER\";\n    return {\n      stdout: this.markIfCut(this.truncateOutput(stdout), overflowed),\n      stderr: this.markIfCut(this.truncateOutput(stderr), overflowed),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  /**\n   * Append the `...(truncated)` marker `ExecuteResult` tells callers to branch on, when the child\n   * was killed for exceeding `maxOutputBytes` and this stream is the one sitting at the cap.\n   *\n   * `truncateOutput` has already run, so an output it marked is left alone rather than marked\n   * twice. Node does not say WHICH stream overflowed, so the stream at the cap is the one that\n   * lost data — the other, being shorter, is complete.\n   */\n  private markIfCut(output: string, overflowed: boolean): string {\n    if (!overflowed) return output;\n    if (output.endsWith(\"...(truncated)\")) return output;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    return Buffer.byteLength(output) >= max ? `${output}\\n...(truncated)` : output;\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n"]}

package/dist/{chunk-NKIQTLFA.cjs → chunk-EQ5IDL6W.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunkUNFBHV46_cjs = require('./chunk-UNFBHV46.cjs');
+var chunkCEGU5AVD_cjs = require('./chunk-CEGU5AVD.cjs');
 var fs = require('fs');
 var os = require('os');
 
-var SessionBusyError = class extends chunkUNFBHV46_cjs.TheokitAgentError {
+var SessionBusyError = class extends chunkCEGU5AVD_cjs.TheokitAgentError {
   constructor(sessionPath) {
     super(
       `another process is already writing this session: ${sessionPath}. Fork it to a new id instead of appending \u2014 two writers interleave lines into a sequence that parses but is not what either process wrote.`,
@@ -107,5 +107,5 @@ function createLease(sessionPath, lockPath) {
 exports.SessionBusyError = SessionBusyError;
 exports.acquireSessionWriter = acquireSessionWriter;
 exports.sessionHasWriter = sessionHasWriter;
-//# sourceMappingURL=chunk-NKIQTLFA.cjs.map
-//# sourceMappingURL=chunk-NKIQTLFA.cjs.map
+//# sourceMappingURL=chunk-EQ5IDL6W.cjs.map
+//# sourceMappingURL=chunk-EQ5IDL6W.cjs.map

package/dist/{chunk-NKIQTLFA.cjs.map → chunk-EQ5IDL6W.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/session-writer.ts"],"names":["TheokitAgentError","hostname","openSync","writeSync","fchmodSync","closeSync","readFileSync","existsSync","rmSync"],"mappings":";;;;;;AAmDO,IAAM,gBAAA,GAAN,cAA+BA,mCAAA,CAAkB;AAAA,EAGtD,YAAqB,WAAA,EAAqB;AACxC,IAAA,KAAA;AAAA,MACE,oDAAoD,WAAW,CAAA,gJAAA,CAAA;AAAA,MAG/D,EAAE,IAAA,EAAM,cAAA,EAAgB,WAAA,EAAa,KAAA;AAAM,KAC7C;AANmB,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AAAA,EAOrB;AAAA,EAPqB,WAAA;AAAA,EAFH,IAAA,GAAO,kBAAA;AAU3B;AA0CO,IAAM,mBAAA,GAAsB,GAAA;AAUnC,SAAS,QAAA,GAAsB;AAC7B,EAAA,OAAO,EAAE,GAAA,EAAK,OAAA,CAAQ,GAAA,EAAK,QAAA,EAAUC,aAAS,EAAG,KAAA,EAAO,IAAA,CAAK,GAAA,EAAI,EAAE;AACrE;AAWA,SAAS,UAAA,CAAW,UAAkB,KAAA,EAAwB;AAC5D,EAAA,MAAM,EAAA,GAAKC,WAAA,CAAS,QAAA,EAAU,GAAA,EAAK,GAAK,CAAA;AACxC,EAAA,IAAI;AACF,IAAAC,YAAA,CAAU,EAAA,EAAI,IAAA,CAAK,SAAA,CAAU,KAAK,CAAC,CAAA;AAInC,IAAAC,aAAA,CAAW,IAAI,GAAK,CAAA;AAAA,EACtB,CAAA,SAAE;AACA,IAAAC,YAAA,CAAU,EAAE,CAAA;AAAA,EACd;AACF;AAGA,SAAS,UAAU,QAAA,EAAyC;AAC1D,EAAA,IAAI,GAAA;AACJ,EAAA,IAAI;AACF,IAAA,GAAA,GAAMC,eAAA,CAAa,UAAU,MAAM,CAAA;AAAA,EACrC,SAAS,GAAA,EAAK;AACZ,IAAA,MAAM,OAAQ,GAAA,CAA8B,IAAA;AAE5C,IAAA,IAAI,IAAA,KAAS,UAAU,OAAO,MAAA;AAO9B,IAAA,IAAI,IAAA,KAAS,UAAU,OAAO,MAAA;AAQ9B,IAAA,MAAM,IAAI,gBAAA,CAAiB,QAAA,CAAS,OAAA,CAAQ,iBAAA,EAAmB,EAAE,CAAC,CAAA;AAAA,EACpE;AACA,EAAA,IAAI;AACF,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA;AACxB,IAAA,IACE,OAAO,CAAA,CAAE,GAAA,KAAQ,QAAA,IACjB,OAAO,CAAA,CAAE,QAAA,KAAa,QAAA,IACtB,OAAO,CAAA,CAAE,KAAA,KAAU,QAAA,EACnB;AACA,MAAA,OAAO,KAAA,CAAA;AAAA,IACT;AACA,IAAA,OAAO,EAAE,KAAK,CAAA,CAAE,GAAA,EAAK,UAAU,CAAA,CAAE,QAAA,EAAU,KAAA,EAAO,CAAA,CAAE,KAAA,EAAM;AAAA,EAC5D,CAAA,CAAA,MAAQ;AAGN,IAAA,OAAO,MAAA;AAAA,EACT;AACF;AAGA,SAAS,aAAa,GAAA,EAAsB;AAC1C,EAAA,IAAI;AACF,IAAA,OAAA,CAAQ,IAAA,CAAK,KAAK,CAAC,CAAA;AACnB,IAAA,OAAO,IAAA;AAAA,EACT,SAAS,GAAA,EAAK;AAEZ,IAAA,OAAQ,IAA8B,IAAA,KAAS,OAAA;AAAA,EACjD;AACF;AAwBA,SAAS,YAAY,KAAA,EAAuC;AAC1D,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,IAAA;AAChC,EAAA,IAAI,KAAA,CAAM,QAAA,KAAaL,WAAA,EAAS,EAAG;AACjC,IAAA,OAAO,IAAA,CAAK,GAAA,EAAI,GAAI,KAAA,CAAM,KAAA,GAAQ,mBAAA;AAAA,EACpC;AACA,EAAA,OAAO,CAAC,YAAA,CAAa,KAAA,CAAM,GAAG,CAAA;AAChC;AAcO,SAAS,iBAAiB,WAAA,EAA8B;AAC7D,EAAA,MAAM,QAAA,GAAW,GAAG,WAAW,CAAA,YAAA,CAAA;AAC/B,EAAA,IAAI,CAACM,aAAA,CAAW,QAAQ,CAAA,EAAG,OAAO,KAAA;AAClC,EAAA,IAAI;AACF,IAAA,OAAO,CAAC,WAAA,CAAY,SAAA,CAAU,QAAQ,CAAC,CAAA;AAAA,EACzC,CAAA,CAAA,MAAQ;AAGN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AASA,eAAsB,qBAAqB,WAAA,EAAkD;AAU3F,EAAA,MAAM,QAAA,GAAW,GAAG,WAAW,CAAA,YAAA,CAAA;AAC/B,EAAA,MAAM,OAAkB,QAAA,EAAS;AACjC,EAAA,IAAI,EAAA;AACJ,EAAA,IAAI;AAEF,IAAA,EAAA,GAAKL,WAAA,CAAS,QAAA,EAAU,IAAA,EAAM,GAAK,CAAA;AAAA,EACrC,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,IAAA,KAAS,QAAA,EAAU,MAAM,GAAA;AAI5D,IAAA,IAAI,CAAC,YAAY,SAAA,CAAU,QAAQ,CAAC,CAAA,EAAG,MAAM,IAAI,gBAAA,CAAiB,WAAW,CAAA;AAC7E,IAAA,UAAA,CAAW,UAAU,IAAI,CAAA;AACzB,IAAA,OAAO,WAAA,CAAY,aAAa,QAAQ,CAAA;AAAA,EAC1C;AACA,EAAAG,YAAA,CAAU,EAAE,CAAA;AACZ,EAAA,UAAA,CAAW,UAAU,IAAI,CAAA;AAEzB,EAAA,OAAO,WAAA,CAAY,aAAa,QAAQ,CAAA;AAC1C;AAGA,SAAS,WAAA,CAAY,aAAqB,QAAA,EAAsC;AAC9E,EAAA,IAAI,QAAA,GAAW,KAAA;AACf,EAAA,OAAO;AAAA,IACL,WAAA;AAAA,IACA,SAAS,YAA2B;AAClC,MAAA,IAAI,QAAA,EAAU;AACd,MAAA,QAAA,GAAW,IAAA;AACX,MAAAG,SAAA,CAAO,QAAA,EAAU,EAAE,KAAA,EAAO,IAAA,EAAM,CAAA;AAAA,IAClC,CAAA;AAAA,IACA,OAAO,MAAY;AAIjB,MAAA,IAAI,QAAA,EAAU;AACd,MAAA,UAAA,CAAW,QAAA,EAAU,UAAU,CAAA;AAAA,IACjC;AAAA,GACF;AACF","file":"chunk-NKIQTLFA.cjs","sourcesContent":["/**\n * M81 — single-writer lease for a session transcript.\n *\n * ## The problem\n *\n * Nothing stops two processes appending to the same JSONL transcript. The concrete case: `exec\n * resume --last` can write into the TUI's live session. Two interleaved appends to an append-only\n * file produce lines that are each individually valid and whose SEQUENCE is fiction — and nothing\n * reports it, because every line parses.\n *\n * ## Why an exclusive lockfile rather than `withFileLock`\n *\n * The plan's ADR D2 said to compose `withFileLock`, and that was the right instinct — do not build a\n * second lock mechanism. It turned out not to fit the SHAPE: `withFileLock(path, fn)` is\n * scope-based — it holds the lock for the duration of a callback. A session lease is **held across\n * turns**, for as long as the process owns the session, with an explicit `release()`. Wrapping the\n * whole session lifetime in a callback would invert control of the entire agent loop.\n *\n * So this uses the same underlying primitive `withFileLock` uses (an exclusive-create lockfile,\n * `wx`) with lease semantics on top. That keeps the mechanism single — the file-existence lock —\n * while giving it the lifetime the caller needs. The deviation from D2 is recorded here because the\n * plan's rationale (no second mechanism) still holds; only its shape assumption did not.\n *\n * ## Fail fast, never wait\n *\n * A second writer that WAITED would block `exec` behind a TUI session that can last hours. The typed\n * error lets the caller choose: fork to a new id, or give up with a real diagnosis.\n *\n * @internal\n */\n\nimport {\n  closeSync,\n  existsSync,\n  fchmodSync,\n  openSync,\n  readFileSync,\n  rmSync,\n  writeSync,\n} from \"node:fs\";\nimport { hostname } from \"node:os\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — another process already holds the writer lease for this session.\n *\n * Carries `sessionPath` because knowing WHICH session is busy is what lets the caller decide between\n * forking and waiting for the user to close the TUI (`rules/error-handling.md § 2` — context enough\n * to act on).\n */\nexport class SessionBusyError extends TheokitAgentError {\n  override readonly name = \"SessionBusyError\";\n\n  constructor(readonly sessionPath: string) {\n    super(\n      `another process is already writing this session: ${sessionPath}. ` +\n        \"Fork it to a new id instead of appending — two writers interleave lines into a sequence \" +\n        \"that parses but is not what either process wrote.\",\n      { code: \"session_busy\", isRetryable: false },\n    );\n  }\n}\n\n/** A held writer lease. `release()` is idempotent. */\nexport interface SessionWriterLease {\n  readonly sessionPath: string;\n  release(): Promise<void>;\n  /**\n   * Re-stamp the ownership record, so a **live** owner never crosses the staleness window.\n   *\n   * Idempotent and cheap: one `write` of a ~80-byte JSON. Call it on the path that already writes to\n   * the session — appending a turn — and the cross-host window stops being a lie about liveness.\n   *\n   * A no-op after `release()`: renewing a lease you no longer hold would re-create the lock file and\n   * hand this process ownership it gave up. That is the one direction of this API that could\n   * *create* the double-writer it exists to prevent.\n   */\n  renew(): void;\n}\n\n/**\n * Staleness window **between machines** — and only between them.\n *\n * 30 s from ACQUISITION. Calling it a \"heartbeat\" would be a lie: the record is written once, when\n * the lease is taken, and is **not** renewed on every write. An earlier version of this comment\n * claimed \"the owner touches the file on every acquisition, so a live process never crosses the\n * window\" — false twice over, and adversarial review measured both.\n *\n * On the **same host** this does not matter: `reclaimable` decides by `pid`, which is exact, and age\n * never enters the calculation. Across hosts it does matter, and it is a real limit: a **live**\n * remote owner loses the lease after 30 s, because there is no way to ask another machine whether\n * its process still exists.\n *\n * **The residue is now closable by the caller** (`agent-builder#118`). `SessionWriterLease.renew()`\n * re-stamps the record; calling it on the path that already writes to the session — appending a turn\n * — keeps a live owner from ever crossing the window. It costs one `write` of ~80 bytes on a file\n * that was previously written once per session.\n *\n * It is `renew()` and not an internal timer on purpose. A timer inside the lease would keep the event\n * loop alive (or need `unref` plus its own teardown), and it would renew a lease belonging to a\n * process that is hung rather than working — which is precisely the state the window exists to\n * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.\n */\nexport const HEARTBEAT_WINDOW_MS = 30_000;\n\n/** Who holds the lock. Written as JSON into `.writer.lock`. */\ninterface LockOwner {\n  pid: number;\n  hostname: string;\n  mtime: number;\n}\n\n/** The ownership record for THIS process, stamped now. One place, so acquire and renew cannot drift. */\nfunction ownerNow(): LockOwner {\n  return { pid: process.pid, hostname: hostname(), mtime: Date.now() };\n}\n\n/**\n * Writes the owner with user-only permissions.\n *\n * `0600` because the lock is an assertion of OWNERSHIP: with the `0664` the usual umask produces,\n * another user in the same group can overwrite the file and forge ownership of the session — and\n * from then on it is the legitimate owner who starts receiving `SessionBusyError`. The content\n * (`pid`, `hostname`) is low-sensitivity; what the permission protects is the signal's\n * **integrity**, not its secrecy.\n */\nfunction writeOwner(lockPath: string, owner: LockOwner): void {\n  const fd = openSync(lockPath, \"w\", 0o600);\n  try {\n    writeSync(fd, JSON.stringify(owner));\n    // `open`'s `mode` only applies on CREATION. A `.writer.lock` inherited from an earlier version —\n    // or left behind by a process with a different umask — would stay `0664` after being reclaimed,\n    // and the forgery window the mode closes for new locks would remain open for old ones.\n    fchmodSync(fd, 0o600);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Reads the lock's owner. `undefined` when the file vanished or the content is unreadable. */\nfunction readOwner(lockPath: string): LockOwner | undefined {\n  let raw: string;\n  try {\n    raw = readFileSync(lockPath, \"utf8\");\n  } catch (err) {\n    const code = (err as NodeJS.ErrnoException).code;\n    // `ENOENT` — vanished between the `EEXIST` and the read. Benign race: the lock is gone.\n    if (code === \"ENOENT\") return undefined;\n    // `EISDIR` — the lock path is a DIRECTORY. No process in this library creates one; it is debris\n    // from something else, and it will never become a readable lock. Failing closed here would lock\n    // the session out forever. Treated as owner-less: acquisition proceeds and fails with the real\n    // FS error, which says what is wrong — instead of a permanent SessionBusyError that says\n    // nothing. It is NOT \"reclaimable\": the lock is not removed, and the caller proceeds without a\n    // lease.\n    if (code === \"EISDIR\") return undefined;\n    // Any other read failure (`EACCES` in a shared directory, `EIO`) differs in kind: the lock\n    // **exists** and it is we who cannot read the owner. Treating it as free would let two writers\n    // coexist — precisely what the lease exists to prevent — and the `0600` that protects the lock\n    // against forgery WIDENS that surface: in a shared directory, another user's lock is unreadable\n    // by design.\n    //\n    // Not knowing who the owner is differs from there being no owner. Fail closed.\n    throw new SessionBusyError(lockPath.replace(/\\.writer\\.lock$/, \"\"));\n  }\n  try {\n    const d = JSON.parse(raw) as Partial<LockOwner>;\n    if (\n      typeof d.pid !== \"number\" ||\n      typeof d.hostname !== \"string\" ||\n      typeof d.mtime !== \"number\"\n    ) {\n      return undefined;\n    }\n    return { pid: d.pid, hostname: d.hostname, mtime: d.mtime };\n  } catch {\n    // Unreadable JSON: a lock nobody can interpret must not lock the session out forever. Treating\n    // it as stale is the recoverable choice; the cost is the same as that of an old lock.\n    return undefined;\n  }\n}\n\n/** Does the process exist? `signal 0` sends nothing — it only queries permission/existence. */\nfunction processAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (err) {\n    // EPERM means it EXISTS and belongs to another user.\n    return (err as NodeJS.ErrnoException).code === \"EPERM\";\n  }\n}\n\n/**\n * Can the lock be taken from whoever holds it?\n *\n * ADR-2 of the plan: reclaiming by `pid` alone has a false positive across machines — the same\n * number exists on another host, pointing at an unrelated process. So:\n *\n * - **same host:** the `pid` is authoritative, and it **alone**. Dead process => reclaimable at\n *   once; live process => never, however old the lock is.\n * - **other host:** the `pid` says nothing here. Only the heartbeat window counts, because it is\n *   the one signal that does not lie across machines.\n *\n * ## Why age does NOT count on the same host\n *\n * The first version did `stale || !processAlive(pid)`, and that was a serious defect: `mtime` is\n * written at **acquisition** and is not touched on each append, so any session lasting longer than\n * the window — that is, **every real session** — became stealable by another process. Two writers\n * on the same transcript is exactly what the lease exists to prevent.\n *\n * On the same host the question \"does the owner still exist?\" has an exact answer, and age adds no\n * information to it — only a way to be wrong. Keeping the window there would be heuristic layered\n * on top of a fact.\n */\nfunction reclaimable(owner: LockOwner | undefined): boolean {\n  if (owner === undefined) return true; // unreadable or vanished\n  if (owner.hostname !== hostname()) {\n    return Date.now() - owner.mtime > HEARTBEAT_WINDOW_MS;\n  }\n  return !processAlive(owner.pid);\n}\n\n/**\n * Does the session have a writer **right now**? A query that does NOT take the lease.\n *\n * M95 — it exists because asking by taking creates the very contention it meant to detect: two\n * processes querying a **free** session at the same time made one of them lose, and the consumer\n * forked for no reason. Measured in adversarial review: `RACE: spurious forks = 1`.\n *\n * It is a snapshot, not a guarantee: between the query and the real acquisition someone may take\n * the session. Callers needing the guarantee use {@link acquireSessionWriter}; callers needing to\n * **decide an id before opening anything** use this, and handle the race where it shows up.\n *\n */\nexport function sessionHasWriter(sessionPath: string): boolean {\n  const lockPath = `${sessionPath}.writer.lock`;\n  if (!existsSync(lockPath)) return false;\n  try {\n    return !reclaimable(readOwner(lockPath));\n  } catch {\n    // `readOwner` throws when the lock exists and cannot be read — fail closed, for the same reason\n    // as there: not knowing who the owner is differs from there being no owner.\n    return true;\n  }\n}\n\n/**\n * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.\n *\n * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the\n * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across\n * processes, not just across async tasks in one process.\n */\nexport async function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease> {\n  // M95 — `.writer.lock`, NOT `.lock`.\n  //\n  // `withFileLock(path, fn)` already uses `<path>.lock` as its companion. While the lease was called\n  // from nowhere (the defect this milestone fixes) the collision was theoretical; wiring it to the\n  // same file would make the long-lived lease block every short critical section on the same path.\n  //\n  // Two files because they are two things: `withFileLock` protects a section with a start and an\n  // end; the lease is OWNERSHIP, held across turns, with an explicit `release()` — the distinction\n  // the M81 docstring above already explains.\n  const lockPath = `${sessionPath}.writer.lock`;\n  const mine: LockOwner = ownerNow();\n  let fd: number;\n  try {\n    // The mode applies on CREATION — the `w` in `writeOwner` does not alter an existing file.\n    fd = openSync(lockPath, \"wx\", 0o600);\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"EEXIST\") throw err;\n    // M95 — the lock exists. Until now that alone was enough to refuse, and that was the defect: a\n    // TUI killed by SIGKILL locked the user out of their own session PERMANENTLY, with no documented\n    // recovery path. Now the lock says who the owner is, and a dead owner yields its place.\n    if (!reclaimable(readOwner(lockPath))) throw new SessionBusyError(sessionPath);\n    writeOwner(lockPath, mine);\n    return createLease(sessionPath, lockPath);\n  }\n  closeSync(fd);\n  writeOwner(lockPath, mine);\n\n  return createLease(sessionPath, lockPath);\n}\n\n/** The lease itself — idempotent `release()`. Extracted because acquisition has two exit paths. */\nfunction createLease(sessionPath: string, lockPath: string): SessionWriterLease {\n  let released = false;\n  return {\n    sessionPath,\n    release: async (): Promise<void> => {\n      if (released) return;\n      released = true;\n      rmSync(lockPath, { force: true });\n    },\n    renew: (): void => {\n      // A released lease does not own the lock. Re-stamping here would RE-CREATE the file and give\n      // this process ownership it explicitly gave up — the one way this method could manufacture the\n      // double-writer the lease exists to prevent.\n      if (released) return;\n      writeOwner(lockPath, ownerNow());\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/session-writer.ts"],"names":["TheokitAgentError","hostname","openSync","writeSync","fchmodSync","closeSync","readFileSync","existsSync","rmSync"],"mappings":"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","file":"chunk-EQ5IDL6W.cjs","sourcesContent":["/**\n * M81 — single-writer lease for a session transcript.\n *\n * ## The problem\n *\n * Nothing stops two processes appending to the same JSONL transcript. The concrete case: `exec\n * resume --last` can write into the TUI's live session. Two interleaved appends to an append-only\n * file produce lines that are each individually valid and whose SEQUENCE is fiction — and nothing\n * reports it, because every line parses.\n *\n * ## Why an exclusive lockfile rather than `withFileLock`\n *\n * The plan's ADR D2 said to compose `withFileLock`, and that was the right instinct — do not build a\n * second lock mechanism. It turned out not to fit the SHAPE: `withFileLock(path, fn)` is\n * scope-based — it holds the lock for the duration of a callback. A session lease is **held across\n * turns**, for as long as the process owns the session, with an explicit `release()`. Wrapping the\n * whole session lifetime in a callback would invert control of the entire agent loop.\n *\n * So this uses the same underlying primitive `withFileLock` uses (an exclusive-create lockfile,\n * `wx`) with lease semantics on top. That keeps the mechanism single — the file-existence lock —\n * while giving it the lifetime the caller needs. The deviation from D2 is recorded here because the\n * plan's rationale (no second mechanism) still holds; only its shape assumption did not.\n *\n * ## Fail fast, never wait\n *\n * A second writer that WAITED would block `exec` behind a TUI session that can last hours. The typed\n * error lets the caller choose: fork to a new id, or give up with a real diagnosis.\n *\n * @internal\n */\n\nimport {\n  closeSync,\n  existsSync,\n  fchmodSync,\n  openSync,\n  readFileSync,\n  rmSync,\n  writeSync,\n} from \"node:fs\";\nimport { hostname } from \"node:os\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — another process already holds the writer lease for this session.\n *\n * Carries `sessionPath` because knowing WHICH session is busy is what lets the caller decide between\n * forking and waiting for the user to close the TUI (`rules/error-handling.md § 2` — context enough\n * to act on).\n */\nexport class SessionBusyError extends TheokitAgentError {\n  override readonly name = \"SessionBusyError\";\n\n  constructor(readonly sessionPath: string) {\n    super(\n      `another process is already writing this session: ${sessionPath}. ` +\n        \"Fork it to a new id instead of appending — two writers interleave lines into a sequence \" +\n        \"that parses but is not what either process wrote.\",\n      { code: \"session_busy\", isRetryable: false },\n    );\n  }\n}\n\n/** A held writer lease. `release()` is idempotent. */\nexport interface SessionWriterLease {\n  readonly sessionPath: string;\n  release(): Promise<void>;\n  /**\n   * Re-stamp the ownership record, so a **live** owner never crosses the staleness window.\n   *\n   * Idempotent and cheap: one `write` of a ~80-byte JSON. Call it on the path that already writes to\n   * the session — appending a turn — and the cross-host window stops being a lie about liveness.\n   *\n   * A no-op after `release()`: renewing a lease you no longer hold would re-create the lock file and\n   * hand this process ownership it gave up. That is the one direction of this API that could\n   * *create* the double-writer it exists to prevent.\n   */\n  renew(): void;\n}\n\n/**\n * Staleness window **between machines** — and only between them.\n *\n * 30 s from ACQUISITION. Calling it a \"heartbeat\" would be a lie: the record is written once, when\n * the lease is taken, and is **not** renewed on every write. An earlier version of this comment\n * claimed \"the owner touches the file on every acquisition, so a live process never crosses the\n * window\" — false twice over, and adversarial review measured both.\n *\n * On the **same host** this does not matter: `reclaimable` decides by `pid`, which is exact, and age\n * never enters the calculation. Across hosts it does matter, and it is a real limit: a **live**\n * remote owner loses the lease after 30 s, because there is no way to ask another machine whether\n * its process still exists.\n *\n * **The residue is now closable by the caller** (`agent-builder#118`). `SessionWriterLease.renew()`\n * re-stamps the record; calling it on the path that already writes to the session — appending a turn\n * — keeps a live owner from ever crossing the window. It costs one `write` of ~80 bytes on a file\n * that was previously written once per session.\n *\n * It is `renew()` and not an internal timer on purpose. A timer inside the lease would keep the event\n * loop alive (or need `unref` plus its own teardown), and it would renew a lease belonging to a\n * process that is hung rather than working — which is precisely the state the window exists to\n * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.\n */\nexport const HEARTBEAT_WINDOW_MS = 30_000;\n\n/** Who holds the lock. Written as JSON into `.writer.lock`. */\ninterface LockOwner {\n  pid: number;\n  hostname: string;\n  mtime: number;\n}\n\n/** The ownership record for THIS process, stamped now. One place, so acquire and renew cannot drift. */\nfunction ownerNow(): LockOwner {\n  return { pid: process.pid, hostname: hostname(), mtime: Date.now() };\n}\n\n/**\n * Writes the owner with user-only permissions.\n *\n * `0600` because the lock is an assertion of OWNERSHIP: with the `0664` the usual umask produces,\n * another user in the same group can overwrite the file and forge ownership of the session — and\n * from then on it is the legitimate owner who starts receiving `SessionBusyError`. The content\n * (`pid`, `hostname`) is low-sensitivity; what the permission protects is the signal's\n * **integrity**, not its secrecy.\n */\nfunction writeOwner(lockPath: string, owner: LockOwner): void {\n  const fd = openSync(lockPath, \"w\", 0o600);\n  try {\n    writeSync(fd, JSON.stringify(owner));\n    // `open`'s `mode` only applies on CREATION. A `.writer.lock` inherited from an earlier version —\n    // or left behind by a process with a different umask — would stay `0664` after being reclaimed,\n    // and the forgery window the mode closes for new locks would remain open for old ones.\n    fchmodSync(fd, 0o600);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Reads the lock's owner. `undefined` when the file vanished or the content is unreadable. */\nfunction readOwner(lockPath: string): LockOwner | undefined {\n  let raw: string;\n  try {\n    raw = readFileSync(lockPath, \"utf8\");\n  } catch (err) {\n    const code = (err as NodeJS.ErrnoException).code;\n    // `ENOENT` — vanished between the `EEXIST` and the read. Benign race: the lock is gone.\n    if (code === \"ENOENT\") return undefined;\n    // `EISDIR` — the lock path is a DIRECTORY. No process in this library creates one; it is debris\n    // from something else, and it will never become a readable lock. Failing closed here would lock\n    // the session out forever. Treated as owner-less: acquisition proceeds and fails with the real\n    // FS error, which says what is wrong — instead of a permanent SessionBusyError that says\n    // nothing. It is NOT \"reclaimable\": the lock is not removed, and the caller proceeds without a\n    // lease.\n    if (code === \"EISDIR\") return undefined;\n    // Any other read failure (`EACCES` in a shared directory, `EIO`) differs in kind: the lock\n    // **exists** and it is we who cannot read the owner. Treating it as free would let two writers\n    // coexist — precisely what the lease exists to prevent — and the `0600` that protects the lock\n    // against forgery WIDENS that surface: in a shared directory, another user's lock is unreadable\n    // by design.\n    //\n    // Not knowing who the owner is differs from there being no owner. Fail closed.\n    throw new SessionBusyError(lockPath.replace(/\\.writer\\.lock$/, \"\"));\n  }\n  try {\n    const d = JSON.parse(raw) as Partial<LockOwner>;\n    if (\n      typeof d.pid !== \"number\" ||\n      typeof d.hostname !== \"string\" ||\n      typeof d.mtime !== \"number\"\n    ) {\n      return undefined;\n    }\n    return { pid: d.pid, hostname: d.hostname, mtime: d.mtime };\n  } catch {\n    // Unreadable JSON: a lock nobody can interpret must not lock the session out forever. Treating\n    // it as stale is the recoverable choice; the cost is the same as that of an old lock.\n    return undefined;\n  }\n}\n\n/** Does the process exist? `signal 0` sends nothing — it only queries permission/existence. */\nfunction processAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (err) {\n    // EPERM means it EXISTS and belongs to another user.\n    return (err as NodeJS.ErrnoException).code === \"EPERM\";\n  }\n}\n\n/**\n * Can the lock be taken from whoever holds it?\n *\n * ADR-2 of the plan: reclaiming by `pid` alone has a false positive across machines — the same\n * number exists on another host, pointing at an unrelated process. So:\n *\n * - **same host:** the `pid` is authoritative, and it **alone**. Dead process => reclaimable at\n *   once; live process => never, however old the lock is.\n * - **other host:** the `pid` says nothing here. Only the heartbeat window counts, because it is\n *   the one signal that does not lie across machines.\n *\n * ## Why age does NOT count on the same host\n *\n * The first version did `stale || !processAlive(pid)`, and that was a serious defect: `mtime` is\n * written at **acquisition** and is not touched on each append, so any session lasting longer than\n * the window — that is, **every real session** — became stealable by another process. Two writers\n * on the same transcript is exactly what the lease exists to prevent.\n *\n * On the same host the question \"does the owner still exist?\" has an exact answer, and age adds no\n * information to it — only a way to be wrong. Keeping the window there would be heuristic layered\n * on top of a fact.\n */\nfunction reclaimable(owner: LockOwner | undefined): boolean {\n  if (owner === undefined) return true; // unreadable or vanished\n  if (owner.hostname !== hostname()) {\n    return Date.now() - owner.mtime > HEARTBEAT_WINDOW_MS;\n  }\n  return !processAlive(owner.pid);\n}\n\n/**\n * Does the session have a writer **right now**? A query that does NOT take the lease.\n *\n * M95 — it exists because asking by taking creates the very contention it meant to detect: two\n * processes querying a **free** session at the same time made one of them lose, and the consumer\n * forked for no reason. Measured in adversarial review: `RACE: spurious forks = 1`.\n *\n * It is a snapshot, not a guarantee: between the query and the real acquisition someone may take\n * the session. Callers needing the guarantee use {@link acquireSessionWriter}; callers needing to\n * **decide an id before opening anything** use this, and handle the race where it shows up.\n *\n */\nexport function sessionHasWriter(sessionPath: string): boolean {\n  const lockPath = `${sessionPath}.writer.lock`;\n  if (!existsSync(lockPath)) return false;\n  try {\n    return !reclaimable(readOwner(lockPath));\n  } catch {\n    // `readOwner` throws when the lock exists and cannot be read — fail closed, for the same reason\n    // as there: not knowing who the owner is differs from there being no owner.\n    return true;\n  }\n}\n\n/**\n * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.\n *\n * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the\n * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across\n * processes, not just across async tasks in one process.\n */\nexport async function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease> {\n  // M95 — `.writer.lock`, NOT `.lock`.\n  //\n  // `withFileLock(path, fn)` already uses `<path>.lock` as its companion. While the lease was called\n  // from nowhere (the defect this milestone fixes) the collision was theoretical; wiring it to the\n  // same file would make the long-lived lease block every short critical section on the same path.\n  //\n  // Two files because they are two things: `withFileLock` protects a section with a start and an\n  // end; the lease is OWNERSHIP, held across turns, with an explicit `release()` — the distinction\n  // the M81 docstring above already explains.\n  const lockPath = `${sessionPath}.writer.lock`;\n  const mine: LockOwner = ownerNow();\n  let fd: number;\n  try {\n    // The mode applies on CREATION — the `w` in `writeOwner` does not alter an existing file.\n    fd = openSync(lockPath, \"wx\", 0o600);\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"EEXIST\") throw err;\n    // M95 — the lock exists. Until now that alone was enough to refuse, and that was the defect: a\n    // TUI killed by SIGKILL locked the user out of their own session PERMANENTLY, with no documented\n    // recovery path. Now the lock says who the owner is, and a dead owner yields its place.\n    if (!reclaimable(readOwner(lockPath))) throw new SessionBusyError(sessionPath);\n    writeOwner(lockPath, mine);\n    return createLease(sessionPath, lockPath);\n  }\n  closeSync(fd);\n  writeOwner(lockPath, mine);\n\n  return createLease(sessionPath, lockPath);\n}\n\n/** The lease itself — idempotent `release()`. Extracted because acquisition has two exit paths. */\nfunction createLease(sessionPath: string, lockPath: string): SessionWriterLease {\n  let released = false;\n  return {\n    sessionPath,\n    release: async (): Promise<void> => {\n      if (released) return;\n      released = true;\n      rmSync(lockPath, { force: true });\n    },\n    renew: (): void => {\n      // A released lease does not own the lock. Re-stamping here would RE-CREATE the file and give\n      // this process ownership it explicitly gave up — the one way this method could manufacture the\n      // double-writer the lease exists to prevent.\n      if (released) return;\n      writeOwner(lockPath, ownerNow());\n    },\n  };\n}\n"]}

package/dist/{chunk-D5KXKBEN.cjs → chunk-FEAWEBWN.cjs}

@@ -1,19 +1,19 @@
 'use strict';
 
 var chunkAA27GEYS_cjs = require('./chunk-AA27GEYS.cjs');
-var chunkUNFBHV46_cjs = require('./chunk-UNFBHV46.cjs');
+var chunkCEGU5AVD_cjs = require('./chunk-CEGU5AVD.cjs');
 var module$1 = require('module');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 var cachedZ;
 function requireZod() {
   if (cachedZ !== void 0) return cachedZ;
-  const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-D5KXKBEN.cjs', document.baseURI).href)));
+  const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-FEAWEBWN.cjs', document.baseURI).href)));
   let mod;
   try {
     mod = r("zod");
   } catch (cause) {
-    throw new chunkUNFBHV46_cjs.ConfigurationError(
+    throw new chunkCEGU5AVD_cjs.ConfigurationError(
       'Structured output requires the optional peer dependency `zod`. Add `"zod": "^3.25.0 || ^4.0.0"` to your package.json and reinstall.',
       { code: "zod_not_installed", cause }
     );
@@ -84,5 +84,5 @@ exports.disposeAndDeleteTransient = disposeAndDeleteTransient;
 exports.extractUsage = extractUsage;
 exports.makeOutputTool = makeOutputTool;
 exports.setupStructuredOutput = setupStructuredOutput;
-//# sourceMappingURL=chunk-D5KXKBEN.cjs.map
-//# sourceMappingURL=chunk-D5KXKBEN.cjs.map
+//# sourceMappingURL=chunk-FEAWEBWN.cjs.map
+//# sourceMappingURL=chunk-FEAWEBWN.cjs.map

package/dist/{chunk-D5KXKBEN.cjs.map → chunk-FEAWEBWN.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/structured-output-helpers.ts"],"names":["createRequire","ConfigurationError","toJsonSchema"],"mappings":"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","file":"chunk-D5KXKBEN.cjs","sourcesContent":["import { createRequire } from \"node:module\";\nimport type { z as ZodNamespace, ZodType } from \"zod\";\nimport { ConfigurationError } from \"../errors.js\";\nimport type { AgentOptions, CustomTool, LocalOptions, ModelSelection } from \"../types/agent.js\";\nimport type { ProviderRoutingSettings } from \"../types/providers.js\";\nimport { toJsonSchema } from \"./zod-to-json-schema.js\";\n\n/**\n * Shared helpers for `Agent.generateObject` (ADR D33) and\n * `Agent.streamObject` (ADR D39). Both build a transient agent with a\n * single synthetic `output` tool whose handler captures the model's\n * structured response.\n *\n * Extracted from inline duplicates to keep jscpd quiet AND to keep the\n * two public APIs in lockstep.\n *\n * @internal\n */\n\nlet cachedZ: typeof ZodNamespace | undefined;\n\n/**\n * Load Zod via createRequire (it's an optional peer dep). Throws a typed\n * ConfigurationError if Zod isn't installed.\n */\nexport function requireZod(): typeof ZodNamespace {\n  if (cachedZ !== undefined) return cachedZ;\n  const r = createRequire(import.meta.url);\n  let mod: { z?: typeof ZodNamespace } & typeof ZodNamespace;\n  try {\n    mod = r(\"zod\") as typeof mod;\n  } catch (cause) {\n    throw new ConfigurationError(\n      \"Structured output requires the optional peer dependency `zod`. \" +\n        'Add `\"zod\": \"^3.25.0 || ^4.0.0\"` to your package.json and reinstall.',\n      { code: \"zod_not_installed\", cause },\n    );\n  }\n  cachedZ = (mod.z ?? mod) as typeof ZodNamespace;\n  return cachedZ;\n}\n\n/**\n * Build the synthetic `output` tool used by both `generateObject` and\n * `streamObject`. The handler captures the raw input on first call only\n * (EC-D10 / EC-6: parallel tool use in Claude 3.5+ may invoke `output`\n * twice; later calls are ignored).\n */\nexport function makeOutputTool(\n  jsonSchema: Record<string, unknown>,\n  onCapture: (input: unknown) => string | Promise<string> | undefined,\n): CustomTool {\n  return {\n    name: \"output\",\n    description: \"Call this tool with your final structured answer. Match the JSON schema exactly.\",\n    inputSchema: jsonSchema,\n    handler: (input) => {\n      const out = onCapture(input);\n      // Some callers throw a sentinel (generate-object) and never return.\n      // Others return a string (stream-object). Anything else → empty string.\n      if (typeof out === \"string\") return out;\n      if (out instanceof Promise) return out;\n      return \"\";\n    },\n  };\n}\n\n/**\n * Assemble the AgentOptions for the transient agent. Shared shape:\n * model + local + tools[output] + systemPrompt + apiKey.\n */\nexport function buildTransientAgentOptions(params: {\n  // SE8 — accepts the bare-string shorthand; forwarded to AgentOptions.model\n  // (normalized at Agent.create).\n  model: string | ModelSelection;\n  local: LocalOptions;\n  outputTool: CustomTool;\n  systemPrompt?: string;\n  apiKey?: string;\n  providers?: ProviderRoutingSettings;\n}): AgentOptions {\n  return {\n    model: params.model,\n    local: params.local,\n    tools: [params.outputTool],\n    systemPrompt:\n      params.systemPrompt ??\n      \"You produce structured output by calling the `output` tool exactly once. Match the JSON schema.\",\n    ...(params.apiKey !== undefined ? { apiKey: params.apiKey } : {}),\n    ...(params.providers !== undefined ? { providers: params.providers } : {}),\n  };\n}\n\n/**\n * Best-effort extraction of token usage from a run result. Local runtimes\n * may not expose it; default to zeros.\n */\nexport function extractUsage(result: unknown): { inputTokens: number; outputTokens: number } {\n  const u = (result as { usage?: { inputTokens?: number; outputTokens?: number } }).usage;\n  if (u === undefined) return { inputTokens: 0, outputTokens: 0 };\n  return { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };\n}\n\n/**\n * Build the user-message prompt that instructs the model to call the\n * `output` tool with a schema-matched structured answer.\n */\nexport function buildToolPrompt(prompt: string): string {\n  return `${prompt}\\n\\nRespond by calling the \\`output\\` tool with the structured answer that matches the schema.`;\n}\n\n/**\n * One-shot setup shared by both `generateObject` and `streamObject`. Loads\n * Zod, computes the JSON schema, primes the captured-raw / usage / retry\n * state. Returns the values needed by the caller's loop.\n */\nexport function setupStructuredOutput<T extends ZodType>(\n  schema: T,\n  maxRetries: number | undefined,\n) {\n  const z = requireZod();\n  // Universal Zod 3+4 conversion (feature-detects native v4, falls back to lib on v3).\n  const jsonSchema = toJsonSchema(schema, { unrepresentable: \"any\" });\n  return {\n    z,\n    jsonSchema,\n    maxRetries: maxRetries ?? 1,\n    initialUsage: { inputTokens: 0, outputTokens: 0 },\n  };\n}\n\n/**\n * Cleanup the transient agent after generateObject/streamObject finish.\n * Disposes AND hard-deletes from the registry so the count stays stable.\n *\n * @internal\n */\nexport async function disposeAndDeleteTransient(\n  agent: { dispose: () => Promise<void>; agentId: string },\n  deletor: (agentId: string) => Promise<void>,\n): Promise<void> {\n  await agent.dispose();\n  try {\n    await deletor(agent.agentId);\n  } catch {\n    // Best-effort cleanup.\n  }\n}\n\n/**\n * The three failure messages, verbatim from what both entry points already emit.\n *\n * Identical strings in two files is how two APIs start describing the same failure differently: the\n * first person to improve one of them improves half the product.\n *\n * @internal\n */\nexport const STRUCTURED_OUTPUT_MESSAGES = {\n  runFailed: (message: string | undefined, code: string | undefined): string =>\n    `Agent run failed before the model could reply: ${message ?? \"unknown error\"} [${code ?? \"?\"}]`,\n  noToolCall: \"The model returned text instead of calling the `output` tool.\",\n  parseFailed: \"Schema parse failed after all retries.\",\n} as const;\n"]}
+{"version":3,"sources":["../src/internal/structured-output-helpers.ts"],"names":["createRequire","ConfigurationError","toJsonSchema"],"mappings":"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","file":"chunk-FEAWEBWN.cjs","sourcesContent":["import { createRequire } from \"node:module\";\nimport type { z as ZodNamespace, ZodType } from \"zod\";\nimport { ConfigurationError } from \"../errors.js\";\nimport type { AgentOptions, CustomTool, LocalOptions, ModelSelection } from \"../types/agent.js\";\nimport type { ProviderRoutingSettings } from \"../types/providers.js\";\nimport { toJsonSchema } from \"./zod-to-json-schema.js\";\n\n/**\n * Shared helpers for `Agent.generateObject` (ADR D33) and\n * `Agent.streamObject` (ADR D39). Both build a transient agent with a\n * single synthetic `output` tool whose handler captures the model's\n * structured response.\n *\n * Extracted from inline duplicates to keep jscpd quiet AND to keep the\n * two public APIs in lockstep.\n *\n * @internal\n */\n\nlet cachedZ: typeof ZodNamespace | undefined;\n\n/**\n * Load Zod via createRequire (it's an optional peer dep). Throws a typed\n * ConfigurationError if Zod isn't installed.\n */\nexport function requireZod(): typeof ZodNamespace {\n  if (cachedZ !== undefined) return cachedZ;\n  const r = createRequire(import.meta.url);\n  let mod: { z?: typeof ZodNamespace } & typeof ZodNamespace;\n  try {\n    mod = r(\"zod\") as typeof mod;\n  } catch (cause) {\n    throw new ConfigurationError(\n      \"Structured output requires the optional peer dependency `zod`. \" +\n        'Add `\"zod\": \"^3.25.0 || ^4.0.0\"` to your package.json and reinstall.',\n      { code: \"zod_not_installed\", cause },\n    );\n  }\n  cachedZ = (mod.z ?? mod) as typeof ZodNamespace;\n  return cachedZ;\n}\n\n/**\n * Build the synthetic `output` tool used by both `generateObject` and\n * `streamObject`. The handler captures the raw input on first call only\n * (EC-D10 / EC-6: parallel tool use in Claude 3.5+ may invoke `output`\n * twice; later calls are ignored).\n */\nexport function makeOutputTool(\n  jsonSchema: Record<string, unknown>,\n  onCapture: (input: unknown) => string | Promise<string> | undefined,\n): CustomTool {\n  return {\n    name: \"output\",\n    description: \"Call this tool with your final structured answer. Match the JSON schema exactly.\",\n    inputSchema: jsonSchema,\n    handler: (input) => {\n      const out = onCapture(input);\n      // Some callers throw a sentinel (generate-object) and never return.\n      // Others return a string (stream-object). Anything else → empty string.\n      if (typeof out === \"string\") return out;\n      if (out instanceof Promise) return out;\n      return \"\";\n    },\n  };\n}\n\n/**\n * Assemble the AgentOptions for the transient agent. Shared shape:\n * model + local + tools[output] + systemPrompt + apiKey.\n */\nexport function buildTransientAgentOptions(params: {\n  // SE8 — accepts the bare-string shorthand; forwarded to AgentOptions.model\n  // (normalized at Agent.create).\n  model: string | ModelSelection;\n  local: LocalOptions;\n  outputTool: CustomTool;\n  systemPrompt?: string;\n  apiKey?: string;\n  providers?: ProviderRoutingSettings;\n}): AgentOptions {\n  return {\n    model: params.model,\n    local: params.local,\n    tools: [params.outputTool],\n    systemPrompt:\n      params.systemPrompt ??\n      \"You produce structured output by calling the `output` tool exactly once. Match the JSON schema.\",\n    ...(params.apiKey !== undefined ? { apiKey: params.apiKey } : {}),\n    ...(params.providers !== undefined ? { providers: params.providers } : {}),\n  };\n}\n\n/**\n * Best-effort extraction of token usage from a run result. Local runtimes\n * may not expose it; default to zeros.\n */\nexport function extractUsage(result: unknown): { inputTokens: number; outputTokens: number } {\n  const u = (result as { usage?: { inputTokens?: number; outputTokens?: number } }).usage;\n  if (u === undefined) return { inputTokens: 0, outputTokens: 0 };\n  return { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };\n}\n\n/**\n * Build the user-message prompt that instructs the model to call the\n * `output` tool with a schema-matched structured answer.\n */\nexport function buildToolPrompt(prompt: string): string {\n  return `${prompt}\\n\\nRespond by calling the \\`output\\` tool with the structured answer that matches the schema.`;\n}\n\n/**\n * One-shot setup shared by both `generateObject` and `streamObject`. Loads\n * Zod, computes the JSON schema, primes the captured-raw / usage / retry\n * state. Returns the values needed by the caller's loop.\n */\nexport function setupStructuredOutput<T extends ZodType>(\n  schema: T,\n  maxRetries: number | undefined,\n) {\n  const z = requireZod();\n  // Universal Zod 3+4 conversion (feature-detects native v4, falls back to lib on v3).\n  const jsonSchema = toJsonSchema(schema, { unrepresentable: \"any\" });\n  return {\n    z,\n    jsonSchema,\n    maxRetries: maxRetries ?? 1,\n    initialUsage: { inputTokens: 0, outputTokens: 0 },\n  };\n}\n\n/**\n * Cleanup the transient agent after generateObject/streamObject finish.\n * Disposes AND hard-deletes from the registry so the count stays stable.\n *\n * @internal\n */\nexport async function disposeAndDeleteTransient(\n  agent: { dispose: () => Promise<void>; agentId: string },\n  deletor: (agentId: string) => Promise<void>,\n): Promise<void> {\n  await agent.dispose();\n  try {\n    await deletor(agent.agentId);\n  } catch {\n    // Best-effort cleanup.\n  }\n}\n\n/**\n * The three failure messages, verbatim from what both entry points already emit.\n *\n * Identical strings in two files is how two APIs start describing the same failure differently: the\n * first person to improve one of them improves half the product.\n *\n * @internal\n */\nexport const STRUCTURED_OUTPUT_MESSAGES = {\n  runFailed: (message: string | undefined, code: string | undefined): string =>\n    `Agent run failed before the model could reply: ${message ?? \"unknown error\"} [${code ?? \"?\"}]`,\n  noToolCall: \"The model returned text instead of calling the `output` tool.\",\n  parseFailed: \"Schema parse failed after all retries.\",\n} as const;\n"]}

package/dist/{chunk-NJSIAJEK.cjs → chunk-FLDMPVUC.cjs}

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkUNFBHV46_cjs = require('./chunk-UNFBHV46.cjs');
+var chunkCEGU5AVD_cjs = require('./chunk-CEGU5AVD.cjs');
 
 // src/internal/concurrency/async-semaphore.ts
 function createSemaphore(permits) {
   if (!Number.isInteger(permits) || permits < 1) {
-    throw new chunkUNFBHV46_cjs.ConfigurationError(
+    throw new chunkCEGU5AVD_cjs.ConfigurationError(
       `async-semaphore: permits must be a positive integer, got ${permits}`,
       { code: "invalid_concurrency" }
     );
@@ -41,5 +41,5 @@ function createSemaphore(permits) {
 }
 
 exports.createSemaphore = createSemaphore;
-//# sourceMappingURL=chunk-NJSIAJEK.cjs.map
-//# sourceMappingURL=chunk-NJSIAJEK.cjs.map
+//# sourceMappingURL=chunk-FLDMPVUC.cjs.map
+//# sourceMappingURL=chunk-FLDMPVUC.cjs.map

package/dist/{chunk-NJSIAJEK.cjs.map → chunk-FLDMPVUC.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/concurrency/async-semaphore.ts"],"names":["ConfigurationError"],"mappings":";;;;;AA2BO,SAAS,gBAAgB,OAAA,EAAiC;AAC/D,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,OAAO,CAAA,IAAK,UAAU,CAAA,EAAG;AAC7C,IAAA,MAAM,IAAIA,oCAAA;AAAA,MACR,4DAA4D,OAAO,CAAA,CAAA;AAAA,MACnE,EAAE,MAAM,qBAAA;AAAsB,KAChC;AAAA,EACF;AACA,EAAA,IAAI,MAAA,GAAS,CAAA;AACb,EAAA,MAAM,QAA2B,EAAC;AAElC,EAAA,SAAS,QAAA,GAAiB;AACxB,IAAA,IAAI,MAAA,GAAS,OAAA,IAAW,KAAA,CAAM,MAAA,GAAS,CAAA,EAAG;AACxC,MAAA,MAAM,OAAA,GAAU,MAAM,KAAA,EAAM;AAC5B,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,MAAA,IAAU,CAAA;AACV,QAAA,OAAA,EAAQ;AAAA,MACV;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,UAAU,MAAM,MAAA;AAAA,IAChB,OAAA,EAAS,MAAM,KAAA,CAAM,MAAA,GAAS,MAAA;AAAA,IAC9B,MAAM,OAAA,GAAU;AACd,MAAA,MAAM,IAAI,OAAA,CAAc,CAAC,OAAA,KAAY;AACnC,QAAA,KAAA,CAAM,KAAK,OAAO,CAAA;AAClB,QAAA,QAAA,EAAS;AAAA,MACX,CAAC,CAAA;AACD,MAAA,IAAI,QAAA,GAAW,KAAA;AACf,MAAA,OAAO,MAAM;AACX,QAAA,IAAI,QAAA,EAAU;AACd,QAAA,QAAA,GAAW,IAAA;AACX,QAAA,MAAA,IAAU,CAAA;AACV,QAAA,QAAA,EAAS;AAAA,MACX,CAAA;AAAA,IACF;AAAA,GACF;AACF","file":"chunk-NJSIAJEK.cjs","sourcesContent":["/**\n * Async-aware counting semaphore (ADR D135).\n *\n * N-permit gate for cooperative concurrency control inside a single\n * Node process. Used by `Agent.batch` to bound parallel agent count\n * without pulling in `p-limit` or `p-queue` (~30 LoC in-house).\n *\n * Contract: `acquire()` returns a release function. Caller MUST call\n * release exactly once when done — typically in a `finally` block.\n * Release is idempotent (multiple calls are no-ops after the first)\n * for defense against caller bugs, but leaking the release function\n * permanently consumes one permit (EC-G — caller responsibility).\n *\n * @internal\n */\n\nimport { ConfigurationError } from \"../../errors.js\";\n\nexport interface AsyncSemaphore {\n  /** Acquire a permit. Returns the release function (call once). */\n  acquire(): Promise<() => void>;\n  /** Permits currently held in flight. */\n  inFlight(): number;\n  /** Total: in-flight + queued waiters. */\n  pending(): number;\n}\n\nexport function createSemaphore(permits: number): AsyncSemaphore {\n  if (!Number.isInteger(permits) || permits < 1) {\n    throw new ConfigurationError(\n      `async-semaphore: permits must be a positive integer, got ${permits}`,\n      { code: \"invalid_concurrency\" },\n    );\n  }\n  let active = 0;\n  const queue: Array<() => void> = [];\n\n  function tryGrant(): void {\n    if (active < permits && queue.length > 0) {\n      const resolve = queue.shift();\n      if (resolve !== undefined) {\n        active += 1;\n        resolve();\n      }\n    }\n  }\n\n  return {\n    inFlight: () => active,\n    pending: () => queue.length + active,\n    async acquire() {\n      await new Promise<void>((resolve) => {\n        queue.push(resolve);\n        tryGrant();\n      });\n      let released = false;\n      return () => {\n        if (released) return;\n        released = true;\n        active -= 1;\n        tryGrant();\n      };\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/internal/concurrency/async-semaphore.ts"],"names":["ConfigurationError"],"mappings":";;;;;AA2BO,SAAS,gBAAgB,OAAA,EAAiC;AAC/D,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,OAAO,CAAA,IAAK,UAAU,CAAA,EAAG;AAC7C,IAAA,MAAM,IAAIA,oCAAA;AAAA,MACR,4DAA4D,OAAO,CAAA,CAAA;AAAA,MACnE,EAAE,MAAM,qBAAA;AAAsB,KAChC;AAAA,EACF;AACA,EAAA,IAAI,MAAA,GAAS,CAAA;AACb,EAAA,MAAM,QAA2B,EAAC;AAElC,EAAA,SAAS,QAAA,GAAiB;AACxB,IAAA,IAAI,MAAA,GAAS,OAAA,IAAW,KAAA,CAAM,MAAA,GAAS,CAAA,EAAG;AACxC,MAAA,MAAM,OAAA,GAAU,MAAM,KAAA,EAAM;AAC5B,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,MAAA,IAAU,CAAA;AACV,QAAA,OAAA,EAAQ;AAAA,MACV;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,UAAU,MAAM,MAAA;AAAA,IAChB,OAAA,EAAS,MAAM,KAAA,CAAM,MAAA,GAAS,MAAA;AAAA,IAC9B,MAAM,OAAA,GAAU;AACd,MAAA,MAAM,IAAI,OAAA,CAAc,CAAC,OAAA,KAAY;AACnC,QAAA,KAAA,CAAM,KAAK,OAAO,CAAA;AAClB,QAAA,QAAA,EAAS;AAAA,MACX,CAAC,CAAA;AACD,MAAA,IAAI,QAAA,GAAW,KAAA;AACf,MAAA,OAAO,MAAM;AACX,QAAA,IAAI,QAAA,EAAU;AACd,QAAA,QAAA,GAAW,IAAA;AACX,QAAA,MAAA,IAAU,CAAA;AACV,QAAA,QAAA,EAAS;AAAA,MACX,CAAA;AAAA,IACF;AAAA,GACF;AACF","file":"chunk-FLDMPVUC.cjs","sourcesContent":["/**\n * Async-aware counting semaphore (ADR D135).\n *\n * N-permit gate for cooperative concurrency control inside a single\n * Node process. Used by `Agent.batch` to bound parallel agent count\n * without pulling in `p-limit` or `p-queue` (~30 LoC in-house).\n *\n * Contract: `acquire()` returns a release function. Caller MUST call\n * release exactly once when done — typically in a `finally` block.\n * Release is idempotent (multiple calls are no-ops after the first)\n * for defense against caller bugs, but leaking the release function\n * permanently consumes one permit (EC-G — caller responsibility).\n *\n * @internal\n */\n\nimport { ConfigurationError } from \"../../errors.js\";\n\nexport interface AsyncSemaphore {\n  /** Acquire a permit. Returns the release function (call once). */\n  acquire(): Promise<() => void>;\n  /** Permits currently held in flight. */\n  inFlight(): number;\n  /** Total: in-flight + queued waiters. */\n  pending(): number;\n}\n\nexport function createSemaphore(permits: number): AsyncSemaphore {\n  if (!Number.isInteger(permits) || permits < 1) {\n    throw new ConfigurationError(\n      `async-semaphore: permits must be a positive integer, got ${permits}`,\n      { code: \"invalid_concurrency\" },\n    );\n  }\n  let active = 0;\n  const queue: Array<() => void> = [];\n\n  function tryGrant(): void {\n    if (active < permits && queue.length > 0) {\n      const resolve = queue.shift();\n      if (resolve !== undefined) {\n        active += 1;\n        resolve();\n      }\n    }\n  }\n\n  return {\n    inFlight: () => active,\n    pending: () => queue.length + active,\n    async acquire() {\n      await new Promise<void>((resolve) => {\n        queue.push(resolve);\n        tryGrant();\n      });\n      let released = false;\n      return () => {\n        if (released) return;\n        released = true;\n        active -= 1;\n        tryGrant();\n      };\n    },\n  };\n}\n"]}

package/dist/{chunk-ASK2OQM5.cjs → chunk-G7XBVM3T.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
-var chunk6LHQPOMI_cjs = require('./chunk-6LHQPOMI.cjs');
+var chunkRNXXYF22_cjs = require('./chunk-RNXXYF22.cjs');
 
 // src/internal/persistence/file-lock.ts
 var cached;
@@ -30,7 +30,7 @@ async function getProperLockfile() {
     if (!validateLockModule(mod)) {
       if (!warnedStructural) {
         warnedStructural = true;
-        chunk6LHQPOMI_cjs.diag(
+        chunkRNXXYF22_cjs.diag(
           "[theokit-sdk] proper-lockfile: imported module does NOT expose the expected `lock`/`unlock` API surface. This may indicate a supply-chain compromise or an incompatible major version. Falling back to in-process mutex (no cross-process safety). Reinstall with: pnpm add proper-lockfile@^11\n"
         );
       }
@@ -54,7 +54,7 @@ async function withFileLock(path, fn, options) {
   if (lib === null) {
     if (!warnedMissing && !warnedStructural) {
       warnedMissing = true;
-      chunk6LHQPOMI_cjs.diag(describeLockLoadFailure(loadFailure));
+      chunkRNXXYF22_cjs.diag(describeLockLoadFailure(loadFailure));
     }
     return chunkZF2LDKQQ_cjs.withCwdMutex(`file-lock:${path}`, fn);
   }
@@ -80,5 +80,5 @@ async function withFileLock(path, fn, options) {
 }
 
 exports.withFileLock = withFileLock;
-//# sourceMappingURL=chunk-ASK2OQM5.cjs.map
-//# sourceMappingURL=chunk-ASK2OQM5.cjs.map
+//# sourceMappingURL=chunk-G7XBVM3T.cjs.map
+//# sourceMappingURL=chunk-G7XBVM3T.cjs.map

package/dist/{chunk-ASK2OQM5.cjs.map → chunk-G7XBVM3T.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/file-lock.ts"],"names":["diag","withCwdMutex"],"mappings":"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","file":"chunk-ASK2OQM5.cjs","sourcesContent":["/**\n * Cross-process file lock helper (ADR D61).\n *\n * Uses `proper-lockfile` (optional peer dep) for cross-process locks. When\n * the peer dep is absent, falls back to `withCwdMutex` (in-process only)\n * with a one-shot stderr warning.\n *\n * EC-1 fix: uses a companion `<path>.lock` file with `realpath: false` so\n * `withFileLock` works even when the target `path` does not exist yet.\n * Without this, fresh installs that lock-then-create would crash with ENOENT.\n *\n * @internal\n */\n\nimport { diag } from \"../diagnostics.js\";\nimport { withCwdMutex } from \"./cwd-mutex.js\";\n\ninterface ProperLockfileModule {\n  lock: (file: string, options: ProperLockfileOptions) => Promise<() => Promise<void>>;\n}\n\ninterface ProperLockfileOptions {\n  lockfilePath?: string;\n  realpath?: boolean;\n  stale?: number;\n  retries?: {\n    retries: number;\n    factor?: number;\n    minTimeout?: number;\n    maxTimeout?: number;\n  };\n}\n\nlet cached: ProperLockfileModule | null | undefined;\nlet warnedMissing = false;\nlet warnedStructural = false;\n/** Why the import failed, kept so the warning can report the observation instead of a guess (#174). */\nlet loadFailure: unknown;\n\n/** Node reports a missing module as `ERR_MODULE_NOT_FOUND` (ESM loader) or `MODULE_NOT_FOUND` (CJS). */\nfunction isModuleAbsent(err: unknown): boolean {\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  return code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\";\n}\n\n/**\n * #174 — build the fallback warning from what actually happened.\n *\n * This used to always read \"proper-lockfile not installed\", because the import was wrapped in a\n * bare `catch` that discarded the error (Unbreakable Rule 8: a swallowed error is the dangerous\n * kind). A consumer whose package WAS installed, declared and resolvable spent a debugging session\n * re-verifying the install, because the message named a cause the code had never checked.\n *\n * Absence is now the only case that claims absence. Every other failure — a broken install, an\n * interop problem, a bundler that rewrote the specifier — reports its own code and message, which\n * is what points at the real cause.\n *\n * @internal\n */\nfunction describeLockLoadFailure(err: unknown): string {\n  const consequence =\n    \"cross-process file lock unavailable — concurrent processes over the same file are NOT serialized.\";\n  if (isModuleAbsent(err)) {\n    return `[theokit-sdk] proper-lockfile not installed; ${consequence} Install with: pnpm add proper-lockfile\\n`;\n  }\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  const detail = err instanceof Error ? err.message : String(err);\n  return (\n    `[theokit-sdk] proper-lockfile could not be loaded${code !== undefined ? ` (${String(code)})` : \"\"}: ` +\n    `${detail}. ${consequence} The package resolves for the SDK but failed to load — check bundling ` +\n    \"and module-format interop before re-checking the install.\\n\"\n  );\n}\n\n/** Test seam for the message builder — NOT in the public barrel. @internal */\nexport function __TESTING__describeLockLoadFailure(err: unknown): string {\n  return describeLockLoadFailure(err);\n}\n\nasync function getProperLockfile(): Promise<ProperLockfileModule | null> {\n  if (cached !== undefined) return cached;\n  try {\n    const mod = await import(\"proper-lockfile\");\n    // T5.9 — supply-chain hardening: validate the imported module\n    // exposes the API surface we depend on BEFORE caching it. A\n    // tampered or incompatible version that lacks `lock`/`unlock`\n    // functions gets treated as \"not installed\" with an advisory\n    // warning — never silently used.\n    if (!validateLockModule(mod)) {\n      if (!warnedStructural) {\n        warnedStructural = true;\n        diag(\n          \"[theokit-sdk] proper-lockfile: imported module does NOT expose \" +\n            \"the expected `lock`/`unlock` API surface. This may indicate a \" +\n            \"supply-chain compromise or an incompatible major version. \" +\n            \"Falling back to in-process mutex (no cross-process safety). \" +\n            \"Reinstall with: pnpm add proper-lockfile@^11\\n\",\n        );\n      }\n      cached = null;\n      return cached;\n    }\n    cached = mod as ProperLockfileModule;\n  } catch (err) {\n    // #174 — keep WHY. Discarding it here is what made the fallback warning assert a cause it had\n    // never observed, and sent a consumer to re-check an install that was already correct.\n    loadFailure = err;\n    cached = null;\n  }\n  return cached;\n}\n\n/**\n * T5.9 — Structural validation of the dynamically-imported\n * `proper-lockfile` module. Verifies the API surface we depend on\n * (`lock` and `unlock` as functions) is present. Pure function —\n * never throws, never mutates, never performs I/O.\n *\n * Exported via `__TESTING__validateLockModule` seam so unit tests\n * can drive the check without spinning up the dynamic import.\n *\n * @internal\n */\nfunction validateLockModule(mod: unknown): boolean {\n  if (mod === null || mod === undefined || typeof mod !== \"object\") return false;\n  const m = mod as Record<string, unknown>;\n  return typeof m.lock === \"function\" && typeof m.unlock === \"function\";\n}\n\n/**\n * T5.9 — Test seam: expose the structural validator for unit tests.\n * NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__validateLockModule(mod: unknown): boolean {\n  return validateLockModule(mod);\n}\n\n/**\n * T5.9 — Test seam: reset the module cache + warning flags between\n * tests so each test starts fresh. NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__resetFileLockCache(): void {\n  cached = undefined;\n  warnedMissing = false;\n  warnedStructural = false;\n  loadFailure = undefined;\n}\n\n/**\n * Retry and staleness tuning for `withFileLock`.\n *\n * Every field is optional and the defaults are applied per call, so `undefined` means the default\n * rather than \"no limit\". They are handed to `proper-lockfile` and have NO effect on the fallback\n * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which\n * queues indefinitely and never goes stale.\n *\n * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a\n * dead process and broken. Setting it below the longest a legitimate holder can run is what turns\n * a slow operation into two concurrent ones.\n *\n * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`\n * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to\n * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall\n * through to running `fn` unlocked.\n *\n * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for\n * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.\n */\nexport interface FileLockOptions {\n  /** Stale lock timeout in ms. Default 30_000 (30s). */\n  stale?: number;\n  /** Max retries on busy lock. Default 5. */\n  retries?: number;\n  /** Backoff factor between retries. Default 1.5. */\n  retryFactor?: number;\n}\n\n/**\n * Run `fn` while holding an OS-level cross-process lock on `path`.\n *\n * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`\n * file (`realpath: false`, so target file does NOT need to exist yet).\n * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot\n * stderr warning telling the user to install `proper-lockfile` for\n * cross-process safety.\n *\n * The lock is released even when `fn` throws.\n *\n */\nexport async function withFileLock<T>(\n  path: string,\n  fn: () => Promise<T>,\n  options?: FileLockOptions,\n): Promise<T> {\n  const lib = await getProperLockfile();\n\n  if (lib === null) {\n    // #174 — stay silent when the structural check already explained itself. Emitting \"not\n    // installed\" on top of \"does not expose lock/unlock\" would be two contradictory diagnoses of\n    // one failure, and the reader has no way to tell which is true.\n    if (!warnedMissing && !warnedStructural) {\n      warnedMissing = true;\n      diag(describeLockLoadFailure(loadFailure));\n    }\n    return withCwdMutex(`file-lock:${path}`, fn);\n  }\n\n  // proper-lockfile errors immediately on same-process concurrent acquire\n  // (\"Lock file is already being held\"). Wrap with cwd-mutex first so\n  // in-process callers queue and only ONE thread at a time enters the\n  // cross-process acquire path. Combined: full in-process + cross-process\n  // serialization.\n  return withCwdMutex(`file-lock:${path}`, async () => {\n    const release = await lib.lock(path, {\n      // EC-1: companion lockfile, target path may not exist yet.\n      lockfilePath: `${path}.lock`,\n      realpath: false,\n      stale: options?.stale ?? 30_000,\n      retries: {\n        retries: options?.retries ?? 5,\n        factor: options?.retryFactor ?? 1.5,\n        minTimeout: 100,\n        maxTimeout: 5_000,\n      },\n    });\n\n    try {\n      return await fn();\n    } finally {\n      await release();\n    }\n  });\n}\n\n/**\n * Test helper — resets the cached proper-lockfile module + warning flag.\n * Allows tests to simulate \"module absent\" by clearing cache then\n * monkey-patching the dynamic import resolution.\n *\n * @internal\n */\nexport function _resetFileLockCacheForTesting(): void {\n  cached = undefined;\n  warnedMissing = false;\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/file-lock.ts"],"names":["diag","withCwdMutex"],"mappings":"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","file":"chunk-G7XBVM3T.cjs","sourcesContent":["/**\n * Cross-process file lock helper (ADR D61).\n *\n * Uses `proper-lockfile` (optional peer dep) for cross-process locks. When\n * the peer dep is absent, falls back to `withCwdMutex` (in-process only)\n * with a one-shot stderr warning.\n *\n * EC-1 fix: uses a companion `<path>.lock` file with `realpath: false` so\n * `withFileLock` works even when the target `path` does not exist yet.\n * Without this, fresh installs that lock-then-create would crash with ENOENT.\n *\n * @internal\n */\n\nimport { diag } from \"../diagnostics.js\";\nimport { withCwdMutex } from \"./cwd-mutex.js\";\n\ninterface ProperLockfileModule {\n  lock: (file: string, options: ProperLockfileOptions) => Promise<() => Promise<void>>;\n}\n\ninterface ProperLockfileOptions {\n  lockfilePath?: string;\n  realpath?: boolean;\n  stale?: number;\n  retries?: {\n    retries: number;\n    factor?: number;\n    minTimeout?: number;\n    maxTimeout?: number;\n  };\n}\n\nlet cached: ProperLockfileModule | null | undefined;\nlet warnedMissing = false;\nlet warnedStructural = false;\n/** Why the import failed, kept so the warning can report the observation instead of a guess (#174). */\nlet loadFailure: unknown;\n\n/** Node reports a missing module as `ERR_MODULE_NOT_FOUND` (ESM loader) or `MODULE_NOT_FOUND` (CJS). */\nfunction isModuleAbsent(err: unknown): boolean {\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  return code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\";\n}\n\n/**\n * #174 — build the fallback warning from what actually happened.\n *\n * This used to always read \"proper-lockfile not installed\", because the import was wrapped in a\n * bare `catch` that discarded the error (Unbreakable Rule 8: a swallowed error is the dangerous\n * kind). A consumer whose package WAS installed, declared and resolvable spent a debugging session\n * re-verifying the install, because the message named a cause the code had never checked.\n *\n * Absence is now the only case that claims absence. Every other failure — a broken install, an\n * interop problem, a bundler that rewrote the specifier — reports its own code and message, which\n * is what points at the real cause.\n *\n * @internal\n */\nfunction describeLockLoadFailure(err: unknown): string {\n  const consequence =\n    \"cross-process file lock unavailable — concurrent processes over the same file are NOT serialized.\";\n  if (isModuleAbsent(err)) {\n    return `[theokit-sdk] proper-lockfile not installed; ${consequence} Install with: pnpm add proper-lockfile\\n`;\n  }\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  const detail = err instanceof Error ? err.message : String(err);\n  return (\n    `[theokit-sdk] proper-lockfile could not be loaded${code !== undefined ? ` (${String(code)})` : \"\"}: ` +\n    `${detail}. ${consequence} The package resolves for the SDK but failed to load — check bundling ` +\n    \"and module-format interop before re-checking the install.\\n\"\n  );\n}\n\n/** Test seam for the message builder — NOT in the public barrel. @internal */\nexport function __TESTING__describeLockLoadFailure(err: unknown): string {\n  return describeLockLoadFailure(err);\n}\n\nasync function getProperLockfile(): Promise<ProperLockfileModule | null> {\n  if (cached !== undefined) return cached;\n  try {\n    const mod = await import(\"proper-lockfile\");\n    // T5.9 — supply-chain hardening: validate the imported module\n    // exposes the API surface we depend on BEFORE caching it. A\n    // tampered or incompatible version that lacks `lock`/`unlock`\n    // functions gets treated as \"not installed\" with an advisory\n    // warning — never silently used.\n    if (!validateLockModule(mod)) {\n      if (!warnedStructural) {\n        warnedStructural = true;\n        diag(\n          \"[theokit-sdk] proper-lockfile: imported module does NOT expose \" +\n            \"the expected `lock`/`unlock` API surface. This may indicate a \" +\n            \"supply-chain compromise or an incompatible major version. \" +\n            \"Falling back to in-process mutex (no cross-process safety). \" +\n            \"Reinstall with: pnpm add proper-lockfile@^11\\n\",\n        );\n      }\n      cached = null;\n      return cached;\n    }\n    cached = mod as ProperLockfileModule;\n  } catch (err) {\n    // #174 — keep WHY. Discarding it here is what made the fallback warning assert a cause it had\n    // never observed, and sent a consumer to re-check an install that was already correct.\n    loadFailure = err;\n    cached = null;\n  }\n  return cached;\n}\n\n/**\n * T5.9 — Structural validation of the dynamically-imported\n * `proper-lockfile` module. Verifies the API surface we depend on\n * (`lock` and `unlock` as functions) is present. Pure function —\n * never throws, never mutates, never performs I/O.\n *\n * Exported via `__TESTING__validateLockModule` seam so unit tests\n * can drive the check without spinning up the dynamic import.\n *\n * @internal\n */\nfunction validateLockModule(mod: unknown): boolean {\n  if (mod === null || mod === undefined || typeof mod !== \"object\") return false;\n  const m = mod as Record<string, unknown>;\n  return typeof m.lock === \"function\" && typeof m.unlock === \"function\";\n}\n\n/**\n * T5.9 — Test seam: expose the structural validator for unit tests.\n * NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__validateLockModule(mod: unknown): boolean {\n  return validateLockModule(mod);\n}\n\n/**\n * T5.9 — Test seam: reset the module cache + warning flags between\n * tests so each test starts fresh. NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__resetFileLockCache(): void {\n  cached = undefined;\n  warnedMissing = false;\n  warnedStructural = false;\n  loadFailure = undefined;\n}\n\n/**\n * Retry and staleness tuning for `withFileLock`.\n *\n * Every field is optional and the defaults are applied per call, so `undefined` means the default\n * rather than \"no limit\". They are handed to `proper-lockfile` and have NO effect on the fallback\n * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which\n * queues indefinitely and never goes stale.\n *\n * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a\n * dead process and broken. Setting it below the longest a legitimate holder can run is what turns\n * a slow operation into two concurrent ones.\n *\n * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`\n * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to\n * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall\n * through to running `fn` unlocked.\n *\n * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for\n * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.\n */\nexport interface FileLockOptions {\n  /** Stale lock timeout in ms. Default 30_000 (30s). */\n  stale?: number;\n  /** Max retries on busy lock. Default 5. */\n  retries?: number;\n  /** Backoff factor between retries. Default 1.5. */\n  retryFactor?: number;\n}\n\n/**\n * Run `fn` while holding an OS-level cross-process lock on `path`.\n *\n * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`\n * file (`realpath: false`, so target file does NOT need to exist yet).\n * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot\n * stderr warning telling the user to install `proper-lockfile` for\n * cross-process safety.\n *\n * The lock is released even when `fn` throws.\n *\n */\nexport async function withFileLock<T>(\n  path: string,\n  fn: () => Promise<T>,\n  options?: FileLockOptions,\n): Promise<T> {\n  const lib = await getProperLockfile();\n\n  if (lib === null) {\n    // #174 — stay silent when the structural check already explained itself. Emitting \"not\n    // installed\" on top of \"does not expose lock/unlock\" would be two contradictory diagnoses of\n    // one failure, and the reader has no way to tell which is true.\n    if (!warnedMissing && !warnedStructural) {\n      warnedMissing = true;\n      diag(describeLockLoadFailure(loadFailure));\n    }\n    return withCwdMutex(`file-lock:${path}`, fn);\n  }\n\n  // proper-lockfile errors immediately on same-process concurrent acquire\n  // (\"Lock file is already being held\"). Wrap with cwd-mutex first so\n  // in-process callers queue and only ONE thread at a time enters the\n  // cross-process acquire path. Combined: full in-process + cross-process\n  // serialization.\n  return withCwdMutex(`file-lock:${path}`, async () => {\n    const release = await lib.lock(path, {\n      // EC-1: companion lockfile, target path may not exist yet.\n      lockfilePath: `${path}.lock`,\n      realpath: false,\n      stale: options?.stale ?? 30_000,\n      retries: {\n        retries: options?.retries ?? 5,\n        factor: options?.retryFactor ?? 1.5,\n        minTimeout: 100,\n        maxTimeout: 5_000,\n      },\n    });\n\n    try {\n      return await fn();\n    } finally {\n      await release();\n    }\n  });\n}\n\n/**\n * Test helper — resets the cached proper-lockfile module + warning flag.\n * Allows tests to simulate \"module absent\" by clearing cache then\n * monkey-patching the dynamic import resolution.\n *\n * @internal\n */\nexport function _resetFileLockCacheForTesting(): void {\n  cached = undefined;\n  warnedMissing = false;\n}\n"]}

package/dist/{chunk-U27XHOEF.js → chunk-H7G65PNI.js}

@@ -1,9 +1,9 @@
 import { globalEmbeddingCache } from './chunk-H73MEMQB.js';
-import { parseRetryAfter, mapOpenAICompatibleError } from './chunk-JLIRFWUG.js';
+import { parseRetryAfter, mapOpenAICompatibleError } from './chunk-ZJAYFSVI.js';
 import { computeBackoffMs } from './chunk-24MGQDK3.js';
-import { mapWithConcurrency } from './chunk-7JAKO3NM.js';
+import { mapWithConcurrency } from './chunk-ORLTGPOS.js';
 import { boundFetch } from './chunk-Q7GYMXVC.js';
-import { AuthenticationError, ConfigurationError, NetworkError } from './chunk-B5MHRQJZ.js';
+import { AuthenticationError, ConfigurationError, NetworkError } from './chunk-TNFOU6SB.js';
 import { createHash } from 'crypto';
 
 var MAX_BATCH = 100;
@@ -205,5 +205,5 @@ function sleep(ms) {
 }
 
 export { createOpenAiCompatibleRuntime };
-//# sourceMappingURL=chunk-U27XHOEF.js.map
-//# sourceMappingURL=chunk-U27XHOEF.js.map
+//# sourceMappingURL=chunk-H7G65PNI.js.map
+//# sourceMappingURL=chunk-H7G65PNI.js.map

package/dist/{chunk-U27XHOEF.js.map → chunk-H7G65PNI.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/memory/adapters/openai-compatible.ts"],"names":[],"mappings":"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","file":"chunk-U27XHOEF.js","sourcesContent":["import { createHash } from \"node:crypto\";\n\nimport { AuthenticationError, ConfigurationError, NetworkError } from \"../../../errors.js\";\nimport { mapWithConcurrency } from \"../../concurrency/map-with-concurrency.js\";\nimport { mapOpenAICompatibleError } from \"../../error-mappers/openai-compatible.js\";\nimport { parseRetryAfter } from \"../../error-mappers/shared.js\";\nimport { computeBackoffMs } from \"../../llm/retry.js\";\nimport { boundFetch } from \"../../runtime-fetch.js\";\nimport type {\n  CreateAdapterOptions,\n  EmbeddingRuntime,\n  EmbeddingRuntimeStats,\n} from \"../embedding-adapter.js\";\nimport { globalEmbeddingCache } from \"../embedding-cache.js\";\n\n/**\n * Shared factory for OpenAI-compatible embedding providers (OpenAI, Mistral,\n * DeepInfra, and anything else exposing `POST /v1/embeddings` with the\n * `{ model, input }` request shape and `{ data: [{ embedding }] }` response).\n *\n * Mirrors the inner mechanics of peer-project's batch embedding runtime.\n *\n * @internal\n */\n\nconst MAX_BATCH = 100;\nconst MAX_RETRIES = 2;\n/**\n * Deliberately tighter than the transport's 500ms/32s.\n *\n * An embedding retry sits inside a memory write on the agent's critical path and cannot be\n * cancelled (see `sleep` below), so the worst case has to be small enough to wait out: 2 retries\n * capped at 4s is at most ~8s. The transport can afford 32s because a streaming turn is already\n * long-running and IS abortable.\n */\nconst EMBED_BACKOFF_BASE_MS = 250;\nconst EMBED_BACKOFF_CAP_MS = 4_000;\n\n/**\n * What one provider adapter tells {@link createOpenAiCompatibleRuntime} about\n * its wire: where to POST, which environment variables carry the key and the\n * base URL, which model to use by default, and how wide each model's vectors\n * are.\n *\n * `id` is the provider id that ends up on errors and on\n * `EmbeddingRuntime.id`, and is also the identity the SQLite vector index stores\n * — changing it invalidates the vectors already on disk.\n *\n * `apiKeyEnv` is required, `baseUrlEnv` is not: a provider that declares no\n * base-URL variable can only be redirected by passing `baseUrl` explicitly.\n * Leave `dialect` unset for anything that speaks the OpenAI embedding wire.\n */\nexport interface OpenAiCompatibleConfig {\n  id: string;\n  defaultBaseUrl: string;\n  apiKeyEnv: string;\n  baseUrlEnv?: string;\n  defaultModel: string;\n  /**\n   * Dimension hint by model id. The chosen model MUST be in this table —\n   * unknown models throw `ConfigurationError(code: \"embedding_unknown_model\")`\n   * (EC-4 fix). This prevents vec0 virtual-table dimension mismatches that\n   * surface as cryptic errors downstream.\n   */\n  dimensionByModel: Record<string, number>;\n  /**\n   * Path component appended to `baseUrl` for the embeddings endpoint.\n   * Default `\"/v1/embeddings\"` (OpenAI canonical). REPLACES the default —\n   * does NOT concatenate. Used by DeepInfra (`\"/v1/openai/embeddings\"`),\n   * etc. (EC-2 fix).\n   */\n  embeddingsPath?: string;\n  /**\n   * theokit#159 — per-provider deviations from the OpenAI wire.\n   *\n   * The runtime was rigidly OpenAI-shaped: one auth header, one body, one response shape. Three of\n   * the ten catalog providers do not speak it, so every call they made was rejected — Azure\n   * authenticates with an `api-key` header and puts the deployment in the path, Cohere's `/v2/embed`\n   * takes `texts` and answers `{embeddings:{float}}`. Advertising a provider that cannot work is\n   * worse than not advertising it.\n   *\n   * Every hook is optional and its default is exactly the previous behaviour, so the seven\n   * providers that DO speak OpenAI are untouched.\n   */\n  dialect?: EmbeddingDialect;\n}\n\n/**\n * theokit#159 — the three points where a provider may deviate from the OpenAI embedding wire.\n *\n * Deliberately three narrow hooks rather than a general \"transform the request\" seam: these are the\n * only axes on which the supported providers actually differ, and a wider seam would invite\n * per-provider logic that belongs in the adapter.\n */\nexport interface EmbeddingDialect {\n  /** Replaces `authorization: Bearer <key>`. */\n  authHeaders?: (apiKey: string) => Record<string, string>;\n  /** Replaces the `{ model, input }` request body. */\n  body?: (model: string, inputs: ReadonlyArray<string>) => Record<string, unknown>;\n  /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */\n  vectors?: (json: unknown) => number[][] | undefined;\n}\n\n/**\n * Build an {@link EmbeddingRuntime} for a provider that speaks the OpenAI\n * embedding wire — or, through `cfg.dialect`, one that deviates from it in a\n * known way. Every adapter in the memory catalog is a thin call to this.\n *\n * Resolution order for each setting is explicit option, then environment\n * variable, then the config default. Two things are checked before any request\n * is sent, so a misconfiguration fails at creation rather than at first search:\n * a missing or empty key rejects with an `AuthenticationError` carrying\n * `embedding_missing_api_key`, and a model absent from `dimensionByModel`\n * rejects with a `ConfigurationError` carrying `embedding_unknown_model`. The\n * second check exists because the vector index is created at a fixed width — an\n * unknown dimension would surface much later as a vec0 mismatch.\n *\n * `{model}` in `embeddingsPath` is replaced with the URL-encoded model, which is\n * how Azure addresses a deployment in the path. `embeddingsPath` replaces the\n * default `/v1/embeddings` rather than being appended to it.\n *\n * The returned `embed` batches at 100 texts per request and runs at most 3\n * requests concurrently, preserving input order. Whitespace-only inputs never\n * reach the network and come back as an all-zero vector. Results are cached by\n * model and text; the cache defaults to a process-wide LRU of 5000 entries, so\n * pass `options.cache` when runtimes must not share entries.\n *\n * Failed requests retry up to twice on 429 and 5xx with a 50ms-per-attempt\n * linear backoff. Anything else, and a retry budget that runs out, throws the\n * typed error the OpenAI-compatible mapper builds from the status and body. A\n * response that parses but carries no vectors throws a `NetworkError` with\n * `embedding_invalid_response`. There is no request timeout here — cancellation\n * is the caller's to impose.\n */\nexport async function createOpenAiCompatibleRuntime(\n  cfg: OpenAiCompatibleConfig,\n  options: CreateAdapterOptions,\n): Promise<EmbeddingRuntime> {\n  const model = options.model ?? cfg.defaultModel;\n  const apiKey = options.apiKey ?? process.env[cfg.apiKeyEnv];\n  if (apiKey === undefined || apiKey.length === 0) {\n    throw new AuthenticationError(`${cfg.apiKeyEnv} missing`, {\n      code: \"embedding_missing_api_key\",\n    });\n  }\n  const envBaseUrl = cfg.baseUrlEnv !== undefined ? process.env[cfg.baseUrlEnv] : undefined;\n  const baseUrl = options.baseUrl ?? envBaseUrl ?? cfg.defaultBaseUrl;\n  const fetchImpl = boundFetch(options.fetch);\n  // T4.4 — default to process-wide singleton (was per-adapter instance).\n  const cache = options.cache ?? globalEmbeddingCache;\n  // EC-4: refuse unknown models to prevent vec0 dimension mismatches downstream.\n  const dimension = cfg.dimensionByModel[model];\n  if (dimension === undefined) {\n    throw new ConfigurationError(\n      `${cfg.id} adapter: model \"${model}\" is not in the dimension table. Use one of: ${Object.keys(cfg.dimensionByModel).join(\", \")}. To add it, update dimensionByModel in the adapter source.`,\n      { code: \"embedding_unknown_model\" },\n    );\n  }\n  // theokit#128: `{model}` is substituted, because Azure OpenAI addresses the deployment IN THE\n  // PATH (`/openai/deployments/{model}/embeddings`) rather than in the body. Without this the URL\n  // carried the literal placeholder and every Azure request 404'd. A path with no placeholder —\n  // every other provider — is passed through untouched.\n  const embeddingsPath = (cfg.embeddingsPath ?? \"/v1/embeddings\").replace(\n    \"{model}\",\n    encodeURIComponent(model),\n  );\n\n  const stats: EmbeddingRuntimeStats = {\n    cacheHits: 0,\n    cacheMisses: 0,\n    httpCalls: 0,\n    retries: 0,\n  };\n\n  return {\n    id: cfg.id,\n    model,\n    dimension,\n    stats: () => ({ ...stats }),\n    embed: (texts) =>\n      embedTexts({\n        texts,\n        cache,\n        stats,\n        model,\n        dimension,\n        apiKey,\n        baseUrl,\n        embeddingsPath,\n        fetchImpl,\n        providerId: cfg.id,\n        dialect: cfg.dialect ?? {},\n      }),\n  };\n}\n\ninterface EmbedTextsInput {\n  texts: ReadonlyArray<string>;\n  cache: NonNullable<CreateAdapterOptions[\"cache\"]>;\n  stats: EmbeddingRuntimeStats;\n  model: string;\n  dimension: number;\n  apiKey: string;\n  baseUrl: string;\n  embeddingsPath: string;\n  fetchImpl: typeof fetch;\n  providerId: string;\n  dialect: EmbeddingDialect;\n}\n\nasync function embedTexts(input: EmbedTextsInput): Promise<number[][]> {\n  const { texts, cache, stats, model, dimension } = input;\n  const results = new Array<number[] | undefined>(texts.length);\n  const pending: Array<{ index: number; text: string; key: string }> = [];\n  for (let i = 0; i < texts.length; i++) {\n    classifyEntry({\n      index: i,\n      text: texts[i] ?? \"\",\n      model,\n      dimension,\n      cache,\n      stats,\n      results,\n      pending,\n    });\n  }\n  await embedInBoundedBatches(input, pending, results);\n  return results.map((v) => v ?? new Array(dimension).fill(0));\n}\n\ninterface ClassifyEntryArgs {\n  index: number;\n  text: string;\n  model: string;\n  dimension: number;\n  cache: NonNullable<CreateAdapterOptions[\"cache\"]>;\n  stats: EmbeddingRuntimeStats;\n  results: Array<number[] | undefined>;\n  pending: Array<{ index: number; text: string; key: string }>;\n}\n\nfunction classifyEntry(args: ClassifyEntryArgs): void {\n  if (args.text.trim().length === 0) {\n    args.results[args.index] = new Array(args.dimension).fill(0);\n    return;\n  }\n  const key = hashKey(args.model, args.text);\n  const cached = args.cache.get(key);\n  if (cached !== undefined) {\n    args.stats.cacheHits += 1;\n    args.results[args.index] = cached;\n    return;\n  }\n  args.stats.cacheMisses += 1;\n  args.pending.push({ index: args.index, text: args.text, key });\n}\n\n// T4.3 — max concurrent embedding API requests per embed() call.\n// 3 is enough to saturate most embedding APIs without triggering\n// rate limits (each batch is already up to MAX_BATCH=100 texts).\nconst MAX_CONCURRENT_BATCHES = 3;\n\n/**\n * T4.3 — parallel embed batches (DR4 finding #3).\n *\n * Pre-T4.3 this was a serial `for` loop — each batch of 100 texts\n * awaited before the next HTTP request started. With 500 texts the\n * serial path took 5 × RTT; parallel takes max(RTT) × ceil(5/3).\n *\n * Uses bounded-concurrency `Promise.all` capped at 3 concurrent\n * HTTP requests to avoid overwhelming the embedding API.\n */\nasync function embedInBoundedBatches(\n  input: EmbedTextsInput,\n  pending: ReadonlyArray<{ index: number; text: string; key: string }>,\n  results: Array<number[] | undefined>,\n): Promise<void> {\n  const batches: Array<ReadonlyArray<{ index: number; text: string; key: string }>> = [];\n  for (let offset = 0; offset < pending.length; offset += MAX_BATCH) {\n    batches.push(pending.slice(offset, offset + MAX_BATCH));\n  }\n  // M0-2: bounded parallel via the shared ordered pool (was an inline\n  // acquire/release clone — see plan m0-foundation-expose-primitives).\n  await mapWithConcurrency(batches, MAX_CONCURRENT_BATCHES, (batch) =>\n    processBatch(input, batch, results),\n  );\n}\n\nasync function processBatch(\n  input: EmbedTextsInput,\n  batch: ReadonlyArray<{ index: number; text: string; key: string }>,\n  results: Array<number[] | undefined>,\n): Promise<void> {\n  const vectors = await embedBatch({\n    apiKey: input.apiKey,\n    baseUrl: input.baseUrl,\n    embeddingsPath: input.embeddingsPath,\n    model: input.model,\n    inputs: batch.map((b) => b.text),\n    fetchImpl: input.fetchImpl,\n    stats: input.stats,\n    providerId: input.providerId,\n    dialect: input.dialect,\n  });\n  for (let j = 0; j < batch.length; j++) {\n    const slot = batch[j];\n    const vector = vectors[j];\n    if (slot === undefined || vector === undefined) continue;\n    results[slot.index] = vector;\n    input.cache.set(slot.key, vector);\n  }\n}\n\ninterface BatchOptions {\n  apiKey: string;\n  baseUrl: string;\n  embeddingsPath: string;\n  model: string;\n  inputs: ReadonlyArray<string>;\n  fetchImpl: typeof fetch;\n  stats: EmbeddingRuntimeStats;\n  providerId: string;\n  dialect: EmbeddingDialect;\n}\n\nasync function embedBatch(opts: BatchOptions): Promise<number[][]> {\n  // EC-2: embeddingsPath REPLACES the suffix; never concatenates.\n  const url = `${opts.baseUrl.replace(/\\/$/, \"\")}${opts.embeddingsPath}`;\n  let attempt = 0;\n  while (true) {\n    opts.stats.httpCalls += 1;\n    const response = await postEmbedRequest(opts, url);\n    if (response.ok)\n      return await parseEmbedResponse(response, opts.providerId, opts.embeddingsPath, opts.dialect);\n    if (isRetryable(response.status) && attempt < MAX_RETRIES) {\n      attempt += 1;\n      opts.stats.retries += 1;\n      const retryAfterSec = parseRetryAfter(response.headers);\n      await sleep(\n        computeBackoffMs({\n          attempt,\n          baseMs: EMBED_BACKOFF_BASE_MS,\n          capMs: EMBED_BACKOFF_CAP_MS,\n          ...(retryAfterSec !== undefined ? { retryAfterMs: retryAfterSec * 1000 } : {}),\n        }),\n      );\n      continue;\n    }\n    throw await mappedEmbedError(opts, response);\n  }\n}\n\n/**\n * The terminal failure: read the body best-effort so the mapper sees the provider's error code, then\n * map it. Its own function because folding it back into the retry loop puts `embedBatch` at\n * cognitive complexity 11 against the repo max of 10 — and the sibling budget for those suppressions\n * is ratcheting DOWN, so adding one here to keep this loop whole would undo that.\n */\nasync function mappedEmbedError(opts: BatchOptions, response: Response): Promise<unknown> {\n  const text = await response.text().catch(() => \"\");\n  let body: unknown = text;\n  try {\n    body = JSON.parse(text);\n  } catch {\n    // not JSON — keep as string\n  }\n  return mapOpenAICompatibleError({\n    providerId: opts.providerId,\n    status: response.status,\n    body,\n    headers: response.headers,\n    endpoint: opts.embeddingsPath,\n  });\n}\n\nasync function postEmbedRequest(opts: BatchOptions, url: string): Promise<Response> {\n  return opts.fetchImpl(url, {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      ...(opts.dialect.authHeaders?.(opts.apiKey) ?? { authorization: `Bearer ${opts.apiKey}` }),\n    },\n    body: JSON.stringify(\n      opts.dialect.body?.(opts.model, opts.inputs) ?? { model: opts.model, input: opts.inputs },\n    ),\n  });\n}\n\nasync function parseEmbedResponse(\n  response: Response,\n  providerId: string,\n  endpoint: string,\n  dialect?: EmbeddingDialect,\n): Promise<number[][]> {\n  const json = (await response.json()) as { data?: Array<{ embedding: number[] }> };\n  // theokit#159 — a provider whose response is not OpenAI-shaped supplies its own reader.\n  const viaDialect = dialect?.vectors?.(json);\n  if (viaDialect !== undefined) return viaDialect;\n  if (!Array.isArray(json.data)) {\n    throw new NetworkError(`${providerId} ${endpoint} returned no data`, {\n      code: \"embedding_invalid_response\",\n      metadata: {\n        provider: providerId,\n        endpoint,\n        code: \"invalid_request\",\n        raw: json,\n      },\n    });\n  }\n  return json.data.map((d) => d.embedding);\n}\n\nfunction isRetryable(status: number): boolean {\n  return status === 429 || (status >= 500 && status < 600);\n}\n\nfunction hashKey(model: string, text: string): string {\n  return createHash(\"sha256\").update(`${model} ${text}`).digest(\"hex\");\n}\n\n/**\n * Not `sleepWithAbort`, and the reason is the parsimony ladder rather than an oversight.\n *\n * `EmbeddingRuntime.embed(texts)` takes no signal, and NONE of its seven callers — lance-index,\n * index-manager, vec-index, the two dreaming phases, scorers — holds one to pass. Adding the\n * parameter would add a seam nobody supplies, so cancellation is bounded instead of plumbed: at most\n * MAX_RETRIES sleeps of at most EMBED_BACKOFF_CAP_MS each. Give `embed()` a signal on the day a\n * caller has one, and this becomes `sleepWithAbort` in the same edit.\n */\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}
+{"version":3,"sources":["../src/internal/memory/adapters/openai-compatible.ts"],"names":[],"mappings":"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","file":"chunk-H7G65PNI.js","sourcesContent":["import { createHash } from \"node:crypto\";\n\nimport { AuthenticationError, ConfigurationError, NetworkError } from \"../../../errors.js\";\nimport { mapWithConcurrency } from \"../../concurrency/map-with-concurrency.js\";\nimport { mapOpenAICompatibleError } from \"../../error-mappers/openai-compatible.js\";\nimport { parseRetryAfter } from \"../../error-mappers/shared.js\";\nimport { computeBackoffMs } from \"../../llm/retry.js\";\nimport { boundFetch } from \"../../runtime-fetch.js\";\nimport type {\n  CreateAdapterOptions,\n  EmbeddingRuntime,\n  EmbeddingRuntimeStats,\n} from \"../embedding-adapter.js\";\nimport { globalEmbeddingCache } from \"../embedding-cache.js\";\n\n/**\n * Shared factory for OpenAI-compatible embedding providers (OpenAI, Mistral,\n * DeepInfra, and anything else exposing `POST /v1/embeddings` with the\n * `{ model, input }` request shape and `{ data: [{ embedding }] }` response).\n *\n * Mirrors the inner mechanics of peer-project's batch embedding runtime.\n *\n * @internal\n */\n\nconst MAX_BATCH = 100;\nconst MAX_RETRIES = 2;\n/**\n * Deliberately tighter than the transport's 500ms/32s.\n *\n * An embedding retry sits inside a memory write on the agent's critical path and cannot be\n * cancelled (see `sleep` below), so the worst case has to be small enough to wait out: 2 retries\n * capped at 4s is at most ~8s. The transport can afford 32s because a streaming turn is already\n * long-running and IS abortable.\n */\nconst EMBED_BACKOFF_BASE_MS = 250;\nconst EMBED_BACKOFF_CAP_MS = 4_000;\n\n/**\n * What one provider adapter tells {@link createOpenAiCompatibleRuntime} about\n * its wire: where to POST, which environment variables carry the key and the\n * base URL, which model to use by default, and how wide each model's vectors\n * are.\n *\n * `id` is the provider id that ends up on errors and on\n * `EmbeddingRuntime.id`, and is also the identity the SQLite vector index stores\n * — changing it invalidates the vectors already on disk.\n *\n * `apiKeyEnv` is required, `baseUrlEnv` is not: a provider that declares no\n * base-URL variable can only be redirected by passing `baseUrl` explicitly.\n * Leave `dialect` unset for anything that speaks the OpenAI embedding wire.\n */\nexport interface OpenAiCompatibleConfig {\n  id: string;\n  defaultBaseUrl: string;\n  apiKeyEnv: string;\n  baseUrlEnv?: string;\n  defaultModel: string;\n  /**\n   * Dimension hint by model id. The chosen model MUST be in this table —\n   * unknown models throw `ConfigurationError(code: \"embedding_unknown_model\")`\n   * (EC-4 fix). This prevents vec0 virtual-table dimension mismatches that\n   * surface as cryptic errors downstream.\n   */\n  dimensionByModel: Record<string, number>;\n  /**\n   * Path component appended to `baseUrl` for the embeddings endpoint.\n   * Default `\"/v1/embeddings\"` (OpenAI canonical). REPLACES the default —\n   * does NOT concatenate. Used by DeepInfra (`\"/v1/openai/embeddings\"`),\n   * etc. (EC-2 fix).\n   */\n  embeddingsPath?: string;\n  /**\n   * theokit#159 — per-provider deviations from the OpenAI wire.\n   *\n   * The runtime was rigidly OpenAI-shaped: one auth header, one body, one response shape. Three of\n   * the ten catalog providers do not speak it, so every call they made was rejected — Azure\n   * authenticates with an `api-key` header and puts the deployment in the path, Cohere's `/v2/embed`\n   * takes `texts` and answers `{embeddings:{float}}`. Advertising a provider that cannot work is\n   * worse than not advertising it.\n   *\n   * Every hook is optional and its default is exactly the previous behaviour, so the seven\n   * providers that DO speak OpenAI are untouched.\n   */\n  dialect?: EmbeddingDialect;\n}\n\n/**\n * theokit#159 — the three points where a provider may deviate from the OpenAI embedding wire.\n *\n * Deliberately three narrow hooks rather than a general \"transform the request\" seam: these are the\n * only axes on which the supported providers actually differ, and a wider seam would invite\n * per-provider logic that belongs in the adapter.\n */\nexport interface EmbeddingDialect {\n  /** Replaces `authorization: Bearer <key>`. */\n  authHeaders?: (apiKey: string) => Record<string, string>;\n  /** Replaces the `{ model, input }` request body. */\n  body?: (model: string, inputs: ReadonlyArray<string>) => Record<string, unknown>;\n  /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */\n  vectors?: (json: unknown) => number[][] | undefined;\n}\n\n/**\n * Build an {@link EmbeddingRuntime} for a provider that speaks the OpenAI\n * embedding wire — or, through `cfg.dialect`, one that deviates from it in a\n * known way. Every adapter in the memory catalog is a thin call to this.\n *\n * Resolution order for each setting is explicit option, then environment\n * variable, then the config default. Two things are checked before any request\n * is sent, so a misconfiguration fails at creation rather than at first search:\n * a missing or empty key rejects with an `AuthenticationError` carrying\n * `embedding_missing_api_key`, and a model absent from `dimensionByModel`\n * rejects with a `ConfigurationError` carrying `embedding_unknown_model`. The\n * second check exists because the vector index is created at a fixed width — an\n * unknown dimension would surface much later as a vec0 mismatch.\n *\n * `{model}` in `embeddingsPath` is replaced with the URL-encoded model, which is\n * how Azure addresses a deployment in the path. `embeddingsPath` replaces the\n * default `/v1/embeddings` rather than being appended to it.\n *\n * The returned `embed` batches at 100 texts per request and runs at most 3\n * requests concurrently, preserving input order. Whitespace-only inputs never\n * reach the network and come back as an all-zero vector. Results are cached by\n * model and text; the cache defaults to a process-wide LRU of 5000 entries, so\n * pass `options.cache` when runtimes must not share entries.\n *\n * Failed requests retry up to twice on 429 and 5xx with a 50ms-per-attempt\n * linear backoff. Anything else, and a retry budget that runs out, throws the\n * typed error the OpenAI-compatible mapper builds from the status and body. A\n * response that parses but carries no vectors throws a `NetworkError` with\n * `embedding_invalid_response`. There is no request timeout here — cancellation\n * is the caller's to impose.\n */\nexport async function createOpenAiCompatibleRuntime(\n  cfg: OpenAiCompatibleConfig,\n  options: CreateAdapterOptions,\n): Promise<EmbeddingRuntime> {\n  const model = options.model ?? cfg.defaultModel;\n  const apiKey = options.apiKey ?? process.env[cfg.apiKeyEnv];\n  if (apiKey === undefined || apiKey.length === 0) {\n    throw new AuthenticationError(`${cfg.apiKeyEnv} missing`, {\n      code: \"embedding_missing_api_key\",\n    });\n  }\n  const envBaseUrl = cfg.baseUrlEnv !== undefined ? process.env[cfg.baseUrlEnv] : undefined;\n  const baseUrl = options.baseUrl ?? envBaseUrl ?? cfg.defaultBaseUrl;\n  const fetchImpl = boundFetch(options.fetch);\n  // T4.4 — default to process-wide singleton (was per-adapter instance).\n  const cache = options.cache ?? globalEmbeddingCache;\n  // EC-4: refuse unknown models to prevent vec0 dimension mismatches downstream.\n  const dimension = cfg.dimensionByModel[model];\n  if (dimension === undefined) {\n    throw new ConfigurationError(\n      `${cfg.id} adapter: model \"${model}\" is not in the dimension table. Use one of: ${Object.keys(cfg.dimensionByModel).join(\", \")}. To add it, update dimensionByModel in the adapter source.`,\n      { code: \"embedding_unknown_model\" },\n    );\n  }\n  // theokit#128: `{model}` is substituted, because Azure OpenAI addresses the deployment IN THE\n  // PATH (`/openai/deployments/{model}/embeddings`) rather than in the body. Without this the URL\n  // carried the literal placeholder and every Azure request 404'd. A path with no placeholder —\n  // every other provider — is passed through untouched.\n  const embeddingsPath = (cfg.embeddingsPath ?? \"/v1/embeddings\").replace(\n    \"{model}\",\n    encodeURIComponent(model),\n  );\n\n  const stats: EmbeddingRuntimeStats = {\n    cacheHits: 0,\n    cacheMisses: 0,\n    httpCalls: 0,\n    retries: 0,\n  };\n\n  return {\n    id: cfg.id,\n    model,\n    dimension,\n    stats: () => ({ ...stats }),\n    embed: (texts) =>\n      embedTexts({\n        texts,\n        cache,\n        stats,\n        model,\n        dimension,\n        apiKey,\n        baseUrl,\n        embeddingsPath,\n        fetchImpl,\n        providerId: cfg.id,\n        dialect: cfg.dialect ?? {},\n      }),\n  };\n}\n\ninterface EmbedTextsInput {\n  texts: ReadonlyArray<string>;\n  cache: NonNullable<CreateAdapterOptions[\"cache\"]>;\n  stats: EmbeddingRuntimeStats;\n  model: string;\n  dimension: number;\n  apiKey: string;\n  baseUrl: string;\n  embeddingsPath: string;\n  fetchImpl: typeof fetch;\n  providerId: string;\n  dialect: EmbeddingDialect;\n}\n\nasync function embedTexts(input: EmbedTextsInput): Promise<number[][]> {\n  const { texts, cache, stats, model, dimension } = input;\n  const results = new Array<number[] | undefined>(texts.length);\n  const pending: Array<{ index: number; text: string; key: string }> = [];\n  for (let i = 0; i < texts.length; i++) {\n    classifyEntry({\n      index: i,\n      text: texts[i] ?? \"\",\n      model,\n      dimension,\n      cache,\n      stats,\n      results,\n      pending,\n    });\n  }\n  await embedInBoundedBatches(input, pending, results);\n  return results.map((v) => v ?? new Array(dimension).fill(0));\n}\n\ninterface ClassifyEntryArgs {\n  index: number;\n  text: string;\n  model: string;\n  dimension: number;\n  cache: NonNullable<CreateAdapterOptions[\"cache\"]>;\n  stats: EmbeddingRuntimeStats;\n  results: Array<number[] | undefined>;\n  pending: Array<{ index: number; text: string; key: string }>;\n}\n\nfunction classifyEntry(args: ClassifyEntryArgs): void {\n  if (args.text.trim().length === 0) {\n    args.results[args.index] = new Array(args.dimension).fill(0);\n    return;\n  }\n  const key = hashKey(args.model, args.text);\n  const cached = args.cache.get(key);\n  if (cached !== undefined) {\n    args.stats.cacheHits += 1;\n    args.results[args.index] = cached;\n    return;\n  }\n  args.stats.cacheMisses += 1;\n  args.pending.push({ index: args.index, text: args.text, key });\n}\n\n// T4.3 — max concurrent embedding API requests per embed() call.\n// 3 is enough to saturate most embedding APIs without triggering\n// rate limits (each batch is already up to MAX_BATCH=100 texts).\nconst MAX_CONCURRENT_BATCHES = 3;\n\n/**\n * T4.3 — parallel embed batches (DR4 finding #3).\n *\n * Pre-T4.3 this was a serial `for` loop — each batch of 100 texts\n * awaited before the next HTTP request started. With 500 texts the\n * serial path took 5 × RTT; parallel takes max(RTT) × ceil(5/3).\n *\n * Uses bounded-concurrency `Promise.all` capped at 3 concurrent\n * HTTP requests to avoid overwhelming the embedding API.\n */\nasync function embedInBoundedBatches(\n  input: EmbedTextsInput,\n  pending: ReadonlyArray<{ index: number; text: string; key: string }>,\n  results: Array<number[] | undefined>,\n): Promise<void> {\n  const batches: Array<ReadonlyArray<{ index: number; text: string; key: string }>> = [];\n  for (let offset = 0; offset < pending.length; offset += MAX_BATCH) {\n    batches.push(pending.slice(offset, offset + MAX_BATCH));\n  }\n  // M0-2: bounded parallel via the shared ordered pool (was an inline\n  // acquire/release clone — see plan m0-foundation-expose-primitives).\n  await mapWithConcurrency(batches, MAX_CONCURRENT_BATCHES, (batch) =>\n    processBatch(input, batch, results),\n  );\n}\n\nasync function processBatch(\n  input: EmbedTextsInput,\n  batch: ReadonlyArray<{ index: number; text: string; key: string }>,\n  results: Array<number[] | undefined>,\n): Promise<void> {\n  const vectors = await embedBatch({\n    apiKey: input.apiKey,\n    baseUrl: input.baseUrl,\n    embeddingsPath: input.embeddingsPath,\n    model: input.model,\n    inputs: batch.map((b) => b.text),\n    fetchImpl: input.fetchImpl,\n    stats: input.stats,\n    providerId: input.providerId,\n    dialect: input.dialect,\n  });\n  for (let j = 0; j < batch.length; j++) {\n    const slot = batch[j];\n    const vector = vectors[j];\n    if (slot === undefined || vector === undefined) continue;\n    results[slot.index] = vector;\n    input.cache.set(slot.key, vector);\n  }\n}\n\ninterface BatchOptions {\n  apiKey: string;\n  baseUrl: string;\n  embeddingsPath: string;\n  model: string;\n  inputs: ReadonlyArray<string>;\n  fetchImpl: typeof fetch;\n  stats: EmbeddingRuntimeStats;\n  providerId: string;\n  dialect: EmbeddingDialect;\n}\n\nasync function embedBatch(opts: BatchOptions): Promise<number[][]> {\n  // EC-2: embeddingsPath REPLACES the suffix; never concatenates.\n  const url = `${opts.baseUrl.replace(/\\/$/, \"\")}${opts.embeddingsPath}`;\n  let attempt = 0;\n  while (true) {\n    opts.stats.httpCalls += 1;\n    const response = await postEmbedRequest(opts, url);\n    if (response.ok)\n      return await parseEmbedResponse(response, opts.providerId, opts.embeddingsPath, opts.dialect);\n    if (isRetryable(response.status) && attempt < MAX_RETRIES) {\n      attempt += 1;\n      opts.stats.retries += 1;\n      const retryAfterSec = parseRetryAfter(response.headers);\n      await sleep(\n        computeBackoffMs({\n          attempt,\n          baseMs: EMBED_BACKOFF_BASE_MS,\n          capMs: EMBED_BACKOFF_CAP_MS,\n          ...(retryAfterSec !== undefined ? { retryAfterMs: retryAfterSec * 1000 } : {}),\n        }),\n      );\n      continue;\n    }\n    throw await mappedEmbedError(opts, response);\n  }\n}\n\n/**\n * The terminal failure: read the body best-effort so the mapper sees the provider's error code, then\n * map it. Its own function because folding it back into the retry loop puts `embedBatch` at\n * cognitive complexity 11 against the repo max of 10 — and the sibling budget for those suppressions\n * is ratcheting DOWN, so adding one here to keep this loop whole would undo that.\n */\nasync function mappedEmbedError(opts: BatchOptions, response: Response): Promise<unknown> {\n  const text = await response.text().catch(() => \"\");\n  let body: unknown = text;\n  try {\n    body = JSON.parse(text);\n  } catch {\n    // not JSON — keep as string\n  }\n  return mapOpenAICompatibleError({\n    providerId: opts.providerId,\n    status: response.status,\n    body,\n    headers: response.headers,\n    endpoint: opts.embeddingsPath,\n  });\n}\n\nasync function postEmbedRequest(opts: BatchOptions, url: string): Promise<Response> {\n  return opts.fetchImpl(url, {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      ...(opts.dialect.authHeaders?.(opts.apiKey) ?? { authorization: `Bearer ${opts.apiKey}` }),\n    },\n    body: JSON.stringify(\n      opts.dialect.body?.(opts.model, opts.inputs) ?? { model: opts.model, input: opts.inputs },\n    ),\n  });\n}\n\nasync function parseEmbedResponse(\n  response: Response,\n  providerId: string,\n  endpoint: string,\n  dialect?: EmbeddingDialect,\n): Promise<number[][]> {\n  const json = (await response.json()) as { data?: Array<{ embedding: number[] }> };\n  // theokit#159 — a provider whose response is not OpenAI-shaped supplies its own reader.\n  const viaDialect = dialect?.vectors?.(json);\n  if (viaDialect !== undefined) return viaDialect;\n  if (!Array.isArray(json.data)) {\n    throw new NetworkError(`${providerId} ${endpoint} returned no data`, {\n      code: \"embedding_invalid_response\",\n      metadata: {\n        provider: providerId,\n        endpoint,\n        code: \"invalid_request\",\n        raw: json,\n      },\n    });\n  }\n  return json.data.map((d) => d.embedding);\n}\n\nfunction isRetryable(status: number): boolean {\n  return status === 429 || (status >= 500 && status < 600);\n}\n\nfunction hashKey(model: string, text: string): string {\n  return createHash(\"sha256\").update(`${model} ${text}`).digest(\"hex\");\n}\n\n/**\n * Not `sleepWithAbort`, and the reason is the parsimony ladder rather than an oversight.\n *\n * `EmbeddingRuntime.embed(texts)` takes no signal, and NONE of its seven callers — lance-index,\n * index-manager, vec-index, the two dreaming phases, scorers — holds one to pass. Adding the\n * parameter would add a seam nobody supplies, so cancellation is bounded instead of plumbed: at most\n * MAX_RETRIES sleeps of at most EMBED_BACKOFF_CAP_MS each. Give `embed()` a signal on the day a\n * caller has one, and this becomes `sleepWithAbort` in the same edit.\n */\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}