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

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

@@ -0,0 +1,79 @@
+#!/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. Also restarts the
+# session-DB replicator /suspend stopped before the snapshot (#812 WI-4):
+# litestream does not survive a suspend/resume freeze on this design (Q2) —
+# /suspend stops it and /resume starts a fresh one, the same pattern already
+# proven for the tunnel.
+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
+# restart" rather than a failed resume (the same Q3 reasoning /run's
+# session-DB step follows). start_litestream's own guards (disabled/marker/
+# already-running) 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_litestream
+
+# 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'` (packages/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,111 @@
+#!/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"
+}
+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 binary NOW so that read overlaps step 4,
+# which needs a different binary (node), instead of landing inside step 5, which
+# start_opencode has to wait for. Backgrounded and never waited on.
+prewarm_litestream
+
+# 4 — credential stores, restored before anything that reads them starts. Fatal
+# only if persistence itself is unavailable (an unset bucket/prefix, or a broken
+# synchroniser bundle) — a VM with no model credentials yet still boots.
+restore_credentials
+
+# 5 — does the runner key in this payload actually authenticate against
+# Evident? Checked here, before opencode or the tunnel spend any of this boot's
+# SIGTERM budget 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 OpenCode session DB (#812 WI-2), restored before opencode opens it —
+# the only place this can happen. Bare, like restore_credentials above:
+# restore_session_db never returns non-zero (Q3 — nothing about the session
+# DB may ever fail /run), so there is deliberately no `||` here to catch.
+restore_session_db
+log "session DB restore done ${SECONDS}s into the hook"
+
+# 7 — opencode. Started here, not at build time: a warm process in the shared
+# snapshot would carry its installation id and database into every VM. Not
+# waited on: a slow opencode boot is not a reason to fail /run (the tunnel CLI
+# auto-starts opencode when it finds none healthy,
+# apps/cli/src/commands/ensure-opencode.ts, and the api-worker lifecycle cron
+# reclaims a runner that never comes online).
+start_opencode
+
+# 8 — begin replicating the session DB (#812 WI-3), now that opencode has
+# opened it and before any work can arrive over the tunnel. Bare, like
+# restore_session_db above: start_litestream never returns non-zero (every
+# guard inside it is its own `return 0`), so there is nothing here for
+# `set -e` to abort on.
+start_litestream
+
+# 9 — 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}"
+
+run_succeeded=true

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

@@ -0,0 +1,19 @@
+#!/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"
+
+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,34 @@
+#!/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"
+
+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/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.1.1-dev.04ef8b1",
+  "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,19 +14,25 @@
     "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 src/microvm/image/hook-server.ts, which imports @evident-ai/lambda-microvm-runtime by its built `main`. Chained into `build` rather than left to turbo's `^build` because publish-runner-cdk.yaml invokes `pnpm --filter @evident-ai/runner-cdk build` directly, which bypasses turbo entirely.",
+    "build-bundled-deps": "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": "^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-ai/lambda-microvm-cdk": "^0.1.1",
+    "@evident-ai/lambda-microvm-runtime": "workspace:*",
     "@evident/webhook-signature": "workspace:*",
     "@types/node": "^22",
     "aws-cdk-lib": "^2.240.0",