@theokit/sdk 5.15.1 → 5.15.2

package/dist/{chunk-5IRDK5BC.js.map → chunk-QH6MWGOA.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/session-writer.ts"],"names":[],"mappings":"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","file":"chunk-5IRDK5BC.js","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":[],"mappings":"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","file":"chunk-QH6MWGOA.js","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-3LMVJTNJ.js → chunk-QPUKIZOT.js}

@@ -1,4 +1,4 @@
-import { setupStructuredOutput, makeOutputTool, buildTransientAgentOptions, buildToolPrompt, extractUsage, STRUCTURED_OUTPUT_MESSAGES, disposeAndDeleteTransient } from './chunk-DFBWYETS.js';
+import { setupStructuredOutput, makeOutputTool, buildTransientAgentOptions, buildToolPrompt, extractUsage, STRUCTURED_OUTPUT_MESSAGES, disposeAndDeleteTransient } from './chunk-JRP2W2DR.js';
 import { StructuredOutputError } from './chunk-TNFOU6SB.js';
 
 // src/generate-object.ts
@@ -133,5 +133,5 @@ async function generateObjectImpl(options, deps) {
 }
 
 export { GenerateObjectError, generateObjectImpl };
-//# sourceMappingURL=chunk-3LMVJTNJ.js.map
-//# sourceMappingURL=chunk-3LMVJTNJ.js.map
+//# sourceMappingURL=chunk-QPUKIZOT.js.map
+//# sourceMappingURL=chunk-QPUKIZOT.js.map

package/dist/{chunk-3LMVJTNJ.js.map → chunk-QPUKIZOT.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/generate-object.ts"],"names":[],"mappings":"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","file":"chunk-3LMVJTNJ.js","sourcesContent":["import type { z as ZodNamespace, ZodType } from \"zod\";\nimport { StructuredOutputError } from \"./errors.js\";\nimport {\n  buildToolPrompt,\n  buildTransientAgentOptions,\n  disposeAndDeleteTransient,\n  extractUsage,\n  makeOutputTool,\n  STRUCTURED_OUTPUT_MESSAGES,\n  setupStructuredOutput,\n} from \"./internal/structured-output-helpers.js\";\nimport type {\n  AgentOptions,\n  BuiltinToolName,\n  LocalOptions,\n  MemorySettings,\n  ModelSelection,\n  SDKAgent,\n} from \"./types/agent.js\";\nimport type { ProviderRoutingSettings } from \"./types/providers.js\";\n\n/**\n * Options accepted by {@link Agent.generateObject}. Returns a typed object\n * matching the supplied Zod schema. See ADR D33.\n *\n * @public\n */\nexport interface GenerateObjectOptions<T extends ZodType> {\n  /** Zod schema describing the expected object shape. */\n  schema: T;\n  /** User prompt — the model is asked to fill the schema given this prompt. */\n  prompt: string;\n  /** Optional system prompt steering the model. */\n  systemPrompt?: string;\n  /** Model selection. Required (transient agents need a model). SE8 — accepts a\n   *  bare-string id shorthand (`\"openai/gpt-4o-mini\"`) or a {@link ModelSelection}. */\n  model: string | ModelSelection;\n  /**\n   * M21 — optional separate model for the STRUCTURING step. When set, `model` first produces a\n   * free-text reasoned answer to the prompt (phase 1), then `structuringModel` extracts the\n   * schema-matched object by calling the `output` tool over that answer (phase 2). Lets a large\n   * model reason while a cheap fast model does the extraction. Absent ⇒ today's single-model flow.\n   */\n  structuringModel?: string | ModelSelection;\n  /** API key. Falls back to env (THEOKIT_API_KEY etc). */\n  apiKey?: string;\n  /** Local runtime config (cwd, sandbox). Required to keep the transient agent local-only. */\n  local: LocalOptions;\n  /**\n   * Retry budget on parse failures. Default 1 (initial attempt + 1 retry).\n   * The transient agent is REUSED across retries so the registry sees a\n   * single entry (EC-3).\n   */\n  maxRetries?: number;\n  /**\n   * Optional provider routing forwarded to the transient agent. Required when\n   * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is\n   * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers\n   * provider from the prefix and may fail with `provider_unresolved` even\n   * when the right env key is set under a different provider name.\n   */\n  providers?: ProviderRoutingSettings;\n  /**\n   * What to do when the model's output fails schema validation after all\n   * retries are exhausted (M14):\n   * - `'throw'` (default) — throw {@link GenerateObjectError} `parse_failed`.\n   * - `'return-raw'` — resolve with the raw, UNVALIDATED input the model sent\n   *   (`object` may not match the schema; inspect `raw` too).\n   * - `'return-partial'` — for object schemas, resolve with only the fields that\n   *   individually validate (best-effort salvage); non-object schemas fall back\n   *   to raw.\n   */\n  errorStrategy?: \"throw\" | \"return-partial\" | \"return-raw\";\n  /**\n   * Builtin tools removed from every transient agent's catalogue (the reasoning-phase agent of\n   * `structuringModel` included), forwarded to {@link AgentOptions.withheldBuiltinTools}.\n   * Absent ⇒ unchanged default: the agent holds `shell`. Pass `[\"shell\"]` for a step that must\n   * only produce JSON. The `output` tool is never withheld.\n   */\n  withheldBuiltinTools?: readonly BuiltinToolName[];\n  /**\n   * Memory settings for every transient agent of the call, forwarded to {@link AgentOptions.memory}.\n   * Absent ⇒ unchanged default (a session transcript is written). Pass `{ enabled: false }`\n   * for a step that must leave no transcript.\n   */\n  memory?: MemorySettings;\n}\n\n/**\n * Successful return from {@link Agent.generateObject}.\n *\n * @public\n */\nexport interface GenerateObjectResult<T> {\n  /** Typed object parsed via the Zod schema. */\n  object: T;\n  /** Raw input the model passed to the synthetic tool, before Zod parse. */\n  raw: unknown;\n  /** Token usage of the LLM call(s) that produced the result. */\n  usage: { inputTokens: number; outputTokens: number };\n  /** Stop reason of the underlying agent run. */\n  finishReason: \"tool_use\" | \"error\";\n}\n\n/**\n * Typed error thrown by {@link Agent.generateObject} when the model refuses\n * to call the synthetic `output` tool or when retries are exhausted.\n *\n * @public\n */\nexport class GenerateObjectError extends StructuredOutputError {\n  override readonly name = \"GenerateObjectError\";\n}\n\ninterface GenerateObjectDeps {\n  create: (options: AgentOptions) => Promise<SDKAgent>;\n  /** Hard-delete the transient agent from the registry after dispose. */\n  delete: (agentId: string) => Promise<void>;\n}\n\n/**\n * M14 — best-effort partial salvage for `errorStrategy: 'return-partial'`. For an object schema,\n * keep only the fields that individually validate; anything else (non-object schema or non-object\n * raw) falls back to the raw value. Works across Zod v3/v4 via the `.shape` record both expose.\n */\nfunction salvagePartial<T extends ZodType>(schema: T, raw: unknown): unknown {\n  if (typeof raw !== \"object\" || raw === null) return raw;\n  const shape = (schema as { shape?: Record<string, ZodType> }).shape;\n  if (shape === undefined || typeof shape !== \"object\") return raw;\n  const rawObj = raw as Record<string, unknown>;\n  const out: Record<string, unknown> = {};\n  for (const [key, fieldSchema] of Object.entries(shape)) {\n    if (typeof fieldSchema?.safeParse !== \"function\") continue;\n    const parsed = fieldSchema.safeParse(rawObj[key]);\n    if (parsed.success) out[key] = parsed.data;\n  }\n  return out;\n}\n\n/**\n * M21 — phase 1: run `options.model` as a plain reasoning agent (no output tool) and return its\n * free-text answer, which phase 2's structuring model then extracts. The transient reasoning agent\n * is disposed + hard-deleted so the registry count stays stable (EC-3, mirrors the phase-2 finally).\n */\nasync function runReasoningPhase<T extends ZodType>(\n  options: GenerateObjectOptions<T>,\n  deps: GenerateObjectDeps,\n): Promise<string> {\n  const reasoningOptions: AgentOptions = {\n    model: options.model,\n    local: options.local,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n    ...(options.withheldBuiltinTools !== undefined\n      ? { withheldBuiltinTools: options.withheldBuiltinTools }\n      : {}),\n    ...(options.memory !== undefined ? { memory: options.memory } : {}),\n  };\n  const reasoningAgent = await deps.create(reasoningOptions);\n  try {\n    const run = await reasoningAgent.send(options.prompt);\n    const result = await run.wait();\n    const text = (result as { result?: unknown }).result;\n    return typeof text === \"string\" ? text : options.prompt;\n  } finally {\n    await disposeAndDeleteTransient(reasoningAgent, deps.delete);\n  }\n}\n\n/**\n * Implementation of `Agent.generateObject`. Receives the `Agent.create`\n * factory as a callback to keep the dependency graph acyclic (mirrors the\n * AgentBuilder pattern in D25 / agent.ts injection).\n *\n * Algorithm:\n *   1. Convert the consumer's Zod schema to JSON Schema.\n *   2. Build a single synthetic `output` CustomTool whose handler captures\n *      the raw input and short-circuits the agent loop. The handler\n *      THROWS a sentinel so the loop terminates immediately without a\n *      second LLM round-trip.\n *   3. Create ONE transient agent (per the entire generateObject call,\n *      not per retry — EC-3). Each retry re-sends through the same agent,\n *      driving fresh LLM rounds.\n *   4. On each attempt, send a wrapper prompt instructing the model to\n *      call the `output` tool. Capture the raw input via the sentinel.\n *   5. Parse the raw input via schema.parse. On success, return typed.\n *      On failure, retry until the budget is exhausted.\n *   6. Always dispose the transient agent in `finally`.\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: retry loop + capture sentinel + dispose-and-delete is a single transaction; splitting harms locality and the finally block.\nexport async function generateObjectImpl<T extends ZodType>(\n  options: GenerateObjectOptions<T>,\n  deps: GenerateObjectDeps,\n): Promise<GenerateObjectResult<ZodNamespace.infer<T>>> {\n  const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(\n    options.schema,\n    options.maxRetries,\n  );\n  let capturedRaw: unknown;\n  let lastUsage = initialUsage;\n  const sentinel = Symbol(\"generate-object-sentinel\");\n  class CaptureSentinel extends Error {\n    readonly [sentinel] = true;\n    constructor(public readonly captured: unknown) {\n      super(\"generate-object-capture\");\n    }\n  }\n\n  const outputTool = makeOutputTool(jsonSchema, (input) => {\n    // EC-D10 (parallel tool use): first capture wins. Subsequent calls\n    // in the same response are ignored.\n    if (capturedRaw === undefined) {\n      capturedRaw = input;\n    }\n    throw new CaptureSentinel(input);\n  });\n\n  // M21 — when a separate structuring model is set, `model` first reasons in free text (phase 1),\n  // and `structuringModel` extracts the object over that text (phase 2). Absent ⇒ single-model flow.\n  const reasoningText =\n    options.structuringModel !== undefined ? await runReasoningPhase(options, deps) : undefined;\n  const structuringModel = options.structuringModel ?? options.model;\n  const structuringPrompt = reasoningText ?? options.prompt;\n\n  const agentOptions: AgentOptions = buildTransientAgentOptions({\n    model: structuringModel,\n    local: options.local,\n    outputTool,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n    ...(options.withheldBuiltinTools !== undefined\n      ? { withheldBuiltinTools: options.withheldBuiltinTools }\n      : {}),\n    ...(options.memory !== undefined ? { memory: options.memory } : {}),\n  });\n  const agent = await deps.create(agentOptions);\n\n  try {\n    const userMessage = buildToolPrompt(structuringPrompt);\n    let lastParseError: unknown;\n\n    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {\n      capturedRaw = undefined;\n      const run = await agent.send(userMessage);\n      const result = await run.wait();\n      lastUsage = extractUsage(result);\n\n      if (capturedRaw === undefined) {\n        // EC: when the underlying run errored (e.g. provider_unresolved),\n        // surface the original cause instead of the misleading \"model\n        // returned text\" message — there was no model call at all.\n        if (result.status === \"error\" && result.error !== undefined) {\n          throw new GenerateObjectError(\n            \"no_tool_call\",\n            STRUCTURED_OUTPUT_MESSAGES.runFailed(result.error.message, result.error.code),\n            result.error,\n          );\n        }\n        // Model didn't call the output tool.\n        if (attempt === maxRetries) {\n          throw new GenerateObjectError(\"no_tool_call\", STRUCTURED_OUTPUT_MESSAGES.noToolCall);\n        }\n        continue;\n      }\n\n      const parsed = options.schema.safeParse(capturedRaw);\n      if (parsed.success) {\n        return {\n          object: parsed.data,\n          raw: capturedRaw,\n          usage: lastUsage,\n          finishReason: \"tool_use\",\n        };\n      }\n      lastParseError = parsed.error;\n    }\n\n    // M14 — all retries exhausted with a parse failure. `errorStrategy` decides the outcome; the\n    // tool WAS called (capturedRaw is set), so `finishReason` stays `tool_use`.\n    if (options.errorStrategy === \"return-raw\") {\n      return {\n        object: capturedRaw as ZodNamespace.infer<T>,\n        raw: capturedRaw,\n        usage: lastUsage,\n        finishReason: \"tool_use\",\n      };\n    }\n    if (options.errorStrategy === \"return-partial\") {\n      return {\n        object: salvagePartial(options.schema, capturedRaw) as ZodNamespace.infer<T>,\n        raw: capturedRaw,\n        usage: lastUsage,\n        finishReason: \"tool_use\",\n      };\n    }\n    throw new GenerateObjectError(\n      \"parse_failed\",\n      STRUCTURED_OUTPUT_MESSAGES.parseFailed,\n      lastParseError,\n    );\n  } finally {\n    // EC-3: dispose AND hard-delete the transient agent so registry count\n    // stays stable across retries.\n    await disposeAndDeleteTransient(agent, deps.delete);\n  }\n}\n"]}
+{"version":3,"sources":["../src/generate-object.ts"],"names":[],"mappings":"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","file":"chunk-QPUKIZOT.js","sourcesContent":["import type { z as ZodNamespace, ZodType } from \"zod\";\nimport { StructuredOutputError } from \"./errors.js\";\nimport {\n  buildToolPrompt,\n  buildTransientAgentOptions,\n  disposeAndDeleteTransient,\n  extractUsage,\n  makeOutputTool,\n  STRUCTURED_OUTPUT_MESSAGES,\n  setupStructuredOutput,\n} from \"./internal/structured-output-helpers.js\";\nimport type {\n  AgentOptions,\n  BuiltinToolName,\n  LocalOptions,\n  MemorySettings,\n  ModelSelection,\n  SDKAgent,\n} from \"./types/agent.js\";\nimport type { ProviderRoutingSettings } from \"./types/providers.js\";\n\n/**\n * Options accepted by {@link Agent.generateObject}. Returns a typed object\n * matching the supplied Zod schema. See ADR D33.\n *\n * @public\n */\nexport interface GenerateObjectOptions<T extends ZodType> {\n  /** Zod schema describing the expected object shape. */\n  schema: T;\n  /** User prompt — the model is asked to fill the schema given this prompt. */\n  prompt: string;\n  /** Optional system prompt steering the model. */\n  systemPrompt?: string;\n  /** Model selection. Required (transient agents need a model). SE8 — accepts a\n   *  bare-string id shorthand (`\"openai/gpt-4o-mini\"`) or a {@link ModelSelection}. */\n  model: string | ModelSelection;\n  /**\n   * M21 — optional separate model for the STRUCTURING step. When set, `model` first produces a\n   * free-text reasoned answer to the prompt (phase 1), then `structuringModel` extracts the\n   * schema-matched object by calling the `output` tool over that answer (phase 2). Lets a large\n   * model reason while a cheap fast model does the extraction. Absent ⇒ today's single-model flow.\n   */\n  structuringModel?: string | ModelSelection;\n  /** API key. Falls back to env (THEOKIT_API_KEY etc). */\n  apiKey?: string;\n  /** Local runtime config (cwd, sandbox). Required to keep the transient agent local-only. */\n  local: LocalOptions;\n  /**\n   * Retry budget on parse failures. Default 1 (initial attempt + 1 retry).\n   * The transient agent is REUSED across retries so the registry sees a\n   * single entry (EC-3).\n   */\n  maxRetries?: number;\n  /**\n   * Optional provider routing forwarded to the transient agent. Required when\n   * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is\n   * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers\n   * provider from the prefix and may fail with `provider_unresolved` even\n   * when the right env key is set under a different provider name.\n   */\n  providers?: ProviderRoutingSettings;\n  /**\n   * What to do when the model's output fails schema validation after all\n   * retries are exhausted (M14):\n   * - `'throw'` (default) — throw {@link GenerateObjectError} `parse_failed`.\n   * - `'return-raw'` — resolve with the raw, UNVALIDATED input the model sent\n   *   (`object` may not match the schema; inspect `raw` too).\n   * - `'return-partial'` — for object schemas, resolve with only the fields that\n   *   individually validate (best-effort salvage); non-object schemas fall back\n   *   to raw.\n   */\n  errorStrategy?: \"throw\" | \"return-partial\" | \"return-raw\";\n  /**\n   * Builtin tools removed from every transient agent's catalogue (the reasoning-phase agent of\n   * `structuringModel` included), forwarded to {@link AgentOptions.withheldBuiltinTools}.\n   * Absent ⇒ unchanged default: the agent holds `shell`. Pass `[\"shell\"]` for a step that must\n   * only produce JSON. The `output` tool is never withheld.\n   */\n  withheldBuiltinTools?: readonly BuiltinToolName[];\n  /**\n   * Memory settings for every transient agent of the call, forwarded to {@link AgentOptions.memory}.\n   * Absent ⇒ unchanged default (a session transcript is written). Pass `{ enabled: false }`\n   * for a step that must leave no transcript.\n   */\n  memory?: MemorySettings;\n}\n\n/**\n * Successful return from {@link Agent.generateObject}.\n *\n * @public\n */\nexport interface GenerateObjectResult<T> {\n  /** Typed object parsed via the Zod schema. */\n  object: T;\n  /** Raw input the model passed to the synthetic tool, before Zod parse. */\n  raw: unknown;\n  /** Token usage of the LLM call(s) that produced the result. */\n  usage: { inputTokens: number; outputTokens: number };\n  /** Stop reason of the underlying agent run. */\n  finishReason: \"tool_use\" | \"error\";\n}\n\n/**\n * Typed error thrown by {@link Agent.generateObject} when the model refuses\n * to call the synthetic `output` tool or when retries are exhausted.\n *\n * @public\n */\nexport class GenerateObjectError extends StructuredOutputError {\n  override readonly name = \"GenerateObjectError\";\n}\n\ninterface GenerateObjectDeps {\n  create: (options: AgentOptions) => Promise<SDKAgent>;\n  /** Hard-delete the transient agent from the registry after dispose. */\n  delete: (agentId: string) => Promise<void>;\n}\n\n/**\n * M14 — best-effort partial salvage for `errorStrategy: 'return-partial'`. For an object schema,\n * keep only the fields that individually validate; anything else (non-object schema or non-object\n * raw) falls back to the raw value. Works across Zod v3/v4 via the `.shape` record both expose.\n */\nfunction salvagePartial<T extends ZodType>(schema: T, raw: unknown): unknown {\n  if (typeof raw !== \"object\" || raw === null) return raw;\n  const shape = (schema as { shape?: Record<string, ZodType> }).shape;\n  if (shape === undefined || typeof shape !== \"object\") return raw;\n  const rawObj = raw as Record<string, unknown>;\n  const out: Record<string, unknown> = {};\n  for (const [key, fieldSchema] of Object.entries(shape)) {\n    if (typeof fieldSchema?.safeParse !== \"function\") continue;\n    const parsed = fieldSchema.safeParse(rawObj[key]);\n    if (parsed.success) out[key] = parsed.data;\n  }\n  return out;\n}\n\n/**\n * M21 — phase 1: run `options.model` as a plain reasoning agent (no output tool) and return its\n * free-text answer, which phase 2's structuring model then extracts. The transient reasoning agent\n * is disposed + hard-deleted so the registry count stays stable (EC-3, mirrors the phase-2 finally).\n */\nasync function runReasoningPhase<T extends ZodType>(\n  options: GenerateObjectOptions<T>,\n  deps: GenerateObjectDeps,\n): Promise<string> {\n  const reasoningOptions: AgentOptions = {\n    model: options.model,\n    local: options.local,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n    ...(options.withheldBuiltinTools !== undefined\n      ? { withheldBuiltinTools: options.withheldBuiltinTools }\n      : {}),\n    ...(options.memory !== undefined ? { memory: options.memory } : {}),\n  };\n  const reasoningAgent = await deps.create(reasoningOptions);\n  try {\n    const run = await reasoningAgent.send(options.prompt);\n    const result = await run.wait();\n    const text = (result as { result?: unknown }).result;\n    return typeof text === \"string\" ? text : options.prompt;\n  } finally {\n    await disposeAndDeleteTransient(reasoningAgent, deps.delete);\n  }\n}\n\n/**\n * Implementation of `Agent.generateObject`. Receives the `Agent.create`\n * factory as a callback to keep the dependency graph acyclic (mirrors the\n * AgentBuilder pattern in D25 / agent.ts injection).\n *\n * Algorithm:\n *   1. Convert the consumer's Zod schema to JSON Schema.\n *   2. Build a single synthetic `output` CustomTool whose handler captures\n *      the raw input and short-circuits the agent loop. The handler\n *      THROWS a sentinel so the loop terminates immediately without a\n *      second LLM round-trip.\n *   3. Create ONE transient agent (per the entire generateObject call,\n *      not per retry — EC-3). Each retry re-sends through the same agent,\n *      driving fresh LLM rounds.\n *   4. On each attempt, send a wrapper prompt instructing the model to\n *      call the `output` tool. Capture the raw input via the sentinel.\n *   5. Parse the raw input via schema.parse. On success, return typed.\n *      On failure, retry until the budget is exhausted.\n *   6. Always dispose the transient agent in `finally`.\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: retry loop + capture sentinel + dispose-and-delete is a single transaction; splitting harms locality and the finally block.\nexport async function generateObjectImpl<T extends ZodType>(\n  options: GenerateObjectOptions<T>,\n  deps: GenerateObjectDeps,\n): Promise<GenerateObjectResult<ZodNamespace.infer<T>>> {\n  const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(\n    options.schema,\n    options.maxRetries,\n  );\n  let capturedRaw: unknown;\n  let lastUsage = initialUsage;\n  const sentinel = Symbol(\"generate-object-sentinel\");\n  class CaptureSentinel extends Error {\n    readonly [sentinel] = true;\n    constructor(public readonly captured: unknown) {\n      super(\"generate-object-capture\");\n    }\n  }\n\n  const outputTool = makeOutputTool(jsonSchema, (input) => {\n    // EC-D10 (parallel tool use): first capture wins. Subsequent calls\n    // in the same response are ignored.\n    if (capturedRaw === undefined) {\n      capturedRaw = input;\n    }\n    throw new CaptureSentinel(input);\n  });\n\n  // M21 — when a separate structuring model is set, `model` first reasons in free text (phase 1),\n  // and `structuringModel` extracts the object over that text (phase 2). Absent ⇒ single-model flow.\n  const reasoningText =\n    options.structuringModel !== undefined ? await runReasoningPhase(options, deps) : undefined;\n  const structuringModel = options.structuringModel ?? options.model;\n  const structuringPrompt = reasoningText ?? options.prompt;\n\n  const agentOptions: AgentOptions = buildTransientAgentOptions({\n    model: structuringModel,\n    local: options.local,\n    outputTool,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n    ...(options.withheldBuiltinTools !== undefined\n      ? { withheldBuiltinTools: options.withheldBuiltinTools }\n      : {}),\n    ...(options.memory !== undefined ? { memory: options.memory } : {}),\n  });\n  const agent = await deps.create(agentOptions);\n\n  try {\n    const userMessage = buildToolPrompt(structuringPrompt);\n    let lastParseError: unknown;\n\n    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {\n      capturedRaw = undefined;\n      const run = await agent.send(userMessage);\n      const result = await run.wait();\n      lastUsage = extractUsage(result);\n\n      if (capturedRaw === undefined) {\n        // EC: when the underlying run errored (e.g. provider_unresolved),\n        // surface the original cause instead of the misleading \"model\n        // returned text\" message — there was no model call at all.\n        if (result.status === \"error\" && result.error !== undefined) {\n          throw new GenerateObjectError(\n            \"no_tool_call\",\n            STRUCTURED_OUTPUT_MESSAGES.runFailed(result.error.message, result.error.code),\n            result.error,\n          );\n        }\n        // Model didn't call the output tool.\n        if (attempt === maxRetries) {\n          throw new GenerateObjectError(\"no_tool_call\", STRUCTURED_OUTPUT_MESSAGES.noToolCall);\n        }\n        continue;\n      }\n\n      const parsed = options.schema.safeParse(capturedRaw);\n      if (parsed.success) {\n        return {\n          object: parsed.data,\n          raw: capturedRaw,\n          usage: lastUsage,\n          finishReason: \"tool_use\",\n        };\n      }\n      lastParseError = parsed.error;\n    }\n\n    // M14 — all retries exhausted with a parse failure. `errorStrategy` decides the outcome; the\n    // tool WAS called (capturedRaw is set), so `finishReason` stays `tool_use`.\n    if (options.errorStrategy === \"return-raw\") {\n      return {\n        object: capturedRaw as ZodNamespace.infer<T>,\n        raw: capturedRaw,\n        usage: lastUsage,\n        finishReason: \"tool_use\",\n      };\n    }\n    if (options.errorStrategy === \"return-partial\") {\n      return {\n        object: salvagePartial(options.schema, capturedRaw) as ZodNamespace.infer<T>,\n        raw: capturedRaw,\n        usage: lastUsage,\n        finishReason: \"tool_use\",\n      };\n    }\n    throw new GenerateObjectError(\n      \"parse_failed\",\n      STRUCTURED_OUTPUT_MESSAGES.parseFailed,\n      lastParseError,\n    );\n  } finally {\n    // EC-3: dispose AND hard-delete the transient agent so registry count\n    // stays stable across retries.\n    await disposeAndDeleteTransient(agent, deps.delete);\n  }\n}\n"]}

package/dist/{chunk-SWALPLFQ.cjs → chunk-RTCO3USA.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-var fs = require('fs');
-var promises = require('fs/promises');
-var path = require('path');
+var node_fs = require('node:fs');
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
 
 // src/internal/runtime/context/context-discovery.ts
 function admittedSpecs(specs, declaredKinds) {
@@ -183,15 +183,15 @@ var TRAVERSAL_RE = /(^|\/)\.\.(\/|$)/;
 function isSafePattern(pattern) {
   if (typeof pattern !== "string" || pattern.length === 0) return false;
   if (TRAVERSAL_RE.test(pattern)) return false;
-  if (path.isAbsolute(pattern)) return false;
+  if (node_path.isAbsolute(pattern)) return false;
   return SAFE_FILENAME.test(pattern);
 }
 function findGitRoot(cwd) {
   if (typeof cwd !== "string" || cwd.length === 0) return void 0;
-  let current = path.resolve(cwd);
+  let current = node_path.resolve(cwd);
   for (let i = 0; i < 64; i += 1) {
-    if (fs.existsSync(path.join(current, ".git"))) return current;
-    const parent = path.dirname(current);
+    if (node_fs.existsSync(node_path.join(current, ".git"))) return current;
+    const parent = node_path.dirname(current);
     if (parent === current) return void 0;
     current = parent;
   }
@@ -201,17 +201,17 @@ function walkUpForFile(cwd, filename, stopDir) {
   if (!isSafePattern(filename)) {
     return [];
   }
-  const start = path.resolve(cwd);
-  const stop = stopDir !== void 0 ? path.resolve(stopDir) : void 0;
+  const start = node_path.resolve(cwd);
+  const stop = stopDir !== void 0 ? node_path.resolve(stopDir) : void 0;
   const found = [];
   const seenReal = /* @__PURE__ */ new Set();
   let current = start;
   for (let i = 0; i < 64; i += 1) {
-    const candidate = path.join(current, filename);
-    if (fs.existsSync(candidate)) {
+    const candidate = node_path.join(current, filename);
+    if (node_fs.existsSync(candidate)) {
       let real;
       try {
-        real = fs.realpathSync(candidate);
+        real = node_fs.realpathSync(candidate);
       } catch {
         real = candidate;
       }
@@ -221,7 +221,7 @@ function walkUpForFile(cwd, filename, stopDir) {
       }
     }
     if (stop !== void 0 && current === stop) break;
-    const parent = path.dirname(current);
+    const parent = node_path.dirname(current);
     if (parent === current) break;
     current = parent;
   }
@@ -232,7 +232,7 @@ async function walkUpForGlob(cwd, pattern) {
   const found = [];
   try {
     for await (const entry of promises.glob(pattern, { cwd })) {
-      found.push(path.resolve(cwd, entry));
+      found.push(node_path.resolve(cwd, entry));
     }
   } catch {
     return [];
@@ -247,5 +247,5 @@ exports.isSafePattern = isSafePattern;
 exports.walkUpForFile = walkUpForFile;
 exports.walkUpForGlob = walkUpForGlob;
 exports.withheldSpecs = withheldSpecs;
-//# sourceMappingURL=chunk-SWALPLFQ.cjs.map
-//# sourceMappingURL=chunk-SWALPLFQ.cjs.map
+//# sourceMappingURL=chunk-RTCO3USA.cjs.map
+//# sourceMappingURL=chunk-RTCO3USA.cjs.map

package/dist/chunk-RTCO3USA.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/context/context-discovery.ts"],"names":["isAbsolute","resolve","existsSync","join","dirname","realpathSync","glob"],"mappings":"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","file":"chunk-RTCO3USA.cjs","sourcesContent":["/**\n * Context file discovery (T1.1, ADRs D150 / D151).\n *\n * Discovers context files via three scopes:\n *  - `cwd-only` — single dir, single path lookup\n *  - `git-root-walk` — walk cwd → git-root, collect every directory's match\n *    (nearest-first ordering)\n *  - `globbed` — glob pattern relative to cwd (e.g. `.cursor/rules/*.mdc`)\n *\n * Pure `existsSync` checks — **no `.gitignore` parsing** (EC-A, KISS) and\n * **no invented `.theokitignore`** (EC-B). Paths normalized via\n * `realpath` to dedup symlink chains pointing to the same physical file\n * (EC-F). Git worktrees work transparently because `.git` exists as a\n * file in that case (EC-N).\n *\n * @internal\n */\n\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { glob } from \"node:fs/promises\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\n\n/** Single filename (\"AGENTS.md\") or relative glob (\".cursor/rules/*.mdc\"). */\nexport type DiscoveryScope = \"cwd-only\" | \"git-root-walk\" | \"globbed\";\n\n/** Parser to apply once file is read. */\nexport type DiscoveryParser = \"plain-markdown\" | \"mdc\" | \"frontmatter-zod\" | \"rules-frontmatter\";\n\n/**\n * One kind of context file the runner knows how to find and read. The shipped registry is\n * `DEFAULT_DISCOVERY_SPECS`; a caller supplies its own array to change the set.\n *\n * `scope` decides how `pattern` is used and how many files a single spec can yield:\n * `cwd-only` looks for one path and stops, `git-root-walk` collects a match in every directory\n * from `cwd` up to the git root (nearest first), and `globbed` expands `pattern` as a glob\n * relative to `cwd`. So `pattern` is a filename for the first two and a glob for the third —\n * putting a glob on a walk scope silently finds nothing.\n *\n * `priority` orders the merged prompt, ascending, and is a plain number rather than an index, so\n * a new spec can be slotted between two existing ones. Lower means earlier and therefore more\n * general; later content wins on conflict.\n *\n * `parser` must match the file format — `plain-markdown` reads the whole file, `mdc` and\n * `rules-frontmatter` parse frontmatter and can DECLINE the file when its activation conditions\n * do not hold, and `frontmatter-zod` is the legacy path the runner currently skips entirely.\n *\n * `followImports` is honored only by `plain-markdown`, and turns `@path` directives in the body\n * into inlined content bounded by the import root. Setting it on a frontmatter parser does\n * nothing.\n *\n * `id` names the source in `<source name=\"\">` and in telemetry. When one spec matches files in\n * several directories, the runner suffixes it with the path relative to the git root to keep them\n * apart.\n *\n * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.\n */\nexport interface DiscoverySpec {\n  /** Stable identifier — used as `<source name=\"\">` and telemetry key. */\n  readonly id: string;\n  /** Priority for merge (lower = earlier in prompt). */\n  readonly priority: number;\n  /** Filename (cwd-only/git-root-walk) or glob (globbed). */\n  readonly pattern: string;\n  readonly scope: DiscoveryScope;\n  readonly parser: DiscoveryParser;\n  /** Whether to follow `@path` import directives (CLAUDE.md / GEMINI.md). */\n  readonly followImports: boolean;\n  /**\n   * The `CompatSource` kind whose grant gates this file — the name a consumer writes in\n   * `local.compatSources` to receive it.\n   *\n   * Absent means UNGATED, and that covers two different situations which the field deliberately does\n   * not distinguish, because the gate treats them identically:\n   *\n   * 1. **Native.** theokit's own roots. Declaring theokit is what running theokit means, so there is\n   *    no separate grant to ask for.\n   * 2. **A repo-root instruction file.** `AGENTS.md`, `GEMINI.md`, `CLAUDE.md` and\n   *    `.cursor/rules/*.mdc` are every bit as foreign as `.claude/` is, and every one of them puts\n   *    a cloned repository's prose into the system prompt. They are ungated anyway, for a reason\n   *    that is a limit rather than a judgement: `adaptersFor` registers ONE foreign adapter,\n   *    `claude-code`, so `compatSources` has no spelling that admits `agents`, `gemini` or\n   *    `cursor`. Labelling them would gate them on a grant nobody can write, making three formats\n   *    permanently unreachable — a silent loss of capability with no way to restore it, which is a\n   *    worse defect than the one being fixed and the exact shape this codebase already paid for in\n   *    usetheokit/theokit-sdk#524.\n   *\n   *    `CLAUDE.md` is ungated for the adjacent reason, and this one IS a judgement: the grant gates\n   *    the foreign ROOT — the `.claude/` directory whose hooks, skills, subagents and plugins\n   *    already require it — and `CLAUDE.md` does not live there. It sits at the repository root\n   *    beside the other three, is widely used as a generic agent-instructions file by projects that\n   *    have no `.claude/` at all, and gating it would take it from them.\n   *\n   *    So this field closes the door the grant vocabulary already has a key for, and leaves three\n   *    named. Whether a repo-root instruction file should require an opt-in at all is a product\n   *    decision affecting every consumer, not a bug fix, and it is tracked separately — writing it\n   *    down is the point, because an undocumented gap reads as an oversight.\n   *\n   * Optional because this interface is `@public` and under semver: a caller passing its own array\n   * keeps working, and its specs read as ungated — the behaviour they had before this field existed.\n   *\n   * On the SPEC rather than as a condition at the call site, because the table MIXES dialects.\n   * Adding one is adding a row, not editing a branch somebody else has to find.\n   */\n  readonly dialect?: string;\n}\n\n/**\n * The specs a consumer's declared compat sources admit.\n *\n * The half that turns {@link DiscoverySpec.dialect} from a label into a gate. A field nobody consults\n * is a control that is declared, exported, documented and wired to nothing — which is the failure\n * this whole change exists to close, and it would be a poor joke to reproduce it here.\n *\n * Three rules, and each is a decision rather than a convenience:\n *\n * - **A spec with no `dialect` is always admitted.** Absent means native, and a caller's own array\n *   predates this field: filtering it by a question it never answered would remove content nobody\n *   asked to remove.\n * - **`undefined` sources admit everything.** That is every consumer before this field existed. This\n *   is the back-compatibility floor and the reason the change is a minor rather than a breaking one.\n * - **A declared list admits only the dialects it names.** This is the fix: a consumer who grants\n *   `theokit` for its own roots and never declares `claude-code` stops receiving that repository's\n *   `.claude/rules/*.md` in its prompt.\n *\n * `@internal`, deliberately. The docblock claimed `@public — re-exported from\n * '@theokit/sdk/context'` and the barrel exported no such name: a reach asserted and not given,\n * which is the defect this whole change is about, committed in the fix for it. A consumer building\n * its own `specs` array does not need this function — it passes `declaredCompatKinds` to\n * `runDiscovery` and gets the same filtering, through a public option on a public interface. So the\n * honest correction is to narrow the claim rather than widen the surface.\n *\n * @internal — exported from the module so the gate is testable at its boundary rather than only\n * through a whole agent, and not re-exported from any public entry point.\n */\nexport function admittedSpecs(\n  specs: ReadonlyArray<DiscoverySpec>,\n  declaredKinds: ReadonlyArray<string> | undefined,\n): ReadonlyArray<DiscoverySpec> {\n  if (declaredKinds === undefined) return specs;\n  const granted = new Set(declaredKinds);\n  return specs.filter((spec) => spec.dialect === undefined || granted.has(spec.dialect));\n}\n\n/**\n * A spec a declaration did not admit, with the grant that would.\n *\n * A NAMED type rather than the inline shape it replaced, and that is not style. The DTS rollup only\n * pulls a symbol into a chunk when a public type references it — with an anonymous return type\n * nothing referenced `withheldSpecs`, the re-export dangled, and the build failed with TS2305 in\n * whichever file carried it. Naming the return value is what makes the function reachable, and it\n * also gives a consumer something to write in their own signature.\n *\n * @public\n */\nexport interface WithheldSpec {\n  /** The spec's stable id, as it appears in telemetry. */\n  readonly id: string;\n  /** The filename or glob that was not loaded. */\n  readonly pattern: string;\n  /** The `compatSources` grant that would admit it. */\n  readonly grant: string;\n}\n\n/**\n * The mirror of {@link admittedSpecs}: the specs a declaration did NOT admit.\n *\n * It exists because `runDiscovery`'s own docblock admits the gap it closes — *\"a shorter result\n * than expected means 'nothing qualified', and this function will not tell you which of those it\n * was\"*. After B-081 gates the four repo-root instruction files, a consumer who declares nothing\n * goes from receiving four files to receiving none, and that has to be legible.\n *\n * Returned as a VALUE rather than only logged, because a log line cannot be asserted by a\n * consumer's test, and this repository does not ship controls that cannot be observed. The loud\n * half is the `warnOnce` the caller emits from this list.\n *\n * Each entry carries the grant that WOULD admit it — being told you lost something, without being\n * told what would bring it back, is a diagnosis with no remedy.\n *\n * `undefined` declaredKinds means \"no gate configured\", which admits everything and therefore\n * withholds nothing. That is NOT the same as `[]`, which is a real declaration of no foreign\n * dialect and withholds every gated spec — the distinction `declaredCompatKinds` already carries,\n * preserved here rather than re-decided.\n *\n * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.\n */\nexport function withheldSpecs(\n  specs: ReadonlyArray<DiscoverySpec>,\n  declaredKinds: ReadonlyArray<string> | undefined,\n): ReadonlyArray<WithheldSpec> {\n  if (declaredKinds === undefined) return [];\n  const granted = new Set(declaredKinds);\n  return specs\n    .filter((spec) => spec.dialect !== undefined && !granted.has(spec.dialect))\n    .map((spec) => ({ id: spec.id, pattern: spec.pattern, grant: String(spec.dialect) }));\n}\n\n/**\n * The context files theokit looks for out of the box, in the order they are concatenated.\n *\n * Two things follow from the ordering. `AGENTS.md` comes first at priority 10 and `THEO.md` last,\n * so theokit-specific instruction wins over the vendor-neutral file on conflict. And the array is\n * consumed in the order written — the runner does not re-sort it — so a caller passing its own\n * array is responsible for keeping `priority` and array position consistent.\n *\n * `CLAUDE.md` and `GEMINI.md` are the only two entries with `followImports: true`, which means\n * they are the only files whose `@path` directives pull other files into the prompt. Those\n * imports cannot escape the import root.\n *\n * Frozen only by type: `ReadonlyArray` is a compile-time constraint, and the array and its\n * elements are not deep-frozen at runtime. Build a new array rather than mutating this one.\n *\n * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.\n */\nexport const DEFAULT_DISCOVERY_SPECS: ReadonlyArray<DiscoverySpec> = [\n  {\n    id: \"AGENTS.md\",\n    dialect: \"agents\",\n    pattern: \"AGENTS.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: false,\n    priority: 10,\n  },\n  {\n    id: \"GEMINI.md\",\n    dialect: \"gemini\",\n    pattern: \"GEMINI.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: true,\n    priority: 20,\n  },\n  {\n    id: \"CLAUDE.md\",\n    dialect: \"claude-code\",\n    pattern: \"CLAUDE.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: true,\n    priority: 30,\n  },\n  {\n    id: \"cursor-rules\",\n    dialect: \"cursor\",\n    pattern: \".cursor/rules/*.mdc\",\n    scope: \"globbed\",\n    parser: \"mdc\",\n    followImports: false,\n    priority: 40,\n  },\n  {\n    id: \"theokit-rules\",\n    pattern: \".theokit/rules/*.md\",\n    scope: \"globbed\",\n    parser: \"rules-frontmatter\",\n    followImports: false,\n    priority: 45,\n  },\n  {\n    // Rules written for the Claude Code CLI. Measured 2026-08-26 over this repository's 32 rule\n    // files: none carries frontmatter, and `rules-frontmatter` already reads a file without it as\n    // `alwaysApply: true` — the format needed nothing, only a spec pointing at the directory.\n    //\n    // 47, not 46. Specs sort ascending and a context budget drops the tail first, so it must land\n    // AFTER `.theokit/rules` (45) — the explicit namespace should survive a squeeze the borrowed one\n    // does not. It must also leave a slot on BOTH sides: B-127 makes these numbers a public contract\n    // precisely so a consumer can place its own source between two defaults, and 46 would have left\n    // no room between 45 and itself. 47 keeps 46 free below and 48–49 free above.\n    //\n    // The reckoning B-127's docblock asks for: no published priority MOVES, so a consumer that chose\n    // 46, 48 or 49 is unaffected. A consumer that had chosen 47 now collides — that is the cost of\n    // an eighth default, paid once and recorded here rather than discovered later.\n    id: \"claude-rules\",\n    dialect: \"claude-code\",\n    pattern: \".claude/rules/*.md\",\n    scope: \"globbed\",\n    parser: \"rules-frontmatter\",\n    followImports: false,\n    priority: 47,\n  },\n  {\n    id: \"theokit-context\",\n    pattern: \".theokit/context/*.md\",\n    scope: \"globbed\",\n    parser: \"frontmatter-zod\",\n    followImports: false,\n    priority: 50,\n  },\n  {\n    // usetheokit/theokit-sdk#531 — THEO.md was the only context file that could not live at the\n    // project root: every sibling here is `git-root-walk`, and this one was `cwd-only` pointed\n    // at `.theokit/THEO.md` specifically, with no warning that a root THEO.md was inert.\n    //\n    // ADDED rather than moving the existing entry below: a project already using\n    // `.theokit/THEO.md` keeps working unchanged. 55 sits between `theokit-context` (50) and the\n    // existing `THEO.md` (60), leaving room on both sides — the numbering discipline\n    // `claude-rules` (47) already established for this array.\n    //\n    // `followImports: true`, unlike the existing entry (`false`) and unlike `AGENTS.md`. This is\n    // a DELIBERATE divergence between the two THEO.md specs, not an inconsistency: a root-level\n    // file is edited by the same people, in the same place, as CLAUDE.md/GEMINI.md — the two\n    // other root-level, human-facing files that both carry `followImports: true` — so it belongs\n    // in their category rather than AGENTS.md's vendor-neutral, import-free one. Because this is a\n    // NEW spec, choosing `true` here changes nothing for `.theokit/THEO.md`, which keeps `false`.\n    id: \"THEO.md.root\",\n    pattern: \"THEO.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: true,\n    priority: 55,\n  },\n  {\n    id: \"THEO.md\",\n    pattern: \".theokit/THEO.md\",\n    scope: \"cwd-only\",\n    parser: \"plain-markdown\",\n    followImports: false,\n    priority: 60,\n  },\n\n  // ── The private chain (B-023) ───────────────────────────────────────────────────────────────\n  //\n  // `*.local.md` is the gitignored companion where an operator keeps the standing corrections too\n  // personal or too situational to commit. Nothing read it: measured 2026-09-12, a grep for the four\n  // `.local` spellings returned 0 files across this package's source, against a control of 23 for\n  // `CLAUDE.md`. The file exists, it is named the documented way, and the agent behaves exactly as\n  // it would if the operator had written nothing.\n  //\n  // ORDER. They sit ABOVE every public spec because a correction has to be composed after the rule\n  // it corrects, and they keep the public chain's relative order among themselves (AGENTS, CLAUDE,\n  // THEO) so the two halves read the same way.\n  //\n  // THE COST OF THAT, stated rather than discovered later: `applyAggregateCap` fills the budget in\n  // ascending priority, so the HIGHEST numbers are the first dropped when the total cap is reached.\n  // Placing the private chain last therefore makes it the first to go under pressure. The\n  // alternative — a low number, to protect it — would compose the operator's refinement BEFORE the\n  // general rule, which inverts its meaning and is the defect this item is about. The existing table\n  // already accepts that trade: `.theokit/THEO.md`, the project's most specific instructions, is at\n  // 60 and is equally droppable. This follows the convention rather than inventing an exception.\n  //\n  // WHY THESE THREE AND NOT SIX. A private companion pairs with a public file THIS seam reads, and\n  // the documented convention is THEO / AGENTS / CLAUDE. `GEMINI.local.md` and a private\n  // `.cursor/rules` are not part of it, and inventing them would publish a convention nobody writes.\n  // Note the rule lands differently in `@theokit/agents`' `DEFAULT_FILE_NAMES`, which has no\n  // `CLAUDE.md` and therefore gets no `CLAUDE.local.md` — same rule, two seams, stated at both ends.\n  //\n  // UNGATED, like the public repo-root files beside them. `CLAUDE.local.md` is a repo-root file, not\n  // a `.claude/` one, so it follows `CLAUDE.md` rather than `claude-rules` — see `dialect`'s\n  // docblock for why the grant gates the foreign ROOT and not the files beside it.\n  {\n    id: \"AGENTS.local.md\",\n    pattern: \"AGENTS.local.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: false,\n    priority: 70,\n  },\n  {\n    id: \"CLAUDE.local.md\",\n    pattern: \"CLAUDE.local.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    // Mirrors `CLAUDE.md`, which follows imports. A private file that could not `@import` while its\n    // public sibling can would be a difference nobody declared.\n    followImports: true,\n    priority: 75,\n  },\n  {\n    id: \"THEO.local.md\",\n    pattern: \"THEO.local.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    // Mirrors `THEO.md.root`, which follows imports.\n    followImports: true,\n    priority: 80,\n  },\n];\n\nconst SAFE_FILENAME = /^[a-zA-Z0-9_.\\-/*]+$/;\nconst TRAVERSAL_RE = /(^|\\/)\\.\\.(\\/|$)/;\n\n/**\n * Reject patterns that contain path traversal (`..`) or non-allowed\n * characters (D81 parity, EC-4).\n *\n * @internal\n */\nexport function isSafePattern(pattern: string): boolean {\n  if (typeof pattern !== \"string\" || pattern.length === 0) return false;\n  if (TRAVERSAL_RE.test(pattern)) return false;\n  if (isAbsolute(pattern)) return false;\n  return SAFE_FILENAME.test(pattern);\n}\n\n/**\n * Walk upward from `cwd` looking for the closest directory containing\n * a `.git` entry (file OR directory — worktrees use a `.git` FILE,\n * EC-N). Returns the absolute path of that directory, or `undefined`\n * when no git root exists at or above `cwd`.\n *\n * @internal\n */\nexport function findGitRoot(cwd: string): string | undefined {\n  if (typeof cwd !== \"string\" || cwd.length === 0) return undefined;\n  let current = resolve(cwd);\n  // Guard against infinite loops on weird filesystems.\n  for (let i = 0; i < 64; i += 1) {\n    if (existsSync(join(current, \".git\"))) return current;\n    const parent = dirname(current);\n    if (parent === current) return undefined;\n    current = parent;\n  }\n  return undefined;\n}\n\n/**\n * Walk `cwd` upward to `stopDir` (inclusive) collecting every existing\n * occurrence of `filename`. Returns absolute, realpath-deduped paths in\n * nearest-first order (innermost dir first).\n *\n * No `.gitignore` parsing (EC-A). Realpath collapses symlink chains\n * pointing to the same physical file (EC-F). Filesystem races (file\n * deleted mid-walk) are skipped silently (EC-5).\n *\n * @internal\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: walk-up loop combines validation + realpath dedup + FS-race handling + stopDir guard in a single bounded loop; splitting fragments the dedup invariant.\nexport function walkUpForFile(\n  cwd: string,\n  filename: string,\n  stopDir: string | undefined,\n): string[] {\n  if (!isSafePattern(filename)) {\n    return [];\n  }\n  const start = resolve(cwd);\n  const stop = stopDir !== undefined ? resolve(stopDir) : undefined;\n  const found: string[] = [];\n  const seenReal = new Set<string>();\n  let current = start;\n  // 64-level depth cap.\n  for (let i = 0; i < 64; i += 1) {\n    const candidate = join(current, filename);\n    if (existsSync(candidate)) {\n      let real: string;\n      try {\n        real = realpathSync(candidate);\n      } catch {\n        // FS race (deleted mid-walk) — skip.\n        real = candidate;\n      }\n      if (!seenReal.has(real)) {\n        seenReal.add(real);\n        found.push(real);\n      }\n    }\n    if (stop !== undefined && current === stop) break;\n    const parent = dirname(current);\n    if (parent === current) break;\n    current = parent;\n  }\n  return found;\n}\n\n/**\n * Glob-style discovery under `cwd` (e.g. `.cursor/rules/*.mdc`, `.theokit/rules/**\\/*.md`).\n * Returns absolute, lex-sorted paths.\n *\n * `*` matches within one path segment and `**` spans any depth, including zero — so\n * `.theokit/rules/**\\/*.md` finds `rules/top.md` as well as `rules/deep/nested/inner.md`, while\n * `.theokit/rules/*.md` keeps its flat meaning and finds only the first. That distinction is the\n * compatibility contract: every existing spec uses a single `*`, and widening it would silently\n * start absorbing nested files nobody chose to expose.\n *\n * ## Why this used to be flat, and what changed (B-119)\n *\n * The previous implementation split the pattern at its LAST `/`, treated the prefix as a literal\n * directory and did one `readdir` — documented as \"nested directories deferred to v2\" (EC-R). The\n * deferral was deliberate; what made it a defect was measured from a consumer. TheoCode's own rule\n * loader descends recursively, so migrating it onto the `theokit-rules` spec would have silently\n * dropped every nested rule — on the path that decides whether a repository's hooks execute. And a\n * pattern written to say so, `.theokit/rules/**\\/*.md`, resolved its directory part to a literal\n * `**` and matched NOTHING, not even the top-level file it matched before the globstar was added.\n *\n * ## Why the stdlib rather than a walker\n *\n * `fs.promises.glob` (Node ≥ 22, and this package requires ≥ 22.12) implements exactly these\n * semantics, verified against a fixture before adoption: `**\\/*.md` returns all three depths,\n * `*.md` returns one, and it emits no experimental warning. Writing a recursive walker here would\n * have been a third implementation of matching inside one package — the same duplication that let\n * the enumerator and the compiler in `context-glob.ts` disagree in the first place. `globToRegex`\n * stays where it belongs: deciding whether a rule APPLIES to a set of paths, which is a different\n * question from which files exist.\n *\n * `isSafePattern` still runs first and is unchanged, so `..` is refused before any I/O.\n *\n * @internal\n */\nexport async function walkUpForGlob(cwd: string, pattern: string): Promise<string[]> {\n  if (!isSafePattern(pattern)) return [];\n  const found: string[] = [];\n  try {\n    for await (const entry of glob(pattern, { cwd })) {\n      found.push(resolve(cwd, entry));\n    }\n  } catch {\n    // A pattern whose directory does not exist is the ordinary case — most projects have no\n    // `.cursor/rules/`. Same outcome as matching nothing.\n    return [];\n  }\n  // Sorted, because discovery order becomes prompt order and must not vary with the filesystem.\n  //\n  // The comparator is explicit and deliberately NOT `localeCompare`, which is the usual suggestion\n  // for a bare `.sort()`. `localeCompare` orders by the machine's locale, so the same tree would\n  // assemble a different prompt on a differently-configured machine — trading one source of\n  // non-determinism for a subtler one. Code-unit ordering is what a bare `.sort()` already does for\n  // strings; writing it out states the intent and keeps the result machine-independent.\n  return found.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));\n}\n"]}

package/dist/{chunk-SAGRF4IB.js → chunk-S2CMEJ5F.js}

@@ -1,4 +1,4 @@
-import { AsyncLocalStorage } from 'async_hooks';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 // src/internal/concurrency/async-local-storage.ts
 var toolWhitelistStore = new AsyncLocalStorage();
@@ -21,5 +21,5 @@ function checkToolWhitelist(toolName) {
 }
 
 export { checkToolWhitelist, withToolWhitelist };
-//# sourceMappingURL=chunk-SAGRF4IB.js.map
-//# sourceMappingURL=chunk-SAGRF4IB.js.map
+//# sourceMappingURL=chunk-S2CMEJ5F.js.map
+//# sourceMappingURL=chunk-S2CMEJ5F.js.map

package/dist/{chunk-SAGRF4IB.js.map → chunk-S2CMEJ5F.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/concurrency/async-local-storage.ts"],"names":[],"mappings":";;;AAsBA,IAAM,kBAAA,GAAqB,IAAI,iBAAA,EAA+B;AAQ9D,eAAsB,iBAAA,CACpB,WACA,EAAA,EACY;AACZ,EAAA,OAAO,kBAAA,CAAmB,GAAA,CAAI,SAAA,EAAW,EAAE,CAAA;AAC7C;AAQO,SAAS,oBAAA,GAAgD;AAC9D,EAAA,OAAO,mBAAmB,QAAA,EAAS;AACrC;AAoBO,SAAS,mBAAmB,QAAA,EAAyC;AAC1E,EAAA,MAAM,YAAY,oBAAA,EAAqB;AACvC,EAAA,IAAI,SAAA,KAAc,MAAA,EAAW,OAAO,EAAE,SAAS,IAAA,EAAK;AACpD,EAAA,IAAI,CAAC,SAAA,CAAU,GAAA,CAAI,QAAQ,CAAA,EAAG;AAC5B,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,KAAA;AAAA,MACT,MAAA,EAAQ,SAAS,QAAQ,CAAA,oCAAA;AAAA,KAC3B;AAAA,EACF;AACA,EAAA,OAAO,EAAE,SAAS,IAAA,EAAK;AACzB","file":"chunk-SAGRF4IB.js","sourcesContent":["/**\n * Per-fork tool whitelist via `AsyncLocalStorage` (ADR D111).\n *\n * Forked agents (background review, curator, judge) need a tool subset\n * distinct from the parent's. A global mutable `let _whitelist` would\n * corrupt state when two forks run in parallel. `AsyncLocalStorage`\n * propagates the whitelist through the async chain so each fork sees its\n * own — no cross-fork bleed.\n *\n * Outside a `withToolWhitelist(...)` scope, `currentToolWhitelist()`\n * returns `undefined` and `checkToolWhitelist` allows every tool — the\n * parent agent is unaffected.\n *\n * Wire site: `internal/agent-loop/tool-dispatch.ts:dispatchSingleCall`\n * calls `checkToolWhitelist` after the repair middleware and before\n * `tools.find`.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nconst toolWhitelistStore = new AsyncLocalStorage<Set<string>>();\n\n/**\n * Run `fn` with `whitelist` as the active tool filter. Nested calls\n * shadow the outer set; the outer is restored on return (EC-F).\n *\n * @internal\n */\nexport async function withToolWhitelist<T>(\n  whitelist: Set<string>,\n  fn: () => Promise<T>,\n): Promise<T> {\n  return toolWhitelistStore.run(whitelist, fn);\n}\n\n/**\n * Active tool whitelist for the current async context, or `undefined`\n * when not inside a `withToolWhitelist(...)` scope.\n *\n * @internal\n */\nexport function currentToolWhitelist(): Set<string> | undefined {\n  return toolWhitelistStore.getStore();\n}\n\n/**\n * Decision returned by {@link checkToolWhitelist}.\n *\n * @internal\n */\nexport interface ToolWhitelistDecision {\n  allowed: boolean;\n  /** Populated only when `allowed === false`. */\n  reason?: string;\n}\n\n/**\n * Check whether `toolName` is allowed in the current fork context.\n * Returns `{ allowed: true }` when no fork is active — preserves the\n * parent agent's full tool surface.\n *\n * @internal\n */\nexport function checkToolWhitelist(toolName: string): ToolWhitelistDecision {\n  const whitelist = currentToolWhitelist();\n  if (whitelist === undefined) return { allowed: true };\n  if (!whitelist.has(toolName)) {\n    return {\n      allowed: false,\n      reason: `Tool \"${toolName}\" not available in this fork context`,\n    };\n  }\n  return { allowed: true };\n}\n"]}
+{"version":3,"sources":["../src/internal/concurrency/async-local-storage.ts"],"names":[],"mappings":";;;AAsBA,IAAM,kBAAA,GAAqB,IAAI,iBAAA,EAA+B;AAQ9D,eAAsB,iBAAA,CACpB,WACA,EAAA,EACY;AACZ,EAAA,OAAO,kBAAA,CAAmB,GAAA,CAAI,SAAA,EAAW,EAAE,CAAA;AAC7C;AAQO,SAAS,oBAAA,GAAgD;AAC9D,EAAA,OAAO,mBAAmB,QAAA,EAAS;AACrC;AAoBO,SAAS,mBAAmB,QAAA,EAAyC;AAC1E,EAAA,MAAM,YAAY,oBAAA,EAAqB;AACvC,EAAA,IAAI,SAAA,KAAc,MAAA,EAAW,OAAO,EAAE,SAAS,IAAA,EAAK;AACpD,EAAA,IAAI,CAAC,SAAA,CAAU,GAAA,CAAI,QAAQ,CAAA,EAAG;AAC5B,IAAA,OAAO;AAAA,MACL,OAAA,EAAS,KAAA;AAAA,MACT,MAAA,EAAQ,SAAS,QAAQ,CAAA,oCAAA;AAAA,KAC3B;AAAA,EACF;AACA,EAAA,OAAO,EAAE,SAAS,IAAA,EAAK;AACzB","file":"chunk-S2CMEJ5F.js","sourcesContent":["/**\n * Per-fork tool whitelist via `AsyncLocalStorage` (ADR D111).\n *\n * Forked agents (background review, curator, judge) need a tool subset\n * distinct from the parent's. A global mutable `let _whitelist` would\n * corrupt state when two forks run in parallel. `AsyncLocalStorage`\n * propagates the whitelist through the async chain so each fork sees its\n * own — no cross-fork bleed.\n *\n * Outside a `withToolWhitelist(...)` scope, `currentToolWhitelist()`\n * returns `undefined` and `checkToolWhitelist` allows every tool — the\n * parent agent is unaffected.\n *\n * Wire site: `internal/agent-loop/tool-dispatch.ts:dispatchSingleCall`\n * calls `checkToolWhitelist` after the repair middleware and before\n * `tools.find`.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nconst toolWhitelistStore = new AsyncLocalStorage<Set<string>>();\n\n/**\n * Run `fn` with `whitelist` as the active tool filter. Nested calls\n * shadow the outer set; the outer is restored on return (EC-F).\n *\n * @internal\n */\nexport async function withToolWhitelist<T>(\n  whitelist: Set<string>,\n  fn: () => Promise<T>,\n): Promise<T> {\n  return toolWhitelistStore.run(whitelist, fn);\n}\n\n/**\n * Active tool whitelist for the current async context, or `undefined`\n * when not inside a `withToolWhitelist(...)` scope.\n *\n * @internal\n */\nexport function currentToolWhitelist(): Set<string> | undefined {\n  return toolWhitelistStore.getStore();\n}\n\n/**\n * Decision returned by {@link checkToolWhitelist}.\n *\n * @internal\n */\nexport interface ToolWhitelistDecision {\n  allowed: boolean;\n  /** Populated only when `allowed === false`. */\n  reason?: string;\n}\n\n/**\n * Check whether `toolName` is allowed in the current fork context.\n * Returns `{ allowed: true }` when no fork is active — preserves the\n * parent agent's full tool surface.\n *\n * @internal\n */\nexport function checkToolWhitelist(toolName: string): ToolWhitelistDecision {\n  const whitelist = currentToolWhitelist();\n  if (whitelist === undefined) return { allowed: true };\n  if (!whitelist.has(toolName)) {\n    return {\n      allowed: false,\n      reason: `Tool \"${toolName}\" not available in this fork context`,\n    };\n  }\n  return { allowed: true };\n}\n"]}

package/dist/{chunk-VZGE7NAI.js → chunk-S5ERB3CH.js}

@@ -1,7 +1,7 @@
 import { getAgentFacade } from './chunk-6X6ID4MO.js';
 import { TheokitAgentError } from './chunk-TNFOU6SB.js';
 import { z } from 'zod';
-import { AsyncLocalStorage } from 'async_hooks';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 var depthStore = new AsyncLocalStorage();
 async function withDelegationDepth(depth, fn) {
@@ -217,5 +217,5 @@ function subAgentToolsFromDefinitions(agents, parentTools) {
 }
 
 export { MaxDelegationDepthError, SubAgent, subAgentToolsFromDefinitions, withInheritedSubAgentCredentials };
-//# sourceMappingURL=chunk-VZGE7NAI.js.map
-//# sourceMappingURL=chunk-VZGE7NAI.js.map
+//# sourceMappingURL=chunk-S5ERB3CH.js.map
+//# sourceMappingURL=chunk-S5ERB3CH.js.map