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

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

@@ -61,13 +61,25 @@ export type EvidentScaleToZeroConstructProps = {
     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).
+     * Container secrets. `availableSecretKeys` are injected by name; EVIDENT_AGENT_KEY
+     * and GH_TOKEN remain available to external adopters that do not enumerate keys.
+     *
+     * `agentSecret` always supplies EVIDENT_AGENT_KEY. When `capabilitySecret` is
+     * ALSO given (#1868 WI-2), every capability key (GH_TOKEN included) is injected
+     * from THAT secret instead, and `availableSecretKeys` is ignored — the two
+     * deploy targets (this one and the MicroVM stack) then read the same
+     * capability keys from the same shared secret rather than each carrying its
+     * own copy. When `capabilitySecret` is absent, behavior is unchanged: GH_TOKEN
+     * plus every `availableSecretKeys` entry, all from `agentSecret` — an external
+     * adopter passing only `agentSecret`/`availableSecretKeys` is unaffected.
      */
     agentSecret: secretsmanager.ISecret;
-    /** Key names present in the agent secret; gates the optional MCP creds. */
+    /** Key names present in the agent secret. Every listed key is injected into the container. */
     availableSecretKeys: Set<string>;
+    /** The shared capability secret (#1868 WI-2). See `agentSecret`'s doc above. */
+    capabilitySecret?: secretsmanager.ISecret;
+    /** Key names present in `capabilitySecret`. Ignored when `capabilitySecret` is absent. */
+    capabilityKeys?: Set<string>;
     /** Waker secret (EVIDENT_WAKE_SECRET), consumed by the waker at runtime. */
     wakerSecret: secretsmanager.ISecret;
 };

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

@@ -61,7 +61,7 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
     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;
+        const { agentName, evidentAgentId, gitRepo, gitBranch, idleTimeoutSeconds, cpu, memoryLimitMiB, resourcePrefix = DEFAULT_RESOURCE_PREFIX, envName, evidentApiUrl, evidentTunnelUrl, extraEnvironment, cluster, securityGroup, taskRole, logGroup, replicaBucket, image, agentSecret, availableSecretKeys, capabilitySecret, capabilityKeys, 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.
@@ -101,7 +101,7 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             // --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
+            // Litestream replica target (read by runner/synchroniser, which
             // generates /etc/evident/litestream.yml at boot).
             LITESTREAM_BUCKET: replicaBucket.bucketName,
             LITESTREAM_PREFIX: this.replicaPrefix,
@@ -115,10 +115,9 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             // 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.
+            // rate. 24h is the tighter mitigation that came out of that (see also the
+            // OPENCODE_VERSION pin above). 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,
@@ -128,16 +127,22 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             ...extraEnvironment,
         };
         const secrets = {
+            // Identifies the runner to Evident. Always agentSecret — capabilitySecret
+            // never carries this key (#1868 WI-2: the two are a deliberate split, not
+            // a duplication of the same data).
             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)) {
+        if (capabilitySecret !== undefined) {
+            for (const key of capabilityKeys ?? new Set()) {
+                secrets[key] = ecs.Secret.fromSecretsManager(capabilitySecret, key);
+            }
+        }
+        else {
+            // Legacy shape, unchanged: GH_TOKEN (required to clone this construct's
+            // workspace at boot) plus every availableSecretKeys entry, all from
+            // agentSecret — what every external adopter still gets.
+            secrets.GH_TOKEN = ecs.Secret.fromSecretsManager(agentSecret, 'GH_TOKEN');
+            for (const key of availableSecretKeys) {
                 secrets[key] = ecs.Secret.fromSecretsManager(agentSecret, key);
             }
         }

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

@@ -0,0 +1,129 @@
+"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/microvm/image-version-reporter/handler.ts
+var handler_exports = {};
+__export(handler_exports, {
+  handleImageVersionReport: () => handleImageVersionReport,
+  handler: () => handler
+});
+module.exports = __toCommonJS(handler_exports);
+var import_node_crypto = require("node:crypto");
+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) {
+  const { SecretString } = await secrets.send(new import_client_secrets_manager.GetSecretValueCommand({ SecretId: secretArn }));
+  if (!SecretString) {
+    throw new Error(`doorbell 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`);
+  }
+  return value;
+}
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`missing required env var ${name}`);
+  }
+  return value;
+}
+function readImageVersions(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("imageVersions must be an object");
+  }
+  return Object.entries(value).map(([shape, imageVersion]) => {
+    if (typeof imageVersion !== "string") {
+      throw new Error(`imageVersions.${shape} must be a string`);
+    }
+    return { shape, image_version: imageVersion };
+  });
+}
+function response() {
+  return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
+}
+var runtimeDependencies = {
+  getSecret: fetchDoorbellSecret,
+  fetch: globalThis.fetch
+};
+async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
+  if (event.RequestType === "Delete") {
+    return response();
+  }
+  let runnerId = "unknown";
+  let versions = [];
+  let responseStatus;
+  try {
+    versions = readImageVersions(event.ResourceProperties?.imageVersions);
+    const config = getConfig();
+    runnerId = config.evidentRunnerId;
+    const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+    const body = JSON.stringify({
+      type: "runner.microvm_image_versions_reported",
+      versions
+    });
+    const signature = (0, import_node_crypto.createHmac)("sha256", secret).update(body).digest("hex");
+    const url = `${config.evidentApiUrl.replace(/\/+$/, "")}/v1/runners/${encodeURIComponent(
+      runnerId
+    )}/microvm-image-versions`;
+    const result = await dependencies.fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-evident-signature": signature
+      },
+      body,
+      signal: AbortSignal.timeout(REPORT_TIMEOUT_MS)
+    });
+    responseStatus = result.status;
+    console.log("runner.microvm_image_versions_reported", {
+      runnerId,
+      versions,
+      status: result.status
+    });
+    if (!result.ok) {
+      throw new Error(`Evident returned HTTP ${result.status}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn("MicroVM image version report failed", {
+      operation: event.RequestType,
+      runnerId,
+      versions,
+      ...responseStatus === void 0 ? {} : { status: responseStatus },
+      error: message
+    });
+  }
+  return response();
+}
+var handler = (event) => handleImageVersionReport(event, () => ({
+  doorbellSecretArn: requireEnv("DOORBELL_SECRET_ARN"),
+  doorbellSecretKey: requireEnv("DOORBELL_SECRET_KEY"),
+  evidentApiUrl: requireEnv("EVIDENT_API_URL"),
+  evidentRunnerId: requireEnv("EVIDENT_RUNNER_ID")
+}));
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handleImageVersionReport,
+  handler
+});

package/dist/index.d.ts

@@ -1,2 +1,6 @@
 export { EvidentScaleToZeroConstruct, type EvidentScaleToZeroConstructProps, } from './evident-scale-to-zero-construct';
 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';

package/dist/index.js

@@ -1,7 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EvidentWaker = exports.EvidentScaleToZeroConstruct = void 0;
+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;
 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; } });
+var construct_2 = require("./microvm/construct");
+Object.defineProperty(exports, "EvidentMicrovmConstruct", { enumerable: true, get: function () { return construct_2.EvidentMicrovmConstruct; } });
+var shapes_1 = require("./microvm/shapes");
+Object.defineProperty(exports, "MICROVM_SHAPES", { enumerable: true, get: function () { return shapes_1.MICROVM_SHAPES; } });
+Object.defineProperty(exports, "validateShapes", { enumerable: true, get: function () { return shapes_1.validateShapes; } });
+var constants_1 = require("./microvm/constants");
+Object.defineProperty(exports, "MICROVM_MAX_RUN_SECONDS", { enumerable: true, get: function () { return constants_1.MICROVM_MAX_RUN_SECONDS; } });
+// The two values a consumer MUST pass to `EvidentMicrovmConstruct` for them
+// to match the published image they were baked into (#1528).
+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; } });

package/dist/microvm/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const HOOKS_PORT = 8080;
+export declare const HOOKS_DIR = "/etc/evident/hooks";
+export declare const HOOK_TIMEOUT_SECONDS = 60;
+export declare const RUN_HOOK_PAYLOAD_MAX_BYTES = 16384;
+export declare const SUSPENDING_POLL_ATTEMPTS = 4;
+export declare const SUSPENDING_POLL_INTERVAL_MS = 500;
+export declare const MICROVM_MAX_RUN_SECONDS = 28800;

package/dist/microvm/constants.js

@@ -0,0 +1,34 @@
+"use strict";
+// Shared literals for the MicroVM controller and for the image it launches.
+// Every module imports from here rather than restating a value that must match
+// across them. The image template pins matching copies, guarded by
+// `microvm/image/dockerfile.test.ts`.
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+// MUST pass the value it was baked with — the construct's own docstring warns
+// that a mismatch means AWS probes a port nothing binds.
+exports.HOOKS_PORT = 8080;
+// One executable per lifecycle phase. A phase with no script is a no-op, which
+// is why the image ships none for `ready` or `validate`: nothing Evident-specific
+// may run before the snapshot, so there is nothing for them to do.
+exports.HOOKS_DIR = '/etc/evident/hooks';
+// Seconds AWS allows a Run/Resume/Suspend/Terminate hook, passed to the
+// construct as `hookTimeoutSeconds`. Exported for the same reason as
+// `HOOKS_PORT`: the hooks are built against it.
+exports.HOOK_TIMEOUT_SECONDS = 60;
+// AWS caps `runHookPayload` at 16 KiB; anything larger is rejected at its API,
+// so the controller checks it before spending a call.
+exports.RUN_HOOK_PAYLOAD_MAX_BYTES = 16384;
+// Worst-case poll (attempts × interval ≈ 2 s) must fit the controller Lambda's 8 s
+// timeout alongside the retry backoff.
+exports.SUSPENDING_POLL_ATTEMPTS = 4;
+exports.SUSPENDING_POLL_INTERVAL_MS = 500;
+// AWS's non-adjustable ceiling on a single MicroVM run, passed as
+// `RunMicrovmCommand`'s `maximumDurationInSeconds`. The version pruner reuses it
+// as its post-deactivation staging delay: once a version has been INACTIVE for
+// longer than any VM can possibly still be running, no VM started before the
+// deactivation can outlive it. The two MUST move together.
+exports.MICROVM_MAX_RUN_SECONDS = 28800;

package/dist/microvm/construct.d.ts

@@ -0,0 +1,105 @@
+import { Construct } from 'constructs';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+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.
+     */
+    readonly imageSource: string;
+    /**
+     * ARN of the Lambda-managed base MicroVM image, from
+     * `aws lambda-microvms list-managed-microvm-images`. A string, not a `CfnParameter`
+     * built here: the caller creates the parameter at ITS OWN stack scope
+     * (preserving its logical id) and passes its resolved value down — a
+     * construct must not mint parameters into a consumer's stack.
+     */
+    readonly baseImageArn: string;
+    /**
+     * Version of the Lambda-managed base MicroVM image, from
+     * `aws lambda-microvms list-managed-microvm-images`. See `baseImageArn` for why this
+     * is a plain string.
+     */
+    readonly baseImageVersion: string;
+    /**
+     * The shape catalogue to build one image per shape from (#723). Defaults to
+     * `MICROVM_SHAPES`, the committed catalogue. Overridable so a caller can
+     * synth a local multi-shape template without mutating that module
+     * constant.
+     */
+    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
+     * 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;
+    /**
+     * Optional runner secret whose JSON values are exported by `/run`. Omitting it
+     * leaves GitHub and MCP credentials unavailable to a generic consumer.
+     */
+    readonly runnerSecret?: secretsmanager.ISecret;
+    /**
+     * Optional runner OpenCode overlay. Absolute paths are image paths; relative
+     * paths are resolved from the baked workspace by the `/run` hook.
+     */
+    readonly runnerOpencodeConfigPath?: string;
+    /** Optional git identity the `/run` hook configures for agent commits. */
+    readonly gitUserName?: string;
+    /** Optional git email the `/run` hook configures for agent commits. */
+    readonly gitUserEmail?: string;
+    /**
+     * 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.
+     */
+    readonly hooksPort: number;
+    /**
+     * Seconds AWS waits for a Run/Resume/Suspend/Terminate hook to answer,
+     * before the image build itself times out (`IMAGE_HOOK_TIMEOUT_SECONDS`,
+     * fixed at 600 s — building the snapshot is a different budget from
+     * running a hook).
+     */
+    readonly hookTimeoutSeconds: number;
+    /**
+     * Base URL of Evident's own API. Together with `evidentRunnerId`, opts this
+     * deploy into reporting each shape's published image version to Evident
+     * (#1903) — a CDK custom resource, triggered only when a deploy actually
+     * changes a version. Omitting BOTH leaves the template byte-for-byte
+     * identical to not having this prop at all: an adopter with no Evident
+     * runner id configured has nothing to report against. Supplying only one
+     * throws at synth — see `evidentRunnerId`.
+     */
+    readonly evidentApiUrl?: string;
+    /**
+     * The pool runner id (public, non-secret UUID) to report against — see
+     * `evidentApiUrl`. Mirrors `EvidentScaleToZeroConstructProps.evidentAgentId`'s
+     * "public (non-secret) Evident agent UUID" precedent. Must be supplied
+     * together with `evidentApiUrl`, or neither at all — supplying exactly one
+     * throws at construction rather than silently disabling the reporter.
+     */
+    readonly evidentRunnerId?: string;
+}
+/**
+ * The customer-account half of the per-session runner (#558): the MicroVM
+ * image and the roles it builds and runs as, plus the stateless controller
+ * Lambda that turns a signed doorbell into RunMicrovm / ResumeMicrovm /
+ * SuspendMicrovm.
+ */
+export declare class EvidentMicrovmConstruct extends Construct {
+    /** POST target for Evident's signed doorbell (HMAC-verified in the handler). */
+    readonly functionUrl: string;
+    /** The shapes the controller can launch, with the image ARN each RunMicrovm uses. */
+    readonly shapeCatalogueJson: string;
+    /** Bucket a runner restores model credentials from: seed `<state_prefix>/claude/credentials.json` here. */
+    readonly durableStateBucket: s3.Bucket;
+    constructor(scope: Construct, id: string, props: EvidentMicrovmConstructProps);
+}