@tanstack/ai-sandbox-cloudflare 0.2.4 → 0.3.0

package/dist/esm/public-host.js

@@ -1,49 +1,94 @@
+//#region src/public-host.ts
+/**
+* Host resolution for the two DISTINCT public surfaces the sandbox layer exposes.
+* Kept in its own (Workers-free) module so it stays pure and unit-testable.
+*
+* These were once a single `PUBLIC_HOSTNAME`, but they have different reachers and
+* therefore different correct values:
+*
+*  - **Bridge / tool-exec** — the off-isolate CONTAINER calls back into the Worker
+*    (`/_bridge`, `/tool-exec`). It must reach the Worker, so locally that's
+*    `host.docker.internal` (the container can't reach the host's `localhost`).
+*  - **Preview** — the BROWSER opens an `exposePort` URL that `proxyToSandbox`
+*    routes into the container. It needs WILDCARD DNS, so locally that's
+*    `*.localhost` (browsers resolve it to loopback with zero setup) and in
+*    production a CUSTOM DOMAIN (`*.workers.dev` has no wildcard subdomains).
+*/
+/** Hostnames that mean "this machine" (the loopback the container can't reach). */
 function isLoopbackHost(host) {
-  const name = host.split(":")[0];
-  return name === "localhost" || name === "127.0.0.1" || name === "0.0.0.0";
+	const name = host.split(":")[0];
+	return name === "localhost" || name === "127.0.0.1" || name === "0.0.0.0";
 }
+/** The port portion of a `host[:port]`, or `fallback` when none is present. */
 function portOf(host, fallback) {
-  const colon = host.indexOf(":");
-  return colon === -1 ? fallback : host.slice(colon + 1);
+	const colon = host.indexOf(":");
+	return colon === -1 ? fallback : host.slice(colon + 1);
 }
+/** `http://` for local hosts (loopback / host.docker.internal), `https://` else. */
 function originForHost(host) {
-  const name = host.split(":")[0];
-  const scheme = isLoopbackHost(host) || name === "host.docker.internal" ? "http" : "https";
-  return `${scheme}://${host}`;
+	const name = host.split(":")[0];
+	return `${isLoopbackHost(host) || name === "host.docker.internal" ? "http" : "https"}://${host}`;
 }
+/**
+* Resolve the ORIGIN the off-isolate sandbox CONTAINER uses to call back into the
+* Worker — the MCP tool-bridge (`/_bridge`) and host-tool execution (`/tool-exec`).
+* Returns a full origin (scheme + host + optional port), e.g.
+* `http://host.docker.internal:3001` locally or `https://app.example.com` deployed.
+*
+* `PUBLIC_HOSTNAME` wins when set; otherwise we derive from the host the trigger
+* request arrived on (`input.publicHost`).
+*
+* ── Why a callback hostname is unavoidable ──────────────────────────────────────
+* The container is SEPARATE compute from the Worker isolate; it can only reach the
+* Worker over the network, so the callback URL must be an absolute host.
+*
+* ── Why request-derivation is SAFE on Cloudflare ────────────────────────────────
+* On a generic Node server the `Host` header is attacker-controlled and trusting it
+* is a Host-injection / token-exfil vector (the per-run bearer token rides this
+* URL). Not so behind Cloudflare: the edge dispatches a request to your Worker only
+* when its hostname matches a route you OWN, so `input.publicHost` is always one of
+* your own hostnames — never an attacker's.
+*
+* ── Local dev: localhost → host.docker.internal ─────────────────────────────────
+* Locally the trigger arrives on `localhost`, which the container CANNOT reach
+* (that's the container's own loopback). So we rewrite it to `host.docker.internal`
+* (the Docker host gateway), keeping the port, over `http`. This removes the need
+* for a dev tunnel for the bridge entirely.
+*/
 function resolveBridgeOrigin(env, input) {
-  const configured = env.PUBLIC_HOSTNAME?.trim();
-  if (configured) return originForHost(configured);
-  const host = input.publicHost;
-  if (!host) {
-    throw new Error(
-      "sandbox agent: no bridge host available — set PUBLIC_HOSTNAME, or run behind Cloudflare so the Worker can derive it from the trigger request."
-    );
-  }
-  if (isLoopbackHost(host)) {
-    return `http://host.docker.internal:${portOf(host, "3001")}`;
-  }
-  return originForHost(host);
+	const configured = env.PUBLIC_HOSTNAME?.trim();
+	if (configured) return originForHost(configured);
+	const host = input.publicHost;
+	if (!host) throw new Error("sandbox agent: no bridge host available — set PUBLIC_HOSTNAME, or run behind Cloudflare so the Worker can derive it from the trigger request.");
+	if (isLoopbackHost(host)) return `http://host.docker.internal:${portOf(host, "3001")}`;
+	return originForHost(host);
 }
+/**
+* Resolve the HOST passed to `exposePort` for browser-facing preview URLs (the app
+* the agent builds). Returns a bare host (the `@cloudflare/sandbox` SDK builds the
+* `<port>-<id>-<token>.<host>` URL + scheme itself).
+*
+* `PREVIEW_HOSTNAME` wins when set; otherwise we derive from the trigger request.
+*
+* Preview URLs require WILDCARD DNS, which constrains the value:
+*  - **Local** → `localhost:<port>`. The SDK's localhost path yields
+*    `http://<port>-<id>-<token>.localhost:<port>`, which browsers resolve to
+*    loopback with no DNS setup — so previews work locally with no tunnel.
+*  - **Deployed** → a CUSTOM DOMAIN with a `*.<domain>` route. `*.workers.dev` has
+*    no wildcard subdomains (the SDK's `exposePort` throws on it), so we throw a
+*    clear error pointing at `PREVIEW_HOSTNAME` rather than letting the run fail
+*    deep in the agent.
+*/
 function resolvePreviewHost(env, input) {
-  const configured = env.PREVIEW_HOSTNAME?.trim();
-  if (configured) return configured;
-  const host = input.publicHost;
-  if (!host) {
-    throw new Error(
-      "sandbox agent: no preview host available — set PREVIEW_HOSTNAME to a custom domain with a wildcard route."
-    );
-  }
-  if (isLoopbackHost(host)) return host;
-  if (host.endsWith(".workers.dev")) {
-    throw new Error(
-      "sandbox agent: preview URLs need a custom domain with wildcard DNS — *.workers.dev has no wildcard subdomains. Set PREVIEW_HOSTNAME to your custom domain and add a `*.<domain>` route to the Worker."
-    );
-  }
-  return host;
+	const configured = env.PREVIEW_HOSTNAME?.trim();
+	if (configured) return configured;
+	const host = input.publicHost;
+	if (!host) throw new Error("sandbox agent: no preview host available — set PREVIEW_HOSTNAME to a custom domain with a wildcard route.");
+	if (isLoopbackHost(host)) return host;
+	if (host.endsWith(".workers.dev")) throw new Error("sandbox agent: preview URLs need a custom domain with wildcard DNS — *.workers.dev has no wildcard subdomains. Set PREVIEW_HOSTNAME to your custom domain and add a `*.<domain>` route to the Worker.");
+	return host;
 }
-export {
-  resolveBridgeOrigin,
-  resolvePreviewHost
-};
-//# sourceMappingURL=public-host.js.map
+//#endregion
+export { resolveBridgeOrigin, resolvePreviewHost };
+
+//# sourceMappingURL=public-host.js.map

package/dist/esm/public-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-host.js","sources":["../../src/public-host.ts"],"sourcesContent":["/**\n * Host resolution for the two DISTINCT public surfaces the sandbox layer exposes.\n * Kept in its own (Workers-free) module so it stays pure and unit-testable.\n *\n * These were once a single `PUBLIC_HOSTNAME`, but they have different reachers and\n * therefore different correct values:\n *\n *  - **Bridge / tool-exec** — the off-isolate CONTAINER calls back into the Worker\n *    (`/_bridge`, `/tool-exec`). It must reach the Worker, so locally that's\n *    `host.docker.internal` (the container can't reach the host's `localhost`).\n *  - **Preview** — the BROWSER opens an `exposePort` URL that `proxyToSandbox`\n *    routes into the container. It needs WILDCARD DNS, so locally that's\n *    `*.localhost` (browsers resolve it to loopback with zero setup) and in\n *    production a CUSTOM DOMAIN (`*.workers.dev` has no wildcard subdomains).\n */\n\n/** Hostnames that mean \"this machine\" (the loopback the container can't reach). */\nfunction isLoopbackHost(host: string): boolean {\n  const name = host.split(':')[0]\n  return name === 'localhost' || name === '127.0.0.1' || name === '0.0.0.0'\n}\n\n/** The port portion of a `host[:port]`, or `fallback` when none is present. */\nfunction portOf(host: string, fallback: string): string {\n  const colon = host.indexOf(':')\n  return colon === -1 ? fallback : host.slice(colon + 1)\n}\n\n/** `http://` for local hosts (loopback / host.docker.internal), `https://` else. */\nfunction originForHost(host: string): string {\n  const name = host.split(':')[0]\n  const scheme =\n    isLoopbackHost(host) || name === 'host.docker.internal' ? 'http' : 'https'\n  return `${scheme}://${host}`\n}\n\n/**\n * Resolve the ORIGIN the off-isolate sandbox CONTAINER uses to call back into the\n * Worker — the MCP tool-bridge (`/_bridge`) and host-tool execution (`/tool-exec`).\n * Returns a full origin (scheme + host + optional port), e.g.\n * `http://host.docker.internal:3001` locally or `https://app.example.com` deployed.\n *\n * `PUBLIC_HOSTNAME` wins when set; otherwise we derive from the host the trigger\n * request arrived on (`input.publicHost`).\n *\n * ── Why a callback hostname is unavoidable ──────────────────────────────────────\n * The container is SEPARATE compute from the Worker isolate; it can only reach the\n * Worker over the network, so the callback URL must be an absolute host.\n *\n * ── Why request-derivation is SAFE on Cloudflare ────────────────────────────────\n * On a generic Node server the `Host` header is attacker-controlled and trusting it\n * is a Host-injection / token-exfil vector (the per-run bearer token rides this\n * URL). Not so behind Cloudflare: the edge dispatches a request to your Worker only\n * when its hostname matches a route you OWN, so `input.publicHost` is always one of\n * your own hostnames — never an attacker's.\n *\n * ── Local dev: localhost → host.docker.internal ─────────────────────────────────\n * Locally the trigger arrives on `localhost`, which the container CANNOT reach\n * (that's the container's own loopback). So we rewrite it to `host.docker.internal`\n * (the Docker host gateway), keeping the port, over `http`. This removes the need\n * for a dev tunnel for the bridge entirely.\n */\nexport function resolveBridgeOrigin(\n  env: { PUBLIC_HOSTNAME?: string },\n  input: { publicHost?: string },\n): string {\n  const configured = env.PUBLIC_HOSTNAME?.trim()\n  if (configured) return originForHost(configured)\n  const host = input.publicHost\n  if (!host) {\n    throw new Error(\n      'sandbox agent: no bridge host available — set PUBLIC_HOSTNAME, or run ' +\n        'behind Cloudflare so the Worker can derive it from the trigger request.',\n    )\n  }\n  // Local dev: the container reaches the host machine via the Docker host gateway.\n  if (isLoopbackHost(host)) {\n    return `http://host.docker.internal:${portOf(host, '3001')}`\n  }\n  return originForHost(host)\n}\n\n/**\n * Resolve the HOST passed to `exposePort` for browser-facing preview URLs (the app\n * the agent builds). Returns a bare host (the `@cloudflare/sandbox` SDK builds the\n * `<port>-<id>-<token>.<host>` URL + scheme itself).\n *\n * `PREVIEW_HOSTNAME` wins when set; otherwise we derive from the trigger request.\n *\n * Preview URLs require WILDCARD DNS, which constrains the value:\n *  - **Local** → `localhost:<port>`. The SDK's localhost path yields\n *    `http://<port>-<id>-<token>.localhost:<port>`, which browsers resolve to\n *    loopback with no DNS setup — so previews work locally with no tunnel.\n *  - **Deployed** → a CUSTOM DOMAIN with a `*.<domain>` route. `*.workers.dev` has\n *    no wildcard subdomains (the SDK's `exposePort` throws on it), so we throw a\n *    clear error pointing at `PREVIEW_HOSTNAME` rather than letting the run fail\n *    deep in the agent.\n */\nexport function resolvePreviewHost(\n  env: { PREVIEW_HOSTNAME?: string },\n  input: { publicHost?: string },\n): string {\n  const configured = env.PREVIEW_HOSTNAME?.trim()\n  if (configured) return configured\n  const host = input.publicHost\n  if (!host) {\n    throw new Error(\n      'sandbox agent: no preview host available — set PREVIEW_HOSTNAME to a ' +\n        'custom domain with a wildcard route.',\n    )\n  }\n  if (isLoopbackHost(host)) return host\n  if (host.endsWith('.workers.dev')) {\n    throw new Error(\n      'sandbox agent: preview URLs need a custom domain with wildcard DNS — ' +\n        '*.workers.dev has no wildcard subdomains. Set PREVIEW_HOSTNAME to your ' +\n        'custom domain and add a `*.<domain>` route to the Worker.',\n    )\n  }\n  return host\n}\n"],"names":[],"mappings":"AAiBA,SAAS,eAAe,MAAuB;AAC7C,QAAM,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC;AAC9B,SAAO,SAAS,eAAe,SAAS,eAAe,SAAS;AAClE;AAGA,SAAS,OAAO,MAAc,UAA0B;AACtD,QAAM,QAAQ,KAAK,QAAQ,GAAG;AAC9B,SAAO,UAAU,KAAK,WAAW,KAAK,MAAM,QAAQ,CAAC;AACvD;AAGA,SAAS,cAAc,MAAsB;AAC3C,QAAM,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC;AAC9B,QAAM,SACJ,eAAe,IAAI,KAAK,SAAS,yBAAyB,SAAS;AACrE,SAAO,GAAG,MAAM,MAAM,IAAI;AAC5B;AA4BO,SAAS,oBACd,KACA,OACQ;AACR,QAAM,aAAa,IAAI,iBAAiB,KAAA;AACxC,MAAI,WAAY,QAAO,cAAc,UAAU;AAC/C,QAAM,OAAO,MAAM;AACnB,MAAI,CAAC,MAAM;AACT,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAGJ;AAEA,MAAI,eAAe,IAAI,GAAG;AACxB,WAAO,+BAA+B,OAAO,MAAM,MAAM,CAAC;AAAA,EAC5D;AACA,SAAO,cAAc,IAAI;AAC3B;AAkBO,SAAS,mBACd,KACA,OACQ;AACR,QAAM,aAAa,IAAI,kBAAkB,KAAA;AACzC,MAAI,WAAY,QAAO;AACvB,QAAM,OAAO,MAAM;AACnB,MAAI,CAAC,MAAM;AACT,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAGJ;AACA,MAAI,eAAe,IAAI,EAAG,QAAO;AACjC,MAAI,KAAK,SAAS,cAAc,GAAG;AACjC,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAIJ;AACA,SAAO;AACT;"}
+{"version":3,"file":"public-host.js","names":[],"sources":["../../src/public-host.ts"],"sourcesContent":["/**\n * Host resolution for the two DISTINCT public surfaces the sandbox layer exposes.\n * Kept in its own (Workers-free) module so it stays pure and unit-testable.\n *\n * These were once a single `PUBLIC_HOSTNAME`, but they have different reachers and\n * therefore different correct values:\n *\n *  - **Bridge / tool-exec** — the off-isolate CONTAINER calls back into the Worker\n *    (`/_bridge`, `/tool-exec`). It must reach the Worker, so locally that's\n *    `host.docker.internal` (the container can't reach the host's `localhost`).\n *  - **Preview** — the BROWSER opens an `exposePort` URL that `proxyToSandbox`\n *    routes into the container. It needs WILDCARD DNS, so locally that's\n *    `*.localhost` (browsers resolve it to loopback with zero setup) and in\n *    production a CUSTOM DOMAIN (`*.workers.dev` has no wildcard subdomains).\n */\n\n/** Hostnames that mean \"this machine\" (the loopback the container can't reach). */\nfunction isLoopbackHost(host: string): boolean {\n  const name = host.split(':')[0]\n  return name === 'localhost' || name === '127.0.0.1' || name === '0.0.0.0'\n}\n\n/** The port portion of a `host[:port]`, or `fallback` when none is present. */\nfunction portOf(host: string, fallback: string): string {\n  const colon = host.indexOf(':')\n  return colon === -1 ? fallback : host.slice(colon + 1)\n}\n\n/** `http://` for local hosts (loopback / host.docker.internal), `https://` else. */\nfunction originForHost(host: string): string {\n  const name = host.split(':')[0]\n  const scheme =\n    isLoopbackHost(host) || name === 'host.docker.internal' ? 'http' : 'https'\n  return `${scheme}://${host}`\n}\n\n/**\n * Resolve the ORIGIN the off-isolate sandbox CONTAINER uses to call back into the\n * Worker — the MCP tool-bridge (`/_bridge`) and host-tool execution (`/tool-exec`).\n * Returns a full origin (scheme + host + optional port), e.g.\n * `http://host.docker.internal:3001` locally or `https://app.example.com` deployed.\n *\n * `PUBLIC_HOSTNAME` wins when set; otherwise we derive from the host the trigger\n * request arrived on (`input.publicHost`).\n *\n * ── Why a callback hostname is unavoidable ──────────────────────────────────────\n * The container is SEPARATE compute from the Worker isolate; it can only reach the\n * Worker over the network, so the callback URL must be an absolute host.\n *\n * ── Why request-derivation is SAFE on Cloudflare ────────────────────────────────\n * On a generic Node server the `Host` header is attacker-controlled and trusting it\n * is a Host-injection / token-exfil vector (the per-run bearer token rides this\n * URL). Not so behind Cloudflare: the edge dispatches a request to your Worker only\n * when its hostname matches a route you OWN, so `input.publicHost` is always one of\n * your own hostnames — never an attacker's.\n *\n * ── Local dev: localhost → host.docker.internal ─────────────────────────────────\n * Locally the trigger arrives on `localhost`, which the container CANNOT reach\n * (that's the container's own loopback). So we rewrite it to `host.docker.internal`\n * (the Docker host gateway), keeping the port, over `http`. This removes the need\n * for a dev tunnel for the bridge entirely.\n */\nexport function resolveBridgeOrigin(\n  env: { PUBLIC_HOSTNAME?: string },\n  input: { publicHost?: string },\n): string {\n  const configured = env.PUBLIC_HOSTNAME?.trim()\n  if (configured) return originForHost(configured)\n  const host = input.publicHost\n  if (!host) {\n    throw new Error(\n      'sandbox agent: no bridge host available — set PUBLIC_HOSTNAME, or run ' +\n        'behind Cloudflare so the Worker can derive it from the trigger request.',\n    )\n  }\n  // Local dev: the container reaches the host machine via the Docker host gateway.\n  if (isLoopbackHost(host)) {\n    return `http://host.docker.internal:${portOf(host, '3001')}`\n  }\n  return originForHost(host)\n}\n\n/**\n * Resolve the HOST passed to `exposePort` for browser-facing preview URLs (the app\n * the agent builds). Returns a bare host (the `@cloudflare/sandbox` SDK builds the\n * `<port>-<id>-<token>.<host>` URL + scheme itself).\n *\n * `PREVIEW_HOSTNAME` wins when set; otherwise we derive from the trigger request.\n *\n * Preview URLs require WILDCARD DNS, which constrains the value:\n *  - **Local** → `localhost:<port>`. The SDK's localhost path yields\n *    `http://<port>-<id>-<token>.localhost:<port>`, which browsers resolve to\n *    loopback with no DNS setup — so previews work locally with no tunnel.\n *  - **Deployed** → a CUSTOM DOMAIN with a `*.<domain>` route. `*.workers.dev` has\n *    no wildcard subdomains (the SDK's `exposePort` throws on it), so we throw a\n *    clear error pointing at `PREVIEW_HOSTNAME` rather than letting the run fail\n *    deep in the agent.\n */\nexport function resolvePreviewHost(\n  env: { PREVIEW_HOSTNAME?: string },\n  input: { publicHost?: string },\n): string {\n  const configured = env.PREVIEW_HOSTNAME?.trim()\n  if (configured) return configured\n  const host = input.publicHost\n  if (!host) {\n    throw new Error(\n      'sandbox agent: no preview host available — set PREVIEW_HOSTNAME to a ' +\n        'custom domain with a wildcard route.',\n    )\n  }\n  if (isLoopbackHost(host)) return host\n  if (host.endsWith('.workers.dev')) {\n    throw new Error(\n      'sandbox agent: preview URLs need a custom domain with wildcard DNS — ' +\n        '*.workers.dev has no wildcard subdomains. Set PREVIEW_HOSTNAME to your ' +\n        'custom domain and add a `*.<domain>` route to the Worker.',\n    )\n  }\n  return host\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,SAAS,eAAe,MAAuB;CAC7C,MAAM,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC;CAC7B,OAAO,SAAS,eAAe,SAAS,eAAe,SAAS;AAClE;;AAGA,SAAS,OAAO,MAAc,UAA0B;CACtD,MAAM,QAAQ,KAAK,QAAQ,GAAG;CAC9B,OAAO,UAAU,KAAK,WAAW,KAAK,MAAM,QAAQ,CAAC;AACvD;;AAGA,SAAS,cAAc,MAAsB;CAC3C,MAAM,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC;CAG7B,OAAO,GADL,eAAe,IAAI,KAAK,SAAS,yBAAyB,SAAS,QACpD,KAAK;AACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,oBACd,KACA,OACQ;CACR,MAAM,aAAa,IAAI,iBAAiB,KAAK;CAC7C,IAAI,YAAY,OAAO,cAAc,UAAU;CAC/C,MAAM,OAAO,MAAM;CACnB,IAAI,CAAC,MACH,MAAM,IAAI,MACR,+IAEF;CAGF,IAAI,eAAe,IAAI,GACrB,OAAO,+BAA+B,OAAO,MAAM,MAAM;CAE3D,OAAO,cAAc,IAAI;AAC3B;;;;;;;;;;;;;;;;;AAkBA,SAAgB,mBACd,KACA,OACQ;CACR,MAAM,aAAa,IAAI,kBAAkB,KAAK;CAC9C,IAAI,YAAY,OAAO;CACvB,MAAM,OAAO,MAAM;CACnB,IAAI,CAAC,MACH,MAAM,IAAI,MACR,2GAEF;CAEF,IAAI,eAAe,IAAI,GAAG,OAAO;CACjC,IAAI,KAAK,SAAS,cAAc,GAC9B,MAAM,IAAI,MACR,uMAGF;CAEF,OAAO;AACT"}

package/dist/esm/run-log-do.d.ts

@@ -1,20 +1,34 @@
-import { RunError, RunEvent, RunEventLog, RunEventLogReadOptions, RunRecord, TerminalRunStatus } from '@tanstack/ai-sandbox';
-import { StreamChunk } from '@tanstack/ai';
+import { RunEvent, RunEventLog, RunEventLogReadOptions, RunLogRecord, RunRecordPatch } from './run-log.js';
+import { RunError, StreamChunk, TerminalRunStatus } from '@tanstack/ai';
 export declare class DurableObjectRunEventLog implements RunEventLog {
     private readonly storage;
     /** Per-run wake-ups for live-tailing readers on THIS instance. */
     private readonly waiters;
     constructor(storage: DurableObjectStorage);
+    /**
+     * Read (and, when needed, migrate + write back) the record under `rec:<runId>`.
+     * The single storage read path — everything else goes through here so no
+     * caller can observe the legacy layout.
+     */
+    private getRecord;
     private require;
     /** Wake (and clear) every reader blocked on this run. */
     private wake;
     open(input: {
         runId: string;
-        threadId?: string;
-    }): Promise<RunRecord>;
+        threadId: string;
+        startedAt?: number;
+    }): Promise<RunLogRecord>;
     append(runId: string, chunk: StreamChunk): Promise<number>;
     finish(runId: string, status: TerminalRunStatus, error?: RunError): Promise<void>;
-    get(runId: string): Promise<RunRecord | null>;
+    update(runId: string, patch: RunRecordPatch): Promise<void>;
+    get(runId: string): Promise<RunLogRecord | null>;
+    /**
+     * Every run record this log holds, migrated. The coordinator's stall
+     * watchdog iterates this instead of listing `rec:` keys itself, so the
+     * storage layout (and its migration) stays this module's private concern.
+     */
+    list(): Promise<Array<RunLogRecord>>;
     read(runId: string, options?: RunEventLogReadOptions): AsyncIterable<RunEvent>;
     /**
      * Resolve when an append/finish wakes this run, the signal aborts, or the

package/dist/esm/run-log-do.js

@@ -1,122 +1,197 @@
-import { isTerminalRunStatus } from "@tanstack/ai-sandbox";
-const TAIL_POLL_MS = 250;
-const recKey = (runId) => `rec:${runId}`;
-const evtKey = (runId, seq) => `evt:${runId}:${String(seq).padStart(8, "0")}`;
-const evtPrefix = (runId) => `evt:${runId}:`;
-class DurableObjectRunEventLog {
-  constructor(storage) {
-    this.storage = storage;
-  }
-  storage;
-  /** Per-run wake-ups for live-tailing readers on THIS instance. */
-  waiters = /* @__PURE__ */ new Map();
-  async require(runId) {
-    const record = await this.storage.get(recKey(runId));
-    if (!record) throw new Error(`run-log: unknown runId "${runId}"`);
-    return record;
-  }
-  /** Wake (and clear) every reader blocked on this run. */
-  wake(runId) {
-    const set = this.waiters.get(runId);
-    if (!set) return;
-    const pending = [...set];
-    set.clear();
-    for (const resolve of pending) resolve();
-  }
-  async open(input) {
-    const existing = await this.storage.get(recKey(input.runId));
-    if (existing) return existing;
-    const now = Date.now();
-    const record = {
-      runId: input.runId,
-      ...input.threadId !== void 0 ? { threadId: input.threadId } : {},
-      status: "running",
-      lastSeq: -1,
-      createdAt: now,
-      updatedAt: now
-    };
-    await this.storage.put(recKey(input.runId), record);
-    return record;
-  }
-  async append(runId, chunk) {
-    const record = await this.require(runId);
-    if (isTerminalRunStatus(record.status)) {
-      throw new Error(
-        `run-log: cannot append to terminal run "${runId}" (status=${record.status})`
-      );
-    }
-    const seq = record.lastSeq + 1;
-    const next = { ...record, lastSeq: seq, updatedAt: Date.now() };
-    await this.storage.transaction(async (txn) => {
-      await txn.put(evtKey(runId, seq), chunk);
-      await txn.put(recKey(runId), next);
-    });
-    this.wake(runId);
-    return seq;
-  }
-  async finish(runId, status, error) {
-    const record = await this.require(runId);
-    if (isTerminalRunStatus(record.status)) return;
-    const next = {
-      ...record,
-      status,
-      ...error !== void 0 ? { error } : {},
-      updatedAt: Date.now()
-    };
-    await this.storage.put(recKey(runId), next);
-    this.wake(runId);
-  }
-  async get(runId) {
-    return await this.storage.get(recKey(runId)) ?? null;
-  }
-  async *read(runId, options) {
-    await this.require(runId);
-    const signal = options?.signal;
-    let cursor = options?.fromSeq ?? -1;
-    while (!signal?.aborted) {
-      const record = await this.require(runId);
-      if (cursor < record.lastSeq) {
-        const events = await this.storage.list({
-          prefix: evtPrefix(runId),
-          start: evtKey(runId, cursor + 1)
-        });
-        for (const [, chunk] of events) {
-          cursor += 1;
-          yield { seq: cursor, chunk };
-          if (signal?.aborted) return;
-        }
-        continue;
-      }
-      if (isTerminalRunStatus(record.status)) return;
-      await this.waitForChange(runId, signal);
-    }
-  }
-  /**
-   * Resolve when an append/finish wakes this run, the signal aborts, or the
-   * fallback poll fires (the poll lets a reader that outlived its in-memory
-   * waiter — e.g. after the appending instance was evicted — keep progressing).
-   */
-  waitForChange(runId, signal) {
-    return new Promise((resolve) => {
-      let set = this.waiters.get(runId);
-      if (!set) {
-        set = /* @__PURE__ */ new Set();
-        this.waiters.set(runId, set);
-      }
-      const localSet = set;
-      const wake = () => {
-        localSet.delete(wake);
-        clearTimeout(timer);
-        if (signal) signal.removeEventListener("abort", wake);
-        resolve();
-      };
-      const timer = setTimeout(wake, TAIL_POLL_MS);
-      localSet.add(wake);
-      if (signal) signal.addEventListener("abort", wake, { once: true });
-    });
-  }
-}
-export {
-  DurableObjectRunEventLog
+import { migrateStoredRunRecord } from "./run-log.js";
+import { isTerminalRunStatus } from "@tanstack/ai";
+//#region src/run-log-do.ts
+/**
+* A durable {@link RunEventLog} backed by Durable Object storage — the storage
+* half of the serverless/edge run model. The coordinator appends every
+* {@link StreamChunk} the agent emits under a monotonic `seq`; clients tail from
+* a cursor. Because events are PERSISTED (not held in a caller's open stream), a
+* reconnecting tab, a dropped WebSocket, or a coordinator that hibernated
+* between chunks all resume cleanly: replay everything after the client's
+* `lastSeq`, then live-tail to terminal.
+*
+* Mirrors {@link InMemoryRunEventLog} exactly.
+* Storage layout (keys scoped by `runId` so one DO can host many runs):
+* - `rec:<runId>`        → the {@link RunLogRecord}
+* - `evt:<runId>:<seq8>` → the chunk for that seq (seq zero-padded to 8 digits
+*                          so `list({ prefix })` returns events in seq order).
+*
+* LIVE-DATA MIGRATION: `rec:` values written before the run vocabulary
+* converged on core's (see the module header in `./run-log`) are converted by
+* {@link migrateStoredRunRecord} on first read and written back immediately, so
+* each record pays the conversion exactly once and every read path — `get`,
+* `append`'s precondition check, the watchdog's {@link list} — observes only
+* the converged layout. Event values (`evt:`) are raw chunks and need no
+* migration.
+*
+* The live-tail wake-up (the in-memory waiter set) is per-INSTANCE; if the
+* instance is evicted mid-run, a reader re-reads the persisted backlog and the
+* `TAIL_POLL_MS` fallback poll keeps it progressing. No event is ever lost.
+*
+* NOTE: Workers-runtime code — compiles against `@cloudflare/workers-types`.
+*/
+/** How long a post-eviction reader waits before re-polling storage (ms). */
+var TAIL_POLL_MS = 250;
+var recKey = (runId) => `rec:${runId}`;
+var evtKey = (runId, seq) => `evt:${runId}:${String(seq).padStart(8, "0")}`;
+var evtPrefix = (runId) => `evt:${runId}:`;
+var DurableObjectRunEventLog = class {
+	storage;
+	/** Per-run wake-ups for live-tailing readers on THIS instance. */
+	waiters = /* @__PURE__ */ new Map();
+	constructor(storage) {
+		this.storage = storage;
+	}
+	/**
+	* Read (and, when needed, migrate + write back) the record under `rec:<runId>`.
+	* The single storage read path — everything else goes through here so no
+	* caller can observe the legacy layout.
+	*/
+	async getRecord(runId) {
+		const stored = await this.storage.get(recKey(runId));
+		if (!stored) return null;
+		const { record, migrated } = migrateStoredRunRecord(stored);
+		if (migrated) await this.storage.put(recKey(runId), record);
+		return record;
+	}
+	async require(runId) {
+		const record = await this.getRecord(runId);
+		if (!record) throw new Error(`run-log: unknown runId "${runId}"`);
+		return record;
+	}
+	/** Wake (and clear) every reader blocked on this run. */
+	wake(runId) {
+		const set = this.waiters.get(runId);
+		if (!set) return;
+		const pending = [...set];
+		set.clear();
+		for (const resolve of pending) resolve();
+	}
+	async open(input) {
+		const existing = await this.getRecord(input.runId);
+		if (existing) return existing;
+		const now = Date.now();
+		const record = {
+			runId: input.runId,
+			threadId: input.threadId,
+			status: "running",
+			lastSeq: -1,
+			startedAt: input.startedAt ?? now,
+			updatedAt: now
+		};
+		await this.storage.put(recKey(input.runId), record);
+		return record;
+	}
+	async append(runId, chunk) {
+		const record = await this.require(runId);
+		if (isTerminalRunStatus(record.status)) throw new Error(`run-log: cannot append to terminal run "${runId}" (status=${record.status})`);
+		const seq = record.lastSeq + 1;
+		const next = {
+			...record,
+			lastSeq: seq,
+			updatedAt: Date.now()
+		};
+		await this.storage.transaction(async (txn) => {
+			await txn.put(evtKey(runId, seq), chunk);
+			await txn.put(recKey(runId), next);
+		});
+		this.wake(runId);
+		return seq;
+	}
+	async finish(runId, status, error) {
+		const record = await this.require(runId);
+		if (isTerminalRunStatus(record.status)) return;
+		const now = Date.now();
+		const next = {
+			...record,
+			status,
+			...error !== void 0 ? { error } : {},
+			finishedAt: now,
+			updatedAt: now
+		};
+		await this.storage.put(recKey(runId), next);
+		this.wake(runId);
+	}
+	async update(runId, patch) {
+		const record = await this.getRecord(runId);
+		if (!record) return;
+		const next = {
+			...record,
+			...patch,
+			updatedAt: Date.now()
+		};
+		await this.storage.put(recKey(runId), next);
+		this.wake(runId);
+	}
+	async get(runId) {
+		return this.getRecord(runId);
+	}
+	/**
+	* Every run record this log holds, migrated. The coordinator's stall
+	* watchdog iterates this instead of listing `rec:` keys itself, so the
+	* storage layout (and its migration) stays this module's private concern.
+	*/
+	async list() {
+		const stored = await this.storage.list({ prefix: "rec:" });
+		const records = [];
+		for (const [key, value] of stored) {
+			const { record, migrated } = migrateStoredRunRecord(value);
+			if (migrated) await this.storage.put(key, record);
+			records.push(record);
+		}
+		return records;
+	}
+	async *read(runId, options) {
+		await this.require(runId);
+		const signal = options?.signal;
+		let cursor = options?.fromSeq ?? -1;
+		while (!signal?.aborted) {
+			const record = await this.require(runId);
+			if (cursor < record.lastSeq) {
+				const events = await this.storage.list({
+					prefix: evtPrefix(runId),
+					start: evtKey(runId, cursor + 1)
+				});
+				for (const [, chunk] of events) {
+					cursor += 1;
+					yield {
+						seq: cursor,
+						chunk
+					};
+					if (signal?.aborted) return;
+				}
+				continue;
+			}
+			if (isTerminalRunStatus(record.status)) return;
+			await this.waitForChange(runId, signal);
+		}
+	}
+	/**
+	* Resolve when an append/finish wakes this run, the signal aborts, or the
+	* fallback poll fires (the poll lets a reader that outlived its in-memory
+	* waiter — e.g. after the appending instance was evicted — keep progressing).
+	*/
+	waitForChange(runId, signal) {
+		return new Promise((resolve) => {
+			let set = this.waiters.get(runId);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				this.waiters.set(runId, set);
+			}
+			const localSet = set;
+			const wake = () => {
+				localSet.delete(wake);
+				clearTimeout(timer);
+				if (signal) signal.removeEventListener("abort", wake);
+				resolve();
+			};
+			const timer = setTimeout(wake, TAIL_POLL_MS);
+			localSet.add(wake);
+			if (signal) signal.addEventListener("abort", wake, { once: true });
+		});
+	}
 };
-//# sourceMappingURL=run-log-do.js.map
+//#endregion
+export { DurableObjectRunEventLog };
+
+//# sourceMappingURL=run-log-do.js.map

package/dist/esm/run-log-do.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-log-do.js","sources":["../../src/run-log-do.ts"],"sourcesContent":["/**\n * A durable {@link RunEventLog} backed by Durable Object storage — the storage\n * half of the serverless/edge run model. The coordinator appends every\n * {@link StreamChunk} the agent emits under a monotonic `seq`; clients tail from\n * a cursor. Because events are PERSISTED (not held in a caller's open stream), a\n * reconnecting tab, a dropped WebSocket, or a coordinator that hibernated\n * between chunks all resume cleanly: replay everything after the client's\n * `lastSeq`, then live-tail to terminal.\n *\n * Mirrors {@link InMemoryRunEventLog} from `@tanstack/ai-sandbox` exactly.\n * Storage layout (keys scoped by `runId` so one DO can host many runs):\n * - `rec:<runId>`        → the {@link RunRecord}\n * - `evt:<runId>:<seq8>` → the chunk for that seq (seq zero-padded to 8 digits\n *                          so `list({ prefix })` returns events in seq order).\n *\n * The live-tail wake-up (the in-memory waiter set) is per-INSTANCE; if the\n * instance is evicted mid-run, a reader re-reads the persisted backlog and the\n * `TAIL_POLL_MS` fallback poll keeps it progressing. No event is ever lost.\n *\n * NOTE: Workers-runtime code — compiles against `@cloudflare/workers-types`.\n */\nimport { isTerminalRunStatus } from '@tanstack/ai-sandbox'\nimport type {\n  RunError,\n  RunEvent,\n  RunEventLog,\n  RunEventLogReadOptions,\n  RunRecord,\n  TerminalRunStatus,\n} from '@tanstack/ai-sandbox'\nimport type { StreamChunk } from '@tanstack/ai'\n\n/** How long a post-eviction reader waits before re-polling storage (ms). */\nconst TAIL_POLL_MS = 250\n\nconst recKey = (runId: string): string => `rec:${runId}`\nconst evtKey = (runId: string, seq: number): string =>\n  `evt:${runId}:${String(seq).padStart(8, '0')}`\nconst evtPrefix = (runId: string): string => `evt:${runId}:`\n\nexport class DurableObjectRunEventLog implements RunEventLog {\n  /** Per-run wake-ups for live-tailing readers on THIS instance. */\n  private readonly waiters = new Map<string, Set<() => void>>()\n\n  constructor(private readonly storage: DurableObjectStorage) {}\n\n  private async require(runId: string): Promise<RunRecord> {\n    const record = await this.storage.get<RunRecord>(recKey(runId))\n    if (!record) throw new Error(`run-log: unknown runId \"${runId}\"`)\n    return record\n  }\n\n  /** Wake (and clear) every reader blocked on this run. */\n  private wake(runId: string): void {\n    const set = this.waiters.get(runId)\n    if (!set) return\n    const pending = [...set]\n    set.clear()\n    for (const resolve of pending) resolve()\n  }\n\n  async open(input: { runId: string; threadId?: string }): Promise<RunRecord> {\n    const existing = await this.storage.get<RunRecord>(recKey(input.runId))\n    if (existing) return existing\n    const now = Date.now()\n    const record: RunRecord = {\n      runId: input.runId,\n      ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),\n      status: 'running',\n      lastSeq: -1,\n      createdAt: now,\n      updatedAt: now,\n    }\n    await this.storage.put(recKey(input.runId), record)\n    return record\n  }\n\n  async append(runId: string, chunk: StreamChunk): Promise<number> {\n    const record = await this.require(runId)\n    if (isTerminalRunStatus(record.status)) {\n      throw new Error(\n        `run-log: cannot append to terminal run \"${runId}\" (status=${record.status})`,\n      )\n    }\n    const seq = record.lastSeq + 1\n    const next: RunRecord = { ...record, lastSeq: seq, updatedAt: Date.now() }\n    // One transaction so the appended event and its bumped record commit\n    // together — a reader never sees a lastSeq pointing at a missing event.\n    await this.storage.transaction(async (txn) => {\n      await txn.put(evtKey(runId, seq), chunk)\n      await txn.put(recKey(runId), next)\n    })\n    this.wake(runId)\n    return seq\n  }\n\n  async finish(\n    runId: string,\n    status: TerminalRunStatus,\n    error?: RunError,\n  ): Promise<void> {\n    const record = await this.require(runId)\n    if (isTerminalRunStatus(record.status)) return\n    const next: RunRecord = {\n      ...record,\n      status,\n      ...(error !== undefined ? { error } : {}),\n      updatedAt: Date.now(),\n    }\n    await this.storage.put(recKey(runId), next)\n    this.wake(runId)\n  }\n\n  async get(runId: string): Promise<RunRecord | null> {\n    return (await this.storage.get<RunRecord>(recKey(runId))) ?? null\n  }\n\n  async *read(\n    runId: string,\n    options?: RunEventLogReadOptions,\n  ): AsyncIterable<RunEvent> {\n    await this.require(runId)\n    const signal = options?.signal\n    let cursor = options?.fromSeq ?? -1\n\n    while (!signal?.aborted) {\n      const record = await this.require(runId)\n      // Drain the persisted backlog after the cursor in seq order. The\n      // zero-padded keys make the prefix list naturally ordered.\n      if (cursor < record.lastSeq) {\n        const events = await this.storage.list<StreamChunk>({\n          prefix: evtPrefix(runId),\n          start: evtKey(runId, cursor + 1),\n        })\n        for (const [, chunk] of events) {\n          cursor += 1\n          yield { seq: cursor, chunk }\n          if (signal?.aborted) return\n        }\n        continue\n      }\n      if (isTerminalRunStatus(record.status)) return\n      await this.waitForChange(runId, signal)\n    }\n  }\n\n  /**\n   * Resolve when an append/finish wakes this run, the signal aborts, or the\n   * fallback poll fires (the poll lets a reader that outlived its in-memory\n   * waiter — e.g. after the appending instance was evicted — keep progressing).\n   */\n  private waitForChange(runId: string, signal?: AbortSignal): Promise<void> {\n    return new Promise<void>((resolve) => {\n      let set = this.waiters.get(runId)\n      if (!set) {\n        set = new Set()\n        this.waiters.set(runId, set)\n      }\n      const localSet = set\n      const wake = (): void => {\n        localSet.delete(wake)\n        clearTimeout(timer)\n        if (signal) signal.removeEventListener('abort', wake)\n        resolve()\n      }\n      const timer = setTimeout(wake, TAIL_POLL_MS)\n      localSet.add(wake)\n      if (signal) signal.addEventListener('abort', wake, { once: true })\n    })\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-log-do.js","names":[],"sources":["../../src/run-log-do.ts"],"sourcesContent":["/**\n * A durable {@link RunEventLog} backed by Durable Object storage — the storage\n * half of the serverless/edge run model. The coordinator appends every\n * {@link StreamChunk} the agent emits under a monotonic `seq`; clients tail from\n * a cursor. Because events are PERSISTED (not held in a caller's open stream), a\n * reconnecting tab, a dropped WebSocket, or a coordinator that hibernated\n * between chunks all resume cleanly: replay everything after the client's\n * `lastSeq`, then live-tail to terminal.\n *\n * Mirrors {@link InMemoryRunEventLog} exactly.\n * Storage layout (keys scoped by `runId` so one DO can host many runs):\n * - `rec:<runId>`        → the {@link RunLogRecord}\n * - `evt:<runId>:<seq8>` → the chunk for that seq (seq zero-padded to 8 digits\n *                          so `list({ prefix })` returns events in seq order).\n *\n * LIVE-DATA MIGRATION: `rec:` values written before the run vocabulary\n * converged on core's (see the module header in `./run-log`) are converted by\n * {@link migrateStoredRunRecord} on first read and written back immediately, so\n * each record pays the conversion exactly once and every read path — `get`,\n * `append`'s precondition check, the watchdog's {@link list} — observes only\n * the converged layout. Event values (`evt:`) are raw chunks and need no\n * migration.\n *\n * The live-tail wake-up (the in-memory waiter set) is per-INSTANCE; if the\n * instance is evicted mid-run, a reader re-reads the persisted backlog and the\n * `TAIL_POLL_MS` fallback poll keeps it progressing. No event is ever lost.\n *\n * NOTE: Workers-runtime code — compiles against `@cloudflare/workers-types`.\n */\nimport { isTerminalRunStatus } from '@tanstack/ai'\nimport { migrateStoredRunRecord } from './run-log'\nimport type {\n  RunEvent,\n  RunEventLog,\n  RunEventLogReadOptions,\n  RunLogRecord,\n  RunRecordPatch,\n} from './run-log'\nimport type { RunError, StreamChunk, TerminalRunStatus } from '@tanstack/ai'\n\n/** How long a post-eviction reader waits before re-polling storage (ms). */\nconst TAIL_POLL_MS = 250\n\n/**\n * What a `rec:` key may hold: the converged layout, or the pre-convergence one\n * `migrateStoredRunRecord` still reads. Typed as the migration function's input\n * so a read is forced through it.\n */\ntype StoredRunRecord = Parameters<typeof migrateStoredRunRecord>[0]\n\nconst recKey = (runId: string): string => `rec:${runId}`\nconst evtKey = (runId: string, seq: number): string =>\n  `evt:${runId}:${String(seq).padStart(8, '0')}`\nconst evtPrefix = (runId: string): string => `evt:${runId}:`\n\nexport class DurableObjectRunEventLog implements RunEventLog {\n  /** Per-run wake-ups for live-tailing readers on THIS instance. */\n  private readonly waiters = new Map<string, Set<() => void>>()\n\n  constructor(private readonly storage: DurableObjectStorage) {}\n\n  /**\n   * Read (and, when needed, migrate + write back) the record under `rec:<runId>`.\n   * The single storage read path — everything else goes through here so no\n   * caller can observe the legacy layout.\n   */\n  private async getRecord(runId: string): Promise<RunLogRecord | null> {\n    const stored = await this.storage.get<StoredRunRecord>(recKey(runId))\n    if (!stored) return null\n    const { record, migrated } = migrateStoredRunRecord(stored)\n    if (migrated) await this.storage.put(recKey(runId), record)\n    return record\n  }\n\n  private async require(runId: string): Promise<RunLogRecord> {\n    const record = await this.getRecord(runId)\n    if (!record) throw new Error(`run-log: unknown runId \"${runId}\"`)\n    return record\n  }\n\n  /** Wake (and clear) every reader blocked on this run. */\n  private wake(runId: string): void {\n    const set = this.waiters.get(runId)\n    if (!set) return\n    const pending = [...set]\n    set.clear()\n    for (const resolve of pending) resolve()\n  }\n\n  async open(input: {\n    runId: string\n    threadId: string\n    startedAt?: number\n  }): Promise<RunLogRecord> {\n    const existing = await this.getRecord(input.runId)\n    if (existing) return existing\n    const now = Date.now()\n    const record: RunLogRecord = {\n      runId: input.runId,\n      threadId: input.threadId,\n      status: 'running',\n      lastSeq: -1,\n      startedAt: input.startedAt ?? now,\n      updatedAt: now,\n    }\n    await this.storage.put(recKey(input.runId), record)\n    return record\n  }\n\n  async append(runId: string, chunk: StreamChunk): Promise<number> {\n    const record = await this.require(runId)\n    if (isTerminalRunStatus(record.status)) {\n      throw new Error(\n        `run-log: cannot append to terminal run \"${runId}\" (status=${record.status})`,\n      )\n    }\n    const seq = record.lastSeq + 1\n    const next: RunLogRecord = {\n      ...record,\n      lastSeq: seq,\n      updatedAt: Date.now(),\n    }\n    // One transaction so the appended event and its bumped record commit\n    // together — a reader never sees a lastSeq pointing at a missing event.\n    await this.storage.transaction(async (txn) => {\n      await txn.put(evtKey(runId, seq), chunk)\n      await txn.put(recKey(runId), next)\n    })\n    this.wake(runId)\n    return seq\n  }\n\n  async finish(\n    runId: string,\n    status: TerminalRunStatus,\n    error?: RunError,\n  ): Promise<void> {\n    const record = await this.require(runId)\n    if (isTerminalRunStatus(record.status)) return\n    const now = Date.now()\n    const next: RunLogRecord = {\n      ...record,\n      status,\n      ...(error !== undefined ? { error } : {}),\n      finishedAt: now,\n      updatedAt: now,\n    }\n    await this.storage.put(recKey(runId), next)\n    this.wake(runId)\n  }\n\n  async update(runId: string, patch: RunRecordPatch): Promise<void> {\n    const record = await this.getRecord(runId)\n    if (!record) return // unknown runId is a no-op\n    const next: RunLogRecord = { ...record, ...patch, updatedAt: Date.now() }\n    await this.storage.put(recKey(runId), next)\n    // A patch may terminalize the shared status field (core's driver writes its\n    // terminal status through `RunStore.update`) — parked readers must see it\n    // now, not a TAIL_POLL_MS later.\n    this.wake(runId)\n  }\n\n  async get(runId: string): Promise<RunLogRecord | null> {\n    return this.getRecord(runId)\n  }\n\n  /**\n   * Every run record this log holds, migrated. The coordinator's stall\n   * watchdog iterates this instead of listing `rec:` keys itself, so the\n   * storage layout (and its migration) stays this module's private concern.\n   */\n  async list(): Promise<Array<RunLogRecord>> {\n    const stored = await this.storage.list<StoredRunRecord>({ prefix: 'rec:' })\n    const records: Array<RunLogRecord> = []\n    for (const [key, value] of stored) {\n      const { record, migrated } = migrateStoredRunRecord(value)\n      if (migrated) await this.storage.put(key, record)\n      records.push(record)\n    }\n    return records\n  }\n\n  async *read(\n    runId: string,\n    options?: RunEventLogReadOptions,\n  ): AsyncIterable<RunEvent> {\n    await this.require(runId)\n    const signal = options?.signal\n    let cursor = options?.fromSeq ?? -1\n\n    while (!signal?.aborted) {\n      const record = await this.require(runId)\n      // Drain the persisted backlog after the cursor in seq order. The\n      // zero-padded keys make the prefix list naturally ordered.\n      if (cursor < record.lastSeq) {\n        const events = await this.storage.list<StreamChunk>({\n          prefix: evtPrefix(runId),\n          start: evtKey(runId, cursor + 1),\n        })\n        for (const [, chunk] of events) {\n          cursor += 1\n          yield { seq: cursor, chunk }\n          if (signal?.aborted) return\n        }\n        continue\n      }\n      if (isTerminalRunStatus(record.status)) return\n      await this.waitForChange(runId, signal)\n    }\n  }\n\n  /**\n   * Resolve when an append/finish wakes this run, the signal aborts, or the\n   * fallback poll fires (the poll lets a reader that outlived its in-memory\n   * waiter — e.g. after the appending instance was evicted — keep progressing).\n   */\n  private waitForChange(runId: string, signal?: AbortSignal): Promise<void> {\n    return new Promise<void>((resolve) => {\n      let set = this.waiters.get(runId)\n      if (!set) {\n        set = new Set()\n        this.waiters.set(runId, set)\n      }\n      const localSet = set\n      const wake = (): void => {\n        localSet.delete(wake)\n        clearTimeout(timer)\n        if (signal) signal.removeEventListener('abort', wake)\n        resolve()\n      }\n      const timer = setTimeout(wake, TAIL_POLL_MS)\n      localSet.add(wake)\n      if (signal) signal.addEventListener('abort', wake, { once: true })\n    })\n  }\n}\n"],"mappings":"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"}