@evident-ai/runner-cdk 3.5.2-dev.bcf1140 → 3.5.2-dev.da3340e

package/README.md

@@ -76,8 +76,8 @@ agent.selfStopRoleArn;
 agent.replicaPrefix;
 ```
 
-For a complete working example, see `GETTING-STARTED.md` (not published to npm); it is the
-construct's own dogfooding consumer.
+For the full end-to-end walkthrough for this construct, see
+[GETTING-STARTED.md](https://github.com/evident-run/evident-run/blob/main/aws/runner-cdk/GETTING-STARTED.md).
 
 ## Props
 
@@ -162,7 +162,8 @@ new EvidentMicrovmConstruct(this, 'Runner', {
 Pass `overlayDir` to add deployment-specific build steps to the staged image. The
 directory provides `setup-root` for root-owned installs and `setup-workspace` for
 dependency installation and workspace build warm-up. See the [MicroVM image
-README](../../runner/docker-images/microvm/README.md) for the full overlay contract.
+README](https://github.com/evident-run/evident-run/blob/main/runner/docker-images/microvm/README.md)
+for the full overlay contract.
 
 The image bakes your repository checked out but not installed and makes no assumptions about
 its package manager. To speed up first boot, install dependencies from your overlay's

package/dist/controller-lambda/handler.js

@@ -49818,7 +49818,7 @@ function verifyWakeSignature(rawBody, signatureHeader, secret) {
   return (0, import_node_crypto11.timingSafeEqual)(providedBuffer, expectedBuffer);
 }
 
-// src/microvm/controller/doorbell.ts
+// src/microvm/controller/doorbell-request.ts
 var WAKE_EVENT_TYPES = ["agent.message_queued", "agent.wake_requested"];
 var SUSPEND_EVENT_TYPE = "runner.suspend_requested";
 var SHAPES_EVENT_TYPE = "runner.shapes_requested";
@@ -49838,7 +49838,7 @@ function nonBlankString(value) {
 function isWakeType(value) {
   return WAKE_EVENT_TYPES.includes(value);
 }
-function parseDoorbell(rawBody) {
+function parseDoorbellRequest(rawBody) {
   let body;
   try {
     body = JSON.parse(rawBody);
@@ -49979,9 +49979,9 @@ function decide({
     action: { kind: action }
   };
 }
-function clientTokenFor(doorbell) {
-  const generation = doorbell.microvmId ?? doorbell.occurredAt;
-  return (0, import_node_crypto12.createHash)("sha256").update(`${doorbell.runnerId}:${generation}`).digest("hex");
+function clientTokenFor(doorbellRequest) {
+  const generation = doorbellRequest.microvmId ?? doorbellRequest.occurredAt;
+  return (0, import_node_crypto12.createHash)("sha256").update(`${doorbellRequest.runnerId}:${generation}`).digest("hex");
 }
 function parseImageVersion(value) {
   const parts = value.trim().split(".");
@@ -50001,17 +50001,17 @@ function compareImageVersions(a7, b7) {
   }
   return 0;
 }
-async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, microvm) {
+async function shouldRecreateForNewerImage(doorbellRequest, shape, runningVersion, microvm) {
   if (runningVersion === void 0) {
     console.warn(
-      `[doorbell] GetMicrovm reported no imageVersion for runner ${doorbell.runnerId}; resuming`
+      `[doorbell] GetMicrovm reported no imageVersion for runner ${doorbellRequest.runnerId}; resuming`
     );
     return false;
   }
   const running = parseImageVersion(runningVersion);
   if (running === void 0) {
     console.warn(
-      `[doorbell] unparseable running imageVersion "${runningVersion}" for runner ${doorbell.runnerId}; resuming`
+      `[doorbell] unparseable running imageVersion "${runningVersion}" for runner ${doorbellRequest.runnerId}; resuming`
     );
     return false;
   }
@@ -50020,14 +50020,14 @@ async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, micr
     latestVersion = await microvm.latestImageVersion(shape.imageArn);
   } catch (error3) {
     console.warn(
-      `[doorbell] GetMicrovmImage failed for runner ${doorbell.runnerId}; resuming on the running image ${runningVersion}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] GetMicrovmImage failed for runner ${doorbellRequest.runnerId}; resuming on the running image ${runningVersion}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return false;
   }
   const latest = latestVersion === void 0 ? void 0 : parseImageVersion(latestVersion);
   if (latest === void 0) {
     console.warn(
-      `[doorbell] no comparable latest image version (${latestVersion ?? "none"}) for runner ${doorbell.runnerId}; resuming on the running image ${runningVersion}`
+      `[doorbell] no comparable latest image version (${latestVersion ?? "none"}) for runner ${doorbellRequest.runnerId}; resuming on the running image ${runningVersion}`
     );
     return false;
   }
@@ -50049,7 +50049,7 @@ async function handleDoorbell({
       reason: REASON.invalidSignature
     });
   }
-  const parsed = parseDoorbell(rawBody);
+  const parsed = parseDoorbellRequest(rawBody);
   if (!parsed.ok) {
     return decide({
       statusCode: 400,
@@ -50057,9 +50057,9 @@ async function handleDoorbell({
       reason: parsed.reason
     });
   }
-  const doorbell = parsed.doorbell;
+  const doorbellRequest = parsed.doorbell;
   const timing = { sleep: sleep4, random };
-  if (doorbell.type === SHAPES_EVENT_TYPE) {
+  if (doorbellRequest.type === SHAPES_EVENT_TYPE) {
     return decide({
       statusCode: 200,
       action: "describe",
@@ -50067,43 +50067,43 @@ async function handleDoorbell({
       shapes: shapes.advertise()
     });
   }
-  if (doorbell.type !== "runner.suspend_requested") {
-    const resolvedShape = shapes.resolve(doorbell.shape);
+  if (doorbellRequest.type !== "runner.suspend_requested") {
+    const resolvedShape = shapes.resolve(doorbellRequest.shape);
     if (resolvedShape === void 0) {
       return decide({
         statusCode: 400,
         action: "rejected",
         reason: REASON.unknownShape,
-        runnerId: doorbell.runnerId,
-        microvmId: doorbell.microvmId
+        runnerId: doorbellRequest.runnerId,
+        microvmId: doorbellRequest.microvmId
       });
     }
-    return handleWakeDoorbell(doorbell, resolvedShape, microvm, timing);
+    return handleWakeDoorbell(doorbellRequest, resolvedShape, microvm, timing);
   }
-  return suspendMicrovm(doorbell, microvm, timing);
+  return suspendMicrovm(doorbellRequest, microvm, timing);
 }
-async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
-  if (doorbell.microvmId === void 0) {
-    return runMicrovm(doorbell, shape, microvm, timing, false, REASON.noMicrovmId);
+async function handleWakeDoorbell(doorbellRequest, shape, microvm, timing) {
+  if (doorbellRequest.microvmId === void 0) {
+    return runMicrovm(doorbellRequest, shape, microvm, timing, false, REASON.noMicrovmId);
   }
   let described;
   let polled = false;
   try {
-    described = await microvm.describe(doorbell.microvmId);
+    described = await microvm.describe(doorbellRequest.microvmId);
     if (described.state === "SUSPENDING") {
-      described = await pollWhileSuspending(doorbell.microvmId, microvm, timing.sleep);
+      described = await pollWhileSuspending(doorbellRequest.microvmId, microvm, timing.sleep);
       polled = true;
     }
   } catch (error3) {
     console.error(
-      `[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] GetMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "none",
       reason: REASON.getStateFailed,
-      runnerId: doorbell.runnerId,
-      microvmId: doorbell.microvmId
+      runnerId: doorbellRequest.runnerId,
+      microvmId: doorbellRequest.microvmId
     });
   }
   const state3 = described.state;
@@ -50113,8 +50113,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
       action: "none",
       reason: REASON.suspendingPollExhausted,
       state: state3,
-      runnerId: doorbell.runnerId,
-      microvmId: doorbell.microvmId,
+      runnerId: doorbellRequest.runnerId,
+      microvmId: doorbellRequest.microvmId,
       polled
     });
   }
@@ -50126,16 +50126,16 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         action: "none",
         reason: state3 === "RUNNING" ? REASON.alreadyRunning : REASON.alreadyStarting,
         state: state3,
-        runnerId: doorbell.runnerId,
-        microvmId: doorbell.microvmId,
+        runnerId: doorbellRequest.runnerId,
+        microvmId: doorbellRequest.microvmId,
         polled,
         startedAt: described.startedAt,
         imageVersion: described.imageVersion
       });
     case "SUSPENDED":
-      if (doorbell.recreateOnOutdatedImage === true && await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
+      if (doorbellRequest.recreateOnOutdatedImage === true && await shouldRecreateForNewerImage(doorbellRequest, shape, described.imageVersion, microvm)) {
         return runMicrovm(
-          doorbell,
+          doorbellRequest,
           shape,
           microvm,
           timing,
@@ -50145,8 +50145,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         );
       }
       return resumeMicrovm(
-        doorbell,
-        doorbell.microvmId,
+        doorbellRequest,
+        doorbellRequest.microvmId,
         shape,
         microvm,
         timing,
@@ -50156,7 +50156,7 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
       );
     default:
       return runMicrovm(
-        doorbell,
+        doorbellRequest,
         shape,
         microvm,
         timing,
@@ -50182,14 +50182,14 @@ function isClientTokenParameterMismatch(error3) {
   const message = typeof e7.message === "string" ? e7.message.toLowerCase() : "";
   return message.includes("clienttoken") && message.includes("different request parameters");
 }
-async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, state3) {
+async function runMicrovm(doorbellRequest, shape, microvm, timing, polled, reason, state3) {
   let started;
   try {
     started = await withThrottleRetry(
       () => microvm.run({
         imageIdentifier: shape.imageArn,
-        runHookPayload: doorbell.runHookPayload,
-        clientToken: clientTokenFor(doorbell)
+        runHookPayload: doorbellRequest.runHookPayload,
+        clientToken: clientTokenFor(doorbellRequest)
       }),
       timing
     );
@@ -50198,26 +50198,26 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
       const name = error3 instanceof Error ? error3.name : "unknown";
       const message = error3 instanceof Error ? error3.message : String(error3);
       console.warn(
-        `[doorbell] RunMicrovm clientToken already used for runner ${doorbell.runnerId}: ${name}: ${message}`
+        `[doorbell] RunMicrovm clientToken already used for runner ${doorbellRequest.runnerId}: ${name}: ${message}`
       );
       return decide({
         statusCode: 200,
         action: "run",
         reason: REASON.runAlreadyStartedForToken,
         state: state3,
-        runnerId: doorbell.runnerId,
+        runnerId: doorbellRequest.runnerId,
         polled
       });
     }
     console.error(
-      `[doorbell] RunMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] RunMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "run",
       reason: REASON.runFailed,
       state: state3,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       polled
     });
   }
@@ -50226,22 +50226,22 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
     action: "run",
     reason,
     state: state3,
-    runnerId: doorbell.runnerId,
+    runnerId: doorbellRequest.runnerId,
     microvmId: started.microvmId,
     polled,
     startedAt: started.startedAt,
     imageVersion: started.imageVersion
   });
 }
-async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, startedAt, imageVersion) {
+async function resumeMicrovm(doorbellRequest, microvmId, shape, microvm, timing, polled, startedAt, imageVersion) {
   try {
     await withThrottleRetry(() => microvm.resume(microvmId), timing);
   } catch (error3) {
     console.error(
-      `[doorbell] ResumeMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] ResumeMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return runMicrovm(
-      doorbell,
+      doorbellRequest,
       shape,
       microvm,
       timing,
@@ -50255,21 +50255,21 @@ async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled
     action: "resume",
     reason: REASON.resumed,
     state: "SUSPENDED",
-    runnerId: doorbell.runnerId,
+    runnerId: doorbellRequest.runnerId,
     microvmId,
     polled,
     startedAt,
     imageVersion
   });
 }
-async function suspendMicrovm(doorbell, microvm, timing) {
-  const microvmId = doorbell.microvmId;
+async function suspendMicrovm(doorbellRequest, microvm, timing) {
+  const microvmId = doorbellRequest.microvmId;
   if (microvmId === void 0) {
     return decide({
       statusCode: 200,
       action: "none",
       reason: REASON.suspendWithoutMicrovmId,
-      runnerId: doorbell.runnerId
+      runnerId: doorbellRequest.runnerId
     });
   }
   let state3;
@@ -50277,13 +50277,13 @@ async function suspendMicrovm(doorbell, microvm, timing) {
     ({ state: state3 } = await microvm.describe(microvmId));
   } catch (error3) {
     console.error(
-      `[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] GetMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "none",
       reason: REASON.getStateFailed,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       microvmId
     });
   }
@@ -50293,7 +50293,7 @@ async function suspendMicrovm(doorbell, microvm, timing) {
       action: "none",
       reason: REASON.suspendAlreadyGone,
       state: state3,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       microvmId
     });
   }
@@ -50301,14 +50301,14 @@ async function suspendMicrovm(doorbell, microvm, timing) {
     await withThrottleRetry(() => microvm.suspend(microvmId), timing);
   } catch (error3) {
     console.error(
-      `[doorbell] SuspendMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] SuspendMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "suspend",
       reason: REASON.suspendFailed,
       state: state3,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       microvmId
     });
   }
@@ -50317,7 +50317,7 @@ async function suspendMicrovm(doorbell, microvm, timing) {
     action: "suspend",
     reason: REASON.suspended,
     state: state3,
-    runnerId: doorbell.runnerId,
+    runnerId: doorbellRequest.runnerId,
     microvmId
   });
 }
@@ -50468,12 +50468,7 @@ function createRuntimeMicrovm(executionRoleArn) {
           // No `idlePolicy` (AC5, #732) — deliberately, not an oversight.
           // `maxIdleDurationSeconds` measures INBOUND endpoint traffic only; our
           // runner is outbound-only (it dials the Cloudflare relay), so AWS sees
-          // an idle endpoint no matter how busy the agent is. Phase 0 measured
-          // this directly: a VM with `maxIdleDurationSeconds=60` and zero inbound
-          // traffic was suspended after 71 s while its guest process was alive
-          // and working (docs/spikes/lambda-microvms-phase0/README.md). AWS's own
-          // Claude-agents guidance recommending `maxIdleDurationSeconds: 120`
-          // targets VMs reached inbound and does not apply here. Idle is instead
+          // an idle endpoint no matter how busy the agent is. Idle is instead
           // decided IN the VM by `evident run --idle-timeout`
           // (packages/runner-cdk/microvm-image/hooks/common.sh's `IDLE_TIMEOUT_SECONDS`), whose
           // clean exit is what drives the controller's own `suspend()` below via

package/dist/microvm/controller/{doorbell.d.ts → doorbell-request.d.ts}

@@ -27,12 +27,12 @@ declare const WAKE_EVENT_TYPES: readonly ["agent.message_queued", "agent.wake_re
 declare const SUSPEND_EVENT_TYPE = "runner.suspend_requested";
 export declare const SHAPES_EVENT_TYPE = "runner.shapes_requested";
 type WakeEventType = (typeof WAKE_EVENT_TYPES)[number];
-type DoorbellFields = {
+type DoorbellRequestFields = {
     runnerId: string;
     occurredAt: string;
     microvmId?: string;
 };
-export type WakeDoorbell = DoorbellFields & {
+export type WakeDoorbellRequest = DoorbellRequestFields & {
     type: WakeEventType;
     runHookPayload: string;
     /**
@@ -46,7 +46,7 @@ export type WakeDoorbell = DoorbellFields & {
      */
     recreateOnOutdatedImage?: boolean;
 };
-export type Doorbell = WakeDoorbell | (DoorbellFields & {
+export type DoorbellRequest = WakeDoorbellRequest | (DoorbellRequestFields & {
     type: typeof SUSPEND_EVENT_TYPE;
 }) | {
     type: typeof SHAPES_EVENT_TYPE;
@@ -67,12 +67,12 @@ export declare const DOORBELL_REJECTION: {
     readonly runPayloadTooLarge: "run_payload_too_large";
 };
 export type DoorbellRejection = (typeof DOORBELL_REJECTION)[keyof typeof DOORBELL_REJECTION];
-export type ParsedDoorbell = {
+export type ParsedDoorbellRequest = {
     ok: true;
-    doorbell: Doorbell;
+    doorbell: DoorbellRequest;
 } | {
     ok: false;
     reason: DoorbellRejection;
 };
-export declare function parseDoorbell(rawBody: string): ParsedDoorbell;
+export declare function parseDoorbellRequest(rawBody: string): ParsedDoorbellRequest;
 export {};

package/dist/microvm/controller/{doorbell.js → doorbell-request.js}

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DOORBELL_REJECTION = exports.SHAPES_EVENT_TYPE = void 0;
-exports.parseDoorbell = parseDoorbell;
+exports.parseDoorbellRequest = parseDoorbellRequest;
 const constants_1 = require("../constants");
 /**
  * The doorbell Evident POSTs to the controller's Function URL. `run_payload` is
@@ -52,7 +52,7 @@ function nonBlankString(value) {
 function isWakeType(value) {
     return WAKE_EVENT_TYPES.includes(value);
 }
-function parseDoorbell(rawBody) {
+function parseDoorbellRequest(rawBody) {
     let body;
     try {
         body = JSON.parse(rawBody);

package/dist/microvm/controller/handle-doorbell.js

@@ -4,7 +4,7 @@ exports.handleDoorbell = handleDoorbell;
 const node_crypto_1 = require("node:crypto");
 const sdk_1 = require("@evident/sdk");
 const constants_1 = require("../constants");
-const doorbell_1 = require("./doorbell");
+const doorbell_request_1 = require("./doorbell-request");
 const throttle_retry_1 = require("./throttle-retry");
 const REASON = {
     invalidSignature: 'invalid_signature',
@@ -65,7 +65,7 @@ function decide({ statusCode, action, reason, state, runnerId, microvmId, starte
 }
 /**
  * `RunMicrovm`'s idempotency key. Keyed on `runner_id` plus a "generation"
- * marker: the dead VM's `microvm_id` on the recovery arms (`doorbell.microvmId`
+ * marker: the dead VM's `microvm_id` on the recovery arms (`doorbellRequest.microvmId`
  * is defined — TERMINATED/TERMINATING/not_found and the resume-failed
  * fallback), else `occurred_at` on the cold arm (no `microvm_id` yet). The id
  * advances every VM generation — `mvm-A` dies, the token keyed on it starts
@@ -92,9 +92,9 @@ function decide({ statusCode, action, reason, state, runnerId, microvmId, starte
  * that retried the same event with a different shape starts TWO concurrent
  * 8-hour VMs instead of deduping to one.
  */
-function clientTokenFor(doorbell) {
-    const generation = doorbell.microvmId ?? doorbell.occurredAt;
-    return (0, node_crypto_1.createHash)('sha256').update(`${doorbell.runnerId}:${generation}`).digest('hex');
+function clientTokenFor(doorbellRequest) {
+    const generation = doorbellRequest.microvmId ?? doorbellRequest.occurredAt;
+    return (0, node_crypto_1.createHash)('sha256').update(`${doorbellRequest.runnerId}:${generation}`).digest('hex');
 }
 /**
  * MicroVM image versions are dotted decimals (`48.0`, `50.0`), so they must NOT
@@ -140,15 +140,15 @@ function compareImageVersions(a, b) {
  * unparseable all warn and return false, i.e. resume exactly as before
  * (`development-workflow.mdc`: never fail a gate on absent evidence).
  */
-async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, microvm) {
+async function shouldRecreateForNewerImage(doorbellRequest, shape, runningVersion, microvm) {
     if (runningVersion === undefined) {
-        console.warn(`[doorbell] GetMicrovm reported no imageVersion for runner ${doorbell.runnerId}; resuming`);
+        console.warn(`[doorbell] GetMicrovm reported no imageVersion for runner ${doorbellRequest.runnerId}; resuming`);
         return false;
     }
     const running = parseImageVersion(runningVersion);
     if (running === undefined) {
         console.warn(`[doorbell] unparseable running imageVersion "${runningVersion}" for runner ` +
-            `${doorbell.runnerId}; resuming`);
+            `${doorbellRequest.runnerId}; resuming`);
         return false;
     }
     let latestVersion;
@@ -159,14 +159,14 @@ async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, micr
         latestVersion = await microvm.latestImageVersion(shape.imageArn);
     }
     catch (error) {
-        console.warn(`[doorbell] GetMicrovmImage failed for runner ${doorbell.runnerId}; resuming on the ` +
+        console.warn(`[doorbell] GetMicrovmImage failed for runner ${doorbellRequest.runnerId}; resuming on the ` +
             `running image ${runningVersion}: ${error instanceof Error ? error.message : String(error)}`);
         return false;
     }
     const latest = latestVersion === undefined ? undefined : parseImageVersion(latestVersion);
     if (latest === undefined) {
         console.warn(`[doorbell] no comparable latest image version (${latestVersion ?? 'none'}) for runner ` +
-            `${doorbell.runnerId}; resuming on the running image ${runningVersion}`);
+            `${doorbellRequest.runnerId}; resuming on the running image ${runningVersion}`);
         return false;
     }
     // Strictly below, not merely different: a running version ABOVE the latest
@@ -182,7 +182,7 @@ async function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes
             reason: REASON.invalidSignature,
         });
     }
-    const parsed = (0, doorbell_1.parseDoorbell)(rawBody);
+    const parsed = (0, doorbell_request_1.parseDoorbellRequest)(rawBody);
     if (!parsed.ok) {
         return decide({
             statusCode: 400,
@@ -190,10 +190,10 @@ async function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes
             reason: parsed.reason,
         });
     }
-    const doorbell = parsed.doorbell;
+    const doorbellRequest = parsed.doorbell;
     const timing = { sleep, random };
-    if (doorbell.type === doorbell_1.SHAPES_EVENT_TYPE) {
-        // A pure read of deploy-time metadata — see doorbell.ts's header comment
+    if (doorbellRequest.type === doorbell_request_1.SHAPES_EVENT_TYPE) {
+        // A pure read of deploy-time metadata — see doorbell-request.ts's header comment
         // (D2) for why replay is deliberately undefended here.
         return decide({
             statusCode: 200,
@@ -202,46 +202,46 @@ async function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes
             shapes: shapes.advertise(),
         });
     }
-    // Resolve the requested shape immediately after parseDoorbell/the describe
+    // Resolve the requested shape immediately after parseDoorbellRequest/the describe
     // arm — BEFORE the suspend_requested branch and the whole state machine
     // (D5). Resolving lazily inside runMicrovm would return 200 and silently
     // ignore a removed shape on the RUNNING/PENDING no-op path and the
     // successful-resume path, since runMicrovm is never reached on either. A
     // suspend doorbell has no `shape` field, so nothing here runs for it.
-    if (doorbell.type !== 'runner.suspend_requested') {
-        const resolvedShape = shapes.resolve(doorbell.shape);
+    if (doorbellRequest.type !== 'runner.suspend_requested') {
+        const resolvedShape = shapes.resolve(doorbellRequest.shape);
         if (resolvedShape === undefined) {
             // 400, not 404/409: a redelivery of the identical body cannot fix this.
             // Never echo the requested shape name — the closed-constant rule
-            // (doorbell.ts's DOORBELL_REJECTION) applies to every reason here too,
+            // (doorbell-request.ts's DOORBELL_REJECTION) applies to every reason here too,
             // and Evident persists response_body.
             return decide({
                 statusCode: 400,
                 action: 'rejected',
                 reason: REASON.unknownShape,
-                runnerId: doorbell.runnerId,
-                microvmId: doorbell.microvmId,
+                runnerId: doorbellRequest.runnerId,
+                microvmId: doorbellRequest.microvmId,
             });
         }
-        return handleWakeDoorbell(doorbell, resolvedShape, microvm, timing);
+        return handleWakeDoorbell(doorbellRequest, resolvedShape, microvm, timing);
     }
-    return suspendMicrovm(doorbell, microvm, timing);
+    return suspendMicrovm(doorbellRequest, microvm, timing);
 }
-async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
-    if (doorbell.microvmId === undefined) {
-        return runMicrovm(doorbell, shape, microvm, timing, false, REASON.noMicrovmId);
+async function handleWakeDoorbell(doorbellRequest, shape, microvm, timing) {
+    if (doorbellRequest.microvmId === undefined) {
+        return runMicrovm(doorbellRequest, shape, microvm, timing, false, REASON.noMicrovmId);
     }
     let described;
     let polled = false;
     try {
-        described = await microvm.describe(doorbell.microvmId);
+        described = await microvm.describe(doorbellRequest.microvmId);
         if (described.state === 'SUSPENDING') {
-            described = await pollWhileSuspending(doorbell.microvmId, microvm, timing.sleep);
+            described = await pollWhileSuspending(doorbellRequest.microvmId, microvm, timing.sleep);
             polled = true;
         }
     }
     catch (error) {
-        console.error(`[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ` +
+        console.error(`[doorbell] GetMicrovm failed for runner ${doorbellRequest.runnerId}: ` +
             `${error instanceof Error ? error.message : String(error)}`);
         // `polled` is omitted here, not passed as `false`: it is only assigned
         // `true` after `pollWhileSuspending` returns, so a throw mid-poll would
@@ -250,8 +250,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
             statusCode: 500,
             action: 'none',
             reason: REASON.getStateFailed,
-            runnerId: doorbell.runnerId,
-            microvmId: doorbell.microvmId,
+            runnerId: doorbellRequest.runnerId,
+            microvmId: doorbellRequest.microvmId,
         });
     }
     const state = described.state;
@@ -264,8 +264,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
             action: 'none',
             reason: REASON.suspendingPollExhausted,
             state,
-            runnerId: doorbell.runnerId,
-            microvmId: doorbell.microvmId,
+            runnerId: doorbellRequest.runnerId,
+            microvmId: doorbellRequest.microvmId,
             polled,
         });
     }
@@ -279,8 +279,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
                 action: 'none',
                 reason: state === 'RUNNING' ? REASON.alreadyRunning : REASON.alreadyStarting,
                 state,
-                runnerId: doorbell.runnerId,
-                microvmId: doorbell.microvmId,
+                runnerId: doorbellRequest.runnerId,
+                microvmId: doorbellRequest.microvmId,
                 polled,
                 startedAt: described.startedAt,
                 imageVersion: described.imageVersion,
@@ -290,15 +290,15 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
             // request (#1906) can still set the same wire flag. Recreate loses VM-local
             // filesystem state; durable provider credentials survive in object storage,
             // but a manual paste/upload not yet synced there may be lost (#2071).
-            if (doorbell.recreateOnOutdatedImage === true &&
-                (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm))) {
-                return runMicrovm(doorbell, shape, microvm, timing, polled, REASON.imageVersionOutdated, state);
+            if (doorbellRequest.recreateOnOutdatedImage === true &&
+                (await shouldRecreateForNewerImage(doorbellRequest, shape, described.imageVersion, microvm))) {
+                return runMicrovm(doorbellRequest, shape, microvm, timing, polled, REASON.imageVersionOutdated, state);
             }
-            return resumeMicrovm(doorbell, doorbell.microvmId, shape, microvm, timing, polled, described.startedAt, described.imageVersion);
+            return resumeMicrovm(doorbellRequest, doorbellRequest.microvmId, shape, microvm, timing, polled, described.startedAt, described.imageVersion);
         default:
             // TERMINATED, TERMINATING, not_found — gone or going, so a fresh VM either
             // way. This is what self-heals a stale `microvm_id`.
-            return runMicrovm(doorbell, shape, microvm, timing, polled, state === 'not_found' ? REASON.microvmNotFound : REASON.terminated, state);
+            return runMicrovm(doorbellRequest, shape, microvm, timing, polled, state === 'not_found' ? REASON.microvmNotFound : REASON.terminated, state);
     }
 }
 /**
@@ -333,13 +333,13 @@ function isClientTokenParameterMismatch(error) {
     const message = typeof e.message === 'string' ? e.message.toLowerCase() : '';
     return message.includes('clienttoken') && message.includes('different request parameters');
 }
-async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, state) {
+async function runMicrovm(doorbellRequest, shape, microvm, timing, polled, reason, state) {
     let started;
     try {
         started = await (0, throttle_retry_1.withThrottleRetry)(() => microvm.run({
             imageIdentifier: shape.imageArn,
-            runHookPayload: doorbell.runHookPayload,
-            clientToken: clientTokenFor(doorbell),
+            runHookPayload: doorbellRequest.runHookPayload,
+            clientToken: clientTokenFor(doorbellRequest),
         }), timing);
     }
     catch (error) {
@@ -353,7 +353,7 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
             // wakes.
             const name = error instanceof Error ? error.name : 'unknown';
             const message = error instanceof Error ? error.message : String(error);
-            console.warn(`[doorbell] RunMicrovm clientToken already used for runner ${doorbell.runnerId}: ` +
+            console.warn(`[doorbell] RunMicrovm clientToken already used for runner ${doorbellRequest.runnerId}: ` +
                 `${name}: ${message}`);
             // No `microvmId` (see the comment above), and therefore deliberately no
             // `startedAt` either: `decide`'s invariant is that `microvm_started_at`
@@ -365,18 +365,18 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
                 action: 'run',
                 reason: REASON.runAlreadyStartedForToken,
                 state,
-                runnerId: doorbell.runnerId,
+                runnerId: doorbellRequest.runnerId,
                 polled,
             });
         }
-        console.error(`[doorbell] RunMicrovm failed for runner ${doorbell.runnerId}: ` +
+        console.error(`[doorbell] RunMicrovm failed for runner ${doorbellRequest.runnerId}: ` +
             `${error instanceof Error ? error.message : String(error)}`);
         return decide({
             statusCode: 500,
             action: 'run',
             reason: REASON.runFailed,
             state,
-            runnerId: doorbell.runnerId,
+            runnerId: doorbellRequest.runnerId,
             polled,
         });
     }
@@ -385,14 +385,14 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
         action: 'run',
         reason,
         state,
-        runnerId: doorbell.runnerId,
+        runnerId: doorbellRequest.runnerId,
         microvmId: started.microvmId,
         polled,
         startedAt: started.startedAt,
         imageVersion: started.imageVersion,
     });
 }
-async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, 
+async function resumeMicrovm(doorbellRequest, microvmId, shape, microvm, timing, polled, 
 // Both values come from the `describe()` result that led here because
 // `ResumeMicrovm` returns no lifecycle metadata of its own.
 startedAt, imageVersion) {
@@ -400,24 +400,24 @@ startedAt, imageVersion) {
         await (0, throttle_retry_1.withThrottleRetry)(() => microvm.resume(microvmId), timing);
     }
     catch (error) {
-        console.error(`[doorbell] ResumeMicrovm failed for runner ${doorbell.runnerId}: ` +
+        console.error(`[doorbell] ResumeMicrovm failed for runner ${doorbellRequest.runnerId}: ` +
             `${error instanceof Error ? error.message : String(error)}`);
-        return runMicrovm(doorbell, shape, microvm, timing, polled, REASON.resumeFailedFallingBackToRun, 'SUSPENDED');
+        return runMicrovm(doorbellRequest, shape, microvm, timing, polled, REASON.resumeFailedFallingBackToRun, 'SUSPENDED');
     }
     return decide({
         statusCode: 200,
         action: 'resume',
         reason: REASON.resumed,
         state: 'SUSPENDED',
-        runnerId: doorbell.runnerId,
+        runnerId: doorbellRequest.runnerId,
         microvmId,
         polled,
         startedAt,
         imageVersion,
     });
 }
-async function suspendMicrovm(doorbell, microvm, timing) {
-    const microvmId = doorbell.microvmId;
+async function suspendMicrovm(doorbellRequest, microvm, timing) {
+    const microvmId = doorbellRequest.microvmId;
     if (microvmId === undefined) {
         // Nothing to suspend, and a redelivery would not change that — 200 so the
         // doorbell is not retried, but loudly enough to notice a mis-wired sender.
@@ -425,7 +425,7 @@ async function suspendMicrovm(doorbell, microvm, timing) {
             statusCode: 200,
             action: 'none',
             reason: REASON.suspendWithoutMicrovmId,
-            runnerId: doorbell.runnerId,
+            runnerId: doorbellRequest.runnerId,
         });
     }
     let state;
@@ -434,13 +434,13 @@ async function suspendMicrovm(doorbell, microvm, timing) {
         ({ state } = await microvm.describe(microvmId));
     }
     catch (error) {
-        console.error(`[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ` +
+        console.error(`[doorbell] GetMicrovm failed for runner ${doorbellRequest.runnerId}: ` +
             `${error instanceof Error ? error.message : String(error)}`);
         return decide({
             statusCode: 500,
             action: 'none',
             reason: REASON.getStateFailed,
-            runnerId: doorbell.runnerId,
+            runnerId: doorbellRequest.runnerId,
             microvmId,
         });
     }
@@ -453,7 +453,7 @@ async function suspendMicrovm(doorbell, microvm, timing) {
             action: 'none',
             reason: REASON.suspendAlreadyGone,
             state,
-            runnerId: doorbell.runnerId,
+            runnerId: doorbellRequest.runnerId,
             microvmId,
         });
     }
@@ -461,14 +461,14 @@ async function suspendMicrovm(doorbell, microvm, timing) {
         await (0, throttle_retry_1.withThrottleRetry)(() => microvm.suspend(microvmId), timing);
     }
     catch (error) {
-        console.error(`[doorbell] SuspendMicrovm failed for runner ${doorbell.runnerId}: ` +
+        console.error(`[doorbell] SuspendMicrovm failed for runner ${doorbellRequest.runnerId}: ` +
             `${error instanceof Error ? error.message : String(error)}`);
         return decide({
             statusCode: 500,
             action: 'suspend',
             reason: REASON.suspendFailed,
             state,
-            runnerId: doorbell.runnerId,
+            runnerId: doorbellRequest.runnerId,
             microvmId,
         });
     }
@@ -477,7 +477,7 @@ async function suspendMicrovm(doorbell, microvm, timing) {
         action: 'suspend',
         reason: REASON.suspended,
         state,
-        runnerId: doorbell.runnerId,
+        runnerId: doorbellRequest.runnerId,
         microvmId,
     });
 }

package/dist/microvm/image/stage-context.d.ts

@@ -35,7 +35,7 @@ export interface StageMicrovmImageContextOptions {
  *
  * The Dockerfile, hook server and phase hooks come from this package's
  * published `dist/`, so a consumer needs no checkout of the source repository and no
- * copy of those files (#1528). A caller may supply an overlay; the default is
+ * copy of those files. A caller may supply an overlay; the default is
  * deterministic no-op scripts. `repositoryPath` is the only required caller
  * input.
  */

package/dist/microvm/image/stage-context.js

@@ -127,7 +127,7 @@ function stageScriptDirectory(source, destination) {
  *
  * The Dockerfile, hook server and phase hooks come from this package's
  * published `dist/`, so a consumer needs no checkout of the source repository and no
- * copy of those files (#1528). A caller may supply an overlay; the default is
+ * copy of those files. A caller may supply an overlay; the default is
  * deterministic no-op scripts. `repositoryPath` is the only required caller
  * input.
  */

package/dist/microvm-image-context/hooks/common.sh

@@ -468,7 +468,6 @@ kill_litestream() {
   rm -f "${LITESTREAM_PID_FILE}"
   log "litestream stop signalled (no wait)"
 }
-# --- litestream replicate (end) ----------------------------------------------
 
 # --- flush_session_db (#812 WI-4) -------------------------------------------
 #

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "3.5.2-dev.bcf1140",
+  "version": "3.5.2-dev.da3340e",
   "description": "Reusable CDK constructs for an Evident agent runner: a single scale-to-zero Fargate runner (task + service + per-agent self-stop role + waker Lambda), or a per-session AWS Lambda MicroVM that boots on demand and suspends between messages. Instantiate once per agent from your own stack.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",