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

package/dist/microvm/construct.js

@@ -0,0 +1,283 @@
+"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");
+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
+ * 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;
+        // D8's "both required together" is a synth-time contract, not just a
+        // README sentence: a caller supplying exactly one silently gets NO
+        // reporter and no warning (the `&&` check below just skips it), which
+        // reads as "configured" when it is not. Fail loudly instead.
+        if (Boolean(props.evidentApiUrl) !== Boolean(props.evidentRunnerId)) {
+            throw new Error('EvidentMicrovmConstruct: evidentApiUrl and evidentRunnerId must be supplied ' +
+                'together or not at all — supplying only one silently disables the image ' +
+                'version reporter rather than reporting a misconfiguration.');
+        }
+        // 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,
+        });
+        // Opt-in only (D8): both values present is what creates the reporter, so an
+        // adopter who supplies neither gets a template with no additional Lambda and
+        // no custom resource — this branch must not run for them.
+        if (props.evidentApiUrl && props.evidentRunnerId) {
+            new construct_1.ImageVersionReporter(this, 'ImageVersionReporter', {
+                doorbellSecret: props.doorbellSecret,
+                evidentApiUrl: props.evidentApiUrl,
+                evidentRunnerId: props.evidentRunnerId,
+                imageVersions: Object.fromEntries(shapes.map((shape) => [shape.name, images.get(shape.name).latestActiveImageVersion])),
+                // `buildInputs` already covers every property that can cause AWS
+                // to publish a new version for THIS shape's image (source, base
+                // image, memory, hooks, environment, description, build role —
+                // see its docstring); no additional encoding needed here.
+                buildTriggers: Object.fromEntries(shapes.map((shape) => [shape.name, images.get(shape.name).buildInputs])),
+            });
+        }
+        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 {};