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

package/README.md

@@ -9,9 +9,9 @@ Reusable AWS CDK constructs for running an [Evident](https://evident.run) agent
   `desiredCount 0`, and an HMAC-authenticated waker Lambda scales it back up on the next
   message. You pay for the time the agent is actually working.
 - **`EvidentMicrovmConstruct`** — a per-session AWS Lambda MicroVM that boots on demand
-  and suspends between messages. Installing 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
+  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
   [the AWS runner doc](https://evident.run/docs/aws-runner) for the full picture of both
   strategies.
 
@@ -34,8 +34,9 @@ cluster can host several agents.
 ## Getting started
 
 For a full end-to-end walkthrough — shared infra, secrets without SOPS/KMS, the image,
-the two grants, deploy, and wiring the wake webhook — see
-[`GETTING-STARTED.md`](./GETTING-STARTED.md). The snippet below is the short version.
+the two grants, deploy, and wiring the wake webhook — see `GETTING-STARTED.md` in this
+package's directory (not published to npm; read it from a checkout of the repo). The
+snippet below is the short version.
 
 ```ts
 import { EvidentScaleToZeroConstruct } from "@evident-ai/runner-cdk";
@@ -96,7 +97,7 @@ the construct's own dogfooding consumer.
 | `cluster`, `securityGroup`, `taskRole`, `logGroup`, `replicaBucket` | interfaces | Shared infra you create and pass in. |
 | `image` | `ecs.ContainerImage` | Your runner image. |
 | `agentSecret`, `wakerSecret` | `secretsmanager.ISecret` | Any Secrets Manager secret. |
-| `availableSecretKeys` | `Set<string>` | Keys present in the agent secret. Requires `EVIDENT_AGENT_KEY` + `GH_TOKEN`; MCP credentials (`BRAVE_API_KEY`, `CLOUDFLARE_API_TOKEN`, `NEON_API_KEY`) are injected only when listed. |
+| `availableSecretKeys` | `Set<string>` | Keys present in the agent secret. Every listed key is injected; `EVIDENT_AGENT_KEY` and `GH_TOKEN` are also injected for compatibility with adopters that do not enumerate their secret. |
 
 ### Two deliberate "no default" choices
 
@@ -111,7 +112,7 @@ the construct's own dogfooding consumer.
 
 This construct never builds an image. Pass any `ecs.ContainerImage` — from a registry, or
 built from a `Dockerfile` you control. The generic runner image lives separately in
-`packages/runner-image`, so you can adopt the image, the construct, or both.
+`runner/docker-images/fargate`, so you can adopt the image, the construct, or both.
 
 ## The MicroVM image
 
@@ -126,6 +127,7 @@ the per-phase hook scripts and the bundled hook server, published inside the tar
 the agent's workspace. `stageMicrovmImageContext()` puts the two together:
 
 ```ts
+import path from 'node:path';
 import {
   EvidentMicrovmConstruct,
   HOOKS_PORT,
@@ -149,6 +151,8 @@ new EvidentMicrovmConstruct(this, 'Runner', {
   baseImageArn,
   baseImageVersion,
   doorbellSecret,
+  runnerSecret,
+  runnerOpencodeConfigPath: 'opencode.runner.jsonc',
 });
 ```
 
@@ -156,14 +160,20 @@ Your repo does not have to be a pnpm workspace. If it commits a `pnpm-lock.yaml`
 pre-installs dependencies at build time (a faster first boot); if not, that step is skipped
 and the agent installs 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. |
+| `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. |
+
 ## Status / limitations
 
-- **Published to npm** as `@evident-ai/runner-cdk` (MIT) — see
-  [#957](https://github.com/sroze/evident/issues/957). Install it with `npm install
-  @evident-ai/runner-cdk` (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.
+- **Published to npm** as `@evident-ai/runner-cdk` (MIT). Install the `@dev` tag —
+  `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.
 - **AWS/ECS-specific.** Non-AWS clouds are an open question on the epic, not a supported
   path.

package/dist/controller-lambda/handler.js

@@ -42866,7 +42866,7 @@ Reference: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.ht
 // ../../node_modules/.pnpm/@aws-sdk+signature-v4-multi-region@3.996.42/node_modules/@aws-sdk/signature-v4-multi-region/dist-cjs/index.js
 var require_dist_cjs23 = __commonJS({
   "../../node_modules/.pnpm/@aws-sdk+signature-v4-multi-region@3.996.42/node_modules/@aws-sdk/signature-v4-multi-region/dist-cjs/index.js"(exports2) {
-    var { SignatureV4: SignatureV43, signatureV4aContainer } = require_dist_cjs17();
+    var { SignatureV4: SignatureV43, signatureV4aContainer } = require_dist_cjs2();
     var signatureV4CrtContainer = {
       CrtSignerV4: null
     };
@@ -49949,6 +49949,7 @@ function decide({
   runnerId,
   microvmId,
   startedAt,
+  imageVersion,
   shapes,
   polled
 }) {
@@ -49966,6 +49967,7 @@ function decide({
       reason,
       ...microvmId === void 0 ? {} : { microvm_id: microvmId },
       ...startedAt === void 0 ? {} : { microvm_started_at: startedAt.toISOString() },
+      ...imageVersion === void 0 ? {} : { image_version: imageVersion },
       ...shapes === void 0 ? {} : { shapes },
       ...polled === true ? { polled: true } : {}
     }),
@@ -50122,7 +50124,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         runnerId: doorbell.runnerId,
         microvmId: doorbell.microvmId,
         polled,
-        startedAt: described.startedAt
+        startedAt: described.startedAt,
+        imageVersion: described.imageVersion
       });
     case "SUSPENDED":
       if (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
@@ -50143,7 +50146,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         microvm,
         timing,
         polled,
-        described.startedAt
+        described.startedAt,
+        described.imageVersion
       );
     default:
       return runMicrovm(
@@ -50220,10 +50224,11 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
     runnerId: doorbell.runnerId,
     microvmId: started.microvmId,
     polled,
-    startedAt: started.startedAt
+    startedAt: started.startedAt,
+    imageVersion: started.imageVersion
   });
 }
-async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, startedAt) {
+async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, startedAt, imageVersion) {
   try {
     await withThrottleRetry(() => microvm.resume(microvmId), timing);
   } catch (error3) {
@@ -50248,7 +50253,8 @@ async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled
     runnerId: doorbell.runnerId,
     microvmId,
     polled,
-    startedAt
+    startedAt,
+    imageVersion
   });
 }
 async function suspendMicrovm(doorbell, microvm, timing) {
@@ -50443,7 +50449,7 @@ function createRuntimeMicrovm(executionRoleArn) {
       return latestActiveImageVersion;
     },
     async run({ imageIdentifier, runHookPayload, clientToken }) {
-      const { microvmId, startedAt } = await microvms.send(
+      const { microvmId, startedAt, imageVersion } = await microvms.send(
         new import_client_lambda_microvms.RunMicrovmCommand({
           imageIdentifier,
           executionRoleArn,
@@ -50476,7 +50482,7 @@ function createRuntimeMicrovm(executionRoleArn) {
       if (!microvmId) {
         throw new Error("RunMicrovm returned no microvmId");
       }
-      return { microvmId, startedAt };
+      return { microvmId, startedAt, imageVersion };
     },
     async resume(microvmId) {
       await microvms.send(new import_client_lambda_microvms.ResumeMicrovmCommand({ microvmIdentifier: microvmId }));

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

@@ -61,13 +61,25 @@ export type EvidentScaleToZeroConstructProps = {
     replicaBucket: s3.IBucket;
     image: ecs.ContainerImage;
     /**
-     * Container secrets. Requires EVIDENT_AGENT_KEY + GH_TOKEN; the MCP
-     * credentials BRAVE_API_KEY / CLOUDFLARE_API_TOKEN / NEON_API_KEY are injected
-     * only if present (see availableSecretKeys).
+     * Container secrets. `availableSecretKeys` are injected by name; EVIDENT_AGENT_KEY
+     * and GH_TOKEN remain available to external adopters that do not enumerate keys.
+     *
+     * `agentSecret` always supplies EVIDENT_AGENT_KEY. When `capabilitySecret` is
+     * ALSO given (#1868 WI-2), every capability key (GH_TOKEN included) is injected
+     * from THAT secret instead, and `availableSecretKeys` is ignored — the two
+     * deploy targets (this one and the MicroVM stack) then read the same
+     * capability keys from the same shared secret rather than each carrying its
+     * own copy. When `capabilitySecret` is absent, behavior is unchanged: GH_TOKEN
+     * plus every `availableSecretKeys` entry, all from `agentSecret` — an external
+     * adopter passing only `agentSecret`/`availableSecretKeys` is unaffected.
      */
     agentSecret: secretsmanager.ISecret;
-    /** Key names present in the agent secret; gates the optional MCP creds. */
+    /** Key names present in the agent secret. Every listed key is injected into the container. */
     availableSecretKeys: Set<string>;
+    /** The shared capability secret (#1868 WI-2). See `agentSecret`'s doc above. */
+    capabilitySecret?: secretsmanager.ISecret;
+    /** Key names present in `capabilitySecret`. Ignored when `capabilitySecret` is absent. */
+    capabilityKeys?: Set<string>;
     /** Waker secret (EVIDENT_WAKE_SECRET), consumed by the waker at runtime. */
     wakerSecret: secretsmanager.ISecret;
 };

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

@@ -61,7 +61,7 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
     service;
     constructor(scope, id, props) {
         super(scope, id);
-        const { agentName, evidentAgentId, gitRepo, gitBranch, idleTimeoutSeconds, cpu, memoryLimitMiB, resourcePrefix = DEFAULT_RESOURCE_PREFIX, envName, evidentApiUrl, evidentTunnelUrl, extraEnvironment, cluster, securityGroup, taskRole, logGroup, replicaBucket, image, agentSecret, availableSecretKeys, wakerSecret, } = props;
+        const { agentName, evidentAgentId, gitRepo, gitBranch, idleTimeoutSeconds, cpu, memoryLimitMiB, resourcePrefix = DEFAULT_RESOURCE_PREFIX, envName, evidentApiUrl, evidentTunnelUrl, extraEnvironment, cluster, securityGroup, taskRole, logGroup, replicaBucket, image, agentSecret, availableSecretKeys, capabilitySecret, capabilityKeys, wakerSecret, } = props;
         this.replicaPrefix = `agents/${evidentAgentId}`;
         // A plain STRING (not service.serviceName) so the container env is static and
         // has no construct-ordering dependency on the service.
@@ -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,
@@ -128,16 +127,22 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             ...extraEnvironment,
         };
         const secrets = {
+            // Identifies the runner to Evident. Always agentSecret — capabilitySecret
+            // never carries this key (#1868 WI-2: the two are a deliberate split, not
+            // a duplication of the same data).
             EVIDENT_AGENT_KEY: ecs.Secret.fromSecretsManager(agentSecret, 'EVIDENT_AGENT_KEY'),
-            GH_TOKEN: ecs.Secret.fromSecretsManager(agentSecret, 'GH_TOKEN'),
         };
-        // Optional MCP creds (consumed by opencode.runner.jsonc): BRAVE_API_KEY →
-        // brave-search, CLOUDFLARE_API_TOKEN → the Cloudflare MCP, NEON_API_KEY →
-        // the Neon MCP (read-only). Injected only if present in the SOPS file — a
-        // referenced-but-absent key fails ECS task startup, so an operator can
-        // enable an MCP by just adding its key + redeploy.
-        for (const key of ['BRAVE_API_KEY', 'CLOUDFLARE_API_TOKEN', 'NEON_API_KEY']) {
-            if (availableSecretKeys.has(key)) {
+        if (capabilitySecret !== undefined) {
+            for (const key of capabilityKeys ?? new Set()) {
+                secrets[key] = ecs.Secret.fromSecretsManager(capabilitySecret, key);
+            }
+        }
+        else {
+            // Legacy shape, unchanged: GH_TOKEN (required to clone this construct's
+            // workspace at boot) plus every availableSecretKeys entry, all from
+            // agentSecret — what every external adopter still gets.
+            secrets.GH_TOKEN = ecs.Secret.fromSecretsManager(agentSecret, 'GH_TOKEN');
+            for (const key of availableSecretKeys) {
                 secrets[key] = ecs.Secret.fromSecretsManager(agentSecret, key);
             }
         }

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/constants.js

@@ -1,9 +1,8 @@
 "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 — including `microvm/image/hook-server.ts`, which runs inside the
-// image and is esbuild-bundled into the published build context by
-// `scripts/build.ts`, so these values reach the image as inlined constants.
+// 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

package/dist/microvm/construct.d.ts

@@ -12,7 +12,7 @@ export interface EvidentMicrovmConstructProps {
     readonly imageSource: string;
     /**
      * ARN of the Lambda-managed base MicroVM image, from
-     * `aws lambda list-managed-microvm-images`. A string, not a `CfnParameter`
+     * `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.
@@ -20,7 +20,7 @@ export interface EvidentMicrovmConstructProps {
     readonly baseImageArn: string;
     /**
      * Version of the Lambda-managed base MicroVM image, from
-     * `aws lambda list-managed-microvm-images`. See `baseImageArn` for why this
+     * `aws lambda-microvms list-managed-microvm-images`. See `baseImageArn` for why this
      * is a plain string.
      */
     readonly baseImageVersion: string;
@@ -41,6 +41,20 @@ export interface EvidentMicrovmConstructProps {
      * 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
@@ -55,6 +69,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
@@ -121,6 +131,16 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
             // 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 = {
@@ -179,6 +199,8 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
         // 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
@@ -237,6 +259,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/handle-doorbell.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleDoorbell = handleDoorbell;
 const node_crypto_1 = require("node:crypto");
-const webhook_signature_1 = require("@evident/webhook-signature");
+const sdk_1 = require("@evident/sdk");
 const constants_1 = require("../constants");
 const doorbell_1 = require("./doorbell");
 const throttle_retry_1 = require("./throttle-retry");
@@ -37,7 +37,7 @@ const LOG_ACTION = {
     rejected: 'reject',
     describe: 'describe',
 };
-function decide({ statusCode, action, reason, state, runnerId, microvmId, startedAt, shapes, polled, }) {
+function decide({ statusCode, action, reason, state, runnerId, microvmId, startedAt, imageVersion, shapes, polled, }) {
     const line = `[doorbell] state=${state ?? 'none'} action=${LOG_ACTION[action]} ` +
         `microvm_id=${microvmId ?? '-'} runner_id=${runnerId ?? '-'} reason=${reason}` +
         (polled === undefined ? '' : ` polled=${polled}`);
@@ -56,6 +56,7 @@ function decide({ statusCode, action, reason, state, runnerId, microvmId, starte
             reason,
             ...(microvmId === undefined ? {} : { microvm_id: microvmId }),
             ...(startedAt === undefined ? {} : { microvm_started_at: startedAt.toISOString() }),
+            ...(imageVersion === undefined ? {} : { image_version: imageVersion }),
             ...(shapes === undefined ? {} : { shapes }),
             ...(polled === true ? { polled: true } : {}),
         }),
@@ -175,7 +176,7 @@ async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, micr
     return compareImageVersions(running, latest) < 0;
 }
 async function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes, microvm, sleep, random, }) {
-    if (!(0, webhook_signature_1.verifyWakeSignature)(rawBody, signatureHeader, doorbellSecret)) {
+    if (!(0, sdk_1.verifyEvidentSignature)(rawBody, signatureHeader, doorbellSecret)) {
         return decide({
             statusCode: 401,
             action: 'rejected',
@@ -283,6 +284,7 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
                 microvmId: doorbell.microvmId,
                 polled,
                 startedAt: described.startedAt,
+                imageVersion: described.imageVersion,
             });
         case 'SUSPENDED':
             // A newer image has been published since this VM booted: resuming would
@@ -292,7 +294,7 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
             if (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);
+            return resumeMicrovm(doorbell, doorbell.microvmId, shape, microvm, timing, polled, described.startedAt, described.imageVersion);
         default:
             // TERMINATED, TERMINATING, not_found — gone or going, so a fresh VM either
             // way. This is what self-heals a stale `microvm_id`.
@@ -387,13 +389,13 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
         microvmId: started.microvmId,
         polled,
         startedAt: started.startedAt,
+        imageVersion: started.imageVersion,
     });
 }
 async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, 
-// Threaded in from the `describe()` result that led here — `ResumeMicrovm`
-// itself returns no `startedAt` (its response is empty), so this arm has no
-// timestamp of its own to report.
-startedAt) {
+// Both values come from the `describe()` result that led here because
+// `ResumeMicrovm` returns no lifecycle metadata of its own.
+startedAt, imageVersion) {
     try {
         await (0, throttle_retry_1.withThrottleRetry)(() => microvm.resume(microvmId), timing);
     }
@@ -411,6 +413,7 @@ startedAt) {
         microvmId,
         polled,
         startedAt,
+        imageVersion,
     });
 }
 async function suspendMicrovm(doorbell, microvm, timing) {

package/dist/microvm/controller/microvm-client.d.ts

@@ -49,7 +49,7 @@ export interface MicrovmClient {
      * (docs/spikes/lambda-microvms-phase0/README.md). AWS's own Claude-agents
      * guidance recommending `maxIdleDurationSeconds: 120` targets VMs reached
      * inbound and does not apply here. Idle is instead decided IN the VM by
-     * `evident run --idle-timeout` (packages/runner-cdk/microvm-image/hooks/common.sh's
+     * `evident run --idle-timeout` (runner/docker-images/microvm/hooks/common.sh's
      * `IDLE_TIMEOUT_SECONDS`), whose clean exit drives this
      * client's own `suspend()` via the `runner.suspend_requested` doorbell.
      */
@@ -69,6 +69,12 @@ export interface MicrovmClient {
          * none. Never synthesize one (e.g. `new Date()`) here or in any caller.
          */
         startedAt?: Date;
+        /**
+         * The image version this VM booted on, straight from `RunMicrovm`'s own
+         * `imageVersion`. Absent means AWS omitted it and must be read as UNKNOWN;
+         * see `MicrovmDescription.imageVersion` above.
+         */
+        imageVersion?: string;
     }>;
     resume(microvmId: string): Promise<void>;
     suspend(microvmId: string): Promise<void>;