@cursor/july 0.1.95 → 0.1.97

package/dist/internal/framework-file-storage.js

@@ -0,0 +1,210 @@
+/**
+ * Framework-level file storage for v2 hosted engines.
+ *
+ * Hosted deployments carry two file stores with different audiences:
+ *
+ * - the **user-level** store (`AGENT_SERVE_STORE_SOURCE_ID`) holds
+ *   author-facing bytes — `ctx.host.files`, skills, memory, artifacts — and
+ *   is browsable from the dashboard and mountable on cloud-runtime VMs;
+ * - the **framework-level** store (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`)
+ *   holds engine-owned session state — session records, event transcripts,
+ *   the continuation index, and the SDK conversation mirror — and is never
+ *   exposed to authors or models.
+ *
+ * This module puts framework session state on the framework store. The
+ * {@link storageKeys} scheme was designed for exactly this: keys are a
+ * stable versioned contract that sinks may route on, so
+ * {@link composeFrameworkStorage} splits one {@link StorageConfig} by key
+ * kind — `session` / `session-events` / `continuation` go to the framework
+ * file store (file-shaped; the store accepts values up to 64 MiB per
+ * object without chunking, versus the KV proxy's 1 MiB row cap), while
+ * author `kv`, eval runs, A/B samples, and conditional writes stay on the
+ * control-plane KV proxy (the dashboard reads them there, and CAS needs a
+ * database).
+ *
+ * v2 only, by construction: the composite is selected in
+ * framework-storage-selection.ts, which v1 never reaches with a
+ * platform-selected definition.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import { mapBounded } from "./bounded.js";
+/**
+ * Key kinds (`agentkit/v1/{agent}/{kind}/…`) that live on the framework
+ * file store. Everything else stays on the KV sink.
+ */
+const FRAMEWORK_FILE_KINDS = new Set([
+    "session",
+    "session-events",
+    "continuation",
+]);
+/**
+ * Whether a framework-minted key (or list prefix) belongs on the framework
+ * file store. Prefixes used by the coordinator are always at least
+ * kind-scoped (`…/{agent}/session/`), so a prefix routes wholly to one side.
+ */
+export function isFrameworkFileKey(key) {
+    if (!key.startsWith(`${STORAGE_KEY_ROOT}/`)) {
+        return false;
+    }
+    const rest = key.slice(STORAGE_KEY_ROOT.length + 1);
+    const agentEnd = rest.indexOf("/");
+    if (agentEnd === -1) {
+        return false;
+    }
+    const afterAgent = rest.slice(agentEnd + 1);
+    const kindEnd = afterAgent.indexOf("/");
+    const kind = kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
+    return FRAMEWORK_FILE_KINDS.has(kind);
+}
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
+/** Parallel per-key reads backing `list` (each is presign + object GET). */
+const LIST_READ_CONCURRENCY = 8;
+/**
+ * A storage key whose path the file store cannot represent (an empty, `.`,
+ * or `..` segment — possible only through caller-controlled segments such
+ * as continuation tokens or a caller-supplied session id). Such an object
+ * can never exist in the store, so reads are a definitive miss rather than
+ * a per-request 400 that the lazy-restore path would propagate forever.
+ */
+function isUnrepresentableFileKey(key) {
+    return key
+        .split("/")
+        .some((segment) => segment === "" || segment === "." || segment === "..");
+}
+export function fileSinkStorageCore(sink) {
+    return {
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (isUnrepresentableFileKey(key)) {
+                    // Loud rather than silent: the coordinator logs and drops failed
+                    // mirror writes (at-most-once), and awaited callers must not
+                    // believe an impossible write landed.
+                    throw new Error(`framework file storage: key "${key}" has a path segment the store cannot represent`);
+                }
+                yield sink.put(key, new TextEncoder().encode(JSON.stringify(value)));
+            });
+        },
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (isUnrepresentableFileKey(key)) {
+                    return undefined;
+                }
+                const body = yield sink.get(key);
+                if (body === undefined) {
+                    return undefined;
+                }
+                return decodeDocument(key, body instanceof Uint8Array ? body : body.body);
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (isUnrepresentableFileKey(key)) {
+                    return;
+                }
+                yield sink.delete(key);
+            });
+        },
+        list(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const entries = yield sink.list(prefix);
+                // FileSink.list returns metadata only, so each value is its own
+                // read; bound the fan-out — a bulk read here sits on restore paths.
+                const bodies = yield mapBounded(entries, LIST_READ_CONCURRENCY, (entry) => sink.get(entry.key));
+                const out = [];
+                for (let index = 0; index < entries.length; index += 1) {
+                    const entry = entries[index];
+                    const body = bodies[index];
+                    if (entry === undefined || body === undefined) {
+                        // Deleted between list and read; a miss is not corruption.
+                        continue;
+                    }
+                    out.push({
+                        key: entry.key,
+                        value: decodeDocument(entry.key, body instanceof Uint8Array ? body : body.body),
+                    });
+                }
+                return out;
+            });
+        },
+    };
+}
+function decodeDocument(key, bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (error) {
+        throw new Error(`framework file storage: stored document at "${key}" is not JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+/**
+ * Split one storage core by key kind: framework session state to `files`,
+ * everything else to `kv`. Spread over the KV backend when building the
+ * full definition so its `evals` / `abs` groups (and the cursor-hosted
+ * marker) ride along untouched; wrap the KV `cas` group with
+ * {@link frameworkGuardedCas} rather than spreading it as-is.
+ */
+export function composeFrameworkStorage(input) {
+    const route = (key) => isFrameworkFileKey(key) ? input.files : input.kv;
+    return {
+        put: (key, value, ctx) => route(key).put(key, value, ctx),
+        get: (key, ctx) => route(key).get(key, ctx),
+        delete: (key, ctx) => route(key).delete(key, ctx),
+        list: (prefix, ctx) => route(prefix).list(prefix, ctx),
+        // Session records — the only `listNewest` consumer — are framework file
+        // keys, and the file store has no write-time ordering. Spreading the KV
+        // backend's `listNewest` through would query rows that live elsewhere
+        // (stale KV leftovers, or nothing), so the composed core explicitly has
+        // none and the engine falls back to the routed `list`.
+        listNewest: undefined,
+    };
+}
+/**
+ * The KV backend's conditional writes, refusing framework-file keys.
+ *
+ * CAS runs on the KV proxy (a database row version); the plain core routes
+ * framework session state to the file store. A future coordination path
+ * that CASes a `session/` or `continuation/` key would otherwise read and
+ * write a different store than the plain path — silent split-brain. Fail
+ * loudly instead; nothing in the package CASes those kinds today.
+ */
+export function frameworkGuardedCas(cas) {
+    const refuse = (key) => {
+        if (isFrameworkFileKey(key)) {
+            throw new Error(`framework file storage: conditional writes are KV-only, but "${key}" routes to the framework file store`);
+        }
+    };
+    return {
+        getWithVersion: (key, ctx) => {
+            refuse(key);
+            return cas.getWithVersion(key, ctx);
+        },
+        putIfAbsent: (key, value, ctx) => {
+            refuse(key);
+            return cas.putIfAbsent(key, value, ctx);
+        },
+        putIfVersion: (key, value, expectedVersion, ctx) => {
+            refuse(key);
+            return cas.putIfVersion(key, value, expectedVersion, ctx);
+        },
+        listKeys: (prefix, ctx) => {
+            refuse(prefix);
+            return cas.listKeys(prefix, ctx);
+        },
+    };
+}

package/dist/internal/framework-storage-selection.d.ts

@@ -17,11 +17,17 @@
  *
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
- *   the Cursor-hosted backend, so session records, event chunks, `host.kv`,
- *   eval runs, and A/B samples land in the control plane and survive pod
- *   replacement. The API key resolves through the full credential chain on
- *   every call because hosted freeze snapshots listen unsigned and the
- *   binder drops the key file after restore.
+ *   the Cursor-hosted backend. When the deployment carries a
+ *   **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), session records, event
+ *   transcripts, and the continuation index live there — file-shaped state
+ *   on file storage, apart from the author-facing user store — while
+ *   `host.kv`, eval runs, A/B samples, and conditional writes stay on the
+ *   control-plane KV proxy (see framework-file-storage.ts). Without one
+ *   (a deploy predating framework-store provisioning), everything goes to
+ *   the KV proxy as before. The API key resolves through the full
+ *   credential chain on every call because hosted freeze snapshots listen
+ *   unsigned and the binder drops the key file after restore.
  * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
  *   is correct when the operator owns the disk.
  *

package/dist/internal/framework-storage-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"framework-storage-selection.d.ts","sourceRoot":"","sources":["../../src/internal/framework-storage-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD,MAAM,WAAW,8BAA8B;IAC7C,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACtD,iEAAiE;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,GAAG,SAAS,CA2B/B"}
+{"version":3,"file":"framework-storage-selection.d.ts","sourceRoot":"","sources":["../../src/internal/framework-storage-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAMH,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AASrD,MAAM,WAAW,8BAA8B;IAC7C,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACtD,iEAAiE;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,GAAG,SAAS,CAoD/B"}

package/dist/internal/framework-storage-selection.js

@@ -17,11 +17,17 @@
  *
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
- *   the Cursor-hosted backend, so session records, event chunks, `host.kv`,
- *   eval runs, and A/B samples land in the control plane and survive pod
- *   replacement. The API key resolves through the full credential chain on
- *   every call because hosted freeze snapshots listen unsigned and the
- *   binder drops the key file after restore.
+ *   the Cursor-hosted backend. When the deployment carries a
+ *   **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), session records, event
+ *   transcripts, and the continuation index live there — file-shaped state
+ *   on file storage, apart from the author-facing user store — while
+ *   `host.kv`, eval runs, A/B samples, and conditional writes stay on the
+ *   control-plane KV proxy (see framework-file-storage.ts). Without one
+ *   (a deploy predating framework-store provisioning), everything goes to
+ *   the KV proxy as before. The API key resolves through the full
+ *   credential chain on every call because hosted freeze snapshots listen
+ *   unsigned and the binder drops the key file after restore.
  * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
  *   is correct when the operator owns the disk.
  *
@@ -33,10 +39,12 @@
  * the session store; what this selects is the durable mirror *beyond* the
  * pod's filesystem.
  */
+import { cursorFrameworkStoreSourceId, cursorHostedFiles, } from "../files-backends/cursor-hosted.js";
 import { defineStorage } from "../storage.js";
 import { cursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { composeFrameworkStorage, fileSinkStorageCore, frameworkGuardedCas, } from "./framework-file-storage.js";
 /**
  * Pick the backend for framework session state.
  *
@@ -60,10 +68,29 @@ export function selectFrameworkStorageDefinition(input) {
         // Self-hosted v2: the state root is the durable copy.
         return undefined;
     }
-    return defineStorage(Object.assign({ name: "cursor-hosted" }, cursorHostedStorage({
-        // Full chain (env → key file → stored login): frozen engines listen
-        // unsigned and bind CURSOR_API_KEY_FILE at task time, after this
-        // definition is constructed.
-        apiKey: () => { var _a; return (_a = resolveApiKeySync()) === null || _a === void 0 ? void 0 : _a.apiKey; },
-    })));
+    // Hosted v2 pods wake per delivery: bulk-restoring up to the default
+    // 1000 sessions on every boot is waste (and against the file-store
+    // backend it is per-key HTTP round trips before the listener even
+    // comes up). Follow-ups restore lazily by continuation or session id;
+    // GET /v1/sessions lists from the sink either way.
+    const policy = { restore: "off" };
+    // Full chain (env → key file → stored login): frozen engines listen
+    // unsigned and bind CURSOR_API_KEY_FILE at task time, after this
+    // definition is constructed.
+    const resolveApiKey = () => { var _a; return (_a = resolveApiKeySync()) === null || _a === void 0 ? void 0 : _a.apiKey; };
+    const kv = cursorHostedStorage({ resolveApiKey });
+    const frameworkStoreId = cursorFrameworkStoreSourceId(env);
+    if (frameworkStoreId === undefined) {
+        return defineStorage(Object.assign({ name: "cursor-hosted", policy }, kv));
+    }
+    // Framework session state on the framework-level file store; author kv,
+    // evals, and A/B tables stay on the KV proxy (spread from `kv`, which
+    // also carries the cursor-hosted marker for GET /v1/sessions).
+    return defineStorage(Object.assign(Object.assign(Object.assign({ name: "cursor-hosted (framework files)", policy }, kv), composeFrameworkStorage({
+        kv,
+        files: fileSinkStorageCore(cursorHostedFiles({ storeSourceId: frameworkStoreId, resolveApiKey })),
+    })), { 
+        // CAS stays on the KV proxy but must refuse framework-file keys, or a
+        // future coordination path would split-brain against the plain core.
+        cas: frameworkGuardedCas(kv.cas) }));
 }

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

@@ -2,6 +2,13 @@ export declare const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
 export declare const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
 export declare const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
 export declare const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
+/**
+ * Filename under the serve `--state-root` (not the per-slug SessionEngine
+ * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
+ * reads this path after hosted-execution and logs it on the activity span.
+ * Must match `AGENT_SERVE_ENGINE_HOSTED_EXECUTION_DIAG_PATH` basename.
+ */
+export declare const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
 export type HostedAdmissionManagedAutomation = {
     automationUuid: string;
     mcpServerNames: string[];

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

@@ -1 +1 @@
-{"version":3,"file":"hosted-delivery-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-delivery-protocol.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAClD,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AACpE,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AACrE,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAErE,MAAM,MAAM,gCAAgC,GAAG;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,EAAE,CAAC,CAAC;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,QAAQ,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,GAAG,cAAc,CAAC;IACtC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,gCAAgC,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,CAAC,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,CAAC,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,EAAE,CAAC,CAAC;IACL,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,CAAC,EAAE,CAAC,CAAC;IACL,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAsDF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,eAAe,GAAG,SAAS,CAuB7B;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,eAAe,GAAG,SAAS,CAe7B;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,sBAAsB,GAAG,SAAS,CAkBpC"}
+{"version":3,"file":"hosted-delivery-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-delivery-protocol.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAClD,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AACpE,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AACrE,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AACrE;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,0BAA0B,CAAC;AAEtE,MAAM,MAAM,gCAAgC,GAAG;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,EAAE,CAAC,CAAC;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,QAAQ,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,GAAG,cAAc,CAAC;IACtC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,gCAAgC,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,CAAC,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,CAAC,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,EAAE,CAAC,CAAC;IACL,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,CAAC,EAAE,CAAC,CAAC;IACL,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAsDF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,eAAe,GAAG,SAAS,CAuB7B;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,eAAe,GAAG,SAAS,CAe7B;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,sBAAsB,GAAG,SAAS,CAkBpC"}

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

@@ -2,6 +2,13 @@ export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
 export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
 export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
 export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
+/**
+ * Filename under the serve `--state-root` (not the per-slug SessionEngine
+ * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
+ * reads this path after hosted-execution and logs it on the activity span.
+ * Must match `AGENT_SERVE_ENGINE_HOSTED_EXECUTION_DIAG_PATH` basename.
+ */
+export const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
 const DELIVERY_KEYS = new Set([
     "v",
     "channelId",

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

@@ -32,6 +32,19 @@ export declare function registerHostedDeliveryRoute(input: {
         definition: object;
     }>;
     buildHandlerArgs(channelId: string, sessionPublicId?: string): ChannelHandlerArgs;
+    /**
+     * Await the session's durable mirror (dispatch chain + storage queue)
+     * before the execution reply: the control plane may park the pod the
+     * moment the reply lands, and a shed session-record flush would strand
+     * the conversation on the next wake.
+     */
+    drainSessionDurability?(sessionId: string): Promise<void>;
+    /**
+     * Serve `--state-root` (not the per-slug SessionEngine dir). Hosted
+     * freeze is `/workspace/.agent-serve`; the Temporal host reads
+     * `hosted-execution.json` from that path after the POST returns.
+     */
+    stateRoot?: string;
 }): void;
 export {};
 //# sourceMappingURL=hosted-delivery.d.ts.map

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":"AAOA,OAAO,KAAK,EAEV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AASrB,OAAO,EAKL,KAAK,eAAe,EAGrB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,aAAa,GAAG;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B,CAAC;AA6DF;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AA2GD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,MAAM,GACvB,kBAAkB,CAAC;CACvB,GAAG,IAAI,CAsKP"}
+{"version":3,"file":"hosted-delivery.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-delivery.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAEV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AASrB,OAAO,EAKL,KAAK,eAAe,EAGrB,MAAM,+BAA+B,CAAC;AASvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,aAAa,GAAG;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B,CAAC;AA6DF;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AA2GD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,MAAM,GACvB,kBAAkB,CAAC;IACtB;;;;;OAKG;IACH,sBAAsB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAsOP"}

package/dist/internal/hosted-delivery.js

@@ -12,6 +12,7 @@ import { dispatchGitHubWebhook, getGitHubChannelOptions, getGitHubDispatchOutcom
 import { createDeferredChannelSession, DeferredChannelSessionError, } from "./deferred-channel-session.js";
 import { HostedAdmissionLocalSendError, runDuringHostedAdmission, } from "./hosted-admission-context.js";
 import { HOSTED_ADMISSION_PATH, HOSTED_DELIVERY_HEADER, HOSTED_DELIVERY_PROTOCOL_VERSION, HOSTED_EXECUTION_PATH, parseHostedAdmission, parseHostedExecution, } from "./hosted-delivery-protocol.js";
+import { abortReasonFromTurnStatus, HOSTED_EXECUTION_DIAG_RUNNING_STATUS, hostedExecutionDiagId, writeHostedExecutionDiag, } from "./hosted-execution-diag.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { errorResponse, readJsonObject } from "./http-channel.js";
 /**
@@ -247,30 +248,74 @@ export function registerHostedDeliveryRoute(input) {
             }
             admitted.sessionPublicId = execution.sessionPublicId;
             (_a = admitted.execution) !== null && _a !== void 0 ? _a : (admitted.execution = (() => __awaiter(this, void 0, void 0, function* () {
-                const args = input.buildHandlerArgs(admitted.send.channelId, execution.sessionPublicId);
-                const session = yield args.send(admitted.send.message, Object.assign(Object.assign({}, admitted.send.options), { mailboxContinuation: {
-                        key: admitted.send.mailboxContinuationKey,
-                    } }));
-                const outcome = yield session.waitForCompletion();
-                if (outcome.status !== "finished") {
+                var _a;
+                const startedAt = performance.now();
+                const executionId = hostedExecutionDiagId(execution.admissionToken);
+                const writeDiag = (fields) => __awaiter(this, void 0, void 0, function* () {
+                    if (input.stateRoot === undefined) {
+                        return;
+                    }
+                    const message = fields.message === undefined
+                        ? undefined
+                        : boundedMessage(fields.message);
+                    yield writeHostedExecutionDiag(input.stateRoot, Object.assign(Object.assign(Object.assign({ v: 1, executionId, writtenAt: new Date().toISOString(), sessionPublicId: execution.sessionPublicId, sessionId: fields.sessionId, turnStatus: fields.turnStatus, durationMs: Math.max(0, Math.round(performance.now() - startedAt)) }, (message === undefined ? {} : { message })), (message !== undefined && /abort/i.test(message)
+                        ? { signalAborted: true }
+                        : {})), (fields.abortReason === undefined
+                        ? {}
+                        : { abortReason: fields.abortReason })));
+                });
+                // Claim the file before the turn runs. The host reads it after its
+                // own POST returns, which for a 9-minute timeout is while this turn
+                // is still going; without this marker that read would surface the
+                // PREVIOUS delivery's terminal record as if it were this one's.
+                yield writeDiag({
+                    sessionId: "",
+                    turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
+                });
+                try {
+                    const args = input.buildHandlerArgs(admitted.send.channelId, execution.sessionPublicId);
+                    const session = yield args.send(admitted.send.message, Object.assign(Object.assign({}, admitted.send.options), { mailboxContinuation: {
+                            key: admitted.send.mailboxContinuationKey,
+                        } }));
+                    const outcome = yield session.waitForCompletion();
+                    // Failed turns drain too: their record/continuation updates must
+                    // survive the park just like a finished turn's.
+                    yield (_a = input.drainSessionDurability) === null || _a === void 0 ? void 0 : _a.call(input, session.id);
+                    yield writeDiag({
+                        sessionId: session.id,
+                        turnStatus: outcome.status,
+                        message: outcome.errorMessage,
+                        abortReason: abortReasonFromTurnStatus(outcome.status, outcome.errorMessage),
+                    });
+                    if (outcome.status !== "finished") {
+                        return {
+                            status: 503,
+                            body: {
+                                ok: false,
+                                error: "turn_failed",
+                                turnStatus: outcome.status,
+                                message: outcome.errorMessage,
+                            },
+                        };
+                    }
                     return {
-                        status: 503,
+                        status: 200,
                         body: {
-                            ok: false,
-                            error: "turn_failed",
-                            turnStatus: outcome.status,
-                            message: outcome.errorMessage,
+                            ok: true,
+                            v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+                            outcome: "send",
                         },
                     };
                 }
-                return {
-                    status: 200,
-                    body: {
-                        ok: true,
-                        v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-                        outcome: "send",
-                    },
-                };
+                catch (error) {
+                    yield writeDiag({
+                        sessionId: "",
+                        turnStatus: "error",
+                        message: error instanceof Error ? error.message : String(error),
+                        abortReason: "execute_throw",
+                    });
+                    throw error;
+                }
             }))());
             const reply = yield admitted.execution;
             return finish(Response.json(reply.body, { status: reply.status }));

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

@@ -0,0 +1,48 @@
+export declare const HOSTED_EXECUTION_DIAG_VERSION = 1;
+/** Cap so a runaway message cannot fill the guest disk or the host log. */
+export declare const HOSTED_EXECUTION_DIAG_MAX_BYTES = 4096;
+/**
+ * Correlate the on-disk record with the execution that produced it. One pod
+ * serves many deliveries of a continuation session, and the file lives at a
+ * single fixed path, so without this the host can read a *previous*
+ * delivery's terminal record whenever July never reaches its own write —
+ * the 9-minute host POST timeout, a 409 on an expired admission token, or a
+ * replayed token that short-circuits on the memoized reply.
+ *
+ * Derived from the admission token (which both sides already hold) rather
+ * than carried on the wire. The digest is one-way, so the token itself never
+ * reaches the guest disk or the host logs.
+ */
+export declare function hostedExecutionDiagId(admissionToken: string): string;
+export type HostedExecutionDiagAbortReason = "signal_abort" | "runner_cancelled" | "runner_error" | "execute_throw";
+/**
+ * Bounded guest-side record of one hosted-execution attempt. No prompt,
+ * tool content, or API key — the host copies known keys onto the Temporal
+ * activity span for Datadog.
+ */
+export type HostedExecutionDiag = {
+    v: typeof HOSTED_EXECUTION_DIAG_VERSION;
+    /** {@link hostedExecutionDiagId} of the execution that wrote this record. */
+    executionId: string;
+    writtenAt: string;
+    sessionPublicId: string;
+    sessionId: string;
+    /** Terminal {@link TurnOutcome} status, or `running` before the turn ends. */
+    turnStatus: string;
+    durationMs: number;
+    message?: string;
+    signalAborted?: boolean;
+    requestId?: string;
+    abortReason?: HostedExecutionDiagAbortReason;
+};
+/** Written before the turn starts so a stalled execution still has a record. */
+export declare const HOSTED_EXECUTION_DIAG_RUNNING_STATUS = "running";
+export declare function hostedExecutionDiagPath(stateRoot: string): string;
+export declare function abortReasonFromTurnStatus(status: string, message: string | undefined): HostedExecutionDiagAbortReason | undefined;
+export declare function parseHostedExecutionDiag(raw: string): HostedExecutionDiag | undefined;
+/**
+ * Overwrite the per-execution diag file. Soft-fail: a write error must not
+ * change the hosted-execution HTTP reply.
+ */
+export declare function writeHostedExecutionDiag(stateRoot: string, diag: HostedExecutionDiag): Promise<void>;
+//# sourceMappingURL=hosted-execution-diag.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-execution-diag.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-execution-diag.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAC/C,2EAA2E;AAC3E,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,MAAM,MAAM,8BAA8B,GACtC,cAAc,GACd,kBAAkB,GAClB,cAAc,GACd,eAAe,CAAC;AAEpB;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,CAAC,EAAE,OAAO,6BAA6B,CAAC;IACxC,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,8BAA8B,CAAC;CAC9C,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,oCAAoC,YAAY,CAAC;AAkC9D,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,8BAA8B,GAAG,SAAS,CAU5C;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,GACV,mBAAmB,GAAG,SAAS,CAsEjC;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,CAkBf"}