@cursor/july 0.1.104 → 0.1.107

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)),
             };
         }
     });
@@ -289,14 +341,30 @@ export function registerHostedDeliveryRoute(input) {
                 if (unconsumed !== undefined) {
                     return finish(unconsumed);
                 }
-                const delivery = parseHostedAdmission(yield readJsonObject(request));
+                const rawAdmission = yield readJsonObject(request);
+                const delivery = parseHostedAdmission(rawAdmission);
                 if (delivery === undefined) {
-                    return finish(errorResponse(400, "invalid_hosted_admission", "Expected a supported Agent SDK hosted-admission envelope."));
+                    const rawKeys = typeof rawAdmission === "object" &&
+                        rawAdmission !== null &&
+                        !Array.isArray(rawAdmission)
+                        ? 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(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;
@@ -342,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;
@@ -387,15 +455,21 @@ export function registerHostedDeliveryRoute(input) {
                         sessionId: "",
                         turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
                     });
+                    let sessionId = "";
                     try {
                         const args = input.buildHandlerArgs(admitted.send.channelId, execution.sessionPublicId);
                         const session = yield args.send(admitted.send.message, Object.assign(Object.assign({}, admitted.send.options), { mailboxContinuation: {
                                 key: admitted.send.mailboxContinuationKey,
                             } }));
+                        sessionId = session.id;
                         const outcome = yield session.waitForCompletion();
                         // Failed turns drain too: their record/continuation updates must
                         // survive the park just like a finished turn's.
                         yield (_a = input.drainSessionDurability) === null || _a === void 0 ? void 0 : _a.call(input, session.id);
+                        // Evict before the reply: TAS parks and hibernates this process
+                        // as soon as the POST returns. A leftover SDK handle freezes a
+                        // dead Connect/HTTP2 session that the next wake then reuses.
+                        evictHostedSdkSessions(input.evictSdkSession, session.id, execution.sessionPublicId);
                         yield writeDiag({
                             sessionId: session.id,
                             turnStatus: outcome.status,
@@ -406,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,
                                 },
@@ -426,6 +502,7 @@ export function registerHostedDeliveryRoute(input) {
                         };
                     }
                     catch (error) {
+                        evictHostedSdkSessions(input.evictSdkSession, sessionId, execution.sessionPublicId);
                         yield writeDiag({
                             sessionId: "",
                             turnStatus: "error",
@@ -442,12 +519,28 @@ export function registerHostedDeliveryRoute(input) {
         }),
     });
 }
-function hostedErrorForUnfinishedTurn(errorMessage) {
+function evictHostedSdkSessions(evict, ...ids) {
+    if (evict === undefined) {
+        return;
+    }
+    const seen = new Set();
+    for (const id of ids) {
+        if (id === undefined || id === "" || seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        evict(id);
+    }
+}
+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/hosted-managed-automation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-managed-automation.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-managed-automation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAUtF,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,gCAAgC,CAAC;CACtD,GAAG,IAAI,CAiBP;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,GACjB,gCAAgC,GAAG,SAAS,CAU9C;AAED,4DAA4D;AAC5D,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D"}
+{"version":3,"file":"hosted-managed-automation.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-managed-automation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAoCtF,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,gCAAgC,CAAC;CACtD,GAAG,IAAI,CA4BP;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,GACjB,gCAAgC,GAAG,SAAS,CAiB9C;AAED,4DAA4D;AAC5D,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D"}

package/dist/internal/hosted-managed-automation.js

@@ -14,14 +14,33 @@
  * excluded from the published `@cursor/july` npm package (see the `files`
  * whitelist); consumed by internal deployments via relative source imports.
  */
-const managedAutomationByDelivery = new Map();
+/**
+ * Process-wide slot for the table. Hosted engines run the compiled CLI
+ * (`dist/`), which records at admission, while first-party factory agents
+ * relative-import this file from `src/` and read at finalize — two module
+ * instances in one process. A module-local Map would be recorded in one
+ * copy and read from the other (always undefined, so a fork never sees its
+ * Slack channels or MCP servers); the shared symbol keeps one table.
+ */
+const MANAGED_AUTOMATION_TABLE_KEY = Symbol.for("cursor.agentkit.hostedManagedAutomationByDelivery");
+function managedAutomationTable() {
+    const slots = globalThis;
+    let table = slots[MANAGED_AUTOMATION_TABLE_KEY];
+    if (table === undefined) {
+        table = new Map();
+        slots[MANAGED_AUTOMATION_TABLE_KEY] = table;
+    }
+    return table;
+}
 /** Long enough to outlive a slow review run kicked off by the delivery. */
 const MANAGED_AUTOMATION_TTL_MS = 60 * 60000;
 const MANAGED_AUTOMATION_MAX_ENTRIES = 10000;
 export function recordHostedManagedAutomation(delivery) {
     if (delivery.managedAutomation === undefined) {
+        console.info(`[agent-sdk] hosted managedAutomation not recorded deliveryId=${delivery.deliveryId}: admission envelope carried no managedAutomation slice (non-managed delivery, or the control plane resolved no MCP servers and no Slack channels)`);
         return;
     }
+    const managedAutomationByDelivery = managedAutomationTable();
     const now = Date.now();
     for (const [key, entry] of managedAutomationByDelivery) {
         if (entry.expiresAt <= now) {
@@ -29,12 +48,15 @@ export function recordHostedManagedAutomation(delivery) {
         }
     }
     if (managedAutomationByDelivery.size >= MANAGED_AUTOMATION_MAX_ENTRIES) {
+        console.info(`[agent-sdk] hosted managedAutomation table full (${String(managedAutomationByDelivery.size)} entries); clearing before recording deliveryId=${delivery.deliveryId}`);
         managedAutomationByDelivery.clear();
     }
     managedAutomationByDelivery.set(delivery.deliveryId, {
         managedAutomation: delivery.managedAutomation,
         expiresAt: now + MANAGED_AUTOMATION_TTL_MS,
     });
+    const slackChannels = delivery.managedAutomation.slackChannels;
+    console.info(`[agent-sdk] hosted managedAutomation recorded deliveryId=${delivery.deliveryId} automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${slackChannels === undefined ? "<absent>" : JSON.stringify(slackChannels)} ttlMs=${String(MANAGED_AUTOMATION_TTL_MS)} tableSize=${String(managedAutomationByDelivery.size)}`);
 }
 /**
  * The managed automation the control plane attributed to a hosted delivery,
@@ -42,11 +64,14 @@ export function recordHostedManagedAutomation(delivery) {
  * expired entries, and non-hosted (webhook/stream) dispatch paths.
  */
 export function getHostedManagedAutomation(deliveryId) {
+    const managedAutomationByDelivery = managedAutomationTable();
     const entry = managedAutomationByDelivery.get(deliveryId);
     if (entry === undefined) {
+        console.info(`[agent-sdk] hosted managedAutomation lookup miss deliveryId=${deliveryId}: no entry (never recorded in this process, or evicted) tableSize=${String(managedAutomationByDelivery.size)} knownDeliveryIds=${JSON.stringify([...managedAutomationByDelivery.keys()].slice(0, 10))}`);
         return undefined;
     }
     if (entry.expiresAt <= Date.now()) {
+        console.info(`[agent-sdk] hosted managedAutomation lookup expired deliveryId=${deliveryId} automationUuid=${entry.managedAutomation.automationUuid} expiredMsAgo=${String(Date.now() - entry.expiresAt)}`);
         managedAutomationByDelivery.delete(deliveryId);
         return undefined;
     }
@@ -54,5 +79,5 @@ export function getHostedManagedAutomation(deliveryId) {
 }
 /** Drop recorded managed-automation slices (tests only). */
 export function resetHostedManagedAutomationForTest() {
-    managedAutomationByDelivery.clear();
+    managedAutomationTable().clear();
 }

package/dist/internal/init-project.d.ts.map

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

package/dist/internal/init-project.js

@@ -25,6 +25,7 @@ const TEMPLATES = {
     "agents-md": { dir: "agents-md" },
     "code-wiki": { dir: "code-wiki" },
     demo: { dir: "demo" },
+    "grokbot-agents": { dir: "grokbot-agents" },
     "pr-autofixer": { dir: "pr-autofixer" },
     "security-help": { dir: "security-help" },
     "security-reviewer": { dir: "security-reviewer" },
@@ -499,6 +500,7 @@ export function printInitGuide() {
 Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
   npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
+  npx ${PACKAGE_NAME} init ./grokbot --template grokbot-agents    # talk to Grok Bot agents
   npx ${PACKAGE_NAME} init ./code-wiki --template code-wiki       # keep wiki pages current after merge
   npx ${PACKAGE_NAME} init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
   npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
@@ -507,8 +509,9 @@ Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-triage --template triage-jira     # comment on Jira issues
   npx ${PACKAGE_NAME} init ./my-owners --template agentic-owners  # review PRs via owners policies
   npx ${PACKAGE_NAME} init ./pr-autofixer --template pr-autofixer # fix PRs on a cloud VM
-  # TTY asks for GitHub repos. Scripts pass --var:
+  # TTY asks the template's questions. Scripts pass --var:
   #   --var repos=acme/widgets,acme/api
+  #   --var agents="Plan Keeper, Chief of Staff"
   cd ./my-agent && agent-sdk dev        # or: npx ${PACKAGE_NAME} dev
 
 Recommended loop once the project exists (from the project directory):

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"}