@cursor/july 0.1.94 → 0.1.96

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

@@ -0,0 +1,204 @@
+/**
+ * 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),
+    };
+}
+/**
+ * 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

@@ -2,36 +2,58 @@
  * Which backend framework session state is mirrored to.
  *
  * Framework state — session records, event chunks, the continuation index —
- * is how a session outlives the process that served it. Today that mirror
- * exists only when the agent author wrote `agent/storage.ts`, which makes
- * platform durability an agent-level decision: of the first-party agents,
- * some choose `cursorHostedStorage()` and some choose `fileKv()` (pod-local
- * disk, lost on pod replacement), and one selects between them at runtime by
- * reading the deployment-id environment variable itself.
+ * is how a session outlives the process that served it. On architecture v1
+ * that mirror exists only when the agent author wrote `agent/storage.ts`,
+ * which makes platform durability an agent-level decision: of the
+ * first-party agents, some choose `cursorHostedStorage()` and some choose
+ * `fileKv()` (pod-local disk, lost on pod replacement), and one selects
+ * between them at runtime by reading the deployment-id environment variable
+ * itself.
  *
- * That selection is a hosting-mode question, not an authoring question, and
- * this module is where it will move. It deliberately reproduces today's
- * behavior exactly for now — authored definition or nothing — so the change
- * that makes framework durability automatic is a change to
- * {@link selectFrameworkStorageDefinition} alone, reviewable on its own and
- * revertable without touching the engine.
+ * That selection is a hosting-mode question, not an authoring question.
+ * Architecture v2 moves it here: `agent/storage.ts` is rejected at
+ * discovery (error diagnostic, so serve and deploy fail early), and the
+ * platform picks the default —
+ *
+ * - **Cursor-managed hosting** (the deployment-generation environment
+ *   variable is set, same signal that registers `GET /v1/manifest`):
+ *   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.
+ *
+ * v1 keeps the authored definition (or nothing) so existing deployments are
+ * untouched while they run.
  *
  * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
  * already holds `session.json` and `events.ndjson` unconditionally, through
  * the session store; what this selects is the durable mirror *beyond* the
  * pod's filesystem.
  */
-import type { StorageDefinition } from "../storage.js";
+import { type StorageDefinition } from "../storage.js";
+import type { AgentArchitecture } from "../types.js";
 export interface FrameworkStorageSelectionInput {
-    /** `agent/storage.ts`, when the author wrote one. */
+    /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
     readonly authored: StorageDefinition | undefined;
+    /** {@link AgentConfig.architecture}; omitted means v1. */
+    readonly architecture?: AgentArchitecture | undefined;
+    /** Environment override for tests; defaults to `process.env`. */
+    readonly env?: Record<string, string | undefined>;
 }
 /**
  * Pick the backend for framework session state.
  *
  * Returns `undefined` when there is no mirror, in which case the pod's local
- * disk is the only copy — the condition F0 exists to remove for hosted
- * deployments.
+ * disk is the only copy.
  */
 export declare function selectFrameworkStorageDefinition(input: FrameworkStorageSelectionInput): StorageDefinition | undefined;
 //# sourceMappingURL=framework-storage-selection.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,MAAM,WAAW,8BAA8B;IAC7C,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,GAAG,SAAS,CAI/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

@@ -2,34 +2,95 @@
  * Which backend framework session state is mirrored to.
  *
  * Framework state — session records, event chunks, the continuation index —
- * is how a session outlives the process that served it. Today that mirror
- * exists only when the agent author wrote `agent/storage.ts`, which makes
- * platform durability an agent-level decision: of the first-party agents,
- * some choose `cursorHostedStorage()` and some choose `fileKv()` (pod-local
- * disk, lost on pod replacement), and one selects between them at runtime by
- * reading the deployment-id environment variable itself.
+ * is how a session outlives the process that served it. On architecture v1
+ * that mirror exists only when the agent author wrote `agent/storage.ts`,
+ * which makes platform durability an agent-level decision: of the
+ * first-party agents, some choose `cursorHostedStorage()` and some choose
+ * `fileKv()` (pod-local disk, lost on pod replacement), and one selects
+ * between them at runtime by reading the deployment-id environment variable
+ * itself.
  *
- * That selection is a hosting-mode question, not an authoring question, and
- * this module is where it will move. It deliberately reproduces today's
- * behavior exactly for now — authored definition or nothing — so the change
- * that makes framework durability automatic is a change to
- * {@link selectFrameworkStorageDefinition} alone, reviewable on its own and
- * revertable without touching the engine.
+ * That selection is a hosting-mode question, not an authoring question.
+ * Architecture v2 moves it here: `agent/storage.ts` is rejected at
+ * discovery (error diagnostic, so serve and deploy fail early), and the
+ * platform picks the default —
+ *
+ * - **Cursor-managed hosting** (the deployment-generation environment
+ *   variable is set, same signal that registers `GET /v1/manifest`):
+ *   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.
+ *
+ * v1 keeps the authored definition (or nothing) so existing deployments are
+ * untouched while they run.
  *
  * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
  * already holds `session.json` and `events.ndjson` unconditionally, through
  * 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.
  *
  * Returns `undefined` when there is no mirror, in which case the pod's local
- * disk is the only copy — the condition F0 exists to remove for hosted
- * deployments.
+ * disk is the only copy.
  */
 export function selectFrameworkStorageDefinition(input) {
-    // Today: the author decides, or there is no mirror. Hosting-mode selection
-    // replaces this body; every caller already routes through here.
-    return input.authored;
+    var _a;
+    if (input.architecture !== "v2") {
+        // v1: the author decides, or there is no mirror.
+        return input.authored;
+    }
+    if (input.authored !== undefined) {
+        // Discovery rejects agent/storage.ts on v2 before an engine is built;
+        // an authored definition reaching this point is a wiring bug. Raise
+        // rather than silently discard what the author believes is configured.
+        throw new Error('defineStorage (agent/storage.ts) is not supported on architecture "v2": storage is platform-selected. Delete the file.');
+    }
+    const env = (_a = input.env) !== null && _a !== void 0 ? _a : process.env;
+    if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+        // Self-hosted v2: the state root is the durable copy.
+        return undefined;
+    }
+    // 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-admission-context.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A `send()` captured outside the delivery (typically at channel `onStart`,
+ * which binds directly to the engine) reached the engine during a hosted
+ * admission window. Running it would start a local July session on a
+ * sessionless pod — invisible to the control plane, destroyed with the pod —
+ * so it fails loudly instead. This is a deterministic authored bug and is
+ * surfaced as a non-retryable 422 by the admission route.
+ */
+export declare class HostedAdmissionLocalSendError extends Error {
+    constructor();
+}
+/**
+ * Run `work` inside the hosted admission window. The context follows the
+ * async graph, including `waitUntil` task bodies scheduled during dispatch,
+ * so the engine can refuse local sends that bypass the capture stub.
+ */
+export declare function runDuringHostedAdmission<T>(work: () => T): T;
+/** True while executing inside a hosted admission window. */
+export declare function isDuringHostedAdmission(): boolean;
+//# sourceMappingURL=hosted-admission-context.d.ts.map

package/dist/internal/hosted-admission-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-admission-context.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-admission-context.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,cAQC;CACF;AAID;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5D;AAED,6DAA6D;AAC7D,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD"}

package/dist/internal/hosted-admission-context.js

@@ -0,0 +1,31 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * A `send()` captured outside the delivery (typically at channel `onStart`,
+ * which binds directly to the engine) reached the engine during a hosted
+ * admission window. Running it would start a local July session on a
+ * sessionless pod — invisible to the control plane, destroyed with the pod —
+ * so it fails loudly instead. This is a deterministic authored bug and is
+ * surfaced as a non-retryable 422 by the admission route.
+ */
+export class HostedAdmissionLocalSendError extends Error {
+    constructor() {
+        super("send() reached the local engine during hosted admission. A send " +
+            "captured at channel startup (onStart) bypasses hosted capture and " +
+            "would run an invisible local session on a sessionless pod. Use the " +
+            "per-delivery send passed to the task callback " +
+            "(task: (args) => args.send(…)) instead.");
+    }
+}
+const admissionWindow = new AsyncLocalStorage();
+/**
+ * Run `work` inside the hosted admission window. The context follows the
+ * async graph, including `waitUntil` task bodies scheduled during dispatch,
+ * so the engine can refuse local sends that bypass the capture stub.
+ */
+export function runDuringHostedAdmission(work) {
+    return admissionWindow.run(true, work);
+}
+/** True while executing inside a hosted admission window. */
+export function isDuringHostedAdmission() {
+    return admissionWindow.getStore() === true;
+}

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

@@ -2,6 +2,10 @@ 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";
+export type HostedAdmissionManagedAutomation = {
+    automationUuid: string;
+    mcpServerNames: string[];
+};
 export type HostedAdmission = {
     v: 2;
     channelId: string;
@@ -11,6 +15,7 @@ export type HostedAdmission = {
     sessionMode: "event" | "continuation";
     mailboxContinuationKey: string;
     payload: unknown;
+    managedAutomation?: HostedAdmissionManagedAutomation;
 };
 export type HostedAdmissionOutcome = {
     ok: true;

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,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;CAClB,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;AAkBF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,eAAe,GAAG,SAAS,CAsB7B;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;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"}

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

@@ -11,11 +11,42 @@ const DELIVERY_KEYS = new Set([
     "sessionMode",
     "mailboxContinuationKey",
     "payload",
+    "managedAutomation",
 ]);
+const MANAGED_AUTOMATION_KEYS = new Set(["automationUuid", "mcpServerNames"]);
+/** More names than any real automation configures is a malformed envelope. */
+const MANAGED_AUTOMATION_MAX_SERVERS = 64;
 const EXECUTION_KEYS = new Set(["v", "admissionToken", "sessionPublicId"]);
 function boundedString(value, max) {
     return typeof value === "string" && value.length > 0 && value.length <= max;
 }
+/**
+ * Parse the optional managed-automation slice. Absent → valid (undefined);
+ * present-but-malformed → invalid (the whole admission fails closed, the
+ * strict posture the rest of the envelope already takes).
+ */
+function parseManagedAutomation(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (Object.keys(body).some((key) => !MANAGED_AUTOMATION_KEYS.has(key)) ||
+        !boundedString(body.automationUuid, 128) ||
+        !Array.isArray(body.mcpServerNames) ||
+        body.mcpServerNames.length > MANAGED_AUTOMATION_MAX_SERVERS ||
+        !body.mcpServerNames.every((name) => boundedString(name, 256))) {
+        return undefined;
+    }
+    return {
+        managedAutomation: {
+            automationUuid: body.automationUuid,
+            mcpServerNames: body.mcpServerNames,
+        },
+    };
+}
 export function parseHostedAdmission(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return undefined;
@@ -29,7 +60,8 @@ export function parseHostedAdmission(value) {
         !boundedString(body.eventType, 128) ||
         !boundedString(body.deliveryId, 256) ||
         (body.sessionMode !== "event" && body.sessionMode !== "continuation") ||
-        !boundedString(body.mailboxContinuationKey, 512)) {
+        !boundedString(body.mailboxContinuationKey, 512) ||
+        parseManagedAutomation(body.managedAutomation) === undefined) {
         return undefined;
     }
     const prefix = body.sessionMode === "event" ? "evt:" : "cont:";

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

@@ -18,8 +18,10 @@ type AdmissionDispatch = {
 };
 /**
  * Run authored admission without creating a framework session. V1 GitHub
- * `task` callbacks execute as sessionless work; `send` is captured and
- * resumed only after the control plane allocates `ses_…`.
+ * `task` callbacks execute as sessionless work; the first `send` is captured
+ * and executed only after the control plane allocates `ses_…`. Capturing
+ * does not terminate the caller — `send` returns an inert deferred handle so
+ * a task body runs to completion before the admission response is computed.
  */
 export declare function dispatchHostedAdmission(input: DispatchInput): Promise<AdmissionDispatch>;
 export declare function registerHostedDeliveryRoute(input: {
@@ -30,6 +32,13 @@ 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>;
 }): 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;AACrB,OAAO,EAKL,KAAK,eAAe,EAGrB,MAAM,+BAA+B,CAAC;AAEvC,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;AAgBF;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CA2G5B;AAeD,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,CAqKP"}
+{"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;IACtB;;;;;OAKG;IACH,sBAAsB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D,GAAG,IAAI,CAyKP"}