@evident-ai/runner-cdk 3.4.1-dev.c463782 → 3.4.1-dev.d0469f4

package/README.md

@@ -11,7 +11,7 @@ Reusable AWS CDK constructs for running an [Evident](https://evident.run) agent
 - **`EvidentMicrovmConstruct`** — a per-session AWS Lambda MicroVM that boots on demand
   and suspends between messages. Installing the `@dev` tag of this package is all you
   need: the image build context ships inside it (see [The MicroVM image](#the-microvm-image)
-  below), so there is no checkout of `sroze/evident` involved. See
+  below), so there is no checkout of the source repository involved. See
   [the AWS runner doc](https://evident.run/docs/aws-runner) for the full picture of both
   strategies.
 
@@ -76,8 +76,8 @@ agent.selfStopRoleArn;
 agent.replicaPrefix;
 ```
 
-For a complete working example, see `infrastructure/evident-runner/` in this repo — it is
-the construct's own dogfooding consumer.
+For a complete working example, see [`GETTING-STARTED.md`](./GETTING-STARTED.md) in this
+package — it is the construct's own dogfooding consumer.
 
 ## Props
 
@@ -121,10 +121,11 @@ context, which `cdk deploy` zips and uploads. The Lambda MicroVM service then bu
 image in *your* account, from a base image ARN you discover there — so, unlike the Fargate
 strategy, there is no registry image to pull.
 
-The context has two halves, and this package ships the half that is ours: the Dockerfile,
-the per-phase hook scripts and the bundled hook server, published inside the tarball at
-`dist/microvm-image-context/`. The other half is **your** repository, which is baked in as
-the agent's workspace. `stageMicrovmImageContext()` puts the two together:
+The context has three parts: this package supplies the Dockerfile, the per-phase hook
+scripts and the bundled hook server, published inside the tarball at
+`dist/microvm-image-context/`; **your** repository is baked in as the agent's workspace;
+and an optional overlay supplies deployment-specific build steps. `stageMicrovmImageContext()`
+puts them together:
 
 ```ts
 import path from 'node:path';
@@ -143,6 +144,8 @@ new EvidentMicrovmConstruct(this, 'Runner', {
     // token the agent pushes with arrives per-session, never baked in.
     originUrl: 'https://github.com/acme/widgets.git',
     destination: path.join(__dirname, '..', 'build', 'image'),
+    // Optional deployment-specific installs and build warm-up.
+    overlayDir: '/path/to/microvm-overlay',
   }),
   // Must match the published image these were baked into, so export them
   // rather than restating the numbers.
@@ -156,15 +159,27 @@ new EvidentMicrovmConstruct(this, 'Runner', {
 });
 ```
 
-Your repo does not have to be a pnpm workspace. If it commits a `pnpm-lock.yaml` the image
-pre-installs dependencies at build time (a faster first boot); if not, that step is skipped
-and the agent installs on first use.
+Pass `overlayDir` to add deployment-specific build steps to the staged image. The
+directory provides `setup-root` for root-owned installs and `setup-workspace` for
+dependency installation and workspace build warm-up. See the [MicroVM image
+README](../../runner/docker-images/microvm/README.md) for the full overlay contract.
+
+The image bakes your repository checked out but not installed and makes no assumptions about
+its package manager. To speed up first boot, install dependencies from your overlay's
+`setup-workspace`; otherwise, the agent installs them on first use.
 
 | MicroVM prop | Omitted behavior |
 | --- | --- |
 | `runnerSecret` | No GitHub or MCP credentials are exported at `/run`. When supplied, `/run` reads the JSON secret and exports every non-empty value whose key is a valid environment-variable name. |
 | `runnerOpencodeConfigPath` | OpenCode uses the baked project configuration. Relative paths resolve from the workspace; absolute paths resolve in the image. |
+| `extraImageEnvironment` | Non-secret values baked into every VM launched from this image version; every VM can read them, so never put secrets here. |
 | `gitUserName` / `gitUserEmail` | The hook uses the Evident bot defaults for git identity. |
+| `evidentApiUrl` / `evidentRunnerId` | No deploy-time report of the published image version — a byte-identical template to not having these props at all. Both non-secret (a URL, a public pool UUID) and both required together: set them if you have an Evident runner id configured for this provisioner, so each deploy that publishes a new image version tells Evident about it (a CloudFormation custom resource, HMAC-signed with `doorbellSecret`). A failure to report never fails your deploy — it warns and Evident reads that provisioner as *unknown*, never as up to date or stale. |
+
+`extraImageEnvironment` is the runtime counterpart to an overlay. Use it when an
+overlay-installed component needs an environment variable after the VM boots. The
+values are baked into every VM launched from that image version and are readable by
+all of them, so never put a secret in this prop.
 
 ## Status / limitations
 
@@ -172,7 +187,6 @@ and the agent installs on first use.
   `npm install @evident-ai/runner-cdk@dev` (or `pnpm add`/`yarn add`); no checkout of
   this repo is required. It builds to a self-contained `dist/` (`pnpm --filter
   @evident-ai/runner-cdk build`) with no `workspace:`/`@evident/*` runtime dependency.
-  This repo's own consumer (`infrastructure/evident-runner`) still consumes it as a
-  `workspace:*` dependency for dogfooding.
+  Evident's own consumer still consumes it as a `workspace:*` dependency for dogfooding.
 - **AWS/ECS-specific.** Non-AWS clouds are an open question on the epic, not a supported
   path.

package/dist/controller-lambda/handler.js

@@ -49854,7 +49854,8 @@ function parseDoorbell(rawBody) {
     occurred_at: occurredAt,
     microvm_id: microvmId,
     run_payload: runPayload,
-    shape
+    shape,
+    recreate_on_outdated_image: recreateOnOutdatedImage
   } = body;
   if (type !== SUSPEND_EVENT_TYPE && type !== SHAPES_EVENT_TYPE && !isWakeType(type)) {
     return { ok: false, reason: DOORBELL_REJECTION.unsupportedType };
@@ -49885,10 +49886,14 @@ function parseDoorbell(rawBody) {
   if (Buffer.byteLength(runHookPayload, "utf8") > RUN_HOOK_PAYLOAD_MAX_BYTES) {
     return { ok: false, reason: DOORBELL_REJECTION.runPayloadTooLarge };
   }
-  return {
-    ok: true,
-    doorbell: shape === void 0 ? { ...fields, type, runHookPayload } : { ...fields, type, shape, runHookPayload }
-  };
+  const doorbell = { ...fields, type, runHookPayload };
+  if (shape !== void 0) {
+    doorbell.shape = shape;
+  }
+  if (recreateOnOutdatedImage === true) {
+    doorbell.recreateOnOutdatedImage = true;
+  }
+  return { ok: true, doorbell };
 }
 
 // src/microvm/controller/throttle-retry.ts
@@ -50128,7 +50133,7 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         imageVersion: described.imageVersion
       });
     case "SUSPENDED":
-      if (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
+      if (doorbell.recreateOnOutdatedImage === true && await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
         return runMicrovm(
           doorbell,
           shape,

package/dist/evident-scale-to-zero-construct.d.ts

@@ -17,7 +17,7 @@ export type EvidentScaleToZeroConstructProps = {
      * (`agents/<id>`) and is the single expected `agent_id` the waker checks.
      */
     evidentAgentId: string;
-    /** GitHub `owner/repo` the agent clones and works on (e.g. `sroze/evident`). */
+    /** GitHub `owner/repo` the agent clones and works on (e.g. `my-org/my-repo`). */
     gitRepo: string;
     /** Branch to clone. Defaults to `main` when omitted. */
     gitBranch?: string;

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

@@ -168,9 +168,8 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             cluster,
             taskDefinition,
             serviceName,
-            // Starts at 1; the runner self-scales to 0 on idle. A deploy resets this to
-            // 1 (CFN), waking a sleeping agent that then re-naps (benign).
-            desiredCount: 1,
+            // Deliberately omit DesiredCount: CloudFormation leaves the existing service's
+            // self-stop/waker count alone; either 1 or 0 would re-assert it on every deploy.
             enableExecuteCommand: true,
             assignPublicIp: true,
             vpcSubnets: { subnetType: ec2.SubnetType.PUBLIC },

package/dist/image-version-reporter-lambda/handler.js

@@ -0,0 +1,129 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/microvm/image-version-reporter/handler.ts
+var handler_exports = {};
+__export(handler_exports, {
+  handleImageVersionReport: () => handleImageVersionReport,
+  handler: () => handler
+});
+module.exports = __toCommonJS(handler_exports);
+var import_node_crypto = require("node:crypto");
+var import_client_secrets_manager = require("@aws-sdk/client-secrets-manager");
+var PHYSICAL_RESOURCE_ID = "evident-image-version-report";
+var REPORT_TIMEOUT_MS = 5e3;
+var secrets = new import_client_secrets_manager.SecretsManagerClient({});
+async function fetchDoorbellSecret(secretArn, secretKey) {
+  const { SecretString } = await secrets.send(new import_client_secrets_manager.GetSecretValueCommand({ SecretId: secretArn }));
+  if (!SecretString) {
+    throw new Error(`doorbell secret ${secretArn} has no SecretString`);
+  }
+  const parsed = JSON.parse(SecretString);
+  const value = parsed !== null && typeof parsed === "object" ? parsed[secretKey] : void 0;
+  if (typeof value !== "string" || value === "") {
+    throw new Error(`doorbell secret ${secretArn} is missing a non-empty '${secretKey}' field`);
+  }
+  return value;
+}
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`missing required env var ${name}`);
+  }
+  return value;
+}
+function readImageVersions(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("imageVersions must be an object");
+  }
+  return Object.entries(value).map(([shape, imageVersion]) => {
+    if (typeof imageVersion !== "string") {
+      throw new Error(`imageVersions.${shape} must be a string`);
+    }
+    return { shape, image_version: imageVersion };
+  });
+}
+function response() {
+  return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
+}
+var runtimeDependencies = {
+  getSecret: fetchDoorbellSecret,
+  fetch: globalThis.fetch
+};
+async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
+  if (event.RequestType === "Delete") {
+    return response();
+  }
+  let runnerId = "unknown";
+  let versions = [];
+  let responseStatus;
+  try {
+    versions = readImageVersions(event.ResourceProperties?.imageVersions);
+    const config = getConfig();
+    runnerId = config.evidentRunnerId;
+    const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+    const body = JSON.stringify({
+      type: "runner.microvm_image_versions_reported",
+      versions
+    });
+    const signature = (0, import_node_crypto.createHmac)("sha256", secret).update(body).digest("hex");
+    const url = `${config.evidentApiUrl.replace(/\/+$/, "")}/v1/runners/${encodeURIComponent(
+      runnerId
+    )}/microvm-image-versions`;
+    const result = await dependencies.fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-evident-signature": signature
+      },
+      body,
+      signal: AbortSignal.timeout(REPORT_TIMEOUT_MS)
+    });
+    responseStatus = result.status;
+    console.log("runner.microvm_image_versions_reported", {
+      runnerId,
+      versions,
+      status: result.status
+    });
+    if (!result.ok) {
+      throw new Error(`Evident returned HTTP ${result.status}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn("MicroVM image version report failed", {
+      operation: event.RequestType,
+      runnerId,
+      versions,
+      ...responseStatus === void 0 ? {} : { status: responseStatus },
+      error: message
+    });
+  }
+  return response();
+}
+var handler = (event) => handleImageVersionReport(event, () => ({
+  doorbellSecretArn: requireEnv("DOORBELL_SECRET_ARN"),
+  doorbellSecretKey: requireEnv("DOORBELL_SECRET_KEY"),
+  evidentApiUrl: requireEnv("EVIDENT_API_URL"),
+  evidentRunnerId: requireEnv("EVIDENT_RUNNER_ID")
+}));
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handleImageVersionReport,
+  handler
+});

package/dist/microvm/construct.d.ts

@@ -55,6 +55,12 @@ export interface EvidentMicrovmConstructProps {
     readonly gitUserName?: string;
     /** Optional git email the `/run` hook configures for agent commits. */
     readonly gitUserEmail?: string;
+    /**
+     * Non-secret values baked into every VM launched from this image version,
+     * typically values a deployment's overlay needs at runtime. Every VM can
+     * read them, so this must never contain a secret.
+     */
+    readonly extraImageEnvironment?: Record<string, 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
@@ -69,6 +75,24 @@ export interface EvidentMicrovmConstructProps {
      * running a hook).
      */
     readonly hookTimeoutSeconds: number;
+    /**
+     * Base URL of Evident's own API. Together with `evidentRunnerId`, opts this
+     * deploy into reporting each shape's published image version to Evident
+     * (#1903) — a CDK custom resource, triggered only when a deploy actually
+     * changes a version. Omitting BOTH leaves the template byte-for-byte
+     * identical to not having this prop at all: an adopter with no Evident
+     * runner id configured has nothing to report against. Supplying only one
+     * throws at synth — see `evidentRunnerId`.
+     */
+    readonly evidentApiUrl?: string;
+    /**
+     * The pool runner id (public, non-secret UUID) to report against — see
+     * `evidentApiUrl`. Mirrors `EvidentScaleToZeroConstructProps.evidentAgentId`'s
+     * "public (non-secret) Evident agent UUID" precedent. Must be supplied
+     * together with `evidentApiUrl`, or neither at all — supplying exactly one
+     * throws at construction rather than silently disabling the reporter.
+     */
+    readonly evidentRunnerId?: string;
 }
 /**
  * The customer-account half of the per-session runner (#558): the MicroVM

package/dist/microvm/construct.js

@@ -41,6 +41,7 @@ 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;
@@ -65,6 +66,15 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
         // 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
@@ -131,6 +141,7 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
                 : {}),
             ...(props.gitUserName ? { GIT_USER_NAME: props.gitUserName } : {}),
             ...(props.gitUserEmail ? { GIT_USER_EMAIL: props.gitUserEmail } : {}),
+            ...props.extraImageEnvironment,
         };
         // ...and the hooks configuration every shape's image is built with.
         const imageHooks = {
@@ -249,6 +260,22 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
             // 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;

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

@@ -40,6 +40,11 @@ export type WakeDoorbell = DoorbellFields & {
      * shape" — the controller resolves it against the shape catalogue.
      */
     shape?: string;
+    /**
+     * Set only when the body carries the literal `true`. When absent, the
+     * suspended VM is always resumed because recreating it destroys its filesystem.
+     */
+    recreateOnOutdatedImage?: boolean;
 };
 export type Doorbell = WakeDoorbell | (DoorbellFields & {
     type: typeof SUSPEND_EVENT_TYPE;

package/dist/microvm/controller/doorbell.js

@@ -63,7 +63,7 @@ function parseDoorbell(rawBody) {
     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;
+    const { type, runner_id: runnerId, occurred_at: occurredAt, microvm_id: microvmId, run_payload: runPayload, shape, recreate_on_outdated_image: recreateOnOutdatedImage, } = body;
     if (type !== SUSPEND_EVENT_TYPE && type !== exports.SHAPES_EVENT_TYPE && !isWakeType(type)) {
         return { ok: false, reason: exports.DOORBELL_REJECTION.unsupportedType };
     }
@@ -95,13 +95,14 @@ function parseDoorbell(rawBody) {
     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 },
-    };
+    // Omit optional fields entirely when absent, rather than setting them to
+    // `undefined`, so older bodies keep the same parsed shape.
+    const doorbell = { ...fields, type, runHookPayload };
+    if (shape !== undefined) {
+        doorbell.shape = shape;
+    }
+    if (recreateOnOutdatedImage === true) {
+        doorbell.recreateOnOutdatedImage = true;
+    }
+    return { ok: true, doorbell };
 }

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

@@ -129,9 +129,8 @@ function compareImageVersions(a, b) {
     return 0;
 }
 /**
- * Whether the SUSPENDED VM must be thrown away and recreated because a newer
- * image has been published since it booted — a resume would otherwise keep
- * that VM on its old baked-in hooks and repo checkout for up to 8 hours.
+ * Whether an opted-in doorbell should throw away and recreate the SUSPENDED VM
+ * because a newer image has been published since it booted.
  *
  * FAIL-SAFE, one direction only: recreating destroys the VM's filesystem
  * (only the credentials and `opencode.db` in the object store survive), so
@@ -287,11 +286,12 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
                 imageVersion: described.imageVersion,
             });
         case 'SUSPENDED':
-            // A newer image has been published since this VM booted: resuming would
-            // keep it on the old baked-in hooks and repo checkout for up to 8 h, so
-            // take the same recreate path the arm below takes — which, passing no
-            // `imageVersion`, boots the latest (handler.ts's `run`).
-            if (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
+            // False/absent disables silent automatic roll-forward; an explicit restart
+            // 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);
             }
             return resumeMicrovm(doorbell, doorbell.microvmId, shape, microvm, timing, polled, described.startedAt, described.imageVersion);

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

@@ -14,6 +14,12 @@ export interface StageMicrovmImageContextOptions {
     readonly originUrl: string;
     /** Directory to write the build context to. Removed and recreated. */
     readonly destination: string;
+    /**
+     * Overlay scripts the image build runs as root and as `runner`. The overlay
+     * ships inside the shared snapshot, so it may install software but must carry
+     * no credential. When omitted, deterministic no-op scripts are written.
+     */
+    readonly overlayDir?: string;
     /**
      * The published template to copy from. Defaults to the one inside this
      * package; named directly by the tests, which assert against a template they
@@ -23,11 +29,14 @@ export interface StageMicrovmImageContextOptions {
 }
 /**
  * Writes the build context AWS unpacks — the Dockerfile, the hook server, the
- * per-phase hook scripts and the repository — and returns its path. The result
- * is what `EvidentMicrovmConstruct`'s `imageSource` takes.
+ * per-phase hook scripts, the deployment overlay and the repository — and
+ * returns its path. The result is what `EvidentMicrovmConstruct`'s `imageSource`
+ * takes.
  *
- * The first three come from this package's published `dist/`, so a consumer
- * needs no checkout of `sroze/evident` and no copy of the Dockerfile or hook
- * scripts (#1528). Only `repositoryPath` is theirs to supply.
+ * The Dockerfile, hook server and phase hooks come from this package's
+ * published `dist/`, so a consumer needs no checkout of the source repository and no
+ * copy of those files (#1528). A caller may supply an overlay; the default is
+ * deterministic no-op scripts. `repositoryPath` is the only required caller
+ * input.
  */
 export declare function stageMicrovmImageContext(options: StageMicrovmImageContextOptions): string;

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

@@ -66,8 +66,8 @@ function isShallowRepository(repositoryPath) {
     }
 }
 /**
- * Clones the caller's repository into the build context, so the Dockerfile can
- * ship the workspace already installed.
+ * Clones the caller's repository into the build context for the Dockerfile to
+ * bake as a checked-out but uninstalled workspace.
  *
  * `file://` rather than a plain path: a path triggers git's local-clone
  * optimisation, which copies the whole object store — every branch and worktree
@@ -102,21 +102,37 @@ function stageRepository(repositoryPath, destination, originUrl) {
     (0, node_fs_1.rmSync)(path.join(destination, '.git', 'index'), { force: true });
     (0, node_fs_1.rmSync)(path.join(destination, '.git', 'logs'), { recursive: true, force: true });
     console.log(`[stage] repo ${git(['rev-parse', 'HEAD'], destination)}`);
-    if (!(0, node_fs_1.existsSync)(path.join(destination, 'pnpm-lock.yaml'))) {
-        console.log(`[stage] ${repositoryPath} has no pnpm-lock.yaml — the image build will skip dependency installation`);
+}
+function stageScriptDirectory(source, destination) {
+    (0, node_fs_1.mkdirSync)(destination);
+    for (const entry of (0, node_fs_1.readdirSync)(source, { withFileTypes: true })) {
+        const sourcePath = path.join(source, entry.name);
+        const staged = path.join(destination, entry.name);
+        if (entry.isDirectory()) {
+            stageScriptDirectory(sourcePath, staged);
+            continue;
+        }
+        (0, node_fs_1.copyFileSync)(sourcePath, staged);
+        // Set modes here rather than inheriting them from the template, so they stay
+        // correct after an npm pack, zip, CI-cache or hand-copy round trip. The image
+        // executes extensionless scripts and sources `.sh` files.
+        (0, node_fs_1.chmodSync)(staged, entry.name.endsWith('.sh') ? 0o644 : 0o755);
     }
 }
 /**
  * Writes the build context AWS unpacks — the Dockerfile, the hook server, the
- * per-phase hook scripts and the repository — and returns its path. The result
- * is what `EvidentMicrovmConstruct`'s `imageSource` takes.
+ * per-phase hook scripts, the deployment overlay and the repository — and
+ * returns its path. The result is what `EvidentMicrovmConstruct`'s `imageSource`
+ * takes.
  *
- * The first three come from this package's published `dist/`, so a consumer
- * needs no checkout of `sroze/evident` and no copy of the Dockerfile or hook
- * scripts (#1528). Only `repositoryPath` is theirs to supply.
+ * The Dockerfile, hook server and phase hooks come from this package's
+ * published `dist/`, so a consumer needs no checkout of the source repository and no
+ * copy of those files (#1528). A caller may supply an overlay; the default is
+ * deterministic no-op scripts. `repositoryPath` is the only required caller
+ * input.
  */
 function stageMicrovmImageContext(options) {
-    const { originUrl, templateDir = TEMPLATE_DIR } = options;
+    const { originUrl, overlayDir, templateDir = TEMPLATE_DIR } = options;
     // `file://` and the clone below only mean anything against absolute paths,
     // and a caller may reasonably pass either.
     const repositoryPath = path.resolve(options.repositoryPath);
@@ -132,16 +148,27 @@ function stageMicrovmImageContext(options) {
     (0, node_fs_1.copyFileSync)(path.join(templateDir, 'hook-server.js'), path.join(destination, 'hook-server.js'));
     const hooksSource = path.join(templateDir, 'hooks');
     const hooksStage = path.join(destination, 'hooks');
-    (0, node_fs_1.mkdirSync)(hooksStage);
-    for (const entry of (0, node_fs_1.readdirSync)(hooksSource)) {
-        const staged = path.join(hooksStage, entry);
-        (0, node_fs_1.copyFileSync)(path.join(hooksSource, entry), staged);
-        // The runtime only runs a hook it can execute. Set here rather than
-        // inherited from the template, so the staged mode is a property of THIS
-        // function rather than of however the template reached disk — `npm pack`
-        // does carry the bit, but a zip-based vendoring, a CI cache restore or a
-        // hand-copied directory need not.
-        (0, node_fs_1.chmodSync)(staged, entry.endsWith('.sh') ? 0o644 : 0o755);
+    stageScriptDirectory(hooksSource, hooksStage);
+    const overlayStage = path.join(destination, 'overlay');
+    if (overlayDir === undefined) {
+        (0, node_fs_1.mkdirSync)(overlayStage);
+        for (const name of ['setup-root', 'setup-workspace']) {
+            const staged = path.join(overlayStage, name);
+            (0, node_fs_1.writeFileSync)(staged, '#!/usr/bin/env bash\n# No overlay supplied.\n', { mode: 0o755 });
+            (0, node_fs_1.chmodSync)(staged, 0o755);
+        }
+    }
+    else {
+        const resolvedOverlayDir = path.resolve(overlayDir);
+        if (!(0, node_fs_1.existsSync)(resolvedOverlayDir)) {
+            throw new Error(`overlay directory does not exist: ${resolvedOverlayDir}`);
+        }
+        for (const required of ['setup-root', 'setup-workspace']) {
+            if (!(0, node_fs_1.existsSync)(path.join(resolvedOverlayDir, required))) {
+                throw new Error(`overlay directory ${resolvedOverlayDir} is missing required script ${required}`);
+            }
+        }
+        stageScriptDirectory(resolvedOverlayDir, overlayStage);
     }
     stageRepository(repositoryPath, path.join(destination, 'repo'), originUrl);
     return destination;

package/dist/microvm/image-version-reporter/construct.d.ts

@@ -0,0 +1,35 @@
+import { Construct } from 'constructs';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import type { MicrovmImageBuildInputs } from '@evident-ai/lambda-microvm-cdk';
+export type ImageVersionReporterProps = {
+    /** The secret whose value is the same HMAC key the controller verifies every doorbell against. */
+    doorbellSecret: secretsmanager.ISecret;
+    /** Base URL of Evident's own API — non-secret. */
+    evidentApiUrl: string;
+    /** The pool runner id the report is filed against — non-secret, public UUID. */
+    evidentRunnerId: string;
+    /** Shape name -> the `Fn::GetAtt LatestActiveImageVersion` published this deploy. */
+    imageVersions: Record<string, string>;
+    /**
+     * Shape name -> {@link MicrovmImageBuildInputs}, a STRUCTURED object (never
+     * a delimiter-joined string — see its docstring for why flattening is
+     * unsafe) that changes whenever THIS deploy's build inputs change. Unlike
+     * `imageVersions`' `Fn::GetAtt` (a runtime attribute of the MicroVM image
+     * service, whose deploy-time propagation to a dependent resource this
+     * construct cannot itself guarantee), every field here is either a
+     * synth-time-computed literal or a plain `Ref`/`Fn::GetAtt` to a resource
+     * IN THIS STACK — CloudFormation diffs the full resolved property tree, so
+     * a change anywhere in this object is a certain, not merely likely,
+     * re-invocation trigger.
+     */
+    buildTriggers: Record<string, MicrovmImageBuildInputs>;
+};
+/**
+ * Deploy-time push: reports each shape's just-published MicroVM image version to
+ * Evident, once per deploy that actually changes it. `imageVersions` is the
+ * payload; `buildTriggers` is what guarantees re-invocation on exactly the
+ * deploy that matters, independent of `imageVersions`' own resolution timing.
+ */
+export declare class ImageVersionReporter extends Construct {
+    constructor(scope: Construct, id: string, props: ImageVersionReporterProps);
+}