@evident-ai/runner-cdk 3.5.2-dev.43244a2 → 3.5.2-dev.8d3aa06

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/evident-scale-to-zero-construct.js

@@ -39,6 +39,7 @@ const constructs_1 = require("constructs");
 const ec2 = __importStar(require("aws-cdk-lib/aws-ec2"));
 const ecs = __importStar(require("aws-cdk-lib/aws-ecs"));
 const iam = __importStar(require("aws-cdk-lib/aws-iam"));
+const constants_1 = require("./microvm/constants");
 const construct_1 = require("./waker/construct");
 /** Current fixed value of `resourcePrefix`, kept as the default so an adopter
  *  omitting the prop reproduces today's physical names exactly. */
@@ -111,15 +112,7 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             GIT_BRANCH: gitBranch ?? 'main',
             // Scale-to-zero self-stop inputs (the entrypoint uses these to scale to 0).
             EVIDENT_IDLE_TIMEOUT_SECONDS: String(idleTimeoutSeconds),
-            // Auto-cleanup (issue #190): `evident run` reads this directly and, once a
-            // retention rule is set, sweeps OpenCode sessions idle longer than the
-            // window (protected/active sessions are never touched). Tightened from 7d
-            // to 24h per #537: at 7d, opencode.db was observed growing ~11x (77 MB ->
-            // 849 MB) in ~24h, so 7d was far too permissive at the observed growth
-            // rate. 24h is the tighter mitigation that came out of that (see also the
-            // OPENCODE_VERSION pin above). Sweep runs on the default 1h interval and
-            // never touches a protected/active session.
-            EVIDENT_SESSION_CLEANUP_MAX_AGE: '24h',
+            EVIDENT_SESSION_CLEANUP_MAX_AGE: constants_1.SESSION_CLEANUP_MAX_AGE,
             CLUSTER: cluster.clusterName,
             SERVICE: serviceName,
             EVIDENT_SELFSTOP_ROLE_ARN: selfStopRole.roleArn,

package/dist/microvm/constants.d.ts

@@ -5,3 +5,5 @@ export declare const RUN_HOOK_PAYLOAD_MAX_BYTES = 16384;
 export declare const SUSPENDING_POLL_ATTEMPTS = 4;
 export declare const SUSPENDING_POLL_INTERVAL_MS = 500;
 export declare const MICROVM_MAX_RUN_SECONDS = 28800;
+export declare const SESSION_CLEANUP_MAX_AGE = "24h";
+export declare const DOORBELL_SECRET_KEY = "DOORBELL_SECRET";

package/dist/microvm/constants.js

@@ -1,10 +1,10 @@
 "use strict";
-// Shared literals for the MicroVM controller and for the image it launches.
+// Shared literals for the MicroVM controller, its image, and the Fargate runner.
 // Every module imports from here rather than restating a value that must match
 // across them. The image template pins matching copies, guarded by
 // `microvm/image/dockerfile.test.ts`.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MICROVM_MAX_RUN_SECONDS = exports.SUSPENDING_POLL_INTERVAL_MS = exports.SUSPENDING_POLL_ATTEMPTS = exports.RUN_HOOK_PAYLOAD_MAX_BYTES = exports.HOOK_TIMEOUT_SECONDS = exports.HOOKS_DIR = exports.HOOKS_PORT = void 0;
+exports.DOORBELL_SECRET_KEY = exports.SESSION_CLEANUP_MAX_AGE = exports.MICROVM_MAX_RUN_SECONDS = exports.SUSPENDING_POLL_INTERVAL_MS = exports.SUSPENDING_POLL_ATTEMPTS = exports.RUN_HOOK_PAYLOAD_MAX_BYTES = exports.HOOK_TIMEOUT_SECONDS = exports.HOOKS_DIR = exports.HOOKS_PORT = void 0;
 // The port the image's hook server binds, baked into the published Dockerfile
 // (`ENV HOOKS_PORT`) and passed to the construct as `hooksPort`. Exported from
 // the package index because a consumer building the published image context
@@ -32,3 +32,12 @@ exports.SUSPENDING_POLL_INTERVAL_MS = 500;
 // longer than any VM can possibly still be running, no VM started before the
 // deactivation can outlive it. The two MUST move together.
 exports.MICROVM_MAX_RUN_SECONDS = 28800;
+// Auto-cleanup (issue #190): `evident run` reads this directly from the Fargate
+// task and MicroVM image. Setting a retention rule makes it sweep OpenCode
+// sessions idle longer than 24h; protected/active sessions are never touched.
+// The 24h window rather than 7d keeps the session database bounded at the growth
+// rate observed in #537. The sweep runs on the default 1h interval.
+exports.SESSION_CLEANUP_MAX_AGE = '24h';
+// The JSON field inside the doorbell secret is shared by the Lambdas that name
+// it and by whatever produces the secret; this is never the secret value.
+exports.DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';

package/dist/microvm/construct.js

@@ -40,14 +40,12 @@ const constructs_1 = require("constructs");
 const lambda = __importStar(require("aws-cdk-lib/aws-lambda"));
 const s3 = __importStar(require("aws-cdk-lib/aws-s3"));
 const lambda_microvm_cdk_1 = require("@evident-ai/lambda-microvm-cdk");
+const constants_1 = require("./constants");
 const shapes_1 = require("./shapes");
 const construct_1 = require("./image-version-reporter/construct");
 // Image hooks build the snapshot, so they get minutes where the runtime hooks
 // get AWS's 60 s.
 const IMAGE_HOOK_TIMEOUT_SECONDS = 600;
-// The field inside the doorbell secret, shared by this construct (which
-// names it for the controller) and whatever produced `props.doorbellSecret`.
-const DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';
 /**
  * The customer-account half of the per-session runner (#558): the MicroVM
  * image and the roles it builds and runs as, plus the stateless controller
@@ -127,10 +125,8 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
             // ("Environment variable key 'AWS_REGION' is reserved", 400), which is
             // also why the synchroniser's S3 client does not need it set — the
             // MicroVM runtime supplies the region itself.
-            // Read by `evident run` itself (not the hooks), the same 24h window ECS
-            // already bakes in for its own runners (evident-scale-to-zero-construct.ts:191).
             // Safe to bake: identical for every VM from this image version.
-            EVIDENT_SESSION_CLEANUP_MAX_AGE: '24h',
+            EVIDENT_SESSION_CLEANUP_MAX_AGE: constants_1.SESSION_CLEANUP_MAX_AGE,
             ...(props.runnerOpencodeConfigPath
                 ? { RUNNER_OPENCODE_CONFIG: props.runnerOpencodeConfigPath }
                 : {}),
@@ -240,7 +236,7 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
                 // Secrets Manager at runtime, so the key is not exposed to anyone with
                 // lambda:GetFunctionConfiguration.
                 DOORBELL_SECRET_ARN: props.doorbellSecret.secretArn,
-                DOORBELL_SECRET_KEY: DOORBELL_SECRET_KEY,
+                DOORBELL_SECRET_KEY: constants_1.DOORBELL_SECRET_KEY,
                 MICROVM_SHAPES: shapeCatalogueJson,
                 // The role every shape's MicroVM shares (D3) — still one role, still
                 // this same expression, now documented as shared rather than singular.

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-version-reporter/construct.js

@@ -39,8 +39,7 @@ const cdk = __importStar(require("aws-cdk-lib"));
 const constructs_1 = require("constructs");
 const lambda = __importStar(require("aws-cdk-lib/aws-lambda"));
 const cr = __importStar(require("aws-cdk-lib/custom-resources"));
-/** The JSON field name inside the doorbell secret, same key the controller reads. */
-const DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';
+const constants_1 = require("../constants");
 /**
  * Deploy-time push: reports each shape's just-published MicroVM image version to
  * Evident, once per deploy that actually changes it. `imageVersions` is the
@@ -66,7 +65,7 @@ class ImageVersionReporter extends constructs_1.Construct {
             environment: {
                 // ARN + field name only, never the value (mirrors the controller and waker).
                 DOORBELL_SECRET_ARN: props.doorbellSecret.secretArn,
-                DOORBELL_SECRET_KEY: DOORBELL_SECRET_KEY,
+                DOORBELL_SECRET_KEY: constants_1.DOORBELL_SECRET_KEY,
                 EVIDENT_API_URL: props.evidentApiUrl,
                 EVIDENT_RUNNER_ID: props.evidentRunnerId,
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "3.5.2-dev.43244a2",
+  "version": "3.5.2-dev.8d3aa06",
   "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",