@evident-ai/runner-cdk 0.1.1-dev.da70cd4 → 3.4.1-dev.1856549

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 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.
 
 ## What it creates
 
@@ -27,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";
@@ -104,18 +112,67 @@ 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
+
+`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 path from 'node:path';
+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,
+  runnerSecret,
+  runnerOpencodeConfigPath: 'opencode.runner.jsonc',
+});
+```
+
+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.
+
+| MicroVM prop | Omitted behavior |
+| --- | --- |
+| `runnerSecret` | No GitHub or MCP credentials are exported at `/run`. |
+| `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. |
 
 ## 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). 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.