@evident-ai/runner-cdk 0.1.0 → 0.1.1-dev.04ef8b1

package/README.md

@@ -1,12 +1,19 @@
 # `@evident-ai/runner-cdk`
 
-A reusable AWS CDK construct for running **one scale-to-zero [Evident](https://evident.run)
-agent runner** on Fargate, in **your** AWS account, against **your** repo.
-
-The runner sleeps when nobody is talking to it: after `idleTimeoutSeconds` of inactivity
-the task scales its own service to `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.
+Reusable AWS CDK constructs for running an [Evident](https://evident.run) agent runner in
+**your** AWS account, against **your** repo. Two runner strategies:
+
+- **`EvidentScaleToZeroConstruct`** — **one scale-to-zero agent runner** on Fargate,
+  covered by the rest of this README. The runner sleeps when nobody is talking to it:
+  after `idleTimeoutSeconds` of inactivity the task scales its own service to
+  `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
+  [the AWS runner doc](https://evident.run/docs/aws-runner) for the full picture of both
+  strategies.
 
 ## What it creates
 
@@ -106,16 +113,57 @@ This construct never builds an image. Pass any `ecs.ContainerImage` — from a r
 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.
 
+## 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.
+
+The context has two halves, and this package ships the half that is ours: the Dockerfile,
+the per-phase hook scripts and the bundled hook server, published inside the tarball at
+`dist/microvm-image-context/`. The other half is **your** repository, which is baked in as
+the agent's workspace. `stageMicrovmImageContext()` puts the two together:
+
+```ts
+import {
+  EvidentMicrovmConstruct,
+  HOOKS_PORT,
+  HOOK_TIMEOUT_SECONDS,
+  stageMicrovmImageContext,
+} from '@evident-ai/runner-cdk';
+
+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'),
+  }),
+  // 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,
+});
+```
+
+Your repo does not have to be a pnpm workspace. If it commits a `pnpm-lock.yaml` the image
+pre-installs dependencies at build time (a faster first boot); if not, that step is skipped
+and the agent installs on first use.
+
 ## Status / limitations
 
-- **Publishable, but not yet published.** The package is `@evident-ai/runner-cdk`
-  (MIT), buildable to a self-contained `dist/` (`pnpm --filter @evident-ai/runner-cdk
-  build`) with no `workspace:`/`@evident/*` runtime dependency — see
-  [#957](https://github.com/sroze/evident/issues/957). The **first** `npm publish` is a
-  one-time human bootstrap step (OIDC/Trusted Publishing can't perform a package's
-  first publish, same as [#612](https://github.com/sroze/evident/issues/612) was for
-  `@evident-ai/runner-synchroniser`) and hasn't happened yet; until then this repo's own
-  consumer (`infrastructure/evident-runner`) keeps consuming it as a `workspace:*`
-  dependency, and following this guide outside this repo means working from a checkout.
+- **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.
 - **AWS/ECS-specific.** Non-AWS clouds are an open question on the epic, not a supported
   path.