@evident-ai/runner-cdk 0.1.1-dev.da70cd4 → 3.4.1-dev.1856549

package/dist/evident-scale-to-zero-construct.js

@@ -101,7 +101,7 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             // --endpoint / --tunnel). The agent is resolved from EVIDENT_AGENT_KEY.
             EVIDENT_API_URL: evidentApiUrl,
             EVIDENT_TUNNEL_URL: evidentTunnelUrl,
-            // Litestream replica target (read by packages/runner-synchroniser, which
+            // Litestream replica target (read by runner/synchroniser, which
             // generates /etc/evident/litestream.yml at boot).
             LITESTREAM_BUCKET: replicaBucket.bucketName,
             LITESTREAM_PREFIX: this.replicaPrefix,
@@ -115,10 +115,9 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             // 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 a tighter mitigation while the growth's root cause is
-            // investigated (see also the OPENCODE_VERSION pin above and the
-            // [memwatch] telemetry in entrypoint.sh). Sweep runs on the default 1h
-            // interval and never touches a protected/active session.
+            // 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',
             CLUSTER: cluster.clusterName,
             SERVICE: serviceName,

package/dist/index.d.ts

@@ -1,2 +1,6 @@
 export { EvidentScaleToZeroConstruct, type EvidentScaleToZeroConstructProps, } from './evident-scale-to-zero-construct';
 export { EvidentWaker, type EvidentWakerProps } from './waker/construct';
+export { EvidentMicrovmConstruct, type EvidentMicrovmConstructProps } from './microvm/construct';
+export { MICROVM_SHAPES, validateShapes, type MicrovmShape } from './microvm/shapes';
+export { MICROVM_MAX_RUN_SECONDS, HOOKS_PORT, HOOK_TIMEOUT_SECONDS, } from './microvm/constants';
+export { stageMicrovmImageContext, type StageMicrovmImageContextOptions, } from './microvm/image/stage-context';

package/dist/index.js

@@ -1,7 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EvidentWaker = exports.EvidentScaleToZeroConstruct = void 0;
+exports.stageMicrovmImageContext = exports.HOOK_TIMEOUT_SECONDS = exports.HOOKS_PORT = exports.MICROVM_MAX_RUN_SECONDS = exports.validateShapes = exports.MICROVM_SHAPES = exports.EvidentMicrovmConstruct = exports.EvidentWaker = exports.EvidentScaleToZeroConstruct = void 0;
 var evident_scale_to_zero_construct_1 = require("./evident-scale-to-zero-construct");
 Object.defineProperty(exports, "EvidentScaleToZeroConstruct", { enumerable: true, get: function () { return evident_scale_to_zero_construct_1.EvidentScaleToZeroConstruct; } });
 var construct_1 = require("./waker/construct");
 Object.defineProperty(exports, "EvidentWaker", { enumerable: true, get: function () { return construct_1.EvidentWaker; } });
+var construct_2 = require("./microvm/construct");
+Object.defineProperty(exports, "EvidentMicrovmConstruct", { enumerable: true, get: function () { return construct_2.EvidentMicrovmConstruct; } });
+var shapes_1 = require("./microvm/shapes");
+Object.defineProperty(exports, "MICROVM_SHAPES", { enumerable: true, get: function () { return shapes_1.MICROVM_SHAPES; } });
+Object.defineProperty(exports, "validateShapes", { enumerable: true, get: function () { return shapes_1.validateShapes; } });
+var constants_1 = require("./microvm/constants");
+Object.defineProperty(exports, "MICROVM_MAX_RUN_SECONDS", { enumerable: true, get: function () { return constants_1.MICROVM_MAX_RUN_SECONDS; } });
+// The two values a consumer MUST pass to `EvidentMicrovmConstruct` for them
+// to match the published image they were baked into (#1528).
+Object.defineProperty(exports, "HOOKS_PORT", { enumerable: true, get: function () { return constants_1.HOOKS_PORT; } });
+Object.defineProperty(exports, "HOOK_TIMEOUT_SECONDS", { enumerable: true, get: function () { return constants_1.HOOK_TIMEOUT_SECONDS; } });
+var stage_context_1 = require("./microvm/image/stage-context");
+Object.defineProperty(exports, "stageMicrovmImageContext", { enumerable: true, get: function () { return stage_context_1.stageMicrovmImageContext; } });

package/dist/microvm/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const HOOKS_PORT = 8080;
+export declare const HOOKS_DIR = "/etc/evident/hooks";
+export declare const HOOK_TIMEOUT_SECONDS = 60;
+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;

package/dist/microvm/constants.js

@@ -0,0 +1,34 @@
+"use strict";
+// Shared literals for the MicroVM controller and for the image it launches.
+// 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;
+// 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
+// MUST pass the value it was baked with — the construct's own docstring warns
+// that a mismatch means AWS probes a port nothing binds.
+exports.HOOKS_PORT = 8080;
+// One executable per lifecycle phase. A phase with no script is a no-op, which
+// is why the image ships none for `ready` or `validate`: nothing Evident-specific
+// may run before the snapshot, so there is nothing for them to do.
+exports.HOOKS_DIR = '/etc/evident/hooks';
+// Seconds AWS allows a Run/Resume/Suspend/Terminate hook, passed to the
+// construct as `hookTimeoutSeconds`. Exported for the same reason as
+// `HOOKS_PORT`: the hooks are built against it.
+exports.HOOK_TIMEOUT_SECONDS = 60;
+// AWS caps `runHookPayload` at 16 KiB; anything larger is rejected at its API,
+// so the controller checks it before spending a call.
+exports.RUN_HOOK_PAYLOAD_MAX_BYTES = 16384;
+// Worst-case poll (attempts × interval ≈ 2 s) must fit the controller Lambda's 8 s
+// timeout alongside the retry backoff.
+exports.SUSPENDING_POLL_ATTEMPTS = 4;
+exports.SUSPENDING_POLL_INTERVAL_MS = 500;
+// AWS's non-adjustable ceiling on a single MicroVM run, passed as
+// `RunMicrovmCommand`'s `maximumDurationInSeconds`. The version pruner reuses it
+// as its post-deactivation staging delay: once a version has been INACTIVE for
+// 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;

package/dist/microvm/construct.d.ts

@@ -0,0 +1,87 @@
+import { Construct } from 'constructs';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import { type MicrovmShape } from './shapes';
+export interface EvidentMicrovmConstructProps {
+    /**
+     * Build context for the image, already staged on disk. An argument rather
+     * than something this construct stages itself, so synthesising the stack
+     * stays a pure function of its inputs instead of depending on how the
+     * ambient checkout was cloned.
+     */
+    readonly imageSource: string;
+    /**
+     * ARN of the Lambda-managed base MicroVM image, from
+     * `aws lambda-microvms list-managed-microvm-images`. A string, not a `CfnParameter`
+     * built here: the caller creates the parameter at ITS OWN stack scope
+     * (preserving its logical id) and passes its resolved value down — a
+     * construct must not mint parameters into a consumer's stack.
+     */
+    readonly baseImageArn: string;
+    /**
+     * Version of the Lambda-managed base MicroVM image, from
+     * `aws lambda-microvms list-managed-microvm-images`. See `baseImageArn` for why this
+     * is a plain string.
+     */
+    readonly baseImageVersion: string;
+    /**
+     * The shape catalogue to build one image per shape from (#723). Defaults to
+     * `MICROVM_SHAPES`, the committed catalogue. Overridable so a caller can
+     * synth a local multi-shape template without mutating that module
+     * constant.
+     */
+    readonly shapes?: readonly MicrovmShape[];
+    /**
+     * The secret holding the shared HMAC key the controller verifies every
+     * doorbell against, under the field `DOORBELL_SECRET`. Any Secrets Manager
+     * secret, however the caller manages it — this construct has no opinion on
+     * SOPS, KMS, or any other production mechanism. Required (not defaulted
+     * here): a default would need a scope of its own, and a caller-owned
+     * default keeps its own logical id — the caller builds one exactly once,
+     * in its own scope, and passes the result in either case.
+     */
+    readonly doorbellSecret: secretsmanager.ISecret;
+    /**
+     * Optional runner secret whose JSON values are exported by `/run`. Omitting it
+     * leaves GitHub and MCP credentials unavailable to a generic consumer.
+     */
+    readonly runnerSecret?: secretsmanager.ISecret;
+    /**
+     * Optional runner OpenCode overlay. Absolute paths are image paths; relative
+     * paths are resolved from the baked workspace by the `/run` hook.
+     */
+    readonly runnerOpencodeConfigPath?: string;
+    /** Optional git identity the `/run` hook configures for agent commits. */
+    readonly gitUserName?: string;
+    /** Optional git email the `/run` hook configures for agent commits. */
+    readonly gitUserEmail?: string;
+    /**
+     * TCP port the image's hook server listens on, baked into both the image
+     * (`HOOKS_PORT` env var) and the `MicrovmImage`'s `hooks.port` — a mismatch
+     * means AWS probes a port nothing binds. Caller-supplied because the hook
+     * server is part of `imageSource`, which this construct does not build.
+     */
+    readonly hooksPort: number;
+    /**
+     * Seconds AWS waits for a Run/Resume/Suspend/Terminate hook to answer,
+     * before the image build itself times out (`IMAGE_HOOK_TIMEOUT_SECONDS`,
+     * fixed at 600 s — building the snapshot is a different budget from
+     * running a hook).
+     */
+    readonly hookTimeoutSeconds: number;
+}
+/**
+ * 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
+ * Lambda that turns a signed doorbell into RunMicrovm / ResumeMicrovm /
+ * SuspendMicrovm.
+ */
+export declare class EvidentMicrovmConstruct extends Construct {
+    /** POST target for Evident's signed doorbell (HMAC-verified in the handler). */
+    readonly functionUrl: string;
+    /** The shapes the controller can launch, with the image ARN each RunMicrovm uses. */
+    readonly shapeCatalogueJson: string;
+    /** Bucket a runner restores model credentials from: seed `<state_prefix>/claude/credentials.json` here. */
+    readonly durableStateBucket: s3.Bucket;
+    constructor(scope: Construct, id: string, props: EvidentMicrovmConstructProps);
+}

package/dist/microvm/construct.js

@@ -0,0 +1,253 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidentMicrovmConstruct = void 0;
+const path = __importStar(require("path"));
+const cdk = __importStar(require("aws-cdk-lib"));
+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 shapes_1 = require("./shapes");
+// 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
+ * Lambda that turns a signed doorbell into RunMicrovm / ResumeMicrovm /
+ * SuspendMicrovm.
+ */
+class EvidentMicrovmConstruct extends constructs_1.Construct {
+    /** POST target for Evident's signed doorbell (HMAC-verified in the handler). */
+    functionUrl;
+    /** The shapes the controller can launch, with the image ARN each RunMicrovm uses. */
+    shapeCatalogueJson;
+    /** Bucket a runner restores model credentials from: seed `<state_prefix>/claude/credentials.json` here. */
+    durableStateBucket;
+    constructor(scope, id, props) {
+        super(scope, id);
+        // Synth-time failure, before any construct exists.
+        const shapes = (0, shapes_1.validateShapes)(props.shapes ?? shapes_1.MICROVM_SHAPES);
+        const [defaultShape, ...additionalShapes] = shapes;
+        // The model credentials a runner restores at /run, and the litestream
+        // session replica (it is `LITESTREAM_BUCKET` below), share one per-runner
+        // prefix chosen at /run — synth can't name it, and lifecycle filters take
+        // a literal prefix with no wildcards, so any rule here is bucket-wide.
+        // RETAIN: deleting the stack must not cost hand-bootstrapped logins.
+        // Versioned, plus the 7-day noncurrent-version expiry below: a clobbered
+        // credential is fixed by the user re-authenticating their provider, not a
+        // version restore, so the versions carry no credential-recovery duty —
+        // the window instead covers the operator accident-net for a manually
+        // deleted corrupt replica (`--on-unusable-replica=leave` never self-heals
+        // one; see README). No current-object expiration, deliberately — that
+        // would destroy both outright. Count-based retention
+        // (`noncurrentVersionsToRetain`) would reap nothing here instead: it's
+        // ANDed with the age condition and counts newer noncurrent versions of
+        // the SAME key, but litestream's LTX keys are txid-unique and churn by
+        // DELETE, so a churned key has exactly one noncurrent version and zero
+        // newer ones. `expiredObjectDeleteMarker` reaps the delete marker itself once
+        // its noncurrent version is gone — without it, the version index grows
+        // unboundedly, one marker per churned LTX key.
+        const durableState = new s3.Bucket(this, 'DurableState', {
+            encryption: s3.BucketEncryption.S3_MANAGED,
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            versioned: true,
+            enforceSSL: true,
+            removalPolicy: cdk.RemovalPolicy.RETAIN,
+            lifecycleRules: [
+                {
+                    // Litestream uploads multipart; an abandoned upload is billed and is
+                    // invisible to ListObjectsV2, so nothing else would ever reap it.
+                    id: 'AbortIncompleteUploads',
+                    abortIncompleteMultipartUploadAfter: cdk.Duration.days(7),
+                },
+                {
+                    id: 'ExpireNoncurrentVersions',
+                    noncurrentVersionExpiration: cdk.Duration.days(7),
+                    expiredObjectDeleteMarker: true,
+                },
+            ],
+        });
+        // The environment shared by every shape's image...
+        const imageEnvironment = {
+            HOOKS_PORT: String(props.hooksPort),
+            // The bucket is identical for every VM from this image version, so it
+            // may be baked. The PREFIX inside it may NOT: it selects one runner's
+            // credential store, so baking it would point every VM at the same one.
+            // It arrives per-VM in the /run payload — `hook-scripts.test.ts` and
+            // this construct's test both hold that line.
+            LITESTREAM_BUCKET: durableState.bucketName,
+            // No AWS_REGION here: the service rejects it as a reserved key
+            // ("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',
+            ...(props.runnerOpencodeConfigPath
+                ? { RUNNER_OPENCODE_CONFIG: props.runnerOpencodeConfigPath }
+                : {}),
+            ...(props.runnerSecret ? { RUNNER_SECRET_ARN: props.runnerSecret.secretArn } : {}),
+            ...(props.gitUserName ? { GIT_USER_NAME: props.gitUserName } : {}),
+            ...(props.gitUserEmail ? { GIT_USER_EMAIL: props.gitUserEmail } : {}),
+        };
+        // ...and the hooks configuration every shape's image is built with.
+        const imageHooks = {
+            port: props.hooksPort,
+            lifecycleTimeout: cdk.Duration.seconds(props.hookTimeoutSeconds),
+            buildTimeout: cdk.Duration.seconds(IMAGE_HOOK_TIMEOUT_SECONDS),
+        };
+        // Built first and with no `executionRole` prop, exactly as before this
+        // shape catalogue existed: same construct id (`Image`, frozen on the
+        // shape record — see shapes.ts), same `imageName`, same description. The
+        // construct therefore creates `Image/ExecutionRole` at its current path
+        // and current logical id — zero CloudFormation churn on the live,
+        // hand-deployed stack (D3/D9). Every additional shape below borrows this
+        // role rather than getting one of its own, which is why `validateShapes`
+        // requires the default shape to be `shapes[0]`: it must exist before any
+        // other shape can reference its execution role.
+        const defaultImage = new lambda_microvm_cdk_1.MicrovmImage(this, defaultShape.constructId, {
+            imageName: defaultShape.imageName,
+            description: defaultShape.description,
+            // A local directory, so the zip is uploaded by `cdk deploy` itself and the
+            // image ARN is a stack reference rather than a deploy-time input.
+            source: props.imageSource,
+            baseImageArn: props.baseImageArn,
+            baseImageVersion: props.baseImageVersion,
+            memoryMiB: defaultShape.memoryMiB,
+            environment: imageEnvironment,
+            hooks: imageHooks,
+        });
+        // WART, accepted deliberately: every additional shape's image is built
+        // with `defaultImage.executionRole`, so this role's construct path
+        // (`Image/ExecutionRole`) reads as if it belongs to just the default
+        // shape's image, when in fact it is shared by every shape. That is
+        // intentional — see D3 in the plan. Do NOT "fix" this with
+        // `overrideLogicalId`: renaming the logical id IS the CloudFormation
+        // churn this design exists to avoid (a delete-and-recreate of the role a
+        // running MicroVM has live session credentials from). The wart is one
+        // comment; the override would undo the point of D3.
+        const images = new Map([[defaultShape.name, defaultImage]]);
+        for (const shape of additionalShapes) {
+            images.set(shape.name, new lambda_microvm_cdk_1.MicrovmImage(this, shape.constructId, {
+                imageName: shape.imageName,
+                description: shape.description,
+                source: props.imageSource,
+                baseImageArn: props.baseImageArn,
+                baseImageVersion: props.baseImageVersion,
+                memoryMiB: shape.memoryMiB,
+                executionRole: defaultImage.executionRole,
+                environment: imageEnvironment,
+                hooks: imageHooks,
+            }));
+        }
+        // Bucket-wide rather than per-prefix (as the ECS runner's task role is):
+        // the prefix arrives at /run, so it cannot be named at synth, and one
+        // execution role is shared by every VM of every shape (D3). So a VM can
+        // read another session's credential store — acceptable within a single
+        // customer account, and what Phase 4 (#263) has to tighten when this goes
+        // multi-tenant.
+        durableState.grantReadWrite(defaultImage.executionRole);
+        // The image receives only an ARN; `/run` reads the secret value at runtime.
+        props.runnerSecret?.grantRead(defaultImage.executionRole);
+        // The shape catalogue the controller resolves a doorbell's `shape` field
+        // against, and advertises over the describe channel (#723). One JSON
+        // array, built with `Stack.toJsonString` — not `JSON.stringify` — because
+        // each `image_arn` is an unresolved `Fn::GetAtt` token at synth time, and
+        // `toJsonString` is the API that resolves tokens embedded in a JSON
+        // string (it emits an `Fn::Join`). `Stack.of(this)`, not `this`, because
+        // this class is a `Construct`, not a `Stack` — `toJsonString` is Stack-only.
+        const shapeCatalogueJson = cdk.Stack.of(this).toJsonString(shapes.map((shape) => ({
+            name: shape.name,
+            title: shape.title,
+            description: shape.description,
+            memory_mib: shape.memoryMiB,
+            image_arn: images.get(shape.name).imageArn,
+            is_default: shape.isDefault,
+        })));
+        const controller = new lambda.Function(this, 'Controller', {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            // Pre-bundled at PACKAGE build time (`pnpm --filter @evident-ai/runner-cdk
+            // build`, see scripts/build.ts), not at synth time — see the waker's
+            // `construct.ts` for why (`NodejsFunction` can't ship in a published
+            // construct: its entry file isn't in the tarball, and bundling would
+            // need esbuild on the consumer's synth machine). Resolved from the
+            // PACKAGE ROOT, two directories below `__dirname` here either compiled
+            // (`dist/microvm`) or via ts-node (`src/microvm`) — same as the waker.
+            code: lambda.Code.fromAsset(path.join(__dirname, '..', '..', 'dist', 'controller-lambda')),
+            handler: 'handler.handler',
+            // 128 MB is a slow cold start for a bundled SDK client on a path with a
+            // hard client deadline.
+            memorySize: 256,
+            // Deliberately BELOW Evident's WEBHOOK_DELIVERY_TIMEOUT_MS (10 s): the
+            // SUSPENDING poll can take ~2 s, and the 409 it produces is only useful if
+            // it reaches Evident before the client aborts. Do not "align" this to 10 s.
+            timeout: cdk.Duration.seconds(8),
+            environment: {
+                // The ARN and field name, never the value: the controller reads it from
+                // 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,
+                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.
+                MICROVM_EXECUTION_ROLE_ARN: defaultImage.executionRole.roleArn,
+            },
+        });
+        // The four control actions are granted on '*', the PassNetworkConnector
+        // resource is a partition/region wildcard, and PassRole names the
+        // execution role every shape now shares (D3) — so nothing in this grant
+        // is image-specific (V4), and one call on the default shape's image
+        // authorises the controller for every shape's MicroVM. N calls would
+        // emit N near-identical policy statements and break the "exactly one
+        // statement granting X" guarantees this construct's test encodes.
+        defaultImage.grantRun(controller);
+        props.doorbellSecret.grantRead(controller);
+        const functionUrl = controller.addFunctionUrl({
+            // HMAC verification of the doorbell body IS the auth, as for the ECS waker.
+            authType: lambda.FunctionUrlAuthType.NONE,
+        });
+        this.functionUrl = functionUrl.url;
+        this.shapeCatalogueJson = shapeCatalogueJson;
+        this.durableStateBucket = durableState;
+    }
+}
+exports.EvidentMicrovmConstruct = EvidentMicrovmConstruct;

package/dist/microvm/controller/doorbell.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The doorbell Evident POSTs to the controller's Function URL. `run_payload` is
+ * OPAQUE: it carries the runner key and whatever else the MicroVM's `/run` hook
+ * needs, and the controller only ever re-serialises it into `runHookPayload`. It
+ * is never parsed, never logged and never echoed — that is what makes the
+ * controller credential-free.
+ *
+ * `occurred_at` is required because it is the per-event half of the `RunMicrovm`
+ * `clientToken` (see `clientTokenFor`): a token derived from `runner_id` alone
+ * would be stable for the runner's whole life, so a post-termination wake would
+ * replay the dead VM's cached response and start nothing.
+ *
+ * A third arm, `runner.shapes_requested`, is a describe request rather than an
+ * event: it has no runner and no event instant, so it is parsed BEFORE the
+ * `runner_id`/`occurred_at` guards below. Its staleness is zero by construction
+ * — the response renders from the same deploy-time environment variable
+ * CloudFormation writes when it builds the images, so there is no second source
+ * to drift from. Replay is deliberately undefended: it is a pure read with no
+ * side effect, and its response carries only deploy-time metadata (shape names,
+ * titles, descriptions, memory) that is already public to the operator, so a
+ * replayed request yields nothing to gain. It is not defenceless — no response
+ * is produced without a valid HMAC over the exact body. ⚠️ Any future
+ * STATE-CHANGING request type added to this channel needs real replay defence
+ * (a timestamp window or a nonce); this reasoning does not extend to one.
+ */
+declare const WAKE_EVENT_TYPES: readonly ["agent.message_queued", "agent.wake_requested"];
+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 = {
+    runnerId: string;
+    occurredAt: string;
+    microvmId?: string;
+};
+export type WakeDoorbell = DoorbellFields & {
+    type: WakeEventType;
+    runHookPayload: string;
+    /**
+     * The shape a doorbell asks for, by name. `undefined` means "the default
+     * shape" — the controller resolves it against the shape catalogue.
+     */
+    shape?: string;
+};
+export type Doorbell = WakeDoorbell | (DoorbellFields & {
+    type: typeof SUSPEND_EVENT_TYPE;
+}) | {
+    type: typeof SHAPES_EVENT_TYPE;
+};
+/**
+ * Rejection reasons. Every one is a fixed constant: it goes into both the
+ * response body (which Evident persists) and the log line, so it must never
+ * contain anything derived from the request.
+ */
+export declare const DOORBELL_REJECTION: {
+    readonly invalidJson: "invalid_json";
+    readonly missingRunnerId: "missing_runner_id";
+    readonly missingOccurredAt: "missing_occurred_at";
+    readonly unsupportedType: "unsupported_event_type";
+    readonly invalidMicrovmId: "invalid_microvm_id";
+    readonly invalidShape: "invalid_shape";
+    readonly missingRunPayload: "missing_run_payload";
+    readonly runPayloadTooLarge: "run_payload_too_large";
+};
+export type DoorbellRejection = (typeof DOORBELL_REJECTION)[keyof typeof DOORBELL_REJECTION];
+export type ParsedDoorbell = {
+    ok: true;
+    doorbell: Doorbell;
+} | {
+    ok: false;
+    reason: DoorbellRejection;
+};
+export declare function parseDoorbell(rawBody: string): ParsedDoorbell;
+export {};

package/dist/microvm/controller/doorbell.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOORBELL_REJECTION = exports.SHAPES_EVENT_TYPE = void 0;
+exports.parseDoorbell = parseDoorbell;
+const constants_1 = require("../constants");
+/**
+ * The doorbell Evident POSTs to the controller's Function URL. `run_payload` is
+ * OPAQUE: it carries the runner key and whatever else the MicroVM's `/run` hook
+ * needs, and the controller only ever re-serialises it into `runHookPayload`. It
+ * is never parsed, never logged and never echoed — that is what makes the
+ * controller credential-free.
+ *
+ * `occurred_at` is required because it is the per-event half of the `RunMicrovm`
+ * `clientToken` (see `clientTokenFor`): a token derived from `runner_id` alone
+ * would be stable for the runner's whole life, so a post-termination wake would
+ * replay the dead VM's cached response and start nothing.
+ *
+ * A third arm, `runner.shapes_requested`, is a describe request rather than an
+ * event: it has no runner and no event instant, so it is parsed BEFORE the
+ * `runner_id`/`occurred_at` guards below. Its staleness is zero by construction
+ * — the response renders from the same deploy-time environment variable
+ * CloudFormation writes when it builds the images, so there is no second source
+ * to drift from. Replay is deliberately undefended: it is a pure read with no
+ * side effect, and its response carries only deploy-time metadata (shape names,
+ * titles, descriptions, memory) that is already public to the operator, so a
+ * replayed request yields nothing to gain. It is not defenceless — no response
+ * is produced without a valid HMAC over the exact body. ⚠️ Any future
+ * STATE-CHANGING request type added to this channel needs real replay defence
+ * (a timestamp window or a nonce); this reasoning does not extend to one.
+ */
+const WAKE_EVENT_TYPES = ['agent.message_queued', 'agent.wake_requested'];
+const SUSPEND_EVENT_TYPE = 'runner.suspend_requested';
+exports.SHAPES_EVENT_TYPE = 'runner.shapes_requested';
+/**
+ * Rejection reasons. Every one is a fixed constant: it goes into both the
+ * response body (which Evident persists) and the log line, so it must never
+ * contain anything derived from the request.
+ */
+exports.DOORBELL_REJECTION = {
+    invalidJson: 'invalid_json',
+    missingRunnerId: 'missing_runner_id',
+    missingOccurredAt: 'missing_occurred_at',
+    unsupportedType: 'unsupported_event_type',
+    invalidMicrovmId: 'invalid_microvm_id',
+    invalidShape: 'invalid_shape',
+    missingRunPayload: 'missing_run_payload',
+    runPayloadTooLarge: 'run_payload_too_large',
+};
+function nonBlankString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isWakeType(value) {
+    return WAKE_EVENT_TYPES.includes(value);
+}
+function parseDoorbell(rawBody) {
+    let body;
+    try {
+        body = JSON.parse(rawBody);
+    }
+    catch {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.invalidJson };
+    }
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.invalidJson };
+    }
+    const { type, runner_id: runnerId, occurred_at: occurredAt, microvm_id: microvmId, run_payload: runPayload, shape, } = body;
+    if (type !== SUSPEND_EVENT_TYPE && type !== exports.SHAPES_EVENT_TYPE && !isWakeType(type)) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.unsupportedType };
+    }
+    // A describe request has no runner and no event instant — resolve it here,
+    // before the runner_id/occurred_at guards below, or it could never satisfy them.
+    if (type === exports.SHAPES_EVENT_TYPE) {
+        return { ok: true, doorbell: { type } };
+    }
+    if (!nonBlankString(runnerId)) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.missingRunnerId };
+    }
+    if (!nonBlankString(occurredAt)) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.missingOccurredAt };
+    }
+    if (microvmId !== undefined && !nonBlankString(microvmId)) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.invalidMicrovmId };
+    }
+    const fields = { runnerId, occurredAt, microvmId };
+    if (type === SUSPEND_EVENT_TYPE) {
+        return { ok: true, doorbell: { ...fields, type } };
+    }
+    if (shape !== undefined && !nonBlankString(shape)) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.invalidShape };
+    }
+    if (runPayload === undefined || runPayload === null) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.missingRunPayload };
+    }
+    const runHookPayload = JSON.stringify(runPayload);
+    if (Buffer.byteLength(runHookPayload, 'utf8') > constants_1.RUN_HOOK_PAYLOAD_MAX_BYTES) {
+        return { ok: false, reason: exports.DOORBELL_REJECTION.runPayloadTooLarge };
+    }
+    // Omit `shape` entirely when absent, rather than setting it to `undefined`,
+    // so a body with no shape parses to exactly the same object as before this
+    // field existed.
+    return {
+        ok: true,
+        doorbell: shape === undefined
+            ? { ...fields, type, runHookPayload }
+            : { ...fields, type, shape, runHookPayload },
+    };
+}

package/dist/microvm/controller/handle-doorbell.d.ts

@@ -0,0 +1,27 @@
+import type { MicrovmClient } from './microvm-client';
+import type { ShapeCatalogue } from './shape-catalogue';
+import { type Timing } from './throttle-retry';
+/**
+ * The controller's pure decision core: verify the HMAC over the raw body, parse
+ * the doorbell, then map the MicroVM's current state to exactly one lifecycle
+ * call. Everything with I/O is injected, so the whole tree is unit-testable.
+ *
+ * The response body NEVER contains anything derived from `run_payload` — Evident
+ * persists it as `response_body`.
+ */
+type ActionKind = 'none' | 'run' | 'resume' | 'suspend' | 'rejected' | 'describe';
+export type DoorbellResult = {
+    statusCode: number;
+    body: string;
+    action: {
+        kind: ActionKind;
+    };
+};
+export declare function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes, microvm, sleep, random, }: {
+    rawBody: string;
+    signatureHeader: string | undefined;
+    doorbellSecret: string;
+    shapes: ShapeCatalogue;
+    microvm: MicrovmClient;
+} & Timing): Promise<DoorbellResult>;
+export {};