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

package/README.md

@@ -165,6 +165,7 @@ and the agent installs on first use.
 | `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
 

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

@@ -69,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
@@ -249,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/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);
+}

package/dist/microvm/image-version-reporter/construct.js

@@ -0,0 +1,91 @@
+"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.ImageVersionReporter = 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 cr = __importStar(require("aws-cdk-lib/custom-resources"));
+/** The JSON field name inside the doorbell secret, same key the controller reads. */
+const DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';
+/**
+ * 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.
+ */
+class ImageVersionReporter extends constructs_1.Construct {
+    constructor(scope, id, props) {
+        super(scope, id);
+        const handler = new lambda.Function(this, 'Function', {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            // Pre-bundled at PACKAGE build time, same reasoning as the waker's and the
+            // controller's own `Code.fromAsset` (see their comments) — resolved from
+            // the PACKAGE ROOT, two directories below this file either compiled
+            // (`dist/microvm/image-version-reporter`) or via ts-node
+            // (`src/microvm/image-version-reporter`).
+            code: lambda.Code.fromAsset(path.join(__dirname, '..', '..', '..', 'dist', 'image-version-reporter-lambda')),
+            handler: 'handler.handler',
+            memorySize: 128,
+            // A deploy hook must not hold CloudFormation for its default 1 h — this is
+            // the hard stop; the handler's own internal REPORT_TIMEOUT_MS is well under it.
+            timeout: cdk.Duration.seconds(30),
+            environment: {
+                // ARN + field name only, never the value (mirrors the controller and waker).
+                DOORBELL_SECRET_ARN: props.doorbellSecret.secretArn,
+                DOORBELL_SECRET_KEY: DOORBELL_SECRET_KEY,
+                EVIDENT_API_URL: props.evidentApiUrl,
+                EVIDENT_RUNNER_ID: props.evidentRunnerId,
+            },
+        });
+        props.doorbellSecret.grantRead(handler);
+        const provider = new cr.Provider(this, 'Provider', {
+            onEventHandler: handler,
+        });
+        new cdk.CustomResource(this, 'Resource', {
+            serviceToken: provider.serviceToken,
+            properties: {
+                imageVersions: props.imageVersions,
+                // Not read by the handler — its only job is to be a property value
+                // CloudFormation can see change (a structured object, so any field
+                // changing anywhere is a real property diff), so the resource is
+                // invoked on exactly the deploy that changes a build input.
+                buildTriggers: props.buildTriggers,
+            },
+        });
+    }
+}
+exports.ImageVersionReporter = ImageVersionReporter;

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

@@ -0,0 +1,26 @@
+export type ImageVersionPair = {
+    shape: string;
+    image_version: string;
+};
+export type ReporterEvent = {
+    RequestType: 'Create' | 'Update' | 'Delete';
+    ResourceProperties?: {
+        imageVersions?: unknown;
+    };
+};
+export type ReporterConfig = {
+    doorbellSecretArn: string;
+    doorbellSecretKey: string;
+    evidentApiUrl: string;
+    evidentRunnerId: string;
+};
+type ReporterDependencies = {
+    getSecret: (secretArn: string, secretKey: string) => Promise<string>;
+    fetch: typeof fetch;
+};
+type ReporterResponse = {
+    PhysicalResourceId: string;
+};
+export declare function handleImageVersionReport(event: ReporterEvent, getConfig: () => ReporterConfig, dependencies?: ReporterDependencies): Promise<ReporterResponse>;
+export declare const handler: (event: ReporterEvent) => Promise<ReporterResponse>;
+export {};

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

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = void 0;
+exports.handleImageVersionReport = handleImageVersionReport;
+const node_crypto_1 = require("node:crypto");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const PHYSICAL_RESOURCE_ID = 'evident-image-version-report';
+const REPORT_TIMEOUT_MS = 5_000;
+const secrets = new client_secrets_manager_1.SecretsManagerClient({});
+async function fetchDoorbellSecret(secretArn, secretKey) {
+    const { SecretString } = await secrets.send(new client_secrets_manager_1.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]
+        : undefined;
+    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 };
+}
+const 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, node_crypto_1.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 === undefined ? {} : { status: responseStatus }),
+            error: message,
+        });
+    }
+    return response();
+}
+const handler = (event) => handleImageVersionReport(event, () => ({
+    doorbellSecretArn: requireEnv('DOORBELL_SECRET_ARN'),
+    doorbellSecretKey: requireEnv('DOORBELL_SECRET_KEY'),
+    evidentApiUrl: requireEnv('EVIDENT_API_URL'),
+    evidentRunnerId: requireEnv('EVIDENT_RUNNER_ID'),
+}));
+exports.handler = handler;

package/dist/microvm-image-context/hooks/common.sh

@@ -52,19 +52,20 @@ log() { echo "[hook:$(hook_name)] $*"; }
 warn() { echo "[hook:$(hook_name)] $*" >&2; }
 error() { echo "[hook:$(hook_name)] ERROR: $*" >&2; }
 
-# Returns the CLI's own exit code. Domain outcomes (nothing persisted yet, a
-# corrupt object) are LOGGED and exit 0, the predicates answer "no" with 10, and
+# Returns the CLI's own exit code. `restore` logs domain outcomes and returns 0;
+# a non-zero status means the tool itself failed. `sync-once` returns 40 for
+# `failed`, `hashFailed`, and `localInvalid` (credentials not persisted), and 0
+# for every other outcome. The predicates answer "no" with 10, and
 # `session-db-classify`'s three typed answers are 30 (fatal)/31 (replica
 # unusable)/32 (retry), extended by `session-db-verify`'s 33 (integrity
 # exhausted, replica separated and local disposed) / 34 (could not prove
-# separation or disposal) — see `runner/synchroniser/src/cli.ts`'s own
-# comment for what each means, not restated here. Any OTHER non-zero status
+# separation or disposal). Any status outside a command's contractual answers
 # means the tool itself broke, which is the only case worth an ERROR here.
 run_synchroniser() {
   local rc=0
   "${SYNCHRONISER}" "$@" || rc=$?
   case "${rc}" in
-    0 | 10 | 30 | 31 | 32 | 33 | 34) ;;
+    0 | 10 | 30 | 31 | 32 | 33 | 34 | 40) ;;
     *) error "synchroniser '$*' exited ${rc}; the '${SYNCHRONISER}' command is missing from PATH, corrupt, or it threw" ;;
   esac
   return "${rc}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "3.4.1-dev.c463782",
+  "version": "3.4.1-dev.cb56b3f",
   "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",