@cursor/bdk 0.2.14 → 0.2.16

package/dist/internal/discovery/project.js

@@ -11,7 +11,7 @@ import { loadChannels } from "./channels.js";
 import { defaultImportModule, displayPath, } from "./context.js";
 import { hasFlatLayoutMarkers, isDirectory, readPackageName, sortedEntries } from "./fs.js";
 import { loadHooks } from "./hooks.js";
-import { NAME_PATTERN } from "./names.js";
+import { NAME_PATTERN, RESERVED_SLUGS } from "./names.js";
 import { loadReminders } from "./reminders.js";
 import { loadSchedules } from "./schedules.js";
 import { appendArtifactTool, loadArtifacts, loadOtel, loadStorage, mergeArtifacts, rejectLegacyResult, } from "./services.js";
@@ -133,8 +133,6 @@ function assertSlug(name, parentDir) {
     }
     return name;
 }
-/** URL path segments reserved by the server; agents cannot use them as slugs. */
-const RESERVED_SLUGS = new Set(["v1", "playground", "docs"]);
 export async function loadAgentProject(dir, options = {}) {
     // Public API: embedders can call discovery directly (without `serve()` or
     // the CLI), and it dynamically imports authored TypeScript.

package/dist/internal/eval-judge-model.d.ts

@@ -7,17 +7,22 @@
  * prompt injection needs. A reply that talks the judge into running a tool would
  * do so on the machine running the eval CLI, under the runner's credentials.
  *
- * The session is therefore confined on every axis the SDK exposes:
+ * The session is therefore given nothing to act with:
  *
- * - `sandboxOptions.enabled` so any tool call the judge is talked into is
- *   confined rather than run directly against the host.
+ * - `tools: []` so the model is offered no built-in tools and can only reply
+ *   with text. An injected reply has no shell, file, or MCP call to invoke.
+ *   Omitting `tools` leaves the default toolset in place.
  * - `mcpServers: {}` so no MCP surface is reachable.
  * - `settingSources: []` plus an empty temp `cwd`, so there is no repo to act on
  *   and no ambient `AGENTS.md` / `.cursor` rule can steer a verdict.
+ * - `sandboxOptions: { enabled: false }` so grading never requests a local
+ *   sandbox. Omitting the field is not the same: a `~/.cursor/sandbox.json`
+ *   policy still counts as a sandbox request and throws on hosts that cannot
+ *   sandbox. With no tools left, there is nothing for a sandbox to confine.
  *
  * The prompt side is hardened separately: `evals/judge.ts` fences untrusted
- * content behind a per-call boundary. Both halves matter — this one limits blast
- * radius, that one removes the instruction channel.
+ * content behind a per-call boundary. Both halves matter — this one removes
+ * the tool channel, that one removes the instruction channel.
  *
  * Grading also declines outright when the credential's backend and the SDK's
  * backend disagree, rather than sending a key somewhere it was not minted for

package/dist/internal/eval-judge-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eval-judge-model.d.ts","sourceRoot":"","sources":["../../src/internal/eval-judge-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAoBhE;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,oBAAoB,EAAE,MAAM,EAC5B,UAAU,GAAE,MAAwB,GACnC,IAAI,CASN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,GAAG,YAAY,GAAG,SAAS,CAQ3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,eAoC5B,CAAC"}
+{"version":3,"file":"eval-judge-model.d.ts","sourceRoot":"","sources":["../../src/internal/eval-judge-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAoBhE;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,oBAAoB,EAAE,MAAM,EAC5B,UAAU,GAAE,MAAwB,GACnC,IAAI,CASN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,GAAG,YAAY,GAAG,SAAS,CAQ3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,eAyC5B,CAAC"}

package/dist/internal/eval-judge-model.js

@@ -7,17 +7,22 @@
  * prompt injection needs. A reply that talks the judge into running a tool would
  * do so on the machine running the eval CLI, under the runner's credentials.
  *
- * The session is therefore confined on every axis the SDK exposes:
+ * The session is therefore given nothing to act with:
  *
- * - `sandboxOptions.enabled` so any tool call the judge is talked into is
- *   confined rather than run directly against the host.
+ * - `tools: []` so the model is offered no built-in tools and can only reply
+ *   with text. An injected reply has no shell, file, or MCP call to invoke.
+ *   Omitting `tools` leaves the default toolset in place.
  * - `mcpServers: {}` so no MCP surface is reachable.
  * - `settingSources: []` plus an empty temp `cwd`, so there is no repo to act on
  *   and no ambient `AGENTS.md` / `.cursor` rule can steer a verdict.
+ * - `sandboxOptions: { enabled: false }` so grading never requests a local
+ *   sandbox. Omitting the field is not the same: a `~/.cursor/sandbox.json`
+ *   policy still counts as a sandbox request and throws on hosts that cannot
+ *   sandbox. With no tools left, there is nothing for a sandbox to confine.
  *
  * The prompt side is hardened separately: `evals/judge.ts` fences untrusted
- * content behind a per-call boundary. Both halves matter — this one limits blast
- * radius, that one removes the instruction channel.
+ * content behind a per-call boundary. Both halves matter — this one removes
+ * the tool channel, that one removes the instruction channel.
  *
  * Grading also declines outright when the credential's backend and the SDK's
  * backend disagree, rather than sending a key somewhere it was not minted for
@@ -89,30 +94,36 @@ export const callJudgeModel = async ({ prompt, model }) => {
     // Imported lazily so a tree of fully deterministic evals never loads the SDK.
     const { Agent } = await import("@cursor/sdk");
     const cwd = await mkdtemp(join(tmpdir(), "agentkit-eval-judge-"));
-    const agent = await Agent.create({
-        apiKey: resolved.apiKey,
-        model: typeof model === "string" ? { id: model } : model,
-        // See the module comment: grading embeds untrusted agent output, so the
-        // session gets no MCP surface, no ambient settings, an empty working
-        // directory, and a sandbox around anything it does attempt.
-        mcpServers: {},
-        local: {
-            cwd,
-            settingSources: [],
-            sandboxOptions: { enabled: true },
-        },
-    });
     try {
-        const run = await agent.send(prompt);
-        const result = await run.wait();
-        if (result.status === "error" || result.status === "cancelled") {
-            const detail = result.error?.message ?? result.result ?? result.status;
-            throw new Error(`eval judge run failed: ${detail}`);
+        const agent = await Agent.create({
+            apiKey: resolved.apiKey,
+            model: typeof model === "string" ? { id: model } : model,
+            // See the module comment: grading embeds untrusted agent output, so the
+            // session gets no tools, no MCP surface, no ambient settings, and an
+            // empty working directory. Sandbox is explicitly off so a per-user
+            // sandbox config cannot re-request one.
+            tools: [],
+            mcpServers: {},
+            local: {
+                cwd,
+                settingSources: [],
+                sandboxOptions: { enabled: false },
+            },
+        });
+        try {
+            const run = await agent.send(prompt);
+            const result = await run.wait();
+            if (result.status === "error" || result.status === "cancelled") {
+                const detail = result.error?.message ?? result.result ?? result.status;
+                throw new Error(`eval judge run failed: ${detail}`);
+            }
+            return result.result ?? "";
+        }
+        finally {
+            agent.close();
         }
-        return result.result ?? "";
     }
     finally {
-        agent.close();
         await rm(cwd, { recursive: true, force: true }).catch(() => undefined);
     }
 };

package/dist/internal/filesystem/subagent-inherit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Task-child inherit for an authored virtual root.
+ *
+ * The SDK calls `resourceProviderOptions` once per child session id,
+ * including nested `Task` grandchildren, and reuses that result for the
+ * child runtime. Each id gets its own {@link childOverlayFs} over the
+ * session union (authored tree plus `/tmp` scratch), so a child write
+ * cannot clobber the parent or a sibling. The FileSystem handle is not
+ * placed on the SDK request.
+ *
+ * Native executor overrides load on the first child. A static import
+ * would pull workspace-only packages into every CLI start. The published
+ * package omits that module; children then keep shell suppressed and
+ * reach the same overlay through synthesized file tools.
+ */
+import type { LocalSubagentInherit, LocalSubagentResourceProviderFields } from "@cursor/sdk";
+import { type FileSystem } from "../../filesystem.js";
+/**
+ * Structural view of the checkout-only executor module. Naming that module
+ * in a type query would pull it into `tsc -p tsconfig.build.json` even
+ * though the build config excludes it, and the published program cannot
+ * see its workspace-only imports.
+ */
+type ChildToolExecutor = NonNullable<LocalSubagentResourceProviderFields["overrideReadExecutor"]>;
+interface FileSystemExecutorModule {
+    createFileSystemReadExecutor(root: FileSystem): ChildToolExecutor;
+    createFileSystemWriteExecutor(root: FileSystem): ChildToolExecutor;
+    createFileSystemGrepExecutor(root: FileSystem): ChildToolExecutor;
+    createFileSystemLsExecutor(root: FileSystem): ChildToolExecutor;
+}
+export interface RootSubagentBinding {
+    readonly inherit: LocalSubagentInherit;
+    /** Overlay for a Task child. Do not pass the parent session id. */
+    fileSystemForSession(sessionId: string): FileSystem;
+}
+export declare function createRootSubagentInherit(parent: FileSystem): RootSubagentBinding;
+export declare function resourceFieldsForChild(overlay: FileSystem, executors: FileSystemExecutorModule | undefined): LocalSubagentResourceProviderFields;
+export {};
+//# sourceMappingURL=subagent-inherit.d.ts.map

package/dist/internal/filesystem/subagent-inherit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-inherit.d.ts","sourceRoot":"","sources":["../../../src/internal/filesystem/subagent-inherit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mCAAmC,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;;GAKG;AACH,KAAK,iBAAiB,GAAG,WAAW,CAAC,mCAAmC,CAAC,sBAAsB,CAAC,CAAC,CAAC;AAElG,UAAU,wBAAwB;IAChC,4BAA4B,CAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAC;IAClE,6BAA6B,CAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAC;IACnE,4BAA4B,CAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAC;IAClE,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAC;CACjE;AAUD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,mEAAmE;IACnE,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC;CACrD;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,UAAU,GAAG,mBAAmB,CAcjF;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,wBAAwB,GAAG,SAAS,GAC9C,mCAAmC,CAWrC"}

package/dist/internal/filesystem/subagent-inherit.js

@@ -0,0 +1,96 @@
+/**
+ * Task-child inherit for an authored virtual root.
+ *
+ * The SDK calls `resourceProviderOptions` once per child session id,
+ * including nested `Task` grandchildren, and reuses that result for the
+ * child runtime. Each id gets its own {@link childOverlayFs} over the
+ * session union (authored tree plus `/tmp` scratch), so a child write
+ * cannot clobber the parent or a sibling. The FileSystem handle is not
+ * placed on the SDK request.
+ *
+ * Native executor overrides load on the first child. A static import
+ * would pull workspace-only packages into every CLI start. The published
+ * package omits that module; children then keep shell suppressed and
+ * reach the same overlay through synthesized file tools.
+ */
+import { childOverlayFs } from "../../filesystem.js";
+/**
+ * Widened to `string` on purpose. A string-literal dynamic import is still
+ * a static dependency, so the published declaration build would compile the
+ * excluded executor module. Node and the test runner resolve this relative
+ * to this file.
+ */
+const FILE_SYSTEM_EXECUTORS_SPECIFIER = "../../filesystem-executors.js";
+export function createRootSubagentInherit(parent) {
+    const overlays = new Map();
+    return {
+        inherit: {
+            reportedWorkspacePath: "/",
+            resourceProviderOptions: async (context) => {
+                const overlay = childOverlayFor(overlays, parent, context.sessionId);
+                return resourceFieldsForChild(overlay, await loadFileSystemExecutors());
+            },
+        },
+        fileSystemForSession(sessionId) {
+            return childOverlayFor(overlays, parent, sessionId);
+        },
+    };
+}
+export function resourceFieldsForChild(overlay, executors) {
+    if (executors === undefined) {
+        return { suppressDefaultShellExecutor: true };
+    }
+    return {
+        overrideReadExecutor: executors.createFileSystemReadExecutor(overlay),
+        overrideWriteExecutor: executors.createFileSystemWriteExecutor(overlay),
+        overrideGrepExecutor: executors.createFileSystemGrepExecutor(overlay),
+        overrideLsExecutor: executors.createFileSystemLsExecutor(overlay),
+        suppressDefaultShellExecutor: true,
+    };
+}
+async function loadFileSystemExecutors() {
+    try {
+        const loaded = await import(FILE_SYSTEM_EXECUTORS_SPECIFIER);
+        if (!isFileSystemExecutorModule(loaded)) {
+            throw new Error("filesystem executors module is missing its factories");
+        }
+        return loaded;
+    }
+    catch (error) {
+        if (isMissingModule(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function isFileSystemExecutorModule(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.createFileSystemReadExecutor === "function" &&
+        typeof candidate.createFileSystemWriteExecutor === "function" &&
+        typeof candidate.createFileSystemGrepExecutor === "function" &&
+        typeof candidate.createFileSystemLsExecutor === "function");
+}
+function isMissingModule(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    if ("code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+        return true;
+    }
+    return "cause" in error && isMissingModule(error.cause);
+}
+function childOverlayFor(overlays, parent, sessionId) {
+    if (sessionId === undefined || sessionId === "") {
+        return childOverlayFs(parent);
+    }
+    const existing = overlays.get(sessionId);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = childOverlayFs(parent);
+    overlays.set(sessionId, created);
+    return created;
+}

package/dist/internal/filesystem/tools.d.ts

@@ -38,5 +38,11 @@ export declare function synthesizedFileSystemToolNames(options: {
 export declare function fileSystemTool(root: FileSystem, name: string, input?: Record<string, unknown>): DiscoveredTool | undefined;
 /** Validate and run the same tool a turn or `callTool` would. */
 export declare function runFileSystemTool(root: FileSystem, name: string, input?: Record<string, unknown>): Promise<unknown>;
+/**
+ * Run `fn` with synthesized file tools bound to `root`. Task children use
+ * this so Read/Write/Delete hit their overlay instead of the parent tree
+ * the tools were built against.
+ */
+export declare function runWithFileSystem<T>(root: FileSystem, fn: () => Promise<T>): Promise<T>;
 export declare function synthesizeFileSystemTools(root: FileSystem, filter?: readonly FileSystemToolName[]): DiscoveredTool[];
 //# sourceMappingURL=tools.d.ts.map

package/dist/internal/filesystem/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/internal/filesystem/tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,kBAAkB,EAYxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,gBAAgB,CAAC;AAgCrE,eAAO,MAAM,kCAAkC,YAC7C,MAAM,EACN,IAAI,EACJ,MAAM,EACN,MAAM,EACN,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,gBAAgB,CACR,CAAC;AAEX,MAAM,MAAM,6BAA6B,GAAG,CAAC,OAAO,kCAAkC,CAAC,CAAC,MAAM,CAAC,CAAC;AAIhG,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrE;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACnC,kBAAkB,EAAE,GAAG,SAAS,CAmBlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACnC,kBAAkB,EAAE,GAAG,SAAS,CAKlC;AAKD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,GAAG,SAAS,6BAA6B,EAAE,CAW3C;AA2lBD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,cAAc,GAAG,SAAS,CAS5B;AAED,iEAAiE;AACjE,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,OAAO,CAAC,OAAO,CAAC,CAclB;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,SAAS,kBAAkB,EAAE,GACrC,cAAc,EAAE,CAQlB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/internal/filesystem/tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,kBAAkB,EAYxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,gBAAgB,CAAC;AAgCrE,eAAO,MAAM,kCAAkC,YAC7C,MAAM,EACN,IAAI,EACJ,MAAM,EACN,MAAM,EACN,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,gBAAgB,CACR,CAAC;AAEX,MAAM,MAAM,6BAA6B,GAAG,CAAC,OAAO,kCAAkC,CAAC,CAAC,MAAM,CAAC,CAAC;AAIhG,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrE;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACnC,kBAAkB,EAAE,GAAG,SAAS,CAmBlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACnC,kBAAkB,EAAE,GAAG,SAAS,CAKlC;AAKD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,GAAG,SAAS,6BAA6B,EAAE,CAW3C;AA2lBD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,cAAc,GAAG,SAAS,CAS5B;AAED,iEAAiE;AACjE,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,OAAO,CAAC,OAAO,CAAC,CAclB;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvF;AA8BD,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,SAAS,kBAAkB,EAAE,GACrC,cAAc,EAAE,CAQlB"}

package/dist/internal/filesystem/tools.js

@@ -5,6 +5,7 @@
  * Each tool is a `defineTool` whose runtime `inputSchema` accepts those
  * fields plus the native aliases the harness still sends.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Buffer } from "node:buffer";
 import { minimatch } from "minimatch";
 import { z } from "zod";
@@ -600,11 +601,47 @@ export async function runFileSystemTool(root, name, input = {}) {
     }
     return execute(validation.value, {});
 }
+const fileSystemStorage = new AsyncLocalStorage();
+/**
+ * Run `fn` with synthesized file tools bound to `root`. Task children use
+ * this so Read/Write/Delete hit their overlay instead of the parent tree
+ * the tools were built against.
+ */
+export function runWithFileSystem(root, fn) {
+    return fileSystemStorage.run(root, fn);
+}
+function bindActiveFileSystem(root, tool) {
+    const execute = tool.definition.execute;
+    if (execute === undefined) {
+        return tool;
+    }
+    return {
+        ...tool,
+        definition: {
+            ...tool.definition,
+            execute: (input, ctx) => {
+                const active = fileSystemStorage.getStore();
+                if (active === undefined || active === root) {
+                    return execute(input, ctx);
+                }
+                const canonical = canonicalizeFileSystemToolName(tool.name);
+                if (canonical === undefined) {
+                    return execute(input, ctx);
+                }
+                const reboundExecute = FILE_SYSTEM_TOOL_FACTORIES[canonical](active).definition.execute;
+                if (reboundExecute === undefined) {
+                    return execute(input, ctx);
+                }
+                return reboundExecute(input, ctx);
+            },
+        },
+    };
+}
 export function synthesizeFileSystemTools(root, filter) {
     const tools = [];
     for (const name of SYNTHESIZED_FILE_SYSTEM_TOOL_NAMES) {
         if (wantsTool(filter, name)) {
-            tools.push(FILE_SYSTEM_TOOL_FACTORIES[name](root));
+            tools.push(bindActiveFileSystem(root, FILE_SYSTEM_TOOL_FACTORIES[name](root)));
         }
     }
     return tools;

package/dist/internal/hosted-catch-protocol.d.ts

@@ -21,6 +21,8 @@ export declare const AGENT_SDK_HTTP_CHANNEL_ID = "http";
 export declare const AGENT_SDK_HTTP_CHANNEL_KIND = "http";
 export declare const AGENT_SDK_SESSION_RESUME_KEY_PREFIX = "cont:session:";
 export declare const AGENT_SDK_CATCH_MAX_BODY_BYTES: number;
+/** Header a replayed request carries so handlers can dedupe on delivery. */
+export declare const CATCH_DELIVERY_ID_HEADER = "x-agent-sdk-delivery-id";
 export declare const AGENT_SDK_CATCH_ROUTE_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
 export type CatchRouteMethod = (typeof AGENT_SDK_CATCH_ROUTE_METHODS)[number];
 export type CatchRequestEnvelope = {

package/dist/internal/hosted-catch-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-catch-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-catch-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAClD,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AACzD,eAAO,MAAM,6BAA6B,WAAW,CAAC;AACtD,eAAO,MAAM,4BAA4B,qBAAqB,CAAC;AAC/D,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AACnE,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,eAAO,MAAM,2BAA2B,SAAS,CAAC;AAClD,eAAO,MAAM,mCAAmC,kBAAkB,CAAC;AACnE,eAAO,MAAM,8BAA8B,EAAE,MAAmB,CAAC;AAEjE,eAAO,MAAM,6BAA6B,YAAI,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAChG,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,MAAM,oBAAoB,GAAG;IACjC,CAAC,EAAE,CAAC,CAAC;IACL,MAAM,EAAE,gBAAgB,CAAC;IACzB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAEtE;AASD,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CA2C1F;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,GAAG,MAAM,CAK1E"}
+{"version":3,"file":"hosted-catch-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-catch-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAClD,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AACzD,eAAO,MAAM,6BAA6B,WAAW,CAAC;AACtD,eAAO,MAAM,4BAA4B,qBAAqB,CAAC;AAC/D,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AACnE,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,eAAO,MAAM,2BAA2B,SAAS,CAAC;AAClD,eAAO,MAAM,mCAAmC,kBAAkB,CAAC;AACnE,eAAO,MAAM,8BAA8B,EAAE,MAAmB,CAAC;AACjE,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAElE,eAAO,MAAM,6BAA6B,YAAI,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAChG,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,MAAM,oBAAoB,GAAG;IACjC,CAAC,EAAE,CAAC,CAAC;IACL,MAAM,EAAE,gBAAgB,CAAC;IACzB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAEtE;AASD,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CA2C1F;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,GAAG,MAAM,CAK1E"}

package/dist/internal/hosted-catch-protocol.js

@@ -22,6 +22,8 @@ export const AGENT_SDK_HTTP_CHANNEL_ID = "http";
 export const AGENT_SDK_HTTP_CHANNEL_KIND = "http";
 export const AGENT_SDK_SESSION_RESUME_KEY_PREFIX = "cont:session:";
 export const AGENT_SDK_CATCH_MAX_BODY_BYTES = 256 * 1024;
+/** Header a replayed request carries so handlers can dedupe on delivery. */
+export const CATCH_DELIVERY_ID_HEADER = "x-agent-sdk-delivery-id";
 export const AGENT_SDK_CATCH_ROUTE_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 /**
  * Mailbox key the control plane stamps on an explicit `ses_…` resume. The

package/dist/internal/hosted-catch.d.ts

@@ -10,9 +10,8 @@
  * a handler that answers without sending is a `skip`.
  */
 import type { AuthContext, ChannelDefinition, ChannelHandlerArgs, ChannelRoute } from "../types.js";
-import { type CatchRequestEnvelope } from "./hosted-catch-protocol.js";
-/** Header a replayed request carries so handlers can dedupe on delivery. */
-export declare const CATCH_DELIVERY_ID_HEADER = "x-agent-sdk-delivery-id";
+import { CATCH_DELIVERY_ID_HEADER, type CatchRequestEnvelope } from "./hosted-catch-protocol.js";
+export { CATCH_DELIVERY_ID_HEADER };
 /**
  * Principal for a replayed request. The deployment secret was checked by
  * the control plane before compute existed; the channel's own auth chain

package/dist/internal/hosted-catch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-catch.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-catch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMpG,OAAO,EAGL,KAAK,oBAAoB,EAG1B,MAAM,4BAA4B,CAAC;AAIpC,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAIlE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAIhC,CAAC;AAIF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,oBAAoB,CAAC;CAChC,GAAG,OAAO,CAcV;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiFpB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,IAAI,CAgBN"}
+{"version":3,"file":"hosted-catch.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-catch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMpG,OAAO,EAGL,wBAAwB,EACxB,KAAK,oBAAoB,EAG1B,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAIpC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAIhC,CAAC;AAIF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,oBAAoB,CAAC;CAChC,GAAG,OAAO,CAcV;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiFpB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,IAAI,CAgBN"}

package/dist/internal/hosted-catch.js

@@ -14,11 +14,10 @@ import { classifyHostedAdmissionRejection } from "./hosted-delivery-protocol.js"
 import { invokeChannelRoute } from "./channel-route-dispatch.js";
 import { DeferredChannelSessionError } from "./deferred-channel-session.js";
 import { attachHostedAdmissionAdapter } from "./hosted-admission-adapter.js";
-import { AGENT_SDK_CATCH_EVENT_TYPE, AGENT_SDK_CUSTOM_CHANNEL_KIND, decodeCatchBody, parseCatchRequestEnvelope, } from "./hosted-catch-protocol.js";
+import { AGENT_SDK_CATCH_EVENT_TYPE, AGENT_SDK_CUSTOM_CHANNEL_KIND, CATCH_DELIVERY_ID_HEADER, decodeCatchBody, parseCatchRequestEnvelope, } from "./hosted-catch-protocol.js";
 import { errorResponse } from "./http-channel.js";
 import { Router } from "./router.js";
-/** Header a replayed request carries so handlers can dedupe on delivery. */
-export const CATCH_DELIVERY_ID_HEADER = "x-agent-sdk-delivery-id";
+export { CATCH_DELIVERY_ID_HEADER };
 /** Placeholder origin for replayed requests; handlers see a well-formed URL. */
 const CATCH_REQUEST_ORIGIN = "http://agent-sdk.hosted";
 /**

package/dist/internal/hosted-delivery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-delivery.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-delivery.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hosted-delivery.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-delivery.ts"],"names":[],"mappings":"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"}

package/dist/internal/hosted-delivery.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { metrics } from "@opentelemetry/api";
+import { metrics, trace } from "@opentelemetry/api";
 import { packageVersion } from "./distribution.js";
 import { dispatchOutcome } from "./channel-dispatch.js";
 import { consumeHostedBoundSecrets, } from "./cursor/hosted-bound-secrets.js";
@@ -11,7 +11,7 @@ import { getHostedAdmissionAdapter, } from "./hosted-admission-adapter.js";
 import { HostedAdmissionLocalSendError, runDuringHostedAdmission, } from "./hosted-admission-context.js";
 import { HOSTED_ADMISSION_PATH, HOSTED_DELIVERY_HEADER, HOSTED_DELIVERY_PROTOCOL_VERSION, HOSTED_EXECUTION_PATH, HOSTED_GUEST_RETRY_TERMINAL, HOSTED_GUEST_RETRY_TRANSIENT, HOSTED_MAX_CONSUMED_DELIVERY_IDS, hostedFailureClassification, hostedGuestErrorResponse, isHostedReminderAdmission, isHostedScheduleAdmission, parseHostedAdmissionHandlerRejection, parseHostedAdmission, parseHostedExecution, parseHostedReminderFireDescriptorPayload, parseHostedReminderFirePayload, parseHostedScheduleFirePayload, } from "./hosted-delivery-protocol.js";
 import { abortReasonFromTurnStatus, HOSTED_EXECUTION_DIAG_RUNNING_STATUS, hostedExecutionDiagId, } from "./hosted-execution-diag.js";
-import { flushHostedExecutionRecord, refreshStartLogWhile, } from "./hosted-execution-flush.js";
+import { flushDurableHostedExecutionRecord, refreshStartLogWhile, writeLocalHostedExecutionRecord, } from "./hosted-execution-flush.js";
 import { finalizeHostedExecutionLatency, formatHostedExecutionLatencyServerTiming, hostedExecutionNow, runWithHostedExecutionLatency, } from "./hosted-execution-latency.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { readJsonObject } from "./http-channel.js";
@@ -482,11 +482,16 @@ export function registerHostedDeliveryRoute(input) {
             if (definition === undefined) {
                 return await responseToReply(finish(terminalHostedError(404, "channel_not_found", `No channel named "${delivery.channelId}" is mounted.`)));
             }
+            const endHandler = startHostedSpan("admission.handler", {
+                "agent_sdk.channel_kind": delivery.channelKind,
+                "agent_sdk.delivery_id": delivery.deliveryId,
+            });
             const admitted = await dispatchHostedAdmission({
                 delivery,
                 definition,
                 args: input.buildHandlerArgs(delivery.channelId),
             });
+            endHandler();
             if (admitted.pendingSend === undefined) {
                 return await responseToReply(finish(admitted.response));
             }
@@ -682,7 +687,13 @@ export function registerHostedDeliveryRoute(input) {
                 admitted.expiresAt = Date.now() + ownerTurnPendingTtlMs;
             }
             admitted.execution ??= afterHostedWork(input.flushOtel, async () => {
+                const spanAttributes = {
+                    "agent_sdk.channel_kind": admitted.channelKind,
+                    "agent_sdk.session_public_id": execution.sessionPublicId,
+                };
+                const endNetworkWait = startHostedSpan("execute.network_wait", spanAttributes);
                 const network = await finishNetworkWait("execution");
+                endNetworkWait();
                 guestNetwork = network.timing;
                 if (network.response !== undefined) {
                     return await responseToReply(finish(network.response));
@@ -697,11 +708,14 @@ export function registerHostedDeliveryRoute(input) {
                     ...(input.flushStartLog === undefined ? {} : { flushStartLog: input.flushStartLog }),
                     ...(input.snapshotLogs === undefined ? {} : { snapshotLogs: input.snapshotLogs }),
                 };
-                const writeDiag = async (fields) => {
+                // Store writes are chained so a slow `running` write cannot land
+                // after the terminal one.
+                let durableWrites = Promise.resolve();
+                const writeDiag = async (fields, options) => {
                     const classification = fields.failureCode === undefined
                         ? undefined
                         : hostedFailureClassification(fields.failureCode);
-                    await flushHostedExecutionRecord(sinks, {
+                    const record = {
                         executionId,
                         sessionPublicId: execution.sessionPublicId,
                         sessionId: fields.sessionId,
@@ -713,16 +727,25 @@ export function registerHostedDeliveryRoute(input) {
                         ...(fields.errorCode === undefined ? {} : { errorCode: fields.errorCode }),
                         classification,
                         ...(fields.error === undefined ? {} : { error: fields.error }),
-                    });
+                    };
+                    const writtenAt = new Date().toISOString();
+                    await writeLocalHostedExecutionRecord(sinks, record, writtenAt);
+                    durableWrites = durableWrites.then(() => flushDurableHostedExecutionRecord(sinks, record, writtenAt));
+                    if (options.awaitDurable) {
+                        await durableWrites;
+                    }
                 };
-                // Claim the file before the turn runs. If a later status request
-                // fails, the host reads this record while the turn may still be
-                // running; the marker prevents it from surfacing the previous
-                // delivery's terminal record.
+                // Claim the local file before the turn runs. If a later status
+                // request fails, the host reads this record while the turn may
+                // still be running; the marker prevents it from surfacing the
+                // previous delivery's terminal record. The store copies are
+                // dashboard history, so the turn does not wait on them.
+                const endClaim = startHostedSpan("execute.claim", spanAttributes);
                 await writeDiag({
                     sessionId: "",
                     turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
-                });
+                }, { awaitDurable: false });
+                endClaim();
                 let sessionId = "";
                 const owner = {
                     primaryDeliveryId: admitted.deliveryId,
@@ -743,6 +766,7 @@ export function registerHostedDeliveryRoute(input) {
                                 key: admitted.send.mailboxContinuationKey,
                             },
                         };
+                        const endSend = startHostedSpan("execute.send", spanAttributes);
                         const session = input.startSend === undefined
                             ? await args.send(admitted.send.message, options)
                             : await input.startSend({
@@ -751,6 +775,7 @@ export function registerHostedDeliveryRoute(input) {
                                 options,
                                 sessionPublicId: execution.sessionPublicId,
                             });
+                        endSend();
                         sessionId = session.id;
                         // The pre-turn claim used an empty sessionId. Stamp the
                         // engine id now so a dashboard / session-view poll that
@@ -758,7 +783,7 @@ export function registerHostedDeliveryRoute(input) {
                         await writeDiag({
                             sessionId,
                             turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
-                        });
+                        }, { awaitDurable: false });
                         const outcome = await refreshStartLogWhile(sinks, execution.sessionPublicId, () => session.waitForCompletion());
                         completionAt = hostedExecutionNow();
                         // Status is the owner turn. waitForCompletion still waited
@@ -796,7 +821,7 @@ export function registerHostedDeliveryRoute(input) {
                             abortReason: abortReasonFromTurnStatus(outcome.status, outcome.cancellationReason),
                             failureCode: hostedFailure?.error,
                             ...(outcome.errorCode === undefined ? {} : { errorCode: outcome.errorCode }),
-                        });
+                        }, { awaitDurable: true });
                         const reply = hostedFailure !== undefined
                             ? {
                                 status: 503,
@@ -845,7 +870,7 @@ export function registerHostedDeliveryRoute(input) {
                             failureCode: "internal_error",
                             error,
                             ...(thrownErrorCode === undefined ? {} : { errorCode: thrownErrorCode }),
-                        });
+                        }, { awaitDurable: true });
                         const endedAt = hostedExecutionNow();
                         // Preserve completion/drain marks when the failure happened
                         // during post-drain work; otherwise collapse to endedAt.
@@ -1023,6 +1048,14 @@ function hostedFailureForUnfinishedTurn(outcome) {
     }
     return { error: "turn_failed", retry: HOSTED_GUEST_RETRY_TERMINAL };
 }
+/**
+ * `agent_sdk.hosted.<step>` span; call the result to end it. The delivery
+ * replies before this work finishes, so the inbound HTTP span never covers it.
+ */
+function startHostedSpan(step, attributes) {
+    const span = trace.getTracer("agent_sdk").startSpan(`agent_sdk.hosted.${step}`, { attributes });
+    return () => span.end();
+}
 async function afterHostedWork(flushOtel, work) {
     try {
         const result = await work();

package/dist/internal/hosted-execution-flush.d.ts

@@ -32,11 +32,14 @@ export type HostedExecutionFlushFields = {
     classification?: HostedFailureClassification;
     error?: unknown;
 };
+/** The guest-disk diagnostic the host reads after a failed execute. */
+export declare function writeLocalHostedExecutionRecord(sinks: HostedExecutionFlushSinks, fields: HostedExecutionFlushFields, writtenAt: string): Promise<void>;
 /**
- * Write local diagnostics and durable output together. Soft-fail per sink so
- * a storage outage does not change the hosted response.
+ * Store-backed execution history and process output. Never rejects. Both
+ * sinks start synchronously, so their crash-flush state is stamped before
+ * either store round trip.
  */
-export declare function flushHostedExecutionRecord(sinks: HostedExecutionFlushSinks, fields: HostedExecutionFlushFields): Promise<void>;
+export declare function flushDurableHostedExecutionRecord(sinks: HostedExecutionFlushSinks, fields: HostedExecutionFlushFields, writtenAt: string): Promise<void>;
 /**
  * Each refresh is a store write on the deployment's shared write budget, so
  * keep it coarse. An unchanged tee costs nothing (the store skips the put).

package/dist/internal/hosted-execution-flush.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-execution-flush.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-execution-flush.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EACL,KAAK,8BAA8B,EAGpC,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAG9B,MAAM,sBAAsB,CAAC;AAU9B,MAAM,MAAM,yBAAyB,GAAG;IACtC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,aAAa,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,8BAA8B,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,2BAA2B,CAAC;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,IAAI,CAAC,CAgDf;AAED;;;GAGG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAE3D;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,KAAK,EAAE,yBAAyB,EAChC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAqBZ;AAED;;GAEG;AACH,wBAAsB,gCAAgC,CAAC,IAAI,EAAE;IAC3D,iBAAiB,EAAE,CACjB,MAAM,EAAE,OAAO,CACb,qBAAqB,EACrB,cAAc,GAAG,oBAAoB,GAAG,qBAAqB,CAC9D,EACD,KAAK,CAAC,EAAE,OAAO,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CACb,qBAAqB,EACrB,cAAc,GAAG,oBAAoB,GAAG,qBAAqB,CAC9D,CAAC;IACF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB"}
+{"version":3,"file":"hosted-execution-flush.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-execution-flush.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EACL,KAAK,8BAA8B,EAGpC,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAG9B,MAAM,sBAAsB,CAAC;AAU9B,MAAM,MAAM,yBAAyB,GAAG;IACtC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,aAAa,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,8BAA8B,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,2BAA2B,CAAC;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,uEAAuE;AACvE,wBAAsB,+BAA+B,CACnD,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,0BAA0B,EAClC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;GAIG;AACH,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,0BAA0B,EAClC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;GAGG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAE3D;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,KAAK,EAAE,yBAAyB,EAChC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAqBZ;AAED;;GAEG;AACH,wBAAsB,gCAAgC,CAAC,IAAI,EAAE;IAC3D,iBAAiB,EAAE,CACjB,MAAM,EAAE,OAAO,CACb,qBAAqB,EACrB,cAAc,GAAG,oBAAoB,GAAG,qBAAqB,CAC9D,EACD,KAAK,CAAC,EAAE,OAAO,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CACb,qBAAqB,EACrB,cAAc,GAAG,oBAAoB,GAAG,qBAAqB,CAC9D,CAAC;IACF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB"}