@evident-ai/runner-cdk 3.5.2-dev.7130f36 → 3.5.2-dev.81383cc

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 the source repository involved. See
+  and suspends between messages. You provide a build-context directory and a full source
+  checkout to `stageMicrovmBuildContext`, then pass its returned directory as
+  `buildContextPath` (see [The MicroVM image](#the-microvm-image) below). See
   [the AWS runner doc](https://evident.run/docs/aws-runner) for the full picture of both
   strategies.
 
@@ -99,6 +99,26 @@ For the full end-to-end walkthrough for this construct, see
 | `agentSecret`, `wakerSecret` | `secretsmanager.ISecret` | Any Secrets Manager secret. |
 | `availableSecretKeys` | `Set<string>` | Keys present in the agent secret. Every listed key is injected; `EVIDENT_RUNNER_KEY` and `EVIDENT_AGENT_KEY` are injected from the `EVIDENT_AGENT_KEY` field, and `GH_TOKEN` is also injected for adopters that do not enumerate their secret. |
 
+### MicroVM props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `buildContextPath` | `string` | Directory containing your Dockerfile and every file it copies, normally the result of `stageMicrovmBuildContext()`. |
+| `baseImageArn` / `baseImageVersion` | `string` | The AWS-managed base MicroVM image values from `aws lambda-microvms list-managed-microvm-images`. |
+| `controllerSigningSecret` | `secretsmanager.ISecret` | Secret containing the shared HMAC key under the `CONTROLLER_SIGNING_SECRET` JSON field. |
+| `hooksPort` / `hookTimeoutSeconds` | `number` | Values exported by the base image contract. |
+| `shapes` | `readonly MicrovmShape[]?` | Shape catalogue to build. Defaults to the committed catalogue. |
+| `runnerSecret` | `secretsmanager.ISecret?` | Optional JSON secret whose values are exported by `/run`. |
+| `runnerOpencodeConfigPath` | `string?` | Optional baked OpenCode configuration path. |
+| `gitUserName` / `gitUserEmail` | `string?` | Optional git identity for agent commits. |
+| `extraImageEnvironment` | `Record<string,string>?` | Non-secret values baked into every VM launched from the image version. |
+| `evidentApiUrl` / `evidentRunnerId` | `string?` | Supply both to report published image versions to Evident, or omit both. |
+| `imageVersionPruning` | `boolean?` | Opts into construct-owned pruning for this deployment's images. Uses the engine defaults; omitting it creates no pruning resources. |
+
+The `DoorbellSecret` CloudFormation logical ID remains stable for Evident's own
+default stack. It identifies the deployed secret resource, not the customer-facing
+name of the signing key.
+
 ### Two deliberate "no default" choices
 
 - **The endpoints are required.** Defaulting them would either bake *our* dev environment
@@ -116,58 +136,73 @@ built from a `Dockerfile` you control. The generic runner image lives separately
 
 ## The MicroVM image
 
-`EvidentMicrovmConstruct`'s `imageSource` is a **local directory** holding the image build
-context, which `cdk deploy` zips and uploads. The Lambda MicroVM service then builds the
-image in *your* account, from a base image ARN you discover there — so, unlike the Fargate
-strategy, there is no registry image to pull.
+### Prune image versions
 
-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:
+MicroVM image versions are quota-bound. Opt into construct-owned pruning with one
+property:
+
+```ts
+new EvidentMicrovmConstruct(this, 'Runner', {
+  // ...other required MicroVM props
+  imageVersionPruning: true,
+});
+```
+
+This bounds the per-image version quota (`L-F8BECE9C`) for this deployment's shapes only.
+Retention follows the engine defaults, and pruning runs before the image publish for the
+deploy that invokes it. The custom-resource Lambda writes per-image verdicts and a summary
+to CloudWatch Logs. Use the `prune-microvm-image-versions` CLI for deployments that do not
+use this construct or that need non-default retention; see the
+`@evident-ai/lambda-microvm-cdk` package README for its flags and safety semantics.
+
+`EvidentMicrovmConstruct`'s `buildContextPath` is a **local directory** holding the
+Dockerfile you control and everything it copies. `cdk deploy` zips and uploads that
+directory, and the Lambda MicroVM service builds the image in *your* account. Start the
+Dockerfile from a pinned `ghcr.io/sroze/evident-microvm-base:X.Y.Z` tag; the base image
+contains the hook server, lifecycle hooks and common agent tooling.
+
+`stageMicrovmBuildContext()` combines your build-context directory with a full checkout
+of the workspace in a fresh temporary directory. The workspace is written at
+`workspace/`, and the returned path is the value for `buildContextPath`:
 
 ```ts
-import path from 'node:path';
 import {
   EvidentMicrovmConstruct,
   HOOKS_PORT,
   HOOK_TIMEOUT_SECONDS,
-  stageMicrovmImageContext,
+  stageMicrovmBuildContext,
 } from '@evident-ai/runner-cdk';
 
+const buildContextPath = stageMicrovmBuildContext({
+  // A full (non-shallow) clone: the agent branches, commits and opens PRs.
+  workspaceRepositoryPath: '/path/to/your/checkout',
+  // Credential-free: the token the agent pushes with arrives per-session.
+  workspaceOriginUrl: 'https://github.com/acme/widgets.git',
+  buildContextPath: '/path/to/your/microvm-build-context',
+});
+
 new EvidentMicrovmConstruct(this, 'Runner', {
-  imageSource: stageMicrovmImageContext({
-    // A full (non-shallow) clone: the agent branches, commits and opens PRs.
-    repositoryPath: '/path/to/your/checkout',
-    // Credential-free — this string ships inside the shared snapshot. The
-    // 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',
-  }),
+  buildContextPath,
   // Must match the published image these were baked into, so export them
   // rather than restating the numbers.
   hooksPort: HOOKS_PORT,
   hookTimeoutSeconds: HOOK_TIMEOUT_SECONDS,
   baseImageArn,
   baseImageVersion,
-  doorbellSecret,
+  controllerSigningSecret,
   runnerSecret,
   runnerOpencodeConfigPath: 'opencode.runner.jsonc',
 });
 ```
 
-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](https://github.com/evident-run/evident-run/blob/main/runner/docker-images/microvm/README.md)
-for the full overlay contract.
+Write project-specific installation and build steps in your Dockerfile. The [MicroVM base
+image README](../../runner/docker-images/microvm/README.md) documents the consumer
+contract, including the required `USER`, `WORKDIR`, ownership and `git reset --quiet`
+steps.
 
-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.
+The staged image includes your repository checkout, while your Dockerfile controls its
+package manager and build warm-up. Do not copy credentials into the build context or bake
+them into image environment variables.
 
 | MicroVM prop | Omitted behavior |
 | --- | --- |
@@ -175,12 +210,27 @@ its package manager. To speed up first boot, install dependencies from your over
 | `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.
+| `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 `controllerSigningSecret`). 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 environment for the image. 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.
+
+## Breaking changes in this release
+
+- `stageMicrovmImageContext` is removed. Use `stageMicrovmBuildContext()` with your
+  Dockerfile and build context.
+- `imageSource` is renamed to `buildContextPath`.
+- `MicrovmShape.constructId` is removed. CloudFormation child identity derives from
+  the shape `name`.
+- `doorbellSecret` is renamed to `controllerSigningSecret`.
+- The default shape's `imageName` changes to `evident-microvm-standard`. The
+  `AWS::Lambda::MicrovmImage` resource, its auto-created build role and execution
+  role, and both roles' default policies are replaced with the new shape identity.
+- The JSON field in the caller-supplied Secrets Manager secret changes from
+  `DOORBELL_SECRET` to `CONTROLLER_SIGNING_SECRET`. Rename that field in your own
+  secret. If you do not, the controller reads no signing key and every doorbell
+  returns HTTP 401 at runtime; TypeScript cannot catch this field-key change.
 
 ## Status / limitations
 

package/dist/controller-lambda/handler.js

@@ -50036,13 +50036,13 @@ async function shouldRecreateForNewerImage(doorbellRequest, shape, runningVersio
 async function handleDoorbell({
   rawBody,
   signatureHeader,
-  doorbellSecret,
+  controllerSigningSecret,
   shapes,
   microvm,
   sleep: sleep4,
   random
 }) {
-  if (!verifyEvidentSignature(rawBody, signatureHeader, doorbellSecret)) {
+  if (!verifyEvidentSignature(rawBody, signatureHeader, controllerSigningSecret)) {
     return decide({
       statusCode: 401,
       action: "rejected",
@@ -50413,20 +50413,20 @@ function parseShapeCatalogue(raw) {
 // src/microvm/controller/handler.ts
 var microvms = new import_client_lambda_microvms.LambdaMicrovmsClient({});
 var secrets = new import_client_secrets_manager.SecretsManagerClient({});
-var cachedDoorbellSecret;
-async function getDoorbellSecret(secretArn, key) {
-  if (cachedDoorbellSecret !== void 0) {
-    return cachedDoorbellSecret;
+var cachedControllerSigningSecret;
+async function getControllerSigningSecret(secretArn, key) {
+  if (cachedControllerSigningSecret !== void 0) {
+    return cachedControllerSigningSecret;
   }
   const { SecretString } = await secrets.send(new import_client_secrets_manager.GetSecretValueCommand({ SecretId: secretArn }));
   if (!SecretString) {
-    throw new Error(`doorbell secret ${secretArn} has no SecretString`);
+    throw new Error(`controller signing secret ${secretArn} has no SecretString`);
   }
   const value = JSON.parse(SecretString)[key];
   if (typeof value !== "string" || value === "") {
-    throw new Error(`doorbell secret ${secretArn} is missing a non-empty '${key}' field`);
+    throw new Error(`controller signing secret ${secretArn} is missing a non-empty '${key}' field`);
   }
-  cachedDoorbellSecret = value;
+  cachedControllerSigningSecret = value;
   return value;
 }
 function createRuntimeMicrovm(executionRoleArn) {
@@ -50501,9 +50501,9 @@ function requireEnv(name) {
 }
 var sleep3 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var handler = async (event) => {
-  const doorbellSecret = await getDoorbellSecret(
-    requireEnv("DOORBELL_SECRET_ARN"),
-    requireEnv("DOORBELL_SECRET_KEY")
+  const controllerSigningSecret = await getControllerSigningSecret(
+    requireEnv("CONTROLLER_SIGNING_SECRET_ARN"),
+    requireEnv("CONTROLLER_SIGNING_SECRET_KEY")
   );
   const shapes = parseShapeCatalogue(requireEnv("MICROVM_SHAPES"));
   const executionRoleArn = requireEnv("MICROVM_EXECUTION_ROLE_ARN");
@@ -50511,7 +50511,7 @@ var handler = async (event) => {
   const { statusCode, body } = await handleDoorbell({
     rawBody,
     signatureHeader: event.headers?.["x-evident-signature"],
-    doorbellSecret,
+    controllerSigningSecret,
     shapes,
     microvm: createRuntimeMicrovm(executionRoleArn),
     sleep: sleep3,