@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/dist/esm/bridge-events.js

@@ -1,76 +1,101 @@
 import { EventType } from "@tanstack/ai";
+//#region src/bridge-events.ts
+/**
+* Helpers that let a harness adapter surface custom events emitted by BRIDGED
+* tools (via {@link ToolBridgeCoreOptions.emitCustomEvent}) on its live output
+* stream.
+*
+* The bridge runs out-of-band from the harness's own event stream, so a bridged
+* tool's progress/console events have no path to the client on their own. An
+* adapter creates a {@link BridgeEventChannel}, hands its `emitCustomEvent` to
+* the bridge provisioner, and {@link mergeChunkStreams | merges} the channel's
+* stream into its translated output — so events interleave live while the agent
+* runs (e.g. code mode's `code_mode:console` logs during a long execution).
+*/
+/** Create a channel whose emitted events become CUSTOM {@link StreamChunk}s. */
 function createBridgeEventChannel(meta) {
-  const buffer = [];
-  let notify = null;
-  let closed = false;
-  async function* stream() {
-    for (; ; ) {
-      const next = buffer.shift();
-      if (next !== void 0) {
-        yield next;
-        continue;
-      }
-      if (closed) return;
-      await new Promise((resolve) => {
-        notify = resolve;
-      });
-      notify = null;
-    }
-  }
-  return {
-    emitCustomEvent(eventName, value) {
-      if (closed) return;
-      buffer.push({
-        type: EventType.CUSTOM,
-        name: eventName,
-        value,
-        timestamp: Date.now(),
-        model: meta.model,
-        ...meta.threadId !== void 0 && { threadId: meta.threadId },
-        ...meta.runId !== void 0 && { runId: meta.runId }
-      });
-      notify?.();
-    },
-    close() {
-      closed = true;
-      notify?.();
-    },
-    stream: stream()
-  };
+	const buffer = [];
+	let notify = null;
+	let closed = false;
+	async function* stream() {
+		for (;;) {
+			const next = buffer.shift();
+			if (next !== void 0) {
+				yield next;
+				continue;
+			}
+			if (closed) return;
+			await new Promise((resolve) => {
+				notify = resolve;
+			});
+			notify = null;
+		}
+	}
+	return {
+		emitCustomEvent(eventName, value) {
+			if (closed) return;
+			buffer.push({
+				type: EventType.CUSTOM,
+				name: eventName,
+				value,
+				timestamp: Date.now(),
+				model: meta.model,
+				...meta.threadId !== void 0 && { threadId: meta.threadId },
+				...meta.runId !== void 0 && { runId: meta.runId }
+			});
+			notify?.();
+		},
+		close() {
+			closed = true;
+			notify?.();
+		},
+		stream: stream()
+	};
 }
+/**
+* Merge a `side` chunk stream into a `base` chunk stream, yielding from whichever
+* settles first. Terminates when `base` ends (the run is over), then releases the
+* side iterator — so a never-ending channel (until closed) doesn't hang the merge.
+*/
 async function* mergeChunkStreams(base, side) {
-  const baseIt = base[Symbol.asyncIterator]();
-  const sideIt = side[Symbol.asyncIterator]();
-  let baseNext = baseIt.next().then((r) => ({ from: "base", r }));
-  let sideNext = sideIt.next().then((r) => ({ from: "side", r }));
-  let sideLive = true;
-  try {
-    for (; ; ) {
-      const winner = await Promise.race(
-        sideLive ? [baseNext, sideNext] : [baseNext]
-      );
-      if (winner.from === "base") {
-        if (winner.r.done) return;
-        yield winner.r.value;
-        baseNext = baseIt.next().then((r) => ({ from: "base", r }));
-      } else if (winner.r.done) {
-        sideLive = false;
-      } else {
-        yield winner.r.value;
-        sideNext = sideIt.next().then((r) => ({ from: "side", r }));
-      }
-    }
-  } finally {
-    const baseReturn = baseIt.return?.(void 0);
-    if (baseReturn) void baseReturn.catch(() => {
-    });
-    const sideReturn = sideIt.return?.(void 0);
-    if (sideReturn) void sideReturn.catch(() => {
-    });
-  }
+	const baseIt = base[Symbol.asyncIterator]();
+	const sideIt = side[Symbol.asyncIterator]();
+	let baseNext = baseIt.next().then((r) => ({
+		from: "base",
+		r
+	}));
+	let sideNext = sideIt.next().then((r) => ({
+		from: "side",
+		r
+	}));
+	let sideLive = true;
+	try {
+		for (;;) {
+			const winner = await Promise.race(sideLive ? [baseNext, sideNext] : [baseNext]);
+			if (winner.from === "base") {
+				if (winner.r.done) return;
+				yield winner.r.value;
+				baseNext = baseIt.next().then((r) => ({
+					from: "base",
+					r
+				}));
+			} else if (winner.r.done) sideLive = false;
+			else {
+				yield winner.r.value;
+				sideNext = sideIt.next().then((r) => ({
+					from: "side",
+					r
+				}));
+			}
+		}
+	} finally {
+		const baseReturn = baseIt.return?.(void 0);
+		if (baseReturn) baseReturn.catch(() => {});
+		const sideReturn = sideIt.return?.(void 0);
+		if (sideReturn) sideReturn.catch(() => {});
+	}
 }
-export {
-  createBridgeEventChannel,
-  mergeChunkStreams
-};
-//# sourceMappingURL=bridge-events.js.map
+//#endregion
+export { createBridgeEventChannel, mergeChunkStreams };
+
+//# sourceMappingURL=bridge-events.js.map

package/dist/esm/bridge-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-events.js","sources":["../../src/bridge-events.ts"],"sourcesContent":["/**\n * Helpers that let a harness adapter surface custom events emitted by BRIDGED\n * tools (via {@link ToolBridgeCoreOptions.emitCustomEvent}) on its live output\n * stream.\n *\n * The bridge runs out-of-band from the harness's own event stream, so a bridged\n * tool's progress/console events have no path to the client on their own. An\n * adapter creates a {@link BridgeEventChannel}, hands its `emitCustomEvent` to\n * the bridge provisioner, and {@link mergeChunkStreams | merges} the channel's\n * stream into its translated output — so events interleave live while the agent\n * runs (e.g. code mode's `code_mode:console` logs during a long execution).\n */\nimport { EventType } from '@tanstack/ai'\nimport type { StreamChunk } from '@tanstack/ai'\n\nexport interface BridgeEventChannel {\n  /** Pass as the bridge's `emitCustomEvent`; buffers a CUSTOM chunk for the stream. */\n  emitCustomEvent: (eventName: string, value: Record<string, unknown>) => void\n  /** Live CUSTOM-chunk stream; ends after {@link close} once drained. */\n  stream: AsyncIterable<StreamChunk>\n  /** Stop the stream (call when the run's main output is done). */\n  close: () => void\n}\n\n/** Create a channel whose emitted events become CUSTOM {@link StreamChunk}s. */\nexport function createBridgeEventChannel(meta: {\n  model: string\n  threadId?: string\n  runId?: string\n}): BridgeEventChannel {\n  const buffer: Array<StreamChunk> = []\n  let notify: (() => void) | null = null\n  let closed = false\n\n  async function* stream(): AsyncIterable<StreamChunk> {\n    for (;;) {\n      const next = buffer.shift()\n      if (next !== undefined) {\n        yield next\n        continue\n      }\n      if (closed) return\n      await new Promise<void>((resolve) => {\n        notify = resolve\n      })\n      notify = null\n    }\n  }\n\n  return {\n    emitCustomEvent(eventName, value) {\n      if (closed) return\n      buffer.push({\n        type: EventType.CUSTOM,\n        name: eventName,\n        value,\n        timestamp: Date.now(),\n        model: meta.model,\n        ...(meta.threadId !== undefined && { threadId: meta.threadId }),\n        ...(meta.runId !== undefined && { runId: meta.runId }),\n      })\n      notify?.()\n    },\n    close() {\n      closed = true\n      notify?.()\n    },\n    stream: stream(),\n  }\n}\n\n/**\n * Merge a `side` chunk stream into a `base` chunk stream, yielding from whichever\n * settles first. Terminates when `base` ends (the run is over), then releases the\n * side iterator — so a never-ending channel (until closed) doesn't hang the merge.\n */\nexport async function* mergeChunkStreams(\n  base: AsyncIterable<StreamChunk>,\n  side: AsyncIterable<StreamChunk>,\n): AsyncIterable<StreamChunk> {\n  const baseIt = base[Symbol.asyncIterator]()\n  const sideIt = side[Symbol.asyncIterator]()\n  let baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))\n  let sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))\n  let sideLive = true\n  try {\n    for (;;) {\n      const winner = await Promise.race(\n        sideLive ? [baseNext, sideNext] : [baseNext],\n      )\n      if (winner.from === 'base') {\n        if (winner.r.done) return\n        yield winner.r.value\n        baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))\n      } else if (winner.r.done) {\n        sideLive = false\n      } else {\n        yield winner.r.value\n        sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))\n      }\n    }\n  } finally {\n    // Fire-and-forget: do NOT await the side return. The channel generator is\n    // suspended on a promise that only `close()` resolves, and `close()` runs in\n    // the adapter's `finally` AFTER this merge completes — awaiting here would\n    // deadlock. The adapter's `close()` lets the generator unwind afterwards.\n    const baseReturn = baseIt.return?.(undefined)\n    if (baseReturn) void baseReturn.catch(() => {})\n    const sideReturn = sideIt.return?.(undefined)\n    if (sideReturn) void sideReturn.catch(() => {})\n  }\n}\n"],"names":[],"mappings":";AAyBO,SAAS,yBAAyB,MAIlB;AACrB,QAAM,SAA6B,CAAA;AACnC,MAAI,SAA8B;AAClC,MAAI,SAAS;AAEb,kBAAgB,SAAqC;AACnD,eAAS;AACP,YAAM,OAAO,OAAO,MAAA;AACpB,UAAI,SAAS,QAAW;AACtB,cAAM;AACN;AAAA,MACF;AACA,UAAI,OAAQ;AACZ,YAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAS;AAAA,MACX,CAAC;AACD,eAAS;AAAA,IACX;AAAA,EACF;AAEA,SAAO;AAAA,IACL,gBAAgB,WAAW,OAAO;AAChC,UAAI,OAAQ;AACZ,aAAO,KAAK;AAAA,QACV,MAAM,UAAU;AAAA,QAChB,MAAM;AAAA,QACN;AAAA,QACA,WAAW,KAAK,IAAA;AAAA,QAChB,OAAO,KAAK;AAAA,QACZ,GAAI,KAAK,aAAa,UAAa,EAAE,UAAU,KAAK,SAAA;AAAA,QACpD,GAAI,KAAK,UAAU,UAAa,EAAE,OAAO,KAAK,MAAA;AAAA,MAAM,CACrD;AACD,eAAA;AAAA,IACF;AAAA,IACA,QAAQ;AACN,eAAS;AACT,eAAA;AAAA,IACF;AAAA,IACA,QAAQ,OAAA;AAAA,EAAO;AAEnB;AAOA,gBAAuB,kBACrB,MACA,MAC4B;AAC5B,QAAM,SAAS,KAAK,OAAO,aAAa,EAAA;AACxC,QAAM,SAAS,KAAK,OAAO,aAAa,EAAA;AACxC,MAAI,WAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AACvE,MAAI,WAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AACvE,MAAI,WAAW;AACf,MAAI;AACF,eAAS;AACP,YAAM,SAAS,MAAM,QAAQ;AAAA,QAC3B,WAAW,CAAC,UAAU,QAAQ,IAAI,CAAC,QAAQ;AAAA,MAAA;AAE7C,UAAI,OAAO,SAAS,QAAQ;AAC1B,YAAI,OAAO,EAAE,KAAM;AACnB,cAAM,OAAO,EAAE;AACf,mBAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AAAA,MACrE,WAAW,OAAO,EAAE,MAAM;AACxB,mBAAW;AAAA,MACb,OAAO;AACL,cAAM,OAAO,EAAE;AACf,mBAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AAAA,MACrE;AAAA,IACF;AAAA,EACF,UAAA;AAKE,UAAM,aAAa,OAAO,SAAS,MAAS;AAC5C,QAAI,WAAY,MAAK,WAAW,MAAM,MAAM;AAAA,IAAC,CAAC;AAC9C,UAAM,aAAa,OAAO,SAAS,MAAS;AAC5C,QAAI,WAAY,MAAK,WAAW,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EAChD;AACF;"}
+{"version":3,"file":"bridge-events.js","names":[],"sources":["../../src/bridge-events.ts"],"sourcesContent":["/**\n * Helpers that let a harness adapter surface custom events emitted by BRIDGED\n * tools (via {@link ToolBridgeCoreOptions.emitCustomEvent}) on its live output\n * stream.\n *\n * The bridge runs out-of-band from the harness's own event stream, so a bridged\n * tool's progress/console events have no path to the client on their own. An\n * adapter creates a {@link BridgeEventChannel}, hands its `emitCustomEvent` to\n * the bridge provisioner, and {@link mergeChunkStreams | merges} the channel's\n * stream into its translated output — so events interleave live while the agent\n * runs (e.g. code mode's `code_mode:console` logs during a long execution).\n */\nimport { EventType } from '@tanstack/ai'\nimport type { StreamChunk } from '@tanstack/ai'\n\nexport interface BridgeEventChannel {\n  /** Pass as the bridge's `emitCustomEvent`; buffers a CUSTOM chunk for the stream. */\n  emitCustomEvent: (eventName: string, value: Record<string, unknown>) => void\n  /** Live CUSTOM-chunk stream; ends after {@link close} once drained. */\n  stream: AsyncIterable<StreamChunk>\n  /** Stop the stream (call when the run's main output is done). */\n  close: () => void\n}\n\n/** Create a channel whose emitted events become CUSTOM {@link StreamChunk}s. */\nexport function createBridgeEventChannel(meta: {\n  model: string\n  threadId?: string\n  runId?: string\n}): BridgeEventChannel {\n  const buffer: Array<StreamChunk> = []\n  let notify: (() => void) | null = null\n  let closed = false\n\n  async function* stream(): AsyncIterable<StreamChunk> {\n    for (;;) {\n      const next = buffer.shift()\n      if (next !== undefined) {\n        yield next\n        continue\n      }\n      if (closed) return\n      await new Promise<void>((resolve) => {\n        notify = resolve\n      })\n      notify = null\n    }\n  }\n\n  return {\n    emitCustomEvent(eventName, value) {\n      if (closed) return\n      buffer.push({\n        type: EventType.CUSTOM,\n        name: eventName,\n        value,\n        timestamp: Date.now(),\n        model: meta.model,\n        ...(meta.threadId !== undefined && { threadId: meta.threadId }),\n        ...(meta.runId !== undefined && { runId: meta.runId }),\n      })\n      notify?.()\n    },\n    close() {\n      closed = true\n      notify?.()\n    },\n    stream: stream(),\n  }\n}\n\n/**\n * Merge a `side` chunk stream into a `base` chunk stream, yielding from whichever\n * settles first. Terminates when `base` ends (the run is over), then releases the\n * side iterator — so a never-ending channel (until closed) doesn't hang the merge.\n */\nexport async function* mergeChunkStreams(\n  base: AsyncIterable<StreamChunk>,\n  side: AsyncIterable<StreamChunk>,\n): AsyncIterable<StreamChunk> {\n  const baseIt = base[Symbol.asyncIterator]()\n  const sideIt = side[Symbol.asyncIterator]()\n  let baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))\n  let sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))\n  let sideLive = true\n  try {\n    for (;;) {\n      const winner = await Promise.race(\n        sideLive ? [baseNext, sideNext] : [baseNext],\n      )\n      if (winner.from === 'base') {\n        if (winner.r.done) return\n        yield winner.r.value\n        baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))\n      } else if (winner.r.done) {\n        sideLive = false\n      } else {\n        yield winner.r.value\n        sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))\n      }\n    }\n  } finally {\n    // Fire-and-forget: do NOT await the side return. The channel generator is\n    // suspended on a promise that only `close()` resolves, and `close()` runs in\n    // the adapter's `finally` AFTER this merge completes — awaiting here would\n    // deadlock. The adapter's `close()` lets the generator unwind afterwards.\n    const baseReturn = baseIt.return?.(undefined)\n    if (baseReturn) void baseReturn.catch(() => {})\n    const sideReturn = sideIt.return?.(undefined)\n    if (sideReturn) void sideReturn.catch(() => {})\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAyBA,SAAgB,yBAAyB,MAIlB;CACrB,MAAM,SAA6B,CAAC;CACpC,IAAI,SAA8B;CAClC,IAAI,SAAS;CAEb,gBAAgB,SAAqC;EACnD,SAAS;GACP,MAAM,OAAO,OAAO,MAAM;GAC1B,IAAI,SAAS,KAAA,GAAW;IACtB,MAAM;IACN;GACF;GACA,IAAI,QAAQ;GACZ,MAAM,IAAI,SAAe,YAAY;IACnC,SAAS;GACX,CAAC;GACD,SAAS;EACX;CACF;CAEA,OAAO;EACL,gBAAgB,WAAW,OAAO;GAChC,IAAI,QAAQ;GACZ,OAAO,KAAK;IACV,MAAM,UAAU;IAChB,MAAM;IACN;IACA,WAAW,KAAK,IAAI;IACpB,OAAO,KAAK;IACZ,GAAI,KAAK,aAAa,KAAA,KAAa,EAAE,UAAU,KAAK,SAAS;IAC7D,GAAI,KAAK,UAAU,KAAA,KAAa,EAAE,OAAO,KAAK,MAAM;GACtD,CAAC;GACD,SAAS;EACX;EACA,QAAQ;GACN,SAAS;GACT,SAAS;EACX;EACA,QAAQ,OAAO;CACjB;AACF;;;;;;AAOA,gBAAuB,kBACrB,MACA,MAC4B;CAC5B,MAAM,SAAS,KAAK,OAAO,cAAc,CAAC;CAC1C,MAAM,SAAS,KAAK,OAAO,cAAc,CAAC;CAC1C,IAAI,WAAW,OAAO,KAAK,CAAC,CAAC,MAAM,OAAO;EAAE,MAAM;EAAiB;CAAE,EAAE;CACvE,IAAI,WAAW,OAAO,KAAK,CAAC,CAAC,MAAM,OAAO;EAAE,MAAM;EAAiB;CAAE,EAAE;CACvE,IAAI,WAAW;CACf,IAAI;EACF,SAAS;GACP,MAAM,SAAS,MAAM,QAAQ,KAC3B,WAAW,CAAC,UAAU,QAAQ,IAAI,CAAC,QAAQ,CAC7C;GACA,IAAI,OAAO,SAAS,QAAQ;IAC1B,IAAI,OAAO,EAAE,MAAM;IACnB,MAAM,OAAO,EAAE;IACf,WAAW,OAAO,KAAK,CAAC,CAAC,MAAM,OAAO;KAAE,MAAM;KAAiB;IAAE,EAAE;GACrE,OAAO,IAAI,OAAO,EAAE,MAClB,WAAW;QACN;IACL,MAAM,OAAO,EAAE;IACf,WAAW,OAAO,KAAK,CAAC,CAAC,MAAM,OAAO;KAAE,MAAM;KAAiB;IAAE,EAAE;GACrE;EACF;CACF,UAAU;EAKR,MAAM,aAAa,OAAO,SAAS,KAAA,CAAS;EAC5C,IAAI,YAAY,WAAgB,YAAY,CAAC,CAAC;EAC9C,MAAM,aAAa,OAAO,SAAS,KAAA,CAAS;EAC5C,IAAI,YAAY,WAAgB,YAAY,CAAC,CAAC;CAChD;AACF"}

package/dist/esm/capabilities.d.ts

@@ -1,10 +1,7 @@
 import { SandboxHandle } from './contracts.js';
-import { LockStore, SandboxStore } from './store.js';
 import { SandboxPolicy } from './policy.js';
 import { ToolBridgeProvisioner } from './tool-bridge.js';
 export declare const SandboxCapability: import('@tanstack/ai').Capability<SandboxHandle, "sandbox">;
-export declare const SandboxStoreCapability: import('@tanstack/ai').Capability<SandboxStore, "sandbox-store">;
-export declare const LocksCapability: import('@tanstack/ai').Capability<LockStore, "locks">;
 /**
  * The active sandbox policy, provided by `withSandbox` from the definition.
  * Harness adapters read it to map allow/ask/deny rules onto their native
@@ -20,7 +17,5 @@ export declare const SandboxPolicyCapability: import('@tanstack/ai').Capability<
 export declare const ToolBridgeProvisionerCapability: import('@tanstack/ai').Capability<ToolBridgeProvisioner, "tool-bridge-provisioner">;
 /** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */
 export declare const getSandbox: import('@tanstack/ai').CapabilityGetter<SandboxHandle>, provideSandbox: import('@tanstack/ai').CapabilityProvider<SandboxHandle>;
-export declare const getSandboxStore: import('@tanstack/ai').CapabilityGetter<SandboxStore>, provideSandboxStore: import('@tanstack/ai').CapabilityProvider<SandboxStore>;
-export declare const getLocks: import('@tanstack/ai').CapabilityGetter<LockStore>, provideLocks: import('@tanstack/ai').CapabilityProvider<LockStore>;
 export declare const getSandboxPolicy: import('@tanstack/ai').CapabilityGetter<SandboxPolicy>, provideSandboxPolicy: import('@tanstack/ai').CapabilityProvider<SandboxPolicy>;
 export declare const getToolBridgeProvisioner: import('@tanstack/ai').CapabilityGetter<ToolBridgeProvisioner>, provideToolBridgeProvisioner: import('@tanstack/ai').CapabilityProvider<ToolBridgeProvisioner>;

package/dist/esm/capabilities.js

@@ -1,29 +1,33 @@
 import { createCapability } from "@tanstack/ai";
-const SandboxCapability = createCapability()("sandbox");
-const SandboxStoreCapability = createCapability()("sandbox-store");
-const LocksCapability = createCapability()("locks");
-const SandboxPolicyCapability = createCapability()("sandbox-policy");
-const ToolBridgeProvisionerCapability = createCapability()("tool-bridge-provisioner");
-const [getSandbox, provideSandbox] = SandboxCapability;
-const [getSandboxStore, provideSandboxStore] = SandboxStoreCapability;
-const [getLocks, provideLocks] = LocksCapability;
-const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability;
-const [getToolBridgeProvisioner, provideToolBridgeProvisioner] = ToolBridgeProvisionerCapability;
-export {
-  LocksCapability,
-  SandboxCapability,
-  SandboxPolicyCapability,
-  SandboxStoreCapability,
-  ToolBridgeProvisionerCapability,
-  getLocks,
-  getSandbox,
-  getSandboxPolicy,
-  getSandboxStore,
-  getToolBridgeProvisioner,
-  provideLocks,
-  provideSandbox,
-  provideSandboxPolicy,
-  provideSandboxStore,
-  provideToolBridgeProvisioner
-};
-//# sourceMappingURL=capabilities.js.map
+//#region src/capabilities.ts
+/**
+* Capability tokens the sandbox layer owns and provides.
+*
+* - `SandboxCapability` is PROVIDED by `withSandbox` and REQUIRED by harness
+*   adapters (`requires: [SandboxCapability]`).
+* - `SandboxInstanceStoreCapability` lives in
+*   `./instance-store` (same package). `LocksCapability` / `withLocks` live in
+*   `@tanstack/ai/locks` and are not re-exported here.
+*/
+var SandboxCapability = createCapability()("sandbox");
+/**
+* The active sandbox policy, provided by `withSandbox` from the definition.
+* Harness adapters read it to map allow/ask/deny rules onto their native
+* permission system.
+*/
+var SandboxPolicyCapability = createCapability()("sandbox-policy");
+/**
+* Provisions the MCP tool-bridge endpoint for a run. OPTIONALLY provided by a
+* serverless/edge orchestrator (e.g. a Durable Object) to override the default
+* `node:http` host transport. Harness adapters read it via `getOptional` and
+* fall back to `nodeHttpBridgeProvisioner` when absent.
+*/
+var ToolBridgeProvisionerCapability = createCapability()("tool-bridge-provisioner");
+/** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */
+var [getSandbox, provideSandbox] = SandboxCapability;
+var [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability;
+var [getToolBridgeProvisioner, provideToolBridgeProvisioner] = ToolBridgeProvisionerCapability;
+//#endregion
+export { SandboxCapability, SandboxPolicyCapability, ToolBridgeProvisionerCapability, getSandbox, getSandboxPolicy, getToolBridgeProvisioner, provideSandbox, provideSandboxPolicy, provideToolBridgeProvisioner };
+
+//# sourceMappingURL=capabilities.js.map

package/dist/esm/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sources":["../../src/capabilities.ts"],"sourcesContent":["/**\n * Capability tokens the sandbox layer provides/consumes through the\n * `@tanstack/ai` middleware capability system.\n *\n * - `SandboxCapability` is PROVIDED by `withSandbox` and REQUIRED by harness\n *   adapters (`requires: [SandboxCapability]`).\n * - `SandboxStoreCapability` / `LocksCapability` are OPTIONALLY required by\n *   `withSandbox`. v1 falls back to in-memory defaults; the future persistence\n *   package PROVIDES durable implementations.\n */\nimport { createCapability } from '@tanstack/ai'\nimport type { SandboxHandle } from './contracts'\nimport type { LockStore, SandboxStore } from './store'\nimport type { SandboxPolicy } from './policy'\nimport type { ToolBridgeProvisioner } from './tool-bridge'\n\nexport const SandboxCapability = createCapability<SandboxHandle>()('sandbox')\n\nexport const SandboxStoreCapability =\n  createCapability<SandboxStore>()('sandbox-store')\n\nexport const LocksCapability = createCapability<LockStore>()('locks')\n\n/**\n * The active sandbox policy, provided by `withSandbox` from the definition.\n * Harness adapters read it to map allow/ask/deny rules onto their native\n * permission system.\n */\nexport const SandboxPolicyCapability =\n  createCapability<SandboxPolicy>()('sandbox-policy')\n\n/**\n * Provisions the MCP tool-bridge endpoint for a run. OPTIONALLY provided by a\n * serverless/edge orchestrator (e.g. a Durable Object) to override the default\n * `node:http` host transport. Harness adapters read it via `getOptional` and\n * fall back to `nodeHttpBridgeProvisioner` when absent.\n */\nexport const ToolBridgeProvisionerCapability =\n  createCapability<ToolBridgeProvisioner>()('tool-bridge-provisioner')\n\n/** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */\nexport const [getSandbox, provideSandbox] = SandboxCapability\nexport const [getSandboxStore, provideSandboxStore] = SandboxStoreCapability\nexport const [getLocks, provideLocks] = LocksCapability\nexport const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability\nexport const [getToolBridgeProvisioner, provideToolBridgeProvisioner] =\n  ToolBridgeProvisionerCapability\n"],"names":[],"mappings":";AAgBO,MAAM,oBAAoB,iBAAA,EAAkC,SAAS;AAErE,MAAM,yBACX,iBAAA,EAAiC,eAAe;AAE3C,MAAM,kBAAkB,iBAAA,EAA8B,OAAO;AAO7D,MAAM,0BACX,iBAAA,EAAkC,gBAAgB;AAQ7C,MAAM,kCACX,iBAAA,EAA0C,yBAAyB;AAG9D,MAAM,CAAC,YAAY,cAAc,IAAI;AACrC,MAAM,CAAC,iBAAiB,mBAAmB,IAAI;AAC/C,MAAM,CAAC,UAAU,YAAY,IAAI;AACjC,MAAM,CAAC,kBAAkB,oBAAoB,IAAI;AACjD,MAAM,CAAC,0BAA0B,4BAA4B,IAClE;"}
+{"version":3,"file":"capabilities.js","names":[],"sources":["../../src/capabilities.ts"],"sourcesContent":["/**\n * Capability tokens the sandbox layer owns and provides.\n *\n * - `SandboxCapability` is PROVIDED by `withSandbox` and REQUIRED by harness\n *   adapters (`requires: [SandboxCapability]`).\n * - `SandboxInstanceStoreCapability` lives in\n *   `./instance-store` (same package). `LocksCapability` / `withLocks` live in\n *   `@tanstack/ai/locks` and are not re-exported here.\n */\nimport { createCapability } from '@tanstack/ai'\nimport type { SandboxHandle } from './contracts'\nimport type { SandboxPolicy } from './policy'\nimport type { ToolBridgeProvisioner } from './tool-bridge'\n\nexport const SandboxCapability = createCapability<SandboxHandle>()('sandbox')\n\n/**\n * The active sandbox policy, provided by `withSandbox` from the definition.\n * Harness adapters read it to map allow/ask/deny rules onto their native\n * permission system.\n */\nexport const SandboxPolicyCapability =\n  createCapability<SandboxPolicy>()('sandbox-policy')\n\n/**\n * Provisions the MCP tool-bridge endpoint for a run. OPTIONALLY provided by a\n * serverless/edge orchestrator (e.g. a Durable Object) to override the default\n * `node:http` host transport. Harness adapters read it via `getOptional` and\n * fall back to `nodeHttpBridgeProvisioner` when absent.\n */\nexport const ToolBridgeProvisionerCapability =\n  createCapability<ToolBridgeProvisioner>()('tool-bridge-provisioner')\n\n/** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */\nexport const [getSandbox, provideSandbox] = SandboxCapability\nexport const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability\nexport const [getToolBridgeProvisioner, provideToolBridgeProvisioner] =\n  ToolBridgeProvisionerCapability\n"],"mappings":";;;;;;;;;;;AAcA,IAAa,oBAAoB,iBAAgC,CAAC,CAAC,SAAS;;;;;;AAO5E,IAAa,0BACX,iBAAgC,CAAC,CAAC,gBAAgB;;;;;;;AAQpD,IAAa,kCACX,iBAAwC,CAAC,CAAC,yBAAyB;;AAGrE,IAAa,CAAC,YAAY,kBAAkB;AAC5C,IAAa,CAAC,kBAAkB,wBAAwB;AACxD,IAAa,CAAC,0BAA0B,gCACtC"}

package/dist/esm/chunk-identity.d.ts

@@ -0,0 +1,52 @@
+import { StreamChunk } from '@tanstack/ai';
+/**
+ * A deterministic id generator scoped to one run.
+ *
+ * Passed as the harness translators' `genId`, so translating the same journal
+ * prefix twice mints the same message ids. The counter is per-generator, so a
+ * replay must create a fresh one and start from the journal's first byte —
+ * which is exactly what the alignment step (a later task) assumes.
+ *
+ * No clock, no `Math.random`, no crypto: `next` is the only state, and it is
+ * seeded fresh for every call to this factory.
+ */
+export declare function createRunScopedIdGen(runId: string): () => string;
+/**
+ * A stable, order-independent identity for a chunk, excluding wall-clock
+ * fields. Used to recognize the chunks a previous host already appended.
+ *
+ * - **Key-order independent**: object keys are sorted before stringifying, so
+ *   a JSON round trip through the journal (which does not preserve key order)
+ *   cannot spuriously diverge.
+ * - **Recurses into nested arrays and objects**: tool-call arguments are
+ *   nested, and a shallow fingerprint would miss a changed argument.
+ * - **Excludes exactly `VOLATILE_FIELDS`** (`timestamp`) — everything else
+ *   participates, including fields whose value is `undefined`.
+ * - **Distinguishes present-but-`undefined` from absent**: `undefined` is
+ *   encoded as the sentinel string `"__undefined__"` rather than dropped, so
+ *   `{a: undefined}` and `{}` do not collide. A translator emitting an
+ *   explicit `undefined` is a different chunk shape and must fingerprint
+ *   differently.
+ */
+export declare function chunkFingerprint(chunk: StreamChunk): string;
+/**
+ * {@link chunkFingerprint} with the chunk's own `threadId` also excluded.
+ *
+ * NOT an alternative identity — never use it to decide that two chunks are the
+ * same. Its single purpose is DIAGNOSIS: when a replay diverges from the stored
+ * log, comparing both fingerprints answers "did the agent behave differently, or
+ * did only the conversation id move?". Two chunks that match here but not under
+ * {@link chunkFingerprint} differ in `threadId` and nothing else, which is a
+ * misconfigured attach route rather than a determinism regression (see
+ * `JournalReplayThreadIdMismatchError` in `align.ts`).
+ */
+export declare function chunkFingerprintIgnoringThreadId(chunk: StreamChunk): string;
+/**
+ * A chunk's own `threadId`, or `undefined` when it carries none.
+ *
+ * Reads the field structurally rather than narrowing on `chunk.type`: nearly
+ * every member of the `StreamChunk` union declares `threadId?: string`, and an
+ * exhaustive switch would have to be revisited for each new member while adding
+ * nothing — a chunk with no `threadId` is exactly the `undefined` case.
+ */
+export declare function chunkThreadId(chunk: StreamChunk): string | undefined;

package/dist/esm/chunk-identity.js

@@ -0,0 +1,102 @@
+//#region src/chunk-identity.ts
+/**
+* A deterministic id generator scoped to one run.
+*
+* Passed as the harness translators' `genId`, so translating the same journal
+* prefix twice mints the same message ids. The counter is per-generator, so a
+* replay must create a fresh one and start from the journal's first byte —
+* which is exactly what the alignment step (a later task) assumes.
+*
+* No clock, no `Math.random`, no crypto: `next` is the only state, and it is
+* seeded fresh for every call to this factory.
+*/
+function createRunScopedIdGen(runId) {
+	let next = 0;
+	return () => {
+		const id = `${runId}-${next}`;
+		next += 1;
+		return id;
+	};
+}
+/**
+* Fields excluded from a fingerprint because they are wall-clock and therefore
+* unreproducible. Kept as an explicit set so adding one is a deliberate,
+* reviewable act rather than a silent loosening of the comparison.
+*/
+var VOLATILE_FIELDS = /* @__PURE__ */ new Set(["timestamp"]);
+/**
+* The conversation id every chunk carries. Excluded from
+* {@link chunkFingerprintIgnoringThreadId} — and ONLY from that variant — so
+* alignment can tell an id-only mismatch from a real content divergence.
+*/
+var THREAD_ID_FIELD = "threadId";
+var VOLATILE_AND_THREAD_ID = /* @__PURE__ */ new Set([...VOLATILE_FIELDS, THREAD_ID_FIELD]);
+/**
+* `dropped` applies at the TOP LEVEL only (nested calls pass `undefined`).
+* A `threadId` nested inside, say, a tool call's arguments is real content and
+* must keep participating in the comparison.
+*/
+function stableStringify(value, dropped) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item, void 0)).join(",")}]`;
+	if (typeof value === "object") {
+		const record = value;
+		return `{${Object.keys(record).filter((key) => dropped === void 0 || !dropped.has(key)).sort().map((key) => {
+			const entry = record[key];
+			const encoded = entry === void 0 ? "\"__undefined__\"" : stableStringify(entry, void 0);
+			return `${JSON.stringify(key)}:${encoded}`;
+		}).join(",")}}`;
+	}
+	const encoded = JSON.stringify(value);
+	return encoded === void 0 ? "null" : encoded;
+}
+/**
+* A stable, order-independent identity for a chunk, excluding wall-clock
+* fields. Used to recognize the chunks a previous host already appended.
+*
+* - **Key-order independent**: object keys are sorted before stringifying, so
+*   a JSON round trip through the journal (which does not preserve key order)
+*   cannot spuriously diverge.
+* - **Recurses into nested arrays and objects**: tool-call arguments are
+*   nested, and a shallow fingerprint would miss a changed argument.
+* - **Excludes exactly `VOLATILE_FIELDS`** (`timestamp`) — everything else
+*   participates, including fields whose value is `undefined`.
+* - **Distinguishes present-but-`undefined` from absent**: `undefined` is
+*   encoded as the sentinel string `"__undefined__"` rather than dropped, so
+*   `{a: undefined}` and `{}` do not collide. A translator emitting an
+*   explicit `undefined` is a different chunk shape and must fingerprint
+*   differently.
+*/
+function chunkFingerprint(chunk) {
+	return stableStringify(chunk, VOLATILE_FIELDS);
+}
+/**
+* {@link chunkFingerprint} with the chunk's own `threadId` also excluded.
+*
+* NOT an alternative identity — never use it to decide that two chunks are the
+* same. Its single purpose is DIAGNOSIS: when a replay diverges from the stored
+* log, comparing both fingerprints answers "did the agent behave differently, or
+* did only the conversation id move?". Two chunks that match here but not under
+* {@link chunkFingerprint} differ in `threadId` and nothing else, which is a
+* misconfigured attach route rather than a determinism regression (see
+* `JournalReplayThreadIdMismatchError` in `align.ts`).
+*/
+function chunkFingerprintIgnoringThreadId(chunk) {
+	return stableStringify(chunk, VOLATILE_AND_THREAD_ID);
+}
+/**
+* A chunk's own `threadId`, or `undefined` when it carries none.
+*
+* Reads the field structurally rather than narrowing on `chunk.type`: nearly
+* every member of the `StreamChunk` union declares `threadId?: string`, and an
+* exhaustive switch would have to be revisited for each new member while adding
+* nothing — a chunk with no `threadId` is exactly the `undefined` case.
+*/
+function chunkThreadId(chunk) {
+	const value = chunk[THREAD_ID_FIELD];
+	return typeof value === "string" ? value : void 0;
+}
+//#endregion
+export { chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, createRunScopedIdGen };
+
+//# sourceMappingURL=chunk-identity.js.map

package/dist/esm/chunk-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-identity.js","names":[],"sources":["../../src/chunk-identity.ts"],"sourcesContent":["/**\n * Deterministic chunk identity — the prerequisite that makes journal replay\n * exact.\n *\n * The design premise is that re-translating a journal prefix reproduces the\n * chunks a previous host already delivered, so a successor can recognize and\n * skip them (see `align.ts`, a later task). Two things in the default path\n * break that premise:\n *\n * 1. `ChatAdapter.generateId()` — `packages/ai/src/activities/chat/adapter.ts:227`,\n *    read directly for this task — is:\n *\n *    ```ts\n *    protected generateId(): string {\n *      return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n *    }\n *    ```\n *\n *    and every harness translator mints message ids through it (wired as\n *    `genId` in the Grok Build, Claude Code, and Codex text adapters). Both\n *    `Date.now()` and `Math.random()` are non-reproducible: replaying the same\n *    journal bytes through a second `generateId()` call produces a different\n *    id every time, so \"same bytes ⇒ same chunks\" is false on the journaled\n *    path today. {@link createRunScopedIdGen} replaces it with a run-scoped\n *    counter that has neither a clock nor randomness, so two generators built\n *    from the same `runId` always produce the same sequence.\n * 2. Chunks also carry `timestamp: Date.now()`, which cannot be reproduced at\n *    all, deterministic id or not. {@link chunkFingerprint} therefore excludes\n *    exactly that field — nothing downstream keys on a chunk's timestamp, so\n *    leaving it wall-clock is safe, but every other field must participate in\n *    the comparison or a real divergence would go undetected.\n */\nimport type { StreamChunk } from '@tanstack/ai'\n\n/**\n * A deterministic id generator scoped to one run.\n *\n * Passed as the harness translators' `genId`, so translating the same journal\n * prefix twice mints the same message ids. The counter is per-generator, so a\n * replay must create a fresh one and start from the journal's first byte —\n * which is exactly what the alignment step (a later task) assumes.\n *\n * No clock, no `Math.random`, no crypto: `next` is the only state, and it is\n * seeded fresh for every call to this factory.\n */\nexport function createRunScopedIdGen(runId: string): () => string {\n  let next = 0\n  return () => {\n    const id = `${runId}-${next}`\n    next += 1\n    return id\n  }\n}\n\n/**\n * Fields excluded from a fingerprint because they are wall-clock and therefore\n * unreproducible. Kept as an explicit set so adding one is a deliberate,\n * reviewable act rather than a silent loosening of the comparison.\n */\nconst VOLATILE_FIELDS: ReadonlySet<string> = new Set(['timestamp'])\n\n/**\n * The conversation id every chunk carries. Excluded from\n * {@link chunkFingerprintIgnoringThreadId} — and ONLY from that variant — so\n * alignment can tell an id-only mismatch from a real content divergence.\n */\nconst THREAD_ID_FIELD = 'threadId'\n\nconst VOLATILE_AND_THREAD_ID: ReadonlySet<string> = new Set([\n  ...VOLATILE_FIELDS,\n  THREAD_ID_FIELD,\n])\n\n/**\n * `dropped` applies at the TOP LEVEL only (nested calls pass `undefined`).\n * A `threadId` nested inside, say, a tool call's arguments is real content and\n * must keep participating in the comparison.\n */\nfunction stableStringify(\n  value: unknown,\n  dropped: ReadonlySet<string> | undefined,\n): string {\n  if (value === null) return 'null'\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item, undefined)).join(',')}]`\n  }\n  if (typeof value === 'object') {\n    const record: Record<string, unknown> = value as Record<string, unknown>\n    const keys = Object.keys(record)\n      .filter((key) => dropped === undefined || !dropped.has(key))\n      .sort()\n    const parts = keys.map((key) => {\n      const entry = record[key]\n      const encoded =\n        entry === undefined\n          ? '\"__undefined__\"'\n          : stableStringify(entry, undefined)\n      return `${JSON.stringify(key)}:${encoded}`\n    })\n    return `{${parts.join(',')}}`\n  }\n  const encoded = JSON.stringify(value)\n  return encoded === undefined ? 'null' : encoded\n}\n\n/**\n * A stable, order-independent identity for a chunk, excluding wall-clock\n * fields. Used to recognize the chunks a previous host already appended.\n *\n * - **Key-order independent**: object keys are sorted before stringifying, so\n *   a JSON round trip through the journal (which does not preserve key order)\n *   cannot spuriously diverge.\n * - **Recurses into nested arrays and objects**: tool-call arguments are\n *   nested, and a shallow fingerprint would miss a changed argument.\n * - **Excludes exactly `VOLATILE_FIELDS`** (`timestamp`) — everything else\n *   participates, including fields whose value is `undefined`.\n * - **Distinguishes present-but-`undefined` from absent**: `undefined` is\n *   encoded as the sentinel string `\"__undefined__\"` rather than dropped, so\n *   `{a: undefined}` and `{}` do not collide. A translator emitting an\n *   explicit `undefined` is a different chunk shape and must fingerprint\n *   differently.\n */\nexport function chunkFingerprint(chunk: StreamChunk): string {\n  return stableStringify(chunk, VOLATILE_FIELDS)\n}\n\n/**\n * {@link chunkFingerprint} with the chunk's own `threadId` also excluded.\n *\n * NOT an alternative identity — never use it to decide that two chunks are the\n * same. Its single purpose is DIAGNOSIS: when a replay diverges from the stored\n * log, comparing both fingerprints answers \"did the agent behave differently, or\n * did only the conversation id move?\". Two chunks that match here but not under\n * {@link chunkFingerprint} differ in `threadId` and nothing else, which is a\n * misconfigured attach route rather than a determinism regression (see\n * `JournalReplayThreadIdMismatchError` in `align.ts`).\n */\nexport function chunkFingerprintIgnoringThreadId(chunk: StreamChunk): string {\n  return stableStringify(chunk, VOLATILE_AND_THREAD_ID)\n}\n\n/**\n * A chunk's own `threadId`, or `undefined` when it carries none.\n *\n * Reads the field structurally rather than narrowing on `chunk.type`: nearly\n * every member of the `StreamChunk` union declares `threadId?: string`, and an\n * exhaustive switch would have to be revisited for each new member while adding\n * nothing — a chunk with no `threadId` is exactly the `undefined` case.\n */\nexport function chunkThreadId(chunk: StreamChunk): string | undefined {\n  const record: Record<string, unknown> = chunk as Record<string, unknown>\n  const value = record[THREAD_ID_FIELD]\n  return typeof value === 'string' ? value : undefined\n}\n"],"mappings":";;;;;;;;;;;;AA6CA,SAAgB,qBAAqB,OAA6B;CAChE,IAAI,OAAO;CACX,aAAa;EACX,MAAM,KAAK,GAAG,MAAM,GAAG;EACvB,QAAQ;EACR,OAAO;CACT;AACF;;;;;;AAOA,IAAM,kCAAuC,IAAI,IAAI,CAAC,WAAW,CAAC;;;;;;AAOlE,IAAM,kBAAkB;AAExB,IAAM,yCAA8C,IAAI,IAAI,CAC1D,GAAG,iBACH,eACF,CAAC;;;;;;AAOD,SAAS,gBACP,OACA,SACQ;CACR,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,IAAI,MAAM,KAAK,SAAS,gBAAgB,MAAM,KAAA,CAAS,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;CAE7E,IAAI,OAAO,UAAU,UAAU;EAC7B,MAAM,SAAkC;EAYxC,OAAO,IAXM,OAAO,KAAK,MAAM,CAAC,CAC7B,QAAQ,QAAQ,YAAY,KAAA,KAAa,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC,CAC3D,KACW,CAAA,CAAK,KAAK,QAAQ;GAC9B,MAAM,QAAQ,OAAO;GACrB,MAAM,UACJ,UAAU,KAAA,IACN,sBACA,gBAAgB,OAAO,KAAA,CAAS;GACtC,OAAO,GAAG,KAAK,UAAU,GAAG,EAAE,GAAG;EACnC,CACW,CAAA,CAAM,KAAK,GAAG,EAAE;CAC7B;CACA,MAAM,UAAU,KAAK,UAAU,KAAK;CACpC,OAAO,YAAY,KAAA,IAAY,SAAS;AAC1C;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,iBAAiB,OAA4B;CAC3D,OAAO,gBAAgB,OAAO,eAAe;AAC/C;;;;;;;;;;;;AAaA,SAAgB,iCAAiC,OAA4B;CAC3E,OAAO,gBAAgB,OAAO,sBAAsB;AACtD;;;;;;;;;AAUA,SAAgB,cAAc,OAAwC;CAEpE,MAAM,QAAQ,MAAO;CACrB,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAA;AAC7C"}