@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/dist/esm/durability.js

@@ -0,0 +1,230 @@
+import "./journal.js";
+import { alignToStoredLog, isBridgeCustomChunk } from "./align.js";
+import { createCapability } from "@tanstack/ai";
+//#region src/durability.ts
+/**
+* The durability seam for a sandboxed run: the option shape `withSandbox` takes,
+* the capability harness adapters read, and the two guards that keep a
+* "durable" run actually recoverable.
+*
+* A run is durable only when BOTH a `RunStore` and a `StreamDurability` are
+* wired, because either alone is useless: a record with no event log cannot be
+* replayed, and a log with no record cannot be found, claimed, or reaped. So the
+* capability exists or it does not — there is no half-configured state, and
+* every existing app (which wires neither) keeps today's behavior untouched.
+*/
+/**
+* Provided by `withSandbox` only when a run is genuinely durable (both stores
+* wired). Harness adapters read it with `getOptional` and treat its absence as
+* "no journaling contract to honour", which is exactly today's behavior.
+*/
+var SandboxDurabilityCapability = createCapability()("sandbox-durability");
+/** Destructured accessors, matching `./capabilities`. */
+var [getSandboxDurability, provideSandboxDurability] = SandboxDurabilityCapability;
+/**
+* A durable run was started without a caller-supplied `runId`.
+*
+* Thrown rather than defaulted because the failure is otherwise INVISIBLE: an
+* adapter-generated id (`${name}-${Date.now()}-${Math.random()...}`) produces a
+* journal path at `/tmp/tanstack-runs/<id>.ndjson` that no successor host can
+* recompute, so the run streams normally, records normally, and is silently
+* unrecoverable. A loud failure at the start of `chatStream` is strictly better
+* than a run that only reveals itself as non-durable during an incident.
+*/
+var DurableRunIdRequiredError = class extends Error {
+	adapter;
+	constructor(adapter) {
+		super(`${adapter}: a durable sandboxed run requires a caller-supplied \`runId\`. The journal path and the deterministic message-id generator are both derived from it, so a successor host can only resume a run whose \`runId\` it can recompute. Pass \`runId\` to chat({ ... }), or drop \`runs\`/\`durability\` from withSandbox(...) to run non-durably.`);
+		this.adapter = adapter;
+		this.name = "DurableRunIdRequiredError";
+	}
+};
+/**
+* Resolve the `runId` a harness adapter will journal under.
+*
+* Replaces the bare `options.runId ?? this.generateId()` in every harness
+* adapter. The fallback is preserved for non-durable runs — several `chat()`
+* paths pass `runId` as a conditional spread, so `undefined` is reachable and
+* removing the fallback would break them for no benefit.
+*
+* The `durable` check runs BEFORE `fallback()`, and that ordering is load
+* bearing: a generated id must never be minted for a durable run, not even one
+* that is discarded, because the whole point is that no such id can exist.
+*/
+function resolveDurableRunId(runId, options) {
+	if (runId !== void 0 && runId.length > 0) return runId;
+	if (options.durable) throw new DurableRunIdRequiredError(options.adapter);
+	return options.fallback();
+}
+/**
+* An ATTACHING durable run was driven without the run record's `threadId`.
+*
+* The sibling of {@link DurableRunIdRequiredError}, for the other id an attach
+* cannot mint for itself. `threadId` lands in EVERY chunk a harness adapter
+* emits (see each package's `stream/translate.ts`), so a replay that generates a
+* fresh one produces a stream that differs from the stored log in its very first
+* chunk. `alignToStoredLog` then fails at index 0 with a
+* `JournalReplayThreadIdMismatchError` — mid-stream, after the takeover has
+* already claimed the run. Refusing up front is strictly better, and mirrors
+* what `resolveDurableRunId` does for an id whose absence is equally fatal.
+*
+* Core already does its part: `startRunDriver` reads the record and hands
+* `active.threadId` to `drive({ runId, threadId, signal })`. This error exists
+* for the one gap it cannot close — application `drive` code that forgets to
+* forward it into `chat()`.
+*/
+var DurableThreadIdRequiredError = class extends Error {
+	adapter;
+	constructor(adapter) {
+		super(`${adapter}: an ATTACHING durable sandboxed run requires the run record's \`threadId\`. Every emitted chunk carries \`threadId\`, so an attach that generates a fresh one replays a stream whose first chunk already differs from the stored log, and alignment fails at index 0 (\`JournalReplayThreadIdMismatchError\`) even though the agent behaved identically. Forward the run record's \`threadId\` — the one \`sandboxRunDriver\` passes to \`drive({ runId, threadId, signal })\` — into \`chat({ ... })\` on the attach route. A durable FRESH run needs none: that run is what establishes the \`threadId\`.`);
+		this.adapter = adapter;
+		this.name = "DurableThreadIdRequiredError";
+	}
+};
+/**
+* Resolve the `threadId` a harness adapter will stamp on every chunk.
+*
+* Replaces the bare `options.threadId ?? this.generateId()` in the journaling
+* harness adapters. Only the durable-AND-attaching quadrant throws; the other
+* three keep the generated fallback and are byte-identical to before:
+*
+* | durable | attaching | behavior                                            |
+* | ------- | --------- | --------------------------------------------------- |
+* | no      | no        | fallback — a plain non-durable run                  |
+* | no      | yes       | fallback — not reachable today, and harmless anyway |
+* | yes     | no        | fallback — the FRESH run that ESTABLISHES the id    |
+* | yes     | yes       | throw {@link DurableThreadIdRequiredError}          |
+*
+* The durable-fresh row is the load-bearing one. A fresh durable run legitimately
+* mints its `threadId` (there is no record to reuse one from), so throwing on
+* `durable` alone — the obvious over-simplification — would break every durable
+* run that has ever worked. Only re-entering an existing run has an id it MUST
+* reuse, which is exactly the condition `attach` already expresses.
+*
+* As in `resolveDurableRunId`, the guard runs BEFORE `fallback()`: a generated id
+* must never be minted on this path, not even one that is then discarded.
+*/
+function resolveDurableThreadId(threadId, options) {
+	if (threadId !== void 0 && threadId.length > 0) return threadId;
+	if (options.durable && options.attaching) throw new DurableThreadIdRequiredError(options.adapter);
+	return options.fallback();
+}
+/**
+* An ATTACH was driven into a code path that can never replay a run.
+*
+* The third sibling of {@link DurableRunIdRequiredError} and
+* {@link DurableThreadIdRequiredError}, and the one that is not about a missing
+* id: here every id is present and the path itself is the problem.
+*
+* `sandboxRunDriver`'s `drive()` re-invokes `chat()` with `attach: true`. On a
+* JOURNALING path that is genuinely a replay — `spawnNdjson` tails the journal
+* the previous host wrote, `awaitAttachableJournal` refuses a hopeless attach up
+* front, and `alignedIfAttaching` suppresses the prefix already delivered. A
+* protocol path with none of those three has no journal to tail and nothing to
+* align against, so `attach: true` does not resume anything: it starts the agent
+* over from scratch against the workspace the first attempt already mutated, and
+* appends its entire output to a log that still holds the first attempt's.
+*
+* Deliberately NOT a `JournalAttachUnavailableError`. That error means "a
+* journal that should exist has not appeared yet" — retryable, scoped to a wait
+* (`attachWaitMs`). This condition is categorically different: the path cannot
+* attach AT ALL, so telling a caller to wait would point it at something that is
+* never coming. A 5xx/501-shaped refusal, not a 504.
+*
+* `reason` names the missing capability in the adapter's own vocabulary (which
+* protocol, which spawn path), because the fix is always to change how the run
+* is spawned or routed, never to retry.
+*/
+var DurableAttachNotSupportedError = class extends Error {
+	adapter;
+	reason;
+	constructor(adapter, reason) {
+		super(`${adapter}: this code path cannot ATTACH to an existing durable run (${reason}). It does not journal, so there is no stored output to replay and no alignment to suppress what was already delivered. Proceeding would re-run the agent from scratch against the workspace the previous attempt already modified, and double-append its entire output to the run log. Route the attach through a journaling spawn path, or drop \`runs\`/\`durability\` from withSandbox(...) so the run is never resumed in the first place. This is not a transient condition — unlike \`JournalAttachUnavailableError\`, waiting and retrying can never make it succeed.`);
+		this.adapter = adapter;
+		this.reason = reason;
+		this.name = "DurableAttachNotSupportedError";
+	}
+};
+/**
+* Resolve `withSandbox`'s two durability options into the capability payload, or
+* `undefined` when the app has not opted in.
+*
+* BOTH `runs` and `durability` are required. A half-configured app gets
+* `undefined` **silently** rather than a warning: it has not asked for
+* durability, so there is nothing to warn about, and the resulting behavior
+* (destroy on disconnect, no journal) is exactly today's.
+*/
+function resolveSandboxDurability(options) {
+	const runs = options?.runs;
+	const durability = options?.durability;
+	if (runs === void 0 || durability === void 0) return void 0;
+	return {
+		runs,
+		adapter: durability.adapter,
+		journalDir: durability.journal ?? "/tmp/tanstack-runs",
+		attach: durability.attach === true,
+		detachOnDisconnect: durability.detachOnDisconnect !== false,
+		...durability.pollIntervalMs === void 0 ? {} : { pollIntervalMs: durability.pollIntervalMs },
+		...durability.attachWaitMs === void 0 ? {} : { attachWaitMs: durability.attachWaitMs }
+	};
+}
+/**
+* Build the `spawnNdjson` journal option for a run, or `undefined` when the run
+* is not durable — in which case `spawnNdjson` takes its original, unjournaled
+* path (`isJournaled` tests `options.journal !== undefined`, `runner.ts:70-72`)
+* and behavior is byte-identical to a pre-durability run.
+*
+* `JournalOptions.dir` is optional, but this always supplies it: the resolved
+* durability has already defaulted `journalDir`, and a successor host must
+* recompute the same path rather than re-derive the default independently.
+*
+* `runs` and `attachWaitMs` are carried ONLY when attaching, and that is not a
+* micro-optimization: they exist for `awaitAttachableJournal`, which the reader
+* runs on the attach path alone. A fresh run has no journal yet BY DESIGN (its own
+* `journaledCommand` spawn creates it moments later), so handing it a run store
+* would only invite a future change to gate a path where absence proves nothing.
+*/
+function journalOptionsFor(durability, runId) {
+	if (durability === void 0) return void 0;
+	return {
+		runId,
+		dir: durability.journalDir,
+		attach: durability.attach,
+		...durability.pollIntervalMs === void 0 ? {} : { pollIntervalMs: durability.pollIntervalMs },
+		...durability.attach ? {
+			runs: durability.runs,
+			...durability.attachWaitMs === void 0 ? {} : { attachWaitMs: durability.attachWaitMs }
+		} : {}
+	};
+}
+/**
+* Align a harness stream against the run's stored log — but ONLY on an attach.
+*
+* The `attach` guard is not an optimization, it is a CORRECTNESS requirement.
+* `alignToStoredLog` snapshots the log before the first chunk is pulled and
+* treats everything in that snapshot as "already delivered". On a FRESH run that
+* premise is false: if such a run were aligned against a log that already holds
+* entries — a `runId` collision, a retried request — its own chunks would be
+* matched against those entries and silently SUPPRESSED instead of delivered,
+* which is silent data loss rather than a slow path. Aligning only when
+* re-entering an existing run keeps the transform's premise ("this stream is a
+* replay of what is already stored") actually true.
+*
+* `isBridgeCustomChunk` is passed because the stored log holds the previous
+* host's MERGED output, including live bridged-tool CUSTOM events that a replay
+* cannot reproduce; without it a bridged-tool run could not be taken over at
+* all. Wrap the merge RESULT, never the pre-merge translator, or the comparison
+* is against a stream the log never contained.
+*/
+function alignedIfAttaching(chunks, durability, logger) {
+	if (durability === void 0 || !durability.attach) return chunks;
+	return alignToStoredLog(chunks, {
+		durability: durability.adapter,
+		isOutOfBand: isBridgeCustomChunk,
+		...logger === void 0 ? {} : { logger }
+	});
+}
+//#endregion
+export { DurableAttachNotSupportedError, DurableRunIdRequiredError, DurableThreadIdRequiredError, SandboxDurabilityCapability, alignedIfAttaching, getSandboxDurability, journalOptionsFor, provideSandboxDurability, resolveDurableRunId, resolveDurableThreadId, resolveSandboxDurability };
+
+//# sourceMappingURL=durability.js.map

package/dist/esm/durability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durability.js","names":[],"sources":["../../src/durability.ts"],"sourcesContent":["/**\n * The durability seam for a sandboxed run: the option shape `withSandbox` takes,\n * the capability harness adapters read, and the two guards that keep a\n * \"durable\" run actually recoverable.\n *\n * A run is durable only when BOTH a `RunStore` and a `StreamDurability` are\n * wired, because either alone is useless: a record with no event log cannot be\n * replayed, and a log with no record cannot be found, claimed, or reaped. So the\n * capability exists or it does not — there is no half-configured state, and\n * every existing app (which wires neither) keeps today's behavior untouched.\n */\nimport { createCapability } from '@tanstack/ai'\nimport { DEFAULT_JOURNAL_DIR } from './journal'\nimport { alignToStoredLog, isBridgeCustomChunk } from './align'\nimport type { JournalOptions } from './runner'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { RunStore, StreamChunk, StreamDurability } from '@tanstack/ai'\n\n/** `withSandbox(sandbox, { durability })`. */\nexport interface SandboxDurabilityOptions<TOffset extends string = string> {\n  /**\n   * Delivery-durable event log for the run. Same key and shape as the\n   * transport's `durability.adapter`, so one adapter instance can be handed to\n   * both `withSandbox` and `toServerSentEventsResponse`.\n   *\n   * Generic in the offset type, defaulted to `string`, for the same reason\n   * {@link SandboxRunDriverOptions} and {@link ReapOptions} are:\n   * `StreamDurability` is INVARIANT in `TOffset` (`read` takes an offset in),\n   * so a backend that brands its cursors — `@tanstack/ai-durable-stream`'s\n   * `durableStream`, the multi-host production backend the sandbox docs point\n   * at — is not assignable to `StreamDurability<string>`. Without the parameter\n   * the resume route could be wired with it and the route that STARTS the run\n   * could not.\n   */\n  adapter: StreamDurability<TOffset>\n  /** Journal directory inside the sandbox. Defaults to `/tmp/tanstack-runs`. */\n  journal?: string\n  /**\n   * Whether a client disconnect DETACHES (leave the agent running) instead of\n   * destroying the sandbox. Defaults to `true` whenever durability is wired,\n   * because that is the whole point of wiring it.\n   *\n   * Set `false` to keep today's destroy-on-disconnect cost profile while still\n   * getting resumable DELIVERY (a reload replays the log). An explicit cancel\n   * destroys either way.\n   */\n  detachOnDisconnect?: boolean\n  /**\n   * Read an EXISTING run's journal instead of starting a new agent. Set by the\n   * attach route's `drive()` callback, never by an application's POST handler.\n   *\n   * This is where `attach` lives, and deliberately NOT on `chat()`: `chat()` is\n   * core and must not gain sandbox vocabulary, and the provider options are\n   * per-model type state, not per-request lifecycle.\n   */\n  attach?: boolean\n  /** Journal poll interval for providers that cannot follow. */\n  pollIntervalMs?: number\n  /**\n   * How long an ATTACH waits for a live run's journal to appear before failing\n   * with a `JournalAttachUnavailableError`. Defaults to\n   * `DEFAULT_ATTACH_JOURNAL_WAIT_MS` (10s). Only the wait is configurable: an\n   * unknown or terminal runId fails immediately regardless, since no amount of\n   * waiting changes either verdict.\n   */\n  attachWaitMs?: number\n}\n\n/**\n * The view of a caller's event log that the capability bus carries.\n *\n * Deliberately NOT the whole `StreamDurability`. `read` is the only member that\n * takes an offset *in*, which is what makes `StreamDurability` invariant in\n * `TOffset` and a branded-cursor backend unassignable to\n * `StreamDurability<string>`. Every other member mentions the offset only in a\n * return position, so this type is a genuine SUPERTYPE of\n * `StreamDurability<TOffset>` for every `TOffset extends string` — which is the\n * one property that lets a single concrete capability instantiation accept a\n * branded backend. `createCapability<T>()` forces exactly one instantiation\n * (the value type is a plain type argument, and TypeScript has no higher-kinded\n * types), so the payload cannot be parameterized the way the *option* above is.\n *\n * Dropping `read` costs nothing, and that is a property of the seam rather than\n * luck: the bus is the JOURNAL/ALIGNMENT seam, and alignment reads the stored\n * prefix through `snapshot()` — never `read()`, which tails an open log forever\n * (see `alignToStoredLog`). Replay *by offset* belongs to the delivery seam,\n * and that seam (`toServerSentEventsResponse`, `sandboxRunDriver`) receives the\n * application's own adapter directly, with its brand intact.\n */\nexport type SandboxDurabilityLog = Omit<StreamDurability, 'read'>\n\n/**\n * Resolved durability, published on the capability bus by `withSandbox`.\n *\n * Deliberately carries NO detached-run TTL. The only actor that enforces one is\n * `reapDetachedRuns`, which runs from a cron with no chat in flight — so it has\n * no `CapabilityContext` and cannot read this bus at all. A TTL published here\n * could therefore only ever be read by nobody, while the sweep took its own\n * `ReapOptions.detachedRunTtlMs`; the two would silently disagree. The reaper's\n * required option is the single source of truth.\n */\nexport interface SandboxRunDurability {\n  runs: RunStore\n  adapter: SandboxDurabilityLog\n  journalDir: string\n  attach: boolean\n  detachOnDisconnect: boolean\n  pollIntervalMs?: number\n  attachWaitMs?: number\n}\n\n/**\n * Provided by `withSandbox` only when a run is genuinely durable (both stores\n * wired). Harness adapters read it with `getOptional` and treat its absence as\n * \"no journaling contract to honour\", which is exactly today's behavior.\n */\nexport const SandboxDurabilityCapability =\n  createCapability<SandboxRunDurability>()('sandbox-durability')\n\n/** Destructured accessors, matching `./capabilities`. */\nexport const [getSandboxDurability, provideSandboxDurability] =\n  SandboxDurabilityCapability\n\n/**\n * A durable run was started without a caller-supplied `runId`.\n *\n * Thrown rather than defaulted because the failure is otherwise INVISIBLE: an\n * adapter-generated id (`${name}-${Date.now()}-${Math.random()...}`) produces a\n * journal path at `/tmp/tanstack-runs/<id>.ndjson` that no successor host can\n * recompute, so the run streams normally, records normally, and is silently\n * unrecoverable. A loud failure at the start of `chatStream` is strictly better\n * than a run that only reveals itself as non-durable during an incident.\n */\nexport class DurableRunIdRequiredError extends Error {\n  constructor(readonly adapter: string) {\n    super(\n      `${adapter}: a durable sandboxed run requires a caller-supplied \\`runId\\`. ` +\n        `The journal path and the deterministic message-id generator are both derived from it, ` +\n        `so a successor host can only resume a run whose \\`runId\\` it can recompute. ` +\n        `Pass \\`runId\\` to chat({ ... }), or drop \\`runs\\`/\\`durability\\` from withSandbox(...) to run non-durably.`,\n    )\n    this.name = 'DurableRunIdRequiredError'\n  }\n}\n\n/**\n * Resolve the `runId` a harness adapter will journal under.\n *\n * Replaces the bare `options.runId ?? this.generateId()` in every harness\n * adapter. The fallback is preserved for non-durable runs — several `chat()`\n * paths pass `runId` as a conditional spread, so `undefined` is reachable and\n * removing the fallback would break them for no benefit.\n *\n * The `durable` check runs BEFORE `fallback()`, and that ordering is load\n * bearing: a generated id must never be minted for a durable run, not even one\n * that is discarded, because the whole point is that no such id can exist.\n */\nexport function resolveDurableRunId(\n  runId: string | undefined,\n  options: { durable: boolean; adapter: string; fallback: () => string },\n): string {\n  if (runId !== undefined && runId.length > 0) return runId\n  if (options.durable) throw new DurableRunIdRequiredError(options.adapter)\n  return options.fallback()\n}\n\n/**\n * An ATTACHING durable run was driven without the run record's `threadId`.\n *\n * The sibling of {@link DurableRunIdRequiredError}, for the other id an attach\n * cannot mint for itself. `threadId` lands in EVERY chunk a harness adapter\n * emits (see each package's `stream/translate.ts`), so a replay that generates a\n * fresh one produces a stream that differs from the stored log in its very first\n * chunk. `alignToStoredLog` then fails at index 0 with a\n * `JournalReplayThreadIdMismatchError` — mid-stream, after the takeover has\n * already claimed the run. Refusing up front is strictly better, and mirrors\n * what `resolveDurableRunId` does for an id whose absence is equally fatal.\n *\n * Core already does its part: `startRunDriver` reads the record and hands\n * `active.threadId` to `drive({ runId, threadId, signal })`. This error exists\n * for the one gap it cannot close — application `drive` code that forgets to\n * forward it into `chat()`.\n */\nexport class DurableThreadIdRequiredError extends Error {\n  constructor(readonly adapter: string) {\n    super(\n      `${adapter}: an ATTACHING durable sandboxed run requires the run record's \\`threadId\\`. ` +\n        `Every emitted chunk carries \\`threadId\\`, so an attach that generates a fresh one replays a stream whose first chunk ` +\n        `already differs from the stored log, and alignment fails at index 0 (\\`JournalReplayThreadIdMismatchError\\`) even though ` +\n        `the agent behaved identically. Forward the run record's \\`threadId\\` — the one \\`sandboxRunDriver\\` passes to ` +\n        `\\`drive({ runId, threadId, signal })\\` — into \\`chat({ ... })\\` on the attach route. ` +\n        `A durable FRESH run needs none: that run is what establishes the \\`threadId\\`.`,\n    )\n    this.name = 'DurableThreadIdRequiredError'\n  }\n}\n\n/**\n * Resolve the `threadId` a harness adapter will stamp on every chunk.\n *\n * Replaces the bare `options.threadId ?? this.generateId()` in the journaling\n * harness adapters. Only the durable-AND-attaching quadrant throws; the other\n * three keep the generated fallback and are byte-identical to before:\n *\n * | durable | attaching | behavior                                            |\n * | ------- | --------- | --------------------------------------------------- |\n * | no      | no        | fallback — a plain non-durable run                  |\n * | no      | yes       | fallback — not reachable today, and harmless anyway |\n * | yes     | no        | fallback — the FRESH run that ESTABLISHES the id    |\n * | yes     | yes       | throw {@link DurableThreadIdRequiredError}          |\n *\n * The durable-fresh row is the load-bearing one. A fresh durable run legitimately\n * mints its `threadId` (there is no record to reuse one from), so throwing on\n * `durable` alone — the obvious over-simplification — would break every durable\n * run that has ever worked. Only re-entering an existing run has an id it MUST\n * reuse, which is exactly the condition `attach` already expresses.\n *\n * As in `resolveDurableRunId`, the guard runs BEFORE `fallback()`: a generated id\n * must never be minted on this path, not even one that is then discarded.\n */\nexport function resolveDurableThreadId(\n  threadId: string | undefined,\n  options: {\n    durable: boolean\n    attaching: boolean\n    adapter: string\n    fallback: () => string\n  },\n): string {\n  if (threadId !== undefined && threadId.length > 0) return threadId\n  if (options.durable && options.attaching) {\n    throw new DurableThreadIdRequiredError(options.adapter)\n  }\n  return options.fallback()\n}\n\n/**\n * An ATTACH was driven into a code path that can never replay a run.\n *\n * The third sibling of {@link DurableRunIdRequiredError} and\n * {@link DurableThreadIdRequiredError}, and the one that is not about a missing\n * id: here every id is present and the path itself is the problem.\n *\n * `sandboxRunDriver`'s `drive()` re-invokes `chat()` with `attach: true`. On a\n * JOURNALING path that is genuinely a replay — `spawnNdjson` tails the journal\n * the previous host wrote, `awaitAttachableJournal` refuses a hopeless attach up\n * front, and `alignedIfAttaching` suppresses the prefix already delivered. A\n * protocol path with none of those three has no journal to tail and nothing to\n * align against, so `attach: true` does not resume anything: it starts the agent\n * over from scratch against the workspace the first attempt already mutated, and\n * appends its entire output to a log that still holds the first attempt's.\n *\n * Deliberately NOT a `JournalAttachUnavailableError`. That error means \"a\n * journal that should exist has not appeared yet\" — retryable, scoped to a wait\n * (`attachWaitMs`). This condition is categorically different: the path cannot\n * attach AT ALL, so telling a caller to wait would point it at something that is\n * never coming. A 5xx/501-shaped refusal, not a 504.\n *\n * `reason` names the missing capability in the adapter's own vocabulary (which\n * protocol, which spawn path), because the fix is always to change how the run\n * is spawned or routed, never to retry.\n */\nexport class DurableAttachNotSupportedError extends Error {\n  constructor(\n    readonly adapter: string,\n    readonly reason: string,\n  ) {\n    super(\n      `${adapter}: this code path cannot ATTACH to an existing durable run (${reason}). ` +\n        `It does not journal, so there is no stored output to replay and no alignment to suppress what was already delivered. ` +\n        `Proceeding would re-run the agent from scratch against the workspace the previous attempt already modified, and double-append its entire output to the run log. ` +\n        `Route the attach through a journaling spawn path, or drop \\`runs\\`/\\`durability\\` from withSandbox(...) so the run is never resumed in the first place. ` +\n        `This is not a transient condition — unlike \\`JournalAttachUnavailableError\\`, waiting and retrying can never make it succeed.`,\n    )\n    this.name = 'DurableAttachNotSupportedError'\n  }\n}\n\n/**\n * Resolve `withSandbox`'s two durability options into the capability payload, or\n * `undefined` when the app has not opted in.\n *\n * BOTH `runs` and `durability` are required. A half-configured app gets\n * `undefined` **silently** rather than a warning: it has not asked for\n * durability, so there is nothing to warn about, and the resulting behavior\n * (destroy on disconnect, no journal) is exactly today's.\n */\nexport function resolveSandboxDurability<TOffset extends string = string>(\n  options:\n    | { runs?: RunStore; durability?: SandboxDurabilityOptions<TOffset> }\n    | undefined,\n): SandboxRunDurability | undefined {\n  const runs = options?.runs\n  const durability = options?.durability\n  if (runs === undefined || durability === undefined) return undefined\n  return {\n    runs,\n    adapter: durability.adapter,\n    journalDir: durability.journal ?? DEFAULT_JOURNAL_DIR,\n    attach: durability.attach === true,\n    detachOnDisconnect: durability.detachOnDisconnect !== false,\n    ...(durability.pollIntervalMs === undefined\n      ? {}\n      : { pollIntervalMs: durability.pollIntervalMs }),\n    ...(durability.attachWaitMs === undefined\n      ? {}\n      : { attachWaitMs: durability.attachWaitMs }),\n  }\n}\n\n/**\n * Build the `spawnNdjson` journal option for a run, or `undefined` when the run\n * is not durable — in which case `spawnNdjson` takes its original, unjournaled\n * path (`isJournaled` tests `options.journal !== undefined`, `runner.ts:70-72`)\n * and behavior is byte-identical to a pre-durability run.\n *\n * `JournalOptions.dir` is optional, but this always supplies it: the resolved\n * durability has already defaulted `journalDir`, and a successor host must\n * recompute the same path rather than re-derive the default independently.\n *\n * `runs` and `attachWaitMs` are carried ONLY when attaching, and that is not a\n * micro-optimization: they exist for `awaitAttachableJournal`, which the reader\n * runs on the attach path alone. A fresh run has no journal yet BY DESIGN (its own\n * `journaledCommand` spawn creates it moments later), so handing it a run store\n * would only invite a future change to gate a path where absence proves nothing.\n */\nexport function journalOptionsFor(\n  durability: SandboxRunDurability | undefined,\n  runId: string,\n): JournalOptions | undefined {\n  if (durability === undefined) return undefined\n  return {\n    runId,\n    dir: durability.journalDir,\n    attach: durability.attach,\n    ...(durability.pollIntervalMs === undefined\n      ? {}\n      : { pollIntervalMs: durability.pollIntervalMs }),\n    ...(durability.attach\n      ? {\n          runs: durability.runs,\n          ...(durability.attachWaitMs === undefined\n            ? {}\n            : { attachWaitMs: durability.attachWaitMs }),\n        }\n      : {}),\n  }\n}\n\n/**\n * Align a harness stream against the run's stored log — but ONLY on an attach.\n *\n * The `attach` guard is not an optimization, it is a CORRECTNESS requirement.\n * `alignToStoredLog` snapshots the log before the first chunk is pulled and\n * treats everything in that snapshot as \"already delivered\". On a FRESH run that\n * premise is false: if such a run were aligned against a log that already holds\n * entries — a `runId` collision, a retried request — its own chunks would be\n * matched against those entries and silently SUPPRESSED instead of delivered,\n * which is silent data loss rather than a slow path. Aligning only when\n * re-entering an existing run keeps the transform's premise (\"this stream is a\n * replay of what is already stored\") actually true.\n *\n * `isBridgeCustomChunk` is passed because the stored log holds the previous\n * host's MERGED output, including live bridged-tool CUSTOM events that a replay\n * cannot reproduce; without it a bridged-tool run could not be taken over at\n * all. Wrap the merge RESULT, never the pre-merge translator, or the comparison\n * is against a stream the log never contained.\n */\nexport function alignedIfAttaching(\n  chunks: AsyncIterable<StreamChunk>,\n  durability: SandboxRunDurability | undefined,\n  logger?: InternalLogger,\n): AsyncIterable<StreamChunk> {\n  if (durability === undefined || !durability.attach) return chunks\n  return alignToStoredLog(chunks, {\n    durability: durability.adapter,\n    isOutOfBand: isBridgeCustomChunk,\n    ...(logger === undefined ? {} : { logger }),\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoHA,IAAa,8BACX,iBAAuC,CAAC,CAAC,oBAAoB;;AAG/D,IAAa,CAAC,sBAAsB,4BAClC;;;;;;;;;;;AAYF,IAAa,4BAAb,cAA+C,MAAM;CAC9B;CAArB,YAAY,SAA0B;EACpC,MACE,GAAG,QAAQ,6UAIb;EANmB,KAAA,UAAA;EAOnB,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;AAcA,SAAgB,oBACd,OACA,SACQ;CACR,IAAI,UAAU,KAAA,KAAa,MAAM,SAAS,GAAG,OAAO;CACpD,IAAI,QAAQ,SAAS,MAAM,IAAI,0BAA0B,QAAQ,OAAO;CACxE,OAAO,QAAQ,SAAS;AAC1B;;;;;;;;;;;;;;;;;;AAmBA,IAAa,+BAAb,cAAkD,MAAM;CACjC;CAArB,YAAY,SAA0B;EACpC,MACE,GAAG,QAAQ,6kBAMb;EARmB,KAAA,UAAA;EASnB,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,uBACd,UACA,SAMQ;CACR,IAAI,aAAa,KAAA,KAAa,SAAS,SAAS,GAAG,OAAO;CAC1D,IAAI,QAAQ,WAAW,QAAQ,WAC7B,MAAM,IAAI,6BAA6B,QAAQ,OAAO;CAExD,OAAO,QAAQ,SAAS;AAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,IAAa,iCAAb,cAAoD,MAAM;CAE7C;CACA;CAFX,YACE,SACA,QACA;EACA,MACE,GAAG,QAAQ,6DAA6D,OAAO,8iBAKjF;EATS,KAAA,UAAA;EACA,KAAA,SAAA;EAST,KAAK,OAAO;CACd;AACF;;;;;;;;;;AAWA,SAAgB,yBACd,SAGkC;CAClC,MAAM,OAAO,SAAS;CACtB,MAAM,aAAa,SAAS;CAC5B,IAAI,SAAS,KAAA,KAAa,eAAe,KAAA,GAAW,OAAO,KAAA;CAC3D,OAAO;EACL;EACA,SAAS,WAAW;EACpB,YAAY,WAAW,WAAA;EACvB,QAAQ,WAAW,WAAW;EAC9B,oBAAoB,WAAW,uBAAuB;EACtD,GAAI,WAAW,mBAAmB,KAAA,IAC9B,CAAC,IACD,EAAE,gBAAgB,WAAW,eAAe;EAChD,GAAI,WAAW,iBAAiB,KAAA,IAC5B,CAAC,IACD,EAAE,cAAc,WAAW,aAAa;CAC9C;AACF;;;;;;;;;;;;;;;;;AAkBA,SAAgB,kBACd,YACA,OAC4B;CAC5B,IAAI,eAAe,KAAA,GAAW,OAAO,KAAA;CACrC,OAAO;EACL;EACA,KAAK,WAAW;EAChB,QAAQ,WAAW;EACnB,GAAI,WAAW,mBAAmB,KAAA,IAC9B,CAAC,IACD,EAAE,gBAAgB,WAAW,eAAe;EAChD,GAAI,WAAW,SACX;GACE,MAAM,WAAW;GACjB,GAAI,WAAW,iBAAiB,KAAA,IAC5B,CAAC,IACD,EAAE,cAAc,WAAW,aAAa;EAC9C,IACA,CAAC;CACP;AACF;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,mBACd,QACA,YACA,QAC4B;CAC5B,IAAI,eAAe,KAAA,KAAa,CAAC,WAAW,QAAQ,OAAO;CAC3D,OAAO,iBAAiB,QAAQ;EAC9B,YAAY,WAAW;EACvB,aAAa;EACb,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;CAC3C,CAAC;AACH"}

package/dist/esm/errors.js

@@ -1,25 +1,29 @@
-class UnsupportedCapabilityError extends Error {
-  provider;
-  capability;
-  constructor(provider, capability, hint) {
-    super(
-      `Sandbox provider "${provider}" does not support the "${capability}" capability.` + (hint ? ` ${hint}` : "")
-    );
-    this.name = "UnsupportedCapabilityError";
-    this.provider = provider;
-    this.capability = capability;
-  }
-}
-class MissingSandboxError extends Error {
-  constructor(adapterName) {
-    super(
-      `Adapter "${adapterName}" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.`
-    );
-    this.name = "MissingSandboxError";
-  }
-}
-export {
-  MissingSandboxError,
-  UnsupportedCapabilityError
+//#region src/errors.ts
+/**
+* Thrown when code invokes an optional sandbox capability that the active
+* provider does not support. Core/middleware should check
+* `handle.capabilities` BEFORE using an optional capability and degrade
+* gracefully; this error exists so that a direct call to an unsupported
+* optional method fails loud instead of silently no-opping.
+*/
+var UnsupportedCapabilityError = class extends Error {
+	provider;
+	capability;
+	constructor(provider, capability, hint) {
+		super(`Sandbox provider "${provider}" does not support the "${capability}" capability.` + (hint ? ` ${hint}` : ""));
+		this.name = "UnsupportedCapabilityError";
+		this.provider = provider;
+		this.capability = capability;
+	}
 };
-//# sourceMappingURL=errors.js.map
+/** Thrown when a harness adapter requires a sandbox but none was provided. */
+var MissingSandboxError = class extends Error {
+	constructor(adapterName) {
+		super(`Adapter "${adapterName}" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.`);
+		this.name = "MissingSandboxError";
+	}
+};
+//#endregion
+export { MissingSandboxError, UnsupportedCapabilityError };
+
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sources":["../../src/errors.ts"],"sourcesContent":["/**\n * Thrown when code invokes an optional sandbox capability that the active\n * provider does not support. Core/middleware should check\n * `handle.capabilities` BEFORE using an optional capability and degrade\n * gracefully; this error exists so that a direct call to an unsupported\n * optional method fails loud instead of silently no-opping.\n */\nexport class UnsupportedCapabilityError extends Error {\n  readonly provider: string\n  readonly capability: string\n\n  constructor(provider: string, capability: string, hint?: string) {\n    super(\n      `Sandbox provider \"${provider}\" does not support the \"${capability}\" capability.` +\n        (hint ? ` ${hint}` : ''),\n    )\n    this.name = 'UnsupportedCapabilityError'\n    this.provider = provider\n    this.capability = capability\n  }\n}\n\n/** Thrown when a harness adapter requires a sandbox but none was provided. */\nexport class MissingSandboxError extends Error {\n  constructor(adapterName: string) {\n    super(\n      `Adapter \"${adapterName}\" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.`,\n    )\n    this.name = 'MissingSandboxError'\n  }\n}\n"],"names":[],"mappings":"AAOO,MAAM,mCAAmC,MAAM;AAAA,EAC3C;AAAA,EACA;AAAA,EAET,YAAY,UAAkB,YAAoB,MAAe;AAC/D;AAAA,MACE,qBAAqB,QAAQ,2BAA2B,UAAU,mBAC/D,OAAO,IAAI,IAAI,KAAK;AAAA,IAAA;AAEzB,SAAK,OAAO;AACZ,SAAK,WAAW;AAChB,SAAK,aAAa;AAAA,EACpB;AACF;AAGO,MAAM,4BAA4B,MAAM;AAAA,EAC7C,YAAY,aAAqB;AAC/B;AAAA,MACE,YAAY,WAAW;AAAA,IAAA;AAEzB,SAAK,OAAO;AAAA,EACd;AACF;"}
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/errors.ts"],"sourcesContent":["/**\n * Thrown when code invokes an optional sandbox capability that the active\n * provider does not support. Core/middleware should check\n * `handle.capabilities` BEFORE using an optional capability and degrade\n * gracefully; this error exists so that a direct call to an unsupported\n * optional method fails loud instead of silently no-opping.\n */\nexport class UnsupportedCapabilityError extends Error {\n  readonly provider: string\n  readonly capability: string\n\n  constructor(provider: string, capability: string, hint?: string) {\n    super(\n      `Sandbox provider \"${provider}\" does not support the \"${capability}\" capability.` +\n        (hint ? ` ${hint}` : ''),\n    )\n    this.name = 'UnsupportedCapabilityError'\n    this.provider = provider\n    this.capability = capability\n  }\n}\n\n/** Thrown when a harness adapter requires a sandbox but none was provided. */\nexport class MissingSandboxError extends Error {\n  constructor(adapterName: string) {\n    super(\n      `Adapter \"${adapterName}\" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.`,\n    )\n    this.name = 'MissingSandboxError'\n  }\n}\n"],"mappings":";;;;;;;;AAOA,IAAa,6BAAb,cAAgD,MAAM;CACpD;CACA;CAEA,YAAY,UAAkB,YAAoB,MAAe;EAC/D,MACE,qBAAqB,SAAS,0BAA0B,WAAW,kBAChE,OAAO,IAAI,SAAS,GACzB;EACA,KAAK,OAAO;EACZ,KAAK,WAAW;EAChB,KAAK,aAAa;CACpB;AACF;;AAGA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,aAAqB;EAC/B,MACE,YAAY,YAAY,oFAC1B;EACA,KAAK,OAAO;CACd;AACF"}

package/dist/esm/file-diff.js

@@ -1,145 +1,161 @@
+//#region src/file-diff.ts
+/** Path relative to the repo/workspace root, POSIX form. */
 function relTo(root, path) {
-  const prefix = root.endsWith("/") ? root : `${root}/`;
-  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+	const prefix = root.endsWith("/") ? root : `${root}/`;
+	return path.startsWith(prefix) ? path.slice(prefix.length) : path;
 }
+/**
+* POSIX single-quote escape for embedding a value in a shell command.
+*/
 function q(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+/**
+* Unified add-patch for a brand-new file, closely following the shape `git
+* diff` produces for an added file (`diff --git` header + `new file mode` +
+* `--- /dev/null` + `+++ b/<rel>`), so synthesized `create` diffs align with
+* the real `git diff` output emitted for `change` events. `rel` must be the
+* repo-root-relative POSIX path (like git's). Reproduces git's `\ No newline
+* at end of file` marker and the header-only form for a zero-byte file, so a
+* consumer applying the patch reconstructs the file byte-for-byte. It is not
+* byte-identical to git — it omits the `index <hash>..<hash>` line and always
+* writes the `+1,N` hunk count (git omits `,1`) — but both are valid
+* unified-diff and accepted by `git apply`/`patch`.
+*/
 function synthesizeAddPatch(rel, content) {
-  const header = `diff --git a/${rel} b/${rel}
-new file mode 100644
-`;
-  if (content === "") return header;
-  const hasFinalNewline = content.endsWith("\n");
-  const lines = content.replace(/\n$/, "").split("\n");
-  const body = lines.map((l) => `+${l}`).join("\n");
-  return header + `--- /dev/null
-+++ b/${rel}
-@@ -0,0 +1,${lines.length} @@
-` + body + (hasFinalNewline ? "\n" : "\n\\n");
+	const header = `diff --git a/${rel} b/${rel}\nnew file mode 100644\n`;
+	if (content === "") return header;
+	const hasFinalNewline = content.endsWith("\n");
+	const lines = content.replace(/\n$/, "").split("\n");
+	const body = lines.map((l) => `+${l}`).join("\n");
+	return header + `--- /dev/null\n+++ b/${rel}\n@@ -0,0 +1,${lines.length} @@\n` + body + (hasFinalNewline ? "\n" : "\n\\n");
 }
+/**
+* Wrap a raw {@link SandboxFileEvent} with lazy git-backed accessors bound to
+* the live handle. `baseSha` is the session baseline (`''` when the workspace
+* isn't a git repo). Never throws — every git/fs failure falls back to `''`
+* (or a synthesized add-patch), but is logged first via `logger` so a failure
+* is observable instead of silently becoming empty data.
+*/
 function buildFileHookEvent(handle, root, baseSha, event, logger) {
-  const after = async () => {
-    if (event.type === "delete") return "";
-    try {
-      return await handle.fs.read(event.path);
-    } catch (error) {
-      logger?.warn("sandbox after() failed to read file", {
-        path: event.path,
-        error
-      });
-      return "";
-    }
-  };
-  const before = async () => {
-    if (baseSha === "") return "";
-    const rel = relTo(root, event.path);
-    try {
-      const res = await handle.process.exec(
-        `git show ${q(baseSha)}:${q(rel)}`,
-        { cwd: root }
-      );
-      if (res.exitCode === 0) return res.stdout;
-      logger?.sandbox("before() git show non-zero exit", {
-        path: event.path,
-        exitCode: res.exitCode,
-        stderr: res.stderr
-      });
-      return "";
-    } catch (error) {
-      logger?.warn("sandbox before() git show failed", {
-        path: event.path,
-        error
-      });
-      return "";
-    }
-  };
-  const synthesizeIfUntracked = async (rel) => {
-    const content = await after();
-    if (content === "") return "";
-    try {
-      const ignored = await handle.process.exec(
-        `git check-ignore -q -- ${q(rel)}`,
-        { cwd: root }
-      );
-      if (ignored.exitCode === 0) {
-        logger?.sandbox("sandbox diff() withheld for git-ignored file", {
-          path: event.path
-        });
-        return "";
-      }
-      if (ignored.exitCode !== 1) {
-        logger?.warn("sandbox diff() git check-ignore non-zero exit", {
-          path: event.path,
-          exitCode: ignored.exitCode,
-          stderr: ignored.stderr
-        });
-      }
-    } catch (error) {
-      logger?.warn("sandbox diff() git check-ignore failed", {
-        path: event.path,
-        error
-      });
-    }
-    try {
-      const res = await handle.process.exec(
-        `git show ${q(baseSha)}:${q(rel)}`,
-        { cwd: root }
-      );
-      if (res.exitCode === 0) return "";
-      logger?.sandbox(
-        "sandbox diff() tracked-ness probe non-zero exit (treating as untracked)",
-        { path: event.path, exitCode: res.exitCode, stderr: res.stderr }
-      );
-      return synthesizeAddPatch(rel, content);
-    } catch (error) {
-      logger?.warn("sandbox diff() tracked-ness probe failed", {
-        path: event.path,
-        error
-      });
-      return "";
-    }
-  };
-  const diff = async () => {
-    if (baseSha === "") {
-      if (event.type === "delete") return "";
-      return synthesizeAddPatch(relTo(root, event.path), await after());
-    }
-    const rel = relTo(root, event.path);
-    try {
-      const res = await handle.process.exec(
-        `git diff ${q(baseSha)} -- ${q(rel)}`,
-        {
-          cwd: root
-        }
-      );
-      if (res.exitCode !== 0) {
-        logger?.warn("sandbox diff() git diff non-zero exit", {
-          path: event.path,
-          exitCode: res.exitCode,
-          stderr: res.stderr
-        });
-        return "";
-      }
-      if (res.stdout !== "") return res.stdout;
-      return synthesizeIfUntracked(rel);
-    } catch (error) {
-      logger?.warn("sandbox diff() git diff failed", {
-        path: event.path,
-        error
-      });
-      return "";
-    }
-  };
-  return { ...event, before, after, diff };
+	const after = async () => {
+		if (event.type === "delete") return "";
+		try {
+			return await handle.fs.read(event.path);
+		} catch (error) {
+			logger?.warn("sandbox after() failed to read file", {
+				path: event.path,
+				error
+			});
+			return "";
+		}
+	};
+	const before = async () => {
+		if (baseSha === "") return "";
+		const rel = relTo(root, event.path);
+		try {
+			const res = await handle.process.exec(`git show ${q(baseSha)}:${q(rel)}`, { cwd: root });
+			if (res.exitCode === 0) return res.stdout;
+			logger?.sandbox("before() git show non-zero exit", {
+				path: event.path,
+				exitCode: res.exitCode,
+				stderr: res.stderr
+			});
+			return "";
+		} catch (error) {
+			logger?.warn("sandbox before() git show failed", {
+				path: event.path,
+				error
+			});
+			return "";
+		}
+	};
+	const synthesizeIfUntracked = async (rel) => {
+		const content = await after();
+		if (content === "") return "";
+		try {
+			const ignored = await handle.process.exec(`git check-ignore -q -- ${q(rel)}`, { cwd: root });
+			if (ignored.exitCode === 0) {
+				logger?.sandbox("sandbox diff() withheld for git-ignored file", { path: event.path });
+				return "";
+			}
+			if (ignored.exitCode !== 1) logger?.warn("sandbox diff() git check-ignore non-zero exit", {
+				path: event.path,
+				exitCode: ignored.exitCode,
+				stderr: ignored.stderr
+			});
+		} catch (error) {
+			logger?.warn("sandbox diff() git check-ignore failed", {
+				path: event.path,
+				error
+			});
+		}
+		try {
+			const res = await handle.process.exec(`git show ${q(baseSha)}:${q(rel)}`, { cwd: root });
+			if (res.exitCode === 0) return "";
+			logger?.sandbox("sandbox diff() tracked-ness probe non-zero exit (treating as untracked)", {
+				path: event.path,
+				exitCode: res.exitCode,
+				stderr: res.stderr
+			});
+			return synthesizeAddPatch(rel, content);
+		} catch (error) {
+			logger?.warn("sandbox diff() tracked-ness probe failed", {
+				path: event.path,
+				error
+			});
+			return "";
+		}
+	};
+	const diff = async () => {
+		if (baseSha === "") {
+			if (event.type === "delete") return "";
+			return synthesizeAddPatch(relTo(root, event.path), await after());
+		}
+		const rel = relTo(root, event.path);
+		try {
+			const res = await handle.process.exec(`git diff ${q(baseSha)} -- ${q(rel)}`, { cwd: root });
+			if (res.exitCode !== 0) {
+				logger?.warn("sandbox diff() git diff non-zero exit", {
+					path: event.path,
+					exitCode: res.exitCode,
+					stderr: res.stderr
+				});
+				return "";
+			}
+			if (res.stdout !== "") return res.stdout;
+			return synthesizeIfUntracked(rel);
+		} catch (error) {
+			logger?.warn("sandbox diff() git diff failed", {
+				path: event.path,
+				error
+			});
+			return "";
+		}
+	};
+	return {
+		...event,
+		before,
+		after,
+		diff
+	};
 }
+/** Normalize the `fileEvents` option (`boolean | { diff?: boolean }`). */
 function resolveFileEvents(opt) {
-  if (opt === false) return { enabled: false, diff: false };
-  if (opt === void 0 || opt === true) return { enabled: true, diff: false };
-  return { enabled: true, diff: opt.diff === true };
+	if (opt === false) return {
+		enabled: false,
+		diff: false
+	};
+	if (opt === void 0 || opt === true) return {
+		enabled: true,
+		diff: false
+	};
+	return {
+		enabled: true,
+		diff: opt.diff === true
+	};
 }
-export {
-  buildFileHookEvent,
-  resolveFileEvents
-};
-//# sourceMappingURL=file-diff.js.map
+//#endregion
+export { buildFileHookEvent, resolveFileEvents };
+
+//# sourceMappingURL=file-diff.js.map