@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/dist/esm/agents-file.js

@@ -1,44 +1,63 @@
-const SYMLINK_NAMES = ["CLAUDE.md", "GEMINI.md"];
+//#region src/agents-file.ts
+/** CLI instruction-file names that should resolve to AGENTS.md. */
+var SYMLINK_NAMES = ["CLAUDE.md", "GEMINI.md"];
+/**
+* Resolve the directory a `gitSkill` repo is cloned into when no explicit
+* `into` override is provided. The convention is:
+*
+*   `<root>/.tanstack-skills/<basename>`
+*
+* where `basename` is derived from the `repo` field by taking the last
+* path segment and stripping a trailing `.git` suffix.
+*
+* Per-harness projectors (e.g. the Claude Code adapter) import this helper
+* so they can locate cloned skill repos consistently.
+*
+* @param root  - Workspace root inside the sandbox (e.g. `/workspace`).
+* @param skill - A `WorkspaceSkill` of `kind === 'git'`.
+*/
 function resolveGitSkillDir(root, skill) {
-  const rawBasename = skill.repo.split("/").pop() ?? skill.repo;
-  const basename = rawBasename.endsWith(".git") ? rawBasename.slice(0, -4) : rawBasename;
-  return `${root}/.tanstack-skills/${basename}`;
+	const rawBasename = skill.repo.split("/").pop() ?? skill.repo;
+	return `${root}/.tanstack-skills/${rawBasename.endsWith(".git") ? rawBasename.slice(0, -4) : rawBasename}`;
 }
+/** Format workspace scripts as a `## Workspace scripts` markdown section. */
 function formatWorkspaceScriptsSection(scripts) {
-  const names = Object.keys(scripts).sort();
-  if (names.length === 0) return "";
-  const lines = names.map((name) => `- ${name} → ${scripts[name]}`);
-  return `## Workspace scripts
-
-${lines.join("\n")}`;
+	const names = Object.keys(scripts).sort();
+	if (names.length === 0) return "";
+	return `## Workspace scripts\n\n${names.map((name) => `- ${name} → ${scripts[name]}`).join("\n")}`;
 }
+/**
+* Merge base AGENTS.md content with an optional workspace scripts section.
+* Returns `undefined` when there is nothing to write.
+*/
 function mergeAgentsContent(base, scripts) {
-  const scriptsSection = scripts !== void 0 ? formatWorkspaceScriptsSection(scripts) : "";
-  if (base === void 0 && scriptsSection.length === 0) return void 0;
-  if (base === void 0) return scriptsSection;
-  if (scriptsSection.length === 0) return base;
-  return `${base.trimEnd()}
-
-${scriptsSection}`;
+	const scriptsSection = scripts !== void 0 ? formatWorkspaceScriptsSection(scripts) : "";
+	if (base === void 0 && scriptsSection.length === 0) return void 0;
+	if (base === void 0) return scriptsSection;
+	if (scriptsSection.length === 0) return base;
+	return `${base.trimEnd()}\n\n${scriptsSection}`;
 }
+/** Escape a string for safe use as a single-quoted shell argument. */
 function sqEscape(value) {
-  return value.replace(/'/g, `'\\''`);
+	return value.replace(/'/g, `'\\''`);
 }
+/**
+* Write `AGENTS.md` under `root` and create per-CLI symlinks (or copies as a
+* fallback when `ln -s` is unavailable).
+*
+* @param handle - The sandbox handle providing `fs` and `process`.
+* @param root   - Absolute path inside the sandbox under which to write.
+* @param content - Markdown content for the instruction file.
+*/
 async function writeAgentsFile(handle, root, content) {
-  const agentsPath = `${root}/AGENTS.md`;
-  await handle.fs.write(agentsPath, content);
-  for (const name of SYMLINK_NAMES) {
-    const lnCmd = `ln -s '${sqEscape("AGENTS.md")}' '${sqEscape(name)}'`;
-    const result = await handle.process.exec(lnCmd, { cwd: root });
-    if (result.exitCode !== 0) {
-      await handle.fs.write(`${root}/${name}`, content);
-    }
-  }
+	const agentsPath = `${root}/AGENTS.md`;
+	await handle.fs.write(agentsPath, content);
+	for (const name of SYMLINK_NAMES) {
+		const lnCmd = `ln -s '${sqEscape("AGENTS.md")}' '${sqEscape(name)}'`;
+		if ((await handle.process.exec(lnCmd, { cwd: root })).exitCode !== 0) await handle.fs.write(`${root}/${name}`, content);
+	}
 }
-export {
-  formatWorkspaceScriptsSection,
-  mergeAgentsContent,
-  resolveGitSkillDir,
-  writeAgentsFile
-};
-//# sourceMappingURL=agents-file.js.map
+//#endregion
+export { formatWorkspaceScriptsSection, mergeAgentsContent, resolveGitSkillDir, writeAgentsFile };
+
+//# sourceMappingURL=agents-file.js.map

package/dist/esm/agents-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents-file.js","sources":["../../src/agents-file.ts"],"sourcesContent":["/**\n * Universal AGENTS.md writer with per-CLI symlink projection, plus the\n * canonical helper for locating cloned gitSkill repositories inside a sandbox.\n *\n * The known-names set below lists the canonical instruction-file names for\n * each AI coding assistant CLI. Keep the list in one place so it is easy to\n * extend. The copy fallback ensures correctness on platforms without symlink\n * support (e.g. Windows).\n *\n * External per-CLI convention: each assistant looks for its own instruction\n * file by name (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, …).\n * We write a single authoritative AGENTS.md and point each name at it.\n */\nimport type { SandboxHandle } from './contracts'\nimport type { WorkspaceSkill } from './workspace'\n\n/** CLI instruction-file names that should resolve to AGENTS.md. */\nconst SYMLINK_NAMES: ReadonlyArray<string> = ['CLAUDE.md', 'GEMINI.md']\n\n/**\n * Resolve the directory a `gitSkill` repo is cloned into when no explicit\n * `into` override is provided. The convention is:\n *\n *   `<root>/.tanstack-skills/<basename>`\n *\n * where `basename` is derived from the `repo` field by taking the last\n * path segment and stripping a trailing `.git` suffix.\n *\n * Per-harness projectors (e.g. the Claude Code adapter) import this helper\n * so they can locate cloned skill repos consistently.\n *\n * @param root  - Workspace root inside the sandbox (e.g. `/workspace`).\n * @param skill - A `WorkspaceSkill` of `kind === 'git'`.\n */\nexport function resolveGitSkillDir(\n  root: string,\n  skill: Extract<WorkspaceSkill, { kind: 'git' }>,\n): string {\n  const rawBasename = skill.repo.split('/').pop() ?? skill.repo\n  const basename = rawBasename.endsWith('.git')\n    ? rawBasename.slice(0, -4)\n    : rawBasename\n  return `${root}/.tanstack-skills/${basename}`\n}\n\n/** Format workspace scripts as a `## Workspace scripts` markdown section. */\nexport function formatWorkspaceScriptsSection(\n  scripts: Record<string, string>,\n): string {\n  const names = Object.keys(scripts).sort()\n  if (names.length === 0) return ''\n  const lines = names.map((name) => `- ${name} → ${scripts[name]}`)\n  return `## Workspace scripts\\n\\n${lines.join('\\n')}`\n}\n\n/**\n * Merge base AGENTS.md content with an optional workspace scripts section.\n * Returns `undefined` when there is nothing to write.\n */\nexport function mergeAgentsContent(\n  base: string | undefined,\n  scripts: Record<string, string> | undefined,\n): string | undefined {\n  const scriptsSection =\n    scripts !== undefined ? formatWorkspaceScriptsSection(scripts) : ''\n  if (base === undefined && scriptsSection.length === 0) return undefined\n  if (base === undefined) return scriptsSection\n  if (scriptsSection.length === 0) return base\n  return `${base.trimEnd()}\\n\\n${scriptsSection}`\n}\n\n/** Escape a string for safe use as a single-quoted shell argument. */\nfunction sqEscape(value: string): string {\n  return value.replace(/'/g, `'\\\\''`)\n}\n\n/**\n * Write `AGENTS.md` under `root` and create per-CLI symlinks (or copies as a\n * fallback when `ln -s` is unavailable).\n *\n * @param handle - The sandbox handle providing `fs` and `process`.\n * @param root   - Absolute path inside the sandbox under which to write.\n * @param content - Markdown content for the instruction file.\n */\nexport async function writeAgentsFile(\n  handle: SandboxHandle,\n  root: string,\n  content: string,\n): Promise<void> {\n  const agentsPath = `${root}/AGENTS.md`\n  await handle.fs.write(agentsPath, content)\n\n  for (const name of SYMLINK_NAMES) {\n    const lnCmd = `ln -s '${sqEscape('AGENTS.md')}' '${sqEscape(name)}'`\n    const result = await handle.process.exec(lnCmd, { cwd: root })\n    if (result.exitCode !== 0) {\n      // Symlinks are not supported on this platform — fall back to a copy.\n      await handle.fs.write(`${root}/${name}`, content)\n    }\n  }\n}\n"],"names":[],"mappings":"AAiBA,MAAM,gBAAuC,CAAC,aAAa,WAAW;AAiB/D,SAAS,mBACd,MACA,OACQ;AACR,QAAM,cAAc,MAAM,KAAK,MAAM,GAAG,EAAE,SAAS,MAAM;AACzD,QAAM,WAAW,YAAY,SAAS,MAAM,IACxC,YAAY,MAAM,GAAG,EAAE,IACvB;AACJ,SAAO,GAAG,IAAI,qBAAqB,QAAQ;AAC7C;AAGO,SAAS,8BACd,SACQ;AACR,QAAM,QAAQ,OAAO,KAAK,OAAO,EAAE,KAAA;AACnC,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,QAAM,QAAQ,MAAM,IAAI,CAAC,SAAS,KAAK,IAAI,MAAM,QAAQ,IAAI,CAAC,EAAE;AAChE,SAAO;AAAA;AAAA,EAA2B,MAAM,KAAK,IAAI,CAAC;AACpD;AAMO,SAAS,mBACd,MACA,SACoB;AACpB,QAAM,iBACJ,YAAY,SAAY,8BAA8B,OAAO,IAAI;AACnE,MAAI,SAAS,UAAa,eAAe,WAAW,EAAG,QAAO;AAC9D,MAAI,SAAS,OAAW,QAAO;AAC/B,MAAI,eAAe,WAAW,EAAG,QAAO;AACxC,SAAO,GAAG,KAAK,QAAA,CAAS;AAAA;AAAA,EAAO,cAAc;AAC/C;AAGA,SAAS,SAAS,OAAuB;AACvC,SAAO,MAAM,QAAQ,MAAM,OAAO;AACpC;AAUA,eAAsB,gBACpB,QACA,MACA,SACe;AACf,QAAM,aAAa,GAAG,IAAI;AAC1B,QAAM,OAAO,GAAG,MAAM,YAAY,OAAO;AAEzC,aAAW,QAAQ,eAAe;AAChC,UAAM,QAAQ,UAAU,SAAS,WAAW,CAAC,MAAM,SAAS,IAAI,CAAC;AACjE,UAAM,SAAS,MAAM,OAAO,QAAQ,KAAK,OAAO,EAAE,KAAK,MAAM;AAC7D,QAAI,OAAO,aAAa,GAAG;AAEzB,YAAM,OAAO,GAAG,MAAM,GAAG,IAAI,IAAI,IAAI,IAAI,OAAO;AAAA,IAClD;AAAA,EACF;AACF;"}
+{"version":3,"file":"agents-file.js","names":[],"sources":["../../src/agents-file.ts"],"sourcesContent":["/**\n * Universal AGENTS.md writer with per-CLI symlink projection, plus the\n * canonical helper for locating cloned gitSkill repositories inside a sandbox.\n *\n * The known-names set below lists the canonical instruction-file names for\n * each AI coding assistant CLI. Keep the list in one place so it is easy to\n * extend. The copy fallback ensures correctness on platforms without symlink\n * support (e.g. Windows).\n *\n * External per-CLI convention: each assistant looks for its own instruction\n * file by name (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, …).\n * We write a single authoritative AGENTS.md and point each name at it.\n */\nimport type { SandboxHandle } from './contracts'\nimport type { WorkspaceSkill } from './workspace'\n\n/** CLI instruction-file names that should resolve to AGENTS.md. */\nconst SYMLINK_NAMES: ReadonlyArray<string> = ['CLAUDE.md', 'GEMINI.md']\n\n/**\n * Resolve the directory a `gitSkill` repo is cloned into when no explicit\n * `into` override is provided. The convention is:\n *\n *   `<root>/.tanstack-skills/<basename>`\n *\n * where `basename` is derived from the `repo` field by taking the last\n * path segment and stripping a trailing `.git` suffix.\n *\n * Per-harness projectors (e.g. the Claude Code adapter) import this helper\n * so they can locate cloned skill repos consistently.\n *\n * @param root  - Workspace root inside the sandbox (e.g. `/workspace`).\n * @param skill - A `WorkspaceSkill` of `kind === 'git'`.\n */\nexport function resolveGitSkillDir(\n  root: string,\n  skill: Extract<WorkspaceSkill, { kind: 'git' }>,\n): string {\n  const rawBasename = skill.repo.split('/').pop() ?? skill.repo\n  const basename = rawBasename.endsWith('.git')\n    ? rawBasename.slice(0, -4)\n    : rawBasename\n  return `${root}/.tanstack-skills/${basename}`\n}\n\n/** Format workspace scripts as a `## Workspace scripts` markdown section. */\nexport function formatWorkspaceScriptsSection(\n  scripts: Record<string, string>,\n): string {\n  const names = Object.keys(scripts).sort()\n  if (names.length === 0) return ''\n  const lines = names.map((name) => `- ${name} → ${scripts[name]}`)\n  return `## Workspace scripts\\n\\n${lines.join('\\n')}`\n}\n\n/**\n * Merge base AGENTS.md content with an optional workspace scripts section.\n * Returns `undefined` when there is nothing to write.\n */\nexport function mergeAgentsContent(\n  base: string | undefined,\n  scripts: Record<string, string> | undefined,\n): string | undefined {\n  const scriptsSection =\n    scripts !== undefined ? formatWorkspaceScriptsSection(scripts) : ''\n  if (base === undefined && scriptsSection.length === 0) return undefined\n  if (base === undefined) return scriptsSection\n  if (scriptsSection.length === 0) return base\n  return `${base.trimEnd()}\\n\\n${scriptsSection}`\n}\n\n/** Escape a string for safe use as a single-quoted shell argument. */\nfunction sqEscape(value: string): string {\n  return value.replace(/'/g, `'\\\\''`)\n}\n\n/**\n * Write `AGENTS.md` under `root` and create per-CLI symlinks (or copies as a\n * fallback when `ln -s` is unavailable).\n *\n * @param handle - The sandbox handle providing `fs` and `process`.\n * @param root   - Absolute path inside the sandbox under which to write.\n * @param content - Markdown content for the instruction file.\n */\nexport async function writeAgentsFile(\n  handle: SandboxHandle,\n  root: string,\n  content: string,\n): Promise<void> {\n  const agentsPath = `${root}/AGENTS.md`\n  await handle.fs.write(agentsPath, content)\n\n  for (const name of SYMLINK_NAMES) {\n    const lnCmd = `ln -s '${sqEscape('AGENTS.md')}' '${sqEscape(name)}'`\n    const result = await handle.process.exec(lnCmd, { cwd: root })\n    if (result.exitCode !== 0) {\n      // Symlinks are not supported on this platform — fall back to a copy.\n      await handle.fs.write(`${root}/${name}`, content)\n    }\n  }\n}\n"],"mappings":";;AAiBA,IAAM,gBAAuC,CAAC,aAAa,WAAW;;;;;;;;;;;;;;;;AAiBtE,SAAgB,mBACd,MACA,OACQ;CACR,MAAM,cAAc,MAAM,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK,MAAM;CAIzD,OAAO,GAAG,KAAK,oBAHE,YAAY,SAAS,MAAM,IACxC,YAAY,MAAM,GAAG,EAAE,IACvB;AAEN;;AAGA,SAAgB,8BACd,SACQ;CACR,MAAM,QAAQ,OAAO,KAAK,OAAO,CAAC,CAAC,KAAK;CACxC,IAAI,MAAM,WAAW,GAAG,OAAO;CAE/B,OAAO,2BADO,MAAM,KAAK,SAAS,KAAK,KAAK,KAAK,QAAQ,OACvB,CAAA,CAAM,KAAK,IAAI;AACnD;;;;;AAMA,SAAgB,mBACd,MACA,SACoB;CACpB,MAAM,iBACJ,YAAY,KAAA,IAAY,8BAA8B,OAAO,IAAI;CACnE,IAAI,SAAS,KAAA,KAAa,eAAe,WAAW,GAAG,OAAO,KAAA;CAC9D,IAAI,SAAS,KAAA,GAAW,OAAO;CAC/B,IAAI,eAAe,WAAW,GAAG,OAAO;CACxC,OAAO,GAAG,KAAK,QAAQ,EAAE,MAAM;AACjC;;AAGA,SAAS,SAAS,OAAuB;CACvC,OAAO,MAAM,QAAQ,MAAM,OAAO;AACpC;;;;;;;;;AAUA,eAAsB,gBACpB,QACA,MACA,SACe;CACf,MAAM,aAAa,GAAG,KAAK;CAC3B,MAAM,OAAO,GAAG,MAAM,YAAY,OAAO;CAEzC,KAAK,MAAM,QAAQ,eAAe;EAChC,MAAM,QAAQ,UAAU,SAAS,WAAW,EAAE,KAAK,SAAS,IAAI,EAAE;EAElE,KAAI,MADiB,OAAO,QAAQ,KAAK,OAAO,EAAE,KAAK,KAAK,CAAC,EAAA,CAClD,aAAa,GAEtB,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,OAAO;CAEpD;AACF"}

package/dist/esm/align.d.ts

@@ -0,0 +1,121 @@
+import { InternalLogger } from '@tanstack/ai/adapter-internals';
+import { StreamChunk, StreamDurability } from '@tanstack/ai';
+/**
+ * Default bound on consecutive stored chunks alignment will skip as out-of-band.
+ *
+ * A bound is what keeps this a tolerance rather than a search. Unbounded, a
+ * genuine determinism regression would make alignment scan forward through the
+ * whole log looking for a fingerprint that happens to match, suppress
+ * everything it passed, and deliver a stream whose prefix and suffix disagree —
+ * the exact failure {@link JournalReplayDivergedError} exists to prevent. 64 is
+ * well above any realistic burst of bridged console events between two
+ * translated chunks and well below a log length where a false match becomes
+ * plausible.
+ */
+export declare const DEFAULT_MAX_OUT_OF_BAND_SKIP = 64;
+/**
+ * The out-of-band predicate for the harness adapters.
+ *
+ * `ai-codex` and `ai-claude-code` splice `createBridgeEventChannel`'s stream
+ * into their translated output with `mergeChunkStreams`. That channel is the
+ * only producer on the path and it emits exclusively `EventType.CUSTOM` chunks
+ * (`bridge-events.ts:53-63`), fired by LIVE bridged-tool execution. A replay
+ * runs no tools, so those chunks exist in the log and not in the replay.
+ *
+ * Structural rather than a list of event names on purpose: a new bridged tool
+ * inventing a new `name` must not silently reintroduce the divergence.
+ */
+export declare function isBridgeCustomChunk(chunk: StreamChunk): boolean;
+/**
+ * The replay produced a different chunk than the log already holds at that
+ * index. Means translation stopped being deterministic — a `genId` that is not
+ * run-scoped, a translator that consults the clock, or a journal that was
+ * rewritten. Fail loud: suppressing the mismatch would deliver a stream whose
+ * prefix and suffix disagree about message identity.
+ */
+export declare class JournalReplayDivergedError extends Error {
+    readonly index: number;
+    readonly stored: string;
+    readonly replayed: string;
+    constructor(index: number, stored: string, replayed: string);
+}
+/**
+ * The replay reproduced the stored chunk EXACTLY except for its `threadId`.
+ *
+ * A distinct diagnosis because the cause and the fix are entirely different from
+ * a real divergence. The adapters resolve `threadId` as
+ * `options.threadId ?? this.generateId()`, and that id lands in every emitted
+ * chunk — so an attach route that drives a run without passing the run record's
+ * `threadId` mints a fresh one, and the very first chunk (`RUN_STARTED`) fails
+ * alignment. The agent behaved identically; only the id moved. Reported as a
+ * generic divergence, that sends the reader hunting for non-determinism in the
+ * translator, which is the wrong place entirely.
+ *
+ * A SUBCLASS of {@link JournalReplayDivergedError}, deliberately: this is still a
+ * divergence and still fatal, so a consumer already branching on the general
+ * class keeps working. The two are not collapsed — a genuine content divergence
+ * throws the base class, so `instanceof JournalReplayThreadIdMismatchError`
+ * separates a config mistake from a determinism bug in exactly one check.
+ */
+export declare class JournalReplayThreadIdMismatchError extends JournalReplayDivergedError {
+    readonly storedThreadId: string | undefined;
+    readonly replayedThreadId: string | undefined;
+    constructor(index: number, stored: string, replayed: string, storedThreadId: string | undefined, replayedThreadId: string | undefined);
+}
+export interface AlignToStoredLogOptions<TOffset extends string = string> {
+    /**
+     * The run's event log. Read from the beginning; never written here.
+     *
+     * Generic in the offset type, defaulted to `string`, for the same reason
+     * {@link RunDeps} is: a branded-cursor backend's `StreamDurability<TOffset>`
+     * is not assignable to `StreamDurability<string>`.
+     *
+     * Narrowed to `snapshot` — the only member this transform touches, as the
+     * function docs below spell out — so the capability-bus view of a log
+     * (`SandboxDurabilityLog`, which omits the offset-invariant `read`) can be
+     * passed straight through by `alignedIfAttaching`. A full `StreamDurability`
+     * still satisfies it, so no existing caller changes.
+     */
+    durability: Pick<StreamDurability<TOffset>, 'snapshot'>;
+    /** Optional sink for the alignment summary. */
+    logger?: InternalLogger;
+    /**
+     * Recognizes a stored chunk that the replay CANNOT reproduce, so alignment
+     * skips it instead of throwing.
+     *
+     * Absent by default, which keeps strict positional comparison: any stored
+     * chunk the replay does not produce is a determinism bug and fails loudly.
+     * Pass {@link isBridgeCustomChunk} on the harness attach path, where the
+     * previous host spliced live bridged-tool events into the log.
+     *
+     * The predicate is applied to the STORED chunk, never to the replayed one. A
+     * skipped entry is suppressed, not re-appended, so the client's view is
+     * unchanged: it already received that chunk under its own offset.
+     */
+    isOutOfBand?: (chunk: StreamChunk) => boolean;
+    /**
+     * Maximum CONSECUTIVE stored chunks that may be skipped as out-of-band before
+     * alignment gives up. Reset by every match. Defaults to
+     * {@link DEFAULT_MAX_OUT_OF_BAND_SKIP}. Ignored when `isOutOfBand` is absent.
+     */
+    maxOutOfBandSkip?: number;
+}
+/**
+ * Suppress the chunks already present in the event log and yield the rest.
+ *
+ * The stored prefix is read exactly once, eagerly, before the first replay
+ * chunk is pulled. Both halves of that matter:
+ *
+ * - **Exactly once**, because a second read mid-stream would race the appends
+ *   the caller is making downstream of this transform and could classify a
+ *   chunk this very run just appended as an already-stored one, dropping it.
+ * - **Via `snapshot()`, never `read()`**. `read` *tails*: it returns only when
+ *   the log is terminalized with `close()` or the caller aborts. A takeover's
+ *   log is open by definition — the host that would have closed it is the host
+ *   that died — so `for await (… of read('-1'))` would never finish, and on an
+ *   empty log `memoryStream` rejects a from-start join outright once its
+ *   first-chunk deadline elapses. `snapshot()` is the bounded read: it resolves
+ *   with what is stored right now, including while the log is still open, and
+ *   resolves to `[]` for a run with nothing stored.
+ */
+export declare function alignToStoredLog<TOffset extends string = string>(chunks: AsyncIterable<StreamChunk>, options: AlignToStoredLogOptions<TOffset>): AsyncIterable<StreamChunk>;

package/dist/esm/align.js

@@ -0,0 +1,197 @@
+import { chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId } from "./chunk-identity.js";
+import { EventType } from "@tanstack/ai";
+//#region src/align.ts
+/**
+* Replay-from-zero with log alignment: the mechanism that makes a resumed
+* journal read idempotent.
+*
+* A host translates journal bytes 0..1000 and appends the resulting chunks, then
+* dies. A successor re-reads the journal **from byte 0** and re-translates it,
+* producing the same chunks again. This transform reads what is already in the
+* event log, verifies that the replay reproduces it, suppresses that prefix, and
+* passes only the remainder downstream to be appended.
+*
+* Why this shape rather than the offset-upsert the design sketched:
+*
+* - `StreamDurability.append` does not accept caller-supplied offsets, and
+*   `UpsertableStreamDurability.upsert` is deliberately **not** used here:
+*   `memoryStream.upsert` rejects any offset it did not mint itself, and
+*   `durableStream` has no `upsert` at all (its offsets embed a
+*   backend-assigned cursor). The journal path therefore only ever *appends*,
+*   and this function's whole job is deciding where that append starts. Do not
+*   "simplify" it into an `upsert` — the recommended production adapter cannot
+*   accept one.
+* - Even if it could, re-translation is only reproducible because
+*   `createRunScopedIdGen` makes it so. The dedupe boundary therefore has to be
+*   *derived from the log*, not tracked beside it — which also means there is no
+*   window in which a checkpoint and the log can disagree, because the log is
+*   the checkpoint.
+* - The log stays append-only with strictly increasing offsets. That is what
+*   `durableStream`'s backend enforces and what the client's offset de-dup
+*   (`ai-client`'s `seen` set) relies on — the client is NOT tolerant of a
+*   duplicated text or tool-argument delta.
+*
+* Divergence is a bug, not a condition to recover from, so it throws.
+*/
+/**
+* Default bound on consecutive stored chunks alignment will skip as out-of-band.
+*
+* A bound is what keeps this a tolerance rather than a search. Unbounded, a
+* genuine determinism regression would make alignment scan forward through the
+* whole log looking for a fingerprint that happens to match, suppress
+* everything it passed, and deliver a stream whose prefix and suffix disagree —
+* the exact failure {@link JournalReplayDivergedError} exists to prevent. 64 is
+* well above any realistic burst of bridged console events between two
+* translated chunks and well below a log length where a false match becomes
+* plausible.
+*/
+var DEFAULT_MAX_OUT_OF_BAND_SKIP = 64;
+/**
+* The out-of-band predicate for the harness adapters.
+*
+* `ai-codex` and `ai-claude-code` splice `createBridgeEventChannel`'s stream
+* into their translated output with `mergeChunkStreams`. That channel is the
+* only producer on the path and it emits exclusively `EventType.CUSTOM` chunks
+* (`bridge-events.ts:53-63`), fired by LIVE bridged-tool execution. A replay
+* runs no tools, so those chunks exist in the log and not in the replay.
+*
+* Structural rather than a list of event names on purpose: a new bridged tool
+* inventing a new `name` must not silently reintroduce the divergence.
+*/
+function isBridgeCustomChunk(chunk) {
+	return chunk.type === EventType.CUSTOM;
+}
+/**
+* The replay produced a different chunk than the log already holds at that
+* index. Means translation stopped being deterministic — a `genId` that is not
+* run-scoped, a translator that consults the clock, or a journal that was
+* rewritten. Fail loud: suppressing the mismatch would deliver a stream whose
+* prefix and suffix disagree about message identity.
+*/
+var JournalReplayDivergedError = class extends Error {
+	index;
+	stored;
+	replayed;
+	constructor(index, stored, replayed) {
+		super(`journal replay diverged at index ${index}: stored ${stored} but replayed ${replayed}`);
+		this.index = index;
+		this.stored = stored;
+		this.replayed = replayed;
+		this.name = "JournalReplayDivergedError";
+	}
+};
+/**
+* The replay reproduced the stored chunk EXACTLY except for its `threadId`.
+*
+* A distinct diagnosis because the cause and the fix are entirely different from
+* a real divergence. The adapters resolve `threadId` as
+* `options.threadId ?? this.generateId()`, and that id lands in every emitted
+* chunk — so an attach route that drives a run without passing the run record's
+* `threadId` mints a fresh one, and the very first chunk (`RUN_STARTED`) fails
+* alignment. The agent behaved identically; only the id moved. Reported as a
+* generic divergence, that sends the reader hunting for non-determinism in the
+* translator, which is the wrong place entirely.
+*
+* A SUBCLASS of {@link JournalReplayDivergedError}, deliberately: this is still a
+* divergence and still fatal, so a consumer already branching on the general
+* class keeps working. The two are not collapsed — a genuine content divergence
+* throws the base class, so `instanceof JournalReplayThreadIdMismatchError`
+* separates a config mistake from a determinism bug in exactly one check.
+*/
+var JournalReplayThreadIdMismatchError = class extends JournalReplayDivergedError {
+	storedThreadId;
+	replayedThreadId;
+	constructor(index, stored, replayed, storedThreadId, replayedThreadId) {
+		super(index, stored, replayed);
+		this.storedThreadId = storedThreadId;
+		this.replayedThreadId = replayedThreadId;
+		this.name = "JournalReplayThreadIdMismatchError";
+		this.message = `journal replay diverged at index ${index} ONLY by threadId: stored ${JSON.stringify(storedThreadId)} but replayed ${JSON.stringify(replayedThreadId)}. Every other field of the chunk is identical, so the agent did NOT behave differently — the attaching run generated a new threadId instead of reusing the run record's. Pass the run record's threadId (RunRecord.threadId, which sandboxRunDriver hands to drive({ runId, threadId, signal })) into chat() on the attach route; without it the adapter falls back to generateId() and every chunk carries an id the stored log cannot match.`;
+	}
+};
+/**
+* Classify a mismatch before throwing.
+*
+* The `threadId`-only case is recognized by comparing the two chunks a SECOND
+* time with `threadId` excluded: equal there and unequal under the real
+* fingerprint means `threadId` is the only field that moved. Cheap, because it
+* runs only on the failure path, and precise, because it is derived from the same
+* fingerprint function rather than a hand-written field diff.
+*/
+function divergenceError(index, storedChunk, replayedChunk, stored, replayed) {
+	const storedThreadId = chunkThreadId(storedChunk);
+	const replayedThreadId = chunkThreadId(replayedChunk);
+	if (storedThreadId !== replayedThreadId && chunkFingerprintIgnoringThreadId(storedChunk) === chunkFingerprintIgnoringThreadId(replayedChunk)) return new JournalReplayThreadIdMismatchError(index, stored, replayed, storedThreadId, replayedThreadId);
+	return new JournalReplayDivergedError(index, stored, replayed);
+}
+/**
+* Suppress the chunks already present in the event log and yield the rest.
+*
+* The stored prefix is read exactly once, eagerly, before the first replay
+* chunk is pulled. Both halves of that matter:
+*
+* - **Exactly once**, because a second read mid-stream would race the appends
+*   the caller is making downstream of this transform and could classify a
+*   chunk this very run just appended as an already-stored one, dropping it.
+* - **Via `snapshot()`, never `read()`**. `read` *tails*: it returns only when
+*   the log is terminalized with `close()` or the caller aborts. A takeover's
+*   log is open by definition — the host that would have closed it is the host
+*   that died — so `for await (… of read('-1'))` would never finish, and on an
+*   empty log `memoryStream` rejects a from-start join outright once its
+*   first-chunk deadline elapses. `snapshot()` is the bounded read: it resolves
+*   with what is stored right now, including while the log is still open, and
+*   resolves to `[]` for a run with nothing stored.
+*/
+async function* alignToStoredLog(chunks, options) {
+	const entries = await options.durability.snapshot();
+	const stored = entries.map((entry) => chunkFingerprint(entry.chunk));
+	const isOutOfBand = options.isOutOfBand;
+	const maxSkip = options.maxOutOfBandSkip ?? 64;
+	let cursor = 0;
+	let suppressed = 0;
+	let skipped = 0;
+	let forwarded = 0;
+	for await (const chunk of chunks) {
+		if (cursor >= stored.length) {
+			forwarded += 1;
+			yield chunk;
+			continue;
+		}
+		const actual = chunkFingerprint(chunk);
+		let consecutiveSkips = 0;
+		for (;;) {
+			const entry = entries[cursor];
+			const expected = stored[cursor];
+			if (entry === void 0 || expected === void 0) {
+				forwarded += 1;
+				yield chunk;
+				break;
+			}
+			if (expected === actual) {
+				cursor += 1;
+				suppressed += 1;
+				break;
+			}
+			if (isOutOfBand === void 0 || !isOutOfBand(entry.chunk)) throw divergenceError(cursor, entry.chunk, chunk, expected, actual);
+			if (consecutiveSkips >= maxSkip) throw divergenceError(cursor, entry.chunk, chunk, expected, actual);
+			cursor += 1;
+			consecutiveSkips += 1;
+			skipped += 1;
+		}
+	}
+	while (cursor < stored.length) {
+		const entry = entries[cursor];
+		if (entry === void 0 || isOutOfBand === void 0 || !isOutOfBand(entry.chunk)) throw new Error(`journal replay is shorter than the stored log: ${stored.length - cursor} stored chunk(s) from index ${cursor} were not reproduced`);
+		cursor += 1;
+		skipped += 1;
+	}
+	options.logger?.provider(`journal alignment: suppressed ${suppressed} stored chunk(s), skipped ${skipped} out-of-band, forwarded ${forwarded}`, {
+		suppressed,
+		skipped,
+		forwarded
+	});
+}
+//#endregion
+export { DEFAULT_MAX_OUT_OF_BAND_SKIP, JournalReplayDivergedError, JournalReplayThreadIdMismatchError, alignToStoredLog, isBridgeCustomChunk };
+
+//# sourceMappingURL=align.js.map

package/dist/esm/align.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"align.js","names":[],"sources":["../../src/align.ts"],"sourcesContent":["/**\n * Replay-from-zero with log alignment: the mechanism that makes a resumed\n * journal read idempotent.\n *\n * A host translates journal bytes 0..1000 and appends the resulting chunks, then\n * dies. A successor re-reads the journal **from byte 0** and re-translates it,\n * producing the same chunks again. This transform reads what is already in the\n * event log, verifies that the replay reproduces it, suppresses that prefix, and\n * passes only the remainder downstream to be appended.\n *\n * Why this shape rather than the offset-upsert the design sketched:\n *\n * - `StreamDurability.append` does not accept caller-supplied offsets, and\n *   `UpsertableStreamDurability.upsert` is deliberately **not** used here:\n *   `memoryStream.upsert` rejects any offset it did not mint itself, and\n *   `durableStream` has no `upsert` at all (its offsets embed a\n *   backend-assigned cursor). The journal path therefore only ever *appends*,\n *   and this function's whole job is deciding where that append starts. Do not\n *   \"simplify\" it into an `upsert` — the recommended production adapter cannot\n *   accept one.\n * - Even if it could, re-translation is only reproducible because\n *   `createRunScopedIdGen` makes it so. The dedupe boundary therefore has to be\n *   *derived from the log*, not tracked beside it — which also means there is no\n *   window in which a checkpoint and the log can disagree, because the log is\n *   the checkpoint.\n * - The log stays append-only with strictly increasing offsets. That is what\n *   `durableStream`'s backend enforces and what the client's offset de-dup\n *   (`ai-client`'s `seen` set) relies on — the client is NOT tolerant of a\n *   duplicated text or tool-argument delta.\n *\n * Divergence is a bug, not a condition to recover from, so it throws.\n */\nimport { EventType } from '@tanstack/ai'\nimport {\n  chunkFingerprint,\n  chunkFingerprintIgnoringThreadId,\n  chunkThreadId,\n} from './chunk-identity'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { StreamChunk, StreamDurability } from '@tanstack/ai'\n\n/**\n * Default bound on consecutive stored chunks alignment will skip as out-of-band.\n *\n * A bound is what keeps this a tolerance rather than a search. Unbounded, a\n * genuine determinism regression would make alignment scan forward through the\n * whole log looking for a fingerprint that happens to match, suppress\n * everything it passed, and deliver a stream whose prefix and suffix disagree —\n * the exact failure {@link JournalReplayDivergedError} exists to prevent. 64 is\n * well above any realistic burst of bridged console events between two\n * translated chunks and well below a log length where a false match becomes\n * plausible.\n */\nexport const DEFAULT_MAX_OUT_OF_BAND_SKIP = 64\n\n/**\n * The out-of-band predicate for the harness adapters.\n *\n * `ai-codex` and `ai-claude-code` splice `createBridgeEventChannel`'s stream\n * into their translated output with `mergeChunkStreams`. That channel is the\n * only producer on the path and it emits exclusively `EventType.CUSTOM` chunks\n * (`bridge-events.ts:53-63`), fired by LIVE bridged-tool execution. A replay\n * runs no tools, so those chunks exist in the log and not in the replay.\n *\n * Structural rather than a list of event names on purpose: a new bridged tool\n * inventing a new `name` must not silently reintroduce the divergence.\n */\nexport function isBridgeCustomChunk(chunk: StreamChunk): boolean {\n  return chunk.type === EventType.CUSTOM\n}\n\n/**\n * The replay produced a different chunk than the log already holds at that\n * index. Means translation stopped being deterministic — a `genId` that is not\n * run-scoped, a translator that consults the clock, or a journal that was\n * rewritten. Fail loud: suppressing the mismatch would deliver a stream whose\n * prefix and suffix disagree about message identity.\n */\nexport class JournalReplayDivergedError extends Error {\n  constructor(\n    readonly index: number,\n    readonly stored: string,\n    readonly replayed: string,\n  ) {\n    super(\n      `journal replay diverged at index ${index}: stored ${stored} but replayed ${replayed}`,\n    )\n    this.name = 'JournalReplayDivergedError'\n  }\n}\n\n/**\n * The replay reproduced the stored chunk EXACTLY except for its `threadId`.\n *\n * A distinct diagnosis because the cause and the fix are entirely different from\n * a real divergence. The adapters resolve `threadId` as\n * `options.threadId ?? this.generateId()`, and that id lands in every emitted\n * chunk — so an attach route that drives a run without passing the run record's\n * `threadId` mints a fresh one, and the very first chunk (`RUN_STARTED`) fails\n * alignment. The agent behaved identically; only the id moved. Reported as a\n * generic divergence, that sends the reader hunting for non-determinism in the\n * translator, which is the wrong place entirely.\n *\n * A SUBCLASS of {@link JournalReplayDivergedError}, deliberately: this is still a\n * divergence and still fatal, so a consumer already branching on the general\n * class keeps working. The two are not collapsed — a genuine content divergence\n * throws the base class, so `instanceof JournalReplayThreadIdMismatchError`\n * separates a config mistake from a determinism bug in exactly one check.\n */\nexport class JournalReplayThreadIdMismatchError extends JournalReplayDivergedError {\n  constructor(\n    index: number,\n    stored: string,\n    replayed: string,\n    readonly storedThreadId: string | undefined,\n    readonly replayedThreadId: string | undefined,\n  ) {\n    super(index, stored, replayed)\n    this.name = 'JournalReplayThreadIdMismatchError'\n    this.message =\n      `journal replay diverged at index ${index} ONLY by threadId: stored ${JSON.stringify(storedThreadId)} but replayed ${JSON.stringify(replayedThreadId)}. ` +\n      `Every other field of the chunk is identical, so the agent did NOT behave differently — the attaching run generated a new threadId instead of reusing the run record's. ` +\n      `Pass the run record's threadId (RunRecord.threadId, which sandboxRunDriver hands to drive({ runId, threadId, signal })) into chat() on the attach route; ` +\n      `without it the adapter falls back to generateId() and every chunk carries an id the stored log cannot match.`\n  }\n}\n\n/**\n * Classify a mismatch before throwing.\n *\n * The `threadId`-only case is recognized by comparing the two chunks a SECOND\n * time with `threadId` excluded: equal there and unequal under the real\n * fingerprint means `threadId` is the only field that moved. Cheap, because it\n * runs only on the failure path, and precise, because it is derived from the same\n * fingerprint function rather than a hand-written field diff.\n */\nfunction divergenceError(\n  index: number,\n  storedChunk: StreamChunk,\n  replayedChunk: StreamChunk,\n  stored: string,\n  replayed: string,\n): JournalReplayDivergedError {\n  const storedThreadId = chunkThreadId(storedChunk)\n  const replayedThreadId = chunkThreadId(replayedChunk)\n  if (\n    storedThreadId !== replayedThreadId &&\n    chunkFingerprintIgnoringThreadId(storedChunk) ===\n      chunkFingerprintIgnoringThreadId(replayedChunk)\n  ) {\n    return new JournalReplayThreadIdMismatchError(\n      index,\n      stored,\n      replayed,\n      storedThreadId,\n      replayedThreadId,\n    )\n  }\n  return new JournalReplayDivergedError(index, stored, replayed)\n}\n\nexport interface AlignToStoredLogOptions<TOffset extends string = string> {\n  /**\n   * The run's event log. Read from the beginning; never written here.\n   *\n   * Generic in the offset type, defaulted to `string`, for the same reason\n   * {@link RunDeps} is: a branded-cursor backend's `StreamDurability<TOffset>`\n   * is not assignable to `StreamDurability<string>`.\n   *\n   * Narrowed to `snapshot` — the only member this transform touches, as the\n   * function docs below spell out — so the capability-bus view of a log\n   * (`SandboxDurabilityLog`, which omits the offset-invariant `read`) can be\n   * passed straight through by `alignedIfAttaching`. A full `StreamDurability`\n   * still satisfies it, so no existing caller changes.\n   */\n  durability: Pick<StreamDurability<TOffset>, 'snapshot'>\n  /** Optional sink for the alignment summary. */\n  logger?: InternalLogger\n  /**\n   * Recognizes a stored chunk that the replay CANNOT reproduce, so alignment\n   * skips it instead of throwing.\n   *\n   * Absent by default, which keeps strict positional comparison: any stored\n   * chunk the replay does not produce is a determinism bug and fails loudly.\n   * Pass {@link isBridgeCustomChunk} on the harness attach path, where the\n   * previous host spliced live bridged-tool events into the log.\n   *\n   * The predicate is applied to the STORED chunk, never to the replayed one. A\n   * skipped entry is suppressed, not re-appended, so the client's view is\n   * unchanged: it already received that chunk under its own offset.\n   */\n  isOutOfBand?: (chunk: StreamChunk) => boolean\n  /**\n   * Maximum CONSECUTIVE stored chunks that may be skipped as out-of-band before\n   * alignment gives up. Reset by every match. Defaults to\n   * {@link DEFAULT_MAX_OUT_OF_BAND_SKIP}. Ignored when `isOutOfBand` is absent.\n   */\n  maxOutOfBandSkip?: number\n}\n\n/**\n * Suppress the chunks already present in the event log and yield the rest.\n *\n * The stored prefix is read exactly once, eagerly, before the first replay\n * chunk is pulled. Both halves of that matter:\n *\n * - **Exactly once**, because a second read mid-stream would race the appends\n *   the caller is making downstream of this transform and could classify a\n *   chunk this very run just appended as an already-stored one, dropping it.\n * - **Via `snapshot()`, never `read()`**. `read` *tails*: it returns only when\n *   the log is terminalized with `close()` or the caller aborts. A takeover's\n *   log is open by definition — the host that would have closed it is the host\n *   that died — so `for await (… of read('-1'))` would never finish, and on an\n *   empty log `memoryStream` rejects a from-start join outright once its\n *   first-chunk deadline elapses. `snapshot()` is the bounded read: it resolves\n *   with what is stored right now, including while the log is still open, and\n *   resolves to `[]` for a run with nothing stored.\n */\nexport async function* alignToStoredLog<TOffset extends string = string>(\n  chunks: AsyncIterable<StreamChunk>,\n  options: AlignToStoredLogOptions<TOffset>,\n): AsyncIterable<StreamChunk> {\n  const entries = await options.durability.snapshot()\n  const stored = entries.map((entry) => chunkFingerprint(entry.chunk))\n\n  const isOutOfBand = options.isOutOfBand\n  const maxSkip = options.maxOutOfBandSkip ?? DEFAULT_MAX_OUT_OF_BAND_SKIP\n\n  let cursor = 0\n  let suppressed = 0\n  let skipped = 0\n  let forwarded = 0\n\n  for await (const chunk of chunks) {\n    // Past the end of the stored log: everything from here is new.\n    if (cursor >= stored.length) {\n      forwarded += 1\n      yield chunk\n      continue\n    }\n\n    const actual = chunkFingerprint(chunk)\n    let consecutiveSkips = 0\n    for (;;) {\n      // `entries` and `stored` are the same length by construction; both are\n      // bound because the predicate needs the CHUNK while the comparison needs\n      // its fingerprint.\n      const entry = entries[cursor]\n      const expected = stored[cursor]\n      if (entry === undefined || expected === undefined) {\n        forwarded += 1\n        yield chunk\n        break\n      }\n      if (expected === actual) {\n        cursor += 1\n        suppressed += 1\n        break\n      }\n      // Mismatch. Only a stored chunk the replay provably cannot reproduce may\n      // be skipped, and only `maxSkip` of them in a row.\n      if (isOutOfBand === undefined || !isOutOfBand(entry.chunk)) {\n        throw divergenceError(cursor, entry.chunk, chunk, expected, actual)\n      }\n      if (consecutiveSkips >= maxSkip) {\n        throw divergenceError(cursor, entry.chunk, chunk, expected, actual)\n      }\n      cursor += 1\n      consecutiveSkips += 1\n      skipped += 1\n    }\n  }\n\n  // Trailing stored entries. Out-of-band ones are expected (a bridged tool's\n  // last event lands after the final translated chunk); anything else means the\n  // journal no longer accounts for chunks the log already delivered, which\n  // nothing downstream can repair.\n  while (cursor < stored.length) {\n    const entry = entries[cursor]\n    if (\n      entry === undefined ||\n      isOutOfBand === undefined ||\n      !isOutOfBand(entry.chunk)\n    ) {\n      throw new Error(\n        `journal replay is shorter than the stored log: ${stored.length - cursor} stored chunk(s) from index ${cursor} were not reproduced`,\n      )\n    }\n    cursor += 1\n    skipped += 1\n  }\n\n  options.logger?.provider(\n    `journal alignment: suppressed ${suppressed} stored chunk(s), skipped ${skipped} out-of-band, forwarded ${forwarded}`,\n    { suppressed, skipped, forwarded },\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,IAAa,+BAA+B;;;;;;;;;;;;;AAc5C,SAAgB,oBAAoB,OAA6B;CAC/D,OAAO,MAAM,SAAS,UAAU;AAClC;;;;;;;;AASA,IAAa,6BAAb,cAAgD,MAAM;CAEzC;CACA;CACA;CAHX,YACE,OACA,QACA,UACA;EACA,MACE,oCAAoC,MAAM,WAAW,OAAO,gBAAgB,UAC9E;EANS,KAAA,QAAA;EACA,KAAA,SAAA;EACA,KAAA,WAAA;EAKT,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;;;AAoBA,IAAa,qCAAb,cAAwD,2BAA2B;CAKtE;CACA;CALX,YACE,OACA,QACA,UACA,gBACA,kBACA;EACA,MAAM,OAAO,QAAQ,QAAQ;EAHpB,KAAA,iBAAA;EACA,KAAA,mBAAA;EAGT,KAAK,OAAO;EACZ,KAAK,UACH,oCAAoC,MAAM,4BAA4B,KAAK,UAAU,cAAc,EAAE,gBAAgB,KAAK,UAAU,gBAAgB,EAAE;CAI1J;AACF;;;;;;;;;;AAWA,SAAS,gBACP,OACA,aACA,eACA,QACA,UAC4B;CAC5B,MAAM,iBAAiB,cAAc,WAAW;CAChD,MAAM,mBAAmB,cAAc,aAAa;CACpD,IACE,mBAAmB,oBACnB,iCAAiC,WAAW,MAC1C,iCAAiC,aAAa,GAEhD,OAAO,IAAI,mCACT,OACA,QACA,UACA,gBACA,gBACF;CAEF,OAAO,IAAI,2BAA2B,OAAO,QAAQ,QAAQ;AAC/D;;;;;;;;;;;;;;;;;;;AA2DA,gBAAuB,iBACrB,QACA,SAC4B;CAC5B,MAAM,UAAU,MAAM,QAAQ,WAAW,SAAS;CAClD,MAAM,SAAS,QAAQ,KAAK,UAAU,iBAAiB,MAAM,KAAK,CAAC;CAEnE,MAAM,cAAc,QAAQ;CAC5B,MAAM,UAAU,QAAQ,oBAAA;CAExB,IAAI,SAAS;CACb,IAAI,aAAa;CACjB,IAAI,UAAU;CACd,IAAI,YAAY;CAEhB,WAAW,MAAM,SAAS,QAAQ;EAEhC,IAAI,UAAU,OAAO,QAAQ;GAC3B,aAAa;GACb,MAAM;GACN;EACF;EAEA,MAAM,SAAS,iBAAiB,KAAK;EACrC,IAAI,mBAAmB;EACvB,SAAS;GAIP,MAAM,QAAQ,QAAQ;GACtB,MAAM,WAAW,OAAO;GACxB,IAAI,UAAU,KAAA,KAAa,aAAa,KAAA,GAAW;IACjD,aAAa;IACb,MAAM;IACN;GACF;GACA,IAAI,aAAa,QAAQ;IACvB,UAAU;IACV,cAAc;IACd;GACF;GAGA,IAAI,gBAAgB,KAAA,KAAa,CAAC,YAAY,MAAM,KAAK,GACvD,MAAM,gBAAgB,QAAQ,MAAM,OAAO,OAAO,UAAU,MAAM;GAEpE,IAAI,oBAAoB,SACtB,MAAM,gBAAgB,QAAQ,MAAM,OAAO,OAAO,UAAU,MAAM;GAEpE,UAAU;GACV,oBAAoB;GACpB,WAAW;EACb;CACF;CAMA,OAAO,SAAS,OAAO,QAAQ;EAC7B,MAAM,QAAQ,QAAQ;EACtB,IACE,UAAU,KAAA,KACV,gBAAgB,KAAA,KAChB,CAAC,YAAY,MAAM,KAAK,GAExB,MAAM,IAAI,MACR,kDAAkD,OAAO,SAAS,OAAO,8BAA8B,OAAO,qBAChH;EAEF,UAAU;EACV,WAAW;CACb;CAEA,QAAQ,QAAQ,SACd,iCAAiC,WAAW,4BAA4B,QAAQ,0BAA0B,aAC1G;EAAE;EAAY;EAAS;CAAU,CACnC;AACF"}

package/dist/esm/approvals.js

@@ -1,36 +1,70 @@
-import { EventType } from "@tanstack/ai";
 import { evaluateCommand } from "./policy.js";
-const APPROVAL_REQUESTED_EVENT = "approval-requested";
+import { EventType } from "@tanstack/ai";
+//#region src/approvals.ts
+/**
+* Shared interactive-approval logic for harness adapters.
+*
+* Flow (rides chat()'s existing resume-based approval mechanism):
+*  1. The agent (inside the sandbox) asks to run a risky action; the harness's
+*     host-side permission callback fires.
+*  2. `resolveApproval` evaluates the sandbox policy: `allow`/`deny` are final;
+*     `ask` consults the client's approval decisions (threaded via
+*     `TextOptions.approvals`, keyed by a stable `approvalId`).
+*  3. On `ask` with no decision yet, the adapter emits an `approval-requested`
+*     CUSTOM event (carrying the `approvalId`) and denies the action this turn.
+*     The client shows UI, then re-runs chat() with the decision in the message;
+*     the engine surfaces it as `approvals`, and the next run allows it.
+*
+* `approvalId` is stable for a given (provider, kind, target) so a client grant
+* matches the same action on the resumed run.
+*/
+/** CUSTOM event name emitted when a harness action needs client approval. */
+var APPROVAL_REQUESTED_EVENT = "approval-requested";
+/** A stable, opaque approval id for a harness action. */
 function approvalId(input) {
-  return `${input.provider}:${input.kind}:${input.target}`;
+	return `${input.provider}:${input.kind}:${input.target}`;
 }
+/** Resolve a harness permission request against policy + client approvals. */
 function resolveApproval(input) {
-  const base = input.command !== void 0 ? evaluateCommand(input.command, input.policy, input.scripts) : input.capability !== void 0 ? input.policy?.capabilities?.[input.capability] ?? input.policy?.default ?? "ask" : input.policy?.default ?? "ask";
-  if (base === "allow") return { decision: "allow", needsApproval: false };
-  if (base === "deny") return { decision: "deny", needsApproval: false };
-  const granted = input.approvals?.get(input.id);
-  if (granted === true) return { decision: "allow", needsApproval: false };
-  if (granted === false) return { decision: "deny", needsApproval: false };
-  return { decision: "deny", needsApproval: true };
+	const base = input.command !== void 0 ? evaluateCommand(input.command, input.policy, input.scripts) : input.capability !== void 0 ? input.policy?.capabilities?.[input.capability] ?? input.policy?.default ?? "ask" : input.policy?.default ?? "ask";
+	if (base === "allow") return {
+		decision: "allow",
+		needsApproval: false
+	};
+	if (base === "deny") return {
+		decision: "deny",
+		needsApproval: false
+	};
+	const granted = input.approvals?.get(input.id);
+	if (granted === true) return {
+		decision: "allow",
+		needsApproval: false
+	};
+	if (granted === false) return {
+		decision: "deny",
+		needsApproval: false
+	};
+	return {
+		decision: "deny",
+		needsApproval: true
+	};
 }
+/** Build the AG-UI `approval-requested` CUSTOM event for a harness action. */
 function buildApprovalRequestedEvent(input) {
-  return {
-    type: EventType.CUSTOM,
-    name: APPROVAL_REQUESTED_EVENT,
-    value: {
-      approvalId: input.approvalId,
-      title: input.title,
-      ...input.detail ?? {}
-    },
-    timestamp: Date.now(),
-    threadId: input.threadId,
-    runId: input.runId
-  };
+	return {
+		type: EventType.CUSTOM,
+		name: APPROVAL_REQUESTED_EVENT,
+		value: {
+			approvalId: input.approvalId,
+			title: input.title,
+			...input.detail ?? {}
+		},
+		timestamp: Date.now(),
+		threadId: input.threadId,
+		runId: input.runId
+	};
 }
-export {
-  APPROVAL_REQUESTED_EVENT,
-  approvalId,
-  buildApprovalRequestedEvent,
-  resolveApproval
-};
-//# sourceMappingURL=approvals.js.map
+//#endregion
+export { APPROVAL_REQUESTED_EVENT, approvalId, buildApprovalRequestedEvent, resolveApproval };
+
+//# sourceMappingURL=approvals.js.map

package/dist/esm/approvals.js.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.js","sources":["../../src/approvals.ts"],"sourcesContent":["/**\n * Shared interactive-approval logic for harness adapters.\n *\n * Flow (rides chat()'s existing resume-based approval mechanism):\n *  1. The agent (inside the sandbox) asks to run a risky action; the harness's\n *     host-side permission callback fires.\n *  2. `resolveApproval` evaluates the sandbox policy: `allow`/`deny` are final;\n *     `ask` consults the client's approval decisions (threaded via\n *     `TextOptions.approvals`, keyed by a stable `approvalId`).\n *  3. On `ask` with no decision yet, the adapter emits an `approval-requested`\n *     CUSTOM event (carrying the `approvalId`) and denies the action this turn.\n *     The client shows UI, then re-runs chat() with the decision in the message;\n *     the engine surfaces it as `approvals`, and the next run allows it.\n *\n * `approvalId` is stable for a given (provider, kind, target) so a client grant\n * matches the same action on the resumed run.\n */\nimport { EventType } from '@tanstack/ai'\nimport { evaluateCommand } from './policy'\nimport type { SandboxPolicy } from './policy'\nimport type { StreamChunk } from '@tanstack/ai'\n\n/** CUSTOM event name emitted when a harness action needs client approval. */\nexport const APPROVAL_REQUESTED_EVENT = 'approval-requested'\n\n/** A stable, opaque approval id for a harness action. */\nexport function approvalId(input: {\n  provider: string\n  kind: 'command' | 'fileWrite' | 'network' | 'tool'\n  target: string\n}): string {\n  return `${input.provider}:${input.kind}:${input.target}`\n}\n\nexport interface ResolveApprovalInput {\n  policy: SandboxPolicy | undefined\n  /** Client approval decisions, keyed by `approvalId`. */\n  approvals: ReadonlyMap<string, boolean> | undefined\n  /** Precomputed approval id for this action. */\n  id: string\n  /** A shell command to match against `policy.commands`. */\n  command?: string\n  /** Named workspace scripts for policy alias resolution. */\n  scripts?: Record<string, string>\n  /** A coarse capability to match against `policy.capabilities`. */\n  capability?: 'fileWrite' | 'network'\n}\n\nexport interface ApprovalOutcome {\n  decision: 'allow' | 'deny'\n  /** True when policy said `ask` and the client hasn't decided yet. */\n  needsApproval: boolean\n}\n\n/** Resolve a harness permission request against policy + client approvals. */\nexport function resolveApproval(input: ResolveApprovalInput): ApprovalOutcome {\n  const base =\n    input.command !== undefined\n      ? evaluateCommand(input.command, input.policy, input.scripts)\n      : input.capability !== undefined\n        ? (input.policy?.capabilities?.[input.capability] ??\n          input.policy?.default ??\n          'ask')\n        : (input.policy?.default ?? 'ask')\n\n  if (base === 'allow') return { decision: 'allow', needsApproval: false }\n  if (base === 'deny') return { decision: 'deny', needsApproval: false }\n\n  // base === 'ask' — consult the client's decision.\n  const granted = input.approvals?.get(input.id)\n  if (granted === true) return { decision: 'allow', needsApproval: false }\n  if (granted === false) return { decision: 'deny', needsApproval: false }\n  return { decision: 'deny', needsApproval: true }\n}\n\n/** Build the AG-UI `approval-requested` CUSTOM event for a harness action. */\nexport function buildApprovalRequestedEvent(input: {\n  approvalId: string\n  title: string\n  threadId: string\n  runId: string\n  detail?: Record<string, unknown>\n}): StreamChunk {\n  return {\n    type: EventType.CUSTOM,\n    name: APPROVAL_REQUESTED_EVENT,\n    value: {\n      approvalId: input.approvalId,\n      title: input.title,\n      ...(input.detail ?? {}),\n    },\n    timestamp: Date.now(),\n    threadId: input.threadId,\n    runId: input.runId,\n  }\n}\n"],"names":[],"mappings":";;AAuBO,MAAM,2BAA2B;AAGjC,SAAS,WAAW,OAIhB;AACT,SAAO,GAAG,MAAM,QAAQ,IAAI,MAAM,IAAI,IAAI,MAAM,MAAM;AACxD;AAuBO,SAAS,gBAAgB,OAA8C;AAC5E,QAAM,OACJ,MAAM,YAAY,SACd,gBAAgB,MAAM,SAAS,MAAM,QAAQ,MAAM,OAAO,IAC1D,MAAM,eAAe,SAClB,MAAM,QAAQ,eAAe,MAAM,UAAU,KAC9C,MAAM,QAAQ,WACd,QACC,MAAM,QAAQ,WAAW;AAElC,MAAI,SAAS,QAAS,QAAO,EAAE,UAAU,SAAS,eAAe,MAAA;AACjE,MAAI,SAAS,OAAQ,QAAO,EAAE,UAAU,QAAQ,eAAe,MAAA;AAG/D,QAAM,UAAU,MAAM,WAAW,IAAI,MAAM,EAAE;AAC7C,MAAI,YAAY,KAAM,QAAO,EAAE,UAAU,SAAS,eAAe,MAAA;AACjE,MAAI,YAAY,MAAO,QAAO,EAAE,UAAU,QAAQ,eAAe,MAAA;AACjE,SAAO,EAAE,UAAU,QAAQ,eAAe,KAAA;AAC5C;AAGO,SAAS,4BAA4B,OAM5B;AACd,SAAO;AAAA,IACL,MAAM,UAAU;AAAA,IAChB,MAAM;AAAA,IACN,OAAO;AAAA,MACL,YAAY,MAAM;AAAA,MAClB,OAAO,MAAM;AAAA,MACb,GAAI,MAAM,UAAU,CAAA;AAAA,IAAC;AAAA,IAEvB,WAAW,KAAK,IAAA;AAAA,IAChB,UAAU,MAAM;AAAA,IAChB,OAAO,MAAM;AAAA,EAAA;AAEjB;"}
+{"version":3,"file":"approvals.js","names":[],"sources":["../../src/approvals.ts"],"sourcesContent":["/**\n * Shared interactive-approval logic for harness adapters.\n *\n * Flow (rides chat()'s existing resume-based approval mechanism):\n *  1. The agent (inside the sandbox) asks to run a risky action; the harness's\n *     host-side permission callback fires.\n *  2. `resolveApproval` evaluates the sandbox policy: `allow`/`deny` are final;\n *     `ask` consults the client's approval decisions (threaded via\n *     `TextOptions.approvals`, keyed by a stable `approvalId`).\n *  3. On `ask` with no decision yet, the adapter emits an `approval-requested`\n *     CUSTOM event (carrying the `approvalId`) and denies the action this turn.\n *     The client shows UI, then re-runs chat() with the decision in the message;\n *     the engine surfaces it as `approvals`, and the next run allows it.\n *\n * `approvalId` is stable for a given (provider, kind, target) so a client grant\n * matches the same action on the resumed run.\n */\nimport { EventType } from '@tanstack/ai'\nimport { evaluateCommand } from './policy'\nimport type { SandboxPolicy } from './policy'\nimport type { StreamChunk } from '@tanstack/ai'\n\n/** CUSTOM event name emitted when a harness action needs client approval. */\nexport const APPROVAL_REQUESTED_EVENT = 'approval-requested'\n\n/** A stable, opaque approval id for a harness action. */\nexport function approvalId(input: {\n  provider: string\n  kind: 'command' | 'fileWrite' | 'network' | 'tool'\n  target: string\n}): string {\n  return `${input.provider}:${input.kind}:${input.target}`\n}\n\nexport interface ResolveApprovalInput {\n  policy: SandboxPolicy | undefined\n  /** Client approval decisions, keyed by `approvalId`. */\n  approvals: ReadonlyMap<string, boolean> | undefined\n  /** Precomputed approval id for this action. */\n  id: string\n  /** A shell command to match against `policy.commands`. */\n  command?: string\n  /** Named workspace scripts for policy alias resolution. */\n  scripts?: Record<string, string>\n  /** A coarse capability to match against `policy.capabilities`. */\n  capability?: 'fileWrite' | 'network'\n}\n\nexport interface ApprovalOutcome {\n  decision: 'allow' | 'deny'\n  /** True when policy said `ask` and the client hasn't decided yet. */\n  needsApproval: boolean\n}\n\n/** Resolve a harness permission request against policy + client approvals. */\nexport function resolveApproval(input: ResolveApprovalInput): ApprovalOutcome {\n  const base =\n    input.command !== undefined\n      ? evaluateCommand(input.command, input.policy, input.scripts)\n      : input.capability !== undefined\n        ? (input.policy?.capabilities?.[input.capability] ??\n          input.policy?.default ??\n          'ask')\n        : (input.policy?.default ?? 'ask')\n\n  if (base === 'allow') return { decision: 'allow', needsApproval: false }\n  if (base === 'deny') return { decision: 'deny', needsApproval: false }\n\n  // base === 'ask' — consult the client's decision.\n  const granted = input.approvals?.get(input.id)\n  if (granted === true) return { decision: 'allow', needsApproval: false }\n  if (granted === false) return { decision: 'deny', needsApproval: false }\n  return { decision: 'deny', needsApproval: true }\n}\n\n/** Build the AG-UI `approval-requested` CUSTOM event for a harness action. */\nexport function buildApprovalRequestedEvent(input: {\n  approvalId: string\n  title: string\n  threadId: string\n  runId: string\n  detail?: Record<string, unknown>\n}): StreamChunk {\n  return {\n    type: EventType.CUSTOM,\n    name: APPROVAL_REQUESTED_EVENT,\n    value: {\n      approvalId: input.approvalId,\n      title: input.title,\n      ...(input.detail ?? {}),\n    },\n    timestamp: Date.now(),\n    threadId: input.threadId,\n    runId: input.runId,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,2BAA2B;;AAGxC,SAAgB,WAAW,OAIhB;CACT,OAAO,GAAG,MAAM,SAAS,GAAG,MAAM,KAAK,GAAG,MAAM;AAClD;;AAuBA,SAAgB,gBAAgB,OAA8C;CAC5E,MAAM,OACJ,MAAM,YAAY,KAAA,IACd,gBAAgB,MAAM,SAAS,MAAM,QAAQ,MAAM,OAAO,IAC1D,MAAM,eAAe,KAAA,IAClB,MAAM,QAAQ,eAAe,MAAM,eACpC,MAAM,QAAQ,WACd,QACC,MAAM,QAAQ,WAAW;CAElC,IAAI,SAAS,SAAS,OAAO;EAAE,UAAU;EAAS,eAAe;CAAM;CACvE,IAAI,SAAS,QAAQ,OAAO;EAAE,UAAU;EAAQ,eAAe;CAAM;CAGrE,MAAM,UAAU,MAAM,WAAW,IAAI,MAAM,EAAE;CAC7C,IAAI,YAAY,MAAM,OAAO;EAAE,UAAU;EAAS,eAAe;CAAM;CACvE,IAAI,YAAY,OAAO,OAAO;EAAE,UAAU;EAAQ,eAAe;CAAM;CACvE,OAAO;EAAE,UAAU;EAAQ,eAAe;CAAK;AACjD;;AAGA,SAAgB,4BAA4B,OAM5B;CACd,OAAO;EACL,MAAM,UAAU;EAChB,MAAM;EACN,OAAO;GACL,YAAY,MAAM;GAClB,OAAO,MAAM;GACb,GAAI,MAAM,UAAU,CAAC;EACvB;EACA,WAAW,KAAK,IAAI;EACpB,UAAU,MAAM;EAChB,OAAO,MAAM;CACf;AACF"}