@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/dist/esm/instance-store.js

@@ -0,0 +1,67 @@
+import { createCapability } from "@tanstack/ai";
+//#region src/instance-store.ts
+/**
+* Durable sandbox **instance** map — which provider sandbox (and snapshot) to
+* resume for a compound key. Owned by `@tanstack/ai-sandbox` (not chat
+* persistence): domain is runtime placement for `ensure`, not conversation state.
+*
+* Pass to `withSandbox(sandbox, { instances })`, which uses it in `ensure`
+* (in-memory fallback when absent). {@link SandboxInstanceStoreCapability} is
+* the ambient alternative for platform-level wiring.
+*/
+/**
+* Type a {@link SandboxInstanceStore} implementation inline: pass the object and
+* get autocomplete + contract checking, with no separate
+* `: SandboxInstanceStore` annotation. Hand the result to
+* `withSandbox(sandbox, { instances })`. Matches `defineLock` /
+* `defineMessageStore` style helpers elsewhere in the monorepo.
+*/
+function defineSandboxInstanceStore(store) {
+	return store;
+}
+/**
+* Capability for the instance map — the ambient alternative to
+* `withSandbox(sandbox, { instances })`. Provide it from any middleware with
+* {@link provideSandboxInstanceStore}; `withSandbox` reads it when no explicit
+* option was passed.
+*/
+var SandboxInstanceStoreCapability = createCapability()("sandbox-instance-store");
+/** Destructured accessors: `getSandboxInstanceStore` / `provideSandboxInstanceStore`. */
+var [getSandboxInstanceStore, provideSandboxInstanceStore] = SandboxInstanceStoreCapability;
+/** In-memory {@link SandboxInstanceStore}. Resume works only within one process. */
+var InMemorySandboxInstanceStore = class {
+	map = /* @__PURE__ */ new Map();
+	get(key) {
+		return Promise.resolve(this.map.get(key) ?? null);
+	}
+	upsert(record) {
+		this.map.set(record.key, record);
+		return Promise.resolve();
+	}
+	delete(key) {
+		this.map.delete(key);
+		return Promise.resolve();
+	}
+};
+/**
+* Wiring note: hand the store straight to the consumer —
+* `withSandbox(sandbox, { instances: store })`. That cannot be mis-ordered,
+* unlike a separate provider middleware composed after `withSandbox` (which
+* silently degrades to the in-memory fallback).
+*
+* ```ts
+* middleware: [
+*   withLocks(locks), // from @tanstack/ai/locks — multi-replica
+*   withSandbox(sandbox, { instances: instanceStore }),
+* ]
+* ```
+*
+* For ambient/platform wiring (a hosting layer injecting infra without touching
+* the call site), any middleware may still
+* `provideSandboxInstanceStore(ctx, store)` on the capability bus; an explicit
+* option takes precedence over it.
+*/
+//#endregion
+export { InMemorySandboxInstanceStore, SandboxInstanceStoreCapability, defineSandboxInstanceStore, getSandboxInstanceStore, provideSandboxInstanceStore };
+
+//# sourceMappingURL=instance-store.js.map

package/dist/esm/instance-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-store.js","names":[],"sources":["../../src/instance-store.ts"],"sourcesContent":["/**\n * Durable sandbox **instance** map — which provider sandbox (and snapshot) to\n * resume for a compound key. Owned by `@tanstack/ai-sandbox` (not chat\n * persistence): domain is runtime placement for `ensure`, not conversation state.\n *\n * Pass to `withSandbox(sandbox, { instances })`, which uses it in `ensure`\n * (in-memory fallback when absent). {@link SandboxInstanceStoreCapability} is\n * the ambient alternative for platform-level wiring.\n */\nimport { createCapability } from '@tanstack/ai'\n\n/** One persisted sandbox instance, keyed by the compound sandbox instance key. */\nexport interface SandboxInstanceRecord {\n  /** Compound key (see `computeSandboxKey`). */\n  key: string\n  /** Provider name that owns `providerSandboxId`. */\n  provider: string\n  /** Provider-assigned sandbox id used to resume. */\n  providerSandboxId: string\n  /** Most recent snapshot id, when the provider supports snapshots. */\n  latestSnapshotId?: string\n  threadId: string\n  latestRunId?: string\n  /**\n   * Epoch ms of last write (for keepAlive / GC by the host app).\n   */\n  updatedAt: number\n}\n\n/**\n * Maps a compound key to the provider sandbox that should be resumed.\n *\n * Implement against your own database (BYO). Prove the contract with\n * `runSandboxInstanceStoreConformance` from `@tanstack/ai-sandbox/testkit`.\n */\nexport interface SandboxInstanceStore {\n  /**\n   * Return the record for `key`, or `null` if none exists.\n   *\n   * INVARIANT: missing keys return `null` (never throw).\n   */\n  get: (key: string) => Promise<SandboxInstanceRecord | null>\n  /**\n   * Insert or fully replace the record for `record.key`.\n   *\n   * INVARIANT (full replace): omitted optional fields (`latestSnapshotId`,\n   * `latestRunId`) MUST clear any previously stored values. Do not merge with\n   * the prior row — a create-without-snapshot path must not leave a stale\n   * snapshot id.\n   */\n  upsert: (record: SandboxInstanceRecord) => Promise<void>\n  /**\n   * Remove the record for `key`.\n   *\n   * INVARIANT: deleting a missing key is a **no-op** (must not throw).\n   */\n  delete: (key: string) => Promise<void>\n}\n\n/**\n * Type a {@link SandboxInstanceStore} implementation inline: pass the object and\n * get autocomplete + contract checking, with no separate\n * `: SandboxInstanceStore` annotation. Hand the result to\n * `withSandbox(sandbox, { instances })`. Matches `defineLock` /\n * `defineMessageStore` style helpers elsewhere in the monorepo.\n */\nexport function defineSandboxInstanceStore(\n  store: SandboxInstanceStore,\n): SandboxInstanceStore {\n  return store\n}\n\n/**\n * Capability for the instance map — the ambient alternative to\n * `withSandbox(sandbox, { instances })`. Provide it from any middleware with\n * {@link provideSandboxInstanceStore}; `withSandbox` reads it when no explicit\n * option was passed.\n */\nexport const SandboxInstanceStoreCapability =\n  createCapability<SandboxInstanceStore>()('sandbox-instance-store')\n\n/** Destructured accessors: `getSandboxInstanceStore` / `provideSandboxInstanceStore`. */\nexport const [getSandboxInstanceStore, provideSandboxInstanceStore] =\n  SandboxInstanceStoreCapability\n\n/** In-memory {@link SandboxInstanceStore}. Resume works only within one process. */\nexport class InMemorySandboxInstanceStore implements SandboxInstanceStore {\n  private readonly map = new Map<string, SandboxInstanceRecord>()\n\n  get(key: string): Promise<SandboxInstanceRecord | null> {\n    return Promise.resolve(this.map.get(key) ?? null)\n  }\n\n  upsert(record: SandboxInstanceRecord): Promise<void> {\n    this.map.set(record.key, record)\n    return Promise.resolve()\n  }\n\n  delete(key: string): Promise<void> {\n    this.map.delete(key)\n    return Promise.resolve()\n  }\n}\n\n/**\n * Wiring note: hand the store straight to the consumer —\n * `withSandbox(sandbox, { instances: store })`. That cannot be mis-ordered,\n * unlike a separate provider middleware composed after `withSandbox` (which\n * silently degrades to the in-memory fallback).\n *\n * ```ts\n * middleware: [\n *   withLocks(locks), // from @tanstack/ai/locks — multi-replica\n *   withSandbox(sandbox, { instances: instanceStore }),\n * ]\n * ```\n *\n * For ambient/platform wiring (a hosting layer injecting infra without touching\n * the call site), any middleware may still\n * `provideSandboxInstanceStore(ctx, store)` on the capability bus; an explicit\n * option takes precedence over it.\n */\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkEA,SAAgB,2BACd,OACsB;CACtB,OAAO;AACT;;;;;;;AAQA,IAAa,iCACX,iBAAuC,CAAC,CAAC,wBAAwB;;AAGnE,IAAa,CAAC,yBAAyB,+BACrC;;AAGF,IAAa,+BAAb,MAA0E;CACxE,sBAAuB,IAAI,IAAmC;CAE9D,IAAI,KAAoD;EACtD,OAAO,QAAQ,QAAQ,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI;CAClD;CAEA,OAAO,QAA8C;EACnD,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM;EAC/B,OAAO,QAAQ,QAAQ;CACzB;CAEA,OAAO,KAA4B;EACjC,KAAK,IAAI,OAAO,GAAG;EACnB,OAAO,QAAQ,QAAQ;CACzB;AACF"}

package/dist/esm/journal-bytes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Byte-exact framing for journal reads.
+ *
+ * Both read paths end in {@link toJournalLines}, which counts absolute file
+ * offsets over BYTES, because a position is only useful if `tail -c +N` can
+ * resume from it. The two paths differ only in how they get bytes:
+ *
+ * - The **bounded** read is base64-framed (see `journal.ts` rule 2) and arrives
+ *   as one complete `ExecResult.stdout` string, so {@link decodeBase64Stream}
+ *   recovers the file's exact bytes regardless of how the provider decoded its
+ *   stdout.
+ * - The **follow** read cannot be base64-framed — the encoder's stdio buffer
+ *   would swallow the stream — so it arrives as provider-decoded text chunks
+ *   and {@link encodeUtf8Stream} turns them back into bytes.
+ *
+ * `atob`, not `Buffer`: this module runs on the host, and the host can itself be
+ * a Cloudflare Worker (`ai-sandbox-cloudflare` drives its sandbox over Workers
+ * RPC from Worker code), where `Buffer` is not a global unless the `nodejs_compat`
+ * flag is on. `atob` is a Web/DOM API available in every host runtime this
+ * package targets, so it is the portable choice here.
+ */
+/**
+ * Decode a streaming base64 frame into raw bytes.
+ *
+ * Whitespace is stripped because `base64(1)` wraps at 76 columns by default and
+ * busybox's build does not accept `-w 0`, so the wrapping cannot be turned off
+ * portably. Only complete 4-character quanta are decoded; a remainder is held
+ * for the next chunk. Padding (`=`) appears only in the final quantum, so an
+ * intermediate group always decodes to exactly 3 bytes.
+ */
+export declare function decodeBase64Stream(chunks: AsyncIterable<string>): AsyncIterable<Uint8Array>;
+/**
+ * Re-encode provider-decoded text chunks as UTF-8 bytes.
+ *
+ * This is the follow path's replacement for {@link decodeBase64Stream}: the
+ * follow command emits the journal's raw bytes, the provider hands them over as
+ * `AsyncIterable<string>`, and `TextEncoder` round-trips that text back to the
+ * bytes it was decoded from. Chunk boundaries do not need to fall on character
+ * boundaries here — {@link toJournalLines} buffers bytes until a newline, so a
+ * multi-byte character split across two chunks is reassembled there, exactly as
+ * it is on the base64 path.
+ *
+ * Empty chunks are dropped rather than forwarded: a zero-length `Uint8Array`
+ * carries no bytes and would only make the downstream loop spin.
+ */
+export declare function encodeUtf8Stream(chunks: AsyncIterable<string>): AsyncIterable<Uint8Array>;
+/** One complete journal line plus the absolute byte position just past its newline. */
+export interface JournalLine {
+    /** The line's text, newline excluded. */
+    line: string;
+    /**
+     * Absolute byte offset immediately AFTER this line's newline — i.e. the count
+     * of journal bytes fully consumed once this line has been handled, and
+     * therefore the exact value to resume a `tail -c +N` from.
+     */
+    endPosition: number;
+}
+/**
+ * Split a byte stream into newline-terminated lines, tracking absolute
+ * positions from `startPosition`.
+ *
+ * Deliberately unlike `toLines` in `runner.ts`, which yields a trailing
+ * unterminated line: here a trailing partial line is a line the agent is still
+ * writing. Yielding it would hand a truncated JSON string downstream AND
+ * advance the position past bytes the next read must re-see.
+ */
+export declare function toJournalLines(byteChunks: AsyncIterable<Uint8Array>, startPosition: number): AsyncIterable<JournalLine>;

package/dist/esm/journal-bytes.js

@@ -0,0 +1,110 @@
+//#region src/journal-bytes.ts
+/**
+* Byte-exact framing for journal reads.
+*
+* Both read paths end in {@link toJournalLines}, which counts absolute file
+* offsets over BYTES, because a position is only useful if `tail -c +N` can
+* resume from it. The two paths differ only in how they get bytes:
+*
+* - The **bounded** read is base64-framed (see `journal.ts` rule 2) and arrives
+*   as one complete `ExecResult.stdout` string, so {@link decodeBase64Stream}
+*   recovers the file's exact bytes regardless of how the provider decoded its
+*   stdout.
+* - The **follow** read cannot be base64-framed — the encoder's stdio buffer
+*   would swallow the stream — so it arrives as provider-decoded text chunks
+*   and {@link encodeUtf8Stream} turns them back into bytes.
+*
+* `atob`, not `Buffer`: this module runs on the host, and the host can itself be
+* a Cloudflare Worker (`ai-sandbox-cloudflare` drives its sandbox over Workers
+* RPC from Worker code), where `Buffer` is not a global unless the `nodejs_compat`
+* flag is on. `atob` is a Web/DOM API available in every host runtime this
+* package targets, so it is the portable choice here.
+*/
+var NEWLINE = 10;
+/** Decode one complete base64 quantum group to bytes. */
+function decodeQuantumGroup(group) {
+	const binary = atob(group);
+	const out = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) out[index] = binary.charCodeAt(index);
+	return out;
+}
+/**
+* Decode a streaming base64 frame into raw bytes.
+*
+* Whitespace is stripped because `base64(1)` wraps at 76 columns by default and
+* busybox's build does not accept `-w 0`, so the wrapping cannot be turned off
+* portably. Only complete 4-character quanta are decoded; a remainder is held
+* for the next chunk. Padding (`=`) appears only in the final quantum, so an
+* intermediate group always decodes to exactly 3 bytes.
+*/
+async function* decodeBase64Stream(chunks) {
+	let pending = "";
+	for await (const chunk of chunks) {
+		pending += chunk.replace(/\s+/g, "");
+		const usable = pending.length - pending.length % 4;
+		if (usable === 0) continue;
+		const group = pending.slice(0, usable);
+		pending = pending.slice(usable);
+		yield decodeQuantumGroup(group);
+	}
+	if (pending.length > 0) throw new Error(`journal: base64 frame ended mid-quantum with ${pending.length} character(s) pending`);
+}
+/**
+* Re-encode provider-decoded text chunks as UTF-8 bytes.
+*
+* This is the follow path's replacement for {@link decodeBase64Stream}: the
+* follow command emits the journal's raw bytes, the provider hands them over as
+* `AsyncIterable<string>`, and `TextEncoder` round-trips that text back to the
+* bytes it was decoded from. Chunk boundaries do not need to fall on character
+* boundaries here — {@link toJournalLines} buffers bytes until a newline, so a
+* multi-byte character split across two chunks is reassembled there, exactly as
+* it is on the base64 path.
+*
+* Empty chunks are dropped rather than forwarded: a zero-length `Uint8Array`
+* carries no bytes and would only make the downstream loop spin.
+*/
+async function* encodeUtf8Stream(chunks) {
+	const encoder = new TextEncoder();
+	for await (const chunk of chunks) {
+		if (chunk.length === 0) continue;
+		yield encoder.encode(chunk);
+	}
+}
+function concatBytes(left, right) {
+	const out = new Uint8Array(left.length + right.length);
+	out.set(left, 0);
+	out.set(right, left.length);
+	return out;
+}
+/**
+* Split a byte stream into newline-terminated lines, tracking absolute
+* positions from `startPosition`.
+*
+* Deliberately unlike `toLines` in `runner.ts`, which yields a trailing
+* unterminated line: here a trailing partial line is a line the agent is still
+* writing. Yielding it would hand a truncated JSON string downstream AND
+* advance the position past bytes the next read must re-see.
+*/
+async function* toJournalLines(byteChunks, startPosition) {
+	const decoder = new TextDecoder();
+	let buffer = /* @__PURE__ */ new Uint8Array(0);
+	let position = startPosition;
+	for await (const bytes of byteChunks) {
+		buffer = concatBytes(buffer, bytes);
+		let newline = buffer.indexOf(NEWLINE);
+		while (newline !== -1) {
+			const lineBytes = buffer.subarray(0, newline);
+			position += newline + 1;
+			yield {
+				line: decoder.decode(lineBytes),
+				endPosition: position
+			};
+			buffer = buffer.slice(newline + 1);
+			newline = buffer.indexOf(NEWLINE);
+		}
+	}
+}
+//#endregion
+export { decodeBase64Stream, encodeUtf8Stream, toJournalLines };
+
+//# sourceMappingURL=journal-bytes.js.map

package/dist/esm/journal-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-bytes.js","names":[],"sources":["../../src/journal-bytes.ts"],"sourcesContent":["/**\n * Byte-exact framing for journal reads.\n *\n * Both read paths end in {@link toJournalLines}, which counts absolute file\n * offsets over BYTES, because a position is only useful if `tail -c +N` can\n * resume from it. The two paths differ only in how they get bytes:\n *\n * - The **bounded** read is base64-framed (see `journal.ts` rule 2) and arrives\n *   as one complete `ExecResult.stdout` string, so {@link decodeBase64Stream}\n *   recovers the file's exact bytes regardless of how the provider decoded its\n *   stdout.\n * - The **follow** read cannot be base64-framed — the encoder's stdio buffer\n *   would swallow the stream — so it arrives as provider-decoded text chunks\n *   and {@link encodeUtf8Stream} turns them back into bytes.\n *\n * `atob`, not `Buffer`: this module runs on the host, and the host can itself be\n * a Cloudflare Worker (`ai-sandbox-cloudflare` drives its sandbox over Workers\n * RPC from Worker code), where `Buffer` is not a global unless the `nodejs_compat`\n * flag is on. `atob` is a Web/DOM API available in every host runtime this\n * package targets, so it is the portable choice here.\n */\n\nconst NEWLINE = 0x0a\n\n/** Decode one complete base64 quantum group to bytes. */\nfunction decodeQuantumGroup(group: string): Uint8Array {\n  const binary = atob(group)\n  const out = new Uint8Array(binary.length)\n  for (let index = 0; index < binary.length; index += 1) {\n    out[index] = binary.charCodeAt(index)\n  }\n  return out\n}\n\n/**\n * Decode a streaming base64 frame into raw bytes.\n *\n * Whitespace is stripped because `base64(1)` wraps at 76 columns by default and\n * busybox's build does not accept `-w 0`, so the wrapping cannot be turned off\n * portably. Only complete 4-character quanta are decoded; a remainder is held\n * for the next chunk. Padding (`=`) appears only in the final quantum, so an\n * intermediate group always decodes to exactly 3 bytes.\n */\nexport async function* decodeBase64Stream(\n  chunks: AsyncIterable<string>,\n): AsyncIterable<Uint8Array> {\n  let pending = ''\n  for await (const chunk of chunks) {\n    pending += chunk.replace(/\\s+/g, '')\n    const usable = pending.length - (pending.length % 4)\n    if (usable === 0) continue\n    const group = pending.slice(0, usable)\n    pending = pending.slice(usable)\n    yield decodeQuantumGroup(group)\n  }\n  if (pending.length > 0) {\n    // Fail loud. A remainder means the frame was cut off mid-quantum, i.e. the\n    // reader died partway through. Rounding it away would silently drop journal\n    // bytes and desync every position derived from this stream.\n    throw new Error(\n      `journal: base64 frame ended mid-quantum with ${pending.length} character(s) pending`,\n    )\n  }\n}\n\n/**\n * Re-encode provider-decoded text chunks as UTF-8 bytes.\n *\n * This is the follow path's replacement for {@link decodeBase64Stream}: the\n * follow command emits the journal's raw bytes, the provider hands them over as\n * `AsyncIterable<string>`, and `TextEncoder` round-trips that text back to the\n * bytes it was decoded from. Chunk boundaries do not need to fall on character\n * boundaries here — {@link toJournalLines} buffers bytes until a newline, so a\n * multi-byte character split across two chunks is reassembled there, exactly as\n * it is on the base64 path.\n *\n * Empty chunks are dropped rather than forwarded: a zero-length `Uint8Array`\n * carries no bytes and would only make the downstream loop spin.\n */\nexport async function* encodeUtf8Stream(\n  chunks: AsyncIterable<string>,\n): AsyncIterable<Uint8Array> {\n  const encoder = new TextEncoder()\n  for await (const chunk of chunks) {\n    if (chunk.length === 0) continue\n    yield encoder.encode(chunk)\n  }\n}\n\n/** One complete journal line plus the absolute byte position just past its newline. */\nexport interface JournalLine {\n  /** The line's text, newline excluded. */\n  line: string\n  /**\n   * Absolute byte offset immediately AFTER this line's newline — i.e. the count\n   * of journal bytes fully consumed once this line has been handled, and\n   * therefore the exact value to resume a `tail -c +N` from.\n   */\n  endPosition: number\n}\n\nfunction concatBytes(left: Uint8Array, right: Uint8Array): Uint8Array {\n  const out = new Uint8Array(left.length + right.length)\n  out.set(left, 0)\n  out.set(right, left.length)\n  return out\n}\n\n/**\n * Split a byte stream into newline-terminated lines, tracking absolute\n * positions from `startPosition`.\n *\n * Deliberately unlike `toLines` in `runner.ts`, which yields a trailing\n * unterminated line: here a trailing partial line is a line the agent is still\n * writing. Yielding it would hand a truncated JSON string downstream AND\n * advance the position past bytes the next read must re-see.\n */\nexport async function* toJournalLines(\n  byteChunks: AsyncIterable<Uint8Array>,\n  startPosition: number,\n): AsyncIterable<JournalLine> {\n  const decoder = new TextDecoder()\n  let buffer: Uint8Array = new Uint8Array(0)\n  let position = startPosition\n  for await (const bytes of byteChunks) {\n    buffer = concatBytes(buffer, bytes)\n    let newline = buffer.indexOf(NEWLINE)\n    while (newline !== -1) {\n      const lineBytes = buffer.subarray(0, newline)\n      position += newline + 1\n      yield { line: decoder.decode(lineBytes), endPosition: position }\n      buffer = buffer.slice(newline + 1)\n      newline = buffer.indexOf(NEWLINE)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,IAAM,UAAU;;AAGhB,SAAS,mBAAmB,OAA2B;CACrD,MAAM,SAAS,KAAK,KAAK;CACzB,MAAM,MAAM,IAAI,WAAW,OAAO,MAAM;CACxC,KAAK,IAAI,QAAQ,GAAG,QAAQ,OAAO,QAAQ,SAAS,GAClD,IAAI,SAAS,OAAO,WAAW,KAAK;CAEtC,OAAO;AACT;;;;;;;;;;AAWA,gBAAuB,mBACrB,QAC2B;CAC3B,IAAI,UAAU;CACd,WAAW,MAAM,SAAS,QAAQ;EAChC,WAAW,MAAM,QAAQ,QAAQ,EAAE;EACnC,MAAM,SAAS,QAAQ,SAAU,QAAQ,SAAS;EAClD,IAAI,WAAW,GAAG;EAClB,MAAM,QAAQ,QAAQ,MAAM,GAAG,MAAM;EACrC,UAAU,QAAQ,MAAM,MAAM;EAC9B,MAAM,mBAAmB,KAAK;CAChC;CACA,IAAI,QAAQ,SAAS,GAInB,MAAM,IAAI,MACR,gDAAgD,QAAQ,OAAO,sBACjE;AAEJ;;;;;;;;;;;;;;;AAgBA,gBAAuB,iBACrB,QAC2B;CAC3B,MAAM,UAAU,IAAI,YAAY;CAChC,WAAW,MAAM,SAAS,QAAQ;EAChC,IAAI,MAAM,WAAW,GAAG;EACxB,MAAM,QAAQ,OAAO,KAAK;CAC5B;AACF;AAcA,SAAS,YAAY,MAAkB,OAA+B;CACpE,MAAM,MAAM,IAAI,WAAW,KAAK,SAAS,MAAM,MAAM;CACrD,IAAI,IAAI,MAAM,CAAC;CACf,IAAI,IAAI,OAAO,KAAK,MAAM;CAC1B,OAAO;AACT;;;;;;;;;;AAWA,gBAAuB,eACrB,YACA,eAC4B;CAC5B,MAAM,UAAU,IAAI,YAAY;CAChC,IAAI,yBAAqB,IAAI,WAAW,CAAC;CACzC,IAAI,WAAW;CACf,WAAW,MAAM,SAAS,YAAY;EACpC,SAAS,YAAY,QAAQ,KAAK;EAClC,IAAI,UAAU,OAAO,QAAQ,OAAO;EACpC,OAAO,YAAY,IAAI;GACrB,MAAM,YAAY,OAAO,SAAS,GAAG,OAAO;GAC5C,YAAY,UAAU;GACtB,MAAM;IAAE,MAAM,QAAQ,OAAO,SAAS;IAAG,aAAa;GAAS;GAC/D,SAAS,OAAO,MAAM,UAAU,CAAC;GACjC,UAAU,OAAO,QAAQ,OAAO;EAClC;CACF;AACF"}

package/dist/esm/journal-reader.d.ts

@@ -0,0 +1,66 @@
+import { JournalPaths } from './journal.js';
+import { JournalLine } from './journal-bytes.js';
+import { SandboxHandle } from './contracts.js';
+/**
+ * Poll interval for the bounded-`exec` strategy. Matches the interval
+ * `ai-sandbox-cloudflare`'s run-log Durable Object already uses, so the two
+ * readers have the same latency profile.
+ */
+export declare const DEFAULT_JOURNAL_POLL_MS = 250;
+export interface ReadJournalOptions {
+    paths: JournalPaths;
+    /**
+     * Count of journal bytes already consumed. The read starts at the next byte.
+     * Defaults to 0, which is also what a takeover uses: the alignment step, not
+     * the reader, decides what has already been delivered.
+     */
+    fromByte?: number;
+    /** Stop reading. On the follow strategy this also kills the `tail`. */
+    signal?: AbortSignal;
+    /** Override the capability-derived strategy. Tests and diagnostics only. */
+    strategy?: 'follow' | 'poll';
+    /** Poll strategy only. Defaults to {@link DEFAULT_JOURNAL_POLL_MS}. */
+    pollIntervalMs?: number;
+    /** Working directory for the read command. Paths are absolute, so rarely needed. */
+    cwd?: string;
+    /**
+     * How long to wait for the FIRST byte of the journal before failing with
+     * `'journal-stalled'`. Defaults to {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} — the
+     * same number that bounds the attach preflight, because it bounds the same
+     * question from the other side. `0` or a non-finite value disables the bound;
+     * do that only where some OTHER deadline already covers the read, since an
+     * unbounded read of an empty journal never returns.
+     *
+     * Only the first byte is bounded. An agent that streams slowly is never cut
+     * off.
+     */
+    firstByteTimeoutMs?: number;
+    /**
+     * Run id, for the stall error's message only. Defaults to naming the journal
+     * path, which is always available and always identifies the run uniquely.
+     */
+    runId?: string;
+}
+/**
+ * Which read strategy a provider supports.
+ *
+ * Keyed on capabilities, never on `handle.provider`: a BYO provider with the
+ * same limitation must get the same treatment, and name-sniffing would silently
+ * hand it an unstoppable `tail -f`.
+ */
+export declare function journalReadStrategy(handle: SandboxHandle): 'follow' | 'poll';
+/**
+ * Read a run's journal as positioned lines.
+ *
+ * **This is a public entry point and it CANNOT hang.** It has no `RunStore` in
+ * its signature and no runId to look one up with, so it cannot run the
+ * `attach-preflight.ts` gate that classifies a stale or mistyped runId as
+ * `'unknown-run'`/`'terminal-run'`; what it has instead is the unconditional
+ * bound described in the module doc. A runId with no journal therefore fails with
+ * {@link JournalAttachUnavailableError} (`reason: 'journal-stalled'`) after
+ * {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} rather than tailing an empty file it
+ * just created, for ever, with no error and no log line. Callers that DO have a
+ * store — `runner.ts` on an attach — run the preflight as well, for the sharper
+ * diagnosis.
+ */
+export declare function readJournal(handle: SandboxHandle, options: ReadJournalOptions): AsyncIterable<JournalLine>;

package/dist/esm/journal-reader.js

@@ -0,0 +1,228 @@
+import { journalFollowCommand, journalReadCommand } from "./journal.js";
+import { JournalAttachUnavailableError } from "./attach-preflight.js";
+import { decodeBase64Stream, encodeUtf8Stream, toJournalLines } from "./journal-bytes.js";
+//#region src/journal-reader.ts
+/**
+* Read a run's journal, live or after the fact, on one code path.
+*
+* Resume is not a special case: every read is `tail -c +N` for some N, and a
+* fresh run is simply N = 0. That is deliberate — `pid` is `-1` on five of six
+* providers, so re-attaching to an existing reader is impossible and a resumed
+* read always spawns a new `tail` anyway.
+*
+* Two strategies, chosen by capability rather than by provider name:
+*
+* - **follow** (`spawn` + `tail -f`): the default. Streams with no polling cost
+*   and is killed when the consumer stops. Its command pipes into nothing — see
+*   `journal.ts` rule 2 — so this path re-encodes the provider's decoded text
+*   rather than decoding a base64 frame.
+* - **poll** (bounded `exec`, no `-f`): for a provider whose spawned process
+*   cannot be stopped. Cloudflare's `kill()` is a documented no-op and it
+*   forwards the AbortSignal to neither `exec` nor `spawn`, so a `tail -f`
+*   there would run forever inside the container. Every poll command terminates
+*   on its own, so nothing needs killing.
+*
+* **Neither strategy may wait forever for its FIRST byte.** This is the bound
+* that used to be missing, and its absence was reachable three ways, one of them
+* self-inflicted:
+*
+* 1. `journalFollowCommand` CREATES the journal before tailing it (`: >> file`),
+*    which it must, so a read for a runId whose journal never existed
+*    manufactures an empty file and tails it forever. The attach preflight
+*    (`attach-preflight.ts`) catches most of those, but it is wired at exactly
+*    one call site and only for `attach === true` — the exported
+*    {@link readJournal} that `docs/sandbox/journal.md` tells users to write has
+*    no preflight, no store, and no runId to look one up with.
+* 2. The preflight's own probe can be unusable, and it deliberately falls through
+*    to a bounded wait rather than skipping; a journal that exists but is
+*    abandoned still reaches the reader.
+* 3. SIGKILL/OOM of the agent's shell between its last line and its sentinel
+*    `printf` leaves a real, non-empty, permanently-silent journal.
+*
+* So a read that receives NO bytes within {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS}
+* raises {@link JournalAttachUnavailableError} with reason `'journal-stalled'`
+* instead of parking. The bound is on the FIRST byte only, deliberately: once the
+* journal is producing, how long the agent thinks between lines is the agent's
+* business and no deadline here may cut a healthy run short. A consumer abort is
+* not a stall — it ends the read quietly, as it always did.
+*/
+/**
+* Poll interval for the bounded-`exec` strategy. Matches the interval
+* `ai-sandbox-cloudflare`'s run-log Durable Object already uses, so the two
+* readers have the same latency profile.
+*/
+var DEFAULT_JOURNAL_POLL_MS = 250;
+/**
+* Which read strategy a provider supports.
+*
+* Keyed on capabilities, never on `handle.provider`: a BYO provider with the
+* same limitation must get the same treatment, and name-sniffing would silently
+* hand it an unstoppable `tail -f`.
+*/
+function journalReadStrategy(handle) {
+	const { backgroundProcesses, killableProcesses } = handle.capabilities;
+	return backgroundProcesses && killableProcesses ? "follow" : "poll";
+}
+function processOptions(options) {
+	return {
+		...options.cwd === void 0 ? {} : { cwd: options.cwd },
+		...options.signal === void 0 ? {} : { signal: options.signal }
+	};
+}
+/** Resolution of the abort race in {@link untilAborted}. Never a stream value. */
+var ABORTED = Symbol("journal-read-aborted");
+/**
+* Iterate `source` but stop the moment `signal` fires, instead of waiting for
+* the stream to close.
+*
+* Without this, aborting a follow read only *asks* the provider to kill `tail`
+* and then blocks on `stdout` until that kill closes the pipe — which is not a
+* guarantee any provider makes. On local-process/Windows, `killTree` falls back
+* to signalling only the `sh` wrapper if `taskkill` is unavailable, leaving the
+* `tail` grandchild holding the stdout pipe open, and the read rides past its
+* own AbortSignal until some outer timeout fires. The signal is the caller's
+* contract with the reader, so the reader honors it itself and treats the kill
+* as best-effort cleanup. (local-process now also verifies the tree is gone and
+* sweeps the MSYS grandchildren `taskkill /T` cannot reach, but that is a
+* provider improving its best effort — not a guarantee this reader may assume of
+* any provider.)
+*/
+async function* untilAborted(source, signal) {
+	if (!signal) {
+		yield* source;
+		return;
+	}
+	if (signal.aborted) return;
+	let onAbort;
+	const aborted = new Promise((resolve) => {
+		onAbort = () => resolve(ABORTED);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	const iterator = source[Symbol.asyncIterator]();
+	try {
+		for (;;) {
+			const next = await Promise.race([iterator.next(), aborted]);
+			if (next === ABORTED || next.done === true) return;
+			yield next.value;
+		}
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+		iterator.return?.().catch(() => {});
+	}
+}
+/** Resolution of the first-byte race in {@link withFirstByteDeadline}. */
+var STALLED = Symbol("journal-read-stalled");
+/** The bound in effect for a read; `undefined` when the caller disabled it. */
+function firstByteTimeout(options) {
+	const ms = options.firstByteTimeoutMs ?? 1e4;
+	return Number.isFinite(ms) && ms > 0 ? ms : void 0;
+}
+/**
+* The `'journal-stalled'` failure, shared by both strategies so the two report
+* the same diagnosis for the same state.
+*/
+function stalled(options, timeoutMs) {
+	return new JournalAttachUnavailableError(options.runId ?? options.paths.journal, "journal-stalled", `its journal (${options.paths.journal}) delivered no bytes within ${timeoutMs}ms. The file exists but nothing is appending to it and no '__exit' sentinel can arrive, so following it would never return: either the read created it itself (a runId with no journal), or the agent's shell was killed before it could write its sentinel.`);
+}
+/**
+* Pass `source` through unchanged, except that receiving NO value within
+* `timeoutMs` throws.
+*
+* Only the first value is raced. After it, the source is iterated directly, so a
+* long gap between later values costs nothing and cannot fail a healthy read.
+*
+* A source that simply ENDS before the deadline is not a stall — that is the
+* consumer's abort (`untilAborted` returns on abort) or a `tail` that exited —
+* and it returns quietly, preserving the "an abort diagnoses nothing" rule.
+*/
+async function* withFirstByteDeadline(source, timeoutMs, onStall) {
+	if (timeoutMs === void 0) {
+		yield* source;
+		return;
+	}
+	const iterator = source[Symbol.asyncIterator]();
+	let timer;
+	const expired = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(STALLED), timeoutMs);
+	});
+	try {
+		const first = await Promise.race([iterator.next(), expired]);
+		if (first === STALLED) throw onStall();
+		if (first.done === true) return;
+		yield first.value;
+		for (;;) {
+			const next = await iterator.next();
+			if (next.done === true) return;
+			yield next.value;
+		}
+	} finally {
+		clearTimeout(timer);
+		iterator.return?.().catch(() => {});
+	}
+}
+async function* followJournal(handle, options) {
+	const fromByte = options.fromByte ?? 0;
+	const proc = await handle.process.spawn(journalFollowCommand(options.paths, fromByte), processOptions(options));
+	const timeoutMs = firstByteTimeout(options);
+	try {
+		yield* toJournalLines(encodeUtf8Stream(withFirstByteDeadline(untilAborted(proc.stdout, options.signal), timeoutMs, () => stalled(options, timeoutMs ?? 0))), fromByte);
+	} finally {
+		try {
+			await proc.kill();
+		} catch {}
+	}
+}
+function sleep(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve) => {
+		const timer = setTimeout(finish, ms);
+		function finish() {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		}
+		signal?.addEventListener("abort", finish, { once: true });
+	});
+}
+async function* singleValue(value) {
+	yield value;
+}
+async function* pollJournal(handle, options) {
+	const intervalMs = options.pollIntervalMs ?? 250;
+	const timeoutMs = firstByteTimeout(options);
+	const deadline = timeoutMs === void 0 ? void 0 : Date.now() + timeoutMs;
+	let sawBytes = false;
+	let position = options.fromByte ?? 0;
+	while (!options.signal?.aborted) {
+		const result = await handle.process.exec(journalReadCommand(options.paths, position), processOptions(options));
+		if (result.stdout.trim() !== "") sawBytes = true;
+		if (!sawBytes && deadline !== void 0 && timeoutMs !== void 0 && Date.now() >= deadline) throw stalled(options, timeoutMs);
+		for await (const line of toJournalLines(decodeBase64Stream(singleValue(result.stdout)), position)) {
+			yield line;
+			position = line.endPosition;
+		}
+		if (options.signal?.aborted) return;
+		await sleep(intervalMs, options.signal);
+	}
+}
+/**
+* Read a run's journal as positioned lines.
+*
+* **This is a public entry point and it CANNOT hang.** It has no `RunStore` in
+* its signature and no runId to look one up with, so it cannot run the
+* `attach-preflight.ts` gate that classifies a stale or mistyped runId as
+* `'unknown-run'`/`'terminal-run'`; what it has instead is the unconditional
+* bound described in the module doc. A runId with no journal therefore fails with
+* {@link JournalAttachUnavailableError} (`reason: 'journal-stalled'`) after
+* {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} rather than tailing an empty file it
+* just created, for ever, with no error and no log line. Callers that DO have a
+* store — `runner.ts` on an attach — run the preflight as well, for the sharper
+* diagnosis.
+*/
+function readJournal(handle, options) {
+	return (options.strategy ?? journalReadStrategy(handle)) === "follow" ? followJournal(handle, options) : pollJournal(handle, options);
+}
+//#endregion
+export { DEFAULT_JOURNAL_POLL_MS, journalReadStrategy, readJournal };
+
+//# sourceMappingURL=journal-reader.js.map

package/dist/esm/journal-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-reader.js","names":[],"sources":["../../src/journal-reader.ts"],"sourcesContent":["/**\n * Read a run's journal, live or after the fact, on one code path.\n *\n * Resume is not a special case: every read is `tail -c +N` for some N, and a\n * fresh run is simply N = 0. That is deliberate — `pid` is `-1` on five of six\n * providers, so re-attaching to an existing reader is impossible and a resumed\n * read always spawns a new `tail` anyway.\n *\n * Two strategies, chosen by capability rather than by provider name:\n *\n * - **follow** (`spawn` + `tail -f`): the default. Streams with no polling cost\n *   and is killed when the consumer stops. Its command pipes into nothing — see\n *   `journal.ts` rule 2 — so this path re-encodes the provider's decoded text\n *   rather than decoding a base64 frame.\n * - **poll** (bounded `exec`, no `-f`): for a provider whose spawned process\n *   cannot be stopped. Cloudflare's `kill()` is a documented no-op and it\n *   forwards the AbortSignal to neither `exec` nor `spawn`, so a `tail -f`\n *   there would run forever inside the container. Every poll command terminates\n *   on its own, so nothing needs killing.\n *\n * **Neither strategy may wait forever for its FIRST byte.** This is the bound\n * that used to be missing, and its absence was reachable three ways, one of them\n * self-inflicted:\n *\n * 1. `journalFollowCommand` CREATES the journal before tailing it (`: >> file`),\n *    which it must, so a read for a runId whose journal never existed\n *    manufactures an empty file and tails it forever. The attach preflight\n *    (`attach-preflight.ts`) catches most of those, but it is wired at exactly\n *    one call site and only for `attach === true` — the exported\n *    {@link readJournal} that `docs/sandbox/journal.md` tells users to write has\n *    no preflight, no store, and no runId to look one up with.\n * 2. The preflight's own probe can be unusable, and it deliberately falls through\n *    to a bounded wait rather than skipping; a journal that exists but is\n *    abandoned still reaches the reader.\n * 3. SIGKILL/OOM of the agent's shell between its last line and its sentinel\n *    `printf` leaves a real, non-empty, permanently-silent journal.\n *\n * So a read that receives NO bytes within {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS}\n * raises {@link JournalAttachUnavailableError} with reason `'journal-stalled'`\n * instead of parking. The bound is on the FIRST byte only, deliberately: once the\n * journal is producing, how long the agent thinks between lines is the agent's\n * business and no deadline here may cut a healthy run short. A consumer abort is\n * not a stall — it ends the read quietly, as it always did.\n */\nimport {\n  DEFAULT_ATTACH_JOURNAL_WAIT_MS,\n  JournalAttachUnavailableError,\n} from './attach-preflight'\nimport { journalFollowCommand, journalReadCommand } from './journal'\nimport {\n  decodeBase64Stream,\n  encodeUtf8Stream,\n  toJournalLines,\n} from './journal-bytes'\nimport type { JournalPaths } from './journal'\nimport type { JournalLine } from './journal-bytes'\nimport type { ProcessOptions, SandboxHandle } from './contracts'\n\n/**\n * Poll interval for the bounded-`exec` strategy. Matches the interval\n * `ai-sandbox-cloudflare`'s run-log Durable Object already uses, so the two\n * readers have the same latency profile.\n */\nexport const DEFAULT_JOURNAL_POLL_MS = 250\n\nexport interface ReadJournalOptions {\n  paths: JournalPaths\n  /**\n   * Count of journal bytes already consumed. The read starts at the next byte.\n   * Defaults to 0, which is also what a takeover uses: the alignment step, not\n   * the reader, decides what has already been delivered.\n   */\n  fromByte?: number\n  /** Stop reading. On the follow strategy this also kills the `tail`. */\n  signal?: AbortSignal\n  /** Override the capability-derived strategy. Tests and diagnostics only. */\n  strategy?: 'follow' | 'poll'\n  /** Poll strategy only. Defaults to {@link DEFAULT_JOURNAL_POLL_MS}. */\n  pollIntervalMs?: number\n  /** Working directory for the read command. Paths are absolute, so rarely needed. */\n  cwd?: string\n  /**\n   * How long to wait for the FIRST byte of the journal before failing with\n   * `'journal-stalled'`. Defaults to {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} — the\n   * same number that bounds the attach preflight, because it bounds the same\n   * question from the other side. `0` or a non-finite value disables the bound;\n   * do that only where some OTHER deadline already covers the read, since an\n   * unbounded read of an empty journal never returns.\n   *\n   * Only the first byte is bounded. An agent that streams slowly is never cut\n   * off.\n   */\n  firstByteTimeoutMs?: number\n  /**\n   * Run id, for the stall error's message only. Defaults to naming the journal\n   * path, which is always available and always identifies the run uniquely.\n   */\n  runId?: string\n}\n\n/**\n * Which read strategy a provider supports.\n *\n * Keyed on capabilities, never on `handle.provider`: a BYO provider with the\n * same limitation must get the same treatment, and name-sniffing would silently\n * hand it an unstoppable `tail -f`.\n */\nexport function journalReadStrategy(handle: SandboxHandle): 'follow' | 'poll' {\n  const { backgroundProcesses, killableProcesses } = handle.capabilities\n  return backgroundProcesses && killableProcesses ? 'follow' : 'poll'\n}\n\nfunction processOptions(options: ReadJournalOptions): ProcessOptions {\n  return {\n    ...(options.cwd === undefined ? {} : { cwd: options.cwd }),\n    ...(options.signal === undefined ? {} : { signal: options.signal }),\n  }\n}\n\n/** Resolution of the abort race in {@link untilAborted}. Never a stream value. */\nconst ABORTED = Symbol('journal-read-aborted')\n\n/**\n * Iterate `source` but stop the moment `signal` fires, instead of waiting for\n * the stream to close.\n *\n * Without this, aborting a follow read only *asks* the provider to kill `tail`\n * and then blocks on `stdout` until that kill closes the pipe — which is not a\n * guarantee any provider makes. On local-process/Windows, `killTree` falls back\n * to signalling only the `sh` wrapper if `taskkill` is unavailable, leaving the\n * `tail` grandchild holding the stdout pipe open, and the read rides past its\n * own AbortSignal until some outer timeout fires. The signal is the caller's\n * contract with the reader, so the reader honors it itself and treats the kill\n * as best-effort cleanup. (local-process now also verifies the tree is gone and\n * sweeps the MSYS grandchildren `taskkill /T` cannot reach, but that is a\n * provider improving its best effort — not a guarantee this reader may assume of\n * any provider.)\n */\nasync function* untilAborted<T>(\n  source: AsyncIterable<T>,\n  signal: AbortSignal | undefined,\n): AsyncIterable<T> {\n  if (!signal) {\n    yield* source\n    return\n  }\n  if (signal.aborted) return\n  let onAbort: (() => void) | undefined\n  const aborted = new Promise<typeof ABORTED>((resolve) => {\n    onAbort = () => resolve(ABORTED)\n    signal.addEventListener('abort', onAbort, { once: true })\n  })\n  const iterator = source[Symbol.asyncIterator]()\n  try {\n    for (;;) {\n      const next = await Promise.race([iterator.next(), aborted])\n      if (next === ABORTED || next.done === true) return\n      yield next.value\n    }\n  } finally {\n    if (onAbort) signal.removeEventListener('abort', onAbort)\n    // NOT awaited. On an async generator, `return()` queues behind the pending\n    // `next()` we just abandoned, so awaiting it would block for exactly as\n    // long as the stream we gave up waiting for — reintroducing the hang this\n    // helper exists to remove. The rejection is swallowed for the same reason\n    // `kill` is best-effort below: the source may already be gone.\n    void iterator.return?.().catch(() => {})\n  }\n}\n\n/** Resolution of the first-byte race in {@link withFirstByteDeadline}. */\nconst STALLED = Symbol('journal-read-stalled')\n\n/** The bound in effect for a read; `undefined` when the caller disabled it. */\nfunction firstByteTimeout(options: ReadJournalOptions): number | undefined {\n  const ms = options.firstByteTimeoutMs ?? DEFAULT_ATTACH_JOURNAL_WAIT_MS\n  return Number.isFinite(ms) && ms > 0 ? ms : undefined\n}\n\n/**\n * The `'journal-stalled'` failure, shared by both strategies so the two report\n * the same diagnosis for the same state.\n */\nfunction stalled(\n  options: ReadJournalOptions,\n  timeoutMs: number,\n): JournalAttachUnavailableError {\n  return new JournalAttachUnavailableError(\n    options.runId ?? options.paths.journal,\n    'journal-stalled',\n    `its journal (${options.paths.journal}) delivered no bytes within ${timeoutMs}ms. ` +\n      `The file exists but nothing is appending to it and no '__exit' sentinel can arrive, ` +\n      `so following it would never return: either the read created it itself (a runId with no journal), ` +\n      `or the agent's shell was killed before it could write its sentinel.`,\n  )\n}\n\n/**\n * Pass `source` through unchanged, except that receiving NO value within\n * `timeoutMs` throws.\n *\n * Only the first value is raced. After it, the source is iterated directly, so a\n * long gap between later values costs nothing and cannot fail a healthy read.\n *\n * A source that simply ENDS before the deadline is not a stall — that is the\n * consumer's abort (`untilAborted` returns on abort) or a `tail` that exited —\n * and it returns quietly, preserving the \"an abort diagnoses nothing\" rule.\n */\nasync function* withFirstByteDeadline<T>(\n  source: AsyncIterable<T>,\n  timeoutMs: number | undefined,\n  onStall: () => JournalAttachUnavailableError,\n): AsyncIterable<T> {\n  if (timeoutMs === undefined) {\n    yield* source\n    return\n  }\n  const iterator = source[Symbol.asyncIterator]()\n  let timer: ReturnType<typeof setTimeout> | undefined\n  const expired = new Promise<typeof STALLED>((resolve) => {\n    timer = setTimeout(() => resolve(STALLED), timeoutMs)\n  })\n  try {\n    const first = await Promise.race([iterator.next(), expired])\n    if (first === STALLED) throw onStall()\n    if (first.done === true) return\n    yield first.value\n    for (;;) {\n      const next = await iterator.next()\n      if (next.done === true) return\n      yield next.value\n    }\n  } finally {\n    clearTimeout(timer)\n    // NOT awaited, for the reason `untilAborted` documents: on the stall path the\n    // abandoned `next()` is exactly the promise that never settles, so awaiting\n    // the `return()` queued behind it would reinstate the hang being reported.\n    void iterator.return?.().catch(() => {})\n  }\n}\n\nasync function* followJournal(\n  handle: SandboxHandle,\n  options: ReadJournalOptions,\n): AsyncIterable<JournalLine> {\n  const fromByte = options.fromByte ?? 0\n  const proc = await handle.process.spawn(\n    journalFollowCommand(options.paths, fromByte),\n    processOptions(options),\n  )\n  const timeoutMs = firstByteTimeout(options)\n  try {\n    yield* toJournalLines(\n      encodeUtf8Stream(\n        withFirstByteDeadline(\n          untilAborted(proc.stdout, options.signal),\n          timeoutMs,\n          // Narrowed by `withFirstByteDeadline` only calling this when the bound\n          // is in effect; `?? 0` keeps that provable without an assertion.\n          () => stalled(options, timeoutMs ?? 0),\n        ),\n      ),\n      fromByte,\n    )\n  } finally {\n    // The consumer may stop early (client gone, lease lost). Providers whose\n    // `kill` is real stop the `tail` here; the signal covers the rest. Guarded\n    // because a `finally` that throws would replace the consumer's own reason\n    // for stopping.\n    try {\n      await proc.kill()\n    } catch {\n      // Best effort: the process may already be gone.\n    }\n  }\n}\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  if (ms <= 0) return Promise.resolve()\n  return new Promise<void>((resolve) => {\n    const timer = setTimeout(finish, ms)\n    function finish(): void {\n      clearTimeout(timer)\n      signal?.removeEventListener('abort', finish)\n      resolve()\n    }\n    signal?.addEventListener('abort', finish, { once: true })\n  })\n}\n\nasync function* singleValue(value: string): AsyncIterable<string> {\n  yield value\n}\n\nasync function* pollJournal(\n  handle: SandboxHandle,\n  options: ReadJournalOptions,\n): AsyncIterable<JournalLine> {\n  const intervalMs = options.pollIntervalMs ?? DEFAULT_JOURNAL_POLL_MS\n  const timeoutMs = firstByteTimeout(options)\n  // Same bound as the follow path, expressed the way a polling loop can enforce\n  // it: an empty frame every time until the deadline is a stalled journal, and\n  // parking here forever is the same defect from the other strategy.\n  const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs\n  let sawBytes = false\n  let position = options.fromByte ?? 0\n  while (!options.signal?.aborted) {\n    const result = await handle.process.exec(\n      journalReadCommand(options.paths, position),\n      processOptions(options),\n    )\n    if (result.stdout.trim() !== '') sawBytes = true\n    if (\n      !sawBytes &&\n      deadline !== undefined &&\n      timeoutMs !== undefined &&\n      Date.now() >= deadline\n    ) {\n      throw stalled(options, timeoutMs)\n    }\n    // Each poll re-reads from `position`, so a line left incomplete by the\n    // previous poll is simply re-fetched whole. That is why `position` advances\n    // only on a COMPLETE line: advancing on bytes received would strand a\n    // partial line's prefix and corrupt every following line.\n    for await (const line of toJournalLines(\n      decodeBase64Stream(singleValue(result.stdout)),\n      position,\n    )) {\n      yield line\n      position = line.endPosition\n    }\n    if (options.signal?.aborted) return\n    await sleep(intervalMs, options.signal)\n  }\n}\n\n/**\n * Read a run's journal as positioned lines.\n *\n * **This is a public entry point and it CANNOT hang.** It has no `RunStore` in\n * its signature and no runId to look one up with, so it cannot run the\n * `attach-preflight.ts` gate that classifies a stale or mistyped runId as\n * `'unknown-run'`/`'terminal-run'`; what it has instead is the unconditional\n * bound described in the module doc. A runId with no journal therefore fails with\n * {@link JournalAttachUnavailableError} (`reason: 'journal-stalled'`) after\n * {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} rather than tailing an empty file it\n * just created, for ever, with no error and no log line. Callers that DO have a\n * store — `runner.ts` on an attach — run the preflight as well, for the sharper\n * diagnosis.\n */\nexport function readJournal(\n  handle: SandboxHandle,\n  options: ReadJournalOptions,\n): AsyncIterable<JournalLine> {\n  const strategy = options.strategy ?? journalReadStrategy(handle)\n  return strategy === 'follow'\n    ? followJournal(handle, options)\n    : pollJournal(handle, options)\n}\n"],"mappings":"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"}