@evident-ai/runner-cdk 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# `@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.
+
+## What it creates
+
+Per instantiation (one agent):
+
+- an ECS **task definition** + **Fargate service** (`<resourcePrefix>-<agentName>-<envName>`),
+- a **per-agent self-stop IAM role** the task assumes to set its own `desiredCount` to 0 —
+  scoped to that one service, so an agent can't stop its neighbours,
+- **S3 grants scoped to that agent's replica prefix** (`agents/<evidentAgentId>`), which is
+  what keeps session-DB replication single-writer,
+- a **waker Lambda** (`EvidentWaker`) that verifies an HMAC signature and the expected
+  `agent_id` before it will scale anything up.
+
+**Shared** infrastructure — the cluster, security group, task role, log group and replica
+bucket — is *not* created here. You create it once in your stack and pass it in, so one
+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.
+
+```ts
+import { EvidentScaleToZeroConstruct } from "@evident-ai/runner-cdk";
+
+const agent = new EvidentScaleToZeroConstruct(this, "MyAgent", {
+  agentName: "my-agent",
+  evidentAgentId: "00000000-0000-0000-0000-000000000000", // public agent UUID
+  gitRepo: "my-org/my-repo",
+  envName: "prod",
+
+  // Your Evident environment — no defaults, on purpose (see below).
+  evidentApiUrl: "https://api.evident.run",
+  evidentTunnelUrl: "wss://tunnel.evident.run",
+
+  idleTimeoutSeconds: 900, // 15 min
+  cpu: 2048,
+  memoryLimitMiB: 16384,
+
+  // Shared infra you own.
+  cluster,
+  securityGroup,
+  taskRole,
+  logGroup,
+  replicaBucket,
+
+  // Your image (see "The image is an input" below).
+  image: ecs.ContainerImage.fromRegistry("ghcr.io/my-org/my-runner:latest"),
+
+  // Your secrets — any Secrets Manager secret, however you manage it.
+  agentSecret,
+  availableSecretKeys: new Set(["EVIDENT_AGENT_KEY", "GH_TOKEN"]),
+  wakerSecret,
+});
+
+// The stack grants sts:AssumeRole on this, and the S3 ListBucket prefix condition.
+agent.selfStopRoleArn;
+agent.replicaPrefix;
+```
+
+For a complete working example, see `infrastructure/evident-runner/` in this repo — it is
+the construct's own dogfooding consumer.
+
+## Props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `agentName` | `string` | Lowercase slug, `/^[a-z0-9-]+$/`. Drives the service name, log stream prefix, self-stop role name. |
+| `evidentAgentId` | `string` | Public (non-secret) agent UUID. Derives the S3 replica prefix and is the only `agent_id` the waker accepts. |
+| `gitRepo` | `string` | `owner/repo` the agent clones and works on. |
+| `gitBranch` | `string?` | Defaults to `main`. |
+| `envName` | `string` | Suffixed onto the service name. |
+| `evidentApiUrl` | `string` | **Required, no default.** Passed to `evident run --endpoint`. |
+| `evidentTunnelUrl` | `string` | **Required, no default.** Passed to `evident run --tunnel`. |
+| `idleTimeoutSeconds` | `number` | Idle seconds before self-scaling to zero. Required — this construct is always scale-to-zero. |
+| `cpu` / `memoryLimitMiB` | `number` | Must be a valid Fargate combination. |
+| `resourcePrefix` | `string?` | Prefix for fixed-name resources. Defaults to `evident-selfhosted`. **Changing it on an existing deployment replaces live infrastructure** — fixed names can't be renamed in place. |
+| `extraEnvironment` | `Record<string,string>?` | Extra container env, merged over the construct's own. |
+| `cluster`, `securityGroup`, `taskRole`, `logGroup`, `replicaBucket` | interfaces | Shared infra you create and pass in. |
+| `image` | `ecs.ContainerImage` | Your runner image. |
+| `agentSecret`, `wakerSecret` | `secretsmanager.ISecret` | Any Secrets Manager secret. |
+| `availableSecretKeys` | `Set<string>` | Keys present in the agent secret. Requires `EVIDENT_AGENT_KEY` + `GH_TOKEN`; MCP credentials (`BRAVE_API_KEY`, `CLOUDFLARE_API_TOKEN`, `NEON_API_KEY`) are injected only when listed. |
+
+### Two deliberate "no default" choices
+
+- **The endpoints are required.** Defaulting them would either bake *our* dev environment
+  into your stack or silently point a mis-wired deployment at production. You state your
+  environment explicitly.
+- **The secrets are plain `secretsmanager.ISecret`.** The construct does not care how you
+  get your secrets into Secrets Manager — SOPS, an existing secret, a manual one. Nothing
+  here requires the SOPS+KMS setup this repo happens to use.
+
+### The image is an input
+
+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.
+
+## 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.
+- **AWS/ECS-specific.** Non-AWS clouds are an open question on the epic, not a supported
+  path.

package/dist/evident-scale-to-zero-construct.d.ts

@@ -0,0 +1,91 @@
+import { Construct } from 'constructs';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as ecs from 'aws-cdk-lib/aws-ecs';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as logs from 'aws-cdk-lib/aws-logs';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+export type EvidentScaleToZeroConstructProps = {
+    /**
+     * Short lowercase slug (e.g. `evident`). Drives the service name
+     * (`<resourcePrefix>-<agentName>-<envName>`), the log stream prefix, the
+     * self-stop role name, and the waker output. Must match `/^[a-z0-9-]+$/`.
+     */
+    agentName: string;
+    /**
+     * Public (non-secret) Evident agent UUID. Derives the S3 replica prefix
+     * (`agents/<id>`) and is the single expected `agent_id` the waker checks.
+     */
+    evidentAgentId: string;
+    /** GitHub `owner/repo` the agent clones and works on (e.g. `sroze/evident`). */
+    gitRepo: string;
+    /** Branch to clone. Defaults to `main` when omitted. */
+    gitBranch?: string;
+    /**
+     * Idle seconds before the runner self-scales its service to `desiredCount 0`
+     * (scale-to-zero). REQUIRED — this construct is always scale-to-zero.
+     */
+    idleTimeoutSeconds: number;
+    /** Fargate vCPU units (e.g. 2048 = 2 vCPU). */
+    cpu: number;
+    /** Fargate memory (MiB). Must be a valid Fargate combination for `cpu`. */
+    memoryLimitMiB: number;
+    /**
+     * Prefix for all FIXED-name physical resources this construct creates
+     * (service, log stream prefix, self-stop role). Defaults to
+     * {@link DEFAULT_RESOURCE_PREFIX}. Fixed names can't be renamed in place —
+     * changing this for an existing deployment replaces live infrastructure.
+     */
+    resourcePrefix?: string;
+    /** Environment slug, suffixed onto the service name (`<resourcePrefix>-<agentName>-<envName>`). */
+    envName: string;
+    /**
+     * Evident API endpoint the runner talks to (passed to `evident run` as
+     * `--endpoint`). No default — every adopter must choose their own environment.
+     */
+    evidentApiUrl: string;
+    /**
+     * Evident tunnel endpoint the runner connects to (passed to `evident run` as
+     * `--tunnel`). No default — every adopter must choose their own environment.
+     */
+    evidentTunnelUrl: string;
+    /**
+     * Extra container environment variables, merged on top of the construct's own
+     * (e.g. a dev-box `DATABASE_URL`). Values here win over the construct's own.
+     */
+    extraEnvironment?: Record<string, string>;
+    cluster: ecs.ICluster;
+    securityGroup: ec2.ISecurityGroup;
+    taskRole: iam.IRole;
+    logGroup: logs.ILogGroup;
+    replicaBucket: s3.IBucket;
+    image: ecs.ContainerImage;
+    /**
+     * Container secrets. Requires EVIDENT_AGENT_KEY + GH_TOKEN; the MCP
+     * credentials BRAVE_API_KEY / CLOUDFLARE_API_TOKEN / NEON_API_KEY are injected
+     * only if present (see availableSecretKeys).
+     */
+    agentSecret: secretsmanager.ISecret;
+    /** Key names present in the agent secret; gates the optional MCP creds. */
+    availableSecretKeys: Set<string>;
+    /** Waker secret (EVIDENT_WAKE_SECRET), consumed by the waker at runtime. */
+    wakerSecret: secretsmanager.ISecret;
+};
+/**
+ * One scale-to-zero Evident agent on Fargate: a task-def + `Runner` container +
+ * Fargate service, a per-agent self-stop role, S3 prefix grants, and a waker
+ * Lambda. Instantiate once per agent; the stack owns the shared infra.
+ *
+ * The agent self-stops (`desiredCount 0`) on a clean idle exit and is woken on
+ * demand by its waker. Exposes {@link selfStopRoleArn} and {@link replicaPrefix}
+ * so the stack can grant `sts:AssumeRole` and the `s3:ListBucket` prefix condition.
+ */
+export declare class EvidentScaleToZeroConstruct extends Construct {
+    /** ARN of the per-agent self-stop role (the stack grants AssumeRole on it). */
+    readonly selfStopRoleArn: string;
+    /** This agent's S3 replica prefix (`agents/<evidentAgentId>`). */
+    readonly replicaPrefix: string;
+    /** The created Fargate service. */
+    readonly service: ecs.FargateService;
+    constructor(scope: Construct, id: string, props: EvidentScaleToZeroConstructProps);
+}

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

@@ -0,0 +1,203 @@
+"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.EvidentScaleToZeroConstruct = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const ec2 = __importStar(require("aws-cdk-lib/aws-ec2"));
+const ecs = __importStar(require("aws-cdk-lib/aws-ecs"));
+const iam = __importStar(require("aws-cdk-lib/aws-iam"));
+const construct_1 = require("./waker/construct");
+/** Current fixed value of `resourcePrefix`, kept as the default so an adopter
+ *  omitting the prop reproduces today's physical names exactly. */
+const DEFAULT_RESOURCE_PREFIX = 'evident-selfhosted';
+/**
+ * One scale-to-zero Evident agent on Fargate: a task-def + `Runner` container +
+ * Fargate service, a per-agent self-stop role, S3 prefix grants, and a waker
+ * Lambda. Instantiate once per agent; the stack owns the shared infra.
+ *
+ * The agent self-stops (`desiredCount 0`) on a clean idle exit and is woken on
+ * demand by its waker. Exposes {@link selfStopRoleArn} and {@link replicaPrefix}
+ * so the stack can grant `sts:AssumeRole` and the `s3:ListBucket` prefix condition.
+ */
+class EvidentScaleToZeroConstruct extends constructs_1.Construct {
+    /** ARN of the per-agent self-stop role (the stack grants AssumeRole on it). */
+    selfStopRoleArn;
+    /** This agent's S3 replica prefix (`agents/<evidentAgentId>`). */
+    replicaPrefix;
+    /** The created Fargate service. */
+    service;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const { agentName, evidentAgentId, gitRepo, gitBranch, idleTimeoutSeconds, cpu, memoryLimitMiB, resourcePrefix = DEFAULT_RESOURCE_PREFIX, envName, evidentApiUrl, evidentTunnelUrl, extraEnvironment, cluster, securityGroup, taskRole, logGroup, replicaBucket, image, agentSecret, availableSecretKeys, wakerSecret, } = props;
+        this.replicaPrefix = `agents/${evidentAgentId}`;
+        // A plain STRING (not service.serviceName) so the container env is static and
+        // has no construct-ordering dependency on the service.
+        const serviceName = `${resourcePrefix}-${agentName}-${envName}`;
+        const taskDefinition = new ecs.FargateTaskDefinition(this, 'TaskDef', {
+            cpu,
+            memoryLimitMiB,
+            taskRole,
+            // 50 GiB: local disk holds the cloned monorepo, node_modules, and
+            // opencode.db. Fargate bills only for storage above the free 20 GiB.
+            ephemeralStorageGiB: 50,
+        });
+        // This agent's single service ARN — used by both the waker and the self-stop
+        // role. Built from CFN pseudo-params so it's synth-safe and available before
+        // the service resource exists.
+        const serviceArn = `arn:aws:ecs:${cdk.Stack.of(this).region}:${cdk.Stack.of(this).account}:service/${cluster.clusterName}/${serviceName}`;
+        // Per-agent self-stop role scoped to ONLY this service ARN, trusting the task
+        // role so the container can assume it to scale itself to 0 on idle. MUST run
+        // before addContainer so EVIDENT_SELFSTOP_ROLE_ARN lands in the container def.
+        const selfStopRole = new iam.Role(this, 'SelfStopRole', {
+            roleName: `${resourcePrefix}-selfstop-${agentName}`,
+            assumedBy: new iam.ArnPrincipal(taskRole.roleArn),
+            description: "Per-agent self-stop: UpdateService on ONLY this agent's service.",
+            maxSessionDuration: cdk.Duration.hours(1),
+        });
+        selfStopRole.addToPolicy(new iam.PolicyStatement({
+            sid: 'SelfStopOwnService',
+            effect: iam.Effect.ALLOW,
+            actions: ['ecs:UpdateService', 'ecs:DescribeServices'],
+            resources: [serviceArn],
+        }));
+        this.selfStopRoleArn = selfStopRole.roleArn;
+        const environment = {
+            OPENCODE_PORT: '4096',
+            HOME: '/home/runner',
+            // Selects the Evident environment (passed to `evident run` as
+            // --endpoint / --tunnel). The agent is resolved from EVIDENT_AGENT_KEY.
+            EVIDENT_API_URL: evidentApiUrl,
+            EVIDENT_TUNNEL_URL: evidentTunnelUrl,
+            // Litestream replica target (read by packages/runner-synchroniser, which
+            // generates /etc/evident/litestream.yml at boot).
+            LITESTREAM_BUCKET: replicaBucket.bucketName,
+            LITESTREAM_PREFIX: this.replicaPrefix,
+            AWS_REGION: cdk.Stack.of(this).region,
+            GIT_REPO: gitRepo,
+            GIT_BRANCH: gitBranch ?? 'main',
+            // Scale-to-zero self-stop inputs (the entrypoint uses these to scale to 0).
+            EVIDENT_IDLE_TIMEOUT_SECONDS: String(idleTimeoutSeconds),
+            // Auto-cleanup (issue #190): `evident run` reads this directly and, once a
+            // retention rule is set, sweeps OpenCode sessions idle longer than the
+            // window (protected/active sessions are never touched). Tightened from 7d
+            // to 24h per #537: at 7d, opencode.db was observed growing ~11x (77 MB ->
+            // 849 MB) in ~24h, so 7d was far too permissive at the observed growth
+            // rate. 24h is a tighter mitigation while the growth's root cause is
+            // investigated (see also the OPENCODE_VERSION pin above and the
+            // [memwatch] telemetry in entrypoint.sh). Sweep runs on the default 1h
+            // interval and never touches a protected/active session.
+            EVIDENT_SESSION_CLEANUP_MAX_AGE: '24h',
+            CLUSTER: cluster.clusterName,
+            SERVICE: serviceName,
+            EVIDENT_SELFSTOP_ROLE_ARN: selfStopRole.roleArn,
+            // Adopter-supplied extras (e.g. this repo's dev-box DATABASE_URL). Spread
+            // LAST so an adopter can override any key above if they ever need to.
+            ...extraEnvironment,
+        };
+        const secrets = {
+            EVIDENT_AGENT_KEY: ecs.Secret.fromSecretsManager(agentSecret, 'EVIDENT_AGENT_KEY'),
+            GH_TOKEN: ecs.Secret.fromSecretsManager(agentSecret, 'GH_TOKEN'),
+        };
+        // Optional MCP creds (consumed by opencode.runner.jsonc): BRAVE_API_KEY →
+        // brave-search, CLOUDFLARE_API_TOKEN → the Cloudflare MCP, NEON_API_KEY →
+        // the Neon MCP (read-only). Injected only if present in the SOPS file — a
+        // referenced-but-absent key fails ECS task startup, so an operator can
+        // enable an MCP by just adding its key + redeploy.
+        for (const key of ['BRAVE_API_KEY', 'CLOUDFLARE_API_TOKEN', 'NEON_API_KEY']) {
+            if (availableSecretKeys.has(key)) {
+                secrets[key] = ecs.Secret.fromSecretsManager(agentSecret, key);
+            }
+        }
+        // Container name pinned to "Runner": operator `execute-command --container
+        // Runner` examples rely on it.
+        taskDefinition.addContainer('Runner', {
+            image,
+            logging: ecs.LogDrivers.awsLogs({
+                streamPrefix: resourcePrefix,
+                logGroup,
+            }),
+            // Fargate max (120s, vs the 30s default) so the entrypoint's graceful
+            // shutdown can land Litestream's FINAL sync to S3 before ECS SIGKILLs the
+            // task — otherwise the last session writes are lost on deploy/stop.
+            stopTimeout: cdk.Duration.seconds(120),
+            environment,
+            secrets,
+        });
+        // 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}/*`);
+        this.service = new ecs.FargateService(this, 'Service', {
+            cluster,
+            taskDefinition,
+            serviceName,
+            // Starts at 1; the runner self-scales to 0 on idle. A deploy resets this to
+            // 1 (CFN), waking a sleeping agent that then re-naps (benign).
+            desiredCount: 1,
+            enableExecuteCommand: true,
+            assignPublicIp: true,
+            vpcSubnets: { subnetType: ec2.SubnetType.PUBLIC },
+            securityGroups: [securityGroup],
+            // No spare task during deploys (preserves single-writer-per-prefix).
+            minHealthyPercent: 0,
+            maxHealthyPercent: 100,
+            circuitBreaker: { rollback: true },
+        });
+        // Waker: reads the wake secret at runtime, scoped to this service ARN only.
+        new construct_1.EvidentWaker(this, 'Waker', {
+            wakeSecret: wakerSecret,
+            agentName,
+            expectedAgentId: evidentAgentId,
+            cluster: cluster.clusterName,
+            service: serviceName,
+            serviceArn,
+        });
+        // --- Per-agent outputs (cluster/log group/bucket are shared) ------------
+        const pascalName = agentName.charAt(0).toUpperCase() + agentName.slice(1);
+        new cdk.CfnOutput(this, `${pascalName}ServiceName`, {
+            description: `ECS service name for the ${agentName} agent`,
+            value: this.service.serviceName,
+        });
+        new cdk.CfnOutput(this, `${pascalName}ExecCommandHint`, {
+            description: `How to 'SSH' into the running ${agentName} runner task`,
+            value: [
+                `aws ecs list-tasks --cluster ${cluster.clusterName} --service-name ${serviceName}`,
+                'then:',
+                `aws ecs execute-command --cluster ${cluster.clusterName} --task <task-id> --container Runner --interactive --command /bin/bash`,
+            ].join(' '),
+        });
+    }
+}
+exports.EvidentScaleToZeroConstruct = EvidentScaleToZeroConstruct;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { EvidentScaleToZeroConstruct, type EvidentScaleToZeroConstructProps, } from './evident-scale-to-zero-construct';
+export { EvidentWaker, type EvidentWakerProps } from './waker/construct';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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");
+Object.defineProperty(exports, "EvidentWaker", { enumerable: true, get: function () { return construct_1.EvidentWaker; } });

package/dist/waker/construct.d.ts

@@ -0,0 +1,30 @@
+import { Construct } from 'constructs';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+export type EvidentWakerProps = {
+    /**
+     * The agent's secret. The waker fetches `EVIDENT_WAKE_SECRET` at RUNTIME
+     * (granted GetSecretValue on its ARN); only the ARN + field name enter the
+     * Lambda env, never the value.
+     */
+    wakeSecret: secretsmanager.ISecret;
+    /** Slug of the agent this waker serves (e.g. `evident`). Namespaces the output. */
+    agentName: string;
+    /** Evident's public `agent_id`; the handler checks the wake payload against it. */
+    expectedAgentId: string;
+    /** ECS cluster name holding the agent's service. */
+    cluster: string;
+    /** ECS service name to scale to `desiredCount 1` on a verified wake. */
+    service: string;
+    /** ARN of the agent's single service; the Lambda role is scoped to exactly it. */
+    serviceArn: string;
+};
+/**
+ * A per-agent waker Lambda: a Function URL (auth is HMAC verification of the wake
+ * body, NOT IAM) that scales ONE agent's ECS service to `desiredCount 1`. Evident
+ * POSTs a signed agent-event webhook (`agent.message_queued` / `agent.wake_requested`)
+ * here when a disconnected agent needs to be woken. The Function URL is emitted as a
+ * CfnOutput for the dashboard.
+ */
+export declare class EvidentWaker extends Construct {
+    constructor(scope: Construct, id: string, props: EvidentWakerProps);
+}

package/dist/waker/construct.js

@@ -0,0 +1,107 @@
+"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.EvidentWaker = 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"));
+/** The JSON field name inside the wake secret; the handler fetches it at runtime. */
+const WAKE_SECRET_KEY = 'EVIDENT_WAKE_SECRET';
+/**
+ * A per-agent waker Lambda: a Function URL (auth is HMAC verification of the wake
+ * body, NOT IAM) that scales ONE agent's ECS service to `desiredCount 1`. Evident
+ * POSTs a signed agent-event webhook (`agent.message_queued` / `agent.wake_requested`)
+ * here when a disconnected agent needs to be woken. The Function URL is emitted as a
+ * CfnOutput for the dashboard.
+ */
+class EvidentWaker extends constructs_1.Construct {
+    constructor(scope, id, props) {
+        super(scope, id);
+        const { wakeSecret, agentName, expectedAgentId, cluster, service, serviceArn } = props;
+        const handler = new lambda.Function(this, 'Function', {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            // Pre-bundled at PACKAGE build time (`pnpm --filter @evident-ai/runner-cdk
+            // build`, see scripts/build.ts), not at synth time: esbuild inlines
+            // @evident/webhook-signature's HMAC verifier into
+            // dist/waker-lambda/handler.js, so neither this package's published npm
+            // artifact (which ships dist/ already built) nor a consuming app needs
+            // that private workspace package, or esbuild, on synth's PATH. Requires
+            // a build before synth when consuming this package via `workspace:*` —
+            // see infrastructure/evident-runner's README "local gate".
+            //
+            // Resolved from the PACKAGE ROOT (../.. ), not `__dirname` directly:
+            // `__dirname` is `dist/waker` at runtime (compiled) but `src/waker` when
+            // this file runs straight off source via ts-node (this package's own
+            // tests) — both are exactly two directories below the package root, so
+            // this resolves to the same `dist/waker-lambda/` either way. A
+            // DIRECTORY, not the bundled file directly: `Code.fromAsset` on a lone
+            // non-zip file fails at synth with `AssetMustBeZipFile`.
+            code: lambda.Code.fromAsset(path.join(__dirname, '..', '..', 'dist', 'waker-lambda')),
+            handler: 'handler.handler',
+            memorySize: 128,
+            timeout: cdk.Duration.seconds(10),
+            environment: {
+                CLUSTER: cluster,
+                SERVICE: service,
+                EXPECTED_AGENT_ID: expectedAgentId,
+                // Non-secret: the secret's ARN + field name (the handler fetches the value
+                // at runtime).
+                WAKE_SECRET_ARN: wakeSecret.secretArn,
+                WAKE_SECRET_KEY,
+            },
+        });
+        // Runtime GetSecretValue on ONLY this agent's wake secret.
+        wakeSecret.grantRead(handler);
+        // Scale ONLY this agent's single service (beyond the default Logs role).
+        handler.addToRolePolicy(new iam.PolicyStatement({
+            sid: 'WakeRunnerService',
+            effect: iam.Effect.ALLOW,
+            actions: ['ecs:UpdateService', 'ecs:DescribeServices'],
+            resources: [serviceArn],
+        }));
+        const functionUrl = handler.addFunctionUrl({
+            // HMAC verification in the handler IS the auth — no IAM on the URL.
+            authType: lambda.FunctionUrlAuthType.NONE,
+        });
+        const pascalName = agentName.charAt(0).toUpperCase() + agentName.slice(1);
+        new cdk.CfnOutput(scope, `WakerFunctionUrl${pascalName}`, {
+            description: `POST target for Evident's signed agent-event webhook (agent.message_queued / agent.wake_requested, HMAC-verified) for the ${agentName} agent.`,
+            value: functionUrl.url,
+        });
+    }
+}
+exports.EvidentWaker = EvidentWaker;

package/dist/waker-lambda/handler.js

@@ -0,0 +1,160 @@
+"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/waker/handler.ts
+var handler_exports = {};
+__export(handler_exports, {
+  handleWake: () => handleWake,
+  handler: () => handler
+});
+module.exports = __toCommonJS(handler_exports);
+var import_client_ecs = require("@aws-sdk/client-ecs");
+var import_client_secrets_manager = require("@aws-sdk/client-secrets-manager");
+
+// ../webhook-signature/src/verify-wake-signature.ts
+var import_node_crypto = require("node:crypto");
+function verifyWakeSignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader || !secret) {
+    return false;
+  }
+  const provided = signatureHeader.startsWith("sha256=") ? signatureHeader.slice("sha256=".length) : signatureHeader;
+  if (provided.length === 0) {
+    return false;
+  }
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(rawBody).digest("hex");
+  const providedBuffer = Buffer.from(provided, "hex");
+  const expectedBuffer = Buffer.from(expected, "hex");
+  if (providedBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+  return (0, import_node_crypto.timingSafeEqual)(providedBuffer, expectedBuffer);
+}
+
+// src/waker/handler.ts
+var ACCEPTED_WAKE_EVENT_TYPES = ["agent.message_queued", "agent.wake_requested"];
+function jsonResponse(statusCode, message) {
+  return {
+    statusCode,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ message })
+  };
+}
+async function handleWake({
+  rawBody,
+  signatureHeader,
+  wakeSecret,
+  expectedAgentId,
+  cluster,
+  service,
+  ecs
+}) {
+  if (!verifyWakeSignature(rawBody, signatureHeader, wakeSecret)) {
+    const { statusCode: statusCode2, body: body2 } = jsonResponse(401, "invalid signature");
+    return { statusCode: statusCode2, body: body2, calledUpdateService: false };
+  }
+  let agentId;
+  let eventType;
+  try {
+    ({ agent_id: agentId, type: eventType } = JSON.parse(rawBody));
+  } catch {
+    const { statusCode: statusCode2, body: body2 } = jsonResponse(400, "invalid JSON body");
+    return { statusCode: statusCode2, body: body2, calledUpdateService: false };
+  }
+  if (eventType !== void 0 && !ACCEPTED_WAKE_EVENT_TYPES.includes(eventType)) {
+    console.warn("wake unsupported event type");
+    const { statusCode: statusCode2, body: body2 } = jsonResponse(400, "unsupported event type");
+    return { statusCode: statusCode2, body: body2, calledUpdateService: false };
+  }
+  if (agentId !== expectedAgentId) {
+    console.warn("wake agent_id mismatch");
+    const { statusCode: statusCode2, body: body2 } = jsonResponse(404, "unknown agent_id");
+    return { statusCode: statusCode2, body: body2, calledUpdateService: false };
+  }
+  try {
+    await ecs.updateService(cluster, service);
+  } catch (error) {
+    console.error("UpdateService failed for", service, error);
+    const { statusCode: statusCode2, body: body2 } = jsonResponse(500, "failed to wake service");
+    return { statusCode: statusCode2, body: body2, calledUpdateService: true };
+  }
+  const { statusCode, body } = jsonResponse(200, "waking");
+  return { statusCode, body, calledUpdateService: true };
+}
+var ecsClient = new import_client_ecs.ECSClient({});
+var secretsClient = new import_client_secrets_manager.SecretsManagerClient({});
+var runtimeEcs = {
+  async updateService(cluster, service) {
+    await ecsClient.send(new import_client_ecs.UpdateServiceCommand({ cluster, service, desiredCount: 1 }));
+  }
+};
+var cachedWakeSecret;
+async function fetchWakeSecret(arn, key) {
+  const { SecretString } = await secretsClient.send(new import_client_secrets_manager.GetSecretValueCommand({ SecretId: arn }));
+  if (!SecretString) {
+    throw new Error("wake secret has no SecretString");
+  }
+  const parsed = JSON.parse(SecretString);
+  const value = parsed[key];
+  if (typeof value !== "string") {
+    throw new Error(`wake secret is missing the '${key}' field`);
+  }
+  return value;
+}
+function getWakeSecret(arn, key) {
+  if (!cachedWakeSecret) {
+    cachedWakeSecret = fetchWakeSecret(arn, key);
+  }
+  return cachedWakeSecret;
+}
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`missing required env var ${name}`);
+  }
+  return value;
+}
+var handler = async (event) => {
+  const cluster = requireEnv("CLUSTER");
+  const service = requireEnv("SERVICE");
+  const expectedAgentId = requireEnv("EXPECTED_AGENT_ID");
+  const wakeSecretArn = requireEnv("WAKE_SECRET_ARN");
+  const wakeSecretKey = requireEnv("WAKE_SECRET_KEY");
+  const rawBody = event.isBase64Encoded ? Buffer.from(event.body ?? "", "base64").toString("utf8") : event.body ?? "";
+  const signatureHeader = event.headers?.["x-evident-signature"];
+  const wakeSecret = await getWakeSecret(wakeSecretArn, wakeSecretKey);
+  const { statusCode, body } = await handleWake({
+    rawBody,
+    signatureHeader,
+    wakeSecret,
+    expectedAgentId,
+    cluster,
+    service,
+    ecs: runtimeEcs
+  });
+  return {
+    statusCode,
+    headers: { "content-type": "application/json" },
+    body
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handleWake,
+  handler
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@evident-ai/runner-cdk",
+  "version": "0.1.0",
+  "description": "Reusable CDK construct for a single scale-to-zero Evident agent runner on Fargate (task + service + per-agent self-stop role + waker Lambda). Instantiate once per agent from your own stack.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "ts-node scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --require ts-node/register 'src/**/*.test.ts'",
+    "format": "prettier --write 'src/**/*.ts'",
+    "lint": "eslint 'src/**/*.ts' --max-warnings=0"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.240.0",
+    "constructs": "^10.5.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-ecs": "^3.682.0",
+    "@aws-sdk/client-secrets-manager": "^3.682.0",
+    "@evident/webhook-signature": "workspace:*",
+    "@types/node": "^22",
+    "aws-cdk-lib": "^2.240.0",
+    "constructs": "^10.5.0",
+    "esbuild": "^0.25.2",
+    "prettier": "^3.3.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sroze/evident.git",
+    "directory": "packages/runner-cdk"
+  },
+  "homepage": "https://evident.run",
+  "author": "Evident <contact@evident.run>",
+  "license": "MIT"
+}