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

package/dist/microvm-image-context/hooks/resume

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+#
+# Re-dial with the identity /run left behind. There is no step that could fetch
+# a fresh runner key, so the one from /run is what resumes. The CLI delegated by
+# start_tunnel owns the session-DB replicator's post-resume start. The interval
+# credential sync loop (#1868 WI-3) stays here because /suspend stops it too, so
+# a resumed VM that never restarted it here would never sync credentials again
+# for the rest of its life.
+set -euo pipefail
+
+# shellcheck source=./common.sh
+source "$(dirname "$0")/common.sh"
+
+# Unlike /run's cleanup, this stops ONLY the tunnel: opencode is inside the
+# snapshot and resumes with it (README.md), already serving from before this
+# hook ever ran, and killing it here would take down a session /run started.
+# The only failure path today is the missing-context-file check below, before
+# start_tunnel ever runs, where stop_tunnel is a cheap no-op. Kept for the same
+# reason /run's trap is: a future failure path introduced between start_tunnel
+# and resume_succeeded=true must not orphan the tunnel it just spawned.
+resume_succeeded=false
+cleanup() {
+  if [ "${resume_succeeded}" = true ]; then
+    return 0
+  fi
+  warn "resume failed; stopping the tunnel it started"
+  stop_tunnel || warn "stop_tunnel failed while cleaning up"
+}
+trap cleanup EXIT
+
+if [ ! -s "${CONTEXT_FILE}" ]; then
+  warn "resume before run: no context at ${CONTEXT_FILE}"
+  exit 1
+fi
+
+{
+  read -r api_url
+  read -r tunnel_url
+  read -r runner_key
+} <"${CONTEXT_FILE}"
+
+# Tolerant, never fatal: a resume that fails costs the user their whole
+# session, so a broken durable-state config degrades to "no session-DB
+# replication" rather than a failed resume. The CLI's own guards handle the
+# rest — this needs no logic of its own.
+load_state_config || warn "could not resolve durable-state config; the session DB will not resume replicating"
+start_credential_sync
+
+# Diagnostic-only, unlike /run's gate: a failed resume costs the user their
+# whole session, so this never exits — it only converts a silent "resumed but
+# the key is dead" into a named RUNNER-KEY-* cause in the log, whatever
+# check_runner_key returns.
+#
+# And BACKGROUNDED for exactly that reason, following prewarm_litestream's
+# pattern in common.sh: this is a network round trip bounded by the CLI's
+# STATUS_TIMEOUT_MS (10 s), and nothing here consumes its answer. In the
+# foreground it would sit between reading the context and `start_tunnel`,
+# delaying the dial that IS this hook's job — by the most on exactly the
+# unreachable API where the answer is worthless — against a resume this image
+# measures in ~2 s (see the waker note in common.sh).
+#
+# Safe to leave running past the hook's own exit: the runtime waits on the
+# script's `'exit'`, not `'close'` (aws/lambda-microvm-runtime/src/
+# runtime.ts), so a lingering child never delays the HTTP response. Its stdio
+# is deliberately NOT redirected — that inherited fd is how the RUNNER-KEY-*
+# line reaches CloudWatch, which is the whole point of running it at all.
+#
+# The subshell is explicit rather than relying on `&` binding the whole AND-OR
+# list, so a later edit cannot accidentally foreground the check again.
+( check_runner_key "${runner_key}" "${api_url}" || true ) &
+
+# Not waited on: the CLI backs off and keeps retrying its own dial with no
+# attempt cap (apps/cli/src/lib/tunnel/connection.ts), and a control-plane
+# reclaim pass (the api-worker lifecycle cron) is what decides whether a
+# runner that never reconnects gets suspended.
+start_tunnel "${runner_key}" "${api_url}" "${tunnel_url}"
+
+resume_succeeded=true

package/dist/microvm-image-context/hooks/run

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+#
+# The per-VM phase. EVERY per-VM and secret-bearing action happens here and
+# nowhere earlier: the image snapshot is shared by every VM started from this
+# image version, so anything done before /run would be identical across all of
+# them — including, fatally, a runner identity.
+set -euo pipefail
+
+# shellcheck source=./common.sh
+source "$(dirname "$0")/common.sh"
+
+# Anything this hook started must not outlive a failure: the next /run would
+# find a stale opencode holding the port. On EXIT rather than ERR because an
+# explicit `exit 1` — which is how every check below rejects — does NOT fire an
+# ERR trap, and those are exactly the paths that have opencode running already.
+# This also runs when the runtime signals an overrun hook, which it does with
+# SIGTERM for exactly that reason: opencode and the tunnel are in a session of
+# their own, so this trap is the only thing that can still reach them.
+run_succeeded=false
+cleanup() {
+  if [ "${run_succeeded}" = true ]; then
+    return 0
+  fi
+  warn "run failed; stopping what it started"
+  # Each stop tolerates its own failure: `set -e` aborts a trap function at the
+  # first non-zero command, which would skip the stop below it — precisely the
+  # orphan this trap exists to prevent.
+  stop_tunnel || warn "stop_tunnel failed while cleaning up"
+  stop_opencode || warn "stop_opencode failed while cleaning up"
+  kill_litestream || warn "kill_litestream failed while cleaning up"
+  stop_credential_sync || warn "stop_credential_sync failed while cleaning up"
+}
+trap cleanup EXIT
+
+# The payload arrives on stdin, never argv.
+payload="$(cat)"
+
+# Never interpolate the payload into the message — it carries the runner key.
+if ! payload_is_complete <<<"${payload}"; then
+  warn "run payload is missing runner_key, endpoints or state_prefix; refusing to dial"
+  exit 1
+fi
+
+# `@sh` quotes each value for the shell, so a hostile payload cannot inject.
+eval "$(jq -er '@sh "runner_key=\(.runner_key) api_url=\(.endpoints.api) tunnel_url=\(.endpoints.tunnel) state_prefix=\(.state_prefix)"' <<<"${payload}")"
+unset payload
+
+# 1 — replace the identity the shared snapshot baked in.
+regenerate_machine_id
+
+# 2 — where this runner's credentials live. Recorded before the restore that
+# reads it, and left behind for the hooks that flush back to the same prefix.
+printf '%s\n' "${state_prefix}" >"${STATE_PREFIX_FILE}"
+
+# 3 — start reading the litestream and aws CLI binaries NOW. The reads run in
+# the background and overlap the CLI's own node startup and auth round trip,
+# keeping their cold first touches off the path to the first credential fetch.
+prewarm_litestream
+prewarm_aws_cli
+
+# 4 — export the durable-state config before anything that reads it. Fatal,
+# because the CLI and the teardown hooks must agree on this runner's state prefix.
+load_state_config || exit 1
+
+# 5 — does the runner key in this payload actually authenticate against
+# Evident? Checked here, before the tunnel spends any of this boot's time on a key
+# that cannot work, and before anything has started that cleanup would need to
+# tear down. Fatal ONLY on contrary evidence
+# (check_runner_key's own contract, common.sh): a key the API actively rejects
+# cannot work regardless, and failing here costs ~5s against the ~10 minutes a
+# runner that can never connect would otherwise burn before the lifecycle cron
+# reclaims it. Absent evidence (unreachable, no parseable JSON) is not fatal —
+# it warns and this VM still boots.
+check_runner_key "${runner_key}" "${api_url}" || exit 1
+
+# 6 — the interval credential sync (#1868 WI-3). It stays before the context file
+# is written. Bare: every guard inside start_credential_sync is its own `return 0`.
+start_credential_sync
+
+# 7 — the first per-VM identity on the wire. The subshell's umask makes the file
+# unreadable to anyone else from the moment it exists, before the key is in it.
+(
+  umask 077
+  printf '%s\n%s\n%s\n' "${api_url}" "${tunnel_url}" "${runner_key}" \
+    >"${CONTEXT_FILE}"
+)
+
+# Not waited on: the CLI backs off and keeps retrying its own dial with no
+# attempt cap (apps/cli/src/lib/tunnel/connection.ts), and a control-plane
+# reclaim pass (the api-worker lifecycle cron) is what decides whether a
+# runner that never connects gets suspended.
+start_tunnel "${runner_key}" "${api_url}" "${tunnel_url}" true true
+
+run_succeeded=true

package/dist/microvm-image-context/hooks/suspend

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+#
+# Flush anything durable, then drop the tunnel so the relay stops routing to a
+# VM that is about to freeze. opencode stays up: it is inside the snapshot and
+# resumes with it.
+set -euo pipefail
+
+# shellcheck source=./common.sh
+source "$(dirname "$0")/common.sh"
+
+# Stopped BEFORE the boundary flush (#1868 WI-3): the interval loop and this
+# flush must not race each other on the same credential stores.
+stop_credential_sync
+sync_credentials
+stop_tunnel
+
+# opencode is deliberately NOT stopped here (#812 WI-4) — it is inside the
+# snapshot and must resume with it — so a turn still in flight may not be
+# fully flushed by this call. Acceptable: the VM resumes with the local DB
+# intact, and this flush exists for the TERMINATED-while-suspended case,
+# where a frozen VM would otherwise flush nothing at all.
+flush_session_db

package/dist/microvm-image-context/hooks/terminate

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+#
+# Best-effort teardown. The runtime reports 200 whatever happens here — the VM
+# is going away either way — so each step is allowed to fail on its own without
+# skipping the ones after it.
+set -uo pipefail
+
+# shellcheck source=./common.sh
+source "$(dirname "$0")/common.sh"
+
+# Stopped BEFORE the boundary flush (#1868 WI-3): the interval loop and this
+# flush must not race each other on the same credential stores.
+stop_credential_sync
+sync_credentials
+stop_tunnel
+
+# Writers stopped BEFORE litestream's final sync (#812 WI-4, the
+# ordered-shutdown invariant, plan §6): otherwise litestream could snapshot
+# while opencode is still writing its WAL and the last session writes would
+# be missing from S3. stop_opencode_and_wait, not /run cleanup's cheap
+# stop_opencode — /terminate can afford the real drain, the VM is being torn
+# down either way.
+stop_opencode_and_wait
+flush_session_db
+
+# The key must not outlive the VM's last useful moment. The no-replicate
+# marker goes alongside it: no state that a later /resume could trust should
+# outlive the VM's last useful moment either.
+#
+# The tunnel-ready marker used to be removed here too. It is gone entirely
+# since #1172 — and naming an unset variable here is not a harmless leftover:
+# this hook runs under `set -u` (above), so an unbound one aborts the script
+# AT THIS LINE, leaving the runner key sitting in CONTEXT_FILE on a VM that is
+# being torn down. That is the one thing this line exists to prevent.
+rm -f "${CONTEXT_FILE}" "${SESSION_DB_NO_REPLICATE_MARKER}"
+
+exit 0

package/dist/waker/construct.js

@@ -56,7 +56,7 @@ class EvidentWaker extends constructs_1.Construct {
             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
+            // @evident/sdk'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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "0.1.1-dev.da70cd4",
-  "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.",
+  "version": "3.4.1-dev.0ef5061",
+  "description": "Reusable CDK constructs for an Evident agent runner: a single scale-to-zero Fargate runner (task + service + per-agent self-stop role + waker Lambda), or a per-session AWS Lambda MicroVM that boots on demand and suspends between messages. Instantiate once per agent from your own stack.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -14,27 +14,35 @@
     "dist"
   ],
   "scripts": {
-    "build": "ts-node scripts/build.ts",
+    "build": "pnpm run build-bundled-deps && ts-node scripts/build.ts",
+    "//build-bundled-deps": "scripts/build.ts esbuild-bundles runner/docker-images/microvm/hook-server.ts, which imports @evident-ai/lambda-microvm-runtime by its built `main`. @evident-ai/lambda-microvm-cdk is a workspace:* devDependency whose types resolve through its own dist/, so tsc --project tsconfig.build.json cannot compile src/microvm/{shapes,construct}.ts without it. Chained into `build` rather than left to turbo's `^build` because publish-runner-cdk.yaml and infrastructure/evident-runner's build-runner-cdk-dep invoke `pnpm --filter @evident-ai/runner-cdk build` directly, which bypasses turbo entirely.",
+    "build-bundled-deps": "pnpm --filter @evident-ai/lambda-microvm-cdk build && pnpm --filter @evident-ai/lambda-microvm-runtime build",
     "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": "@evident-ai/lambda-microvm-cdk is a registry range here, never workspace:*: publish-runner-cdk.yaml ships this package with `npm publish`, not `pnpm publish`, so pnpm's workspace-protocol substitution never runs and a workspace: range would reach npm literally, breaking every external install. Enforced by src/published-surface.test.ts. The matching devDependency is workspace:* so this monorepo's own build compiles against aws/lambda-microvm-cdk's source.",
   "peerDependencies": {
+    "@evident-ai/lambda-microvm-cdk": "^0.1.1",
     "aws-cdk-lib": "^2.240.0",
     "constructs": "^10.5.0"
   },
   "devDependencies": {
     "@aws-sdk/client-ecs": "^3.682.0",
+    "@aws-sdk/client-lambda-microvms": "^3.1095.0",
     "@aws-sdk/client-secrets-manager": "^3.682.0",
-    "@evident/webhook-signature": "workspace:*",
+    "@evident-ai/lambda-microvm-cdk": "workspace:*",
+    "@evident-ai/lambda-microvm-runtime": "workspace:*",
+    "@evident/sdk": "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"
+    "typescript": "^5.6.3",
+    "runner-microvm-image": "workspace:*"
   },
   "publishConfig": {
     "access": "public"
@@ -42,9 +50,9 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/sroze/evident.git",
-    "directory": "packages/runner-cdk"
+    "directory": "aws/runner-cdk"
   },
   "homepage": "https://evident.run",
-  "author": "Evident <contact@evident.run>",
+  "author": "Evident <hello@evident.run>",
   "license": "MIT"
 }