@evident-ai/runner-cdk 0.1.0 → 0.1.1-dev.d96ef8a

package/dist/microvm/controller/shape-catalogue.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Parses the `MICROVM_SHAPES` environment variable (a JSON array, written by
+ * CloudFormation from `infrastructure/evident-microvm/src/shapes.ts` at
+ * deploy time — see D6/D7 in the plan) into a `ShapeCatalogue` the pure
+ * decision core can query, without that core ever touching `process.env`
+ * itself.
+ *
+ * A malformed catalogue means a broken deploy: `parseShapeCatalogue` throws
+ * once, loudly, at cold start rather than handing back a half-parsed
+ * catalogue that degrades per-request.
+ *
+ * `resolve()` never falls back to the default shape for a *named* request —
+ * only the absence of a name (`undefined`) means "give me the default". An
+ * unrecognised name returns `undefined` so the caller can reject loudly
+ * (AC-4) instead of silently launching the default shape a doorbell did not
+ * ask for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseShapeCatalogue = parseShapeCatalogue;
+function nonBlankString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function parseShapeEntry(entry, index) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        throw new Error(`MICROVM_SHAPES[${index}] is not an object.`);
+    }
+    const { name, title, description, memory_mib: memoryMiB, image_arn: imageArn, is_default: isDefault, } = entry;
+    if (!nonBlankString(name)) {
+        throw new Error(`MICROVM_SHAPES[${index}] is missing a non-blank "name".`);
+    }
+    if (!nonBlankString(title)) {
+        throw new Error(`Shape "${name}" is missing a non-blank "title".`);
+    }
+    if (!nonBlankString(description)) {
+        throw new Error(`Shape "${name}" is missing a non-blank "description".`);
+    }
+    if (typeof memoryMiB !== 'number' || !Number.isFinite(memoryMiB)) {
+        throw new Error(`Shape "${name}" has a non-number "memory_mib".`);
+    }
+    if (!nonBlankString(imageArn)) {
+        throw new Error(`Shape "${name}" is missing a non-blank "image_arn".`);
+    }
+    if (typeof isDefault !== 'boolean') {
+        throw new Error(`Shape "${name}" has a non-boolean "is_default".`);
+    }
+    return { name, title, description, memoryMiB, imageArn, isDefault };
+}
+/**
+ * Parses and validates the `MICROVM_SHAPES` catalogue. Mirrors
+ * `validateShapes`'s (`src/shapes.ts`) message vocabulary so an operator
+ * reading a controller cold-start failure recognises it as the same rule
+ * they already met at synth time.
+ *
+ * Throws on: invalid JSON, a non-array, an empty array, an entry missing a
+ * non-blank `name`/`title`/`description`/`image_arn`, a non-number
+ * `memory_mib`, a non-boolean `is_default`, a duplicate `name`, or
+ * zero/multiple `is_default: true` entries.
+ */
+function parseShapeCatalogue(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('MICROVM_SHAPES is not valid JSON.');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('MICROVM_SHAPES must be a JSON array.');
+    }
+    if (parsed.length === 0) {
+        throw new Error('MICROVM_SHAPES must not be empty.');
+    }
+    const shapes = parsed.map((entry, index) => parseShapeEntry(entry, index));
+    const seenNames = new Set();
+    for (const shape of shapes) {
+        if (seenNames.has(shape.name)) {
+            throw new Error(`Duplicate MicroVM shape name "${shape.name}" in MICROVM_SHAPES — shape names must be unique.`);
+        }
+        seenNames.add(shape.name);
+    }
+    const defaults = shapes.filter((shape) => shape.isDefault);
+    if (defaults.length === 0) {
+        throw new Error('MICROVM_SHAPES must mark exactly one shape is_default: true — none does.');
+    }
+    if (defaults.length > 1) {
+        throw new Error('MICROVM_SHAPES must mark exactly one shape is_default: true — ' +
+            `found ${defaults.length}: ${defaults.map((shape) => shape.name).join(', ')}.`);
+    }
+    const defaultShape = defaults[0];
+    return {
+        resolve(name) {
+            if (name === undefined) {
+                return defaultShape;
+            }
+            return shapes.find((shape) => shape.name === name);
+        },
+        advertise() {
+            return shapes.map((shape) => ({
+                name: shape.name,
+                title: shape.title,
+                description: shape.description,
+                memory_mib: shape.memoryMiB,
+                is_default: shape.isDefault,
+            }));
+        },
+    };
+}

package/dist/microvm/controller/throttle-retry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Retry for the mutating MicroVM operations. `RunMicrovm`/`ResumeMicrovm` are 5/s
+ * and `SuspendMicrovm` is 2/s burst 2, so a doorbell burst throttles in normal
+ * operation. Full jitter over `[300, 900] ms` — worst case 1.2 s, which has to
+ * coexist with the `SUSPENDING` poll (≤ 2 s) inside the Lambda's 8 s timeout.
+ */
+export type Timing = {
+    sleep: (ms: number) => Promise<void>;
+    random: () => number;
+};
+export declare function withThrottleRetry<T>(operation: () => Promise<T>, { sleep, random }: Timing): Promise<T>;

package/dist/microvm/controller/throttle-retry.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Retry for the mutating MicroVM operations. `RunMicrovm`/`ResumeMicrovm` are 5/s
+ * and `SuspendMicrovm` is 2/s burst 2, so a doorbell burst throttles in normal
+ * operation. Full jitter over `[300, 900] ms` — worst case 1.2 s, which has to
+ * coexist with the `SUSPENDING` poll (≤ 2 s) inside the Lambda's 8 s timeout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withThrottleRetry = withThrottleRetry;
+const BACKOFF_MS = [300, 900];
+function isThrottling(error) {
+    const name = error?.name;
+    return name === 'ThrottlingException' || name === 'TooManyRequestsException';
+}
+async function withThrottleRetry(operation, { sleep, random }) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (attempt >= BACKOFF_MS.length || !isThrottling(error)) {
+                throw error;
+            }
+            await sleep(Math.floor(random() * BACKOFF_MS[attempt]));
+        }
+    }
+}

package/dist/microvm/shapes.d.ts

@@ -0,0 +1,72 @@
+import { type MicrovmMemoryMiB } from '@evident-ai/lambda-microvm-cdk';
+/**
+ * An operator-authored MicroVM shape: a named memory footprint the controller
+ * can launch a session on. A shape's size is fixed on its image (#723) —
+ * there is no launch-time resource dial — so "a bigger machine" means "a
+ * different shape", each backed by its own `MicrovmImage`.
+ *
+ * `constructId` and `imageName` are carried **explicitly** rather than
+ * derived from `name`, because for the default shape they are frozen
+ * deployment identity (see the comment on `MICROVM_SHAPES` below): deriving
+ * them would let an innocent rename of `name` silently rebuild the live
+ * image. Every other shape is free to name these however is convenient.
+ */
+export interface MicrovmShape {
+    /** The stable id a doorbell asks for; crosses the wire to Evident. */
+    readonly name: string;
+    /** Operator-authored, for Evident's future shape picker. */
+    readonly title: string;
+    /**
+     * Operator-authored; also becomes the image's CloudFormation
+     * `Description`.
+     */
+    readonly description: string;
+    readonly memoryMiB: MicrovmMemoryMiB;
+    /**
+     * Exactly one shape must set this, and — see the ordering contract below —
+     * it must be the first entry in `MICROVM_SHAPES`.
+     */
+    readonly isDefault: boolean;
+    /** The `MicrovmImage` construct id within the stack. */
+    readonly constructId: string;
+    /** The account-unique `imageName` passed to `MicrovmImage`. */
+    readonly imageName: string;
+}
+/**
+ * The committed shape list. Ordering contract (load-bearing, not cosmetic):
+ * the list is ordered, the default shape MUST be the first entry, and the
+ * stack constructs shapes in list order. That is because every non-default
+ * shape's image is built with the default shape's own execution role (D3 in
+ * the plan) — so the default has to exist before any other shape can borrow
+ * its role. Reordering this list to put the default anywhere but index 0 is
+ * a synth-time error (`validateShapes`), not a cosmetic change. The same
+ * order is what `advertise()` (controller-side) hands Evident's future
+ * picker, so default-first is also the picker's ordering — a small price for
+ * making the construction-order contract enforceable rather than a
+ * convention.
+ *
+ * The default entry's `constructId` ("Image") and `imageName`
+ * ("evident-microvm") are FROZEN: they are today's live, hand-deployed
+ * image's identity. Changing either destroys and rebuilds it (~4m45s,
+ * measured) plus a window with no image. Its `description` is copied
+ * verbatim from the image that is live today so the deploy changes nothing
+ * about it.
+ *
+ * "Frozen" means unchanged under OUR OWN synth (no `microvm:*` context set —
+ * `main.ts` passes none). `imageName` MAY carry a customer's
+ * `microvm:namePrefix` (`deployment.ts`'s `resolveShapeCatalogue`) — that is
+ * account-scoped naming, not a change to this module. `constructId` stays
+ * frozen unconditionally, with no override anywhere: it is the
+ * CloudFormation logical-id path, and prefixing it is the resource
+ * replacement this whole file's FROZEN warning exists to prevent.
+ */
+export declare const MICROVM_SHAPES: readonly MicrovmShape[];
+/**
+ * Validates a shape list at synth time. Deliberately lean
+ * (`code-simplicity.mdc`): this is a hand-edited constant list in a typed
+ * file, so it only checks what `tsc` cannot already catch — CDK itself
+ * rejects a duplicate `constructId`, so that one needs no check here, and no
+ * byte-budget cap is applied (the image ARNs are unresolved tokens at synth,
+ * so a rendered size is not measurable anyway).
+ */
+export declare function validateShapes(shapes: readonly MicrovmShape[]): readonly MicrovmShape[];

package/dist/microvm/shapes.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MICROVM_SHAPES = void 0;
+exports.validateShapes = validateShapes;
+const lambda_microvm_cdk_1 = require("@evident-ai/lambda-microvm-cdk");
+/**
+ * The committed shape list. Ordering contract (load-bearing, not cosmetic):
+ * the list is ordered, the default shape MUST be the first entry, and the
+ * stack constructs shapes in list order. That is because every non-default
+ * shape's image is built with the default shape's own execution role (D3 in
+ * the plan) — so the default has to exist before any other shape can borrow
+ * its role. Reordering this list to put the default anywhere but index 0 is
+ * a synth-time error (`validateShapes`), not a cosmetic change. The same
+ * order is what `advertise()` (controller-side) hands Evident's future
+ * picker, so default-first is also the picker's ordering — a small price for
+ * making the construction-order contract enforceable rather than a
+ * convention.
+ *
+ * The default entry's `constructId` ("Image") and `imageName`
+ * ("evident-microvm") are FROZEN: they are today's live, hand-deployed
+ * image's identity. Changing either destroys and rebuilds it (~4m45s,
+ * measured) plus a window with no image. Its `description` is copied
+ * verbatim from the image that is live today so the deploy changes nothing
+ * about it.
+ *
+ * "Frozen" means unchanged under OUR OWN synth (no `microvm:*` context set —
+ * `main.ts` passes none). `imageName` MAY carry a customer's
+ * `microvm:namePrefix` (`deployment.ts`'s `resolveShapeCatalogue`) — that is
+ * account-scoped naming, not a change to this module. `constructId` stays
+ * frozen unconditionally, with no override anywhere: it is the
+ * CloudFormation logical-id path, and prefixing it is the resource
+ * replacement this whole file's FROZEN warning exists to prevent.
+ */
+exports.MICROVM_SHAPES = [
+    {
+        name: 'standard',
+        title: 'Standard',
+        description: 'Evident per-session runner: an arm64 image that boots with no identity and acquires one at /run.',
+        memoryMiB: 4096,
+        isDefault: true,
+        // FROZEN — see the file-level comment. Do not rename either string.
+        constructId: 'Image',
+        imageName: 'evident-microvm',
+    },
+];
+/**
+ * Validates a shape list at synth time. Deliberately lean
+ * (`code-simplicity.mdc`): this is a hand-edited constant list in a typed
+ * file, so it only checks what `tsc` cannot already catch — CDK itself
+ * rejects a duplicate `constructId`, so that one needs no check here, and no
+ * byte-budget cap is applied (the image ARNs are unresolved tokens at synth,
+ * so a rendered size is not measurable anyway).
+ */
+function validateShapes(shapes) {
+    if (shapes.length === 0) {
+        throw new Error('MICROVM_SHAPES must not be empty.');
+    }
+    const seenNames = new Set();
+    for (const shape of shapes) {
+        if (seenNames.has(shape.name)) {
+            throw new Error(`Duplicate MicroVM shape name "${shape.name}" — shape names must be unique.`);
+        }
+        seenNames.add(shape.name);
+    }
+    const seenImageNames = new Set();
+    for (const shape of shapes) {
+        if (seenImageNames.has(shape.imageName)) {
+            throw new Error(`Duplicate MicroVM image name "${shape.imageName}" (shape "${shape.name}") — ` +
+                'AWS rejects this only at deploy, minutes in, so it is checked here instead.');
+        }
+        seenImageNames.add(shape.imageName);
+    }
+    const defaults = shapes.filter((shape) => shape.isDefault);
+    if (defaults.length === 0) {
+        throw new Error('MICROVM_SHAPES must mark exactly one shape isDefault: true — none does.');
+    }
+    if (defaults.length > 1) {
+        throw new Error('MICROVM_SHAPES must mark exactly one shape isDefault: true — ' +
+            `found ${defaults.length}: ${defaults.map((shape) => shape.name).join(', ')}.`);
+    }
+    if (shapes[0] !== defaults[0]) {
+        throw new Error(`The default shape ("${defaults[0].name}") must be the first entry in MICROVM_SHAPES, ` +
+            `not index ${shapes.indexOf(defaults[0])}. Every non-default shape's image is built ` +
+            "with the default shape's own execution role, so the default has to be constructed first.");
+    }
+    for (const shape of shapes) {
+        if (!lambda_microvm_cdk_1.MICROVM_MEMORY_TIERS_MIB.includes(shape.memoryMiB)) {
+            throw new Error(`Shape "${shape.name}" has memoryMiB ${shape.memoryMiB}, which is not one of the ` +
+                `MicroVM memory tiers (${lambda_microvm_cdk_1.MICROVM_MEMORY_TIERS_MIB.join(', ')} MiB).`);
+        }
+    }
+    return shapes;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "0.1.0",
-  "description": "Reusable CDK construct for a single scale-to-zero Evident agent runner on Fargate (task + service + per-agent self-stop role + waker Lambda). Instantiate once per agent from your own stack.",
+  "version": "0.1.1-dev.d96ef8a",
+  "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",
   "exports": {
@@ -21,12 +21,15 @@
     "lint": "eslint 'src/**/*.ts' --max-warnings=0"
   },
   "peerDependencies": {
+    "@evident-ai/lambda-microvm-cdk": "^0.1.1",
     "aws-cdk-lib": "^2.240.0",
     "constructs": "^10.5.0"
   },
   "devDependencies": {
     "@aws-sdk/client-ecs": "^3.682.0",
+    "@aws-sdk/client-lambda-microvms": "^3.1095.0",
     "@aws-sdk/client-secrets-manager": "^3.682.0",
+    "@evident-ai/lambda-microvm-cdk": "^0.1.1",
     "@evident/webhook-signature": "workspace:*",
     "@types/node": "^22",
     "aws-cdk-lib": "^2.240.0",