@cursor/july 0.1.105 → 0.1.107

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

@@ -13,7 +13,10 @@
  * 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 —
+ * platform picks the default. Architecture v1 with no authored file now
+ * uses the same hosted-vs-self-hosted split, so deleting `agent/storage.ts`
+ * (required to deploy the same tree onto v2) does not drop the Cursor-hosted
+ * session mirror on a still-v1 pod.
  *
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
@@ -33,8 +36,10 @@
  * - **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.
+ * v1 still honors an authored `agent/storage.ts` when present. Hosted v1
+ * pods with no authored file get the Cursor-hosted lazy mirror (gated on
+ * `AGENT_SERVE_DEPLOYMENT_ID`, the same signal the previous authored sinks
+ * used). Self-hosted v1 with no authored file stays disk-only.
  *
  * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
  * already holds `session.json` and `events.ndjson` unconditionally, through
@@ -43,10 +48,17 @@
  */
 import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
 import { defineStorage } from "../storage.js";
+import { AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR, cursorHostedStorage, } from "../storage-backends/cursor-hosted.js";
 import { cursorHostedStorageV2 } from "../storage-backends/cursor-hosted-v2.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { composeFrameworkStorage, fileSinkStorageCore, frameworkGuardedCas, } from "./framework-file-storage.js";
 import { resolveAgentV2Hosting } from "./v2-hosting.js";
+/**
+ * Hosted v2 event-chunk flush debounce. Matches the session view's live poll
+ * cadence; a streaming turn still caps each chunk at the coordinator's batch
+ * limit, so a long turn writes a few dozen chunks rather than one per event.
+ */
+export const HOSTED_V2_EVENT_FLUSH_DEBOUNCE_MS = 2000;
 /**
  * Pick the backend for framework session state.
  *
@@ -54,9 +66,19 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
  * disk is the only copy.
  */
 export function selectFrameworkStorageDefinition(input) {
+    var _a, _b;
     if (input.architecture !== "v2") {
-        // v1: the author decides, or there is no mirror.
-        return input.authored;
+        if (input.authored !== undefined) {
+            return input.authored;
+        }
+        const env = (_a = input.env) !== null && _a !== void 0 ? _a : process.env;
+        if (((_b = env[AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR]) !== null && _b !== void 0 ? _b : "").trim() !== "") {
+            // Hosted v1 pod with no authored sink: keep the Cursor-hosted
+            // mirror (lazy restore) so agents can delete `agent/storage.ts`
+            // without losing durability while they still run architecture v1.
+            return defineStorage(Object.assign({ name: "cursor-hosted (lazy restore)", policy: { restore: "off" } }, cursorHostedStorage()));
+        }
+        return undefined;
     }
     if (input.authored !== undefined) {
         // Discovery rejects agent/storage.ts on v2 before an engine is built;
@@ -77,7 +99,15 @@ export function selectFrameworkStorageDefinition(input) {
     // 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" };
+    //
+    // Events flush on a quiet-period debounce rather than only at turn end so
+    // the read-only session view and dashboard trace (which have no resident
+    // engine to ask) see steps mid-turn. The turn-end record still lands
+    // before the execution reply: drainSessionDurability forces the flush.
+    const policy = {
+        restore: "off",
+        debounceMs: HOSTED_V2_EVENT_FLUSH_DEBOUNCE_MS,
+    };
     // Full chain (env → bind file → stored login): frozen engines listen
     // unsigned and bind store ids + CURSOR_API_KEY at task time, after this
     // definition is constructed.

package/dist/internal/guest-network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guest-network.d.ts","sourceRoot":"","sources":["../../src/internal/guest-network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAuB1D,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,OAAO,yBAAyB,CAA6B;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,YACE,OAAO,SAAsD,EAC7D,MAAM,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,EAMzD;CACF;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAgBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQhE;AAED,4EAA4E;AAC5E,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExE;AA+ED,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAG7C,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AA2CF,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,CAAC;AAE1E,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,OAAO,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAkDjC;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,QAAQ,CAAC,CAsCnB"}
+{"version":3,"file":"guest-network.d.ts","sourceRoot":"","sources":["../../src/internal/guest-network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAuB1D,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,OAAO,yBAAyB,CAA6B;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,YACE,OAAO,SAAsD,EAC7D,MAAM,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,EAMzD;CACF;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAgBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQhE;AAED,4EAA4E;AAC5E,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExE;AA+ED,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAG7C,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AA2CF,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,CAAC;AAE1E,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,OAAO,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAkDjC;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,QAAQ,CAAC,CAuCnB"}

package/dist/internal/guest-network.js

@@ -27,6 +27,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+import { HOSTED_GUEST_RETRY_TRANSIENT } from "./hosted-delivery-protocol.js";
 export const GUEST_NETWORK_UNAVAILABLE = "guest_network_unavailable";
 export const GUEST_CONNECT_STALLED = "guest_connect_stalled";
 /** Control-plane readiness probe. Auth none, same as `/v1/health`. */
@@ -290,6 +291,7 @@ export function guestNetworkReadinessResponse() {
             return new Response(JSON.stringify({
                 ok: false,
                 error: GUEST_NETWORK_UNAVAILABLE,
+                retry: HOSTED_GUEST_RETRY_TRANSIENT,
                 message: error.message,
                 waitMs: error.waitMs,
                 probeAttempts: error.probeAttempts,

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

@@ -2,6 +2,28 @@ 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 declare const HOSTED_GUEST_RETRY_TRANSIENT = "transient";
+export declare const HOSTED_GUEST_RETRY_TERMINAL = "terminal";
+export type HostedGuestRetryDisposition = typeof HOSTED_GUEST_RETRY_TRANSIENT | typeof HOSTED_GUEST_RETRY_TERMINAL;
+export type HostedGuestError = {
+    ok: false;
+    error: string;
+    retry: HostedGuestRetryDisposition;
+    message?: string;
+    turnStatus?: string;
+};
+/**
+ * Hosted delivery is the only HTTP surface whose failures drive Temporal
+ * retries. Keep its retry disposition explicit instead of making the shared
+ * HTTP error helper guess from a status code.
+ */
+export declare function hostedGuestErrorResponse(input: {
+    status: number;
+    error: string;
+    retry: HostedGuestRetryDisposition;
+    message?: string;
+    turnStatus?: string;
+}): Response;
 /**
  * Filename under the serve `--state-root` (not the per-slug SessionEngine
  * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
@@ -9,6 +31,22 @@ export declare const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
  * Must match `AGENT_SERVE_ENGINE_HOSTED_EXECUTION_DIAG_PATH` basename.
  */
 export declare const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
+/**
+ * Reserved hosted-admission `channelKind` for durable reminder fires.
+ * Bypasses authored channel admission and invokes ReminderRunner.dispatch.
+ * Backend builds envelopes with this constant + {@link HOSTED_REMINDER_EVENT_TYPE}.
+ */
+export declare const HOSTED_REMINDER_CHANNEL_KIND = "agent-sdk:reminder";
+/**
+ * Reserved hosted-admission `eventType` for durable reminder fires.
+ * Payload is {@link HostedReminderFirePayload}.
+ */
+export declare const HOSTED_REMINDER_EVENT_TYPE = "agent-sdk.reminder/fire";
+/** Compact reminder-fire payload on the reserved hosted-admission path. */
+export type HostedReminderFirePayload = {
+    reminderId: string;
+    fireCount: number;
+};
 export type HostedAdmissionManagedAutomation = {
     automationUuid: string;
     mcpServerNames: string[];
@@ -57,5 +95,15 @@ export type HostedExecutionOutcome = {
 };
 export declare function parseHostedAdmission(value: unknown): HostedAdmission | undefined;
 export declare function parseHostedExecution(value: unknown): HostedExecution | undefined;
+/**
+ * True when the admission envelope is the reserved internal reminder fire
+ * path (not an authored channel event).
+ */
+export declare function isHostedReminderAdmission(delivery: HostedAdmission): boolean;
+/**
+ * Parse `{ reminderId, fireCount }` from a reserved reminder admission
+ * payload. Rejects unknown keys and non-integer fireCount.
+ */
+export declare function parseHostedReminderFirePayload(value: unknown): HostedReminderFirePayload | undefined;
 export declare function parseHostedAdmissionOutcome(value: unknown): HostedAdmissionOutcome | undefined;
 //# sourceMappingURL=hosted-delivery-protocol.d.ts.map

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;AACrE;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,0BAA0B,CAAC;AAEtE,MAAM,MAAM,gCAAgC,GAAG;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,EAAE,CAAC,CAAC;IACL,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,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;AAyEF,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":"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"}

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

@@ -2,6 +2,23 @@ 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";
+export const HOSTED_GUEST_RETRY_TRANSIENT = "transient";
+export const HOSTED_GUEST_RETRY_TERMINAL = "terminal";
+/**
+ * Hosted delivery is the only HTTP surface whose failures drive Temporal
+ * retries. Keep its retry disposition explicit instead of making the shared
+ * HTTP error helper guess from a status code.
+ */
+export function hostedGuestErrorResponse(input) {
+    const body = {
+        ok: false,
+        error: input.error,
+        retry: input.retry,
+        message: input.message,
+        turnStatus: input.turnStatus,
+    };
+    return Response.json(body, { status: input.status });
+}
 /**
  * Filename under the serve `--state-root` (not the per-slug SessionEngine
  * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
@@ -9,6 +26,17 @@ export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
  * Must match `AGENT_SERVE_ENGINE_HOSTED_EXECUTION_DIAG_PATH` basename.
  */
 export const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
+/**
+ * Reserved hosted-admission `channelKind` for durable reminder fires.
+ * Bypasses authored channel admission and invokes ReminderRunner.dispatch.
+ * Backend builds envelopes with this constant + {@link HOSTED_REMINDER_EVENT_TYPE}.
+ */
+export const HOSTED_REMINDER_CHANNEL_KIND = "agent-sdk:reminder";
+/**
+ * Reserved hosted-admission `eventType` for durable reminder fires.
+ * Payload is {@link HostedReminderFirePayload}.
+ */
+export const HOSTED_REMINDER_EVENT_TYPE = "agent-sdk.reminder/fire";
 const DELIVERY_KEYS = new Set([
     "v",
     "channelId",
@@ -103,6 +131,38 @@ export function parseHostedExecution(value) {
     }
     return body;
 }
+/**
+ * True when the admission envelope is the reserved internal reminder fire
+ * path (not an authored channel event).
+ */
+export function isHostedReminderAdmission(delivery) {
+    return (delivery.channelKind === HOSTED_REMINDER_CHANNEL_KIND &&
+        delivery.eventType === HOSTED_REMINDER_EVENT_TYPE);
+}
+/**
+ * Parse `{ reminderId, fireCount }` from a reserved reminder admission
+ * payload. Rejects unknown keys and non-integer fireCount.
+ */
+export function parseHostedReminderFirePayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    const keys = Object.keys(body);
+    if (keys.length !== 2 ||
+        !Object.hasOwn(body, "reminderId") ||
+        !Object.hasOwn(body, "fireCount") ||
+        !boundedString(body.reminderId, 128) ||
+        typeof body.fireCount !== "number" ||
+        !Number.isInteger(body.fireCount) ||
+        body.fireCount < 0) {
+        return undefined;
+    }
+    return {
+        reminderId: body.reminderId,
+        fireCount: body.fireCount,
+    };
+}
 export function parseHostedAdmissionOutcome(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return undefined;

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

@@ -39,6 +39,16 @@ export declare function registerHostedDeliveryRoute(input: {
         definition: object;
     }>;
     buildHandlerArgs(channelId: string, sessionPublicId?: string): ChannelHandlerArgs;
+    /**
+     * Reserved reminder admission: dispatch a hydrated ReminderRunner fire
+     * without authored channel admission. Returns the runner's outcome so the
+     * route can map fired → task and noop → skip.
+     */
+    fireReminder?(reminderId: string, expectedFireCount: number): Promise<{
+        reminderId: string;
+        outcome: "fired" | "noop";
+        reason?: string;
+    }>;
     /**
      * Await the session's durable mirror (dispatch chain + storage queue)
      * before the execution reply: the control plane may park the pod the

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":"AACA,OAAO,KAAK,EAEV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAKL,KAAK,sBAAsB,EAI5B,MAAM,oBAAoB,CAAC;AAS5B,OAAO,EAKL,KAAK,eAAe,EAGrB,MAAM,+BAA+B,CAAC;AAYvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,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;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AAkKD,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;;;OAGG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,8DAA8D;IAC9D,aAAa,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,wDAAwD;IACxD,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC;IAChC;;;;;OAKG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,mBAAmB,CAAC,IAAI,OAAO,CAAC,sBAAsB,GAAG,OAAO,CAAC,CAAC;IAClE;;;;OAIG;IACH,mBAAmB,CAAC,IAAI,wBAAwB,CAAC;CAClD,GAAG,IAAI,CAwVP"}
+{"version":3,"file":"hosted-delivery.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-delivery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAKL,KAAK,sBAAsB,EAI5B,MAAM,oBAAoB,CAAC;AAS5B,OAAO,EAOL,KAAK,eAAe,EAOrB,MAAM,+BAA+B,CAAC;AAYvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAOlD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,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;AAuFF;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAU5B;AA+ND,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;;;;OAIG;IACH,YAAY,CAAC,CACX,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH;;;;;OAKG;IACH,sBAAsB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;OAGG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,8DAA8D;IAC9D,aAAa,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,wDAAwD;IACxD,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC;IAChC;;;;;OAKG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,mBAAmB,CAAC,IAAI,OAAO,CAAC,sBAAsB,GAAG,OAAO,CAAC,CAAC;IAClE;;;;OAIG;IACH,mBAAmB,CAAC,IAAI,wBAAwB,CAAC;CAClD,GAAG,IAAI,CAwWP"}

package/dist/internal/hosted-delivery.js

@@ -14,12 +14,13 @@ import { createDeferredChannelSession, DeferredChannelSessionError, } from "./de
 import { formatGuestNetworkServerTiming, GUEST_CONNECT_STALLED, GUEST_NETWORK_UNAVAILABLE, GuestNetworkUnavailableError, isQuietGuestConnectStallMessage, waitForGuestNetworkReady, } from "./guest-network.js";
 import { getHostedAdmissionAdapter, } from "./hosted-admission-adapter.js";
 import { HostedAdmissionLocalSendError, runDuringHostedAdmission, } from "./hosted-admission-context.js";
-import { HOSTED_ADMISSION_PATH, HOSTED_DELIVERY_HEADER, HOSTED_DELIVERY_PROTOCOL_VERSION, HOSTED_EXECUTION_PATH, parseHostedAdmission, parseHostedExecution, } from "./hosted-delivery-protocol.js";
+import { HOSTED_ADMISSION_PATH, HOSTED_DELIVERY_HEADER, HOSTED_DELIVERY_PROTOCOL_VERSION, HOSTED_EXECUTION_PATH, HOSTED_GUEST_RETRY_TERMINAL, HOSTED_GUEST_RETRY_TRANSIENT, hostedGuestErrorResponse, isHostedReminderAdmission, parseHostedAdmission, parseHostedExecution, parseHostedReminderFirePayload, } from "./hosted-delivery-protocol.js";
 import { abortReasonFromTurnStatus, HOSTED_EXECUTION_DIAG_RUNNING_STATUS, hostedExecutionDiagId, } from "./hosted-execution-diag.js";
 import { flushHostedExecutionRecord, } from "./hosted-execution-flush.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
-import { errorResponse, readJsonObject } from "./http-channel.js";
+import { readJsonObject } from "./http-channel.js";
 import { endActiveHttpSpan } from "./otel/http.js";
+import { ReminderValidationError, UnknownReminderError, } from "./reminder-runner.js";
 import { statusForThrownRequestError } from "./request-error-status.js";
 /**
  * A second `send()` in one delivery is a deterministic authored bug — the
@@ -44,6 +45,22 @@ function boundedMessage(text) {
         ? `${text.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
         : text;
 }
+function terminalHostedError(status, error, message) {
+    return hostedGuestErrorResponse({
+        status,
+        error,
+        retry: HOSTED_GUEST_RETRY_TERMINAL,
+        message,
+    });
+}
+function transientHostedError(status, error, message) {
+    return hostedGuestErrorResponse({
+        status,
+        error,
+        retry: HOSTED_GUEST_RETRY_TRANSIENT,
+        message,
+    });
+}
 /**
  * Classify deterministic authored protocol violations as non-retryable 422
  * admissions. Anything else returns `undefined` so callers fall through to
@@ -61,7 +78,7 @@ function nonRetryableRejection(error) {
         return undefined;
     }
     return {
-        response: errorResponse(422, code, boundedMessage(error.message)),
+        response: terminalHostedError(422, code, boundedMessage(error.message)),
     };
 }
 /**
@@ -79,7 +96,7 @@ export function dispatchHostedAdmission(input) {
         const adapter = getHostedAdmissionAdapter(input.definition);
         if (adapter === undefined || adapter.kind !== input.delivery.channelKind) {
             return {
-                response: Response.json({ ok: false, error: "channel_kind_mismatch" }, { status: 422 }),
+                response: terminalHostedError(422, "channel_kind_mismatch"),
             };
         }
         // The admission window marker follows the async graph into task bodies so
@@ -87,6 +104,41 @@ export function dispatchHostedAdmission(input) {
         return runDuringHostedAdmission(() => runAdmission(input, adapter));
     });
 }
+/**
+ * Reserved reminder admission: parse the compact payload and invoke
+ * ReminderRunner.dispatch. Returns a standard hosted outcome (`task` /
+ * `skip`) and never opens the send-capture / model-session path here —
+ * prompt-form fires still follow up inside the runner.
+ */
+function dispatchHostedReminderAdmission(input, delivery) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (input.fireReminder === undefined) {
+            return transientHostedError(503, "reminder_dispatch_unavailable", "This guest has no reminder runner wired for hosted admission.");
+        }
+        const payload = parseHostedReminderFirePayload(delivery.payload);
+        if (payload === undefined) {
+            return terminalHostedError(400, "invalid_reminder_payload", "Expected reminder payload { reminderId, fireCount }.");
+        }
+        try {
+            const result = yield input.fireReminder(payload.reminderId, payload.fireCount);
+            const outcome = result.outcome === "noop" ? "skip" : "task";
+            return Response.json({
+                ok: true,
+                v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+                outcome,
+            });
+        }
+        catch (error) {
+            if (error instanceof UnknownReminderError) {
+                return terminalHostedError(404, "unknown_reminder", boundedMessage(error.message));
+            }
+            if (error instanceof ReminderValidationError) {
+                return terminalHostedError(400, "invalid_reminder", boundedMessage(error.message));
+            }
+            throw error;
+        }
+    });
+}
 function runAdmission(input, adapter) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
@@ -121,7 +173,7 @@ function runAdmission(input, adapter) {
         }
         if (!dispatched.ok) {
             return {
-                response: Response.json({ ok: false, error: "channel_dispatch_failed" }, { status: dispatched.status >= 400 ? dispatched.status : 502 }),
+                response: terminalHostedError(dispatched.status >= 400 ? dispatched.status : 502, "channel_dispatch_failed"),
             };
         }
         try {
@@ -133,7 +185,7 @@ function runAdmission(input, adapter) {
                 return rejected;
             }
             return {
-                response: errorResponse(503, "background_dispatch_failed", boundedMessage(error instanceof Error ? error.message : String(error))),
+                response: terminalHostedError(503, "background_dispatch_failed", boundedMessage(error instanceof Error ? error.message : String(error))),
             };
         }
         if (captured !== undefined) {
@@ -156,7 +208,7 @@ function runAdmission(input, adapter) {
         const outcome = dispatchOutcome(dispatched);
         if (outcome === undefined || outcome === "send") {
             return {
-                response: Response.json({ ok: false, error: "channel_outcome_missing" }, { status: 502 }),
+                response: terminalHostedError(502, "channel_outcome_missing"),
             };
         }
         return {
@@ -234,7 +286,7 @@ export function registerHostedDeliveryRoute(input) {
         const consumed = consumeBoundSecrets();
         return consumed.ok
             ? undefined
-            : errorResponse(503, consumed.code, boundedMessage(consumed.message));
+            : transientHostedError(503, consumed.code, boundedMessage(consumed.message));
     };
     const finishNetworkWait = (phase) => __awaiter(this, void 0, void 0, function* () {
         try {
@@ -252,7 +304,7 @@ export function registerHostedDeliveryRoute(input) {
                     : "Guest network is not ready for outbound requests.";
             return {
                 timing,
-                response: errorResponse(503, GUEST_NETWORK_UNAVAILABLE, boundedMessage(message)),
+                response: transientHostedError(503, GUEST_NETWORK_UNAVAILABLE, boundedMessage(message)),
             };
         }
     });
@@ -298,13 +350,21 @@ export function registerHostedDeliveryRoute(input) {
                         ? Object.keys(rawAdmission)
                         : [];
                     console.info(`[agent-sdk] hosted admission rejected: envelope failed to parse keys=${JSON.stringify(rawKeys)} hasManagedAutomation=${String(rawKeys.includes("managedAutomation"))}`);
-                    return finish(errorResponse(400, "invalid_hosted_admission", "Expected a supported Agent SDK hosted-admission envelope."));
+                    return finish(terminalHostedError(400, "invalid_hosted_admission", "Expected a supported Agent SDK hosted-admission envelope."));
                 }
                 console.info(`[agent-sdk] hosted admission received deliveryId=${delivery.deliveryId} channelId=${delivery.channelId} channelKind=${delivery.channelKind} eventType=${delivery.eventType} sessionMode=${delivery.sessionMode} managedAutomation=${delivery.managedAutomation === undefined ? "<absent>" : `automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${delivery.managedAutomation.slackChannels === undefined ? "<absent>" : JSON.stringify(delivery.managedAutomation.slackChannels)}`}`);
                 recordHostedManagedAutomation(delivery);
+                if (isHostedReminderAdmission(delivery)) {
+                    const network = yield finishNetworkWait("admission");
+                    guestNetwork = network.timing;
+                    if (network.response !== undefined) {
+                        return finish(network.response);
+                    }
+                    return finish(yield dispatchHostedReminderAdmission(input, delivery));
+                }
                 const channel = input.channels.find((candidate) => candidate.id === delivery.channelId);
                 if (channel === undefined) {
-                    return finish(errorResponse(404, "channel_not_found", `No channel named "${delivery.channelId}" is mounted.`));
+                    return finish(terminalHostedError(404, "channel_not_found", `No channel named "${delivery.channelId}" is mounted.`));
                 }
                 const network = yield finishNetworkWait("admission");
                 guestNetwork = network.timing;
@@ -350,16 +410,16 @@ export function registerHostedDeliveryRoute(input) {
                 }
                 const execution = parseHostedExecution(yield readJsonObject(request));
                 if (execution === undefined) {
-                    return finish(errorResponse(400, "invalid_hosted_execution", "Expected a supported Agent SDK hosted-execution envelope."));
+                    return finish(terminalHostedError(400, "invalid_hosted_execution", "Expected a supported Agent SDK hosted-execution envelope."));
                 }
                 pruneExpired();
                 const admitted = pending.get(execution.admissionToken);
                 if (admitted === undefined) {
-                    return finish(errorResponse(409, "hosted_admission_unavailable", "The hosted admission token is missing or expired."));
+                    return finish(transientHostedError(409, "hosted_admission_unavailable", "The hosted admission token is missing or expired."));
                 }
                 if (admitted.sessionPublicId !== undefined &&
                     admitted.sessionPublicId !== execution.sessionPublicId) {
-                    return finish(errorResponse(409, "hosted_admission_session_mismatch", "The hosted admission token is already bound to another session."));
+                    return finish(transientHostedError(409, "hosted_admission_session_mismatch", "The hosted admission token is already bound to another session."));
                 }
                 const network = yield finishNetworkWait("execution");
                 guestNetwork = network.timing;
@@ -420,11 +480,13 @@ export function registerHostedDeliveryRoute(input) {
                             // waitForCompletion resolves (does not throw) on a quiet
                             // Connect abort. Map that to guest_connect_stalled so TAS
                             // retries the same pod. Real runner failures stay turn_failed.
+                            const hostedFailure = hostedFailureForUnfinishedTurn(outcome.errorMessage);
                             return {
                                 status: 503,
                                 body: {
                                     ok: false,
-                                    error: hostedErrorForUnfinishedTurn(outcome.errorMessage),
+                                    error: hostedFailure.error,
+                                    retry: hostedFailure.retry,
                                     turnStatus: outcome.status,
                                     message: outcome.errorMessage,
                                 },
@@ -470,12 +532,15 @@ function evictHostedSdkSessions(evict, ...ids) {
         evict(id);
     }
 }
-function hostedErrorForUnfinishedTurn(errorMessage) {
+function hostedFailureForUnfinishedTurn(errorMessage) {
     if (errorMessage !== undefined &&
         isQuietGuestConnectStallMessage(errorMessage)) {
-        return GUEST_CONNECT_STALLED;
+        return {
+            error: GUEST_CONNECT_STALLED,
+            retry: HOSTED_GUEST_RETRY_TRANSIENT,
+        };
     }
-    return "turn_failed";
+    return { error: "turn_failed", retry: HOSTED_GUEST_RETRY_TERMINAL };
 }
 function afterHostedWork(flushOtel, work) {
     return __awaiter(this, void 0, void 0, function* () {

package/dist/internal/local-control-plane.d.ts

@@ -3,6 +3,12 @@
  * and reminder documents + clocks, then fires into the kit the same way the
  * Cursor backend does over HTTP when `--no-control-plane` is set.
  *
+ * Reminder lifecycle (protocol v1): CP assigns id, arms timers, claims a due
+ * fire once, invokes a guest executor with an immutable descriptor, and
+ * applies the outcome with generation/fireCount CAS. Cancel/rekey racing an
+ * in-flight execution bumps generation so a stale outcome cannot resurrect
+ * the reminder. Legacy `fireReminder(id, fireCount)` remains for v1 runners.
+ *
  * v2 ingest lives here: `routeContinuation` stamps the mailbox (July twin
  * of hosted `routeVerifiedIngressContinuation`), and `attachScmEvents`
  * owns the `/v0/scm-events` long poll. v1 keeps engine-side scm-events.
@@ -10,7 +16,8 @@
  */
 import { type LocalIngressContinuation, type RouteLocalIngressContinuationInput } from "./local-ingress.js";
 import type { PlatformTimers } from "./platform-timers.js";
-export interface LocalControlPlane extends PlatformTimers {
+import { type ReminderControlPlane, type ReminderGuestExecutor } from "./reminder-control-plane-protocol.js";
+export interface LocalControlPlane extends PlatformTimers, ReminderControlPlane {
     /**
      * Stamp a v2 mailbox from the channel selector + live payload. Same
      * contract as hosted verified ingress. `/v1` is a no-op.
@@ -30,7 +37,16 @@ export interface LocalControlPlane extends PlatformTimers {
 }
 export declare function createLocalControlPlane(opts: {
     fireSchedule: (name: string) => Promise<unknown>;
-    fireReminder: (id: string, fireCount: number) => Promise<unknown>;
+    /**
+     * Legacy v1 path: CP calls this with (id, fireCount) and the runner mutates
+     * authoritative state. Prefer {@link executeReminder} for architecture v2.
+     */
+    fireReminder?: (id: string, fireCount: number) => Promise<unknown>;
+    /**
+     * Protocol guest executor. When set, due timers claim once, invoke this
+     * with an immutable descriptor, and apply the returned outcome via CAS.
+     */
+    executeReminder?: ReminderGuestExecutor;
     /**
      * Persist reminder documents under `<stateDir>/reminders`. Local serve
      * passes `<stateRoot>/control-plane`.

package/dist/internal/local-control-plane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-control-plane.d.ts","sourceRoot":"","sources":["../../src/internal/local-control-plane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,kCAAkC,EAExC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD;;;OAGG;IACH,iBAAiB,CACf,KAAK,EAAE,kCAAkC,GACxC,wBAAwB,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE;QAAE,KAAK,IAAI,IAAI,CAAC;QAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACvE,yEAAyE;IACzE,WAAW,IAAI,IAAI,CAAC;IACpB,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsJ7B"}
+{"version":3,"file":"local-control-plane.d.ts","sourceRoot":"","sources":["../../src/internal/local-control-plane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,kCAAkC,EAExC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAKL,KAAK,oBAAoB,EAIzB,KAAK,qBAAqB,EAI3B,MAAM,sCAAsC,CAAC;AAI9C,MAAM,WAAW,iBACf,SAAQ,cAAc,EACpB,oBAAoB;IACtB;;;OAGG;IACH,iBAAiB,CACf,KAAK,EAAE,kCAAkC,GACxC,wBAAwB,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE;QAAE,KAAK,IAAI,IAAI,CAAC;QAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACvE,yEAAyE;IACzE,WAAW,IAAI,IAAI,CAAC;IACpB,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE;;;OAGG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0X7B"}