@cursor/july 0.1.94 → 0.1.96

package/src/internal/deferred-channel-session.ts

@@ -0,0 +1,61 @@
+import type { ChannelSession } from "../types.js";
+
+const deferredSessions = new WeakSet<ChannelSession>();
+
+/**
+ * Authored code touched a member of the deferred handle that needs the live
+ * session. This is deterministic (the session never exists during admission),
+ * so the admission route surfaces it as a non-retryable 422 rather than a
+ * retryable failure.
+ */
+export class DeferredChannelSessionError extends Error {
+  constructor(member: string) {
+    super(
+      `ChannelSession.${member} is not available on a send() captured ` +
+        "during hosted admission: the control plane allocates the session " +
+        "(and runs the turn) only after this delivery is acknowledged, so " +
+        "the handle cannot observe it yet. Move work that needs the live " +
+        "session into the session turn instead."
+    );
+  }
+}
+
+function unavailable(member: string): never {
+  throw new DeferredChannelSessionError(member);
+}
+
+/**
+ * Inert `ChannelSession` returned by the hosted-admission `send` stub: every
+ * member fails loudly via {@link DeferredChannelSessionError}. Caveat: new
+ * OPTIONAL members added to `ChannelSession` slip through this factory
+ * silently (reads return `undefined`) until a throwing getter is added here.
+ */
+export function createDeferredChannelSession(): ChannelSession {
+  const session: ChannelSession = {
+    get id(): string {
+      return unavailable("id");
+    },
+    get continuationToken(): string | null {
+      return unavailable("continuationToken");
+    },
+    get isNew(): boolean {
+      return unavailable("isNew");
+    },
+    get coalesced(): boolean | undefined {
+      return unavailable("coalesced");
+    },
+    get info(): ChannelSession["info"] {
+      return unavailable("info");
+    },
+    getEventStream: async () => unavailable("getEventStream()"),
+    waitForCompletion: async () => unavailable("waitForCompletion()"),
+    setContinuationToken: async () => unavailable("setContinuationToken()"),
+  };
+  deferredSessions.add(session);
+  return session;
+}
+
+/** True when `send()` returned a hosted-admission capture handle. */
+export function isDeferredChannelSession(session: ChannelSession): boolean {
+  return deferredSessions.has(session);
+}

package/src/internal/deploy-client.ts

@@ -224,6 +224,16 @@ export interface AgentkitDeployAccepted {
   status: string;
 }
 
+/**
+ * One release component of a v2 multi-component deploy: a stable key (the
+ * child agent's slug) plus that agent's directory relative to the repo
+ * root.
+ */
+export interface AgentkitDeployComponent {
+  componentKey: string;
+  agentPath?: string;
+}
+
 /** Customer-visible v2 deploy status (`GET /internal/agentkit/deployments/:slug`). */
 export type AgentkitCustomerStatus =
   | "pending"
@@ -576,7 +586,9 @@ export class AgentServeDeployClient {
   /**
    * Create or redeploy onto the v2 control plane
    * (`POST /internal/agentkit/deployments`). 202 means accepted; poll
-   * {@link getAgentkitDeploy} until a terminal status.
+   * {@link getAgentkitDeploy} until a terminal status. `components` deploys
+   * one application with several release components (one per agent
+   * directory); it is mutually exclusive with `agentPath`.
    */
   async deployAgentkit(args: {
     teamId: number;
@@ -584,12 +596,22 @@ export class AgentServeDeployClient {
     gitRepoUrl: string;
     gitRef?: string;
     agentPath?: string;
+    components?: AgentkitDeployComponent[];
     repositories?: string[];
   }): Promise<AgentkitDeployAccepted> {
     const slugError = validateDeploymentSlug(args.slug);
     if (slugError !== undefined) {
       throw new DeployApiError(slugError, 400);
     }
+    for (const component of args.components ?? []) {
+      const keyError = validateDeploymentSlug(component.componentKey);
+      if (keyError !== undefined) {
+        throw new DeployApiError(
+          `Invalid component key ${JSON.stringify(component.componentKey)}: use lowercase letters, digits, '-' or '_' (max 64 chars)`,
+          400
+        );
+      }
+    }
     const raw = await this.request({
       method: "POST",
       path: "/internal/agentkit/deployments",
@@ -599,6 +621,7 @@ export class AgentServeDeployClient {
         gitRepoUrl: args.gitRepoUrl,
         gitRef: args.gitRef,
         agentPath: args.agentPath,
+        components: args.components,
         repositories:
           args.repositories !== undefined && args.repositories.length > 0
             ? args.repositories

package/src/internal/deploy-manifest.ts

@@ -168,12 +168,17 @@ export function buildAgentDeployManifest(
     declarations: {
       egressDomains: [...(project.agent.hosting?.egressDomains ?? [])],
       publicRoutePaths,
+      // v2 ignores authored storage; deploy manifests describe
+      // Cursor-hosted deployments, where framework-storage-selection.ts
+      // injects the Cursor-hosted mirror.
       frameworkStorage:
-        project.storage === undefined
-          ? "none"
-          : isCursorHostedStorage(project.storage)
-            ? "cursor-hosted"
-            : "other",
+        project.agent.architecture === "v2"
+          ? "cursor-hosted"
+          : project.storage === undefined
+            ? "none"
+            : isCursorHostedStorage(project.storage)
+              ? "cursor-hosted"
+              : "other",
       ...(project.agent.architecture === undefined
         ? {}
         : { architecture: project.agent.architecture }),

package/src/internal/discovery.ts

@@ -307,7 +307,7 @@ export async function loadAgentProject(
   const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
   const abs = await loadABs(ctx, agentDir);
   const abConfig = await loadABConfig(ctx, agentDir);
-  const storage = await loadStorage(ctx, agentDir);
+  const storage = await loadStorage(ctx, agentDir, agent.architecture);
   const artifacts = await loadArtifacts(ctx, agentDir);
   const otel = await loadOtel(ctx, agentDir);
   await appendArtifactTool(ctx, agentDir, agent, artifacts);
@@ -2151,12 +2151,35 @@ async function loadABConfig(
 
 async function loadStorage(
   ctx: DiscoveryContext,
-  agentDir: string
+  agentDir: string,
+  architecture: AgentArchitecture | undefined
 ): Promise<StorageDefinition | undefined> {
   const path = await findModuleFile(agentDir, "storage");
   if (path === undefined) {
     return undefined;
   }
+  if (architecture === "v2") {
+    // Storage is a hosting-mode decision on v2, made by
+    // framework-storage-selection.ts: the state root when self-hosted,
+    // Cursor-managed storage on Cursor hosting. Fail early (error
+    // diagnostics refuse serve and deploy) rather than silently running
+    // with storage the author believes they configured. Not imported.
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        'agent/storage.ts is not supported on architecture "v2": the platform selects storage (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Delete the file.',
+    });
+    return undefined;
+  }
+  // v1 keeps loading the authored sink, with notice: defineStorage is going
+  // away with the v1 control plane.
+  ctx.diagnostics.push({
+    severity: "warning",
+    path: displayPath(ctx, path),
+    message:
+      'agent/storage.ts (defineStorage) is deprecated and going away: architecture "v2" selects storage automatically (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Still honored on v1.',
+  });
   const definition = await importDefault(ctx, path, "storage");
   return definition as StorageDefinition | undefined;
 }

package/src/internal/framework-file-storage.ts

@@ -0,0 +1,222 @@
+/**
+ * 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.
+ */
+
+import type { FileSink } from "../files.js";
+import type { StorageConfig, StorageEntry } from "../storage.js";
+import { STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import type { JsonValue } from "../types.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: ReadonlySet<string> = 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: string): boolean {
+  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);
+}
+
+/** The KV core over a {@link FileSink}: one JSON document per key. */
+export type FileSinkStorageCore = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+>;
+
+/**
+ * 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: string): boolean {
+  return key
+    .split("/")
+    .some((segment) => segment === "" || segment === "." || segment === "..");
+}
+
+export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
+  return {
+    async put(key, value): Promise<void> {
+      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`
+        );
+      }
+      await sink.put(key, new TextEncoder().encode(JSON.stringify(value)));
+    },
+    async get(key): Promise<JsonValue | undefined> {
+      if (isUnrepresentableFileKey(key)) {
+        return undefined;
+      }
+      const body = await sink.get(key);
+      if (body === undefined) {
+        return undefined;
+      }
+      return decodeDocument(key, body instanceof Uint8Array ? body : body.body);
+    },
+    async delete(key): Promise<void> {
+      if (isUnrepresentableFileKey(key)) {
+        return;
+      }
+      await sink.delete(key);
+    },
+    async list(prefix): Promise<StorageEntry[]> {
+      const entries = await 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 = await mapBounded(entries, LIST_READ_CONCURRENCY, (entry) =>
+        sink.get(entry.key)
+      );
+      const out: StorageEntry[] = [];
+      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: string, bytes: Uint8Array): JsonValue {
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes)) as JsonValue;
+  } 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: {
+  kv: FileSinkStorageCore;
+  files: FileSinkStorageCore;
+}): FileSinkStorageCore {
+  const route = (key: string): FileSinkStorageCore =>
+    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: NonNullable<StorageConfig["cas"]>
+): NonNullable<StorageConfig["cas"]> {
+  const refuse = (key: string): void => {
+    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/src/internal/framework-storage-selection.ts

@@ -2,19 +2,37 @@
  * 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
@@ -22,24 +40,88 @@
  * pod's filesystem.
  */
 
-import type { StorageDefinition } from "../storage.js";
+import {
+  cursorFrameworkStoreSourceId,
+  cursorHostedFiles,
+} from "../files-backends/cursor-hosted.js";
+import { defineStorage, type StorageDefinition } from "../storage.js";
+import { cursorHostedStorage } from "../storage-backends/cursor-hosted.js";
+import type { AgentArchitecture } from "../types.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";
 
 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 function selectFrameworkStorageDefinition(
   input: FrameworkStorageSelectionInput
 ): StorageDefinition | undefined {
-  // Today: the author decides, or there is no mirror. Hosting-mode selection
-  // replaces this body; every caller already routes through here.
-  return input.authored;
+  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 = input.env ?? 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" } as const;
+  // 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 = (): string | undefined => resolveApiKeySync()?.apiKey;
+  const kv = cursorHostedStorage({ resolveApiKey });
+  const frameworkStoreId = cursorFrameworkStoreSourceId(
+    env as NodeJS.ProcessEnv
+  );
+  if (frameworkStoreId === undefined) {
+    return defineStorage({ 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({
+    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/src/internal/hosted-admission-context.ts

@@ -0,0 +1,37 @@
+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<true>();
+
+/**
+ * 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<T>(work: () => T): T {
+  return admissionWindow.run(true, work);
+}
+
+/** True while executing inside a hosted admission window. */
+export function isDuringHostedAdmission(): boolean {
+  return admissionWindow.getStore() === true;
+}

package/src/internal/hosted-delivery-protocol.ts

@@ -3,6 +3,11 @@ 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";
 
+export type HostedAdmissionManagedAutomation = {
+  automationUuid: string;
+  mcpServerNames: string[];
+};
+
 export type HostedAdmission = {
   v: 2;
   channelId: string;
@@ -12,6 +17,7 @@ export type HostedAdmission = {
   sessionMode: "event" | "continuation";
   mailboxContinuationKey: string;
   payload: unknown;
+  managedAutomation?: HostedAdmissionManagedAutomation;
 };
 
 export type HostedAdmissionOutcome =
@@ -39,13 +45,49 @@ 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: unknown, max: number): value is string {
   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: unknown
+): { managedAutomation?: HostedAdmissionManagedAutomation } | undefined {
+  if (value === undefined) {
+    return {};
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  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: unknown
 ): HostedAdmission | undefined {
@@ -62,7 +104,8 @@ export function parseHostedAdmission(
     !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;
   }