@evident-ai/runner-cdk 3.5.2-dev.2f7c636 → 3.5.2-dev.4f96188

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,25 @@ 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. |
+
+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 +135,65 @@ 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
+
+MicroVM image versions are quota-bound. `@evident-ai/lambda-microvm-cdk` ships the
+`prune-microvm-image-versions` CLI; enable it with one `package.json` script line:
+
+```json
+"microvm:prune": "prune-microvm-image-versions --image-arn arn:aws:lambda:eu-west-1:000000000000:microvm-image:your-image"
+```
+
+See the `@evident-ai/lambda-microvm-cdk` package README for the CLI 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.
 
-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:
+`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 +201,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,

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

@@ -157,6 +157,13 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
         // Object Get/Put/Delete scoped to this agent's prefix. DeleteObject is
         // required: Litestream's retention/compaction prunes old LTX files.
         replicaBucket.grantReadWrite(taskRole, `${this.replicaPrefix}/*`);
+        // Vault credentials are read and conditionally written, so this shared prefix
+        // needs no delete or list permission; conditional writes use request headers.
+        taskRole.addToPrincipalPolicy(new iam.PolicyStatement({
+            sid: 'ReadWriteCredentialVaultObjects',
+            actions: ['s3:GetObject', 's3:PutObject'],
+            resources: [replicaBucket.arnForObjects('credential-vaults/*')],
+        }));
         this.service = new ecs.FargateService(this, 'Service', {
             cluster,
             taskDefinition,

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

@@ -29,15 +29,17 @@ 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) {
+async function fetchControllerSigningSecret(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`);
+    throw new Error(`controller signing 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`);
+    throw new Error(
+      `controller signing secret ${secretArn} is missing a non-empty '${secretKey}' field`
+    );
   }
   return value;
 }
@@ -63,7 +65,7 @@ function response() {
   return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
 }
 var runtimeDependencies = {
-  getSecret: fetchDoorbellSecret,
+  getSecret: fetchControllerSigningSecret,
   fetch: globalThis.fetch
 };
 async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
@@ -77,7 +79,10 @@ async function handleImageVersionReport(event, getConfig, dependencies = runtime
     versions = readImageVersions(event.ResourceProperties?.imageVersions);
     const config = getConfig();
     runnerId = config.evidentRunnerId;
-    const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+    const secret = await dependencies.getSecret(
+      config.controllerSigningSecretArn,
+      config.controllerSigningSecretKey
+    );
     const body = JSON.stringify({
       type: "runner.microvm_image_versions_reported",
       versions
@@ -117,8 +122,8 @@ async function handleImageVersionReport(event, getConfig, dependencies = runtime
   return response();
 }
 var handler = (event) => handleImageVersionReport(event, () => ({
-  doorbellSecretArn: requireEnv("DOORBELL_SECRET_ARN"),
-  doorbellSecretKey: requireEnv("DOORBELL_SECRET_KEY"),
+  controllerSigningSecretArn: requireEnv("CONTROLLER_SIGNING_SECRET_ARN"),
+  controllerSigningSecretKey: requireEnv("CONTROLLER_SIGNING_SECRET_KEY"),
   evidentApiUrl: requireEnv("EVIDENT_API_URL"),
   evidentRunnerId: requireEnv("EVIDENT_RUNNER_ID")
 }));

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { EvidentWaker, type EvidentWakerProps } from './waker/construct';
 export { EvidentMicrovmConstruct, type EvidentMicrovmConstructProps } from './microvm/construct';
 export { MICROVM_SHAPES, validateShapes, type MicrovmShape } from './microvm/shapes';
 export { MICROVM_MAX_RUN_SECONDS, HOOKS_PORT, HOOK_TIMEOUT_SECONDS, } from './microvm/constants';
-export { stageMicrovmImageContext, type StageMicrovmImageContextOptions, } from './microvm/image/stage-context';
+export { MICROVM_WORKSPACE_DIRECTORY, stageMicrovmBuildContext, type StageMicrovmBuildContextOptions, } from './microvm/image/stage-context';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stageMicrovmImageContext = exports.HOOK_TIMEOUT_SECONDS = exports.HOOKS_PORT = exports.MICROVM_MAX_RUN_SECONDS = exports.validateShapes = exports.MICROVM_SHAPES = exports.EvidentMicrovmConstruct = exports.EvidentWaker = exports.EvidentScaleToZeroConstruct = void 0;
+exports.stageMicrovmBuildContext = exports.MICROVM_WORKSPACE_DIRECTORY = exports.HOOK_TIMEOUT_SECONDS = exports.HOOKS_PORT = exports.MICROVM_MAX_RUN_SECONDS = exports.validateShapes = exports.MICROVM_SHAPES = exports.EvidentMicrovmConstruct = exports.EvidentWaker = exports.EvidentScaleToZeroConstruct = void 0;
 var evident_scale_to_zero_construct_1 = require("./evident-scale-to-zero-construct");
 Object.defineProperty(exports, "EvidentScaleToZeroConstruct", { enumerable: true, get: function () { return evident_scale_to_zero_construct_1.EvidentScaleToZeroConstruct; } });
 var construct_1 = require("./waker/construct");
@@ -17,4 +17,5 @@ Object.defineProperty(exports, "MICROVM_MAX_RUN_SECONDS", { enumerable: true, ge
 Object.defineProperty(exports, "HOOKS_PORT", { enumerable: true, get: function () { return constants_1.HOOKS_PORT; } });
 Object.defineProperty(exports, "HOOK_TIMEOUT_SECONDS", { enumerable: true, get: function () { return constants_1.HOOK_TIMEOUT_SECONDS; } });
 var stage_context_1 = require("./microvm/image/stage-context");
-Object.defineProperty(exports, "stageMicrovmImageContext", { enumerable: true, get: function () { return stage_context_1.stageMicrovmImageContext; } });
+Object.defineProperty(exports, "MICROVM_WORKSPACE_DIRECTORY", { enumerable: true, get: function () { return stage_context_1.MICROVM_WORKSPACE_DIRECTORY; } });
+Object.defineProperty(exports, "stageMicrovmBuildContext", { enumerable: true, get: function () { return stage_context_1.stageMicrovmBuildContext; } });

package/dist/microvm/constants.d.ts

@@ -6,4 +6,4 @@ export declare const SUSPENDING_POLL_ATTEMPTS = 4;
 export declare const SUSPENDING_POLL_INTERVAL_MS = 500;
 export declare const MICROVM_MAX_RUN_SECONDS = 28800;
 export declare const SESSION_CLEANUP_MAX_AGE = "24h";
-export declare const DOORBELL_SECRET_KEY = "DOORBELL_SECRET";
+export declare const CONTROLLER_SIGNING_SECRET_KEY = "CONTROLLER_SIGNING_SECRET";

package/dist/microvm/constants.js

@@ -4,7 +4,7 @@
 // across them. The image template pins matching copies, guarded by
 // `microvm/image/dockerfile.test.ts`.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DOORBELL_SECRET_KEY = exports.SESSION_CLEANUP_MAX_AGE = 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;
+exports.CONTROLLER_SIGNING_SECRET_KEY = exports.SESSION_CLEANUP_MAX_AGE = 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
 // (`ENV HOOKS_PORT`) and passed to the construct as `hooksPort`. Exported from
 // the package index because a consumer building the published image context
@@ -38,6 +38,9 @@ exports.MICROVM_MAX_RUN_SECONDS = 28800;
 // The 24h window rather than 7d keeps the session database bounded at the growth
 // rate observed in #537. The sweep runs on the default 1h interval.
 exports.SESSION_CLEANUP_MAX_AGE = '24h';
-// The JSON field inside the doorbell secret is shared by the Lambdas that name
-// it and by whatever produces the secret; this is never the secret value.
-exports.DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';
+// The JSON field inside the controller signing secret is shared by the Lambdas
+// that name it and by whatever produces the secret; this is never the secret
+// value. It is customer-facing and separate from persisted doorbell messages
+// and telemetry. Changing the value silently stops an existing adopter's
+// secret from being read.
+exports.CONTROLLER_SIGNING_SECRET_KEY = 'CONTROLLER_SIGNING_SECRET';

package/dist/microvm/construct.d.ts

@@ -4,12 +4,10 @@ import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
 import { type MicrovmShape } from './shapes';
 export interface EvidentMicrovmConstructProps {
     /**
-     * Build context for the image, already staged on disk. An argument rather
-     * than something this construct stages itself, so synthesising the stack
-     * stays a pure function of its inputs instead of depending on how the
-     * ambient checkout was cloned.
+     * Directory containing the consumer's Dockerfile and every file it copies,
+     * typically the return value of `stageMicrovmBuildContext()`.
      */
-    readonly imageSource: string;
+    readonly buildContextPath: string;
     /**
      * ARN of the Lambda-managed base MicroVM image, from
      * `aws lambda-microvms list-managed-microvm-images`. A string, not a `CfnParameter`
@@ -33,14 +31,14 @@ export interface EvidentMicrovmConstructProps {
     readonly shapes?: readonly MicrovmShape[];
     /**
      * The secret holding the shared HMAC key the controller verifies every
-     * doorbell against, under the field `DOORBELL_SECRET`. Any Secrets Manager
+     * doorbell against, under the field `CONTROLLER_SIGNING_SECRET`. Any Secrets Manager
      * secret, however the caller manages it — this construct has no opinion on
      * SOPS, KMS, or any other production mechanism. Required (not defaulted
      * here): a default would need a scope of its own, and a caller-owned
      * default keeps its own logical id — the caller builds one exactly once,
      * in its own scope, and passes the result in either case.
      */
-    readonly doorbellSecret: secretsmanager.ISecret;
+    readonly controllerSigningSecret: secretsmanager.ISecret;
     /**
      * Optional runner secret whose JSON values are exported by `/run`. Omitting it
      * leaves GitHub and MCP credentials unavailable to a generic consumer.
@@ -65,7 +63,7 @@ export interface EvidentMicrovmConstructProps {
      * 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
      * means AWS probes a port nothing binds. Caller-supplied because the hook
-     * server is part of `imageSource`, which this construct does not build.
+     * server is part of the base image, which this construct does not build.
      */
     readonly hooksPort: number;
     /**

package/dist/microvm/construct.js

@@ -37,6 +37,7 @@ exports.EvidentMicrovmConstruct = void 0;
 const path = __importStar(require("path"));
 const cdk = __importStar(require("aws-cdk-lib"));
 const constructs_1 = require("constructs");
+const iam = __importStar(require("aws-cdk-lib/aws-iam"));
 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");
@@ -145,42 +146,31 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
             lifecycleTimeout: cdk.Duration.seconds(props.hookTimeoutSeconds),
             buildTimeout: cdk.Duration.seconds(IMAGE_HOOK_TIMEOUT_SECONDS),
         };
-        // Built first and with no `executionRole` prop, exactly as before this
-        // shape catalogue existed: same construct id (`Image`, frozen on the
-        // shape record — see shapes.ts), same `imageName`, same description. The
-        // construct therefore creates `Image/ExecutionRole` at its current path
-        // and current logical id — zero CloudFormation churn on the live,
-        // hand-deployed stack (D3/D9). Every additional shape below borrows this
-        // role rather than getting one of its own, which is why `validateShapes`
-        // requires the default shape to be `shapes[0]`: it must exist before any
-        // other shape can reference its execution role.
-        const defaultImage = new lambda_microvm_cdk_1.MicrovmImage(this, defaultShape.constructId, {
+        // Built first without an `executionRole` prop, so every additional shape
+        // can borrow this image's execution role. `validateShapes` requires the
+        // default shape to be `shapes[0]` because that role must exist first.
+        const defaultImage = new lambda_microvm_cdk_1.MicrovmImage(this, defaultShape.name, {
             imageName: defaultShape.imageName,
             description: defaultShape.description,
             // A local directory, so the zip is uploaded by `cdk deploy` itself and the
             // image ARN is a stack reference rather than a deploy-time input.
-            source: props.imageSource,
+            source: props.buildContextPath,
             baseImageArn: props.baseImageArn,
             baseImageVersion: props.baseImageVersion,
             memoryMiB: defaultShape.memoryMiB,
             environment: imageEnvironment,
             hooks: imageHooks,
         });
-        // WART, accepted deliberately: every additional shape's image is built
-        // with `defaultImage.executionRole`, so this role's construct path
-        // (`Image/ExecutionRole`) reads as if it belongs to just the default
-        // shape's image, when in fact it is shared by every shape. That is
-        // intentional — see D3 in the plan. Do NOT "fix" this with
-        // `overrideLogicalId`: renaming the logical id IS the CloudFormation
-        // churn this design exists to avoid (a delete-and-recreate of the role a
-        // running MicroVM has live session credentials from). The wart is one
-        // comment; the override would undo the point of D3.
+        // WART: every additional shape shares `defaultImage.executionRole`, so the
+        // role's path under the default image reads as if it belongs to one shape
+        // even though it serves all of them. Keeping one role avoids replacing a
+        // role that running MicroVMs may still have credentials from.
         const images = new Map([[defaultShape.name, defaultImage]]);
         for (const shape of additionalShapes) {
-            images.set(shape.name, new lambda_microvm_cdk_1.MicrovmImage(this, shape.constructId, {
+            images.set(shape.name, new lambda_microvm_cdk_1.MicrovmImage(this, shape.name, {
                 imageName: shape.imageName,
                 description: shape.description,
-                source: props.imageSource,
+                source: props.buildContextPath,
                 baseImageArn: props.baseImageArn,
                 baseImageVersion: props.baseImageVersion,
                 memoryMiB: shape.memoryMiB,
@@ -189,13 +179,14 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
                 hooks: imageHooks,
             }));
         }
-        // Bucket-wide rather than per-prefix (as the ECS runner's task role is):
-        // the prefix arrives at /run, so it cannot be named at synth, and one
-        // execution role is shared by every VM of every shape (D3). So a VM can
-        // read another session's credential store — acceptable within a single
-        // customer account, and what Phase 4 (#263) has to tighten when this goes
-        // multi-tenant.
-        durableState.grantReadWrite(defaultImage.executionRole);
+        // The execution role serves every image shape, so per-session state is scoped
+        // to the `runners/` root; vault credentials need only GetObject and PutObject.
+        durableState.grantReadWrite(defaultImage.executionRole, 'runners/*');
+        defaultImage.executionRole.addToPrincipalPolicy(new iam.PolicyStatement({
+            sid: 'ReadWriteCredentialVaultObjects',
+            actions: ['s3:GetObject', 's3:PutObject'],
+            resources: [durableState.arnForObjects('credential-vaults/*')],
+        }));
         // 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
@@ -235,8 +226,8 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
                 // The ARN and field name, never the value: the controller reads it from
                 // Secrets Manager at runtime, so the key is not exposed to anyone with
                 // lambda:GetFunctionConfiguration.
-                DOORBELL_SECRET_ARN: props.doorbellSecret.secretArn,
-                DOORBELL_SECRET_KEY: constants_1.DOORBELL_SECRET_KEY,
+                CONTROLLER_SIGNING_SECRET_ARN: props.controllerSigningSecret.secretArn,
+                CONTROLLER_SIGNING_SECRET_KEY: constants_1.CONTROLLER_SIGNING_SECRET_KEY,
                 MICROVM_SHAPES: shapeCatalogueJson,
                 // The role every shape's MicroVM shares (D3) — still one role, still
                 // this same expression, now documented as shared rather than singular.
@@ -251,7 +242,7 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
         // emit N near-identical policy statements and break the "exactly one
         // statement granting X" guarantees this construct's test encodes.
         defaultImage.grantRun(controller);
-        props.doorbellSecret.grantRead(controller);
+        props.controllerSigningSecret.grantRead(controller);
         const functionUrl = controller.addFunctionUrl({
             // HMAC verification of the doorbell body IS the auth, as for the ECS waker.
             authType: lambda.FunctionUrlAuthType.NONE,
@@ -261,7 +252,7 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
         // no custom resource — this branch must not run for them.
         if (props.evidentApiUrl && props.evidentRunnerId) {
             new construct_1.ImageVersionReporter(this, 'ImageVersionReporter', {
-                doorbellSecret: props.doorbellSecret,
+                controllerSigningSecret: props.controllerSigningSecret,
                 evidentApiUrl: props.evidentApiUrl,
                 evidentRunnerId: props.evidentRunnerId,
                 imageVersions: Object.fromEntries(shapes.map((shape) => [shape.name, images.get(shape.name).latestActiveImageVersion])),

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

@@ -17,10 +17,10 @@ export type DoorbellResult = {
         kind: ActionKind;
     };
 };
-export declare function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes, microvm, sleep, random, }: {
+export declare function handleDoorbell({ rawBody, signatureHeader, controllerSigningSecret, shapes, microvm, sleep, random, }: {
     rawBody: string;
     signatureHeader: string | undefined;
-    doorbellSecret: string;
+    controllerSigningSecret: string;
     shapes: ShapeCatalogue;
     microvm: MicrovmClient;
 } & Timing): Promise<DoorbellResult>;

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

@@ -174,8 +174,8 @@ async function shouldRecreateForNewerImage(doorbellRequest, shape, runningVersio
     // been deactivated, and recreating would not roll it forward. Resume.
     return compareImageVersions(running, latest) < 0;
 }
-async function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes, microvm, sleep, random, }) {
-    if (!(0, sdk_1.verifyEvidentSignature)(rawBody, signatureHeader, doorbellSecret)) {
+async function handleDoorbell({ rawBody, signatureHeader, controllerSigningSecret, shapes, microvm, sleep, random, }) {
+    if (!(0, sdk_1.verifyEvidentSignature)(rawBody, signatureHeader, controllerSigningSecret)) {
         return decide({
             statusCode: 401,
             action: 'rejected',

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

@@ -1,42 +1,17 @@
-export interface StageMicrovmImageContextOptions {
-    /**
-     * The repository baked into the image as the agent's workspace. This is the
-     * CONSUMER's repository, not Evident's — the image is a dev box for whatever
-     * codebase the agent works on. Must be a full (non-shallow) clone.
-     */
-    readonly repositoryPath: string;
-    /**
-     * `origin` of the baked repository, as the VM will see it. Must be a
-     * credential-free URL (typically `https://github.com/<owner>/<repo>.git`):
-     * this string ships inside the shared snapshot, so a token in it would be
-     * baked into every VM. The credential arrives per-VM instead.
-     */
-    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
-     * built themselves rather than whichever `dist/` happens to be present.
-     */
-    readonly templateDir?: string;
+/** The fixed directory that contains the workspace in a staged build context. */
+export declare const MICROVM_WORKSPACE_DIRECTORY = "workspace";
+export interface StageMicrovmBuildContextOptions {
+    /** The customer's directory containing their Dockerfile and COPY sources. */
+    readonly buildContextPath: string;
+    /** A full local checkout to bake into the image's `workspace/` directory. */
+    readonly workspaceRepositoryPath: string;
+    /** Credential-free origin URL carried by the baked checkout. */
+    readonly workspaceOriginUrl: string;
 }
 /**
- * Writes the build context AWS unpacks — the Dockerfile, the hook server, the
- * per-phase hook scripts, the deployment overlay and the repository — and
- * returns its path. The result is what `EvidentMicrovmConstruct`'s `imageSource`
- * takes.
+ * Stages customer-owned image inputs in a fresh temporary directory.
  *
- * 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. A caller may supply an overlay; the default is
- * deterministic no-op scripts. `repositoryPath` is the only required caller
- * input.
+ * Staging keeps the image asset hash a pure function of the workspace commit while
+ * leaving the customer in control of the Dockerfile and its build context.
  */
-export declare function stageMicrovmImageContext(options: StageMicrovmImageContextOptions): string;
+export declare function stageMicrovmBuildContext(options: StageMicrovmBuildContextOptions): string;