Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Move backend into backend/, split CLI/backend release tags

0xken15617ff4fb2ce8
diff --git a/.github/workflows/production-be-build.yaml b/.github/workflows/production-be-build.yaml
new file mode 100644
index 000000000..e514f067e
--- /dev/null
+++ b/.github/workflows/production-be-build.yaml
@@ -0,0 +1,18 @@
+name: Docker production backend build
+
+on:
+ push:
+ tags:
+ - 'v*_api'
+
+jobs:
+ build-autonomous-code-be-production:
+ uses: autonomous-ai/github-templates/.github/workflows/docker-build-and-push.yaml@main
+ with:
+ DOCKER_IMAGE_NAME: autonomous-code-be
+ DOCKER_CONTEXT: backend
+ DOCKERFILE_NAME: Dockerfile.k8s
+ CONCURRENCY_GROUP: docker_build_web_production
+ RUNNER_TAG: ubuntu-latest
+ secrets:
+ GCLOUD_DEV_SERVICE_ACCOUNT_JSON: ${{ secrets.GCLOUD_DEV_SERVICE_ACCOUNT_JSON }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 254969bf8..ebd1dc67f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,6 +1,11 @@
name: Release
-# Cut a release by pushing a tag: git tag -a v0.1.72 -F notes.md && git push origin v0.1.72
+# Cut a release by pushing a tag: git tag -a v0.1.72_cli -F notes.md && git push origin v0.1.72_cli
+#
+# The `_cli` suffix exists only so this workflow's tag trigger never fires on the backend's
+# `v*_api` release tags (see .github/workflows/production-be-build.yaml) now that both live in one
+# repo. It is stripped below before anything treats it as a version — the manifest, the release
+# title, and the daemon's self-update comparison all only ever see a bare X.Y.Z.
#
# Publishes the `cli` key of harness/cli/metadata.json — the manifest EVERY RUNNING DAEMON POLLS
# EVERY 60 SECONDS (src/config/env.ts: ADAPTER_UPDATE_URL / ADAPTER_UPDATE_CHECK_MS). That is the
@@ -38,7 +43,7 @@ name: Release
on:
push:
- tags: ['v*']
+ tags: ['v*_cli']
workflow_dispatch:
inputs:
version:
@@ -81,9 +86,13 @@ jobs:
INPUT_METADATA_PATH: ${{ inputs.metadata_path }}
run: |
set -euo pipefail
+ # A tag push names the ref "vX.Y.Z_cli"; workflow_dispatch's input.version is already
+ # bare. Strip both the leading "v" and the trailing "_cli" so $ver is always X.Y.Z —
+ # the suffix is a tag-trigger routing marker only, never part of the published version.
ver="${INPUT_VERSION:-${REF_NAME#v}}"
+ ver="${ver%_cli}"
if [[ ! "$ver" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
- echo "::error::version '$ver' must look like X.Y.Z — tag as vX.Y.Z"
+ echo "::error::version '$ver' must look like X.Y.Z — tag as vX.Y.Z_cli"
exit 1
fi
meta="${INPUT_METADATA_PATH:-harness/cli/metadata.json}"
diff --git a/backend/.dockerignore b/backend/.dockerignore
new file mode 100644
index 000000000..08240eddf
--- /dev/null
+++ b/backend/.dockerignore
@@ -0,0 +1,7 @@
+**/node_modules
+**/dist
+**/.git
+**/.env
+**/.env.*
+**/*.log
+**/.tsbuildinfo
diff --git a/backend/.env.example b/backend/.env.example
new file mode 100644
index 000000000..e91002ab0
--- /dev/null
+++ b/backend/.env.example
@@ -0,0 +1,87 @@
+# --- backend (central product API) configuration ---
+
+# The single port the web connects to. Serves the control API (/api/auth, /api/users,
+# /api/agents, /api/health) locally and reverse-proxies every other /api/* + the /api/ws
+# WebSocket to the agent-manager (data plane).
+PORT=8085
+
+# Dedicated PUBLIC subdomain app-proxy port. Traffic to <sub><APP_DOMAIN_SUFFIX> hits this listener
+# (Host-header routed → owning manager's app-proxy), separate from the api-key control/proxy plane on PORT.
+PORT_APP_PROXY=8087
+# Domain suffix stripped from the Host header to get the subdomain (e.g. foo.harness.autonomous.ai → "foo").
+APP_DOMAIN_SUFFIX=.harness.autonomous.ai
+
+NODE_ENV=development
+
+# Shared registry DB — MUST be the same MongoDB (and database) the agent-manager uses, so the
+# backend reads `managers` (publicHost + apiKey + capacity) and resolves which manager to reach
+# per agent. Backend owns `users` + `agent_bindings`. Prisma needs a replica set (single-node ok).
+DATABASE_URL=mongodb://localhost:27017/harness?replicaSet=rs0
+
+# Redis for the cross-instance data bus (inverted WS transport). Behind a load balancer an agent's web
+# socket and its manager socket may land on different backend instances; Redis pub/sub bridges them
+# (channels up:{agentId}/down:{agentId} + presence). Run redis on the host (or a container published on
+# 6379). See docs/plans/2026-07-09_invert-ws-transport-backend-hub-redis.md.
+REDIS_URL=redis://127.0.0.1:6379
+
+# STUN-only direct WebRTC for CLI-to-CLI remote terminals. If ICE cannot connect, terminal traffic
+# stays on the existing WebSocket relay; no TURN service is used. Set to 0 for the kill switch.
+TERMINAL_P2P_ROLLOUT_PERCENT=100
+# Comma-separated, sliced to 8. The CLI probes them all at once and uses whichever answers first.
+TERMINAL_P2P_STUN_URLS=stun:stun.cloudflare.com:3478,stun:stun.cloudflare.com:53,stun:stun.l.google.com:19302,stun:stun2.l.google.com:19302,stun:global.stun.twilio.com:3478,stun:stun.nextcloud.com:443,stun:stun.ekiga.net:3478,stun:stun.voipgate.com:3478
+# 2500 so a TURN-relayed channel (measured ~1372ms to open) wins the first-terminal gate.
+TERMINAL_P2P_OPEN_WAIT_MS=2500
+
+# Cloudflare Realtime TURN. Leave the key id empty to disable TURN entirely (STUN-only, pre-TURN
+# behaviour) — that is also the kill switch. https://developers.cloudflare.com/realtime/turn/
+TERMINAL_P2P_TURN_KEY_ID=
+TERMINAL_P2P_TURN_API_TOKEN=
+TERMINAL_P2P_TURN_TTL_SECONDS=7200
+TERMINAL_P2P_TURN_TIMEOUT_MS=5000
+
+# Public app-proxy safety limits.
+APP_PROXY_MAX_REQUEST_BYTES=104857600
+APP_PROXY_MAX_RESPONSE_BYTES=536870912
+APP_PROXY_MAX_WS_FRAME_BYTES=8388608
+APP_PROXY_MAX_STREAMS_PER_SUBDOMAIN=128
+APP_PROXY_IDLE_TIMEOUT_MS=300000
+
+# No MANAGER_URL / MANAGER_API_KEY here — the backend gets each manager's publicHost + apiKey
+# from the `managers` collection (each manager publishes its own via PUBLIC_HOST + MANAGER_API_KEY).
+
+# Production is the default for new users. Existing pre-split rows are backfilled as staging;
+# admins opt individual new users into staging via User.autonomousEnv.
+SSO_ISSUER=https://auth.autonomous.ai
+SSO_PROFILE_URL=https://apiv2.autonomous.ai/api/v1/me/profile
+STAGING_SSO_ISSUER=https://auth.staging.autonomousdev.xyz
+STAGING_SSO_PROFILE_URL=https://apiv2.staging.autonomousdev.xyz/api/v1/me/profile
+# Optional when staging uses a different OAuth client; otherwise SSO_CLIENT_* is reused.
+# STAGING_SSO_CLIENT_ID=
+# STAGING_SSO_CLIENT_SECRET=
+SSO_PROFILE_TIMEOUT_MS=5000
+
+# New managed harness checkout (enabled by default). Before production boot, both backend + manager
+# must share the same random 32-byte base64 encryption key (`openssl rand -base64 32`). Set false
+# only as a rollback switch; then only Remote is offered for new harnesses.
+HARNESS_BILLING_ENABLED=true
+AUTONOMOUS_BFF_URL=https://apiv2.autonomous.ai
+STAGING_AUTONOMOUS_BFF_URL=https://apiv2.staging.autonomousdev.xyz
+# Worker-only subscription sync. Keys require subscriptions:read and are intentionally separate
+# because production and staging campaign services have independent credentials.
+AUTONOMOUS_CAMPAIGN_API_URL=https://campaign-api.autonomous.ai
+STAGING_AUTONOMOUS_CAMPAIGN_API_URL=https://campaign-api.staging.autonomousdev.xyz
+AUTONOMOUS_CAMPAIGN_API_KEY=
+STAGING_AUTONOMOUS_CAMPAIGN_API_KEY=
+AUTONOMOUS_CHECKOUT_ORIGIN=https://autonomous.ai
+STAGING_AUTONOMOUS_CHECKOUT_ORIGIN=https://staging.autonomousdev.xyz
+AUTONOMOUS_BFF_TIMEOUT_MS=10000
+HARNESS_CAMPAIGN_CODE=ai-harness-device
+HARNESS_DEVICE_TYPE=15
+HARNESS_DEVICE_TIMEZONE_DEFAULT=Asia/Saigon
+# Optional explicit page; default is WEB_URL/harness-checkout. Stripe-hosted plan changes require
+# HTTPS, so local end-to-end billing must set this to an HTTPS tunnel pointing at the web app.
+HARNESS_CHECKOUT_CALLBACK_URL=
+HARNESS_CREDENTIAL_ENCRYPTION_KEY=
+
+# Comma-separated emails that get role=admin when first created (login auto-creates users).
+ADMIN_EMAILS=
diff --git a/backend/.gitignore b/backend/.gitignore
new file mode 100644
index 000000000..0d7af1a82
--- /dev/null
+++ b/backend/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+.tsbuildinfo
+.env
diff --git a/backend/Dockerfile b/backend/Dockerfile
new file mode 100644
index 000000000..1c9275bcf
--- /dev/null
+++ b/backend/Dockerfile
@@ -0,0 +1,35 @@
+# Central product backend: a Fastify control API (auth/users/agents/devices) + a data-plane reverse
+# proxy that forwards web traffic to the owning agent-manager. Stateless → clustered by pm2. Unlike
+# the agent-manager it does NOT drive Docker, so no docker CLI / socket is needed.
+FROM node:22-bookworm-slim
+
+WORKDIR /app
+
+# openssl so `prisma generate` detects the correct engine target (bookworm = openssl-3.0.x).
+# Without it Prisma mis-detects openssl-1.1.x and the runtime can't load the query engine.
+RUN apt-get update && apt-get install -y --no-install-recommends openssl && rm -rf /var/lib/apt/lists/*
+
+# Process manager: `npm run start:runtime` → `pm2-runtime start ecosystem.config.cjs` runs the
+# clustered HTTP/WS server plus exactly one singleton job worker in one foreground
+# (PID-1-friendly) process, forwards logs to stdout, and restarts on crash. (`start` is pm2 daemon
+# mode — wrong for a container.) Global so it survives the dev prune.
+RUN npm install -g pm2
+
+# Install deps first (postinstall runs `prisma generate`, so the schema must be present).
+# Dev deps are needed to build; prune them afterwards.
+COPY package.json package-lock.json ./
+COPY prisma ./prisma
+RUN npm ci
+
+# Build, then drop dev dependencies for a leaner runtime image.
+COPY tsconfig.json build.mjs ./
+COPY src ./src
+RUN npm run build && npm prune --omit=dev
+
+COPY ecosystem.config.cjs.docker ./ecosystem.config.cjs
+
+ENV NODE_ENV=production
+# 8085 = control API + /proxy data-plane; 8087 = public subdomain app-proxy (Host-routed).
+EXPOSE 8085 8087
+# pm2-runtime stays in the foreground so the container lives as long as the apps do.
+CMD ["npm", "run", "start:runtime"]
diff --git a/backend/Dockerfile.k8s b/backend/Dockerfile.k8s
new file mode 100644
index 000000000..62d31cb0d
--- /dev/null
+++ b/backend/Dockerfile.k8s
@@ -0,0 +1,73 @@
+# Central product backend — Kubernetes image. (The sibling `Dockerfile` is the pm2/compose one;
+# this file is the k8s-shaped variant and is what the k8s build should target.)
+#
+# ONE image, TWO roles — selected by the APP env var, so both Deployments run the same image and the
+# manifests differ only by `env` + `replicas`:
+# APP=api (N replicas) : node dist/server.js ← default
+# APP=job (1 replica) : node dist/worker.js
+#
+# Why one process per container: src/worker.ts owns schema push, migrateHarnessRename, ensurePlans and
+# the backfills, and those boot steps are NOT guarded across processes (only the recurring billing
+# loop takes a Redis lease). Baking the pm2 ecosystem here would start a worker in EVERY replica and
+# race them. K8s owns the replica count; a pm2 cluster inside a pod would also mis-size itself, since
+# os.cpus() reports the node's cores, not the pod's cgroup CPU limit.
+
+# --- builder: full install (postinstall = prisma generate) + esbuild → dist/ ------------------
+FROM node:22-bookworm-slim AS builder
+WORKDIR /app
+
+# openssl so `prisma generate` detects the correct engine target (bookworm = openssl-3.0.x).
+# Without it Prisma mis-detects openssl-1.1.x and the runtime can't load the query engine.
+RUN apt-get update && apt-get install -y --no-install-recommends openssl && rm -rf /var/lib/apt/lists/*
+
+# postinstall runs `prisma generate`, so the schema must be present first.
+COPY package.json package-lock.json ./
+COPY prisma ./prisma
+RUN npm ci
+
+COPY tsconfig.json build.mjs ./
+COPY src ./src
+RUN npm run build
+
+# --- runner: dist/ + production node_modules only, non-root ----------------------------------
+FROM node:22-bookworm-slim AS runner
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends openssl && rm -rf /var/lib/apt/lists/*
+
+RUN groupadd --system --gid 1001 nodejs \
+ && useradd --system --uid 1001 --gid nodejs backend
+
+COPY package.json package-lock.json ./
+COPY prisma ./prisma
+# Production deps WITHOUT lifecycle scripts: postinstall is `prisma generate`, which needs the Prisma
+# CLI — a devDependency that `--omit=dev` does not install.
+RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
+
+# Take the Prisma pieces from the builder, where the full install already generated them:
+# .prisma generated client + query engine
+# prisma the CLI — the worker shells out to prisma/build/index.js for `db push` at boot
+# (lib/db/migrate.ts ensureSchema). Miss it and schema management SILENTLY no-ops.
+# @prisma client runtime + engines
+COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma
+COPY --from=builder /app/node_modules/prisma ./node_modules/prisma
+COPY --from=builder /app/node_modules/@prisma ./node_modules/@prisma
+
+# Runtime artifacts only — no src/, tsconfig.json or build.mjs in the published image. dist/ mirrors
+# src/ 1:1 (build.mjs sets bundle:false), so node_modules must ship with it.
+COPY --from=builder /app/dist ./dist
+
+ENV NODE_ENV=production
+# Role selector. Override to `job` on the worker Deployment (replicas: 1).
+ENV APP=api
+
+USER backend
+
+# 8085 = control API + /proxy data-plane; 8087 = public subdomain app-proxy (same process, so the
+# api Service must expose BOTH). Documentation only — k8s publishes via the Service.
+EXPOSE 8085 8087
+
+# `exec` replaces the shell, so node ends up as PID 1 and receives SIGTERM directly; both entry
+# points shut down on it (server.ts closes the listeners; worker.ts stops the billing loop and hard-
+# exits after 5s, so give the worker terminationGracePeriodSeconds >= 10).
+CMD ["sh", "-c", "case \"$APP\" in api) exec node dist/server.js ;; job) exec node dist/worker.js ;; *) echo \"FATAL: unknown APP='$APP' (expected 'api' or 'job')\" >&2; exit 1 ;; esac"]
diff --git a/backend/README.md b/backend/README.md
new file mode 100644
index 000000000..65c90771a
--- /dev/null
+++ b/backend/README.md
@@ -0,0 +1,80 @@
+# autonomous-harness-backend — central product API + single-port reverse proxy
+
+The **central, public-facing** backend for the distributed deployment. It is the **one port** the
+web connects to. It:
+
+1. **Manages users + auth** — `POST /api/auth/login {email,password}` issues a JWT. An unknown email
+ is **created on the spot** (login doubles as signup). Admin-only user CRUD under `/api/users`.
+2. **Provisions agent-nodes** — `POST /api/agents` generates a per-agent api-key, **picks a
+ manager by capacity** (reads `maxNodes`/`nodeCount` from the shared `managers` collection;
+ best-fit = the live manager with the least free room, 503 if all full), calls that manager's
+ control API to create the node, and stores the `user → agentId/apiKey/managerUrl` binding.
+ `DELETE /api/agents/:agentId` tears it down. The data-plane proxy then targets the binding's
+ manager.
+3. **Reverse-proxies the data plane** — every other `/api/*` request and the `/api/ws` WebSocket are
+ authenticated by the **agent api key** (NOT the JWT): the client sends it (`x-api-key` for HTTP,
+ the WS subprotocol) on a **`/proxy/...`** path, the backend derives `agentId = sha256(key)[:32]`,
+ looks up the owning manager, and forwards the path verbatim to it (the manager mounts its data
+ plane under `/proxy` and strips it before the node). So any client (a CLI, another app, the web
+ chat page) can reach an agent with **only its api key**. The owner obtains that key from the
+ control plane (#2); possessing it is the auth (128-bit preimage).
+
+```
+control: web ──(JWT)──────────────────────▶ backend :8085 /api/auth|users|agents ──(x-api-key: MANAGER_API_KEY)──▶ manager :8090/api
+data: client ──(agent api key: x-api-key / WS subprotocol)──▶ backend :8085 /proxy/api/* ──▶ manager :8090/proxy/api/* ──▶ agent-node/api/*
+```
+
+## One port, two planes
+
+A single `http.Server` (`server.ts` `serverFactory`) splits traffic by an explicit path prefix:
+
+- **Data plane (reverse-proxied):** everything under **`/proxy/*`** (incl. the `/proxy/api/ws`
+ upgrade) → `lib/proxy.ts`.
+- **Local (Fastify control API):** everything else — `/api/health`, `/api/auth/*`, `/api/users/*`,
+ `/api/agents*`. A stray `/api/*` that isn't a control route now 404s here instead of being proxied.
+
+## Run
+
+```bash
+npm install # runs `prisma generate`
+
+# Needs MongoDB (shared with the agent-manager) + a running agent-manager:
+# cd ../autonomous-code/apps/mongodb && docker compose up -d
+# cd ../autonomous-code/apps/machine-manager && npm run dev
+npm run dev # tsx watch, :8085 by default
+```
+
+Copy `.env.example` → `.env` and set at least `MANAGER_API_KEY` (to match the manager) and a
+`DATABASE_URL` pointing at the **same** MongoDB the manager uses. Production SSO/profile URLs are
+the defaults; override `SSO_ISSUER` and `SSO_PROFILE_URL` with the staging hosts for local testing.
+
+| dev | build | other |
+|-----|-------|-------|
+| `npm run dev` (tsx watch) | `npm run build` (esbuild via `build.mjs`) | `npm run typecheck`; `npm run test` (vitest) |
+
+### CLI terminal P2P canary
+
+Remote CLI-to-CLI terminals can use an ordered WebRTC DataChannel while authentication, encrypted
+signaling, chat/RPC, and fallback remain on the existing WebSocket path. This mode is STUN-only and
+does not require or use TURN. Configure `TERMINAL_P2P_ROLLOUT_PERCENT` (default `100`; set `0` as the kill switch),
+`TERMINAL_P2P_STUN_URLS` (default Cloudflare STUN), and `TERMINAL_P2P_OPEN_WAIT_MS` (default `1500`).
+When direct ICE fails, the terminal opens on WebSocket relay automatically.
+
+## Deploy
+
+`../.github/workflows/production-be-build.yaml` builds and pushes the production Docker image on
+tag push. Backend releases are tagged **`vX.Y.Z_api`** — the `_api` suffix is what routes the push
+to this workflow instead of the CLI's `../.github/workflows/release.yml` (which only reacts to
+`vX.Y.Z_cli`), now that both live in this one repo:
+
+```bash
+git tag vX.Y.Z_api && git push origin vX.Y.Z_api
+```
+
+## Persistence
+
+Prisma over the **same MongoDB** as the agent-manager (no migration files — `prisma db push` at
+startup). The backend owns the `users` + `agent_bindings` collections; it never manages the
+manager-owned `agent_nodes`/`managers` (read those via raw queries when status enrichment is needed).
+
+Historical architecture notes still live in `autonomous-code/docs`.
diff --git a/backend/build.mjs b/backend/build.mjs
new file mode 100644
index 000000000..1b5acf163
--- /dev/null
+++ b/backend/build.mjs
@@ -0,0 +1,33 @@
+import * as esbuild from 'esbuild'
+import { readdirSync, statSync } from 'fs'
+import { join } from 'path'
+
+function getAllTsFiles(dir, fileList = []) {
+ for (const file of readdirSync(dir)) {
+ const filePath = join(dir, file)
+ if (statSync(filePath).isDirectory()) {
+ getAllTsFiles(filePath, fileList)
+ } else if (file.endsWith('.ts') && !file.endsWith('.test.ts')) {
+ fileList.push(filePath)
+ }
+ }
+ return fileList
+}
+
+try {
+ await esbuild.build({
+ entryPoints: getAllTsFiles('src'),
+ outdir: 'dist',
+ bundle: false,
+ platform: 'node',
+ format: 'esm',
+ target: 'node20',
+ sourcemap: true,
+ outExtension: { '.js': '.js' },
+ logLevel: 'info',
+ })
+ console.log('✓ Build completed successfully')
+} catch (error) {
+ console.error('✗ Build failed:', error)
+ process.exit(1)
+}
diff --git a/backend/docker-compose.yml b/backend/docker-compose.yml
new file mode 100644
index 000000000..be8c4b8e7
--- /dev/null
+++ b/backend/docker-compose.yml
@@ -0,0 +1,28 @@
+# Central backend in a container. Mirrors apps/machine-manager. Connects to an ALREADY-RUNNING MongoDB
+# (start it from apps/mongodb: `docker compose up -d`).
+#
+# START IT WITH:
+# docker compose up -d --build
+#
+# Config: the local `.env` is injected straight into the container (env_file). Because that .env
+# points at 127.0.0.1 for both MongoDB (:27017) and the agent-manager (publicHost :8090), the service
+# uses HOST networking so those addresses resolve to the services on the same VM — no rewriting .env.
+#
+# Notes:
+# - `network_mode: host` is a Linux feature (this is the production path). On Docker-Desktop-Mac it's
+# unreliable → for Mac dev run the backend natively (`npm run dev`).
+# - With host networking `ports:` is ignored; the app binds PORT (default 8085, from .env) on the host.
+# - To use bridge networking instead: drop `network_mode`, add `ports: ["8085:8085"]` +
+# `extra_hosts: ["host.docker.internal:host-gateway"]`, and point DATABASE_URL (and the manager
+# publicHost it reads from the DB) at host.docker.internal.
+services:
+ backend:
+ build:
+ context: .
+ dockerfile: Dockerfile
+ image: backend:local
+ container_name: backend
+ env_file:
+ - .env
+ network_mode: host
+ restart: unless-stopped
diff --git a/backend/ecosystem.config.cjs b/backend/ecosystem.config.cjs
new file mode 100644
index 000000000..8345ce1a7
--- /dev/null
+++ b/backend/ecosystem.config.cjs
@@ -0,0 +1,21 @@
+module.exports = {
+ apps: [
+ {
+ name: 'backend-worker',
+ script: 'dist/worker.js',
+ exec_mode: 'fork',
+ instances: 1,
+ wait_ready: true,
+ listen_timeout: 120000,
+ kill_timeout: 6000,
+ env: { NODE_ENV: 'production' },
+ },
+ {
+ name: 'backend',
+ script: 'dist/server.js',
+ exec_mode: 'cluster',
+ instances: 'max',
+ env: { NODE_ENV: 'production' },
+ },
+ ],
+}
diff --git a/backend/ecosystem.config.cjs.docker b/backend/ecosystem.config.cjs.docker
new file mode 100644
index 000000000..c3525aef2
--- /dev/null
+++ b/backend/ecosystem.config.cjs.docker
@@ -0,0 +1,36 @@
+// pm2 deployment for the central backend.
+//
+// npm run build && pm2 start ecosystem.config.cjs (or `npm run start` → pm2-runtime, in Docker)
+//
+// The HTTP/WS server is stateless and clusters cleanly. Schema/catalog/reconcile jobs live in a
+// separate singleton worker so no server process owns background state.
+//
+// Runs on Kubernetes → default to 'max' (use every core in the pod). Caveat: pm2 'max' reads
+// os.cpus().length, which under a cgroup CPU *limit* still reports the NODE's cores, not the pod's
+// limit → it can over-subscribe. If the pod has a CPU limit, pin BACKEND_INSTANCES from the
+// downward API (resources.limits.cpu) instead of relying on 'max'.
+const instances = process.env.BACKEND_INSTANCES
+ ? (process.env.BACKEND_INSTANCES === 'max' ? 'max' : Number(process.env.BACKEND_INSTANCES))
+ : 'max'
+
+module.exports = {
+ apps: [
+ {
+ name: 'backend-worker',
+ script: 'dist/worker.js',
+ exec_mode: 'fork',
+ instances: 1,
+ wait_ready: true,
+ listen_timeout: 120000,
+ kill_timeout: 6000,
+ env: { NODE_ENV: 'production' },
+ },
+ {
+ name: 'backend',
+ script: 'dist/server.js',
+ exec_mode: 'cluster',
+ instances,
+ env: { NODE_ENV: 'production' },
+ },
+ ],
+}
diff --git a/backend/package-lock.json b/backend/package-lock.json
new file mode 100644
index 000000000..a2f75ffa2
--- /dev/null
+++ b/backend/package-lock.json
@@ -0,0 +1,3587 @@
+{
+ "name": "backend",
+ "version": "0.1.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "backend",
+ "version": "0.1.0",
+ "hasInstallScript": true,
+ "dependencies": {
+ "@fastify/cors": "^10.1.0",
+ "@fastify/multipart": "^9.4.0",
+ "@noble/curves": "^2.4.0",
+ "@prisma/client": "^5.22.0",
+ "@types/ws": "^8.18.1",
+ "dotenv": "^17.2.3",
+ "fastify": "^5.6.2",
+ "http-proxy": "^1.18.1",
+ "ioredis": "^5.11.1",
+ "ws": "^8.21.0",
+ "zod": "^4.0.0"
+ },
+ "devDependencies": {
+ "@types/http-proxy": "^1.17.15",
+ "@types/node": "^20.14.10",
+ "concurrently": "^9.1.2",
+ "esbuild": "^0.27.2",
+ "prisma": "^5.22.0",
+ "tsx": "^4.16.2",
+ "typescript": "^5.5.3",
+ "vitest": "^4.0.17"
+ }
+ },
+ "node_modules/@esbuild/aix-ppc64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+ "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "aix"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+ "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+ "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+ "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
+ "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+ "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+ "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+ "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+ "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+ "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ia32": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+ "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-loong64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+ "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+ "cpu": [
+ "loong64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-mips64el": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+ "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+ "cpu": [
+ "mips64el"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ppc64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+ "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-riscv64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+ "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+ "cpu": [
+ "riscv64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-s390x": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+ "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+ "cpu": [
+ "s390x"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+ "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+ "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+ "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+ "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+ "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openharmony-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+ "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openharmony"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/sunos-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+ "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "sunos"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+ "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-ia32": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+ "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+ "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@fastify/ajv-compiler": {
+ "version": "4.0.6",
+ "resolved": "https://registry.npmjs.org/@fastify/ajv-compiler/-/ajv-compiler-4.0.6.tgz",
+ "integrity": "sha512-NtuzM0SfaMJbGlnjr9LWQUN5LzgSrbB8tf/wRZNas+4E1O/Nmzl53e7ruT61HDZyRCJGC6FxIogmNZO1c5ETBA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "ajv": "^8.12.0",
+ "ajv-formats": "^3.0.1",
+ "fast-uri": "^4.0.0"
+ }
+ },
+ "node_modules/@fastify/busboy": {
+ "version": "3.2.2",
+ "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-3.2.2.tgz",
+ "integrity": "sha512-yXSS27qPExaXeuLvMRMXOLtpipzfQYNjG3FkunDWKGfMYjKuhFXko9CVzqxm8jcF+lmtS9Fd89QNdh9XDjnbNg==",
+ "license": "MIT"
+ },
+ "node_modules/@fastify/cors": {
+ "version": "10.1.0",
+ "resolved": "https://registry.npmjs.org/@fastify/cors/-/cors-10.1.0.tgz",
+ "integrity": "sha512-MZyBCBJtII60CU9Xme/iE4aEy8G7QpzGR8zkdXZkDFt7ElEMachbE61tfhAG/bvSaULlqlf0huMT12T7iqEmdQ==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "fastify-plugin": "^5.0.0",
+ "mnemonist": "0.40.0"
+ }
+ },
+ "node_modules/@fastify/deepmerge": {
+ "version": "3.2.1",
+ "resolved": "https://registry.npmjs.org/@fastify/deepmerge/-/deepmerge-3.2.1.tgz",
+ "integrity": "sha512-N5Oqvltoa2r9z1tbx4xjky0oRR60v+T47Ic4J1ukoVQcptLOrIdRnCSdTGmOmajZuHVKlTnfcmrjyqsGEW1ztA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT"
+ },
+ "node_modules/@fastify/error": {
+ "version": "4.2.0",
+ "resolved": "https://registry.npmjs.org/@fastify/error/-/error-4.2.0.tgz",
+ "integrity": "sha512-RSo3sVDXfHskiBZKBPRgnQTtIqpi/7zhJOEmAxCiBcM7d0uwdGdxLlsCaLzGs8v8NnxIRlfG0N51p5yFaOentQ==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT"
+ },
+ "node_modules/@fastify/fast-json-stringify-compiler": {
+ "version": "5.1.0",
+ "resolved": "https://registry.npmjs.org/@fastify/fast-json-stringify-compiler/-/fast-json-stringify-compiler-5.1.0.tgz",
+ "integrity": "sha512-PxcYtKLbQ8Z+yApiqjK8FwxIwvEj38k2OiLc17u8dkJSlmfi2wHHPaSnaoqBPQqtvF8YVsDgDpP2snDCfFrpfw==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "fast-json-stringify": "^7.0.0"
+ }
+ },
+ "node_modules/@fastify/forwarded": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/@fastify/forwarded/-/forwarded-3.0.2.tgz",
+ "integrity": "sha512-NE8HgKLgYejV9lDpqkEFaDKMLYelJBVfHekhB0UKvX0ghagXRJqg68feg8er1NPXxG4N9i6vPxzt8E+3wHfcmA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT"
+ },
+ "node_modules/@fastify/merge-json-schemas": {
+ "version": "0.2.1",
+ "resolved": "https://registry.npmjs.org/@fastify/merge-json-schemas/-/merge-json-schemas-0.2.1.tgz",
+ "integrity": "sha512-OA3KGBCy6KtIvLf8DINC5880o5iBlDX4SxzLQS8HorJAbqluzLRn80UXU0bxZn7UOFhFgpRJDasfwn9nG4FG4A==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "dequal": "^2.0.3"
+ }
+ },
+ "node_modules/@fastify/multipart": {
+ "version": "9.4.0",
+ "resolved": "https://registry.npmjs.org/@fastify/multipart/-/multipart-9.4.0.tgz",
+ "integrity": "sha512-Z404bzZeLSXTBmp/trCBuoVFX28pM7rhv849Q5TsbTFZHuk1lc4QjQITTPK92DKVpXmNtJXeHSSc7GYvqFpxAQ==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@fastify/busboy": "^3.0.0",
+ "@fastify/deepmerge": "^3.0.0",
+ "@fastify/error": "^4.0.0",
+ "fastify-plugin": "^5.0.0",
+ "secure-json-parse": "^4.0.0"
+ }
+ },
+ "node_modules/@fastify/proxy-addr": {
+ "version": "5.1.0",
+ "resolved": "https://registry.npmjs.org/@fastify/proxy-addr/-/proxy-addr-5.1.0.tgz",
+ "integrity": "sha512-INS+6gh91cLUjB+PVHfu1UqcB76Sqtpyp7bnL+FYojhjygvOPA9ctiD/JDKsyD9Xgu4hUhCSJBPig/w7duNajw==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@fastify/forwarded": "^3.0.0",
+ "ipaddr.js": "^2.1.0"
+ }
+ },
+ "node_modules/@ioredis/commands": {
+ "version": "1.10.0",
+ "resolved": "https://registry.npmjs.org/@ioredis/commands/-/commands-1.10.0.tgz",
+ "integrity": "sha512-UmeW7z4LfctwoQ5wkhVzgq8tXkreED2xZGpX+Bg+zA+WJFZCT6c062AfCK/Dfk81xZnnwdhJCUMkitihRaoC2Q==",
+ "license": "MIT"
+ },
+ "node_modules/@jridgewell/sourcemap-codec": {
+ "version": "1.6.0",
+ "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz",
+ "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@noble/curves": {
+ "version": "2.4.0",
+ "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-2.4.0.tgz",
+ "integrity": "sha512-P4/62zrgfH33CneE3Dn4WhJVA22YUU0eR51wKIan4NVRvwsA0YnPTwWGpNbpuacSujmSFLvyzpyuR30+fbq2Ew==",
+ "license": "MIT",
+ "dependencies": {
+ "@noble/hashes": "2.4.0"
+ },
+ "engines": {
+ "node": ">= 20.19.0"
+ },
+ "funding": {
+ "url": "https://paulmillr.com/funding/"
+ }
+ },
+ "node_modules/@noble/hashes": {
+ "version": "2.4.0",
+ "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.4.0.tgz",
+ "integrity": "sha512-X5XaVWZIBCT7HHZGm5I7ZQXDwLG+bGXuSrMQAW+7Zvl87h1kmc1ZB1VSRJcpUfoUrGQp4Fkoxm5kZ+Ms+aW+eA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 20.19.0"
+ },
+ "funding": {
+ "url": "https://paulmillr.com/funding/"
+ }
+ },
+ "node_modules/@oxc-project/types": {
+ "version": "0.148.0",
+ "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.148.0.tgz",
+ "integrity": "sha512-Nm4s/jB+4FpFsPhWGEC4h7rzksesmtnMXomo6rCMcg/b8zLQuOziRgkCS1fxDCXOlJB/6Q8oABOZ/OP6RIPj9A==",
+ "dev": true,
+ "license": "MIT",
+ "funding": {
+ "url": "https://github.com/sponsors/oxc-project"
+ }
+ },
+ "node_modules/@pinojs/redact": {
+ "version": "0.4.0",
+ "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
+ "integrity": "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==",
+ "license": "MIT"
+ },
+ "node_modules/@prisma/client": {
+ "version": "5.22.0",
+ "resolved": "https://registry.npmjs.org/@prisma/client/-/client-5.22.0.tgz",
+ "integrity": "sha512-M0SVXfyHnQREBKxCgyo7sffrKttwE6R8PMq330MIUF0pTwjUhLbW84pFDlf06B27XyCR++VtjugEnIHdr07SVA==",
+ "hasInstallScript": true,
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=16.13"
+ },
+ "peerDependencies": {
+ "prisma": "*"
+ },
+ "peerDependenciesMeta": {
+ "prisma": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/@prisma/debug": {
+ "version": "5.22.0",
+ "resolved": "https://registry.npmjs.org/@prisma/debug/-/debug-5.22.0.tgz",
+ "integrity": "sha512-AUt44v3YJeggO2ZU5BkXI7M4hu9BF2zzH2iF2V5pyXT/lRTyWiElZ7It+bRH1EshoMRxHgpYg4VB6rCM+mG5jQ==",
+ "devOptional": true,
+ "license": "Apache-2.0"
+ },
+ "node_modules/@prisma/engines": {
+ "version": "5.22.0",
+ "resolved": "https://registry.npmjs.org/@prisma/engines/-/engines-5.22.0.tgz",
+ "integrity": "sha512-UNjfslWhAt06kVL3CjkuYpHAWSO6L4kDCVPegV6itt7nD1kSJavd3vhgAEhjglLJJKEdJ7oIqDJ+yHk6qO8gPA==",
+ "devOptional": true,
+ "hasInstallScript": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@prisma/debug": "5.22.0",
+ "@prisma/engines-version": "5.22.0-44.605197351a3c8bdd595af2d2a9bc3025bca48ea2",
+ "@prisma/fetch-engine": "5.22.0",
+ "@prisma/get-platform": "5.22.0"
+ }
+ },
+ "node_modules/@prisma/engines-version": {
+ "version": "5.22.0-44.605197351a3c8bdd595af2d2a9bc3025bca48ea2",
+ "resolved": "https://registry.npmjs.org/@prisma/engines-version/-/engines-version-5.22.0-44.605197351a3c8bdd595af2d2a9bc3025bca48ea2.tgz",
+ "integrity": "sha512-2PTmxFR2yHW/eB3uqWtcgRcgAbG1rwG9ZriSvQw+nnb7c4uCr3RAcGMb6/zfE88SKlC1Nj2ziUvc96Z379mHgQ==",
+ "devOptional": true,
+ "license": "Apache-2.0"
+ },
+ "node_modules/@prisma/fetch-engine": {
+ "version": "5.22.0",
+ "resolved": "https://registry.npmjs.org/@prisma/fetch-engine/-/fetch-engine-5.22.0.tgz",
+ "integrity": "sha512-bkrD/Mc2fSvkQBV5EpoFcZ87AvOgDxbG99488a5cexp5Ccny+UM6MAe/UFkUC0wLYD9+9befNOqGiIJhhq+HbA==",
+ "devOptional": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@prisma/debug": "5.22.0",
+ "@prisma/engines-version": "5.22.0-44.605197351a3c8bdd595af2d2a9bc3025bca48ea2",
+ "@prisma/get-platform": "5.22.0"
+ }
+ },
+ "node_modules/@prisma/get-platform": {
+ "version": "5.22.0",
+ "resolved": "https://registry.npmjs.org/@prisma/get-platform/-/get-platform-5.22.0.tgz",
+ "integrity": "sha512-pHhpQdr1UPFpt+zFfnPazhulaZYCUqeIcPpJViYoq9R+D/yw4fjE+CtnsnKzPYm0ddUbeXUzjGVGIRVgPDCk4Q==",
+ "devOptional": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@prisma/debug": "5.22.0"
+ }
+ },
+ "node_modules/@rolldown/binding-android-arm-eabi": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.7.tgz",
+ "integrity": "sha512-EypzgnYCwyVY4NDHKzGmNJT5b+XaQEBniHxsMdeIQLB/tcCzZnhqrzHpZFbX9iaxx+5RiB8caATBtfvZP7zVxQ==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-android-arm64": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.2.7.tgz",
+ "integrity": "sha512-l17HE9EweWaqJZhuUuNBN/FzM62xw+DECVnJyvMsxn8vJFAGLy5QfLDoYAcronkAN8VxKZHezDpulHDPx95vFw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-darwin-arm64": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.2.7.tgz",
+ "integrity": "sha512-8ED8ELFvHXc6OCETIn4gXObPiaR6bckM/ipXtbzlPVDRMBfEGjCKgO90F9YtfdpDatVx/ZQw7aZ1vUMf/+T3Mw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-darwin-x64": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.2.7.tgz",
+ "integrity": "sha512-/WPripjtiAIZ2tWY7ddijORT0Ujg87wxWW/qcoFVCKAWVDPhtY0xr7Dj0M3GyNGz60jGwTElhro/mkF9dT7dDQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-freebsd-x64": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.2.7.tgz",
+ "integrity": "sha512-14DI4NcqpvbICxSnGLx3PmtDaWqRP/KGSGb6C+JLLVPeZRl6dKdHba3pGsqT3vpdTqhEYIPG0MMQ8c0xYqoJxA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.2.7.tgz",
+ "integrity": "sha512-bxrWIRvHWQvbJwi+VIie/kDJmQxcNE6xxWwZdqF/ExVAigtHkv54WTLQPb+QsZdnFy18fg7JPfWGL0RH6vwIlQ==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-linux-arm64-gnu": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.7.tgz",
+ "integrity": "sha512-toOY2BChBZyuxU7OYX6Tn389di4IzAqPTycVcci0O7FSfBqzRB3RZn+K5Is6ANf4tmgRd/K1yZTsNTXbkXsnLg==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-linux-arm64-musl": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.7.tgz",
+ "integrity": "sha512-lAIXTH/aiLRLxsTgQvfhjo4K1ydWIp00+V0voOr9beb/9ZmkUFrSIb03dXNFRgMNvkE6oGsF10ioQ6UsI+vS5Q==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-linux-ppc64-gnu": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.2.7.tgz",
+ "integrity": "sha512-kdnwS28Pkenp/mZMRwjXXXwxQ7pIsm+bF919LUK93BOyhcLsrVKdP2p9fxpiPNPAbNuch8ypQt0pm2P2LYCAGg==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-linux-s390x-gnu": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.2.7.tgz",
+ "integrity": "sha512-516OdsyLdr5E65paF3yBF55t8mfm9+gmtCsK3xI7XKXIT7EfRlHhxL8K/NR6Hu8BWSgF5+1w74lTL0+nxcc8Qw==",
+ "cpu": [
+ "s390x"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-linux-x64-gnu": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.7.tgz",
+ "integrity": "sha512-r8/z8n7GFaYRln3xmP1Cxy0HH/HLM0uBUPkEuSVEfKGDA89M0FsZRZJRSwe/tJjRx+fpH/gjorfhB8tmEbSFLA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-linux-x64-musl": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.7.tgz",
+ "integrity": "sha512-pAsE8iiDxUg1xBqdhrTfg45AVDVpirjz00sblEYClGNNcMnDb+e8beQgqIAw6LvauX/APvgxUnwrgun/YYGBhw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-openharmony-arm64": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.2.7.tgz",
+ "integrity": "sha512-lTcIYmmnQQA8Or/2DatS6oSqcdLHvendjS+zLu+FwgToynWMRSmQdpM65fTANJgIS4mjbMOo5KT2lnT9SAb96w==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openharmony"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-win32-arm64-msvc": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.7.tgz",
+ "integrity": "sha512-e3Gu3WxbNk/UqQhxqU7YIYO+9ZBvWNz3U+h/qRFosscMFzdRPbXYSaSWgSnklv2fz1TgzBTcti2z35c/7irsHw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/binding-win32-x64-msvc": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.7.tgz",
+ "integrity": "sha512-W/jg5qoRSqjsEv0+dZi4e687mcHqmVuU0P4fK6qS/xjetW2Gmc1W8j//z5nAeNcC8Ttm0hV46IjcYeuVwYhuiw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ }
+ },
+ "node_modules/@rolldown/pluginutils": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
+ "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@standard-schema/spec": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+ "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@types/chai": {
+ "version": "5.2.3",
+ "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+ "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/deep-eql": "*",
+ "assertion-error": "^2.0.1"
+ }
+ },
+ "node_modules/@types/deep-eql": {
+ "version": "4.0.2",
+ "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+ "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@types/estree": {
+ "version": "1.0.9",
+ "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+ "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@types/http-proxy": {
+ "version": "1.17.17",
+ "resolved": "https://registry.npmjs.org/@types/http-proxy/-/http-proxy-1.17.17.tgz",
+ "integrity": "sha512-ED6LB+Z1AVylNTu7hdzuBqOgMnvG/ld6wGCG8wFnAzKX5uyW2K3WD52v0gnLCTK/VLpXtKckgWuyScYK6cSPaw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/node": "*"
+ }
+ },
+ "node_modules/@types/node": {
+ "version": "20.19.43",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+ "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~6.21.0"
+ }
+ },
+ "node_modules/@types/ws": {
+ "version": "8.18.1",
+ "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+ "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/node": "*"
+ }
+ },
+ "node_modules/@vitest/expect": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.11.tgz",
+ "integrity": "sha512-VX2x5vNJXET47KAFzwERI+KRMtTTCSWTfSMKsW7JsUsXV4psq++e3DvZpuTDOpHcxytiDs6p2nhVb2tVDiiUYw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@standard-schema/spec": "^1.1.0",
+ "@types/chai": "^5.2.2",
+ "@vitest/spy": "4.1.11",
+ "@vitest/utils": "4.1.11",
+ "chai": "^6.2.2",
+ "tinyrainbow": "^3.1.0"
+ },
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ }
+ },
+ "node_modules/@vitest/mocker": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.11.tgz",
+ "integrity": "sha512-2XJVD55d1o5AZous5CCGKS74g/riOj9odEt2bQpCVZeblHyHdnMeFl4jl0XjU21stf4mbjUkew2eXQZt65g5CQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vitest/spy": "4.1.11",
+ "estree-walker": "^3.0.3",
+ "magic-string": "^0.30.21"
+ },
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ },
+ "peerDependencies": {
+ "msw": "^2.4.9",
+ "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+ },
+ "peerDependenciesMeta": {
+ "msw": {
+ "optional": true
+ },
+ "vite": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/@vitest/pretty-format": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.11.tgz",
+ "integrity": "sha512-yiZzPbGTS9Sr/JpFl8zHrcIkAofNbFV6k21vIgQN/cY/oxZeXhJv5sc/MBJ5jFKWmWs+oJHw0UXLZjmf931+Vw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "tinyrainbow": "^3.1.0"
+ },
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ }
+ },
+ "node_modules/@vitest/runner": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.11.tgz",
+ "integrity": "sha512-LztvUgdwMNJMIkj3hQnnxiC2Xy1zNxq928W/xhjCLaNCzqTZOudjwbQf6v9IntZGPw132i2Lq2rgTRZHD3JHNw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vitest/utils": "4.1.11",
+ "pathe": "^2.0.3"
+ },
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ }
+ },
+ "node_modules/@vitest/snapshot": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.11.tgz",
+ "integrity": "sha512-pN7ikn1ON7h8ee4gIAp4AzyK+zBtJPzVbqOgu5LCEh4VaJVbPQcgYQYJIMGQPXVeJJq1fnfazis7a5pFNPahog==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vitest/pretty-format": "4.1.11",
+ "@vitest/utils": "4.1.11",
+ "magic-string": "^0.30.21",
+ "pathe": "^2.0.3"
+ },
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ }
+ },
+ "node_modules/@vitest/spy": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.11.tgz",
+ "integrity": "sha512-apNa/prQy2qCeywhnixOHPRCgGNhvg7T4Dapfl1GahLp/R+uhBm5cPyFoNVyqsNd2h1nJxL6BqqdIjiABL60YA==",
+ "dev": true,
+ "license": "MIT",
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ }
+ },
+ "node_modules/@vitest/utils": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.11.tgz",
+ "integrity": "sha512-zTCVGpyFsGWBhllOyKlTw/vnr6D9qxsfSDyfbyZmTyjHw5N/VuvzHpHoQjm2ZJzn4RJgx5w4r7V0er69CmLgPQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vitest/pretty-format": "4.1.11",
+ "convert-source-map": "^2.0.0",
+ "tinyrainbow": "^3.1.0"
+ },
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ }
+ },
+ "node_modules/abstract-logging": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/abstract-logging/-/abstract-logging-2.0.1.tgz",
+ "integrity": "sha512-2BjRTZxTPvheOvGbBslFSYOUkr+SjPtOnrLP33f+VIWLzezQpZcqVg7ja3L4dBXmzzgwT+a029jRx5PCi3JuiA==",
+ "license": "MIT"
+ },
+ "node_modules/ajv": {
+ "version": "8.20.0",
+ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+ "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+ "license": "MIT",
+ "dependencies": {
+ "fast-deep-equal": "^3.1.3",
+ "fast-uri": "^3.0.1",
+ "json-schema-traverse": "^1.0.0",
+ "require-from-string": "^2.0.2"
+ },
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/sponsors/epoberezkin"
+ }
+ },
+ "node_modules/ajv-formats": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
+ "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+ "license": "MIT",
+ "dependencies": {
+ "ajv": "^8.0.0"
+ },
+ "peerDependencies": {
+ "ajv": "^8.0.0"
+ },
+ "peerDependenciesMeta": {
+ "ajv": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/ajv/node_modules/fast-uri": {
+ "version": "3.1.7",
+ "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.7.tgz",
+ "integrity": "sha512-dOvZVzjdZdz7phd9v6jCbwxrBW3fK6n8Rc0CtdmM4bumzMnxywBYhuph6J819RRw/ku+rLbelwfMunktuzVVHg==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/ansi-regex": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+ "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/ansi-styles": {
+ "version": "4.3.0",
+ "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+ "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "color-convert": "^2.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ },
+ "funding": {
+ "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+ }
+ },
+ "node_modules/assertion-error": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+ "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/atomic-sleep": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/atomic-sleep/-/atomic-sleep-1.0.0.tgz",
+ "integrity": "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=8.0.0"
+ }
+ },
+ "node_modules/avvio": {
+ "version": "9.3.0",
+ "resolved": "https://registry.npmjs.org/avvio/-/avvio-9.3.0.tgz",
+ "integrity": "sha512-g2tQ7LE7oOSqDfwEm3M+ZCMTJc7KiZCdJ4UwyZJb5ckTKyYu50OYmvv0mCFXPuYXoM4zkSt8zM9XQ9KCvxA74A==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@fastify/error": "^4.0.0",
+ "fastq": "^1.17.1"
+ }
+ },
+ "node_modules/chai": {
+ "version": "6.2.2",
+ "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+ "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/chalk": {
+ "version": "4.1.2",
+ "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
+ "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ansi-styles": "^4.1.0",
+ "supports-color": "^7.1.0"
+ },
+ "engines": {
+ "node": ">=10"
+ },
+ "funding": {
+ "url": "https://github.com/chalk/chalk?sponsor=1"
+ }
+ },
+ "node_modules/chalk/node_modules/supports-color": {
+ "version": "7.2.0",
+ "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+ "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "has-flag": "^4.0.0"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/cliui": {
+ "version": "8.0.1",
+ "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+ "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+ "dev": true,
+ "license": "ISC",
+ "dependencies": {
+ "string-width": "^4.2.0",
+ "strip-ansi": "^6.0.1",
+ "wrap-ansi": "^7.0.0"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/cluster-key-slot": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/cluster-key-slot/-/cluster-key-slot-1.1.1.tgz",
+ "integrity": "sha512-rwHwUfXL40Chm1r08yrhU3qpUvdVlgkKNeyeGPOxnW8/SyVDvgRaed/Uz54AqWNaTCAThlj6QAs3TZcKI0xDEw==",
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/color-convert": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+ "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "color-name": "~1.1.4"
+ },
+ "engines": {
+ "node": ">=7.0.0"
+ }
+ },
+ "node_modules/color-name": {
+ "version": "1.1.4",
+ "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+ "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/concurrently": {
+ "version": "9.2.4",
+ "resolved": "https://registry.npmjs.org/concurrently/-/concurrently-9.2.4.tgz",
+ "integrity": "sha512-TZ0CEhyzvFjgtAvHTusDMgj7wNdihCh7LLLrzdUOXIhdlnL2JBBGA9eJxR24rtqgmdjh3OA3hrN1rCHj6HM8qA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "chalk": "4.1.2",
+ "rxjs": "7.8.2",
+ "shell-quote": "1.9.0",
+ "supports-color": "8.1.1",
+ "tree-kill": "1.2.2",
+ "yargs": "17.7.2"
+ },
+ "bin": {
+ "conc": "dist/bin/concurrently.js",
+ "concurrently": "dist/bin/concurrently.js"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/open-cli-tools/concurrently?sponsor=1"
+ }
+ },
+ "node_modules/convert-source-map": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
+ "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/cookie": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz",
+ "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/debug": {
+ "version": "4.4.3",
+ "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+ "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+ "license": "MIT",
+ "dependencies": {
+ "ms": "^2.1.3"
+ },
+ "engines": {
+ "node": ">=6.0"
+ },
+ "peerDependenciesMeta": {
+ "supports-color": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/denque": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/denque/-/denque-2.1.0.tgz",
+ "integrity": "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==",
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=0.10"
+ }
+ },
+ "node_modules/dequal": {
+ "version": "2.0.3",
+ "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
+ "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/detect-libc": {
+ "version": "2.1.2",
+ "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+ "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/dotenv": {
+ "version": "17.4.2",
+ "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.4.2.tgz",
+ "integrity": "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==",
+ "license": "BSD-2-Clause",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://dotenvx.com"
+ }
+ },
+ "node_modules/emoji-regex": {
+ "version": "8.0.0",
+ "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+ "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/es-module-lexer": {
+ "version": "2.3.2",
+ "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
+ "integrity": "sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/esbuild": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
+ "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "bin": {
+ "esbuild": "bin/esbuild"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "optionalDependencies": {
+ "@esbuild/aix-ppc64": "0.27.7",
+ "@esbuild/android-arm": "0.27.7",
+ "@esbuild/android-arm64": "0.27.7",
+ "@esbuild/android-x64": "0.27.7",
+ "@esbuild/darwin-arm64": "0.27.7",
+ "@esbuild/darwin-x64": "0.27.7",
+ "@esbuild/freebsd-arm64": "0.27.7",
+ "@esbuild/freebsd-x64": "0.27.7",
+ "@esbuild/linux-arm": "0.27.7",
+ "@esbuild/linux-arm64": "0.27.7",
+ "@esbuild/linux-ia32": "0.27.7",
+ "@esbuild/linux-loong64": "0.27.7",
+ "@esbuild/linux-mips64el": "0.27.7",
+ "@esbuild/linux-ppc64": "0.27.7",
+ "@esbuild/linux-riscv64": "0.27.7",
+ "@esbuild/linux-s390x": "0.27.7",
+ "@esbuild/linux-x64": "0.27.7",
+ "@esbuild/netbsd-arm64": "0.27.7",
+ "@esbuild/netbsd-x64": "0.27.7",
+ "@esbuild/openbsd-arm64": "0.27.7",
+ "@esbuild/openbsd-x64": "0.27.7",
+ "@esbuild/openharmony-arm64": "0.27.7",
+ "@esbuild/sunos-x64": "0.27.7",
+ "@esbuild/win32-arm64": "0.27.7",
+ "@esbuild/win32-ia32": "0.27.7",
+ "@esbuild/win32-x64": "0.27.7"
+ }
+ },
+ "node_modules/escalade": {
+ "version": "3.2.0",
+ "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+ "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/estree-walker": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+ "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/estree": "^1.0.0"
+ }
+ },
+ "node_modules/eventemitter3": {
+ "version": "4.0.7",
+ "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz",
+ "integrity": "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==",
+ "license": "MIT"
+ },
+ "node_modules/expect-type": {
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
+ "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=12.0.0"
+ }
+ },
+ "node_modules/fast-decode-uri-component": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/fast-decode-uri-component/-/fast-decode-uri-component-1.0.1.tgz",
+ "integrity": "sha512-WKgKWg5eUxvRZGwW8FvfbaH7AXSh2cL+3j5fMGzUMCxWBJ3dV3a7Wz8y2f/uQ0e3B6WmodD3oS54jTQ9HVTIIg==",
+ "license": "MIT"
+ },
+ "node_modules/fast-deep-equal": {
+ "version": "3.1.3",
+ "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+ "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+ "license": "MIT"
+ },
+ "node_modules/fast-json-stringify": {
+ "version": "7.0.1",
+ "resolved": "https://registry.npmjs.org/fast-json-stringify/-/fast-json-stringify-7.0.1.tgz",
+ "integrity": "sha512-eRSayARSbbwlBjpP4vnTTIRD5QPcIrmihPxDeN1DtKnHPg66UuJLx+8hlK1kaFdjvzyQ/dzALoi4vwAQ+T+iZA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@fastify/merge-json-schemas": "^0.2.0",
+ "ajv": "^8.12.0",
+ "ajv-formats": "^3.0.1",
+ "fast-uri": "^4.0.0",
+ "json-schema-ref-resolver": "^3.0.0",
+ "rfdc": "^1.2.0"
+ }
+ },
+ "node_modules/fast-querystring": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/fast-querystring/-/fast-querystring-1.1.2.tgz",
+ "integrity": "sha512-g6KuKWmFXc0fID8WWH0jit4g0AGBoJhCkJMb1RmbsSEUNvQ+ZC8D6CUZ+GtF8nMzSPXnhiePyyqqipzNNEnHjg==",
+ "license": "MIT",
+ "dependencies": {
+ "fast-decode-uri-component": "^1.0.1"
+ }
+ },
+ "node_modules/fast-uri": {
+ "version": "4.1.4",
+ "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-4.1.4.tgz",
+ "integrity": "sha512-dODXrIxlS9JSdgAnhIUKOosKV1oMtU2VtVw87QRaHzyl5jxO290Ii5tEZfCfzfWNHi3jKWwBSdQj0qIyshdZdQ==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/fastify": {
+ "version": "5.12.1",
+ "resolved": "https://registry.npmjs.org/fastify/-/fastify-5.12.1.tgz",
+ "integrity": "sha512-FWi+tQvwxR/PeRX7Z2mhfEF5ozJ3jn9asiiclzKXNSzJRHAYcU924aIOKAdHFJ+YIKieh3cqr1IwCOvTr41B3Q==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@fastify/ajv-compiler": "^4.0.5",
+ "@fastify/error": "^4.0.0",
+ "@fastify/fast-json-stringify-compiler": "^5.0.0",
+ "@fastify/proxy-addr": "^5.0.0",
+ "abstract-logging": "^2.0.1",
+ "avvio": "^9.0.0",
+ "fast-json-stringify": "^7.0.0",
+ "find-my-way": "^9.6.0",
+ "light-my-request": "^6.0.0",
+ "pino": "^9.14.0 || ^10.1.0",
+ "process-warning": "^5.1.0",
+ "rfdc": "^1.3.1",
+ "secure-json-parse": "^4.0.0",
+ "semver": "^7.6.0",
+ "toad-cache": "^3.7.0"
+ }
+ },
+ "node_modules/fastify-plugin": {
+ "version": "5.1.0",
+ "resolved": "https://registry.npmjs.org/fastify-plugin/-/fastify-plugin-5.1.0.tgz",
+ "integrity": "sha512-FAIDA8eovSt5qcDgcBvDuX/v0Cjz0ohGhENZ/wpc3y+oZCY2afZ9Baqql3g/lC+OHRnciQol4ww7tuthOb9idw==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT"
+ },
+ "node_modules/fastq": {
+ "version": "1.20.3",
+ "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.3.tgz",
+ "integrity": "sha512-XKv5nnLs6nLF71NgiKJLIZFLkPyIEuOselLG7ujZnGrRfQK8HpvY+WqKhAJUAdLomwVHErVS4LfxFlPq0/FTAw==",
+ "license": "ISC",
+ "dependencies": {
+ "reusify": "^1.0.4"
+ }
+ },
+ "node_modules/fdir": {
+ "version": "6.5.0",
+ "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+ "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=12.0.0"
+ },
+ "peerDependencies": {
+ "picomatch": "^3 || ^4"
+ },
+ "peerDependenciesMeta": {
+ "picomatch": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/find-my-way": {
+ "version": "9.9.0",
+ "resolved": "https://registry.npmjs.org/find-my-way/-/find-my-way-9.9.0.tgz",
+ "integrity": "sha512-sJsgZ1sQH2UDuowPuMKg8az7Qc8F0jnj+SKkFWU/+T0xcFlgV5skgXOGUqmQzOdmW6ALA7AhJINWx3qFBkbLHA==",
+ "license": "MIT",
+ "dependencies": {
+ "fast-deep-equal": "^3.1.3",
+ "fast-querystring": "^1.0.0",
+ "safe-regex2": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ },
+ "node_modules/follow-redirects": {
+ "version": "1.16.0",
+ "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
+ "integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
+ "funding": [
+ {
+ "type": "individual",
+ "url": "https://github.com/sponsors/RubenVerborgh"
+ }
+ ],
+ "license": "MIT",
+ "engines": {
+ "node": ">=4.0"
+ },
+ "peerDependenciesMeta": {
+ "debug": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/fsevents": {
+ "version": "2.3.3",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+ "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+ }
+ },
+ "node_modules/get-caller-file": {
+ "version": "2.0.5",
+ "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+ "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": "6.* || 8.* || >= 10.*"
+ }
+ },
+ "node_modules/has-flag": {
+ "version": "4.0.0",
+ "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+ "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/http-proxy": {
+ "version": "1.18.1",
+ "resolved": "https://registry.npmjs.org/http-proxy/-/http-proxy-1.18.1.tgz",
+ "integrity": "sha512-7mz/721AbnJwIVbnaSv1Cz3Am0ZLT/UBwkC92VlxhXv/k/BBQfM2fXElQNC27BVGr0uwUpplYPQM9LnaBMR5NQ==",
+ "license": "MIT",
+ "dependencies": {
+ "eventemitter3": "^4.0.0",
+ "follow-redirects": "^1.0.0",
+ "requires-port": "^1.0.0"
+ },
+ "engines": {
+ "node": ">=8.0.0"
+ }
+ },
+ "node_modules/ioredis": {
+ "version": "5.11.1",
+ "resolved": "https://registry.npmjs.org/ioredis/-/ioredis-5.11.1.tgz",
+ "integrity": "sha512-ehuGcf94bQXhfagULNXrJdfnWO38v070jxSx/qE87Kjzmu2fU7ro5EFAb+OPituLqgfyuQaym5DlrNydW2sJ9A==",
+ "license": "MIT",
+ "dependencies": {
+ "@ioredis/commands": "1.10.0",
+ "cluster-key-slot": "1.1.1",
+ "debug": "4.4.3",
+ "denque": "2.1.0",
+ "redis-errors": "1.2.0",
+ "redis-parser": "3.0.0",
+ "standard-as-callback": "2.1.0"
+ },
+ "engines": {
+ "node": ">=12.22.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/ioredis"
+ }
+ },
+ "node_modules/ipaddr.js": {
+ "version": "2.5.0",
+ "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-2.5.0.tgz",
+ "integrity": "sha512-aq+t5NAc+cS6rZQQVWC2x98CPqGtKKTMDd4Gaodv0wShnItdKg/51djkGJ1hqH+Oy0ivDftCbSLCQob8zso01w==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 10"
+ }
+ },
+ "node_modules/is-fullwidth-code-point": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+ "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/json-schema-ref-resolver": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/json-schema-ref-resolver/-/json-schema-ref-resolver-3.0.0.tgz",
+ "integrity": "sha512-hOrZIVL5jyYFjzk7+y7n5JDzGlU8rfWDuYyHwGa2WA8/pcmMHezp2xsVwxrebD/Q9t8Nc5DboieySDpCp4WG4A==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "dequal": "^2.0.3"
+ }
+ },
+ "node_modules/json-schema-traverse": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+ "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+ "license": "MIT"
+ },
+ "node_modules/light-my-request": {
+ "version": "6.6.0",
+ "resolved": "https://registry.npmjs.org/light-my-request/-/light-my-request-6.6.0.tgz",
+ "integrity": "sha512-CHYbu8RtboSIoVsHZ6Ye4cj4Aw/yg2oAFimlF7mNvfDV192LR7nDiKtSIfCuLT7KokPSTn/9kfVLm5OGN0A28A==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "cookie": "^1.0.1",
+ "process-warning": "^4.0.0",
+ "set-cookie-parser": "^2.6.0"
+ }
+ },
+ "node_modules/light-my-request/node_modules/process-warning": {
+ "version": "4.0.1",
+ "resolved": "https://registry.npmjs.org/process-warning/-/process-warning-4.0.1.tgz",
+ "integrity": "sha512-3c2LzQ3rY9d0hc1emcsHhfT9Jwz0cChib/QN89oME2R451w5fy3f0afAhERFZAwrbDU43wk12d0ORBpDVME50Q==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT"
+ },
+ "node_modules/lightningcss": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz",
+ "integrity": "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==",
+ "dev": true,
+ "license": "MPL-2.0",
+ "dependencies": {
+ "detect-libc": "^2.0.3"
+ },
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ },
+ "optionalDependencies": {
+ "lightningcss-android-arm64": "1.33.0",
+ "lightningcss-darwin-arm64": "1.33.0",
+ "lightningcss-darwin-x64": "1.33.0",
+ "lightningcss-freebsd-x64": "1.33.0",
+ "lightningcss-linux-arm-gnueabihf": "1.33.0",
+ "lightningcss-linux-arm64-gnu": "1.33.0",
+ "lightningcss-linux-arm64-musl": "1.33.0",
+ "lightningcss-linux-x64-gnu": "1.33.0",
+ "lightningcss-linux-x64-musl": "1.33.0",
+ "lightningcss-win32-arm64-msvc": "1.33.0",
+ "lightningcss-win32-x64-msvc": "1.33.0"
+ }
+ },
+ "node_modules/lightningcss-android-arm64": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.33.0.tgz",
+ "integrity": "sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-darwin-arm64": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.33.0.tgz",
+ "integrity": "sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-darwin-x64": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.33.0.tgz",
+ "integrity": "sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-freebsd-x64": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.33.0.tgz",
+ "integrity": "sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-linux-arm-gnueabihf": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.33.0.tgz",
+ "integrity": "sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-linux-arm64-gnu": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.33.0.tgz",
+ "integrity": "sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-linux-arm64-musl": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.33.0.tgz",
+ "integrity": "sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-linux-x64-gnu": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.33.0.tgz",
+ "integrity": "sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-linux-x64-musl": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.33.0.tgz",
+ "integrity": "sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-win32-arm64-msvc": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.33.0.tgz",
+ "integrity": "sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/lightningcss-win32-x64-msvc": {
+ "version": "1.33.0",
+ "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.33.0.tgz",
+ "integrity": "sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MPL-2.0",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">= 12.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/magic-string": {
+ "version": "0.30.21",
+ "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+ "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@jridgewell/sourcemap-codec": "^1.5.5"
+ }
+ },
+ "node_modules/mnemonist": {
+ "version": "0.40.0",
+ "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.40.0.tgz",
+ "integrity": "sha512-kdd8AFNig2AD5Rkih7EPCXhu/iMvwevQFX/uEiGhZyPZi7fHqOoF4V4kHLpCfysxXMgQ4B52kdPMCwARshKvEg==",
+ "license": "MIT",
+ "dependencies": {
+ "obliterator": "^2.0.4"
+ }
+ },
+ "node_modules/ms": {
+ "version": "2.1.3",
+ "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+ "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+ "license": "MIT"
+ },
+ "node_modules/nanoid": {
+ "version": "3.3.18",
+ "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+ "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/ai"
+ }
+ ],
+ "license": "MIT",
+ "bin": {
+ "nanoid": "bin/nanoid.cjs"
+ },
+ "engines": {
+ "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+ }
+ },
+ "node_modules/obliterator": {
+ "version": "2.0.5",
+ "resolved": "https://registry.npmjs.org/obliterator/-/obliterator-2.0.5.tgz",
+ "integrity": "sha512-42CPE9AhahZRsMNslczq0ctAEtqk8Eka26QofnqC346BZdHDySk3LWka23LI7ULIw11NmltpiLagIq8gBozxTw==",
+ "license": "MIT"
+ },
+ "node_modules/obug": {
+ "version": "2.1.4",
+ "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.4.tgz",
+ "integrity": "sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==",
+ "dev": true,
+ "funding": [
+ "https://github.com/sponsors/sxzz",
+ "https://opencollective.com/debug"
+ ],
+ "license": "MIT",
+ "engines": {
+ "node": ">=12.20.0"
+ }
+ },
+ "node_modules/on-exit-leak-free": {
+ "version": "2.1.2",
+ "resolved": "https://registry.npmjs.org/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz",
+ "integrity": "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=14.0.0"
+ }
+ },
+ "node_modules/pathe": {
+ "version": "2.0.3",
+ "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+ "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/picocolors": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+ "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+ "dev": true,
+ "license": "ISC"
+ },
+ "node_modules/picomatch": {
+ "version": "4.0.7",
+ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",
+ "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/jonschlinkert"
+ }
+ },
+ "node_modules/pino": {
+ "version": "10.3.1",
+ "resolved": "https://registry.npmjs.org/pino/-/pino-10.3.1.tgz",
+ "integrity": "sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg==",
+ "license": "MIT",
+ "dependencies": {
+ "@pinojs/redact": "^0.4.0",
+ "atomic-sleep": "^1.0.0",
+ "on-exit-leak-free": "^2.1.0",
+ "pino-abstract-transport": "^3.0.0",
+ "pino-std-serializers": "^7.0.0",
+ "process-warning": "^5.0.0",
+ "quick-format-unescaped": "^4.0.3",
+ "real-require": "^0.2.0",
+ "safe-stable-stringify": "^2.3.1",
+ "sonic-boom": "^4.0.1",
+ "thread-stream": "^4.0.0"
+ },
+ "bin": {
+ "pino": "bin.js"
+ }
+ },
+ "node_modules/pino-abstract-transport": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz",
+ "integrity": "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==",
+ "license": "MIT",
+ "dependencies": {
+ "split2": "^4.0.0"
+ }
+ },
+ "node_modules/pino-std-serializers": {
+ "version": "7.1.0",
+ "resolved": "https://registry.npmjs.org/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz",
+ "integrity": "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==",
+ "license": "MIT"
+ },
+ "node_modules/postcss": {
+ "version": "8.5.28",
+ "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.28.tgz",
+ "integrity": "sha512-RRuzqDtt5Y9h3quz5hWhK+TPnsmVs6WwSU6LkJMeY4HstUEDuYTG8UJSdawMRzmzAtV+KEoG8N3Qg2qLy5vM/A==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/postcss/"
+ },
+ {
+ "type": "tidelift",
+ "url": "https://tidelift.com/funding/github/npm/postcss"
+ },
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/ai"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "nanoid": "^3.3.18",
+ "picocolors": "^1.1.1",
+ "source-map-js": "^1.2.1"
+ },
+ "engines": {
+ "node": "^10 || ^12 || >=14"
+ }
+ },
+ "node_modules/prisma": {
+ "version": "5.22.0",
+ "resolved": "https://registry.npmjs.org/prisma/-/prisma-5.22.0.tgz",
+ "integrity": "sha512-vtpjW3XuYCSnMsNVBjLMNkTj6OZbudcPPTPYHqX0CJfpcdWciI1dM8uHETwmDxxiqEwCIE6WvXucWUetJgfu/A==",
+ "devOptional": true,
+ "hasInstallScript": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@prisma/engines": "5.22.0"
+ },
+ "bin": {
+ "prisma": "build/index.js"
+ },
+ "engines": {
+ "node": ">=16.13"
+ },
+ "optionalDependencies": {
+ "fsevents": "2.3.3"
+ }
+ },
+ "node_modules/process-warning": {
+ "version": "5.1.0",
+ "resolved": "https://registry.npmjs.org/process-warning/-/process-warning-5.1.0.tgz",
+ "integrity": "sha512-jQSaVHsPgtyw60e1rQ/A+/ArPEj/S8pS/vFnyGa/gYFXrKk/6RuDkoqVDQ5NI5MmS01698ltlAk0NoDBNLujRw==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT"
+ },
+ "node_modules/quick-format-unescaped": {
+ "version": "4.0.4",
+ "resolved": "https://registry.npmjs.org/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz",
+ "integrity": "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==",
+ "license": "MIT"
+ },
+ "node_modules/real-require": {
+ "version": "0.2.0",
+ "resolved": "https://registry.npmjs.org/real-require/-/real-require-0.2.0.tgz",
+ "integrity": "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 12.13.0"
+ }
+ },
+ "node_modules/redis-errors": {
+ "version": "1.2.0",
+ "resolved": "https://registry.npmjs.org/redis-errors/-/redis-errors-1.2.0.tgz",
+ "integrity": "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=4"
+ }
+ },
+ "node_modules/redis-parser": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/redis-parser/-/redis-parser-3.0.0.tgz",
+ "integrity": "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A==",
+ "license": "MIT",
+ "dependencies": {
+ "redis-errors": "^1.0.0"
+ },
+ "engines": {
+ "node": ">=4"
+ }
+ },
+ "node_modules/require-directory": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+ "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/require-from-string": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+ "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/requires-port": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
+ "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==",
+ "license": "MIT"
+ },
+ "node_modules/ret": {
+ "version": "0.5.0",
+ "resolved": "https://registry.npmjs.org/ret/-/ret-0.5.0.tgz",
+ "integrity": "sha512-I1XxrZSQ+oErkRR4jYbAyEEu2I0avBvvMM5JN+6EBprOGRCs63ENqZ3vjavq8fBw2+62G5LF5XelKwuJpcvcxw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/reusify": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz",
+ "integrity": "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==",
+ "license": "MIT",
+ "engines": {
+ "iojs": ">=1.0.0",
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/rfdc": {
+ "version": "1.4.1",
+ "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz",
+ "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==",
+ "license": "MIT"
+ },
+ "node_modules/rolldown": {
+ "version": "1.2.7",
+ "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.7.tgz",
+ "integrity": "sha512-g0EtLvBjTUB7jhyV0S/TCup3v/XSVl45vUIGbOGU4QPiyjTenCe4mKuFvW9fEgYmS2Fo42AUssRmNuMziXdrig==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@oxc-project/types": "=0.148.0",
+ "@rolldown/pluginutils": "^1.0.0"
+ },
+ "bin": {
+ "rolldown": "bin/cli.mjs"
+ },
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ },
+ "optionalDependencies": {
+ "@rolldown/binding-android-arm-eabi": "1.2.7",
+ "@rolldown/binding-android-arm64": "1.2.7",
+ "@rolldown/binding-darwin-arm64": "1.2.7",
+ "@rolldown/binding-darwin-x64": "1.2.7",
+ "@rolldown/binding-freebsd-x64": "1.2.7",
+ "@rolldown/binding-linux-arm-gnueabihf": "1.2.7",
+ "@rolldown/binding-linux-arm64-gnu": "1.2.7",
+ "@rolldown/binding-linux-arm64-musl": "1.2.7",
+ "@rolldown/binding-linux-ppc64-gnu": "1.2.7",
+ "@rolldown/binding-linux-s390x-gnu": "1.2.7",
+ "@rolldown/binding-linux-x64-gnu": "1.2.7",
+ "@rolldown/binding-linux-x64-musl": "1.2.7",
+ "@rolldown/binding-openharmony-arm64": "1.2.7",
+ "@rolldown/binding-win32-arm64-msvc": "1.2.7",
+ "@rolldown/binding-win32-x64-msvc": "1.2.7"
+ }
+ },
+ "node_modules/rxjs": {
+ "version": "7.8.2",
+ "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",
+ "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "tslib": "^2.1.0"
+ }
+ },
+ "node_modules/safe-regex2": {
+ "version": "5.1.1",
+ "resolved": "https://registry.npmjs.org/safe-regex2/-/safe-regex2-5.1.1.tgz",
+ "integrity": "sha512-mOSBvHGDZMuIEZMdOz/aCEYDCv0E7nfcNsIhUF+/P+xC7Hyf3FkvymqgPbg9D1EdSGu+uKbJgy09K/RKKc7kJA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "ret": "~0.5.0"
+ },
+ "bin": {
+ "safe-regex2": "bin/safe-regex2.js"
+ }
+ },
+ "node_modules/safe-stable-stringify": {
+ "version": "2.5.0",
+ "resolved": "https://registry.npmjs.org/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz",
+ "integrity": "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/secure-json-parse": {
+ "version": "4.1.0",
+ "resolved": "https://registry.npmjs.org/secure-json-parse/-/secure-json-parse-4.1.0.tgz",
+ "integrity": "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/semver": {
+ "version": "7.8.5",
+ "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+ "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+ "license": "ISC",
+ "bin": {
+ "semver": "bin/semver.js"
+ },
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/set-cookie-parser": {
+ "version": "2.7.2",
+ "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-2.7.2.tgz",
+ "integrity": "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==",
+ "license": "MIT"
+ },
+ "node_modules/shell-quote": {
+ "version": "1.9.0",
+ "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.9.0.tgz",
+ "integrity": "sha512-Iov+JwFv/2HcTpcwNMKd8+IWNb8tboQJNQTkAY/LLVK7gGH9jy+LGkVqPxfekHl+yMmiqXszdGWXgkfml7hjqA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/siginfo": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+ "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+ "dev": true,
+ "license": "ISC"
+ },
+ "node_modules/sonic-boom": {
+ "version": "4.2.1",
+ "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
+ "integrity": "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==",
+ "license": "MIT",
+ "dependencies": {
+ "atomic-sleep": "^1.0.0"
+ }
+ },
+ "node_modules/source-map-js": {
+ "version": "1.2.1",
+ "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+ "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/split2": {
+ "version": "4.2.0",
+ "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+ "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+ "license": "ISC",
+ "engines": {
+ "node": ">= 10.x"
+ }
+ },
+ "node_modules/stackback": {
+ "version": "0.0.2",
+ "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+ "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/standard-as-callback": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/standard-as-callback/-/standard-as-callback-2.1.0.tgz",
+ "integrity": "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==",
+ "license": "MIT"
+ },
+ "node_modules/std-env": {
+ "version": "4.2.0",
+ "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.2.0.tgz",
+ "integrity": "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/string-width": {
+ "version": "4.2.3",
+ "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+ "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "emoji-regex": "^8.0.0",
+ "is-fullwidth-code-point": "^3.0.0",
+ "strip-ansi": "^6.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/strip-ansi": {
+ "version": "6.0.1",
+ "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+ "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ansi-regex": "^5.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/supports-color": {
+ "version": "8.1.1",
+ "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz",
+ "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "has-flag": "^4.0.0"
+ },
+ "engines": {
+ "node": ">=10"
+ },
+ "funding": {
+ "url": "https://github.com/chalk/supports-color?sponsor=1"
+ }
+ },
+ "node_modules/thread-stream": {
+ "version": "4.2.0",
+ "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.2.0.tgz",
+ "integrity": "sha512-e2zZ96wSChazBsbENf/Pcm/4swHt2cEKQ92rhUjkL9GCKiTDJIaTBenjE/m9DXi0QBmTMDkFDdOomUy20A1tDQ==",
+ "license": "MIT",
+ "dependencies": {
+ "real-require": "^1.0.0"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ },
+ "node_modules/thread-stream/node_modules/real-require": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/real-require/-/real-require-1.0.0.tgz",
+ "integrity": "sha512-P4nbQYQfePJxRSmY+v/KINxVucm4NF3p3s7pJveMTtom52FR4YGltUQLB8idDXwDDWW+eYrWDFbuzUnjoWHF7g==",
+ "license": "MIT"
+ },
+ "node_modules/tinybench": {
+ "version": "2.9.0",
+ "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+ "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/tinyexec": {
+ "version": "1.3.1",
+ "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz",
+ "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tinyglobby": {
+ "version": "0.2.17",
+ "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+ "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "fdir": "^6.5.0",
+ "picomatch": "^4.0.4"
+ },
+ "engines": {
+ "node": ">=12.0.0"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/SuperchupuDev"
+ }
+ },
+ "node_modules/tinyrainbow": {
+ "version": "3.1.1",
+ "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",
+ "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=14.0.0"
+ }
+ },
+ "node_modules/toad-cache": {
+ "version": "3.7.4",
+ "resolved": "https://registry.npmjs.org/toad-cache/-/toad-cache-3.7.4.tgz",
+ "integrity": "sha512-m1TdR/rvT7kgGJZhspNtXdsdYk0fddFpJJFlG5s+UkPFo6lkLoZ3YLOaovPYjq1R75NP5JfeTlSHaOsE09peCg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=20"
+ }
+ },
+ "node_modules/tree-kill": {
+ "version": "1.2.2",
+ "resolved": "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz",
+ "integrity": "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==",
+ "dev": true,
+ "license": "MIT",
+ "bin": {
+ "tree-kill": "cli.js"
+ }
+ },
+ "node_modules/tslib": {
+ "version": "2.8.1",
+ "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+ "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+ "dev": true,
+ "license": "0BSD"
+ },
+ "node_modules/tsx": {
+ "version": "4.23.13",
+ "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.13.tgz",
+ "integrity": "sha512-BL5MGkRln6aDYhb0xbQlEAGw743BaZYWdbWtdJOBriYJboKgUUYCadFp2/FpBBZquBC/ezNBn7wMMPx7FDZUDw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "esbuild": "~0.28.0"
+ },
+ "bin": {
+ "tsx": "dist/cli.mjs"
+ },
+ "engines": {
+ "node": ">=18.0.0"
+ },
+ "optionalDependencies": {
+ "fsevents": "~2.3.3"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/aix-ppc64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
+ "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "aix"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/android-arm": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
+ "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/android-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
+ "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/android-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
+ "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/darwin-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
+ "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/darwin-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
+ "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/freebsd-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
+ "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/freebsd-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
+ "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-arm": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
+ "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
+ "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-ia32": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
+ "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-loong64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
+ "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
+ "cpu": [
+ "loong64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-mips64el": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
+ "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
+ "cpu": [
+ "mips64el"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-ppc64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
+ "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-riscv64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
+ "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
+ "cpu": [
+ "riscv64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-s390x": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
+ "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
+ "cpu": [
+ "s390x"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/linux-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
+ "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/netbsd-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
+ "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/netbsd-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
+ "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/openbsd-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
+ "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/openbsd-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
+ "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/openharmony-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
+ "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openharmony"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/sunos-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
+ "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "sunos"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/win32-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
+ "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/win32-ia32": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
+ "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/@esbuild/win32-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
+ "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/tsx/node_modules/esbuild": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
+ "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "bin": {
+ "esbuild": "bin/esbuild"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "optionalDependencies": {
+ "@esbuild/aix-ppc64": "0.28.2",
+ "@esbuild/android-arm": "0.28.2",
+ "@esbuild/android-arm64": "0.28.2",
+ "@esbuild/android-x64": "0.28.2",
+ "@esbuild/darwin-arm64": "0.28.2",
+ "@esbuild/darwin-x64": "0.28.2",
+ "@esbuild/freebsd-arm64": "0.28.2",
+ "@esbuild/freebsd-x64": "0.28.2",
+ "@esbuild/linux-arm": "0.28.2",
+ "@esbuild/linux-arm64": "0.28.2",
+ "@esbuild/linux-ia32": "0.28.2",
+ "@esbuild/linux-loong64": "0.28.2",
+ "@esbuild/linux-mips64el": "0.28.2",
+ "@esbuild/linux-ppc64": "0.28.2",
+ "@esbuild/linux-riscv64": "0.28.2",
+ "@esbuild/linux-s390x": "0.28.2",
+ "@esbuild/linux-x64": "0.28.2",
+ "@esbuild/netbsd-arm64": "0.28.2",
+ "@esbuild/netbsd-x64": "0.28.2",
+ "@esbuild/openbsd-arm64": "0.28.2",
+ "@esbuild/openbsd-x64": "0.28.2",
+ "@esbuild/openharmony-arm64": "0.28.2",
+ "@esbuild/sunos-x64": "0.28.2",
+ "@esbuild/win32-arm64": "0.28.2",
+ "@esbuild/win32-ia32": "0.28.2",
+ "@esbuild/win32-x64": "0.28.2"
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ },
+ "node_modules/undici-types": {
+ "version": "6.21.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+ "license": "MIT"
+ },
+ "node_modules/vite": {
+ "version": "8.2.2",
+ "resolved": "https://registry.npmjs.org/vite/-/vite-8.2.2.tgz",
+ "integrity": "sha512-cFKLV/PRgAUlIRm5WjMjJ86jrftzpqcgH+Us+DS8mI3CDNiH30Whrz8uHL3+MOLPAgqbMBAqWdAHAphOAM+z/Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "lightningcss": "^1.33.0",
+ "picomatch": "^4.0.5",
+ "postcss": "^8.5.26",
+ "rolldown": "~1.2.4",
+ "tinyglobby": "^0.2.17"
+ },
+ "bin": {
+ "vite": "bin/vite.js"
+ },
+ "engines": {
+ "node": "^20.19.0 || >=22.12.0"
+ },
+ "funding": {
+ "url": "https://github.com/vitejs/vite?sponsor=1"
+ },
+ "optionalDependencies": {
+ "fsevents": "~2.3.3"
+ },
+ "peerDependencies": {
+ "@types/node": "^20.19.0 || >=22.12.0",
+ "@vitejs/devtools": "^0.4.0 || ^0.5.0",
+ "esbuild": "^0.27.0 || ^0.28.0",
+ "jiti": ">=1.21.0",
+ "less": "^4.0.0",
+ "sass": "^1.70.0",
+ "sass-embedded": "^1.70.0",
+ "stylus": ">=0.54.8",
+ "sugarss": "^5.0.0",
+ "terser": "^5.16.0",
+ "tsx": "^4.8.1",
+ "yaml": "^2.4.2"
+ },
+ "peerDependenciesMeta": {
+ "@types/node": {
+ "optional": true
+ },
+ "@vitejs/devtools": {
+ "optional": true
+ },
+ "esbuild": {
+ "optional": true
+ },
+ "jiti": {
+ "optional": true
+ },
+ "less": {
+ "optional": true
+ },
+ "sass": {
+ "optional": true
+ },
+ "sass-embedded": {
+ "optional": true
+ },
+ "stylus": {
+ "optional": true
+ },
+ "sugarss": {
+ "optional": true
+ },
+ "terser": {
+ "optional": true
+ },
+ "tsx": {
+ "optional": true
+ },
+ "yaml": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/vitest": {
+ "version": "4.1.11",
+ "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.11.tgz",
+ "integrity": "sha512-fhACrNXUidIbGSBr5FlbuBkO7VWC1ZyLl0DO4CU2DrQoAPxX84Ysxs+HeGQpii5lZWV1Q4gBZTTu49mF+A6Edw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vitest/expect": "4.1.11",
+ "@vitest/mocker": "4.1.11",
+ "@vitest/pretty-format": "4.1.11",
+ "@vitest/runner": "4.1.11",
+ "@vitest/snapshot": "4.1.11",
+ "@vitest/spy": "4.1.11",
+ "@vitest/utils": "4.1.11",
+ "es-module-lexer": "^2.0.0",
+ "expect-type": "^1.3.0",
+ "magic-string": "^0.30.21",
+ "obug": "^2.1.1",
+ "pathe": "^2.0.3",
+ "picomatch": "^4.0.3",
+ "std-env": "^4.0.0-rc.1",
+ "tinybench": "^2.9.0",
+ "tinyexec": "^1.0.2",
+ "tinyglobby": "^0.2.15",
+ "tinyrainbow": "^3.1.0",
+ "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
+ "why-is-node-running": "^2.3.0"
+ },
+ "bin": {
+ "vitest": "vitest.mjs"
+ },
+ "engines": {
+ "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+ },
+ "funding": {
+ "url": "https://opencollective.com/vitest"
+ },
+ "peerDependencies": {
+ "@edge-runtime/vm": "*",
+ "@opentelemetry/api": "^1.9.0",
+ "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+ "@vitest/browser-playwright": "4.1.11",
+ "@vitest/browser-preview": "4.1.11",
+ "@vitest/browser-webdriverio": "4.1.11",
+ "@vitest/coverage-istanbul": "4.1.11",
+ "@vitest/coverage-v8": "4.1.11",
+ "@vitest/ui": "4.1.11",
+ "happy-dom": "*",
+ "jsdom": "*",
+ "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+ },
+ "peerDependenciesMeta": {
+ "@edge-runtime/vm": {
+ "optional": true
+ },
+ "@opentelemetry/api": {
+ "optional": true
+ },
+ "@types/node": {
+ "optional": true
+ },
+ "@vitest/browser-playwright": {
+ "optional": true
+ },
+ "@vitest/browser-preview": {
+ "optional": true
+ },
+ "@vitest/browser-webdriverio": {
+ "optional": true
+ },
+ "@vitest/coverage-istanbul": {
+ "optional": true
+ },
+ "@vitest/coverage-v8": {
+ "optional": true
+ },
+ "@vitest/ui": {
+ "optional": true
+ },
+ "happy-dom": {
+ "optional": true
+ },
+ "jsdom": {
+ "optional": true
+ },
+ "vite": {
+ "optional": false
+ }
+ }
+ },
+ "node_modules/why-is-node-running": {
+ "version": "2.3.0",
+ "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+ "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "siginfo": "^2.0.0",
+ "stackback": "0.0.2"
+ },
+ "bin": {
+ "why-is-node-running": "cli.js"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/wrap-ansi": {
+ "version": "7.0.0",
+ "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+ "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ansi-styles": "^4.0.0",
+ "string-width": "^4.1.0",
+ "strip-ansi": "^6.0.0"
+ },
+ "engines": {
+ "node": ">=10"
+ },
+ "funding": {
+ "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+ }
+ },
+ "node_modules/ws": {
+ "version": "8.21.3",
+ "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
+ "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=10.0.0"
+ },
+ "peerDependencies": {
+ "bufferutil": "^4.0.1",
+ "utf-8-validate": ">=5.0.2"
+ },
+ "peerDependenciesMeta": {
+ "bufferutil": {
+ "optional": true
+ },
+ "utf-8-validate": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/y18n": {
+ "version": "5.0.8",
+ "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+ "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/yargs": {
+ "version": "17.7.2",
+ "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
+ "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "cliui": "^8.0.1",
+ "escalade": "^3.1.1",
+ "get-caller-file": "^2.0.5",
+ "require-directory": "^2.1.1",
+ "string-width": "^4.2.3",
+ "y18n": "^5.0.5",
+ "yargs-parser": "^21.1.1"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/yargs-parser": {
+ "version": "21.1.1",
+ "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+ "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/zod": {
+ "version": "4.5.4",
+ "resolved": "https://registry.npmjs.org/zod/-/zod-4.5.4.tgz",
+ "integrity": "sha512-sC95tT5iHHH9gtpj6A81kh+NEaRAUFN+qlUPDUbRfOMvNf5QCBqsb3WgvnpVtK5Y+4UfA6KqufotuTvMGiTlsA==",
+ "license": "MIT",
+ "funding": {
+ "url": "https://github.com/sponsors/colinhacks"
+ }
+ }
+ }
+}
diff --git a/backend/package.json b/backend/package.json
new file mode 100644
index 000000000..d0512371f
--- /dev/null
+++ b/backend/package.json
@@ -0,0 +1,47 @@
+{
+ "name": "backend",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "concurrently -k -n server,worker -c cyan,magenta \"npm run dev:server\" \"npm run dev:worker\"",
+ "dev:server": "tsx watch src/server.ts",
+ "dev:worker": "tsx watch src/worker.ts",
+ "build": "node build.mjs",
+ "build:tsc": "tsc",
+ "typecheck": "tsc --noEmit",
+ "start": "pm2 start ecosystem.config.cjs",
+ "stop": "pm2 stop ecosystem.config.cjs",
+ "start:runtime": "pm2-runtime start ecosystem.config.cjs",
+ "restart": "pm2 startOrReload ecosystem.config.cjs --update-env",
+ "start:server": "node dist/server.js",
+ "start:worker": "node dist/worker.js",
+ "start:local": "concurrently -k -n server,worker -c cyan,magenta \"node dist/server.js\" \"node dist/worker.js\"",
+ "test": "NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= vitest run",
+ "test:watch": "vitest",
+ "postinstall": "prisma generate"
+ },
+ "dependencies": {
+ "@fastify/cors": "^10.1.0",
+ "@fastify/multipart": "^9.4.0",
+ "@noble/curves": "^2.4.0",
+ "@prisma/client": "^5.22.0",
+ "@types/ws": "^8.18.1",
+ "dotenv": "^17.2.3",
+ "fastify": "^5.6.2",
+ "http-proxy": "^1.18.1",
+ "ioredis": "^5.11.1",
+ "ws": "^8.21.0",
+ "zod": "^4.0.0"
+ },
+ "devDependencies": {
+ "@types/http-proxy": "^1.17.15",
+ "@types/node": "^20.14.10",
+ "concurrently": "^9.1.2",
+ "esbuild": "^0.27.2",
+ "prisma": "^5.22.0",
+ "tsx": "^4.16.2",
+ "typescript": "^5.5.3",
+ "vitest": "^4.0.17"
+ }
+}
diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prisma
new file mode 100644
index 000000000..ebd3cb5f3
--- /dev/null
+++ b/backend/prisma/schema.prisma
@@ -0,0 +1,421 @@
+datasource db {
+ provider = "mongodb"
+ url = env("DATABASE_URL")
+}
+
+generator client {
+ provider = "prisma-client-js"
+}
+
+/// A thin MIRROR of a product user. Identity is the normalized email authenticated by Autonomous
+/// SSO. The two Autonomous account planes issue different subjects for the same email, so production
+/// and staging subjects are stored separately. Lives in the SAME MongoDB the agent-manager uses, but
+/// in its own `users` collection — the manager never touches it.
+///
+/// The production subject (`externalId`) remains unique because SDS stores that value as a device's
+/// `customer_id`. A device may connect before its owner has signed in, so that provisional row uses a
+/// deterministic non-deliverable email until the first production SSO login claims it.
+model User {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ email String @unique // normalized SSO identity; provisional device rows use @pending.harness.invalid
+ externalId String @unique // production SSO subject == SDS `customer_id`; local-prod-* until known
+ stagExternalId String? // staging SSO subject; authentication still keys by email
+ passwordHash String? // legacy only; SSO users have none
+ name String?
+ role String @default("user") // user | admin
+ // Which Autonomous account plane this user signs in against. Existing rows are backfilled to
+ // staging because they were created while the app used staging globally; new users default prod.
+ autonomousEnv String @default("prod") // prod | stag
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ @@index([stagExternalId])
+ @@map("users")
+}
+
+/// A machine: the unit that groups N agents and the thing a user creates, names, pays for and
+/// attaches a device to. Maps a user to their provisioned machine (agent-node) + the per-machine
+/// api-key the backend generated for it. The backend injects this key when reverse-proxying the
+/// user's data-plane traffic to the manager (the web never sees it). One node per machine.
+/// The manager owns the authoritative `machine_nodes` record; this is the backend's routing view
+/// (api-key + which manager owns the node).
+model Machine {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ userId String // owner (User.id); a user may own many machines
+ machineId String @unique // sha256(apiKey)[:32] — the routing key, on the wire as `machineId`
+ apiKey String // per-machine key; the data-plane credential (handed to the owner) + routing/node auth
+ managerId String // which manager owns the node → its dial-in socket routes this machine's traffic
+ workspaceId String?
+ // Immutable upstream plane copied from the owner when the machine is created. Billing and campaign
+ // credentials always resolve from this value, even if an admin later switches the user env.
+ autonomousEnv String @default("prod") // prod | stag
+ // Subscription plan the machine is on (SubscriptionPlan.id). cpus/memory are resolved THROUGH the
+ // plan (the manager reads it), replacing the old per-machine cpus/memory fields. Optional so legacy
+ // rows read; set to the default plan on every new create.
+ planId String?
+ // Denormalized from SubscriptionPlan.authMode at creation — IMMUTABLE (set once; there is no
+ // plan-switch path). All authMode logic reads THIS field, never the plan (a later plan-doc edit
+ // must not flip a live machine's mode). Optional so legacy rows read; backfilled at backend startup.
+ authMode String?
+ // The machine's display name. User-editable (PATCH /api/machines/:id); seeded ONCE from the
+ // connecting computer's hostname when still empty, then never overwritten by a connect.
+ name String?
+ // Hostname of the COMPUTER on its LAST adapter-ws connect (remote machines only) — the adapter
+ // sends it as `?label=` and it is overwritten every time, so it reflects the most recent computer.
+ // Secondary detail only: never used as the machine's name. Null for machines that never connected.
+ hostname String?
+ // The COMPUTER currently bound to this machine — the CLI's per-computer id, normalized
+ // (lib/deviceAuth.ts:normalizeComputerId). Stamped when a computer is connected through the
+ // device-auth grant and refreshed on every adapter-ws connect, so `harness auth device` on the same
+ // box reconnects to THAT machine instead of minting a second one. Null on rows that predate it.
+ computerId String?
+ // Version string the CLIENT reported on its LAST adapter-ws connect (remote machines only) — the
+ // client sends it as `?v=` and it is overwritten every time, so it reflects the most recent connect.
+ // Self-declared and sanitized at the upgrade; null for a machine that never connected or a client
+ // old enough not to send it.
+ clientVersion String?
+ // Billing lifecycle for newly-created campaign machines. Missing on old rows means legacy-active.
+ // Grandfathered Remote machines are `not_required`; new paid Remote and managed machines move pending -> active only after
+ // checkout verification. A cancelled paid subscription stays active until its period end, then
+ // the billing worker moves it to `suspended` and the manager stops (but preserves) its node.
+ billingStatus String?
+ externalDeviceId String?
+ externalSubscriptionId String?
+ externalSubscriptionStatus Int?
+ externalSubscriptionEndAt DateTime?
+ externalSubscriptionCancelledAt DateTime?
+ billingActivatedAt DateTime?
+ billingError String?
+ billingErrorAt DateTime?
+ // AES-256-GCM envelope containing the managed campaign llm_api_key. Always null for Remote.
+ llmApiKeyEncrypted String?
+ // authMode 'provider' only. The A2A endpoint this machine is backed by — supplied by the OWNER, so
+ // every outbound request to it goes through lib/providerUrl.ts (SSRF guard), never a bare fetch.
+ providerUrl String?
+ // AES-256-GCM envelope (lib/machineCredential.ts) holding the owner's credential FOR THE PROVIDER.
+ // Write-only from the client's point of view: never returned by an API, never logged.
+ providerCredentialEncrypted String?
+ // Soft-delete marker: destroy() stamps this instead of removing the row (the container/node is
+ // still torn down). Every read path treats a stamped row as absent. NOTE (Prisma-Mongo): legacy
+ // rows LACK the field entirely and `{deletedAt: null}` does not match absent — filter with the
+ // shared `machineAlive` helper (lib/prisma.ts), never an inline `deletedAt: null`.
+ deletedAt DateTime?
+ createdAt DateTime @default(now())
+
+ @@index([userId])
+ @@index([userId, computerId])
+ @@index([managerId, billingStatus])
+ @@index([billingStatus, externalSubscriptionStatus, externalSubscriptionEndAt])
+ @@map("machines")
+}
+
+/// Durable, account-scoped right to use the Free campaign tier. `reserved` prevents two tabs from
+/// starting two Free machines; once activation succeeds it becomes `claimed` and is never deleted,
+/// even if the machine is later upgraded or removed.
+model MachineFreeEntitlement {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ userId String
+ autonomousEnv String @default("prod") // copied from the machine; one lifetime Free grant per env
+ machineId String @unique
+ status String @default("reserved") // reserved | claimed
+ reservedAt DateTime @default(now())
+ claimedAt DateTime?
+ updatedAt DateTime @updatedAt
+
+ @@unique([userId, autonomousEnv])
+ @@map("machine_free_entitlements")
+}
+
+/// Subscription package: the per-machine resource tier + price. A machine is assigned a plan at
+/// create (the default one); the manager reads cpus/memory THROUGH the machine's plan. The backend
+/// owns writes; the manager mirrors this read-only. Exactly one plan should have isDefault=true.
+model SubscriptionPlan {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ name String
+ autonomousEnv String @default("prod") // prod | stag; external ids differ between planes
+ cpus String // docker --cpus, e.g. "1"
+ memory String // docker --memory, e.g. "2g"
+ maxAgents Int @default(1) // cap enforced by the backend on agent create
+ priceUsd Float @default(0)
+ // Backend-owned daily voice/STT allowance in seconds. `0` means unlimited; null keeps legacy
+ // plans unlimited until the worker backfills their explicit value.
+ dailyVoiceLimitSeconds Int?
+ // How the agent-node authenticates with Claude:
+ // "self" → the user logs the in-container `claude` CLI in (creds in ~/.claude), no env injected.
+ // "managed" → the manager injects ANTHROPIC_* creds into the container at start (no user login).
+ authMode String @default("self")
+ isDefault Boolean @default(false)
+ // Catalog visibility is explicit so legacy Self-Auth/Managed rows remain readable but cannot be
+ // selected for new machines. Missing means unavailable. Free/Pro/Max/Remote are synchronized from
+ // the environment-specific Autonomous campaign catalog when billing is enabled.
+ available Boolean?
+ externalPlanId Int?
+ externalPlanName String?
+ campaignCode String?
+ // Origin that supplied externalPlanId (staging/prod ids are not interchangeable). A cached
+ // catalog is reusable only when this matches the current AUTONOMOUS_BFF_URL origin.
+ catalogSource String?
+ externalMetadata Json?
+ catalogSyncedAt DateTime?
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ @@unique([autonomousEnv, name])
+ @@index([autonomousEnv, externalPlanId])
+ @@map("subscription_plans")
+}
+
+/// One UTC-day usage bucket per machine. `usedMs` includes pending STT reservations so concurrent
+/// devices cannot both pass the same remaining allowance.
+model MachineVoiceDailyUsage {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ machineId String
+ dayKey String
+ usedMs Int @default(0)
+ expiresAt DateTime
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ @@unique([machineId, dayKey])
+ @@index([expiresAt])
+ @@map("machine_voice_daily_usage")
+}
+
+/// Idempotency + crash-recovery record for a completed voice upload. A reservation is created in
+/// the same transaction that increments MachineVoiceDailyUsage, committed after STT returns, and
+/// released by the worker if STT fails or the process disappears.
+model MachineVoiceReservation {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ uploadId String @unique
+ machineId String
+ dayKey String
+ durationMs Int
+ status String @default("pending") // pending | committed | released
+ releaseAt DateTime?
+ expiresAt DateTime
+ committedAt DateTime?
+ releasedAt DateTime?
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ @@index([status, releaseAt])
+ @@index([expiresAt])
+ @@index([machineId, dayKey])
+ @@map("machine_voice_reservations")
+}
+
+/// Audit/idempotency record for every hosted checkout attempt. Redirect URLs can contain opaque
+/// provider state, so they are owner-only and never logged. Multiple attempts may exist per machine.
+model MachineCheckoutAttempt {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ machineId String
+ userId String
+ // Snapshot of the machine's immutable upstream plane. Callback completion must not depend on the
+ // user's current env because an admin may switch it while Stripe is open.
+ autonomousEnv String @default("prod")
+ externalPlanId Int
+ externalDeviceId String
+ sessionId String @unique
+ // Stable local operation id embedded in success/failure callback URLs. Hosted checkout operations
+ // use this instead of relying on the provider returning a checkout-session id, including Free card setup.
+ operationId String?
+ operationType String? // subscribe | plan_change
+ sourcePlanId String?
+ targetPlanId String?
+ providerSessionId String?
+ redirectUrl String?
+ // Snapshot of the non-secret checkout request so checkout-complete can resend the exact same
+ // fields even if the user's email, WEB_URL, or callback config changes while Stripe is open.
+ checkoutEmail String?
+ successUrl String?
+ failureUrl String?
+ webOrigin String?
+ status String @default("pending") // pending|completed|failed|cancelled
+ error String?
+ completedAt DateTime?
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ @@index([machineId, createdAt])
+ @@index([userId])
+ // MongoDB unique indexes treat repeated null optional fields as duplicates. sessionId is already
+ // unique and equals operationId for every new attempt; keep this nullable legacy field indexed.
+ @@index([operationId])
+ @@map("machine_checkout_attempts")
+}
+
+/// Per-machine agent association (an "agent" = one working unit with its own workspace and engine),
+/// populated by the data-plane tap (lib/agentTracker.ts): when a create succeeds we upsert one row;
+/// on DELETE we remove it. Lets the backend answer "how many agents does this machine have" without
+/// owning contents (the agent-node's SQLite remains the source of truth).
+model MachineAgent {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ machineId String // owning machine (matches Machine.machineId)
+ agentId String // the agent unit's UUID, from the create response
+ name String?
+ createdAt DateTime @default(now())
+
+ @@unique([machineId, agentId])
+ @@index([machineId])
+ @@map("machine_agents")
+}
+
+/// A device: one COMPUTER running the `harness` daemon, which serves a dial over USB and drives the
+/// owner's machines on its behalf. There is no pairing code and no device token — `/api/device-ws`
+/// authenticates with the owner's SSO access token plus a `?computer=` id, and this row is
+/// resolved-or-created from that. Deleting a row therefore FORGETS a dial (and closes its live socket);
+/// it is not a revocation, because the daemon re-creates it on its next connect.
+model DeviceBinding {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ userId String // owner (User.id)
+ // The COMPUTER this device row belongs to — the `harness` CLI's per-computer id, normalized
+ // (lib/deviceAuth.ts:normalizeComputerId). This is the ONLY way a device comes into existence now:
+ // `/api/device-ws` authenticates with the owner's SSO token plus `?computer=`, and the row is
+ // resolved-or-created from it. Optional only so `prisma db push` reads rows that predate it — those
+ // are pruned at boot (pruneLegacyDeviceBindings), since nothing can ever connect as them again.
+ computerId String?
+ // LEGACY per-machine pairing pinned the device here. NULL for per-user devices — they pick machines at
+ // runtime over the commander socket (`machine_select`). Kept only to read a legacy device's origin.
+ machineId String? // (Machine.machineId)
+ // Derived, never random: "cmp-" + sha256(userId:autonomousEnv:computerId)[:24]. See
+ // DeviceService.resolveOrCreateForComputer for why each ingredient is load-bearing.
+ deviceId String @unique
+ name String @default("device")
+ lastSeenAt DateTime?
+ createdAt DateTime @default(now())
+
+ // ── Reported by the device, snapshotted at each `device_hello` (deviceWs handleHello) ──────────
+ // These exist so the mobile app can render a device WITHOUT a live socket of its own; the web reads
+ // the same facts off the wire instead. All nullable: a device that has never connected on a build
+ // that reports them has none of them, and that must read as "unknown", never as a zero value.
+ firmwareVersion String?
+ chip String?
+ // WiFi as of the last hello. No shipping client reports these since the dial went cable-only, so they
+ // stay null — which clients must render as "no data" rather than an empty name or a zero-bar meter.
+ ssid String?
+ rssi Int? // dBm, negative. 0 is never stored — the firmware uses it for "unknown".
+ // The machine this device is CURRENTLY attached to (`machine_select` → relay setActiveMachine).
+ // Deliberately NOT the legacy `machineId` above: that one is the immutable pairing origin, this one
+ // moves every time the user picks a different machine on the device screen. Null while the device is
+ // parked on the picker. NOT cleared on socket close — a fast reconnect would race its own teardown —
+ // so on an offline device this reads as "last attached to"; clients gate it on liveness.
+ activeMachineId String?
+
+ @@index([userId])
+ @@index([userId, computerId])
+ @@map("device_bindings")
+}
+
+/// READ-ONLY view of the agent-manager's `managers` collection (the manager owns writes).
+/// The backend reads capacity (maxNodes/nodeCount) to pick a manager on create, and apiKey to
+/// authenticate its dial-in socket (/api/manager-ws). No address is needed — the manager dials the
+/// backend (inverted transport). The `@unique` on managerId matches the manager's own index so
+/// `prisma db push` from both services stays consistent.
+model Manager {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ managerId String @unique
+ maxNodes Int @default(0)
+ nodeCount Int @default(0)
+ apiKey String? // this manager's MANAGER_API_KEY (x-api-key on its dial-in socket)
+ agentEngine String? // manager AGENT_ENGINE default for machine_nodes without an explicit engine
+ lastSeenAt DateTime?
+
+ @@map("managers")
+}
+
+/// Backend-owned routing record for a published app (mirrors Machine's role for machines):
+/// answers "which manager owns this subdomain" for the :8087 public app-proxy. The manager owns
+/// the parallel `app_deployments` record (subdomain → appPort). Written at register; the subdomain
+/// is a random slug (user never picks it). machineId/agentId denormalized for filtered list/get.
+model Subdomain {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ subdomain String @unique
+ machineId String // owning machine (Machine.machineId — the data path routes by it)
+ agentId String // the agent unit
+ managerId String // which manager serves it (app control RPC target)
+ userId String
+ createdAt DateTime @default(now())
+
+ @@index([userId])
+ @@index([machineId])
+ @@index([machineId, agentId])
+ @@map("subdomains")
+}
+
+/// Harness Analytics — ADDITIVE counters only (see docs/design/harness-analytics.md).
+/// Safe to sum along engine, mode, origin, machine, and day. A union of intervals or a distinct
+/// count must NEVER live here: splitting one by engine and re-summing double-counts concurrency,
+/// which is the exact error the wall-clock metric exists to prevent. Those live on
+/// AnalyticsDailyMachine at (machine, day) granularity instead.
+model AnalyticsDailyBucket {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ userId String
+ machineId String
+ dayUtc DateTime // midnight UTC of the day these counters belong to
+ engine String
+ mode String // self | managed | remote | provider
+ origin String // human | scheduled | system | api
+ schemaVersion Int
+ // Client monotonic stamp, CLAMPED server-side against receivedAt. Ordering key for last-write-wins:
+ // each (machine, day, engine, mode, origin) has exactly ONE writer, so no version vector is needed.
+ // A client-chosen revision was rejected — a bad or hostile value could pin a record permanently.
+ generatedAt DateTime
+ instructions Int @default(0)
+ turnsStarted Int @default(0)
+ turnsCompleted Int @default(0)
+ turnsFailed Int @default(0)
+ turnsCancelled Int @default(0)
+ turnsInputNeeded Int @default(0)
+ agentRuntimeMs BigInt @default(0) // sum of terminal turn durations; overlaps counted twice by design
+ updatedAt DateTime @updatedAt
+
+ @@unique([userId, machineId, dayUtc, engine, mode, origin, schemaVersion])
+ @@index([userId, dayUtc])
+ @@map("analytics_daily_buckets")
+}
+
+/// Harness Analytics — NON-ADDITIVE metrics plus the reporting heartbeat. Exactly one row per
+/// machine per day. A row with all-zero counters means "the machine was up and idle"; a MISSING row
+/// means "we have no data". The UI must never render those two states the same way.
+model AnalyticsDailyMachine {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ userId String
+ machineId String
+ dayUtc DateTime
+ wallClockActiveMs BigInt @default(0) // union of turn intervals, computed locally where all are visible
+ activeAgents Int @default(0) // distinct agents; sums across machines (an agent has one machine)
+ uptimeMs BigInt @default(0) // denominator for utilization; 0 when not meaningful (provider)
+ reported Boolean @default(true) // heartbeat: this machine DID report this day
+ generatedAt DateTime
+ updatedAt DateTime @updatedAt
+
+ @@unique([userId, machineId, dayUtc])
+ @@index([userId, dayUtc])
+ @@map("analytics_daily_machines")
+}
+
+/// Harness Analytics — per-machine collector control and coverage state. Backs the Coverage panel
+/// and the ingest response, which is the ONLY channel a headless collector has for learning that the
+/// account turned collection off or deleted its history.
+model AnalyticsMachineState {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ machineId String @unique
+ userId String
+ // Collection is ON by default; the owner can switch it off per machine or for the whole account.
+ consent String @default("on") // on | off
+ // Bumped by a user-triggered deletion. Uploads carrying an older epoch are refused, so a collector
+ // still holding queued records cannot resurrect erased history.
+ epoch Int @default(0)
+ collectorVersion String?
+ engineCoverage String[] // engines this collector instruments
+ // Engines the collector can SEE here (registered agents / discovered binaries). The difference
+ // enginesPresent - engineCoverage is what the UI shows as "not instrumented" — coverage alone
+ // cannot tell an uninstrumented engine from one that is simply not installed.
+ enginesPresent String[]
+ lastReportAt DateTime?
+ clockSkewMs Int? // receivedAt - generatedAt at the last report; surfaced in Coverage
+ updatedAt DateTime @updatedAt
+
+ @@index([userId])
+ @@map("analytics_machine_states")
+}
diff --git a/backend/scripts/fake-cursor-adapter.mjs b/backend/scripts/fake-cursor-adapter.mjs
new file mode 100755
index 000000000..3e9f07ec8
--- /dev/null
+++ b/backend/scripts/fake-cursor-adapter.mjs
@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+//
+// A stand-in for the macOS Cursor adapter, so the device path can be exercised before that app exists.
+//
+// It dials /api/adapter-ws as a remote machine, keeps presence alive, publishes one Cursor-badged agent,
+// and lets you toggle Cursor's open/closed/missing state from the keyboard. What you should see on the
+// dial's Machines wheel:
+//
+// ✓ Kyle's Mac Cursor · open <-- press c to flip it to "closed"
+//
+// Usage:
+// node scripts/fake-cursor-adapter.mjs --token <machine apiKey> [--url wss://harness-api.autonomous.ai]
+// node scripts/fake-cursor-adapter.mjs --token $KEY --url ws://localhost:8085
+//
+// Keys while running: o = open c = closed m = missing a = re-publish the agent q = quit
+//
+// The token is a REMOTE machine's apiKey (POST /api/machines with a remote plan, or the value behind
+// `harness join <token>`). The backend rejects any other authMode with 401, so a managed machine's key
+// will not work here — that is the gate at adapterWs.ts, not a bug in this script.
+//
+// E2EE IS implemented (scripts/lib/e2ee-core.mjs, validated against the device's own golden vectors),
+// because a remote machine cannot do anything without it: the backend relays agents_list to the machine
+// and expects per-connId ciphertext back, and the device's picker row stays "Not linked" until the
+// pairing completes. Pairing needs the 6-character code the DEVICE shows on screen — that is the whole
+// security property, so it cannot be automated. Write it to PAIR_CODE_FILE and this adapter continues:
+//
+// echo K7P4X9 > /tmp/harness-pair-code
+
+import { createHash, randomBytes } from 'node:crypto'
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import * as E from './lib/e2ee-core.mjs'
+
+// There is no root package.json in this monorepo, so `ws` is resolved out of the backend's own
+// node_modules. Node's global WebSocket would avoid the dependency but cannot set request headers and
+// does not surface the HTTP status of a failed upgrade — and 401 vs 402 vs 409 is exactly what this
+// script exists to let you test.
+let WebSocket
+try {
+ WebSocket = createRequire(new URL('../package.json', import.meta.url))('ws').WebSocket
+} catch {
+ console.error('cannot resolve `ws` — run `npm install` in the backend repo first')
+ process.exit(2)
+}
+
+const args = process.argv.slice(2)
+const flag = (name, fallback) => {
+ const i = args.indexOf(`--${name}`)
+ return i >= 0 && args[i + 1] ? args[i + 1] : fallback
+}
+
+const token = flag('token')
+if (!token) {
+ console.error('usage: fake-cursor-adapter.mjs --token <machine apiKey> [--url <ws base>] [--label <name>]')
+ process.exit(2)
+}
+const base = flag('url', 'wss://harness-api.autonomous.ai').replace(/\/$/, '')
+const label = flag('label', 'Fake Cursor Mac')
+// Stable per invocation of this script on this host. The backend enforces one computer per machine and
+// answers 409 for a different one, so reusing the same value lets a restart reclaim its own machine.
+const computerId = createHash('sha256').update(`fake-cursor-adapter:${process.env.USER ?? 'anon'}`).digest('hex').slice(0, 32)
+const machineId = createHash('sha256').update(token).digest('hex').slice(0, 32)
+
+const AGENT = {
+ id: 'fake-composer-0001-0002-0003',
+ name: 'Spider research',
+ engine: 'cursor',
+}
+
+let appState = 'open'
+let ws
+let pingTimer
+
+const send = (obj) => {
+ if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify(obj))
+}
+
+/** Both eligibility flags false: the backend routes this to its machine watchers, never to a client. */
+const sendAppState = () => {
+ send({ t: 'up', webEligible: false, commanderEligible: false,
+ frame: { type: 'machine_app_status', payload: { engine: 'cursor', state: appState } } })
+ console.log(`→ machine_app_status cursor:${appState}`)
+}
+
+/** agent_synced is what puts a Cursor badge on the tile — the machine-level engine is pinned to claude. */
+const sendAgent = () => {
+ send({ t: 'up', webEligible: true, commanderEligible: true,
+ frame: { type: 'agent_synced', engine: AGENT.engine,
+ payload: { agent: { id: AGENT.id, name: AGENT.name }, engine: AGENT.engine, status: 'active' } } })
+ console.log(`→ agent_synced ${AGENT.name} (${AGENT.engine})`)
+}
+
+// ── E2EE (adapter = CPace INITIATOR; the device is the responder and shows the code) ───────────────
+const PAIR_CODE_FILE = '/tmp/harness-pair-code'
+const b64 = (b) => Buffer.from(b).toString('base64')
+const unb64 = (s) => Buffer.from(String(s ?? ''), 'base64')
+
+// Persisted, because the device PINS this identity: a fresh seed each run makes every restart look like
+// an adapter that rotated its key, so the device unpins and demands the code again — which turns a
+// one-line edit into a re-pair. Keyed by machine so two machines don't share an identity.
+const IDENTITY_FILE = `/tmp/harness-adapter-identity-${machineId}.json`
+let store = { seed: null, pinned: null }
+try { store = { ...store, ...JSON.parse(readFileSync(IDENTITY_FILE, 'utf8')) } } catch { /* first run */ }
+const identitySeed = store.seed ? Buffer.from(store.seed, 'base64') : randomBytes(32)
+const identityPub = E.edPublicFromSeed(identitySeed)
+const persist = () => {
+ try {
+ writeFileSync(IDENTITY_FILE, JSON.stringify({
+ seed: identitySeed.toString('base64'),
+ pinned: pinnedDevicePub ? pinnedDevicePub.toString('base64') : null,
+ }), { mode: 0o600 })
+ } catch { /* dev convenience only */ }
+}
+const ci = E.pairContext(machineId, 'device')
+const groupKey = randomBytes(32)
+const epoch = randomBytes(4).toString('hex')
+
+let pinnedDevicePub = store.pinned ? Buffer.from(store.pinned, 'base64') : null
+let pair = null // in-flight CPace state
+const sessions = new Map() // connId → {c2s, s2c, sendCtr}
+
+const sendFrame = (type, payload, connId) =>
+ send({ t: 'up', commanderEligible: true, webEligible: false, targetConnId: connId,
+ frame: { type, payload } })
+
+function onE2eFrame(type, p, connId) {
+ if (type === 'e2e_status') {
+ // Must answer within 6s: the device falls back to plaintext after that, and for a REMOTE machine the
+ // backend then refuses every RPC — an empty machine with no explanation.
+ const paired = !!pinnedDevicePub && pinnedDevicePub.equals(unb64(p.identityPub))
+ console.log(`← e2e_status → supported:true paired:${paired}`)
+ return sendFrame('e2e_status_result', { supported: true, paired }, connId)
+ }
+
+ if (type === 'e2e_pair_intent') {
+ const pairId = unb64(p.pairId)
+ pair = { pairIdB64: p.pairId, pairId, connId }
+ console.log(`\n← e2e_pair_intent PAIRING NEEDED`)
+ console.log(` Read the 6-character code off the dial, then:`)
+ console.log(` echo <CODE> > ${PAIR_CODE_FILE}\n`)
+ waitForCode()
+ return
+ }
+
+ if (type === 'e2e_pake' && pair && p.pairId === pair.pairIdB64) return onPake(p, connId)
+ if (type === 'e2e_hello') return onHello(p, connId)
+}
+
+function waitForCode() {
+ // The device rotates its code every 60s with a fresh pairId, so intents repeat. One waiter at a time,
+ // or a later code could restart CPace on top of an in-flight exchange.
+ if (pair.waiting) return
+ pair.waiting = true
+ const deadline = Date.now() + 120_000
+ const tick = setInterval(() => {
+ if (!pair) return clearInterval(tick)
+ if (Date.now() > deadline) { clearInterval(tick); console.log('✗ pairing timed out'); pair = null; return }
+ if (!existsSync(PAIR_CODE_FILE)) return
+ const code = readFileSync(PAIR_CODE_FILE, 'utf8').trim()
+ try { unlinkSync(PAIR_CODE_FILE) } catch { /* ignore */ }
+ if (!code) return
+ clearInterval(tick)
+ startCpace(code)
+ }, 400)
+}
+
+function startCpace(code) {
+ console.log(`→ e2e_pake round 1 code="${code}"`)
+ const g = E.cpaceGenerator(code, pair.pairId, ci)
+ pair.y = E.randScalar()
+ pair.Ya = Buffer.from(g.multiply(pair.y).toBytes())
+ sendFrame('e2e_pake', { pairId: pair.pairIdB64, round: 1, ya: b64(pair.Ya) }, pair.connId)
+}
+
+function onPake(p, connId) {
+ if (p.round === 2) {
+ pair.Yb = unb64(p.yb)
+ let K
+ try { K = E.cpaceShared(pair.Yb, pair.y) } catch { console.log('✗ bad Yb'); pair = null; return }
+ pair.isk = E.cpaceISK(pair.pairId, K, pair.Ya, pair.Yb)
+ pair.th = E.transcriptHash(pair.pairId, ci, pair.Ya, pair.Yb)
+ const kc = E.kcKeys(pair.isk, ci)
+ // The device proves it derived the same ISK — i.e. that it knew the code. A wrong code dies here.
+ if (!E.macTag(kc.responder, pair.th).equals(unb64(p.mac))) {
+ console.log('✗ wrong code — device MAC mismatch'); pair = null; return
+ }
+ const pk = E.pairKey(pair.isk, ci)
+ const me = JSON.stringify({ id: b64(identityPub), sig: b64(E.pairBindSig(identitySeed, pair.th)) })
+ // Identity exchange rides inside the PAKE: literal "e2e-id" AAD, counters 3 and 4 (not the frame AAD).
+ const enc = E.aeadSeal(pk, 3, Buffer.from('e2e-id'), Buffer.from(me))
+ console.log('→ e2e_pake round 3 code accepted, sending identity')
+ return sendFrame('e2e_pake', { pairId: pair.pairIdB64, round: 3, mac: b64(E.macTag(kc.adapter, pair.th)), enc: b64(enc) }, connId)
+ }
+
+ if (p.round === 4) {
+ const pk = E.pairKey(pair.isk, ci)
+ const pt = E.aeadOpen(pk, 4, Buffer.from('e2e-id'), unb64(p.enc))
+ if (!pt) { console.log('✗ cannot open device identity'); pair = null; return }
+ const { id, sig } = JSON.parse(pt.toString())
+ const devPub = unb64(id)
+ if (!E.pairBindVerify(devPub, pair.th, unb64(sig))) { console.log('✗ device bind sig invalid'); pair = null; return }
+ pinnedDevicePub = devPub
+ persist()
+ console.log(`→ e2e_pake round 5 PAIRED device=${E.fingerprint(devPub)}`)
+ console.log(` adapter=${E.fingerprint(identityPub)}`)
+ sendFrame('e2e_pake', { pairId: pair.pairIdB64, round: 5, ok: true }, connId)
+ pair = null
+ }
+}
+
+function onHello(p, connId) {
+ const devIdPub = unb64(p.identityPub)
+ const devEphPub = unb64(p.ephPub)
+ if (!E.helloVerify(devIdPub, machineId, devEphPub, unb64(p.sig))) { console.log('✗ hello sig invalid'); return }
+ const ephSeed = randomBytes(32)
+ const ephPub = E.xPublicFromSeed(ephSeed)
+ // Both sides pass the SAME ordering: (responder=device eph, initiator=adapter eph).
+ const { c2s, s2c } = E.sessionKeys(ephSeed, devEphPub, machineId, devEphPub, ephPub)
+ sessions.set(connId, { c2s, s2c, sendCtr: 1 }) // 0 is spent by the welcome below
+ const enc = E.aeadSeal(s2c, 0, Buffer.from('e2e-welcome'),
+ Buffer.from(JSON.stringify({ groupKey: b64(groupKey), epoch })))
+ console.log(`→ e2e_welcome session up (epoch ${epoch})`)
+ sendFrame('e2e_welcome', {
+ ephPub: b64(ephPub),
+ webEphPub: b64(devEphPub), // echo — proves we answered THIS hello
+ sig: b64(E.welcomeSig(identitySeed, machineId, devEphPub, ephPub)),
+ enc: b64(enc),
+ }, connId)
+}
+
+/** A protected RPC from the device: ciphertext in, ciphertext out, per connId. */
+function onDataFrame(type, frame, connId) {
+ const sess = sessions.get(connId)
+ const env = frame.payload?.__e2e
+ let payload = frame.payload
+ if (env && sess) {
+ const pt = E.aeadOpen(env.k === 'g' ? groupKey : sess.c2s, env.n,
+ E.aad(type, frame.dbSessionId, env.k, env.epoch), Buffer.from(env.ct, 'base64'))
+ if (!pt) { console.log(`✗ cannot decrypt ${type}`); return }
+ payload = JSON.parse(pt.toString())
+ }
+ console.log(`← ${type}${env ? ' (encrypted)' : ''}`)
+
+ if (type === 'agents_list' && sess) {
+ const result = { requestId: payload?.requestId, agents: [{ id: AGENT.id, name: AGENT.name, engine: AGENT.engine }] }
+ return sendEncrypted('agents_list_result', result, connId)
+ }
+
+ if (type === 'agent_recent' && sess) {
+ // The tile's last-activity line. `summary` is the kind the device renders as a recap card (and the
+ // kind it beeps on); `recap` is the short headline, `text` the body behind tap-to-read.
+ return sendEncrypted('agent_recent_result', {
+ requestId: payload?.requestId,
+ agentId: payload?.agentId ?? AGENT.id,
+ events: [{ kind: 'summary', recap: 'Mapped the spider dataset', text: 'Went through the spider dataset and pulled out the three columns that actually matter.' }],
+ }, connId)
+ }
+}
+
+function sendEncrypted(type, payload, connId) {
+ const sess = sessions.get(connId)
+ if (!sess) return
+ // Pairwise frames carry NO epoch — present-but-empty would change the AAD and fail to open.
+ const wrapped = E.wrapPayload(sess.s2c, 'p', sess.sendCtr++, type, undefined, payload)
+ console.log(`→ ${type} (encrypted)`)
+ sendFrame(type, wrapped, connId)
+}
+
+function connect() {
+ const url = `${base}/api/adapter-ws?label=${encodeURIComponent(label)}&computer=${computerId}`
+ console.log(`connecting machineId=${machineId}\n ${url}`)
+ // The apiKey travels as the FIRST websocket subprotocol; x-api-key is accepted too and sent as a belt.
+ ws = new WebSocket(url, [token], { headers: { 'x-api-key': token } })
+
+ ws.on('unexpected-response', (_req, res) => {
+ // These three are genuinely different and a real adapter must not conflate them: 401 means the
+ // token is dead (wipe it), 402 means billing (keep it, retry), 409 means another computer holds
+ // this machine (keep it, do not fight).
+ const why = { 401: 'not a remote machine, or the token was revoked — do NOT retry with this token',
+ 402: 'subscription required — keep the token and retry later',
+ 409: 'another computer already holds this machine' }[res.statusCode]
+ console.error(`✗ HTTP ${res.statusCode}${why ? ` — ${why}` : ''}`)
+ process.exit(1)
+ })
+
+ ws.on('open', () => {
+ console.log('✓ connected\n keys: o=open c=closed m=missing a=agent q=quit\n')
+ sendAgent()
+ sendAppState()
+ // Refreshes presence AND renews the one-computer claim; the backend's own key TTL is 30s.
+ pingTimer = setInterval(() => send({ t: 'ping' }), 15_000)
+ })
+
+ ws.on('message', (raw) => {
+ let env
+ try { env = JSON.parse(raw.toString()) } catch { return }
+ if (env.t !== 'down') return
+ const type = env.frame?.type
+ if (type === 'machine_meta') { console.log(`← machine_meta name="${env.frame.payload?.name ?? ''}"`); return }
+ if (type === '__clients') {
+ const p = env.frame.payload ?? {}
+ console.log(`← __clients ui=${p.ui ?? 0} commander=${p.commander ?? 0} active=${p.commanderActive ?? 0}`)
+ return
+ }
+ if (type?.startsWith('e2e_')) return onE2eFrame(type, env.frame.payload ?? {}, env.connId)
+ return onDataFrame(type, env.frame, env.connId)
+ })
+
+ ws.on('close', (code, reason) => {
+ clearInterval(pingTimer)
+ const note = code === 4000 ? ' (superseded — another adapter took this machine)'
+ : code === 4003 ? ' (subscription required)' : ''
+ console.error(`✗ closed ${code}${note} ${reason?.toString() ?? ''}`)
+ process.exit(1)
+ })
+ ws.on('error', (err) => console.error('✗ socket error', err.message))
+}
+
+// Same idea as the pairing code: a file, so the state can be flipped while this runs detached.
+// echo closed > /tmp/harness-cursor-state
+const STATE_FILE = '/tmp/harness-cursor-state'
+setInterval(() => {
+ if (!existsSync(STATE_FILE)) return
+ let next
+ try { next = readFileSync(STATE_FILE, 'utf8').trim(); unlinkSync(STATE_FILE) } catch { return }
+ if (!['open', 'closed', 'missing'].includes(next) || next === appState) return
+ appState = next
+ sendAppState()
+}, 400)
+
+if (process.stdin.isTTY) {
+ process.stdin.setRawMode(true)
+ process.stdin.resume()
+ process.stdin.on('data', (buf) => {
+ const k = buf.toString()
+ if (k === 'q' || k === '') { console.log('bye'); process.exit(0) }
+ if (k === 'a') return sendAgent()
+ const next = { o: 'open', c: 'closed', m: 'missing' }[k]
+ if (!next) return
+ appState = next
+ sendAppState()
+ })
+}
+
+connect()
diff --git a/backend/scripts/lib/e2ee-core.mjs b/backend/scripts/lib/e2ee-core.mjs
new file mode 100644
index 000000000..6676d7609
--- /dev/null
+++ b/backend/scripts/lib/e2ee-core.mjs
@@ -0,0 +1,256 @@
+// E2EE crypto core — JS twin of apps/web/src/lib/e2ee/core.ts and
+// apps/esp32-square/main/e2ee/e2ee_core.c, for the dev adapter in scripts/.
+//
+// This is a THIRD implementation of a scheme where every copy must agree byte-for-byte, so it is not
+// trusted on inspection: `node scripts/lib/e2ee-core.mjs --selftest` re-derives the golden vectors the
+// device's C port is validated against, parsed straight out of e2ee_vectors.h rather than hand-copied.
+//
+// Node's crypto covers Ed25519 (deterministic, unlike CryptoKit's), X25519, SHA-2, HMAC, HKDF and
+// ChaCha20-Poly1305. Only ristretto255 needs @noble.
+
+import { createHash, createHmac, hkdfSync, createPrivateKey, createPublicKey, sign as edSign,
+ verify as edVerify, createCipheriv, createDecipheriv, randomBytes, diffieHellman } from 'node:crypto'
+import { createRequire } from 'node:module'
+
+const require = createRequire(new URL('../../package.json', import.meta.url))
+const { ristretto255, ristretto255_hasher } = require('@noble/curves/ed25519.js')
+
+export const CPACE_DSI = 'e2e-cpace-ristretto255-v1'
+export const E2E_VERSION = 1
+
+const u8 = (s) => Buffer.from(s, 'utf8')
+
+/** Length-prefixed concat: 4-byte BE length per field. */
+export function lvCat(...parts) {
+ const chunks = []
+ for (const p of parts) {
+ const b = Buffer.isBuffer(p) ? p : typeof p === 'string' ? u8(p) : Buffer.from(p)
+ const len = Buffer.alloc(4)
+ len.writeUInt32BE(b.length, 0)
+ chunks.push(len, b)
+ }
+ return Buffer.concat(chunks)
+}
+
+/** expand_message_xmd (RFC 9380 §5.3.1) with SHA-512, 64-byte output. */
+export function expandMessageXMD64(msg, dst) {
+ const dstB = u8(dst)
+ const dstPrime = Buffer.concat([dstB, Buffer.from([dstB.length])])
+ const zPad = Buffer.alloc(128) // r_in_bytes for SHA-512
+ const lIB = Buffer.from([0x00, 0x40]) // I2OSP(64, 2)
+ const b0 = createHash('sha512')
+ .update(zPad).update(msg).update(lIB).update(Buffer.from([0])).update(dstPrime).digest()
+ return createHash('sha512')
+ .update(b0).update(Buffer.from([1])).update(dstPrime).digest()
+}
+
+// ── identity (Ed25519) ─────────────────────────────────────────────────────────────────────────────
+// Node wants DER/JWK, not raw bytes, so wrap the 32-byte seed in the minimal PKCS#8 prefix.
+const PKCS8_ED25519 = Buffer.from('302e020100300506032b657004220420', 'hex')
+const SPKI_ED25519 = Buffer.from('302a300506032b6570032100', 'hex')
+
+export function edKeyFromSeed(seed) {
+ return createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, seed]), format: 'der', type: 'pkcs8' })
+}
+export function edPublicFromSeed(seed) {
+ const pub = createPublicKey(edKeyFromSeed(seed)).export({ format: 'der', type: 'spki' })
+ return pub.subarray(pub.length - 32)
+}
+export function sign(seed, msg) { return edSign(null, msg, edKeyFromSeed(seed)) }
+export function verify(pub, msg, sig) {
+ try {
+ const key = createPublicKey({ key: Buffer.concat([SPKI_ED25519, pub]), format: 'der', type: 'spki' })
+ return edVerify(null, msg, key, sig)
+ } catch { return false }
+}
+export function fingerprint(pub) {
+ const hex = createHash('sha256').update(pub).digest('hex').slice(0, 16).toUpperCase()
+ return [0, 4, 8, 12].map((i) => hex.slice(i, i + 4)).join('·')
+}
+
+// ── CPace over ristretto255 ────────────────────────────────────────────────────────────────────────
+export function pairContext(machineId, role = 'device') {
+ return `autonomous-e2e-pair|agent:${machineId}|a:adapter|b:${role}`
+}
+
+export function cpaceGenerator(code, sid, ci) {
+ const genStr = lvCat(CPACE_DSI, normalizeCode(code), sid, ci)
+ // Same two steps the C does: expand_message_xmd(SHA-512, 64) then the ristretto one-way map.
+ const xmd = expandMessageXMD64(genStr, CPACE_DSI)
+ return ristretto255_hasher.hashToCurve(genStr, { DST: CPACE_DSI, xmd })
+}
+
+const leToBig = (b) => { let x = 0n; for (let i = b.length - 1; i >= 0; i--) x = (x << 8n) | BigInt(b[i]); return x }
+
+/** libsodium's crypto_core_ristretto255_scalar_reduce: 64 bytes LITTLE-endian, reduced mod L. */
+export function scalarReduce64(b) { return leToBig(b) % ristretto255.Point.Fn.ORDER }
+
+/** Uniform scalar in [1, L). */
+export function randScalar() {
+ for (;;) {
+ const s = scalarReduce64(randomBytes(64))
+ if (s !== 0n) return s
+ }
+}
+
+export function cpaceShared(peerY, y) {
+ const P = ristretto255.Point.fromBytes(Buffer.from(peerY))
+ const K = P.multiply(y)
+ if (K.is0()) throw new Error('cpace: identity shared point')
+ return Buffer.from(K.toBytes())
+}
+
+export function cpaceISK(sid, K, Ya, Yb) {
+ return createHash('sha512').update(
+ lvCat(`${CPACE_DSI}_ISK`, sid, K, lvCat(Ya, 'a'), lvCat(Yb, 'b')),
+ ).digest()
+}
+export function transcriptHash(sid, ci, Ya, Yb) {
+ return createHash('sha512').update(lvCat(sid, ci, lvCat(Ya, 'a'), lvCat(Yb, 'b'))).digest()
+}
+const hkdf32 = (ikm, salt, info, len) =>
+ Buffer.from(hkdfSync('sha256', ikm, salt, u8(info), len))
+
+export function kcKeys(isk, ci) {
+ const kc = hkdf32(isk, u8(ci), 'e2e-kc-v1', 64)
+ return { adapter: kc.subarray(0, 32), responder: kc.subarray(32, 64) }
+}
+export function macTag(key, th) { return createHmac('sha256', key).update(th).digest() }
+export function pairKey(isk, ci) { return hkdf32(isk, u8(ci), 'e2e-id-v1', 32) }
+export function pairBindSig(seed, th) { return sign(seed, Buffer.concat([u8('e2e-pair-bind'), th])) }
+export function pairBindVerify(pub, th, sig) {
+ return verify(pub, Buffer.concat([u8('e2e-pair-bind'), th]), sig)
+}
+
+// ── per-connection session (X25519 → HKDF) ─────────────────────────────────────────────────────────
+const PKCS8_X25519 = Buffer.from('302e020100300506032b656e04220420', 'hex')
+const SPKI_X25519 = Buffer.from('302a300506032b656e032100', 'hex')
+
+export function xKeyFromSeed(seed) {
+ return createPrivateKey({ key: Buffer.concat([PKCS8_X25519, seed]), format: 'der', type: 'pkcs8' })
+}
+export function xPublicFromSeed(seed) {
+ const pub = createPublicKey(xKeyFromSeed(seed)).export({ format: 'der', type: 'spki' })
+ return pub.subarray(pub.length - 32)
+}
+export function sessionKeys(ephPriv, peerEphPub, machineId, responderEphPub, initiatorEphPub) {
+ const shared = diffieHellman({
+ privateKey: xKeyFromSeed(ephPriv),
+ publicKey: createPublicKey({ key: Buffer.concat([SPKI_X25519, Buffer.from(peerEphPub)]), format: 'der', type: 'spki' }),
+ })
+ const salt = lvCat(machineId, responderEphPub, initiatorEphPub)
+ const sess = hkdf32(shared, salt, 'e2e-sess-v1', 64)
+ return { c2s: sess.subarray(0, 32), s2c: sess.subarray(32, 64) }
+}
+export function helloVerify(pub, machineId, ephPub, sig) {
+ return verify(pub, lvCat('e2e-hello-v1', machineId, ephPub), sig)
+}
+export function welcomeSig(seed, machineId, responderEphPub, initiatorEphPub) {
+ return sign(seed, lvCat('e2e-welcome-v1', machineId, responderEphPub, initiatorEphPub))
+}
+
+// ── AEAD ───────────────────────────────────────────────────────────────────────────────────────────
+export function counterNonce(counter) {
+ const n = Buffer.alloc(12)
+ n.writeBigUInt64BE(BigInt(counter), 0) // 8-byte BE counter ‖ 4 zero bytes
+ return n
+}
+export function aeadSeal(key, counter, aad, pt) {
+ const c = createCipheriv('chacha20-poly1305', key, counterNonce(counter), { authTagLength: 16 })
+ c.setAAD(aad)
+ return Buffer.concat([c.update(pt), c.final(), c.getAuthTag()]) // ct ‖ tag, NOT nonce-prefixed
+}
+export function aeadOpen(key, counter, aad, ct) {
+ try {
+ const body = ct.subarray(0, ct.length - 16)
+ const tag = ct.subarray(ct.length - 16)
+ const d = createDecipheriv('chacha20-poly1305', key, counterNonce(counter), { authTagLength: 16 })
+ d.setAAD(aad)
+ d.setAuthTag(tag)
+ return Buffer.concat([d.update(body), d.final()])
+ } catch { return null }
+}
+/** Absent fields are the EMPTY STRING, never omitted — a missing separator changes the AAD. */
+export function aad(frameType, dbSessionId, k, epoch) {
+ return u8(`${E2E_VERSION}|${frameType ?? ''}|${dbSessionId ?? ''}|${k}|${epoch ?? ''}`)
+}
+export function wrapPayload(key, k, counter, frameType, dbSessionId, payload, epoch) {
+ const ct = aeadSeal(key, counter, aad(frameType, dbSessionId, k, epoch), u8(JSON.stringify(payload ?? null)))
+ const env = { v: E2E_VERSION, k, n: counter, ct: ct.toString('base64') }
+ if (epoch !== undefined) env.epoch = epoch // omitted for pairwise frames — it is in the AAD
+ return { __e2e: env }
+}
+
+// ── pairing code ───────────────────────────────────────────────────────────────────────────────────
+export function normalizeCode(code) {
+ return code.toUpperCase().replace(/[\s\-·_]/g, '')
+ .replace(/I/g, '1').replace(/L/g, '1').replace(/O/g, '0').replace(/U/g, 'V')
+}
+
+// ── self-test against the device's golden vectors ──────────────────────────────────────────────────
+if (process.argv[1] && process.argv[1].endsWith('e2ee-core.mjs') && process.argv.includes('--selftest')) {
+ const { existsSync, readFileSync } = await import('node:fs')
+ const vectorCandidates = [
+ process.env.E2EE_VECTORS_PATH,
+ new URL('../../../autonomous-code/apps/esp32-square/main/e2ee/e2ee_vectors.h', import.meta.url).pathname,
+ new URL('../../../autonomous-code/apps/esp32-square-s3/main/e2ee/e2ee_vectors.h', import.meta.url).pathname,
+ new URL('../../apps/esp32-square/main/e2ee/e2ee_vectors.h', import.meta.url).pathname,
+ new URL('../../apps/esp32-square-s3/main/e2ee/e2ee_vectors.h', import.meta.url).pathname,
+ ].filter(Boolean)
+ const vectorPath = vectorCandidates.find((path) => existsSync(path))
+ if (!vectorPath) {
+ console.error(`cannot find e2ee_vectors.h; tried:\n${vectorCandidates.map((path) => ` ${path}`).join('\n')}`)
+ process.exit(1)
+ }
+ const src = readFileSync(vectorPath, 'utf8')
+ const V = {}
+ for (const [, k, v] of src.matchAll(/#define\s+(E2EV_\w+)\s+"([^"]*)"/g)) V[k] = v
+ for (const [, k, body] of src.matchAll(/static const uint8_t\s+(E2EV_\w+)\[\]\s*=\s*\{([^}]*)\}/g)) {
+ V[k] = Buffer.from(body.split(',').map((s) => s.trim()).filter(Boolean).map(Number))
+ }
+ let pass = 0, fail = 0
+ const eq = (name, a, b) => {
+ const ok = Buffer.isBuffer(a) ? a.equals(b) : a === b
+ ok ? (pass++, console.log(' ok ', name)) : (fail++, console.log(' FAIL', name))
+ }
+ // Deterministic LCG — byte-identical to the C suite and core.test.ts seeded().
+ let S = 0
+ const lcg = (seed, n) => { S = seed; return Buffer.from(Array.from({ length: n }, () => {
+ S = (Math.imul(S, 1103515245) + 12345) & 0x7fffffff; return S & 0xff })) }
+
+ eq('expand_message_xmd', expandMessageXMD64(V.E2EV_GENSTR, CPACE_DSI), V.E2EV_XMD64)
+ const g = cpaceGenerator(V.E2EV_CODE, V.E2EV_SID, V.E2EV_CI)
+ eq('cpace_generator', Buffer.from(g.toBytes()), V.E2EV_GENERATOR)
+ const ya = scalarReduce64(lcg(1, 64))
+ const yb = scalarReduce64(lcg(2, 64))
+ eq('cpace Ya', Buffer.from(g.multiply(ya).toBytes()), V.E2EV_YA)
+ eq('cpace Yb', Buffer.from(g.multiply(yb).toBytes()), V.E2EV_YB)
+ const K = cpaceShared(V.E2EV_YA, yb)
+ eq('cpace K', K, V.E2EV_K)
+ const isk = cpaceISK(V.E2EV_SID, K, V.E2EV_YA, V.E2EV_YB)
+ eq('cpace_isk', isk, V.E2EV_ISK)
+ const th = transcriptHash(V.E2EV_SID, V.E2EV_CI, V.E2EV_YA, V.E2EV_YB)
+ eq('transcript_hash', th, V.E2EV_TH)
+ const kc = kcKeys(isk, V.E2EV_CI)
+ eq('kc_adapter', kc.adapter, V.E2EV_KC_ADAPTER)
+ eq('kc_responder', kc.responder, V.E2EV_KC_RESPONDER)
+ eq('mac_A', macTag(kc.adapter, th), V.E2EV_MAC_A)
+ eq('mac_B', macTag(kc.responder, th), V.E2EV_MAC_B)
+ eq('pair_key', pairKey(isk, V.E2EV_CI), V.E2EV_PAIRKEY)
+ const seedB = lcg(20, 32)
+ eq('identity pub', edPublicFromSeed(seedB), V.E2EV_IDB_PUB)
+ eq('pair_bind_sig', pairBindSig(seedB, th), V.E2EV_IDB_BINDSIG)
+ eq('fingerprint', fingerprint(edPublicFromSeed(seedB)), V.E2EV_IDB_FP)
+ const ephB = lcg(4, 32)
+ eq('ephB pub', xPublicFromSeed(ephB), V.E2EV_EPHB_PUB)
+ const sess = sessionKeys(ephB, V.E2EV_EPHA_PUB, V.E2EV_AGENT, V.E2EV_EPHB_PUB, V.E2EV_EPHA_PUB)
+ eq('session c2s', sess.c2s, V.E2EV_C2S)
+ eq('session s2c', sess.s2c, V.E2EV_S2C)
+ const ct = Buffer.from(V.E2EV_AEAD_CT_B64, 'base64')
+ const a = aad('commander_event', 'sess1', 'g', V.E2EV_AEAD_EPOCH)
+ eq('aead_open', aeadOpen(V.E2EV_GROUPKEY, 0, a, ct).toString(), '{"kind":"processing","text":"hi"}')
+ eq('aead_seal', aeadSeal(V.E2EV_GROUPKEY, 0, a, Buffer.from('{"kind":"processing","text":"hi"}')), ct)
+ eq('normalizeCode', normalizeCode('k7p-4x9'), 'K7P4X9')
+ console.log(`\n${pass} passed, ${fail} failed`)
+ process.exit(fail ? 1 : 0)
+}
diff --git a/backend/scripts/release-be.sh b/backend/scripts/release-be.sh
new file mode 100755
index 000000000..d741efb41
--- /dev/null
+++ b/backend/scripts/release-be.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Cut a backend release: bump the version, tag HEAD `vX.Y.Z`, push the tag.
+#
+# ./scripts/release-be.sh # patch bump (v1.1.2 -> v1.1.3)
+# ./scripts/release-be.sh minor # v1.1.2 -> v1.2.0
+# ./scripts/release-be.sh major # v1.1.2 -> v2.0.0
+# ./scripts/release-be.sh 1.4.1 # exact version -> v1.4.1
+# ./scripts/release-be.sh --dry-run # print what it WOULD do, touch nothing
+#
+# Pushing the tag is the whole point: .github/workflows/production-be-build.yaml triggers on
+# SemVer tags (`vX.Y.Z`) and builds
+# Dockerfile.k8s -> autonomous-code-be.
+# The image ArgoCD deploys is named after this tag, so the tag must point at the commit you want live.
+# Bash 3.2-compatible (macOS default).
+set -euo pipefail
+
+SERVICE="backend (autonomous-code-be)"
+WORKFLOW=".github/workflows/production-be-build.yaml"
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+DRY_RUN=0
+BUMP="patch"
+for arg in "$@"; do
+ case "$arg" in
+ --dry-run) DRY_RUN=1 ;;
+ patch|minor|major) BUMP="$arg" ;;
+ [0-9]*.[0-9]*.[0-9]*) BUMP="exact"; EXACT="${arg#v}" ;;
+ *) echo "usage: $0 [patch|minor|major|X.Y.Z] [--dry-run]" >&2; exit 1 ;;
+ esac
+done
+
+if [[ "$BUMP" == "exact" ]] &&
+ ! [[ "$EXACT" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+ echo "ERROR exact version '$EXACT' is invalid; use SemVer X.Y.Z (for example 1.4.1)." >&2
+ exit 1
+fi
+
+# --- preflight: the tag names a commit, so that commit must be the right one and must be on origin.
+git fetch --tags --quiet origin
+
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+HEAD_SHA="$(git rev-parse HEAD)"
+
+if [[ -n "$(git status --porcelain)" ]]; then
+ echo "ERROR working tree is dirty — release tags must capture the tested source exactly:" >&2
+ git status --short | sed 's/^/ /' >&2
+ exit 1
+fi
+
+if ! git merge-base --is-ancestor "$HEAD_SHA" "origin/$BRANCH" 2>/dev/null; then
+ echo "ERROR HEAD is not on origin/$BRANCH — push the commit first, or CI will build a commit nobody else has." >&2
+ exit 1
+fi
+
+# --- next version: highest valid SemVer release tag, then bump.
+# `sort -V` handles numeric ordering while grep drops malformed tags.
+LATEST="$(git tag -l 'v*' \
+ | { grep -E '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$' || true; } \
+ | sed -E 's/^v//' \
+ | sort -V | tail -1)"
+LATEST="${LATEST:-0.0.0}"
+
+MAJOR="${LATEST%%.*}"
+REST="${LATEST#*.}"
+MINOR="${REST%%.*}"
+PATCH="${REST#*.}"
+
+case "$BUMP" in
+ patch) NEXT="$MAJOR.$MINOR.$((PATCH + 1))" ;;
+ minor) NEXT="$MAJOR.$((MINOR + 1)).0" ;;
+ major) NEXT="$((MAJOR + 1)).0.0" ;;
+ exact) NEXT="$EXACT" ;;
+esac
+
+TAG="v${NEXT}"
+
+if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+ echo "ERROR tag $TAG already exists. Re-tagging a released version breaks the image<->commit mapping." >&2
+ exit 1
+fi
+
+echo " service : $SERVICE"
+echo " branch : $BRANCH @ $(git rev-parse --short HEAD) $(git log -1 --format=%s | cut -c1-60)"
+echo " latest : v$LATEST"
+echo " new tag : $TAG [$BUMP]"
+
+if [[ "$DRY_RUN" == "1" ]]; then
+ echo " DRY RUN — nothing tagged or pushed."
+ exit 0
+fi
+
+git tag -a "$TAG" -m "$SERVICE release $TAG"
+git push origin "$TAG"
+
+echo ""
+echo " pushed $TAG → CI builds autonomous-code-be and rolls it out. Nothing else to do."
+echo " watch : gh run list --workflow='Docker production backend build' --limit 3"
diff --git a/backend/scripts/terminal-local-db-fixture.mjs b/backend/scripts/terminal-local-db-fixture.mjs
new file mode 100755
index 000000000..ff8c58e3b
--- /dev/null
+++ b/backend/scripts/terminal-local-db-fixture.mjs
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto'
+import { createRequire } from 'node:module'
+
+const requireFromBackend = createRequire(new URL('../package.json', import.meta.url))
+const { PrismaClient } = requireFromBackend('@prisma/client')
+
+const apiKey = process.env.LOCAL_TERMINAL_E2E_API_KEY ?? ''
+if (!/^[a-f0-9]{64}$/.test(apiKey)) {
+ console.error('LOCAL_TERMINAL_E2E_API_KEY must be exactly 64 lowercase hex characters')
+ process.exit(64)
+}
+if (!process.env.DATABASE_URL) {
+ console.error('DATABASE_URL is required')
+ process.exit(64)
+}
+
+const machineId = createHash('sha256').update(apiKey).digest('hex').slice(0, 32)
+const externalId = `local-terminal-e2e-${machineId}`
+const email = `${externalId}@local.invalid`
+const prisma = new PrismaClient()
+
+try {
+ const user = await prisma.user.upsert({
+ where: { email },
+ update: { externalId, autonomousEnv: 'prod' },
+ create: { email, externalId, autonomousEnv: 'prod', name: 'Local terminal E2E' },
+ })
+ await prisma.machine.upsert({
+ where: { machineId },
+ update: {
+ userId: user.id,
+ apiKey,
+ managerId: 'local-terminal-e2e',
+ autonomousEnv: 'prod',
+ authMode: 'remote',
+ billingStatus: 'not_required',
+ deletedAt: null,
+ name: 'local-terminal-e2e',
+ },
+ create: {
+ userId: user.id,
+ machineId,
+ apiKey,
+ managerId: 'local-terminal-e2e',
+ autonomousEnv: 'prod',
+ authMode: 'remote',
+ billingStatus: 'not_required',
+ name: 'local-terminal-e2e',
+ },
+ })
+ process.stdout.write(`${JSON.stringify({ machineId, machineName: 'local-terminal-e2e' })}\n`)
+} finally {
+ await prisma.$disconnect()
+}
diff --git a/backend/src/config/env.ts b/backend/src/config/env.ts
new file mode 100644
index 000000000..37d6c2bb7
--- /dev/null
+++ b/backend/src/config/env.ts
@@ -0,0 +1,226 @@
+import 'dotenv/config'
+import { z } from 'zod'
+
+const envSchema = z.object({
+ NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+
+ // The single web-facing port: control API + data-plane reverse proxy.
+ PORT: z.string().default('8085').transform(Number),
+
+ // Dedicated PUBLIC subdomain app-proxy port. Traffic to [sub].<APP_DOMAIN_SUFFIX> hits this
+ // listener (Host-header routed), separate from the api-key control/`/proxy` plane on PORT.
+ PORT_APP_PROXY: z.string().default('8087').transform(Number),
+ // Domain suffix stripped from the Host header to get the subdomain (e.g. ".harness.autonomous.ai").
+ APP_DOMAIN_SUFFIX: z.string().default('.harness.autonomous.ai'),
+
+ // Same MongoDB (and database) as the agent-manager — backend owns `users` +
+ // `machines`; reads `managers`/`machine_nodes` via raw queries when needed.
+ DATABASE_URL: z.string().default('mongodb://localhost:27017/harness?replicaSet=rs0'),
+
+ // Redis for the cross-instance data bus. Behind a load balancer an agent's web socket and its
+ // manager socket may land on different backend instances; Redis pub/sub bridges them
+ // (channels up:{machineId} / down:{machineId}) plus an agent→manager presence key. See lib/bus.ts.
+ REDIS_URL: z.string().default('redis://localhost:6379'),
+
+ // This backend instance's stable id (used to route manager-command replies via Redis in a
+ // multi-instance deploy). Defaults to the pm2 instance index or a per-process fallback.
+ BACKEND_INSTANCE_ID: z.string().default(''),
+
+ // Instance mesh (Phase 2 of the data-plane short-circuit): each backend instance/worker binds an
+ // INTERNAL-only listener and advertises its endpoint in Redis (inst:{id}:mesh). A public app-request
+ // that lands on an instance NOT holding the agent's manager socket is forwarded to the instance that
+ // does (agent:{machineId}:appinst), so the data path is a direct backpressured socket, not Redis relay.
+ // Off by default (single-instance/dev needs nothing — it's always co-located). Enable in multi-instance.
+ MESH_ENABLED: z.string().default('false').transform((v) => v === 'true'),
+ // Host the mesh endpoint is reachable at from OTHER instances: 127.0.0.1 for a single-host pm2 cluster,
+ // the VM's routable IP for multi-VM. Advertised verbatim in Redis.
+ MESH_HOST: z.string().default('127.0.0.1'),
+ // Base internal port; each worker binds MESH_PORT_BASE + NODE_APP_INSTANCE (distinct per worker).
+ MESH_PORT_BASE: z.string().default('8095').transform(Number),
+
+ // Remote-terminal WebRTC is STUN-only: successful ICE bypasses the backend data relay; failed ICE
+ // keeps using the existing WebSocket route. Enabled by default; percentage 0 is the kill switch.
+ TERMINAL_P2P_ROLLOUT_PERCENT: z.coerce.number().int().min(0).max(100).default(100),
+ // Comma-separated, capped at ten (was eight until 2026-09-10 — the CLI's own parsing of this list on
+ // the OFFERER side, remoteRelay.ts's p2pPolicy(), was separately capping at 4, so half of whatever
+ // shipped here was silently dropped before an offer was ever built; raised there to 10 to match).
+ // werift itself has no failover — parseIceServers() collapses the list to a single `stunServer`
+ // (first stun: url wins) — so the CLI races these with its own STUN binding requests and hands
+ // werift the fastest responder (cli/src/lib/stunSelect.ts). Older CLIs simply use the first entry,
+ // exactly as before, so a longer list is safe to ship at any time.
+ // Port 53 is here because networks that drop unusual UDP ports usually still pass DNS; the race
+ // drops it at runtime if it ever stops answering, so listing it costs nothing.
+ // Beyond Cloudflare: two Google mirrors, Twilio, Nextcloud (also firewall-friendly :443), Ekiga and
+ // VoIPGate — all live-probed with a real RFC 5389 binding request before being added (2026-09-09);
+ // stun.stunprotocol.org and stun.services.mozilla.com were dropped for the same reason (no DNS record
+ // any more). Added 2026-09-10, also live-probed: Linphone's official server (Belledonne
+ // Communications — has its own documented DNS-SRV failover to sip1.linphone.org, unlike the
+ // similarly-themed stun.freeswitch.org and stun.antisip.com candidates considered and rejected —
+ // the former has open GitHub issues reporting real instability, the latter has no confirmed owner at
+ // all) and Xiaomi's MiWiFi server, which is real production infra for millions of routers and — more
+ // to the point — the one entry here actually reachable from behind networks that block the Western
+ // majority of this list, filling a gap none of the other eight cover.
+ TERMINAL_P2P_STUN_URLS: z.string().default(
+ 'stun:stun.cloudflare.com:3478,stun:stun.cloudflare.com:53,'
+ + 'stun:stun.l.google.com:19302,stun:stun2.l.google.com:19302,'
+ + 'stun:global.stun.twilio.com:3478,stun:stun.nextcloud.com:443,'
+ + 'stun:stun.ekiga.net:3478,stun:stun.voipgate.com:3478,'
+ + 'stun:stun.linphone.org:3478,stun:stun.miwifi.com:3478',
+ ),
+ // 2500, not 1500: a TURN-relayed data channel was measured opening in 1372ms, and this is the gate
+ // (remoteRelay.ts) that decides whether the FIRST terminal takes p2p or falls back to the WS relay.
+ // At 1500 the relay path loses that race almost every time and only the second terminal gets p2p.
+ TERMINAL_P2P_OPEN_WAIT_MS: z.coerce.number().int().min(0).max(5000).default(2500),
+
+ // Cloudflare Realtime TURN. Optional on purpose: with no key the policy ships STUN-only, which is
+ // exactly the pre-TURN behaviour, so clearing TERMINAL_P2P_TURN_KEY_ID is the kill switch. Checked
+ // at the consumer (lib/turnCredentials.ts), not here — same as GEMINI_API_KEY/DEEPGRAM_API_KEY.
+ TERMINAL_P2P_TURN_KEY_ID: z.string().optional(),
+ TERMINAL_P2P_TURN_API_TOKEN: z.string().optional(),
+ // Cloudflare caps credential ttl at 172800 (48h); we refresh well before expiry anyway.
+ TERMINAL_P2P_TURN_TTL_SECONDS: z.coerce.number().int().min(600).max(172800).default(7200),
+ TERMINAL_P2P_TURN_TIMEOUT_MS: z.coerce.number().int().min(1000).max(30000).default(5000),
+
+ // No manager env: each manager publishes its apiKey + capacity into the `managers` collection;
+ // the backend authenticates the manager's dial-in socket (/api/manager-ws) against that apiKey and
+ // picks a manager on create by capacity (machines.managerId → managers). See lib/managers.ts.
+
+ // Autonomous SSO (OAuth2 Authorization Code + PKCE). The backend exchanges the code, then hands
+ // the SSO access token to the web. Control-plane REST + web WS validate that token through the
+ // Autonomous profile API instead of minting a second backend-owned session JWT.
+ SSO_ISSUER: z.string().default('https://auth.autonomous.ai'),
+ SSO_CLIENT_ID: z.string().default('command_57db108dd2391a9a4bedd6d079bdbe3e'),
+ SSO_CLIENT_SECRET: z.string().optional(), // public client (PKCE, auth method 'none') → leave unset
+ SSO_SCOPE: z.string().default('openid profile email roles'),
+ SSO_PROFILE_URL: z.string().default('https://apiv2.autonomous.ai/api/v1/me/profile'),
+ // Per-user staging override. Production remains the default; these are consulted only after the
+ // login transaction/user record explicitly selects `stag`.
+ STAGING_SSO_ISSUER: z.string().default('https://auth.staging.autonomousdev.xyz'),
+ STAGING_SSO_CLIENT_ID: z.string().optional(),
+ STAGING_SSO_CLIENT_SECRET: z.string().optional(),
+ STAGING_SSO_PROFILE_URL: z.string().default('https://apiv2.staging.autonomousdev.xyz/api/v1/me/profile'),
+ SSO_PROFILE_TIMEOUT_MS: z.coerce.number().int().positive().default(5000),
+ // Forces the SSO account picker so users can switch accounts (not silently auto-login the last one).
+ // Set to '' to disable, or 'login' to force re-entering credentials.
+ SSO_PROMPT: z.string().default('select_account'),
+ // Backend callback registered with the SSO client. LEAVE EMPTY to auto-derive from the request host
+ // (so live→live, local→local); set explicitly only to pin one value. Must be a value registered
+ // with the client on the Autonomous side.
+ SSO_REDIRECT_URI: z.string().default(''),
+ // The primary/fallback SPA origin the browser is sent back to after login (also the first allowed
+ // origin). Live sets this to https://harness.autonomous.ai.
+ WEB_URL: z.string().default('http://localhost:3000'),
+ // Extra allowed SPA origins (comma-separated), e.g. to let one backend serve both live + local.
+ // The post-login token is only ever redirected to an origin in this allowlist (never an arbitrary
+ // one from the request), so it can't be leaked to a spoofed host.
+ WEB_ORIGINS: z.string().default(''),
+
+ // Autonomous campaign billing for NEW managed machines. A cold catalog outage still cannot expose
+ // incomplete plans: the seeder retains a complete cache or falls back to Remote only.
+ HARNESS_BILLING_ENABLED: z.string().default('true').transform((v) => v === 'true'),
+ // Ceiling on billing-free Remote machines auto-created by the device-auth grant
+ // (`harness auth device`). That path is free and its computer id is self-declared, so this caps the
+ // rows one account can mint; 0 disables the check. Hygiene, not a security control.
+ HARNESS_DEVICE_AUTH_MACHINE_LIMIT: z.coerce.number().int().min(0).default(20),
+ AUTONOMOUS_BFF_URL: z.string().url().default('https://apiv2.autonomous.ai'),
+ STAGING_AUTONOMOUS_BFF_URL: z.string().url().default('https://apiv2.staging.autonomousdev.xyz'),
+ // Server-to-server subscription snapshots used by the singleton billing worker. These use
+ // environment-specific x-api-key credentials, never a user's SSO access token.
+ AUTONOMOUS_CAMPAIGN_API_URL: z.string().url().default('https://campaign-api.autonomous.ai'),
+ STAGING_AUTONOMOUS_CAMPAIGN_API_URL: z.string().url().default('https://campaign-api.staging.autonomousdev.xyz'),
+ AUTONOMOUS_CAMPAIGN_API_KEY: z.string().optional(),
+ STAGING_AUTONOMOUS_CAMPAIGN_API_KEY: z.string().optional(),
+ // Origins accepted by Autonomous' hosted-checkout endpoint. They belong to the selected
+ // Autonomous environment, not to the Machine UI that supplied success_url/failure_url.
+ AUTONOMOUS_CHECKOUT_ORIGIN: z.string().url().default('https://autonomous.ai'),
+ STAGING_AUTONOMOUS_CHECKOUT_ORIGIN: z.string().url().default('https://staging.autonomousdev.xyz'),
+ AUTONOMOUS_BFF_TIMEOUT_MS: z.coerce.number().int().positive().default(10000),
+ // NB: the VALUE is an identifier registered on the EXTERNAL campaign API — subscriptions are matched
+ // by campaignCode, so this must stay in lockstep with the campaign registered there. Renamed to
+ // `ai-harness-device` with the Machine rebrand: the campaign has to be renamed on the campaign side
+ // too, otherwise existing subscriptions stop matching and machines read as unpaid.
+ HARNESS_CAMPAIGN_CODE: z.string().default('ai-harness-device'),
+ HARNESS_DEVICE_TYPE: z.coerce.number().int().positive().default(15),
+ HARNESS_DEVICE_TIMEZONE_DEFAULT: z.string().default('Asia/Saigon'),
+ // DEV ONLY. A `provider` machine dials a URL its owner typed, so plain http:// and loopback are
+ // refused (see lib/providerUrl.ts). This flag lifts the scheme check so a developer can point a
+ // machine at a local example-provider (autonomous-ai/autonomous-harness). Setting it in production
+ // disables an SSRF control — boot
+ // logs a FATAL-level warning if it is on there.
+ PROVIDER_ALLOW_INSECURE_URLS: z.coerce.boolean().default(false),
+ // Callback page on the web app. When empty, WEB_URL/machine-checkout is used.
+ HARNESS_CHECKOUT_CALLBACK_URL: z.string().default(''),
+ // Shared with agent-manager. 32 raw bytes encoded as base64; required when billing is enabled.
+ HARNESS_CREDENTIAL_ENCRYPTION_KEY: z.string().default(''),
+
+ // Comma-separated emails granted role=admin on first creation.
+ ADMIN_EMAILS: z.string().default(''),
+
+ // Device voice STT (PCM arrives on /api/device-ws → batch STT). VOICE_PROVIDER selects the backend:
+ // 'deepgram' → needs DEEPGRAM_API_KEY
+ // 'gemini' → needs GEMINI_API_KEY (model via GEMINI_STT_MODEL)
+ VOICE_PROVIDER: z.enum(['deepgram', 'gemini']).default('deepgram'),
+ DEEPGRAM_API_KEY: z.string().optional(),
+ GEMINI_API_KEY: z.string().optional(),
+ GEMINI_STT_MODEL: z.string().default('gemini-2.0-flash'),
+
+ // Shared secret for POST /api/cursor/stt — the standalone file-upload STT endpoint the Cursor desktop
+ // app calls (routes/cursor.ts). That client is neither a device nor a browser session, so it holds
+ // no machine api key and no SSO token; this is its only credential, sent as the `api_key` header.
+ // Optional here, but the route fails CLOSED when unset: an absent secret must never read as "open" on
+ // an endpoint that spends Deepgram credit.
+ CURSOR_STT_API_KEY: z.string().optional(),
+
+ // The LLM behind POST /api/cursor/summarize — an OpenAI-compatible endpoint (the Grid relay). The base
+ // URL already ends in `/v1` and embeds a network id, and the key is a long-lived JWT, so neither is
+ // hardcoded; routes/cursor.ts appends `/chat/completions`. URL and key are optional here but the route
+ // fails CLOSED without them, for the same reason CURSOR_STT_API_KEY does: this endpoint spends credit.
+ CURSOR_LLM_BASE_URL: z.string().optional(),
+ CURSOR_LLM_API_KEY: z.string().optional(),
+ CURSOR_LLM_MODEL: z.string().default('DeepSeek-V4-Flash-0731'),
+
+ // TTL for the in-memory subdomain→machineId cache on the public app-proxy hot path
+ // (avoids a Mongo lookup per request). Bounds staleness after a cross-instance app teardown.
+ // 60 min default (mapping is stable; a same-instance delete evicts immediately).
+ AGENT_TARGET_CACHE_TTL_MS: z.string().default('3600000').transform(Number),
+ // TTL for NEGATIVE caching of unknown subdomains — so scans/misconfigured DNS hitting nonexistent
+ // subdomains don't hit Mongo on every request. Short so a subdomain registered on another instance
+ // becomes reachable quickly. 5s default.
+ AGENT_TARGET_NEG_CACHE_TTL_MS: z.string().default('5000').transform(Number),
+
+ // Public app-proxy safety limits. 0 disables the byte limit for that direction. These protect the
+ // unauthenticated subdomain data-plane from unbounded tunnel/socket buffering.
+ APP_PROXY_MAX_REQUEST_BYTES: z.string().default('104857600').transform(Number), // 100 MiB
+ APP_PROXY_MAX_RESPONSE_BYTES: z.string().default('536870912').transform(Number), // 512 MiB
+ APP_PROXY_MAX_WS_FRAME_BYTES: z.string().default('8388608').transform(Number), // 8 MiB
+ APP_PROXY_MAX_STREAMS_PER_SUBDOMAIN: z.string().default('128').transform(Number),
+ APP_PROXY_IDLE_TIMEOUT_MS: z.string().default('300000').transform(Number), // 5 min
+
+})
+
+export type Env = z.infer<typeof envSchema>
+
+function validateEnv(): Env {
+ const parsed = envSchema.safeParse(process.env)
+ if (!parsed.success) {
+ console.error('Invalid environment variables:', parsed.error.flatten().fieldErrors)
+ process.exit(1)
+ }
+ const data = parsed.data
+ if (data.HARNESS_BILLING_ENABLED) {
+ let key: Buffer
+ try { key = Buffer.from(data.HARNESS_CREDENTIAL_ENCRYPTION_KEY, 'base64') } catch { key = Buffer.alloc(0) }
+ if (key.length !== 32) {
+ console.error('Invalid environment variables: HARNESS_CREDENTIAL_ENCRYPTION_KEY must be 32 bytes encoded as base64 when HARNESS_BILLING_ENABLED=true')
+ process.exit(1)
+ }
+ }
+ return data
+}
+
+export const env = validateEnv()
+
+/** Lower-cased set of admin emails (empty entries dropped). */
+export const ADMIN_EMAILS = new Set(
+ env.ADMIN_EMAILS.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean),
+)
diff --git a/backend/src/errors/AppError.ts b/backend/src/errors/AppError.ts
new file mode 100644
index 000000000..f578c429d
--- /dev/null
+++ b/backend/src/errors/AppError.ts
@@ -0,0 +1,53 @@
+export class AppError extends Error {
+ constructor(
+ public message: string,
+ public statusCode: number = 500,
+ public code?: string
+ ) {
+ super(message)
+ this.name = 'AppError'
+ Error.captureStackTrace(this, this.constructor)
+ }
+}
+
+export class NotFoundError extends AppError {
+ constructor(resource: string) {
+ super(`${resource} not found`, 404, 'NOT_FOUND')
+ this.name = 'NotFoundError'
+ }
+}
+
+export class ValidationError extends AppError {
+ constructor(message: string) {
+ super(message, 400, 'VALIDATION_ERROR')
+ this.name = 'ValidationError'
+ }
+}
+
+export class UnauthorizedError extends AppError {
+ constructor(message = 'Unauthorized') {
+ super(message, 401, 'UNAUTHORIZED')
+ this.name = 'UnauthorizedError'
+ }
+}
+
+export class ForbiddenError extends AppError {
+ constructor(message = 'Forbidden') {
+ super(message, 403, 'FORBIDDEN')
+ this.name = 'ForbiddenError'
+ }
+}
+
+export class ConflictError extends AppError {
+ constructor(message: string) {
+ super(message, 409, 'CONFLICT')
+ this.name = 'ConflictError'
+ }
+}
+
+export class InternalError extends AppError {
+ constructor(message = 'Internal server error') {
+ super(message, 500, 'INTERNAL_ERROR')
+ this.name = 'InternalError'
+ }
+}
diff --git a/backend/src/errors/index.ts b/backend/src/errors/index.ts
new file mode 100644
index 000000000..52b0d4f7f
--- /dev/null
+++ b/backend/src/errors/index.ts
@@ -0,0 +1 @@
+export * from './AppError.js'
diff --git a/backend/src/lib/adapterWs.ts b/backend/src/lib/adapterWs.ts
new file mode 100644
index 000000000..1574268f7
--- /dev/null
+++ b/backend/src/lib/adapterWs.ts
@@ -0,0 +1,420 @@
+/**
+ * Backend hub — remote-machine adapter endpoint (`/api/adapter-ws`).
+ *
+ * A "remote" machine has no manager/agent-node: the user's own COMPUTER runs the machine-adapter CLI,
+ * which dials in here and occupies the NODE side of the machineId — the same role a manager socket
+ * plays for a docker node:
+ * - down:{machineId} (client chat/RPC) → forwarded to the adapter socket
+ * - adapter `up` frames (normalized claude events + `<x>_result` RPC replies) → publishUp(machineId)
+ * - presence key machine:{machineId}:mgr = 'remote' while connected → drives web node_status
+ *
+ * Auth: the first WebSocket subprotocol is the user's SSO access token. The stable `computer` query
+ * parameter selects (or creates) that user's Remote machine; a managed machine never gains a second
+ * writer for its down:{machineId} channel.
+ */
+import type { IncomingMessage } from 'http'
+import type { Duplex } from 'stream'
+import { WebSocketServer, WebSocket, type RawData } from 'ws'
+import { prisma } from './prisma.js'
+import {
+ publishUp, claimMachineOwner, releaseMachineOwner, publishDeviceE2eePair,
+ publishTerminalUp, subscribeTerminalDown,
+ setMachineAppState, clearMachineAppState,
+} from './bus.js'
+import { trackSocketLiveness } from './hub.js'
+import { attachNodeRole, PRESENCE_TTL_SEC } from './nodeRole.js'
+import { recordCreatedAgent, recordDeletedAgent } from './agentTracker.js'
+import type { Frame } from './tunnel.js'
+import { logger } from '../utils/logger.js'
+import { machineBillingAllowsDataPlane } from './billingState.js'
+import { normalizeComputerId } from './deviceAuth.js'
+import { authenticateAccessToken, SsoAuthError } from './ssoAuth.js'
+import { parseAutonomousEnvironment } from './autonomousEnvironment.js'
+import { machineService } from '../services/MachineService.js'
+import { AppError } from '../errors/index.js'
+import {
+ isEncryptedTerminalFrame,
+ TERMINAL_ENVELOPE_MAX_BYTES,
+ TERMINAL_UP_TYPES,
+ terminalFrameBytes,
+ TerminalRateGuard,
+} from './terminalRelay.js'
+import { decodeTerminalHop, TerminalBinaryKind, TerminalHopDirection } from './terminalBinary.js'
+import {
+ isEncryptedP2pFrame,
+ P2P_SIGNAL_MAX_BYTES,
+ P2P_UP_TYPES,
+ p2pFrameBytes,
+ P2pSignalRateGuard,
+ terminalP2pPolicy,
+} from './p2pSignaling.js'
+
+const wss = new WebSocketServer({
+ noServer: true,
+ handleProtocols: (protocols) => {
+ const first = [...protocols][0]
+ return first ?? false
+ },
+})
+
+// machineId → the current adapter socket. One writer per machineId: down:{machineId} must have exactly
+// one consumer, so a reconnecting adapter supersedes its predecessor (same as attachNode does).
+const owners = new Map<string, WebSocket>()
+
+/** Frames the adapter sends us. `up.frame` is opaque (ServerEvents / `<x>_result` replies /
+ * commander_event device cards). Eligibility is per-frame: web defaults true, commander defaults
+ * false — the adapter opts device frames in (mirrors the node's managerSocket.emitUp channels). */
+type AdapterFrame =
+ | { t: 'up'; frame: Frame; webEligible?: boolean; commanderEligible?: boolean; targetConnId?: string; userEligible?: boolean }
+ | { t: 'ping' }
+
+// Which desktop app a remote computer drives, and whether it is running. Sent as an `up` frame with
+// BOTH eligibility flags false, so it reaches the per-machine subscribeUp watchers (deviceWs) without
+// ever being fanned out to an attached client — no existing firmware can see an unknown frame type.
+const APP_ENGINES = new Set(['cursor'])
+const APP_STATES = new Set(['open', 'closed', 'missing'])
+
+// `?v=` is self-declared by the client, so it is never persisted raw: anything outside a plain
+// semver-ish token (or longer than 64 chars) is dropped rather than stored.
+const CLIENT_VERSION_RE = /^[A-Za-z0-9._+-]{1,64}$/
+
+function sanitizeClientVersion(raw: string | null): string | undefined {
+ const v = raw?.trim()
+ return v && CLIENT_VERSION_RE.test(v) ? v : undefined
+}
+
+/** Adapter authentication is SSO-only: accept precisely the first WS subprotocol, never x-api-key. */
+function accessTokenFromProtocol(req: IncomingMessage): string | undefined {
+ const raw = req.headers['sec-websocket-protocol']
+ const first = (Array.isArray(raw) ? raw[0] : raw)?.split(',')[0]?.trim()
+ return first || undefined
+}
+
+/** Fastify/http upgrade hook for `/api/adapter-ws`. Auth = user SSO access token. */
+export function handleAdapterUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
+ // Reject with an explicit HTTP 401 (not a silent destroy) so the adapter's ws client surfaces
+ // "Unexpected server response: 401" — which it treats as a FATAL deauthorization (deleted/unknown
+ // machine) and clears its saved token, instead of an ambiguous close-1006 it would retry forever.
+ const deny = (): void => {
+ try { socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
+ socket.destroy()
+ }
+ // One computer per machine: when a DIFFERENT computer already holds this machine, reject with an
+ // explicit HTTP 409 (not 401 — the adapter treats 401/403 as deauth and would WIPE its valid token).
+ // The adapter surfaces 409 as an info message ("already connected from another computer") and stops.
+ const denyBusy = (): void => {
+ try { socket.write('HTTP/1.1 409 Conflict\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
+ socket.destroy()
+ }
+ // Billing suspension is retryable: unlike 401/403, the adapter must retain its token so it can
+ // reconnect automatically after the owner renews or re-subscribes.
+ const denyPayment = (): void => {
+ try { socket.write('HTTP/1.1 402 Payment Required\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
+ socket.destroy()
+ }
+ const accessToken = accessTokenFromProtocol(req)
+ if (!accessToken) { deny(); return }
+ // The adapter sends its computer's hostname as `?label=`, a stable `?computer=` id, its version,
+ // and the selected Autonomous environment. `computer` is required: without it the backend has no
+ // safe way to choose between a user's Remote machines.
+ let label: string | undefined
+ let computerId: string | undefined
+ let clientVersion: string | undefined
+ let claimedMachineId: string | undefined
+ let autonomousEnv: 'prod' | 'stag' = 'prod'
+ try {
+ const params = new URL(req.url ?? '', 'http://x').searchParams
+ label = params.get('label') || undefined
+ computerId = normalizeComputerId(params.get('computer') ?? '') ?? undefined
+ // The machine id this daemon still believes it is. Optional: a freshly logged-in CLI has none
+ // yet. When present it lets `resolveOrCreateForComputer` tell a REVOKED daemon apart from a
+ // first-time pairing, instead of silently minting it a replacement machine.
+ claimedMachineId = params.get('machine') || undefined
+ clientVersion = sanitizeClientVersion(params.get('v'))
+ autonomousEnv = parseAutonomousEnvironment(params.get('autonomousEnv'))
+ } catch { deny(); return }
+ if (!computerId) { deny(); return }
+ void (async () => {
+ let user
+ try { user = await authenticateAccessToken(accessToken, autonomousEnv) } catch (err) {
+ if (err instanceof SsoAuthError && (err.code === 'AUTONOMOUS_ENV_MISMATCH' || err.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')) {
+ try { socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
+ socket.destroy()
+ return
+ }
+ deny()
+ return
+ }
+ const resolved = await machineService.resolveOrCreateForComputer(user.sub, user.autonomousEnv, computerId, label ?? 'computer', claimedMachineId)
+ const machine = resolved.machine
+ const machineId = machine.machineId
+ if (!machineBillingAllowsDataPlane(machine)) { denyPayment(); return }
+ // Single-computer claim BEFORE upgrade/attach, so a rejected second computer never supersedes the first.
+ if (!(await claimMachineOwner(machineId, computerId, PRESENCE_TTL_SEC))) { denyBusy(); return }
+ wss.handleUpgrade(req, socket, head, (ws) => void attachAdapter(ws, machineId, machine.userId, machine.name, label, computerId, clientVersion))
+ })().catch((err) => {
+ if (err instanceof AppError) {
+ // 403 is the revoked-machine answer from `resolveOrCreateForComputer`; the CLI keys off the
+ // numeric status, but sending it under the wrong reason phrase would mislead anyone reading a
+ // packet capture or a proxy log.
+ const text = err.statusCode === 403 ? 'Forbidden' : err.statusCode === 409 ? 'Conflict' : 'Service Unavailable'
+ try { socket.write(`HTTP/1.1 ${err.statusCode} ${text}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`) } catch { /* ignore */ }
+ socket.destroy()
+ return
+ }
+ logger.warn('adapter-ws upgrade failed', { error: String(err) })
+ socket.destroy()
+ })
+}
+
+async function attachAdapter(ws: WebSocket, machineId: string, userId: string, currentName: string | null, label?: string, computerId?: string, clientVersion?: string): Promise<void> {
+ // A different computer was already rejected at the upgrade (denyBusy), so this only closes our OWN
+ // stale local socket on a same-computer reconnect landing on this worker.
+ owners.get(machineId)?.close(4000, 'superseded')
+ owners.set(machineId, ws)
+ logger.info('adapter connected', { machineId, computer: label })
+ try { ws.send(JSON.stringify({ t: 'connected', machineId })) } catch { /* ignore */ }
+
+ // Last desktop-app state THIS socket asserted. Socket-scoped on purpose: a new adapter connection
+ // starts with no claim and must re-assert, so a fresh value can never renew a stale one.
+ let appState: { engine: string; state: string } | undefined
+ const terminalRate = new TerminalRateGuard()
+ const p2pSignalRate = new P2pSignalRateGuard()
+
+ // Buffer messages from RIGHT NOW, because the real handler cannot be installed until after the
+ // `await attachNodeRole(...)` below — and `ws` drops any message emitted with no listener attached.
+ // An adapter that (reasonably) sends as soon as its socket opens therefore lost its FIRST frame,
+ // every time. That was invisible for a long while because the CLI's first frame is a resend-on-tick,
+ // so it just looked like a one-tick delay; an adapter whose first frame is one-shot state lost it
+ // outright. Buffer, then replay in order once the handler exists.
+ const preHandlerQueue: Array<[RawData, boolean]> = []
+ let onMessage: ((raw: RawData, isBinary: boolean) => void) | null = null
+ ws.on('message', (raw: RawData, isBinary: boolean) => {
+ if (onMessage) onMessage(raw, isBinary)
+ else if (preHandlerQueue.length < 64) preHandlerQueue.push([raw, isBinary])
+ })
+
+ // Two separate fields, deliberately: `hostname` tracks whichever computer connected LAST, while
+ // `name` is the user-editable display name and is only ever SEEDED here — a connect must never
+ // clobber a name the owner set. Best-effort; never blocks the connection.
+ const seededName = !currentName?.trim() && label ? label.slice(0, 120) : null
+ // Normalized on the way to Mongo so this column matches what the device-auth grant stamps — the
+ // reuse lookup is an equality match on it. The RAW `computerId` keeps driving the Redis owner claim
+ // (see the upgrade handler): that key is a self-consistent liveness token nothing joins against, and
+ // re-keying it would 409 every already-connected adapter until its old claim aged out.
+ const boundComputer = computerId ? normalizeComputerId(computerId) : null
+ if (label || seededName || clientVersion || boundComputer) {
+ void prisma.machine.update({
+ where: { machineId },
+ data: {
+ ...(label ? { hostname: label.slice(0, 120) } : {}),
+ ...(seededName ? { name: seededName } : {}),
+ // Same overwrite-every-connect rule as `hostname`; absent (old client) leaves the last value.
+ ...(clientVersion ? { clientVersion } : {}),
+ ...(boundComputer ? { computerId: boundComputer } : {}),
+ },
+ }).catch(() => { /* best effort */ })
+ }
+ // Tell the adapter its machine's display name (it mirrors it locally for `harness status`); null when
+ // unnamed so a stale mirror clears. Renames while connected arrive the same way (machine_meta).
+ try {
+ ws.send(JSON.stringify({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: currentName?.trim() || seededName } } }))
+ } catch { /* ignore */ }
+
+ // The node role — down subscription, presence, `__clients` resync, node_status — is shared with
+ // every other backer of a machine and lives in nodeRole.ts. Only the delivery and teardown are
+ // adapter-specific, so only those are passed in.
+ const role = await attachNodeRole({
+ machineId,
+ owner: 'remote',
+ offlineReason: 'remote computer offline',
+ deliver: (msg) => {
+ if (ws.readyState !== WebSocket.OPEN) return
+ try { ws.send(JSON.stringify({ t: 'down', connId: msg.connId, frame: msg.frame })) } catch { /* ignore */ }
+ // `machine_revoked` used to be pushed and nothing more, leaving the socket open and the machine
+ // still serving if the client ignored it — an old CLI, a dropped frame. Close it ourselves right
+ // after the send so revocation does not depend on the client cooperating. Same shape as
+ // onBillingSuspended below; the close must happen HERE rather than in MachineService because the
+ // socket may live on another backend instance, reachable only through the Redis fan-out.
+ if ((msg.frame as { type?: string } | undefined)?.type === 'machine_revoked') {
+ try { ws.close(4004, 'machine revoked') } catch { /* ignore */ }
+ }
+ },
+ onBillingSuspended: () => {
+ // Close the live machine session WITHOUT revoking its saved token: the adapter's normal retry
+ // loop then receives HTTP 402 until billing is restored, and reconnects by itself afterwards.
+ try { ws.close(4003, 'subscription required') } catch { /* ignore */ }
+ },
+ onHeartbeat: () => {
+ if (computerId) void claimMachineOwner(machineId, computerId, PRESENCE_TTL_SEC) // renew the one-computer claim
+ // Same tick renews the app-state key, so it shares presence's TTL and can never outlive it.
+ if (appState) void setMachineAppState(machineId, appState.engine, appState.state, PRESENCE_TTL_SEC)
+ },
+ })
+ const terminalDownUnsub = await subscribeTerminalDown(machineId, (packet) => {
+ if (ws.readyState !== WebSocket.OPEN) return
+ try { ws.send(packet) } catch { /* ignore */ }
+ })
+
+ // Liveness. The previous implementation pinged every 25 s and terminated on a single missed PONG —
+ // and counted pongs only, so an adapter that was actively sending application traffic could still
+ // be killed if one pong went missing. `trackSocketLiveness` counts message/ping/pong against a time
+ // deadline instead, which is the same fix already applied to the hub's own sockets.
+ const releaseLiveness = trackSocketLiveness(ws)
+
+ onMessage = (raw: RawData, isBinary: boolean): void => {
+ if (isBinary) {
+ const hop = decodeTerminalHop(new Uint8Array(raw as Buffer))
+ if (!hop || hop.direction !== TerminalHopDirection.up
+ || (hop.kind !== TerminalBinaryKind.output && hop.kind !== TerminalBinaryKind.keyframe
+ && hop.kind !== TerminalBinaryKind.sync)
+ || !terminalRate.allow(
+ hop.kind === TerminalBinaryKind.output
+ ? 'terminal_output'
+ : hop.kind === TerminalBinaryKind.keyframe ? 'terminal_keyframe' : 'terminal_sync',
+ hop.clientFrame.length,
+ )) return
+ void publishTerminalUp(machineId, Buffer.from(raw as Buffer))
+ return
+ }
+ let env: AdapterFrame
+ try { env = JSON.parse(raw.toString()) as AdapterFrame } catch { return }
+ if (env.t === 'ping') {
+ role.touch() // refreshes presence and renews the machine claim
+ return
+ }
+ if (env.t === 'up' && env.frame) {
+ const terminalType = env.frame.type as string | undefined
+ if (typeof terminalType === 'string' && terminalType.startsWith('terminal_')) {
+ if (!TERMINAL_UP_TYPES.has(terminalType)) return
+ const bytes = terminalFrameBytes(env.frame)
+ if (!env.targetConnId || bytes > TERMINAL_ENVELOPE_MAX_BYTES
+ || !isEncryptedTerminalFrame(env.frame) || !terminalRate.allow(terminalType, bytes)) return
+ void publishUp(machineId, {
+ webEligible: true,
+ commanderEligible: false,
+ targetConnId: env.targetConnId,
+ targetKind: 'web',
+ frame: env.frame,
+ })
+ return
+ }
+ if (typeof terminalType === 'string' && terminalType.startsWith('p2p_')) {
+ const bytes = p2pFrameBytes(env.frame)
+ if (!P2P_UP_TYPES.has(terminalType) || !env.targetConnId
+ || !terminalP2pPolicy(userId, machineId).enabled
+ || bytes > P2P_SIGNAL_MAX_BYTES || !isEncryptedP2pFrame(env.frame)
+ || !p2pSignalRate.allow(bytes)) return
+ void publishUp(machineId, {
+ webEligible: true,
+ commanderEligible: false,
+ targetConnId: env.targetConnId,
+ targetKind: 'web',
+ frame: env.frame,
+ })
+ return
+ }
+ // Desktop-app presence. Handled in full here and NEVER falls through to the generic publish:
+ // the eligibility flags are forced false locally rather than trusted from the frame, so no
+ // adapter can fan an unknown frame type out to web clients or devices. Validated against a
+ // closed vocabulary so an arbitrary string can never reach the enum the firmware parses.
+ // Unchanged values are suppressed (the heartbeat keeps the TTL alive), which caps a chatty
+ // adapter at the heartbeat rate.
+ const app = env.frame as { type?: string; payload?: { engine?: unknown; state?: unknown } }
+ if (app.type === 'machine_app_status') {
+ const engine = typeof app.payload?.engine === 'string' ? app.payload.engine : ''
+ const state = typeof app.payload?.state === 'string' ? app.payload.state : ''
+ if (!APP_ENGINES.has(engine) || !APP_STATES.has(state)) return
+ if (appState?.engine === engine && appState.state === state) return
+ appState = { engine, state }
+ void setMachineAppState(machineId, engine, state, PRESENCE_TTL_SEC)
+ void publishUp(machineId, {
+ webEligible: false,
+ commanderEligible: false,
+ frame: { type: 'machine_app_status', payload: { engine, state } } as unknown as Frame,
+ })
+ return
+ }
+ // Hub tap (mirrors managerWs): keep `machine_agents` in sync from the adapter's agent
+ // lifecycle frames. Needed so the device voice path's agent-ownership check
+ // (deviceWs: `machineAgent.findFirst`) recognizes remote tmux sessions.
+ const f = env.frame as { type?: string; payload?: { agent?: unknown; agentId?: unknown; machineId?: unknown } }
+ if (f.type === 'agent_synced') {
+ void recordCreatedAgent(machineId, f.payload?.agent as { id?: unknown; name?: unknown } | undefined)
+ } else if (f.type === 'agent_deleted' && typeof f.payload?.agentId === 'string') {
+ // Every producer sends `agentId` (machine-adapter cli.ts, machine-node websocket.ts/agents.ts).
+ // Reading `machineId` here meant no deletion was EVER recorded, so machine_agents grew a row per
+ // agent forever — and that table is what the plan cap counts.
+ void recordDeletedAgent(machineId, f.payload.agentId)
+ }
+ if (env.userEligible) {
+ void publishUserDeviceE2eePair(userId, machineId, env.frame).catch((err) => {
+ logger.warn('adapter user-level e2ee pair publish failed', { machineId, userId, error: String(err) })
+ })
+ if (env.webEligible === false && env.commanderEligible !== true && !env.targetConnId) return
+ }
+ // No originPid: the hub's Redis loopback must deliver to this instance's own web clients too
+ // (there's no manager-ws local fast-path on this route).
+ void publishUp(machineId, {
+ webEligible: env.webEligible !== false, // default true (plain event/RPC frames)
+ commanderEligible: env.commanderEligible === true, // devices get only opted-in frames
+ ...(env.targetConnId ? { targetConnId: env.targetConnId } : {}), // E2EE per-client push
+ frame: env.frame,
+ })
+ }
+ }
+ // Drain whatever arrived while the role was being attached, in the order it was sent.
+ for (const [raw, isBinary] of preHandlerQueue) onMessage(raw, isBinary)
+ preHandlerQueue.length = 0
+
+ const cleanup = (): void => {
+ releaseLiveness()
+ terminalDownUnsub()
+ // Only the CURRENT owner tears the role down — a superseded socket must not mark the fresh
+ // connection offline. A superseded socket still releases its own liveness tracking above.
+ if (owners.get(machineId) === ws) {
+ owners.delete(machineId)
+ void role.detach()
+ if (computerId) void releaseMachineOwner(machineId, computerId) // free the claim (compare-and-delete)
+ // Drop the app claim with the socket. role.detach() already publishes node_status{online:false},
+ // and every row builder omits the app keys when offline, so the device converges on that frame;
+ // this delete is what stops a reconnect from briefly re-reading the dead value.
+ void clearMachineAppState(machineId)
+ logger.info('adapter disconnected', { machineId })
+ }
+ }
+ ws.on('close', cleanup)
+ ws.on('error', cleanup)
+}
+
+async function publishUserDeviceE2eePair(userId: string, machineId: string, frame: Frame): Promise<void> {
+ const type = frame.type as string | undefined
+ if (type !== 'device_e2ee_pair_pending' && type !== 'device_e2ee_pair_cleared') return
+ const p = (frame.payload ?? {}) as Record<string, unknown>
+ const pairId = typeof p.pairId === 'string' ? p.pairId : ''
+ if (!pairId) return
+
+ const machine = await prisma.machine.findUnique({
+ where: { machineId },
+ select: { name: true },
+ })
+ const base = {
+ machineId,
+ machineName: machine?.name ?? null,
+ pairId,
+ computerFingerprint: typeof p.computerFingerprint === 'string' ? p.computerFingerprint : null,
+ }
+
+ if (type === 'device_e2ee_pair_pending') {
+ await publishDeviceE2eePair(userId, {
+ kind: 'pending',
+ ...base,
+ label: typeof p.label === 'string' ? p.label : 'Device',
+ expiresAt: typeof p.expiresAt === 'number' ? p.expiresAt : Date.now() + 60_000,
+ })
+ return
+ }
+
+ const result = p.result === 'paired' || p.result === 'failed' || p.result === 'cancelled' ? p.result : 'failed'
+ await publishDeviceE2eePair(userId, { kind: 'cleared', ...base, result })
+}
diff --git a/backend/src/lib/agentTracker.ts b/backend/src/lib/agentTracker.ts
new file mode 100644
index 000000000..3535d255b
--- /dev/null
+++ b/backend/src/lib/agentTracker.ts
@@ -0,0 +1,46 @@
+import { prisma } from './prisma.js'
+import { storedAutonomousEnvironment } from './autonomousEnvironment.js'
+
+/**
+ * Per-machine agent tracking (`machine_agents`) for plan caps. The source of truth for agent
+ * CONTENT is the agent-node's SQLite; the central layer only keeps a count. Maintained by the backend
+ * hub tap on the node's `agent_synced` / `agent_deleted` up-frames (see managerWs.ts) — this
+ * replaced the old data-plane proxy-response tap when chat moved onto the hub WS.
+ */
+
+/**
+ * The agent's current project count + its plan's max. Count comes from `machine_agents`; the cap is
+ * resolved machineId → agent_bindings.planId → subscription_plans.maxAgents (default plan when no
+ * planId; floor of 1 when unresolved).
+ */
+export async function agentLimit(machineId: string): Promise<{ count: number; max: number }> {
+ const [count, bindingRow] = await Promise.all([
+ prisma.machineAgent.count({ where: { machineId: machineId } }),
+ prisma.machine.findUnique({ where: { machineId: machineId } }),
+ ])
+ const binding = bindingRow && !bindingRow.deletedAt ? bindingRow : null // soft-deleted = absent
+ const plan = binding?.planId
+ ? await prisma.subscriptionPlan.findUnique({ where: { id: binding.planId } })
+ : await prisma.subscriptionPlan.findFirst({
+ where: { autonomousEnv: storedAutonomousEnvironment(binding?.autonomousEnv), isDefault: true },
+ })
+ return { count, max: plan?.maxAgents ?? 1 }
+}
+
+/** Upsert a `machine_agents` row from an agent object (hub tap on `agent_synced`). Best-effort. */
+export async function recordCreatedAgent(machineId: string, agent: { id?: unknown; name?: unknown } | null | undefined): Promise<void> {
+ const agentId = typeof agent?.id === 'string' ? agent.id : undefined
+ if (!agentId) return
+ const name = typeof agent?.name === 'string' ? agent.name : null
+ await prisma.machineAgent.upsert({
+ where: { machineId_agentId: { machineId, agentId } },
+ create: { machineId, agentId, name },
+ update: { name },
+ })
+}
+
+/** Remove a `machine_agents` row (hub tap on `agent_deleted`). */
+export async function recordDeletedAgent(machineId: string, agentId: string): Promise<void> {
+ if (!agentId) return
+ await prisma.machineAgent.deleteMany({ where: { machineId, agentId } })
+}
diff --git a/backend/src/lib/analyticsIngest.ts b/backend/src/lib/analyticsIngest.ts
new file mode 100644
index 000000000..4b1b1acac
--- /dev/null
+++ b/backend/src/lib/analyticsIngest.ts
@@ -0,0 +1,232 @@
+/**
+ * Harness Analytics ingest — the write path for `POST /api/analytics/report`.
+ *
+ * Design: docs/design/harness-analytics.md ("Upload contract").
+ *
+ * Four gates run before anything is stored, in this order, because each one can make the next
+ * meaningless:
+ *
+ * 1. epoch — a collector holding records from before a deletion must not resurrect them.
+ * 2. consent — nothing is stored until the owner has seen the field list.
+ * 3. clock — a machine whose clock is years off would otherwise own every chart.
+ * 4. LWW — each record key has exactly ONE writer, so `generatedAt` ordering is sufficient
+ * and no client-chosen revision is accepted (a hostile one could pin a record).
+ */
+import { Prisma } from '@prisma/client'
+import { prisma } from './prisma.js'
+import {
+ CLOCK_SKEW_TOLERANCE_MS,
+ RETENTION_DAYS,
+ utcDayStart,
+ type AnalyticsReportRequest,
+ type AnalyticsReportResponse,
+ type ConsentState,
+ type DailyReportPayload,
+ type Engine,
+} from '../types/analytics.js'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+export interface MachineIdentity {
+ machineId: string
+ userId: string
+ /**
+ * The machine's authMode, read from its own record.
+ *
+ * `mode` is a dimension of every bucket, and the client's opinion about it is ignored: the backend
+ * already knows what kind of machine this is, and a collector that mislabelled itself would split
+ * one machine's history across two dimensions that can never be reconciled.
+ */
+ mode: string
+}
+
+export class AnalyticsEpochError extends Error {
+ constructor(readonly currentEpoch: number) {
+ super('Report carries a stale analytics epoch')
+ this.name = 'AnalyticsEpochError'
+ }
+}
+
+interface StateRow {
+ consent: string
+ epoch: number
+}
+
+/**
+ * Read the machine's collector state, creating it on first contact.
+ *
+ * A new row is created already switched ON: collection is the default, and the owner turns it off
+ * rather than turning it on. The row's existence is also what tells the dashboard this machine runs
+ * a collector at all.
+ */
+export async function loadMachineState({ machineId, userId }: MachineIdentity): Promise<StateRow> {
+ const existing = await prisma.analyticsMachineState.findUnique({ where: { machineId } })
+ if (existing) return { consent: existing.consent, epoch: existing.epoch }
+ const created = await prisma.analyticsMachineState.upsert({
+ where: { machineId },
+ create: { machineId, userId, engineCoverage: [] },
+ update: {},
+ })
+ return { consent: created.consent, epoch: created.epoch }
+}
+
+/** A day is storable when its date sits inside the retention window and is not in the future. */
+export function dayIsInWindow(dayUtc: Date, now: Date): boolean {
+ const today = utcDayStart(now).getTime()
+ const day = dayUtc.getTime()
+ if (Number.isNaN(day)) return false
+ // One day of slack ahead: a collector on a machine that is a few hours ahead of the server may
+ // legitimately have already opened tomorrow's record.
+ if (day > today + DAY_MS) return false
+ return day >= today - RETENTION_DAYS * DAY_MS
+}
+
+/**
+ * Store one day's records if they are newer than what is already there.
+ *
+ * `updateMany` with a `generatedAt: { lt }` guard is the atomic half of last-write-wins: it touches
+ * the row only when this report is genuinely newer. A zero count means either "no row yet" or "the
+ * stored row is newer", and `create` distinguishes them — a unique-constraint violation is the
+ * second case and is silently correct.
+ */
+async function writeDay(
+ identity: MachineIdentity,
+ day: DailyReportPayload,
+ dayUtc: Date,
+ generatedAt: Date,
+ schemaVersion: number,
+): Promise<void> {
+ const { machineId, userId } = identity
+ const md = day.machineDay
+ const machineData = {
+ wallClockActiveMs: BigInt(Math.max(0, Math.round(md.wallClockActiveMs))),
+ activeAgents: Math.max(0, Math.round(md.activeAgents)),
+ uptimeMs: BigInt(Math.max(0, Math.round(md.uptimeMs))),
+ reported: md.reported !== false,
+ generatedAt,
+ }
+ const touched = await prisma.analyticsDailyMachine.updateMany({
+ where: { userId, machineId, dayUtc, generatedAt: { lt: generatedAt } },
+ data: machineData,
+ })
+ if (touched.count === 0) {
+ await prisma.analyticsDailyMachine
+ .create({ data: { userId, machineId, dayUtc, ...machineData } })
+ .catch(swallowUniqueViolation)
+ }
+
+ for (const bucket of day.buckets) {
+ const key = {
+ userId,
+ machineId,
+ dayUtc,
+ engine: bucket.engine,
+ // Server-derived, not client-chosen: see MachineIdentity.mode.
+ mode: identity.mode,
+ origin: bucket.origin,
+ schemaVersion,
+ }
+ const data = {
+ instructions: nonNegative(bucket.instructions),
+ turnsStarted: nonNegative(bucket.turnsStarted),
+ turnsCompleted: nonNegative(bucket.turnsCompleted),
+ turnsFailed: nonNegative(bucket.turnsFailed),
+ turnsCancelled: nonNegative(bucket.turnsCancelled),
+ turnsInputNeeded: nonNegative(bucket.turnsInputNeeded),
+ agentRuntimeMs: BigInt(nonNegative(bucket.agentRuntimeMs)),
+ generatedAt,
+ }
+ const updated = await prisma.analyticsDailyBucket.updateMany({
+ where: { ...key, generatedAt: { lt: generatedAt } },
+ data,
+ })
+ if (updated.count === 0) {
+ await prisma.analyticsDailyBucket.create({ data: { ...key, ...data } }).catch(swallowUniqueViolation)
+ }
+ }
+}
+
+function nonNegative(value: number): number {
+ return Number.isFinite(value) ? Math.max(0, Math.round(value)) : 0
+}
+
+/** A unique-constraint violation here means a newer record already won the race. That is the goal. */
+function swallowUniqueViolation(err: unknown): void {
+ if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === 'P2002') return
+ throw err
+}
+
+/**
+ * Apply one report.
+ *
+ * Returns what the collector needs to act on: the authoritative consent state and epoch. That
+ * response IS the control channel — a headless CLI has no other way to learn it should stop.
+ */
+export async function ingestReport(
+ identity: MachineIdentity,
+ report: AnalyticsReportRequest,
+ now: Date = new Date(),
+): Promise<AnalyticsReportResponse> {
+ const state = await loadMachineState(identity)
+
+ // 1. Epoch. Refuse outright so the collector drops its queue instead of retrying forever.
+ if (report.epoch < state.epoch) throw new AnalyticsEpochError(state.epoch)
+
+ const base = {
+ consent: state.consent as ConsentState,
+ epoch: state.epoch,
+ serverTime: now.toISOString(),
+ }
+
+ // 2. Consent. Nothing is stored, and nothing about the collector is recorded either.
+ if (state.consent !== 'on') return { ...base, accepted: 0, quarantined: 0 }
+
+ // 3. Clock. A report stamped far from the server's clock is quarantined whole: its day keys cannot
+ // be trusted either. The skew is still recorded, so Coverage can explain the silence.
+ const generatedAt = new Date(report.generatedAt)
+ const skewMs = Number.isNaN(generatedAt.getTime())
+ ? null
+ : now.getTime() - generatedAt.getTime()
+ const clockUsable = skewMs !== null && Math.abs(skewMs) <= CLOCK_SKEW_TOLERANCE_MS
+
+ let accepted = 0
+ let quarantined = 0
+
+ if (!clockUsable) {
+ quarantined = report.days.length
+ } else {
+ for (const day of report.days) {
+ const dayUtc = utcDayStart(day.dayUtc)
+ if (!dayIsInWindow(dayUtc, now)) {
+ quarantined++
+ continue
+ }
+ // 4. Last-write-wins by generatedAt, per record.
+ await writeDay(identity, day, dayUtc, generatedAt, report.schemaVersion)
+ accepted++
+ }
+ }
+
+ await prisma.analyticsMachineState.update({
+ where: { machineId: identity.machineId },
+ data: {
+ collectorVersion: report.collector.version,
+ engineCoverage: dedupeEngines(report.collector.engineCoverage),
+ enginesPresent: dedupeEngines(report.collector.enginesPresent ?? []),
+ lastReportAt: now,
+ clockSkewMs: skewMs === null ? null : clampSkewForStorage(skewMs),
+ },
+ })
+
+ return { ...base, accepted, quarantined }
+}
+
+function dedupeEngines(engines: Engine[]): string[] {
+ return [...new Set(engines)]
+}
+
+/** Keep the stored skew inside Int32 so a nonsense clock cannot overflow the column. */
+function clampSkewForStorage(skewMs: number): number {
+ const limit = 2_147_483_647
+ return Math.max(-limit, Math.min(limit, Math.round(skewMs)))
+}
diff --git a/backend/src/lib/analyticsQuery.ts b/backend/src/lib/analyticsQuery.ts
new file mode 100644
index 000000000..25dcb7001
--- /dev/null
+++ b/backend/src/lib/analyticsQuery.ts
@@ -0,0 +1,425 @@
+/**
+ * Harness Analytics read path — account rollups for the dashboard.
+ *
+ * Design: docs/design/harness-analytics.md ("Metric contract", "Backend data model").
+ *
+ * The rollup rules are not stylistic; breaking them produces numbers that are wrong in a way nobody
+ * notices:
+ *
+ * - `AnalyticsDailyBucket` may be aggregated freely (additive counters).
+ * - `AnalyticsDailyMachine.activeAgents` may be summed ACROSS MACHINES only — an agent belongs to
+ * exactly one machine, so there is nothing to de-duplicate, but it is never split by engine.
+ * - `AnalyticsDailyMachine.wallClockActiveMs` is summed across machines only under the label
+ * "sum across machines". It is a union within a machine and cannot become a union across them.
+ */
+import { prisma } from './prisma.js'
+import { machineAlive } from './prisma.js'
+import {
+ MIN_DAYS_FOR_BASELINE,
+ MIN_SAMPLE_FOR_RATE,
+ utcDayKey,
+ utcDayStart,
+ type Engine,
+} from '../types/analytics.js'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+export type MachineDataState = 'active' | 'idle' | 'no_data'
+
+export interface AnalyticsOverview {
+ range: { fromDay: string; toDay: string; days: number }
+ totals: {
+ instructions: number
+ turnsStarted: number
+ turnsCompleted: number
+ turnsFailed: number
+ turnsCancelled: number
+ turnsInputNeeded: number
+ terminalTurns: number
+ agentRuntimeMs: number
+ /** Sum across machines — overlapping work on two machines is counted twice, by design. */
+ wallClockActiveMs: number
+ activeAgents: number
+ activeDays: number
+ /** Suppressed (null) below MIN_SAMPLE_FOR_RATE terminal turns rather than shown over a tiny n. */
+ completionRate: number | null
+ unproductiveShare: number | null
+ }
+ byEngine: EngineTotals[]
+ daily: DailyPoint[]
+ machines: MachineSummary[]
+ coverage: {
+ knownMachines: number
+ reportingMachines: number
+ staleMachines: number
+ lastReportAt: string | null
+ }
+ health: {
+ ready: boolean
+ baselineDays: number
+ requiredDays: number
+ latestDay: string | null
+ latestRate: number | null
+ baselineRate: number | null
+ }
+ notInstrumented: { machineId: string; machineName: string | null; engines: string[] }[]
+}
+
+export interface EngineTotals {
+ engine: string
+ instructions: number
+ turnsCompleted: number
+ turnsFailed: number
+ turnsCancelled: number
+ turnsInputNeeded: number
+ agentRuntimeMs: number
+}
+
+export interface DailyPoint {
+ day: string
+ instructions: number
+ turnsCompleted: number
+ turnsFailed: number
+ turnsCancelled: number
+ turnsInputNeeded: number
+ byEngine: Record<string, number>
+ /** Per-machine reporting state for this day. This is what keeps "idle" from reading as "no data". */
+ machineStates: Record<string, MachineDataState>
+}
+
+export interface MachineSummary {
+ machineId: string
+ /**
+ * RAW `Machine.name`, not a display string.
+ *
+ * The display name is `machineLabel()` in apps/web/src/lib/machineLabel.ts, which every other
+ * surface already uses. Deriving a second one here is how the Analytics table ended up showing
+ * `cf755d85` while the Machines list showed `machine-cf755d85` for the same machine.
+ */
+ name: string | null
+ mode: string
+ billed: boolean
+ wallClockActiveMs: number
+ uptimeMs: number
+ /** null when uptime is not meaningful (remote computers and providers are not containers). */
+ utilization: number | null
+ reportedDays: number
+ missingDays: number
+ lastReportAt: string | null
+ collectorVersion: string | null
+ consent: string
+ clockSkewMs: number | null
+}
+
+/** A machine is considered stale when it has not reported for longer than this. */
+export const STALE_AFTER_MS = 24 * 60 * 60 * 1000
+
+/** Modes whose machines are containers we bill for, so utilization is a meaningful number. */
+const UTILIZATION_MODES = new Set(['managed', 'self'])
+
+export interface OverviewOptions {
+ userId: string
+ days: number
+ machineId?: string
+ now?: Date
+}
+
+export async function analyticsOverview(opts: OverviewOptions): Promise<AnalyticsOverview> {
+ const now = opts.now ?? new Date()
+ const toDay = utcDayStart(now)
+ const fromDay = new Date(toDay.getTime() - (opts.days - 1) * DAY_MS)
+
+ const machineFilter = opts.machineId ? { machineId: opts.machineId } : {}
+
+ const [machineRows, buckets, machineDays, states] = await Promise.all([
+ prisma.machine.findMany({
+ where: { userId: opts.userId, ...machineFilter, ...machineAlive },
+ select: { machineId: true, name: true, hostname: true, authMode: true, billingStatus: true },
+ }),
+ prisma.analyticsDailyBucket.findMany({
+ where: { userId: opts.userId, ...machineFilter, dayUtc: { gte: fromDay, lte: toDay } },
+ }),
+ prisma.analyticsDailyMachine.findMany({
+ where: { userId: opts.userId, ...machineFilter, dayUtc: { gte: fromDay, lte: toDay } },
+ }),
+ prisma.analyticsMachineState.findMany({ where: { userId: opts.userId, ...machineFilter } }),
+ ])
+
+ const stateByMachine = new Map(states.map((s) => [s.machineId, s]))
+ const rawNameOf = (machineId: string): string | null =>
+ machineRows.find((m) => m.machineId === machineId)?.name ?? null
+
+ // ---- additive rollup -------------------------------------------------------------------------
+ const totals = {
+ instructions: 0,
+ turnsStarted: 0,
+ turnsCompleted: 0,
+ turnsFailed: 0,
+ turnsCancelled: 0,
+ turnsInputNeeded: 0,
+ agentRuntimeMs: 0,
+ }
+ const engineTotals = new Map<string, EngineTotals>()
+ const dayPoints = new Map<string, DailyPoint>()
+
+ for (const b of buckets) {
+ totals.instructions += b.instructions
+ totals.turnsStarted += b.turnsStarted
+ totals.turnsCompleted += b.turnsCompleted
+ totals.turnsFailed += b.turnsFailed
+ totals.turnsCancelled += b.turnsCancelled
+ totals.turnsInputNeeded += b.turnsInputNeeded
+ totals.agentRuntimeMs += Number(b.agentRuntimeMs)
+
+ const et = engineTotals.get(b.engine) ?? {
+ engine: b.engine,
+ instructions: 0,
+ turnsCompleted: 0,
+ turnsFailed: 0,
+ turnsCancelled: 0,
+ turnsInputNeeded: 0,
+ agentRuntimeMs: 0,
+ }
+ et.instructions += b.instructions
+ et.turnsCompleted += b.turnsCompleted
+ et.turnsFailed += b.turnsFailed
+ et.turnsCancelled += b.turnsCancelled
+ et.turnsInputNeeded += b.turnsInputNeeded
+ et.agentRuntimeMs += Number(b.agentRuntimeMs)
+ engineTotals.set(b.engine, et)
+
+ const key = utcDayKey(b.dayUtc)
+ const point = dayPoints.get(key) ?? emptyPoint(key)
+ point.instructions += b.instructions
+ point.turnsCompleted += b.turnsCompleted
+ point.turnsFailed += b.turnsFailed
+ point.turnsCancelled += b.turnsCancelled
+ point.turnsInputNeeded += b.turnsInputNeeded
+ point.byEngine[b.engine] = (point.byEngine[b.engine] ?? 0) + b.instructions
+ dayPoints.set(key, point)
+ }
+
+ // ---- non-additive rollup ---------------------------------------------------------------------
+ // These come ONLY from AnalyticsDailyMachine, at (machine, day) granularity. They are never
+ // derived from the engine-split buckets, because a union and a distinct count do not decompose.
+ let wallClockActiveMs = 0
+ let activeAgents = 0
+ const activeDays = new Set<string>()
+ const perMachine = new Map<string, { wallClockActiveMs: number; uptimeMs: number; reportedDays: number }>()
+
+ for (const md of machineDays) {
+ const key = utcDayKey(md.dayUtc)
+ wallClockActiveMs += Number(md.wallClockActiveMs)
+ activeAgents += md.activeAgents
+ if (Number(md.wallClockActiveMs) > 0) activeDays.add(key)
+
+ const agg = perMachine.get(md.machineId) ?? { wallClockActiveMs: 0, uptimeMs: 0, reportedDays: 0 }
+ agg.wallClockActiveMs += Number(md.wallClockActiveMs)
+ agg.uptimeMs += Number(md.uptimeMs)
+ if (md.reported) agg.reportedDays++
+ perMachine.set(md.machineId, agg)
+
+ const point = dayPoints.get(key) ?? emptyPoint(key)
+ point.machineStates[md.machineId] = Number(md.wallClockActiveMs) > 0 ? 'active' : 'idle'
+ dayPoints.set(key, point)
+ }
+
+ // Every (machine, day) with no record at all is explicitly `no_data`, never an implicit zero.
+ const allDayKeys: string[] = []
+ for (let i = 0; i < opts.days; i++) {
+ allDayKeys.push(utcDayKey(new Date(fromDay.getTime() + i * DAY_MS)))
+ }
+ for (const key of allDayKeys) {
+ const point = dayPoints.get(key) ?? emptyPoint(key)
+ for (const m of machineRows) {
+ if (!point.machineStates[m.machineId]) point.machineStates[m.machineId] = 'no_data'
+ }
+ dayPoints.set(key, point)
+ }
+
+ const terminalTurns =
+ totals.turnsCompleted + totals.turnsFailed + totals.turnsCancelled + totals.turnsInputNeeded
+ const enoughSample = terminalTurns >= MIN_SAMPLE_FOR_RATE
+
+ const machines: MachineSummary[] = machineRows.map((m) => {
+ const agg = perMachine.get(m.machineId) ?? { wallClockActiveMs: 0, uptimeMs: 0, reportedDays: 0 }
+ const state = stateByMachine.get(m.machineId)
+ const mode = m.authMode ?? 'managed'
+ const utilization =
+ UTILIZATION_MODES.has(mode) && agg.uptimeMs > 0
+ ? agg.wallClockActiveMs / agg.uptimeMs
+ : null
+ return {
+ machineId: m.machineId,
+ name: m.name ?? null,
+ mode,
+ billed: m.billingStatus === 'active',
+ wallClockActiveMs: agg.wallClockActiveMs,
+ uptimeMs: agg.uptimeMs,
+ utilization,
+ reportedDays: agg.reportedDays,
+ missingDays: opts.days - agg.reportedDays,
+ lastReportAt: state?.lastReportAt?.toISOString() ?? null,
+ collectorVersion: state?.collectorVersion ?? null,
+ consent: state?.consent ?? 'unacknowledged',
+ clockSkewMs: state?.clockSkewMs ?? null,
+ }
+ })
+
+ const lastReportTimes = states
+ .map((s) => s.lastReportAt?.getTime())
+ .filter((t): t is number => typeof t === 'number')
+ const lastReportAt = lastReportTimes.length ? new Date(Math.max(...lastReportTimes)) : null
+
+ const daily = allDayKeys.map((k) => dayPoints.get(k) ?? emptyPoint(k))
+
+ return {
+ range: { fromDay: utcDayKey(fromDay), toDay: utcDayKey(toDay), days: opts.days },
+ totals: {
+ ...totals,
+ terminalTurns,
+ wallClockActiveMs,
+ activeAgents,
+ activeDays: activeDays.size,
+ completionRate: enoughSample ? totals.turnsCompleted / terminalTurns : null,
+ unproductiveShare: enoughSample
+ ? (totals.turnsFailed + totals.turnsCancelled) / terminalTurns
+ : null,
+ },
+ byEngine: [...engineTotals.values()].sort((a, b) => b.instructions - a.instructions),
+ daily,
+ machines,
+ coverage: {
+ knownMachines: machineRows.length,
+ reportingMachines: machines.filter((m) => m.reportedDays > 0).length,
+ staleMachines: machines.filter(
+ (m) => m.lastReportAt !== null && now.getTime() - Date.parse(m.lastReportAt) > STALE_AFTER_MS,
+ ).length,
+ lastReportAt: lastReportAt?.toISOString() ?? null,
+ },
+ health: healthOf(daily, machineDays.length, now),
+ notInstrumented: states
+ .map((s) => ({
+ machineId: s.machineId,
+ machineName: rawNameOf(s.machineId),
+ engines: (s.enginesPresent ?? []).filter((e) => !(s.engineCoverage ?? []).includes(e)),
+ }))
+ .filter((row) => row.engines.length > 0),
+ }
+}
+
+function emptyPoint(day: string): DailyPoint {
+ return {
+ day,
+ instructions: 0,
+ turnsCompleted: 0,
+ turnsFailed: 0,
+ turnsCancelled: 0,
+ turnsInputNeeded: 0,
+ byEngine: {},
+ machineStates: {},
+ }
+}
+
+/**
+ * Compare the most recent day against the account's OWN trailing baseline.
+ *
+ * Never against other accounts, and never against an engine ranking. Until there is enough history
+ * the panel reports that it is still building rather than inventing a comparison.
+ */
+function healthOf(
+ daily: DailyPoint[],
+ recordCount: number,
+ now: Date,
+): AnalyticsOverview['health'] {
+ const withTurns = daily.filter(
+ (d) => d.turnsCompleted + d.turnsFailed + d.turnsCancelled + d.turnsInputNeeded > 0,
+ )
+ const baselineDays = withTurns.length
+ if (recordCount === 0 || baselineDays < MIN_DAYS_FOR_BASELINE) {
+ return {
+ ready: false,
+ baselineDays,
+ requiredDays: MIN_DAYS_FOR_BASELINE,
+ latestDay: null,
+ latestRate: null,
+ baselineRate: null,
+ }
+ }
+ const latest = withTurns[withTurns.length - 1]
+ const prior = withTurns.slice(0, -1)
+ const rate = (d: DailyPoint): number => {
+ const terminal = d.turnsCompleted + d.turnsFailed + d.turnsCancelled + d.turnsInputNeeded
+ return terminal === 0 ? 0 : d.turnsCompleted / terminal
+ }
+ const priorTerminal = prior.reduce(
+ (acc, d) => acc + d.turnsCompleted + d.turnsFailed + d.turnsCancelled + d.turnsInputNeeded,
+ 0,
+ )
+ const priorCompleted = prior.reduce((acc, d) => acc + d.turnsCompleted, 0)
+ void now
+ return {
+ ready: true,
+ baselineDays,
+ requiredDays: MIN_DAYS_FOR_BASELINE,
+ latestDay: latest.day,
+ latestRate: rate(latest),
+ baselineRate: priorTerminal === 0 ? null : priorCompleted / priorTerminal,
+ }
+}
+
+/** Engines the UI may render as series, ranked by volume. */
+export function topEngines(byEngine: EngineTotals[], limit = 5): Engine[] {
+ return byEngine.slice(0, limit).map((e) => e.engine as Engine)
+}
+
+
+export interface ConsentMachineRow {
+ machineId: string
+ name: string | null
+ hostname: string | null
+ authMode: string | null
+}
+
+export interface ConsentStateRow {
+ machineId: string
+ consent: string
+ collectorVersion: string | null
+ lastReportAt: Date | null
+ engineCoverage: string[]
+ enginesPresent: string[]
+}
+
+/**
+ * Build the consent view.
+ *
+ * A machine only HAS a collector once it has reported at least once — `loadMachineState` creates its
+ * row on first contact — so a machine with NO row has never run one. Keeping those two apart is what
+ * stops the dashboard telling an owner their machines are collecting when the build on them has no
+ * collector in it.
+ */
+export function buildConsentView(machines: ConsentMachineRow[], states: ConsentStateRow[]) {
+ const byId = new Map(states.map((s) => [s.machineId, s]))
+
+ return {
+ machines: machines.map((m) => {
+ const s = byId.get(m.machineId)
+ return {
+ machineId: m.machineId,
+ // Raw, like everywhere else here: the web formats it with machineLabel().
+ name: m.name ?? null,
+ mode: m.authMode ?? 'managed',
+ // Collection is on by default; a machine with no row simply has not reported yet.
+ consent: s?.consent ?? 'on',
+ /** False = no collector has ever reported from this machine. */
+ hasReported: s !== undefined,
+ collectorVersion: s?.collectorVersion ?? null,
+ lastReportAt: s?.lastReportAt?.toISOString() ?? null,
+ engineCoverage: s?.engineCoverage ?? [],
+ enginesPresent: s?.enginesPresent ?? [],
+ }
+ }),
+ /** True when no machine on the account has ever run a collector. */
+ noCollectorYet: states.length === 0,
+ }
+}
diff --git a/backend/src/lib/appTargetCache.ts b/backend/src/lib/appTargetCache.ts
new file mode 100644
index 000000000..f668119b9
--- /dev/null
+++ b/backend/src/lib/appTargetCache.ts
@@ -0,0 +1,52 @@
+import { env } from '../config/env.js'
+
+/**
+ * Per-process TTL + LRU cache: subdomain → owning machineId. The public app-proxy resolves the routing
+ * target (the agent whose manager socket tunnels the request) on every request; the mapping is stable
+ * so cache it and skip the 1-doc Mongo lookup for hot subdomains. TTL bounds staleness; an explicit
+ * evict clears only the instance that handled a delete.
+ *
+ * Negative entries (machineId === null) are cached too, with a SHORTER TTL, so scans / misconfigured DNS
+ * hitting nonexistent subdomains don't hit Mongo on every request (the positive TTL would be too long to
+ * pin a not-yet-registered subdomain as missing).
+ */
+
+interface Entry {
+ machineId: string | null // null = negative (known-missing)
+ expiresAt: number
+}
+
+const MAX_ENTRIES = 50_000
+const cache = new Map<string, Entry>()
+
+/**
+ * Tri-state lookup:
+ * string → cached machineId (positive hit)
+ * null → cached negative (known-missing → answer NO_APP without a DB read)
+ * undefined → not cached (caller must query the DB)
+ */
+export function getCachedAppAgent(subdomain: string): string | null | undefined {
+ const e = cache.get(subdomain)
+ if (!e) return undefined
+ if (Date.now() > e.expiresAt) {
+ cache.delete(subdomain)
+ return undefined
+ }
+ cache.delete(subdomain)
+ cache.set(subdomain, e)
+ return e.machineId
+}
+
+/** Cache a resolved machineId (positive, long TTL) or a not-found result (negative, short TTL). */
+export function setCachedAppAgent(subdomain: string, machineId: string | null): void {
+ if (cache.size >= MAX_ENTRIES && !cache.has(subdomain)) {
+ const oldest = cache.keys().next().value
+ if (oldest !== undefined) cache.delete(oldest)
+ }
+ const ttl = machineId === null ? env.AGENT_TARGET_NEG_CACHE_TTL_MS : env.AGENT_TARGET_CACHE_TTL_MS
+ cache.set(subdomain, { machineId, expiresAt: Date.now() + ttl })
+}
+
+export function evictCachedAppTarget(subdomain: string): void {
+ cache.delete(subdomain)
+}
diff --git a/backend/src/lib/appTunnel.ts b/backend/src/lib/appTunnel.ts
new file mode 100644
index 000000000..a6160d788
--- /dev/null
+++ b/backend/src/lib/appTunnel.ts
@@ -0,0 +1,388 @@
+/**
+ * Backend side of the app-proxy tunnel — the PUBLIC terminator of `<sub>.<APP_DOMAIN_SUFFIX>`.
+ *
+ * A public HTTP request / WS upgrade becomes a per-request STREAM (`streamId`) tunnelled to the owning
+ * agent's manager over the manager socket (no manager address needed). Two delivery modes, chosen per
+ * stream at open time by whether THIS backend instance already holds the agent's app-pool manager socket:
+ *
+ * LOCAL (co-located): write frames straight to the local manager socket + register a local up-handler.
+ * Zero Redis, native socket backpressure. (registry.appSocketFor(machineId))
+ * REDIS (cross-instance): publishAppDown(machineId, …) → B_m; subscribe appup:{streamId} for the reply.
+ *
+ * Down (client→app): app_req | app_body | app_ws_* | app_abort. Up (app→client): app_res | app_res_body
+ * | app_ws_* | app_abort. Bodies ride chunked base64 frames so uploads/downloads/SSE stream.
+ */
+import type { IncomingMessage, ServerResponse } from 'http'
+import type { Duplex } from 'stream'
+import { randomUUID } from 'crypto'
+import { WebSocketServer, WebSocket } from 'ws'
+import { subscribeAppUp, publishAppDown } from './bus.js'
+import * as registry from './registry.js'
+import { env } from '../config/env.js'
+import type {
+ AppResEnvelope,
+ AppBodyEnvelope,
+ AppWsMsgEnvelope,
+ AppWsCloseEnvelope,
+ AppAbortEnvelope,
+ AppDownFrame,
+} from './tunnel.js'
+import { logger } from '../utils/logger.js'
+
+// No app_res within this window → the node app is unreachable / never answered → 502.
+const RESPONSE_TIMEOUT_MS = 30_000
+
+type UpFrame = AppResEnvelope | AppBodyEnvelope | AppWsMsgEnvelope | AppWsCloseEnvelope | AppAbortEnvelope
+
+const wss = new WebSocketServer({ noServer: true })
+
+// streamId → local up-handler, for streams whose manager socket is on THIS instance (LOCAL mode). The
+// manager-ws message loop calls deliverAppUpLocal before falling back to publishAppUp.
+const localStreams = new Map<string, (frame: UpFrame) => void>()
+
+const MAX_REQUEST_BYTES = env.APP_PROXY_MAX_REQUEST_BYTES
+const MAX_RESPONSE_BYTES = env.APP_PROXY_MAX_RESPONSE_BYTES
+const MAX_WS_FRAME_BYTES = env.APP_PROXY_MAX_WS_FRAME_BYTES
+const IDLE_TIMEOUT_MS = env.APP_PROXY_IDLE_TIMEOUT_MS
+const MAX_STREAMS_PER_SUBDOMAIN = env.APP_PROXY_MAX_STREAMS_PER_SUBDOMAIN
+
+const activeBySubdomain = new Map<string, number>()
+const HTTP_STRIP_HEADERS = new Set([
+ 'connection',
+ 'keep-alive',
+ 'proxy-authenticate',
+ 'proxy-authorization',
+ 'te',
+ 'trailer',
+ 'transfer-encoding',
+ 'upgrade',
+])
+
+function acquireSubdomainSlot(subdomain: string): (() => void) | null {
+ const n = activeBySubdomain.get(subdomain) ?? 0
+ if (n >= MAX_STREAMS_PER_SUBDOMAIN) return null
+ activeBySubdomain.set(subdomain, n + 1)
+ return () => {
+ const cur = activeBySubdomain.get(subdomain) ?? 0
+ if (cur <= 1) activeBySubdomain.delete(subdomain)
+ else activeBySubdomain.set(subdomain, cur - 1)
+ }
+}
+
+function sanitizeHttpHeaders(req: IncomingMessage): Record<string, string | string[] | undefined> {
+ const headers: Record<string, string | string[] | undefined> = {}
+ for (const [k, v] of Object.entries(req.headers)) {
+ if (!HTTP_STRIP_HEADERS.has(k.toLowerCase())) headers[k] = v
+ }
+ const remote = req.socket.remoteAddress
+ const priorFor = req.headers['x-forwarded-for']
+ headers['x-forwarded-for'] = [Array.isArray(priorFor) ? priorFor.join(', ') : priorFor, remote].filter(Boolean).join(', ')
+ headers['x-forwarded-host'] = req.headers.host
+ headers['x-forwarded-proto'] = Array.isArray(req.headers['x-forwarded-proto'])
+ ? req.headers['x-forwarded-proto'][0]
+ : (req.headers['x-forwarded-proto'] ?? 'https')
+ if (remote) headers['x-real-ip'] = remote
+ return headers
+}
+
+function sendWsJson(ws: WebSocket, frame: AppDownFrame): Promise<void> {
+ if (ws.readyState !== WebSocket.OPEN) return Promise.reject(new Error('manager app socket is closed'))
+ const payload = JSON.stringify(frame)
+ return new Promise((resolve, reject) => {
+ try {
+ ws.send(payload, (err) => (err ? reject(err) : resolve()))
+ } catch (err) {
+ reject(err)
+ }
+ })
+}
+
+/** Deliver an app→client up-frame to a co-located stream. Returns true if a local handler consumed it. */
+export function deliverAppUpLocal(streamId: string, frame: UpFrame): boolean {
+ const h = localStreams.get(streamId)
+ if (!h) return false
+ h(frame)
+ return true
+}
+
+/** Pick the down-channel for a new stream: local manager socket if held here, else Redis. */
+function openChannel(machineId: string, streamId: string, onUp: (f: UpFrame) => void): {
+ sendDown: (f: AppDownFrame) => Promise<void>
+ teardown: () => void
+} | Promise<{ sendDown: (f: AppDownFrame) => Promise<void>; teardown: () => void }> {
+ const local = registry.appSocketFor(machineId)
+ if (local) {
+ localStreams.set(streamId, onUp)
+ return {
+ sendDown: (f) => sendWsJson(local, f),
+ teardown: () => { localStreams.delete(streamId) },
+ }
+ }
+ return subscribeAppUp(streamId, onUp as (m: unknown) => void).then((unsub) => ({
+ sendDown: async (f: AppDownFrame) => {
+ const subscribers = await publishAppDown(machineId, f)
+ if (subscribers === 0) throw new Error('manager app socket is unreachable')
+ },
+ teardown: () => unsub(),
+ }))
+}
+
+/** Tunnel one public HTTP request to the agent's app over the manager socket. */
+export async function tunnelHttp(
+ req: IncomingMessage,
+ res: ServerResponse,
+ machineId: string,
+ subdomain: string,
+): Promise<void> {
+ const streamId = randomUUID()
+ const releaseSlot = acquireSubdomainSlot(subdomain)
+ if (!releaseSlot) {
+ res.writeHead(429, { 'content-type': 'text/plain' })
+ res.end('Too many active app streams')
+ logger.warn('app-tunnel stream rejected: concurrency limit', { machineId, subdomain })
+ return
+ }
+ const release = releaseSlot
+ let settled = false
+ let headWritten = false
+ let requestBytes = 0
+ let responseBytes = 0
+ let bodyChain: Promise<void> = Promise.resolve()
+ let writeChain: Promise<void> = Promise.resolve()
+
+ const responseTimer = setTimeout(() => {
+ fail(502, 'App did not respond', 'response_timeout')
+ }, RESPONSE_TIMEOUT_MS)
+ let idleTimer: NodeJS.Timeout | null = null
+ const refreshIdle = (): void => {
+ if (idleTimer) clearTimeout(idleTimer)
+ idleTimer = setTimeout(() => fail(504, 'App stream timed out', 'idle_timeout'), IDLE_TIMEOUT_MS)
+ }
+
+ logger.info('app-tunnel http open', { machineId, subdomain, streamId, method: req.method, url: req.url })
+
+ const writeBody = (buf: Buffer): Promise<void> => new Promise((resolve) => {
+ if (settled || res.destroyed) { resolve(); return }
+ try {
+ if (res.write(buf)) { resolve(); return }
+ res.once('drain', resolve)
+ } catch {
+ resolve()
+ }
+ })
+
+ const onUp = (f: UpFrame): void => {
+ if (f.streamId !== streamId) return
+ refreshIdle()
+ switch (f.t) {
+ case 'app_res':
+ headWritten = true
+ clearTimeout(responseTimer)
+ try { res.writeHead(f.status, f.headers as Record<string, string | string[]>) } catch { /* ignore */ }
+ break
+ case 'app_res_body':
+ if (f.chunk) {
+ const buf = Buffer.from(f.chunk, 'base64')
+ responseBytes += buf.length
+ if (MAX_RESPONSE_BYTES > 0 && responseBytes > MAX_RESPONSE_BYTES) {
+ fail(502, 'App response too large', 'response_too_large')
+ return
+ }
+ writeChain = writeChain.then(() => writeBody(buf))
+ }
+ if (f.end) {
+ void writeChain.finally(() => {
+ if (!settled) { try { res.end() } catch { /* ignore */ }; cleanup('complete') }
+ })
+ }
+ break
+ case 'app_abort':
+ fail(headWritten ? 502 : 502, 'App error', f.reason ?? 'app_abort')
+ break
+ default:
+ break
+ }
+ }
+
+ let channel: Awaited<ReturnType<typeof openChannel>>
+ try {
+ channel = await openChannel(machineId, streamId, onUp)
+ } catch (err) {
+ clearTimeout(responseTimer)
+ if (idleTimer) clearTimeout(idleTimer)
+ release()
+ logger.warn('app-tunnel http channel open failed', { machineId, subdomain, streamId, error: err instanceof Error ? err.message : String(err) })
+ if (!res.headersSent) {
+ try { res.writeHead(502, { 'content-type': 'text/plain' }); res.end('App unavailable') } catch { /* ignore */ }
+ }
+ return
+ }
+ const { sendDown, teardown } = channel
+
+ function cleanup(reason: string): void {
+ if (settled) return
+ settled = true
+ clearTimeout(responseTimer)
+ if (idleTimer) clearTimeout(idleTimer)
+ teardown()
+ release()
+ logger.info('app-tunnel http close', { machineId, subdomain, streamId, reason, requestBytes, responseBytes })
+ }
+
+ function fail(status: number, message: string, reason: string): void {
+ if (settled) return
+ void sendDown({ t: 'app_abort', streamId, reason }).catch(() => { /* ignore */ })
+ if (!res.headersSent) {
+ try { res.writeHead(status, { 'content-type': 'text/plain' }); res.end(message) } catch { /* ignore */ }
+ } else {
+ try { res.end() } catch { /* ignore */ }
+ }
+ cleanup(reason)
+ }
+
+ // Open the stream, then pipe the request body as chunked frames.
+ try {
+ await sendDown({ t: 'app_req', streamId, subdomain, method: req.method ?? 'GET', url: req.url ?? '/', headers: sanitizeHttpHeaders(req) })
+ refreshIdle()
+ } catch (err) {
+ logger.warn('app-tunnel http open failed', { machineId, subdomain, streamId, error: err instanceof Error ? err.message : String(err) })
+ fail(502, 'App unavailable', 'open_failed')
+ return
+ }
+ req.on('data', (chunk: Buffer) => {
+ if (settled) return
+ requestBytes += chunk.length
+ if (MAX_REQUEST_BYTES > 0 && requestBytes > MAX_REQUEST_BYTES) {
+ req.pause()
+ fail(413, 'Request body too large', 'request_too_large')
+ return
+ }
+ req.pause()
+ bodyChain = bodyChain
+ .then(() => sendDown({ t: 'app_body', streamId, chunk: Buffer.from(chunk).toString('base64') }))
+ .catch((err) => {
+ logger.warn('app-tunnel request body send failed', { machineId, subdomain, streamId, error: err instanceof Error ? err.message : String(err) })
+ fail(502, 'App unavailable', 'send_failed')
+ })
+ .finally(() => { if (!settled) req.resume() })
+ })
+ req.on('end', () => {
+ bodyChain = bodyChain
+ .then(() => (settled ? undefined : sendDown({ t: 'app_body', streamId, end: true })))
+ .catch((err) => {
+ logger.warn('app-tunnel request end send failed', { machineId, subdomain, streamId, error: err instanceof Error ? err.message : String(err) })
+ fail(502, 'App unavailable', 'send_failed')
+ })
+ })
+ const abort = (): void => {
+ if (!settled) sendDown({ t: 'app_abort', streamId, reason: 'client closed' })
+ .catch(() => { /* ignore */ })
+ .finally(() => cleanup('client_closed'))
+ }
+ req.on('error', abort)
+ res.on('close', () => { if (!settled) abort() })
+}
+
+/** Tunnel one public WebSocket upgrade to the agent's app over the manager socket. */
+export async function tunnelWs(
+ req: IncomingMessage,
+ socket: Duplex,
+ head: Buffer,
+ machineId: string,
+ subdomain: string,
+): Promise<void> {
+ const streamId = randomUUID()
+ const releaseSlot = acquireSubdomainSlot(subdomain)
+ if (!releaseSlot) {
+ try { socket.write('HTTP/1.1 429 Too Many Requests\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
+ socket.destroy()
+ logger.warn('app-tunnel ws rejected: concurrency limit', { machineId, subdomain })
+ return
+ }
+ const release = releaseSlot
+ const ws = await new Promise<WebSocket>((resolve) => {
+ wss.handleUpgrade(req, socket, head, (client) => resolve(client))
+ })
+
+ let closed = false
+ let inBytes = 0
+ let outBytes = 0
+ let idleTimer: NodeJS.Timeout | null = null
+ const refreshIdle = (): void => {
+ if (idleTimer) clearTimeout(idleTimer)
+ idleTimer = setTimeout(() => close(1001), IDLE_TIMEOUT_MS)
+ }
+ const close = (code?: number): void => {
+ if (closed) return
+ closed = true
+ if (idleTimer) clearTimeout(idleTimer)
+ try { ws.close(code) } catch { /* ignore */ }
+ void sendDown({ t: 'app_ws_close', streamId, code })
+ .catch(() => { /* ignore */ })
+ teardown()
+ release()
+ logger.info('app-tunnel ws close', { machineId, subdomain, streamId, code, inBytes, outBytes })
+ }
+
+ const onUp = (f: UpFrame): void => {
+ if (f.streamId !== streamId) return
+ refreshIdle()
+ if (f.t === 'app_ws_msg') {
+ const data = Buffer.from(f.data, 'base64')
+ outBytes += data.length
+ if (MAX_WS_FRAME_BYTES > 0 && data.length > MAX_WS_FRAME_BYTES) { close(1009); return }
+ try { ws.send(data, { binary: f.binary }) } catch { /* ignore */ }
+ } else if (f.t === 'app_ws_close') {
+ closed = true
+ if (idleTimer) clearTimeout(idleTimer)
+ try { ws.close(f.code) } catch { /* ignore */ }
+ teardown()
+ release()
+ logger.info('app-tunnel ws close', { machineId, subdomain, streamId, code: f.code, inBytes, outBytes })
+ } else if (f.t === 'app_abort') {
+ closed = true
+ if (idleTimer) clearTimeout(idleTimer)
+ try { ws.close(1011) } catch { /* ignore */ }
+ teardown()
+ release()
+ logger.warn('app-tunnel ws abort', { machineId, subdomain, streamId, reason: f.reason, inBytes, outBytes })
+ }
+ }
+
+ let channel: Awaited<ReturnType<typeof openChannel>>
+ try {
+ channel = await openChannel(machineId, streamId, onUp)
+ } catch (err) {
+ closed = true
+ if (idleTimer) clearTimeout(idleTimer)
+ release()
+ logger.warn('app-tunnel ws channel open failed', { machineId, subdomain, streamId, error: err instanceof Error ? err.message : String(err) })
+ try { ws.close(1011) } catch { /* ignore */ }
+ return
+ }
+ const { sendDown, teardown } = channel
+
+ logger.info('app-tunnel ws open', { machineId, subdomain, streamId, url: req.url })
+ try {
+ await sendDown({ t: 'app_ws_open', streamId, subdomain, url: req.url ?? '/', headers: sanitizeHttpHeaders(req) })
+ refreshIdle()
+ } catch (err) {
+ logger.warn('app-tunnel ws open failed', { machineId, subdomain, streamId, error: err instanceof Error ? err.message : String(err) })
+ close(1011)
+ return
+ }
+
+ ws.on('message', (data: Buffer, isBinary: boolean) => {
+ if (closed) return
+ inBytes += data.length
+ refreshIdle()
+ if (MAX_WS_FRAME_BYTES > 0 && data.length > MAX_WS_FRAME_BYTES) { close(1009); return }
+ void sendDown({ t: 'app_ws_msg', streamId, data: Buffer.from(data).toString('base64'), binary: isBinary })
+ .catch((err) => {
+ logger.warn('app-tunnel ws msg send failed', { machineId, subdomain, streamId, error: err instanceof Error ? err.message : String(err) })
+ close(1011)
+ })
+ })
+ ws.on('close', (code: number) => close(code))
+ ws.on('error', (err: Error) => { logger.warn('app-tunnel client ws error', { subdomain, error: err.message }); close(1011) })
+}
diff --git a/backend/src/lib/autonomousBff.test.ts b/backend/src/lib/autonomousBff.test.ts
new file mode 100644
index 000000000..d273eee9b
--- /dev/null
+++ b/backend/src/lib/autonomousBff.test.ts
@@ -0,0 +1,246 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('../config/env.js', () => ({
+ env: {
+ AUTONOMOUS_BFF_URL: 'https://bff.example',
+ STAGING_AUTONOMOUS_BFF_URL: 'https://bff.staging.example',
+ AUTONOMOUS_CHECKOUT_ORIGIN: 'https://autonomous.ai',
+ STAGING_AUTONOMOUS_CHECKOUT_ORIGIN: 'https://staging.autonomousdev.xyz',
+ AUTONOMOUS_BFF_TIMEOUT_MS: 1000,
+ HARNESS_CAMPAIGN_CODE: 'ai-harness-device',
+ HARNESS_DEVICE_TYPE: 15,
+ HARNESS_DEVICE_TIMEZONE_DEFAULT: 'Asia/Saigon',
+ },
+}))
+
+import {
+ completeCheckout,
+ createCampaignDevice,
+ createCheckout,
+ fetchCampaignPlans,
+ fireCampaignDevice,
+ getCampaignDevice,
+ listCampaignSubscriptions,
+} from './autonomousBff.js'
+
+afterEach(() => vi.unstubAllGlobals())
+
+describe('Autonomous campaign catalog', () => {
+ it('reads billable ids and prices from each monthly frequencies entry', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1,
+ data: {
+ plans: [
+ { name: 'free', title: 'Free', daily_token_limit: 10, frequencies: [{ plan_id: 37, amount: 0, frequency: 'month', currency: 'USD' }] },
+ { name: 'pro', title: 'Pro', daily_token_limit: 50, frequencies: [{ plan_id: 38, amount: 20, frequency: 'month', currency: 'USD' }] },
+ { name: 'max', title: 'Max', daily_token_limit: 0, frequencies: [{ plan_id: 39, amount: 100, frequency: 'month', currency: 'USD' }] },
+ { name: 'remote', title: 'Remote', frequencies: [{ plan_id: 40, amount: 10, frequency: 'month', currency: 'USD' }] },
+ ],
+ },
+ }), { status: 200 })))
+
+ const plans = await fetchCampaignPlans('prod')
+ expect(plans.map((p) => [p.code, p.id, p.amount])).toEqual([
+ ['free', 37, 0], ['pro', 38, 20], ['max', 39, 100], ['remote', 40, 10],
+ ])
+ expect(plans.every((p) => p.currency === 'USD')).toBe(true)
+ expect(plans[1].metadata.daily_token_limit).toBe(50)
+ })
+
+ it('recognises the Provider tier without colliding with Pro', async () => {
+ // Mirrors the live catalog (verified 2026-08-04): five tiers, Provider at $10/month.
+ // `provider` and `pro` are one substring apart, so this pins the word boundary that keeps them
+ // distinct — get it wrong and the Pro plan silently becomes the Provider plan.
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1,
+ data: {
+ plans: [
+ { name: 'free', title: 'Free', frequencies: [{ plan_id: 41, amount: 0, frequency: 'month', currency: 'USD' }] },
+ { name: 'pro', title: 'Pro', frequencies: [{ plan_id: 42, amount: 20, frequency: 'month', currency: 'USD' }] },
+ { name: 'max', title: 'Max', frequencies: [{ plan_id: 43, amount: 100, frequency: 'month', currency: 'USD' }] },
+ { name: 'remote', title: 'Remote', frequencies: [{ plan_id: 44, amount: 10, frequency: 'month', currency: 'USD' }] },
+ { name: 'provider', title: 'Provider', frequencies: [{ plan_id: 45, amount: 10, frequency: 'month', currency: 'USD' }] },
+ ],
+ },
+ }), { status: 200 })))
+
+ const plans = await fetchCampaignPlans('prod')
+ expect(plans.map((p) => [p.code, p.id, p.amount])).toEqual([
+ ['free', 41, 0], ['pro', 42, 20], ['max', 43, 100], ['remote', 44, 10], ['provider', 45, 10],
+ ])
+ // The decisive assertion: Pro kept its own id rather than being overwritten by Provider.
+ expect(plans.find((p) => p.code === 'pro')?.id).toBe(42)
+ })
+
+ it('drops a tier it does not recognise rather than failing the whole catalog', async () => {
+ // A tier appearing upstream before this backend knows about it must be INVISIBLE, not fatal:
+ // the catalog is only usable if every known tier is present, so a stray row that inflated the
+ // map would take Free/Pro/Max/Remote down with it.
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1,
+ data: {
+ plans: [
+ { name: 'free', title: 'Free', frequencies: [{ plan_id: 1, amount: 0, frequency: 'month', currency: 'USD' }] },
+ { name: 'enterprise', title: 'Enterprise', frequencies: [{ plan_id: 99, amount: 500, frequency: 'month', currency: 'USD' }] },
+ ],
+ },
+ }), { status: 200 })))
+
+ const plans = await fetchCampaignPlans('prod')
+ expect(plans.map((p) => p.code)).toEqual(['free'])
+ })
+
+ it('does not treat an empty subscription placeholder as a paid subscription', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1,
+ data: { device_id: 'device-1', subscription: {} },
+ }), { status: 200 })))
+
+ await expect(getCampaignDevice('prod', 'token', 'device-1')).resolves.toEqual({
+ deviceId: 'device-1',
+ llmApiKey: undefined,
+ })
+ })
+
+ it('parses daily token usage without exposing unrelated device fields', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1,
+ data: { device_id: 'device-1', daily_usage: 230_946, monthly_usage: 900_000 },
+ }), { status: 200 })))
+
+ await expect(getCampaignDevice('prod', 'token', 'device-1')).resolves.toEqual({
+ deviceId: 'device-1',
+ llmApiKey: undefined,
+ dailyUsage: 230_946,
+ })
+ })
+
+ it('parses the nested subscription-list response used as the authoritative payment fallback', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1,
+ data: {
+ data: [{
+ id: 'sub-1', campaign_code: 'ai-harness-device', reference_id: 'device-1',
+ plan_id: 38, plan_name: 'Pro', status: 2,
+ }],
+ total: 1,
+ },
+ }), { status: 200 })))
+
+ await expect(listCampaignSubscriptions('prod', 'token', 'ai-harness-device', 'device-1')).resolves.toEqual([{
+ id: 'sub-1', campaignCode: 'ai-harness-device', referenceId: 'device-1', planId: 38, planName: 'Pro',
+ status: 2, startAt: undefined, endAt: undefined, cancelledAt: undefined,
+ }])
+ })
+
+ it('parses protobuf timestamp objects returned on campaign subscriptions', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1,
+ data: {
+ device_id: 'device-1',
+ subscription: {
+ id: 'sub-1',
+ start_date: { seconds: 1_784_703_323, nanos: 261_000_000 },
+ end_date: { seconds: 1_787_381_732 },
+ cancelled_date: {},
+ },
+ },
+ }), { status: 200 })))
+
+ const device = await getCampaignDevice('prod', 'token', 'device-1')
+ expect(device.subscription?.startAt?.toISOString()).toBe('2026-07-22T06:55:23.261Z')
+ expect(device.subscription?.endAt?.toISOString()).toBe('2026-08-22T06:55:32.000Z')
+ expect(device.subscription?.cancelledAt).toBeUndefined()
+ })
+
+ it('forwards the callback reference code when completing hosted checkout', async () => {
+ const fetchMock = vi.fn(async (_input: string | URL | Request, init?: RequestInit) => {
+ expect(init?.headers).toMatchObject({ Origin: 'https://autonomous.ai' })
+ expect(JSON.parse(String(init?.body))).toMatchObject({
+ session_id: 'checkout-1', reference: '2607000093', reference_id: 'device-1', plan_id: 38,
+ })
+ return new Response(JSON.stringify({ status: 1, data: {} }), { status: 200 })
+ })
+ vi.stubGlobal('fetch', fetchMock)
+
+ await completeCheckout('prod', 'token', 'checkout-1', {
+ email: '[email protected]', planId: 38, referenceId: 'device-1', referenceCode: '2607000093',
+ successUrl: 'http://localhost:3000/machine-checkout?checkout=success',
+ failureUrl: 'http://localhost:3000/machine-checkout?checkout=cancelled',
+ origin: 'http://localhost:3000',
+ })
+ })
+
+ it('forwards only the caller token and configured campaign device metadata to staging BFF', async () => {
+ const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+ const url = String(input)
+ const body = init?.body ? JSON.parse(String(init.body)) as Record<string, unknown> : {}
+ expect(init?.headers).toMatchObject({ Authorization: 'Bearer sso-access', location: 'en-US' })
+ expect(url).toContain('https://bff.staging.example')
+ if (url.endsWith('/api/v1/stand-to-earn/device')) {
+ expect(body).toEqual({ device_type: 15, timezone: 'Asia/Saigon' })
+ return new Response(JSON.stringify({ status: 1, data: { device_id: 'device-1' } }), { status: 200 })
+ }
+ expect(url).toContain('/api/v1/checkout/stripe/checkout-session')
+ expect(init?.headers).toMatchObject({ Origin: 'https://staging.autonomousdev.xyz' })
+ expect(body).toMatchObject({
+ email: '[email protected]', campaign_code: 'ai-harness-device', plan_id: 38,
+ reference_id: 'device-1', use_stripe_hosted_subscription: true,
+ })
+ return new Response(JSON.stringify({
+ status: 1, data: { checkout_session_id: 'checkout-1', redirect_url: 'https://checkout.example/1' },
+ }), { status: 200 })
+ })
+ vi.stubGlobal('fetch', fetchMock)
+
+ await expect(createCampaignDevice('stag', 'sso-access')).resolves.toBe('device-1')
+ await expect(createCheckout('stag', 'sso-access', {
+ email: '[email protected]', planId: 38, referenceId: 'device-1',
+ successUrl: 'http://localhost:3000/machine-checkout?checkout=success',
+ failureUrl: 'http://localhost:3000/machine-checkout?checkout=cancelled',
+ origin: 'http://localhost:3000',
+ })).resolves.toEqual({ sessionId: 'checkout-1', redirectUrl: 'https://checkout.example/1' })
+ })
+
+ it('does not classify a billing-upstream auth rejection as an expired Machine SSO session', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(
+ JSON.stringify({ status: 0, message: 'Unauthorized' }),
+ { status: 401 },
+ )))
+
+ await expect(createCheckout('stag', 'sso-access', {
+ email: '[email protected]', planId: 38, referenceId: 'device-1',
+ successUrl: 'https://harness.autonomous.ai/machine-checkout?checkout=success',
+ failureUrl: 'https://harness.autonomous.ai/machine-checkout?checkout=cancelled',
+ origin: 'https://harness.autonomous.ai',
+ })).rejects.toMatchObject({
+ statusCode: 502,
+ code: 'BILLING_UPSTREAM_UNAUTHORIZED',
+ })
+ })
+
+ it('parses a session-only response so the service can enforce plan-specific redirect rules', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({
+ status: 1, data: { checkout_session_id: 'checkout-1' },
+ }), { status: 200 })))
+
+ await expect(createCheckout('prod', 'sso-access', {
+ email: '[email protected]', planId: 37, referenceId: 'device-1',
+ successUrl: 'http://localhost:3000/machine-checkout?checkout=success',
+ failureUrl: 'http://localhost:3000/machine-checkout?checkout=cancelled',
+ origin: 'http://localhost:3000',
+ })).resolves.toEqual({ sessionId: 'checkout-1' })
+ })
+
+ it('uses fire-intern rather than raw device delete for billing-safe cleanup', async () => {
+ const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+ expect(String(input)).toContain('/api/v1/stand-to-earn/device/device-1/fire-intern')
+ expect(init?.method).toBe('POST')
+ return new Response(JSON.stringify({ status: 1, data: {} }), { status: 200 })
+ })
+ vi.stubGlobal('fetch', fetchMock)
+
+ await expect(fireCampaignDevice('prod', 'sso-access', 'device-1')).resolves.toBeUndefined()
+ expect(fetchMock).toHaveBeenCalledOnce()
+ })
+})
diff --git a/backend/src/lib/autonomousBff.ts b/backend/src/lib/autonomousBff.ts
new file mode 100644
index 000000000..df604c3a7
--- /dev/null
+++ b/backend/src/lib/autonomousBff.ts
@@ -0,0 +1,350 @@
+import { env } from '../config/env.js'
+import { AppError } from '../errors/index.js'
+import { autonomousEnvironmentConfig, type AutonomousEnvironment } from './autonomousEnvironment.js'
+
+type JsonObject = Record<string, unknown>
+
+export interface CampaignPlan {
+ id: number
+ code: 'free' | 'pro' | 'max' | 'remote' | 'provider'
+ name: string
+ amount: number
+ currency: string
+ metadata: JsonObject
+}
+
+export interface CheckoutInput {
+ email: string
+ planId: number
+ referenceId: string
+ referenceCode?: string
+ successUrl: string
+ failureUrl: string
+ origin: string
+}
+
+export interface CheckoutResult {
+ sessionId?: string
+ redirectUrl?: string
+}
+
+export interface CampaignDevice {
+ deviceId: string
+ subscription?: CampaignSubscription
+ llmApiKey?: string
+ dailyUsage?: number
+}
+
+export interface CampaignSubscription {
+ id?: string
+ campaignCode?: string
+ referenceId?: string
+ planId?: number
+ planName?: string
+ status?: number
+ startAt?: Date
+ endAt?: Date
+ cancelledAt?: Date
+}
+
+function object(value: unknown): JsonObject | undefined {
+ return value != null && typeof value === 'object' && !Array.isArray(value) ? value as JsonObject : undefined
+}
+
+function unwrap(raw: unknown): unknown {
+ const body = object(raw)
+ if (!body) return raw
+ if (body.status !== undefined && body.status !== 1 && body.status !== true && body.status !== 'success') {
+ const message = typeof body.message === 'string' ? body.message : 'Autonomous BFF rejected the request'
+ throw new AppError(message, 503, 'BILLING_UPSTREAM_ERROR')
+ }
+ return body.data ?? body.result ?? raw
+}
+
+function firstObject(raw: unknown): JsonObject {
+ const value = unwrap(raw)
+ if (Array.isArray(value)) return object(value[0]) ?? {}
+ const obj = object(value) ?? {}
+ for (const key of ['device', 'checkout', 'checkout_session', 'subscription_plan']) {
+ const nested = object(obj[key])
+ if (nested) return nested
+ }
+ return obj
+}
+
+function str(obj: JsonObject, ...keys: string[]): string | undefined {
+ for (const key of keys) {
+ const value = obj[key]
+ if (typeof value === 'string' && value.trim()) return value.trim()
+ if (typeof value === 'number' && Number.isFinite(value)) return String(value)
+ }
+}
+
+function num(obj: JsonObject, ...keys: string[]): number | undefined {
+ const value = str(obj, ...keys)
+ if (value === undefined) return undefined
+ const parsed = Number(value)
+ return Number.isFinite(parsed) ? parsed : undefined
+}
+
+function date(obj: JsonObject, ...keys: string[]): Date | undefined {
+ for (const key of keys) {
+ const value = obj[key]
+ const timestamp = object(value)
+ if (timestamp) {
+ // Campaign APIs serialize protobuf timestamps as { seconds, nanos } rather than ISO strings.
+ const seconds = num(timestamp, 'seconds')
+ const nanos = num(timestamp, 'nanos') ?? 0
+ if (seconds !== undefined) {
+ const parsed = new Date(seconds * 1000 + nanos / 1_000_000)
+ if (!Number.isNaN(parsed.getTime())) return parsed
+ }
+ }
+ if (typeof value !== 'string' && typeof value !== 'number') continue
+ const parsed = typeof value === 'number'
+ ? new Date(value < 10_000_000_000 ? value * 1000 : value)
+ : new Date(value)
+ if (!Number.isNaN(parsed.getTime())) return parsed
+ }
+}
+
+export function parseSubscription(subscription: JsonObject): CampaignSubscription {
+ return {
+ id: str(subscription, 'id', '_id', 'subscription_id', 'subscriptionId'),
+ campaignCode: str(subscription, 'campaign_code', 'campaignCode', 'code'),
+ referenceId: str(subscription, 'reference_id', 'referenceId'),
+ planId: num(subscription, 'plan_id', 'planId'),
+ planName: str(subscription, 'plan_name', 'planName', 'name'),
+ status: num(subscription, 'status', 'subscription_status', 'subscriptionStatus'),
+ startAt: date(subscription, 'start_date', 'startDate', 'started_at', 'startedAt'),
+ endAt: date(subscription, 'end_date', 'endDate', 'expires_at', 'expiresAt'),
+ cancelledAt: date(subscription, 'cancelled_date', 'cancelledDate', 'canceled_at', 'cancelled_at'),
+ }
+}
+
+async function request(
+ autonomousEnv: AutonomousEnvironment,
+ path: string,
+ opts: { token?: string; method?: string; body?: unknown; origin?: string } = {},
+): Promise<unknown> {
+ let response: Response
+ try {
+ const environment = autonomousEnvironmentConfig(autonomousEnv)
+ // Autonomous validates Origin separately from success_url/failure_url. A staging account used
+ // from the production Machine UI must still present the staging allowlisted origin upstream, while
+ // Stripe callbacks continue returning to the actual Machine web origin carried in the request body.
+ const upstreamOrigin = opts.origin ? environment.checkoutOrigin : undefined
+ response = await fetch(new URL(path, environment.bffUrl), {
+ method: opts.method ?? 'GET',
+ headers: {
+ Accept: 'application/json',
+ location: 'en-US',
+ ...(opts.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+ ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}),
+ ...(upstreamOrigin ? { Origin: upstreamOrigin } : {}),
+ },
+ ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+ signal: AbortSignal.timeout(env.AUTONOMOUS_BFF_TIMEOUT_MS),
+ })
+ } catch {
+ throw new AppError('Autonomous billing service unavailable', 503, 'BILLING_SERVICE_UNAVAILABLE')
+ }
+ if (response.status === 401 || response.status === 403) {
+ // The app auth middleware has already validated this same token through the profile API. Do not
+ // report an upstream billing authorization failure as the Machine SSO session expiring: the web
+ // would refresh once and then incorrectly log the user out.
+ throw new AppError(
+ 'Autonomous billing service rejected the account session',
+ 502,
+ 'BILLING_UPSTREAM_UNAUTHORIZED',
+ )
+ }
+ if (response.status === 404) {
+ if (opts.method === 'DELETE') return undefined
+ throw new AppError('Campaign device not found', 404, 'BILLING_DEVICE_NOT_FOUND')
+ }
+ if (!response.ok) {
+ throw new AppError('Autonomous billing service unavailable', 503, 'BILLING_SERVICE_UNAVAILABLE')
+ }
+ if (response.status === 204) return undefined
+ try { return await response.json() } catch {
+ throw new AppError('Autonomous billing service returned invalid data', 503, 'BILLING_UPSTREAM_ERROR')
+ }
+}
+
+function planCode(raw: JsonObject): CampaignPlan['code'] | undefined {
+ const haystack = [str(raw, 'code', 'plan_code', 'slug'), str(raw, 'name', 'plan_name', 'title')]
+ .filter(Boolean).join(' ').toLowerCase()
+ // `provider` is tested BEFORE `pro` for readability only — the word boundary in /\bpro\b/ already
+ // prevents "provider" from matching it. An upstream code this function does not recognise is
+ // dropped by the caller, so a new tier appearing upstream is invisible here rather than fatal.
+ if (/\bfree\b/.test(haystack)) return 'free'
+ if (/\bprovider\b/.test(haystack)) return 'provider'
+ if (/\bpro\b/.test(haystack)) return 'pro'
+ if (/\bmax\b/.test(haystack)) return 'max'
+ if (/\bremote\b/.test(haystack)) return 'remote'
+ return undefined
+}
+
+export async function fetchCampaignPlans(autonomousEnv: AutonomousEnvironment): Promise<CampaignPlan[]> {
+ const raw = unwrap(await request(autonomousEnv, `/api/v1/stand-to-earn/device/${encodeURIComponent(env.HARNESS_CAMPAIGN_CODE)}/subscription-plans`))
+ const root = object(raw)
+ const rows = Array.isArray(raw) ? raw : Array.isArray(root?.plans) ? root.plans : Array.isArray(root?.items) ? root.items : []
+ const parsed: CampaignPlan[] = []
+ for (const value of rows) {
+ const p = object(value)
+ if (!p) continue
+ const frequencies = Array.isArray(p.frequencies) ? p.frequencies : []
+ const monthly = frequencies.map(object).find((f) => f?.frequency === 'month') ?? object(frequencies[0])
+ const id = num(monthly ?? p, 'id', 'plan_id')
+ const code = planCode(p)
+ if (!id || !code) continue
+ parsed.push({
+ id,
+ code,
+ name: str(p, 'name', 'plan_name', 'title') ?? code,
+ amount: num(monthly ?? p, 'amount', 'price', 'price_usd') ?? 0,
+ currency: (str(monthly ?? p, 'currency') ?? '').toUpperCase(),
+ metadata: p,
+ })
+ }
+ return parsed
+}
+
+export async function createCampaignDevice(autonomousEnv: AutonomousEnvironment, token: string): Promise<string> {
+ const obj = firstObject(await request(autonomousEnv, '/api/v1/stand-to-earn/device', {
+ token,
+ method: 'POST',
+ body: { device_type: env.HARNESS_DEVICE_TYPE, timezone: env.HARNESS_DEVICE_TIMEZONE_DEFAULT },
+ }))
+ const deviceId = str(obj, 'device_id', 'deviceId', 'id')
+ if (!deviceId) throw new AppError('Autonomous billing service did not return a device id', 503, 'BILLING_UPSTREAM_ERROR')
+ return deviceId
+}
+
+function checkoutBody(input: CheckoutInput): JsonObject {
+ return {
+ email: input.email,
+ campaign_code: env.HARNESS_CAMPAIGN_CODE,
+ plan_id: input.planId,
+ reference_id: input.referenceId,
+ quantity: 1,
+ use_stripe_hosted_subscription: true,
+ success_url: input.successUrl,
+ failure_url: input.failureUrl,
+ }
+}
+
+export async function createCheckout(autonomousEnv: AutonomousEnvironment, token: string, input: CheckoutInput): Promise<CheckoutResult> {
+ const obj = firstObject(await request(autonomousEnv, '/api/v1/checkout/stripe/checkout-session', {
+ token,
+ method: 'POST',
+ origin: input.origin,
+ body: checkoutBody(input),
+ }))
+ const sessionId = str(obj, 'checkout_session_id', 'session_id', 'checkoutSessionId', 'sessionId', 'id')
+ const redirectUrl = str(obj, 'redirect_url', 'checkout_url', 'redirectUrl', 'checkoutUrl', 'url')
+ if (redirectUrl) {
+ try {
+ if (new URL(redirectUrl).protocol !== 'https:') throw new Error('not https')
+ } catch {
+ throw new AppError('Autonomous billing service returned an invalid checkout URL', 503, 'BILLING_UPSTREAM_ERROR')
+ }
+ }
+ return { ...(sessionId ? { sessionId } : {}), ...(redirectUrl ? { redirectUrl } : {}) }
+}
+
+export async function completeCheckout(autonomousEnv: AutonomousEnvironment, token: string, sessionId: string, input: CheckoutInput): Promise<void> {
+ const raw = await request(autonomousEnv, `/api/v1/checkout/stripe/checkout-complete/${encodeURIComponent(sessionId)}`, {
+ token,
+ method: 'POST',
+ origin: input.origin,
+ body: {
+ ...checkoutBody(input),
+ session_id: sessionId,
+ ...(input.referenceCode ? { reference: input.referenceCode } : {}),
+ },
+ })
+ // The BFF can report an application error in a HTTP 200 envelope. Do not silently continue to
+ // device verification when checkout completion itself was rejected.
+ unwrap(raw)
+}
+
+export async function getCampaignDevice(autonomousEnv: AutonomousEnvironment, token: string, deviceId: string): Promise<CampaignDevice> {
+ const obj = firstObject(await request(autonomousEnv, `/api/v1/stand-to-earn/device/${encodeURIComponent(deviceId)}`, { token }))
+ const subscription = object(obj.subscription)
+ const parsedSubscription = subscription ? parseSubscription(subscription) : undefined
+ const hasSubscription = !!parsedSubscription && Object.values(parsedSubscription).some((value) => value !== undefined)
+ const dailyUsage = num(obj, 'daily_usage', 'dailyUsage')
+ return {
+ deviceId: str(obj, 'device_id', 'deviceId', 'id') ?? deviceId,
+ llmApiKey: str(obj, 'llm_api_key', 'llmApiKey'),
+ ...(dailyUsage !== undefined ? { dailyUsage: Math.max(0, dailyUsage) } : {}),
+ ...(hasSubscription ? { subscription: parsedSubscription } : {}),
+ }
+}
+
+export async function listCampaignSubscriptions(
+ autonomousEnv: AutonomousEnvironment,
+ token: string,
+ campaignCode: string,
+ referenceId: string,
+): Promise<CampaignSubscription[]> {
+ const query = new URLSearchParams({ campaign_code: campaignCode })
+ query.append('reference_ids[]', referenceId)
+ const raw = unwrap(await request(autonomousEnv, `/api/v1/me/subscriptions?${query.toString()}`, { token }))
+ const root = object(raw)
+ // Current BFF shape is {status:1,data:{data:[...],total:n}}. Keep the direct array/items aliases
+ // for compatibility with older deployments.
+ const rows = Array.isArray(raw)
+ ? raw
+ : Array.isArray(root?.data)
+ ? root.data
+ : Array.isArray(root?.subscriptions)
+ ? root.subscriptions
+ : Array.isArray(root?.items)
+ ? root.items
+ : []
+ return rows.flatMap((value) => {
+ const subscription = object(value)
+ if (!subscription) return []
+ return [parseSubscription(subscription)]
+ })
+}
+
+export async function cancelCampaignSubscription(autonomousEnv: AutonomousEnvironment, token: string, subscriptionId: string): Promise<void> {
+ const raw = await request(autonomousEnv, `/api/v1/me/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`, {
+ token,
+ method: 'POST',
+ })
+ unwrap(raw)
+}
+
+export async function renewCampaignSubscription(autonomousEnv: AutonomousEnvironment, token: string, subscriptionId: string): Promise<void> {
+ const raw = await request(autonomousEnv, `/api/v1/me/subscriptions/${encodeURIComponent(subscriptionId)}/renew`, {
+ token,
+ method: 'POST',
+ })
+ unwrap(raw)
+}
+
+/** Billing-safe device removal. Unlike raw DELETE, fire-intern also cancels the attached
+ * subscription and releases any provider-side plan allocation before deleting the device. */
+export async function fireCampaignDevice(autonomousEnv: AutonomousEnvironment, token: string, deviceId: string): Promise<void> {
+ let raw: unknown
+ try {
+ raw = await request(autonomousEnv, `/api/v1/stand-to-earn/device/${encodeURIComponent(deviceId)}/fire-intern`, {
+ token,
+ method: 'POST',
+ })
+ } catch (err) {
+ // A prior retry may already have fired the device. With no device left there is nothing that
+ // can renew through this reference, so deletion remains idempotent.
+ if (err instanceof AppError && err.code === 'BILLING_DEVICE_NOT_FOUND') return
+ throw err
+ }
+ try { unwrap(raw) } catch (err) {
+ if (err instanceof AppError && /not found/i.test(err.message)) return
+ throw err
+ }
+}
diff --git a/backend/src/lib/autonomousCampaign.ts b/backend/src/lib/autonomousCampaign.ts
new file mode 100644
index 000000000..4b5667c59
--- /dev/null
+++ b/backend/src/lib/autonomousCampaign.ts
@@ -0,0 +1,135 @@
+import { env } from '../config/env.js'
+import type { AutonomousEnvironment } from './autonomousEnvironment.js'
+import { autonomousEnvironmentConfig } from './autonomousEnvironment.js'
+import { type CampaignSubscription, parseSubscription } from './autonomousBff.js'
+
+type JsonObject = Record<string, unknown>
+
+const PAGE_SIZE = 100
+const MAX_PAGES = 1_000
+export const CAMPAIGN_REFERENCE_BATCH_SIZE = 100
+
+function object(value: unknown): JsonObject | undefined {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+ ? value as JsonObject
+ : undefined
+}
+
+function number(value: unknown): number | undefined {
+ if (typeof value === 'number' && Number.isFinite(value)) return value
+ if (typeof value === 'string' && value.trim()) {
+ const parsed = Number(value)
+ if (Number.isFinite(parsed)) return parsed
+ }
+ return undefined
+}
+
+function pageData(raw: unknown): { rows: unknown[]; total?: number } {
+ const envelope = object(raw)
+ const status = number(envelope?.status)
+ if (status !== undefined && status !== 1) {
+ throw new Error(`Autonomous campaign subscription API rejected the request (status ${status})`)
+ }
+ const data = object(envelope?.data) ?? envelope
+ const rows = Array.isArray(data?.data)
+ ? data.data
+ : Array.isArray(data?.subscriptions)
+ ? data.subscriptions
+ : Array.isArray(data?.items)
+ ? data.items
+ : Array.isArray(raw)
+ ? raw
+ : []
+ return { rows, total: number(data?.total) }
+}
+
+export function hasCampaignSubscriptionApiKey(autonomousEnv: AutonomousEnvironment): boolean {
+ return !!autonomousEnvironmentConfig(autonomousEnv).campaignApiKey
+}
+
+/** A device record as projected by the campaign service — trimmed to what the device flow actually uses.
+ *
+ * The response also carries `fa_channel` / `fd_channel`, and they are deliberately NOT read: the device
+ * relays its own provisioned topics and those are what the bridge connects with, so parsing the record's
+ * copy would only invite someone to start trusting it. Broker credentials are absent from the projection
+ * entirely (as are the lobster api key and device secret). */
+export interface CampaignDevice {
+ id: string
+ /** The Autonomous SSO subject == `User.externalId`. This is what attributes a device to an account. */
+ customerId: string
+ /** Account email from the record's `created_user_id`. Required — see the throw in the parser. */
+ createdUserEmail: string
+ status?: number
+}
+
+function stringField(value: unknown): string {
+ return typeof value === 'string' ? value.trim() : ''
+}
+
+/**
+ * Reads the campaign-wide subscription snapshot with a server credential. This deliberately lives
+ * outside autonomousBff: the BFF client carries a user's bearer token, while this endpoint accepts
+ * only x-api-key and is owned by the singleton worker.
+ */
+export async function listCampaignSubscriptionsByApiKey(
+ autonomousEnv: AutonomousEnvironment,
+ campaignCode: string,
+ referenceIds: readonly string[],
+): Promise<CampaignSubscription[]> {
+ const uniqueReferenceIds = [...new Set(referenceIds.map((value) => value.trim()).filter(Boolean))]
+ if (!uniqueReferenceIds.length) {
+ throw new Error('Autonomous campaign subscription API requires at least one reference id')
+ }
+ if (uniqueReferenceIds.length > CAMPAIGN_REFERENCE_BATCH_SIZE) {
+ throw new Error(
+ `Autonomous campaign subscription API accepts at most ${CAMPAIGN_REFERENCE_BATCH_SIZE} reference ids per request`,
+ )
+ }
+ const environment = autonomousEnvironmentConfig(autonomousEnv)
+ if (!environment.campaignApiKey) {
+ throw new Error(`Autonomous campaign subscription API key is not configured for ${autonomousEnv}`)
+ }
+
+ const subscriptions: CampaignSubscription[] = []
+ for (let page = 1; page <= MAX_PAGES; page++) {
+ const url = new URL('/api/v1/subscriptions/', environment.campaignApiUrl)
+ url.searchParams.set('campaign_code', campaignCode)
+ for (const referenceId of uniqueReferenceIds) url.searchParams.append('reference_ids[]', referenceId)
+ url.searchParams.set('page', String(page))
+ url.searchParams.set('limit', String(PAGE_SIZE))
+
+ let response: Response
+ try {
+ response = await fetch(url, {
+ headers: {
+ Accept: 'application/json',
+ 'x-api-key': environment.campaignApiKey,
+ },
+ signal: AbortSignal.timeout(env.AUTONOMOUS_BFF_TIMEOUT_MS),
+ })
+ } catch {
+ throw new Error(`Autonomous campaign subscription API is unavailable for ${autonomousEnv}`)
+ }
+ if (!response.ok) {
+ throw new Error(`Autonomous campaign subscription API failed for ${autonomousEnv} (HTTP ${response.status})`)
+ }
+
+ let raw: unknown
+ try {
+ raw = await response.json()
+ } catch {
+ throw new Error(`Autonomous campaign subscription API returned invalid data for ${autonomousEnv}`)
+ }
+ const { rows, total } = pageData(raw)
+ for (const value of rows) {
+ const row = object(value)
+ if (!row) continue
+ const parsed = parseSubscription(row)
+ if (parsed.id) subscriptions.push(parsed)
+ }
+ if (rows.length === 0 || rows.length < PAGE_SIZE || (total !== undefined && subscriptions.length >= total)) {
+ return subscriptions
+ }
+ }
+ throw new Error(`Autonomous campaign subscription API exceeded ${MAX_PAGES} pages for ${autonomousEnv}`)
+}
diff --git a/backend/src/lib/autonomousEnvironment.ts b/backend/src/lib/autonomousEnvironment.ts
new file mode 100644
index 000000000..ba26dc078
--- /dev/null
+++ b/backend/src/lib/autonomousEnvironment.ts
@@ -0,0 +1,63 @@
+import { env } from '../config/env.js'
+
+export const autonomousEnvironments = ['prod', 'stag'] as const
+export type AutonomousEnvironment = typeof autonomousEnvironments[number]
+
+export function isAutonomousEnvironment(value: unknown): value is AutonomousEnvironment {
+ return value === 'prod' || value === 'stag'
+}
+
+/** Missing values are production for backward-compatible clients; malformed explicit values fail. */
+export function parseAutonomousEnvironment(
+ value: unknown,
+ fallback: AutonomousEnvironment = 'prod',
+): AutonomousEnvironment {
+ if (value == null || value === '') return fallback
+ if (isAutonomousEnvironment(value)) return value
+ throw new Error('INVALID_AUTONOMOUS_ENV')
+}
+
+/** Reads a persisted row safely during rolling migration, before the worker has stamped it. */
+export function storedAutonomousEnvironment(value: unknown): AutonomousEnvironment {
+ return isAutonomousEnvironment(value) ? value : 'stag'
+}
+
+export interface AutonomousEnvironmentConfig {
+ name: AutonomousEnvironment
+ ssoIssuer: string
+ ssoClientId: string
+ ssoClientSecret?: string
+ ssoProfileUrl: string
+ bffUrl: string
+ checkoutOrigin: string
+ campaignApiUrl: string
+ campaignApiKey?: string
+}
+
+/** Single source of truth for upstream account-plane routing. */
+export function autonomousEnvironmentConfig(name: AutonomousEnvironment): AutonomousEnvironmentConfig {
+ if (name === 'stag') {
+ return {
+ name,
+ ssoIssuer: env.STAGING_SSO_ISSUER,
+ ssoClientId: env.STAGING_SSO_CLIENT_ID || env.SSO_CLIENT_ID,
+ ssoClientSecret: env.STAGING_SSO_CLIENT_SECRET || env.SSO_CLIENT_SECRET,
+ ssoProfileUrl: env.STAGING_SSO_PROFILE_URL,
+ bffUrl: env.STAGING_AUTONOMOUS_BFF_URL,
+ checkoutOrigin: env.STAGING_AUTONOMOUS_CHECKOUT_ORIGIN,
+ campaignApiUrl: env.STAGING_AUTONOMOUS_CAMPAIGN_API_URL,
+ campaignApiKey: env.STAGING_AUTONOMOUS_CAMPAIGN_API_KEY || undefined,
+ }
+ }
+ return {
+ name,
+ ssoIssuer: env.SSO_ISSUER,
+ ssoClientId: env.SSO_CLIENT_ID,
+ ssoClientSecret: env.SSO_CLIENT_SECRET,
+ ssoProfileUrl: env.SSO_PROFILE_URL,
+ bffUrl: env.AUTONOMOUS_BFF_URL,
+ checkoutOrigin: env.AUTONOMOUS_CHECKOUT_ORIGIN,
+ campaignApiUrl: env.AUTONOMOUS_CAMPAIGN_API_URL,
+ campaignApiKey: env.AUTONOMOUS_CAMPAIGN_API_KEY || undefined,
+ }
+}
diff --git a/backend/src/lib/billingPlanMetadata.test.ts b/backend/src/lib/billingPlanMetadata.test.ts
new file mode 100644
index 000000000..fea340a5e
--- /dev/null
+++ b/backend/src/lib/billingPlanMetadata.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { dailyTokenLimitForPlan } from './billingPlanMetadata.js'
+
+describe('campaign plan metadata', () => {
+ it('reads finite non-negative daily token limits and preserves unlimited zero', () => {
+ expect(dailyTokenLimitForPlan({ externalMetadata: { daily_token_limit: 10_000_000 } })).toBe(10_000_000)
+ expect(dailyTokenLimitForPlan({ externalMetadata: { daily_token_limit: '50000000' } })).toBe(50_000_000)
+ expect(dailyTokenLimitForPlan({ externalMetadata: { daily_token_limit: 0 } })).toBe(0)
+ })
+
+ it('omits missing or invalid catalog limits', () => {
+ expect(dailyTokenLimitForPlan({ externalMetadata: null })).toBeNull()
+ expect(dailyTokenLimitForPlan({ externalMetadata: {} })).toBeNull()
+ expect(dailyTokenLimitForPlan({ externalMetadata: { daily_token_limit: '' } })).toBeNull()
+ expect(dailyTokenLimitForPlan({ externalMetadata: { daily_token_limit: -1 } })).toBeNull()
+ expect(dailyTokenLimitForPlan({ externalMetadata: { daily_token_limit: 'many' } })).toBeNull()
+ })
+})
diff --git a/backend/src/lib/billingPlanMetadata.ts b/backend/src/lib/billingPlanMetadata.ts
new file mode 100644
index 000000000..1dfbd0d6d
--- /dev/null
+++ b/backend/src/lib/billingPlanMetadata.ts
@@ -0,0 +1,14 @@
+type PlanMetadataCarrier = { externalMetadata?: unknown }
+
+/** Read the campaign's daily token quota from the opaque catalog snapshot stored on a plan.
+ * Zero is meaningful: Autonomous uses it for an unlimited daily quota. */
+export function dailyTokenLimitForPlan(plan: PlanMetadataCarrier): number | null {
+ const metadata = plan.externalMetadata
+ if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return null
+ const raw = (metadata as Record<string, unknown>).daily_token_limit
+ if (typeof raw !== 'number' && typeof raw !== 'string') return null
+ if (typeof raw === 'string' && !raw.trim()) return null
+ const parsed = typeof raw === 'number' ? raw : Number(raw.trim())
+ if (!Number.isFinite(parsed) || parsed < 0) return null
+ return Math.floor(parsed)
+}
diff --git a/backend/src/lib/billingState.test.ts b/backend/src/lib/billingState.test.ts
new file mode 100644
index 000000000..59985d6f1
--- /dev/null
+++ b/backend/src/lib/billingState.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { billingStatusOf, subscriptionMatches } from './billingState.js'
+
+describe('machine billing state', () => {
+ it('grandfathers rows without billingStatus as active', () => {
+ expect(billingStatusOf({ authMode: 'managed' })).toBe('active')
+ expect(billingStatusOf({ authMode: 'remote' })).toBe('not_required')
+ expect(billingStatusOf({ authMode: 'remote', billingStatus: 'not_required' })).toBe('not_required')
+ expect(billingStatusOf({ authMode: 'remote', billingStatus: 'active' })).toBe('active')
+ expect(billingStatusOf({ authMode: 'managed', billingStatus: 'pending' })).toBe('pending')
+ expect(billingStatusOf({ authMode: 'remote', billingStatus: 'suspended' })).toBe('suspended')
+ })
+
+ it('requires campaign, device reference and plan id to all match', () => {
+ const expected = { campaignCode: 'ai-harness-device', referenceId: 'device-1', planId: 38 }
+ expect(subscriptionMatches({ campaignCode: 'ai-harness-device', referenceId: 'device-1', planId: 38 }, expected)).toBe(true)
+ expect(subscriptionMatches({ campaignCode: 'other', referenceId: 'device-1', planId: 38 }, expected)).toBe(false)
+ expect(subscriptionMatches({ campaignCode: 'ai-harness-device', referenceId: 'device-2', planId: 38 }, expected)).toBe(false)
+ expect(subscriptionMatches({ campaignCode: 'ai-harness-device', referenceId: 'device-1', planId: 39 }, expected)).toBe(false)
+ })
+})
diff --git a/backend/src/lib/billingState.ts b/backend/src/lib/billingState.ts
new file mode 100644
index 000000000..095a30ea9
--- /dev/null
+++ b/backend/src/lib/billingState.ts
@@ -0,0 +1,39 @@
+import { AppError } from '../errors/index.js'
+
+export type MachineBillingStatus = 'not_required' | 'pending' | 'active' | 'suspended'
+export const REMOTE_BILLING_SUSPENDED_FRAME = '__billing_suspended'
+
+/** Missing managed status is legacy-active; missing Remote status is grandfathered/unbilled. */
+export function billingStatusOf(binding: { billingStatus?: string | null; authMode?: string | null }): MachineBillingStatus {
+ if (binding.billingStatus === 'pending') return 'pending'
+ if (binding.billingStatus === 'suspended') return 'suspended'
+ if (binding.billingStatus === 'active') return 'active'
+ if (binding.billingStatus === 'not_required') return 'not_required'
+ // Remote rows created before campaign billing have no status and remain grandfathered.
+ if (binding.authMode === 'remote') return 'not_required'
+ return 'active'
+}
+
+export function assertMachineBillingActive(binding: { billingStatus?: string | null; authMode?: string | null }): void {
+ if (billingStatusOf(binding) === 'pending') {
+ throw new AppError('Machine payment is pending', 409, 'MACHINE_PAYMENT_PENDING')
+ }
+ if (billingStatusOf(binding) === 'suspended') {
+ throw new AppError('Machine subscription is required', 402, 'MACHINE_SUBSCRIPTION_REQUIRED')
+ }
+}
+
+export function machineBillingAllowsDataPlane(binding: { billingStatus?: string | null; authMode?: string | null }): boolean {
+ const status = billingStatusOf(binding)
+ return status === 'active' || status === 'not_required'
+}
+
+export function subscriptionMatches(
+ subscription: { campaignCode?: string; referenceId?: string; planId?: number } | undefined,
+ expected: { campaignCode: string; referenceId: string; planId: number },
+): boolean {
+ return !!subscription &&
+ subscription.campaignCode === expected.campaignCode &&
+ subscription.referenceId === expected.referenceId &&
+ subscription.planId === expected.planId
+}
diff --git a/backend/src/lib/bus.ts b/backend/src/lib/bus.ts
new file mode 100644
index 000000000..2255d9061
--- /dev/null
+++ b/backend/src/lib/bus.ts
@@ -0,0 +1,619 @@
+/**
+ * Cross-instance data bus over Redis pub/sub.
+ *
+ * Behind a load balancer a given agent's web socket(s) and its single manager socket can land on
+ * DIFFERENT backend instances. Redis bridges that gap (this is the ONLY cross-instance state — see
+ * docs/plans/2026-07-09_invert-ws-transport-backend-hub-redis.md):
+ *
+ * - up:{machineId} — node→client events. Published by the backend holding the manager socket (B_m);
+ * delivered by every backend with ≥1 local client for the agent (≤ M subscribers).
+ * - down:{machineId} — client→node messages. Published by any client-holding backend; delivered by the
+ * single backend holding the manager socket (exactly 1 subscriber, B_m).
+ * - mgr:{managerId} — control/provisioning commands to a specific manager (Phase 3), delivered by the
+ * backend holding that manager's socket.
+ *
+ * ioredis requires a connection in subscribe mode to be dedicated (it can't run other commands), so
+ * we keep one `sub` connection for SUBSCRIBE and one `pub` connection for PUBLISH/keys.
+ */
+import { Redis } from 'ioredis'
+import { env } from '../config/env.js'
+import { logger } from '../utils/logger.js'
+import type { UpBusMsg, DownBusMsg } from './tunnel.js'
+
+const redisOpts = { maxRetriesPerRequest: null as null, lazyConnect: false }
+
+export const pub = new Redis(env.REDIS_URL, redisOpts)
+const sub = new Redis(env.REDIS_URL, redisOpts)
+const terminalSub = new Redis(env.REDIS_URL, redisOpts)
+
+pub.on('error', (err: Error) => logger.error('[bus] pub redis error', err))
+sub.on('error', (err: Error) => logger.error('[bus] sub redis error', err))
+terminalSub.on('error', (err: Error) => logger.error('[bus] terminal sub redis error', err))
+
+export async function closeBus(): Promise<void> {
+ await Promise.allSettled([pub.quit(), sub.quit(), terminalSub.quit()])
+}
+
+type Cb = (msg: unknown) => void
+const channelSubs = new Map<string, Set<Cb>>()
+const channelSubscribePromises = new Map<string, Promise<void>>()
+
+sub.on('message', (channel: string, payload: string) => {
+ const set = channelSubs.get(channel)
+ if (!set || set.size === 0) return
+ let msg: unknown
+ try {
+ msg = JSON.parse(payload)
+ } catch (err) {
+ logger.error('[bus] bad JSON on channel', err, { channel })
+ return
+ }
+ for (const cb of set) {
+ try {
+ cb(msg)
+ } catch (err) {
+ logger.error('[bus] subscriber callback threw', err, { channel })
+ }
+ }
+})
+
+/** Refcounted subscribe: SUBSCRIBEs on the first callback for a channel, UNSUBSCRIBEs on the last. */
+async function addSub(channel: string, cb: Cb): Promise<() => void> {
+ let set = channelSubs.get(channel)
+ let subscribePromise = channelSubscribePromises.get(channel)
+ if (!set) {
+ set = new Set()
+ channelSubs.set(channel, set)
+ subscribePromise = sub.subscribe(channel)
+ .then(() => undefined)
+ .catch((err) => {
+ logger.error('[bus] subscribe failed', err, { channel })
+ if (channelSubs.get(channel) === set) channelSubs.delete(channel)
+ throw err
+ })
+ .finally(() => {
+ if (channelSubscribePromises.get(channel) === subscribePromise) channelSubscribePromises.delete(channel)
+ })
+ channelSubscribePromises.set(channel, subscribePromise)
+ }
+ set.add(cb)
+ if (subscribePromise) {
+ try {
+ await subscribePromise
+ } catch (err) {
+ const s = channelSubs.get(channel)
+ if (s === set) {
+ s.delete(cb)
+ if (s.size === 0) channelSubs.delete(channel)
+ }
+ throw err
+ }
+ }
+ return () => {
+ const s = channelSubs.get(channel)
+ if (!s) return
+ s.delete(cb)
+ if (s.size === 0) {
+ channelSubs.delete(channel)
+ sub.unsubscribe(channel).catch(() => { /* ignore */ })
+ }
+ }
+}
+
+const upChannel = (machineId: string): string => `up:${machineId}`
+const downChannel = (machineId: string): string => `down:${machineId}`
+const mgrChannel = (managerId: string): string => `mgr:${managerId}`
+const appDownChannel = (machineId: string): string => `appdown:${machineId}`
+const appUpChannel = (streamId: string): string => `appup:${streamId}`
+const presenceKey = (machineId: string): string => `machine:${machineId}:mgr`
+const terminalUpChannel = (machineId: string): string => `termup:${machineId}`
+const terminalDownChannel = (machineId: string): string => `termdown:${machineId}`
+
+type BinaryCb = (payload: Buffer) => void
+const binarySubs = new Map<string, Set<BinaryCb>>()
+terminalSub.on('messageBuffer', (channelRaw: Buffer, payload: Buffer) => {
+ const callbacks = binarySubs.get(channelRaw.toString('utf8'))
+ if (!callbacks) return
+ for (const callback of callbacks) {
+ try { callback(Buffer.from(payload)) } catch (err) { logger.error('[bus] binary subscriber callback threw', err) }
+ }
+})
+
+async function addBinarySub(channel: string, callback: BinaryCb): Promise<() => void> {
+ let callbacks = binarySubs.get(channel)
+ if (!callbacks) {
+ callbacks = new Set()
+ binarySubs.set(channel, callbacks)
+ await terminalSub.subscribe(channel)
+ }
+ callbacks.add(callback)
+ return () => {
+ const current = binarySubs.get(channel)
+ if (!current) return
+ current.delete(callback)
+ if (current.size === 0) {
+ binarySubs.delete(channel)
+ void terminalSub.unsubscribe(channel)
+ }
+ }
+}
+
+export function subscribeTerminalUp(machineId: string, callback: BinaryCb): Promise<() => void> {
+ return addBinarySub(terminalUpChannel(machineId), callback)
+}
+export function subscribeTerminalDown(machineId: string, callback: BinaryCb): Promise<() => void> {
+ return addBinarySub(terminalDownChannel(machineId), callback)
+}
+export function publishTerminalUp(machineId: string, payload: Uint8Array): Promise<number> {
+ return pub.publish(terminalUpChannel(machineId), Buffer.from(payload))
+}
+export function publishTerminalDown(machineId: string, payload: Uint8Array): Promise<number> {
+ return pub.publish(terminalDownChannel(machineId), Buffer.from(payload))
+}
+
+// ── up / down data channels ──────────────────────────────────────────────────────────────────────
+
+export function subscribeUp(machineId: string, cb: (msg: UpBusMsg) => void): Promise<() => void> {
+ return addSub(upChannel(machineId), cb as Cb)
+}
+
+export function subscribeDown(machineId: string, cb: (msg: DownBusMsg) => void): Promise<() => void> {
+ return addSub(downChannel(machineId), cb as Cb)
+}
+
+export function publishUp(machineId: string, msg: UpBusMsg): Promise<number> {
+ return pub.publish(upChannel(machineId), JSON.stringify(msg))
+}
+
+export function publishDown(machineId: string, msg: DownBusMsg): Promise<number> {
+ return pub.publish(downChannel(machineId), JSON.stringify(msg))
+}
+
+// ── app-proxy tunnel channels ────────────────────────────────────────────────────────────────────
+// App traffic is routed by MACHINEID (not managerId): an app belongs to a machine, and the machine's
+// node manager socket has exactly ONE backend subscriber (B_m), so appdown:{machineId} has a single
+// delivery path (no duplication under clustering) and rides the machine's sharded pool socket. Responses flow back
+// on a per-STREAM channel so they reach the exact backend instance terminating the public request.
+
+/** client→app frames (app_req, app_body, app_ws_open/msg/close, app_abort), delivered by B_m. */
+export function subscribeAppDown(machineId: string, cb: (msg: unknown) => void): Promise<() => void> {
+ return addSub(appDownChannel(machineId), cb)
+}
+export function publishAppDown(machineId: string, msg: unknown): Promise<number> {
+ return pub.publish(appDownChannel(machineId), JSON.stringify(msg))
+}
+
+/** app→client frames (app_res, app_res_body, app_ws_msg/close, app_abort) → the origin instance. */
+export function subscribeAppUp(streamId: string, cb: (msg: unknown) => void): Promise<() => void> {
+ return addSub(appUpChannel(streamId), cb)
+}
+export function publishAppUp(streamId: string, msg: unknown): Promise<number> {
+ return pub.publish(appUpChannel(streamId), JSON.stringify(msg))
+}
+
+// ── manager command channel (Phase 3) ──────────────────────────────────────────────────────────
+
+export function subscribeMgr(managerId: string, cb: (msg: unknown) => void): Promise<() => void> {
+ return addSub(mgrChannel(managerId), cb)
+}
+
+export function publishMgr(managerId: string, msg: unknown): Promise<number> {
+ return pub.publish(mgrChannel(managerId), JSON.stringify(msg))
+}
+
+// Per-request reply channel for the provisioning RPC (backend → mgr:{managerId} → manager → reply).
+const replyChannel = (requestId: string): string => `mgrreply:${requestId}`
+
+export function subscribeReply(requestId: string, cb: (msg: unknown) => void): Promise<() => void> {
+ return addSub(replyChannel(requestId), cb)
+}
+
+export function publishReply(requestId: string, msg: unknown): Promise<number> {
+ return pub.publish(replyChannel(requestId), JSON.stringify(msg))
+}
+
+// ── agent→manager presence (which manager currently owns an agent's node) ─────────────────────────
+
+/** Set/refresh the presence key. Called on register + on each manager ping. */
+export async function setAgentPresence(machineId: string, managerId: string, ttlSec = 30): Promise<void> {
+ try {
+ await pub.set(presenceKey(machineId), managerId, 'EX', ttlSec)
+ } catch (err) {
+ logger.error('[bus] setAgentPresence failed', err, { machineId })
+ }
+}
+
+export async function getAgentPresence(machineId: string): Promise<string | null> {
+ try {
+ return await pub.get(presenceKey(machineId))
+ } catch (err) {
+ logger.error('[bus] getAgentPresence failed', err, { machineId })
+ return null
+ }
+}
+
+// A device's last-selected machine, so the backend can restore the active machine after a reconnect. A
+// multi_machine device renders agents by attaching to every machine WITHOUT sending machine_select, so on a
+// fresh connection `activeMachineId` would otherwise stay null and voice/RPCs fail with "no machine selected".
+const deviceLastMachineKey = (deviceId: string): string => `devlastmachine:${deviceId}`
+export async function setDeviceLastMachine(deviceId: string, machineId: string, ttlSec = 30 * 24 * 3600): Promise<void> {
+ try { await pub.set(deviceLastMachineKey(deviceId), machineId, 'EX', ttlSec) } catch (err) { logger.error('[bus] setDeviceLastMachine failed', err, { deviceId }) }
+}
+export async function getDeviceLastMachine(deviceId: string): Promise<string | null> {
+ try { return await pub.get(deviceLastMachineKey(deviceId)) } catch { return null }
+}
+
+// ── provider-machine recap cache (the device's tile text) ─────────────────────────────────────────
+// Redis rather than a process Map because the backend runs FOUR cluster workers: the worker that ran
+// the turn is usually not the one the device's `agent_recent` lands on, so an in-heap cache would
+// answer "no recap" most of the time and every worker restart would blank the tiles. Only the
+// provider path writes here — every other machine kind persists its own recap node-side.
+// A whole small array under one key, not LPUSH/LTRIM: `n` is capped at 5 by the schema, so the value
+// is tiny, and every other value in this file is a plain JSON `set`. Two turns finishing on the SAME
+// agent at once can lose an entry in the read-modify-write; that is no worse than `activeTasks`,
+// which is already one-per-machine, and a lost tile self-heals on the next turn.
+const machineRecapKey = (machineId: string, agentId: string): string => `machine:${machineId}:recap:${agentId}`
+const MACHINE_RECAP_KEEP = 5
+
+export async function pushMachineRecap<T>(machineId: string, agentId: string, entry: T, ttlSec = 30 * 24 * 3600): Promise<void> {
+ if (!agentId) return
+ try {
+ const existing = await getMachineRecaps<T>(machineId, agentId, MACHINE_RECAP_KEEP)
+ const next = [entry, ...existing].slice(0, MACHINE_RECAP_KEEP)
+ await pub.set(machineRecapKey(machineId, agentId), JSON.stringify(next), 'EX', ttlSec)
+ } catch (err) {
+ // Best-effort: a recap that fails to cache costs a tile after a device reboot, never a turn.
+ logger.error('[bus] pushMachineRecap failed', err, { machineId, agentId })
+ }
+}
+
+export async function getMachineRecaps<T>(machineId: string, agentId: string, n: number): Promise<T[]> {
+ if (!agentId) return []
+ try {
+ const raw = await pub.get(machineRecapKey(machineId, agentId))
+ if (!raw) return []
+ const parsed = JSON.parse(raw) as unknown
+ return Array.isArray(parsed) ? (parsed.slice(0, n) as T[]) : []
+ } catch {
+ return []
+ }
+}
+
+// ── Resumable voice upload: park a partial live-stream so it survives a WS drop + reconnect ──────────
+// Streaming voice has no local device copy; a WS blip mid-recording used to lose the whole (up to ~10-min)
+// ramble. On a drop the backend PARKS the accumulated audio here keyed by the STABLE deviceId (not the
+// per-connection closure), so a reconnect — which may land on a DIFFERENT backend instance (prod is
+// multi-instance, non-sticky) — can `resumeVoiceUpload` and continue appending. Grace TTL ~60s. Written
+// once per DROP (not per chunk). meta is the commit marker (set AFTER the pcm), so a torn write reads as
+// absent. See docs/plans resumable-voice-upload.
+export interface ParkedVoiceMeta {
+ uploadId: string
+ mode: 'turn' | 'ask'
+ route: boolean
+ goal: boolean
+ loop: boolean
+ autonomy: 'plan' | 'auto'
+ agentId: string | null
+ sessionId: string | null
+ requestId: string | null
+ sr: number
+ lang: string
+ size: number
+ machineId: string | null
+}
+const voiceUploadPcmKey = (deviceId: string): string => `voiceupload:${deviceId}:pcm`
+const voiceUploadMetaKey = (deviceId: string): string => `voiceupload:${deviceId}:meta`
+export async function parkVoiceUpload(deviceId: string, meta: ParkedVoiceMeta, pcm: Buffer, ttlSec = 60): Promise<void> {
+ try {
+ await pub.set(voiceUploadPcmKey(deviceId), pcm, 'EX', ttlSec) // binary value (ioredis Buffer)
+ await pub.set(voiceUploadMetaKey(deviceId), JSON.stringify(meta), 'EX', ttlSec) // commit marker last
+ } catch (err) { logger.error('[bus] parkVoiceUpload failed', err, { deviceId, size: pcm.length }) }
+}
+export async function resumeVoiceUpload(deviceId: string): Promise<{ meta: ParkedVoiceMeta; pcm: Buffer } | null> {
+ try {
+ const metaStr = await pub.get(voiceUploadMetaKey(deviceId))
+ if (!metaStr) return null
+ const pcm = await pub.getBuffer(voiceUploadPcmKey(deviceId))
+ if (!pcm) return null
+ return { meta: JSON.parse(metaStr) as ParkedVoiceMeta, pcm }
+ } catch (err) { logger.error('[bus] resumeVoiceUpload failed', err, { deviceId }); return null }
+}
+export async function evictVoiceUpload(deviceId: string): Promise<void> {
+ try { await pub.del(voiceUploadMetaKey(deviceId), voiceUploadPcmKey(deviceId)) } catch { /* best effort */ }
+}
+
+export async function clearAgentPresence(machineId: string): Promise<void> {
+ try {
+ await pub.del(presenceKey(machineId))
+ } catch (err) {
+ logger.error('[bus] clearAgentPresence failed', err, { machineId })
+ }
+}
+
+// ── one-computer-per-machine ownership ────────────────────────────────────────────────────────────
+// A SEPARATE key from presence (which stays `machine:{id}:mgr` = 'remote' for the online/status path):
+// `machine:{id}:owner` = the connecting COMPUTER's stable id. Atomic compare-and-set so a SECOND
+// computer (different computerId) is rejected while the first holds the machine, but the SAME computer
+// reconnecting after a blip/restart (its 30s key may still be alive) always reclaims. The value is the
+// computerId — not a shared token — so the delete on teardown is conditional (a superseded/other socket
+// can't free the real owner's claim). Mirrors the device-presence compare-and-delete pattern below.
+const ownerKey = (machineId: string): string => `machine:${machineId}:owner`
+
+/** Claim or refresh ownership. Returns true when this computer owns the machine afterwards (it was free
+ * or already ours), false when a DIFFERENT computer currently holds it. Also used as the refresh call. */
+export async function claimMachineOwner(machineId: string, computerId: string, ttlSec = 30): Promise<boolean> {
+ try {
+ const res = await pub.eval(
+ "local cur = redis.call('get', KEYS[1]) " +
+ "if (not cur) or (cur == ARGV[1]) then redis.call('set', KEYS[1], ARGV[1], 'EX', ARGV[2]) return 1 else return 0 end",
+ 1, ownerKey(machineId), computerId, String(ttlSec),
+ )
+ return res === 1
+ } catch (err) {
+ // On a Redis error, fail OPEN (allow) — losing the backend link should never lock a user out of
+ // their own machine; single-computer enforcement is best-effort liveness, not a security boundary.
+ logger.error('[bus] claimMachineOwner failed', err, { machineId })
+ return true
+ }
+}
+
+/** Conditional delete: only frees the claim if it still holds THIS computerId (compare-and-delete). */
+export async function releaseMachineOwner(machineId: string, computerId: string): Promise<void> {
+ try {
+ await pub.eval(
+ "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
+ 1, ownerKey(machineId), computerId,
+ )
+ } catch (err) {
+ logger.error('[bus] releaseMachineOwner failed', err, { machineId })
+ }
+}
+
+// ── desktop-app state on a remote machine ─────────────────────────────────────────────────────────
+// `machine:{id}:app` = "<engine>:<state>" — which desktop app this COMPUTER drives and whether it is
+// running right now (see docs/specs/machine-adapter-cursor-desktop-integration.md). Written by the
+// adapter socket, refreshed on the same 15s heartbeat that renews presence, and given the SAME 30s
+// TTL as `machine:{id}:mgr` so the claim can never outlive the socket that made it: if a worker is
+// killed without running cleanup, both keys expire together and the machine reads offline rather
+// than "Cursor open" forever. Deliberately NOT a Prisma column — the value's useful life is 30s and
+// a DB row would survive a crashed worker and lie.
+const appStateKey = (machineId: string): string => `machine:${machineId}:app`
+
+export async function setMachineAppState(
+ machineId: string, engine: string, state: string, ttlSec = 30,
+): Promise<void> {
+ try {
+ await pub.set(appStateKey(machineId), `${engine}:${state}`, 'EX', ttlSec)
+ } catch (err) {
+ logger.error('[bus] setMachineAppState failed', err, { machineId })
+ }
+}
+
+/** null when unknown (no adapter, legacy adapter, or the key expired). */
+export async function getMachineAppState(
+ machineId: string,
+): Promise<{ engine: string; state: string } | null> {
+ try {
+ const raw = await pub.get(appStateKey(machineId))
+ if (!raw) return null
+ const sep = raw.indexOf(':')
+ if (sep <= 0 || sep === raw.length - 1) return null
+ return { engine: raw.slice(0, sep), state: raw.slice(sep + 1) }
+ } catch (err) {
+ logger.error('[bus] getMachineAppState failed', err, { machineId })
+ return null
+ }
+}
+
+export async function clearMachineAppState(machineId: string): Promise<void> {
+ try {
+ await pub.del(appStateKey(machineId))
+ } catch (err) {
+ logger.error('[bus] clearMachineAppState failed', err, { machineId })
+ }
+}
+
+// ── device presence (is a paired device's socket currently connected?) ─────────────────────────────
+// One key PER DEVICE (`device:{deviceId}:conn`) — a user with many devices has one independent key,
+// refresh loop and supersede scope per device. The VALUE is the connection's own token so that when
+// a device reconnects (new socket, possibly on another worker) the OLD socket's teardown cannot
+// delete the NEW socket's key: the delete is conditional on the token still being ours.
+const devicePresenceKey = (deviceId: string): string => `device:${deviceId}:conn`
+const deviceStatusChannel = (userId: string): string => `devstatus:${userId}`
+const deviceMachineListChannel = (userId: string): string => `devmachines:${userId}`
+const deviceE2eePairChannel = (userId: string): string => `deve2eepair:${userId}`
+
+/** Set/refresh this connection's presence. Called on device-ws open + every ~15s while connected. */
+export async function setDevicePresence(deviceId: string, connToken: string, ttlSec = 45): Promise<void> {
+ try {
+ await pub.set(devicePresenceKey(deviceId), connToken, 'EX', ttlSec)
+ } catch (err) {
+ logger.error('[bus] setDevicePresence failed', err, { deviceId })
+ }
+}
+
+/** Conditional delete: only removes the key if it still holds THIS connection's token.
+ * Returns true when the key is gone afterwards (deleted by us or already absent). */
+export async function clearDevicePresence(deviceId: string, connToken: string): Promise<boolean> {
+ try {
+ await pub.eval(
+ "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
+ 1, devicePresenceKey(deviceId), connToken,
+ )
+ return !(await pub.get(devicePresenceKey(deviceId)))
+ } catch (err) {
+ logger.error('[bus] clearDevicePresence failed', err, { deviceId })
+ return false
+ }
+}
+
+export async function getDevicePresence(deviceId: string): Promise<boolean> {
+ try {
+ return !!(await pub.get(devicePresenceKey(deviceId)))
+ } catch (err) {
+ logger.error('[bus] getDevicePresence failed', err, { deviceId })
+ return false
+ }
+}
+
+export interface DeviceStatusMsg { deviceId: string; online: boolean; lastSeenAt?: string }
+
+/** Per-USER transition channel (one sub per watching web socket); messages are PER-DEVICE. */
+export function publishDeviceStatus(userId: string, msg: DeviceStatusMsg): Promise<number> {
+ return pub.publish(deviceStatusChannel(userId), JSON.stringify(msg))
+}
+
+export function subscribeDeviceStatus(userId: string, cb: (msg: DeviceStatusMsg) => void): Promise<() => void> {
+ return addSub(deviceStatusChannel(userId), cb as Cb)
+}
+
+// Per-USER machine-list invalidation for connected devices (and web machine-list watchers). Machine
+// create/delete/rename happens on normal REST workers, while device/web sockets may live on another
+// worker, so Redis fans out "re-query the DB now".
+export interface DeviceMachineListChangedMsg {
+ reason: 'created' | 'deleted' | 'renamed' | 'updated' | 'environment_changed'
+ autonomousEnv?: 'prod' | 'stag'
+}
+
+export function publishDeviceMachineListChanged(userId: string, msg: DeviceMachineListChangedMsg): Promise<number> {
+ return pub.publish(deviceMachineListChannel(userId), JSON.stringify(msg))
+}
+
+export function subscribeDeviceMachineListChanged(userId: string, cb: (msg: DeviceMachineListChangedMsg) => void): Promise<() => void> {
+ return addSub(deviceMachineListChannel(userId), cb as Cb)
+}
+
+export interface DeviceE2eePairMsg {
+ kind: 'pending' | 'cleared'
+ machineId: string
+ machineName?: string | null
+ label?: string
+ pairId: string
+ expiresAt?: number
+ computerFingerprint?: string | null
+ result?: 'paired' | 'failed' | 'cancelled'
+}
+
+export function publishDeviceE2eePair(userId: string, msg: DeviceE2eePairMsg): Promise<number> {
+ return pub.publish(deviceE2eePairChannel(userId), JSON.stringify(msg))
+}
+
+export function subscribeDeviceE2eePair(userId: string, cb: (msg: DeviceE2eePairMsg) => void): Promise<() => void> {
+ return addSub(deviceE2eePairChannel(userId), cb as Cb)
+}
+
+// ── per-device control channel (backend → the one connected device socket, any worker) ────────────
+// Unlike pushDeviceRevoked (rides up:{machineId}, reaches only a hub-ATTACHED commander conn — i.e. a
+// device that has selected a machine), this reaches the device-ws relay itself, so a device parked on
+// the machine PICKER is covered too.
+const deviceControlChannel = (deviceId: string): string => `devctl:${deviceId}`
+
+export interface DeviceControlMsg { action: 'revoked' | 'superseded'; by?: string }
+
+export function publishDeviceControl(deviceId: string, msg: DeviceControlMsg): Promise<number> {
+ return pub.publish(deviceControlChannel(deviceId), JSON.stringify(msg))
+}
+
+export function subscribeDeviceControl(deviceId: string, cb: (msg: DeviceControlMsg) => void): Promise<() => void> {
+ return addSub(deviceControlChannel(deviceId), cb as Cb)
+}
+
+// ── instance-affinity for the data-plane mesh (Phase 2) ────────────────────────────────────────────
+// machine:{machineId}:appinst → the backend INSTANCE id holding that agent's app-pool manager socket.
+// inst:{instanceId}:mesh → that instance's internal mesh endpoint (host:port). Both TTL-refreshed.
+const appInstKey = (machineId: string): string => `machine:${machineId}:appinst`
+const meshKey = (instanceId: string): string => `inst:${instanceId}:mesh`
+
+export async function setAppInstance(machineId: string, instanceId: string, ttlSec = 30): Promise<void> {
+ try { await pub.set(appInstKey(machineId), instanceId, 'EX', ttlSec) } catch (err) { logger.error('[bus] setAppInstance failed', err, { machineId }) }
+}
+export async function getAppInstance(machineId: string): Promise<string | null> {
+ try { return await pub.get(appInstKey(machineId)) } catch (err) { logger.error('[bus] getAppInstance failed', err, { machineId }); return null }
+}
+export async function clearAppInstance(machineId: string): Promise<void> {
+ try { await pub.del(appInstKey(machineId)) } catch (err) { logger.error('[bus] clearAppInstance failed', err, { machineId }) }
+}
+export async function setMeshEndpoint(instanceId: string, endpoint: string, ttlSec = 30): Promise<void> {
+ try { await pub.set(meshKey(instanceId), endpoint, 'EX', ttlSec) } catch (err) { logger.error('[bus] setMeshEndpoint failed', err, { instanceId }) }
+}
+export async function getMeshEndpoint(instanceId: string): Promise<string | null> {
+ try { return await pub.get(meshKey(instanceId)) } catch (err) { logger.error('[bus] getMeshEndpoint failed', err, { instanceId }); return null }
+}
+
+// ── global per-agent client-count registry ─────────────────────────────────────────────────────────
+// Drives the node's `__clients` aggregate lifecycle. `registry.clientCounts` is PER-PROCESS, but the
+// node needs the CROSS-INSTANCE total (web on B1 + device on B2 must both count). We keep a HASH per
+// agent, field = backend INSTANCE_ID → "ui,commander". Each field carries a per-field TTL (HEXPIRE,
+// Redis ≥7.4) so a CRASHED instance's contribution ages out on its own — else the node would keep a
+// commander/web aggregate warm for a dead client-holder. Live instances refresh on the hub heartbeat
+// (25s < 45s TTL). Only B_m reads the sum and emits the frame (see hub.recomputeAndSendClients).
+const clientsKey = (machineId: string): string => `machine:${machineId}:clients`
+const commanderJoinGenerationKey = (machineId: string): string => `machine:${machineId}:commander-join-generation`
+const CLIENT_COUNT_TTL_SEC = 45
+
+/** Write THIS instance's local {ui,commander,commanderActive} for an agent (HDEL when zero), with a fresh
+ * per-field TTL. Field format is `ui,commander,commanderActive`; the trailing field is optional so an old
+ * instance's `ui,commander` still parses (missing → 0). */
+export async function setAgentClientCount(machineId: string, instanceId: string, ui: number, commander: number, commanderActive = 0): Promise<void> {
+ const key = clientsKey(machineId)
+ try {
+ if (ui === 0 && commander === 0) { await pub.hdel(key, instanceId); return }
+ await pub.hset(key, instanceId, `${ui},${commander},${commanderActive}`)
+ } catch (err) {
+ logger.error('[bus] setAgentClientCount failed', err, { machineId, instanceId })
+ return
+ }
+ // Per-field expiry (Redis 7.4+): FIELDS 1 <field>. Refreshed each heartbeat; a dead instance's field
+ // simply expires. `pub.call` avoids depending on ioredis' typed hexpire signature. On Redis < 7.4
+ // (HEXPIRE unknown) fall back to a whole-key TTL — coarser (any live instance's heartbeat keeps the
+ // whole key warm), but enough that a crashed sole instance still ages out. The count was already
+ // written above, so a TTL failure must NOT surface as a "client count failed" error.
+ try {
+ await pub.call('HEXPIRE', key, String(CLIENT_COUNT_TTL_SEC), 'FIELDS', '1', instanceId)
+ } catch {
+ try { await pub.expire(key, CLIENT_COUNT_TTL_SEC) } catch { /* best-effort */ }
+ }
+}
+
+/** Sum of every live instance's counts for an agent (expired fields already dropped Redis-side). */
+export async function getAgentClientTotals(machineId: string): Promise<{ ui: number; commander: number; commanderActive: number }> {
+ try {
+ const h = await pub.hgetall(clientsKey(machineId))
+ let ui = 0
+ let commander = 0
+ let commanderActive = 0
+ for (const v of Object.values(h)) {
+ const [u, c, a] = String(v).split(',')
+ ui += parseInt(u, 10) || 0
+ commander += parseInt(c, 10) || 0
+ commanderActive += parseInt(a, 10) || 0
+ }
+ return { ui, commander, commanderActive }
+ } catch (err) {
+ logger.error('[bus] getAgentClientTotals failed', err, { machineId })
+ return { ui: 0, commander: 0, commanderActive: 0 }
+ }
+}
+
+/** Monotonic machine-wide generation. Unlike the aggregate count, this changes for EVERY commander attach,
+ * including a leave/rejoin that is coalesced to the same total before the node sees a count snapshot. */
+export async function bumpCommanderJoinGeneration(machineId: string): Promise<number | undefined> {
+ try {
+ return await pub.incr(commanderJoinGenerationKey(machineId))
+ } catch (err) {
+ logger.error('[bus] bumpCommanderJoinGeneration failed', err, { machineId })
+ return undefined
+ }
+}
+
+export async function getCommanderJoinGeneration(machineId: string): Promise<number | undefined> {
+ try {
+ const raw = await pub.get(commanderJoinGenerationKey(machineId))
+ if (raw == null) return undefined
+ const generation = Number(raw)
+ return Number.isSafeInteger(generation) && generation >= 0 ? generation : undefined
+ } catch (err) {
+ logger.error('[bus] getCommanderJoinGeneration failed', err, { machineId })
+ return undefined
+ }
+}
diff --git a/backend/src/lib/db/freeEntitlement.ts b/backend/src/lib/db/freeEntitlement.ts
new file mode 100644
index 000000000..b5fac533f
--- /dev/null
+++ b/backend/src/lib/db/freeEntitlement.ts
@@ -0,0 +1,58 @@
+import { prisma } from '../prisma.js'
+import { env } from '../../config/env.js'
+import { logger } from '../../utils/logger.js'
+
+/**
+ * One-time additive backfill for accounts that already activated a Free machine. Existing machines are
+ * grandfathered: we only create the lifetime claim and never suspend/delete a duplicate historical
+ * machine. A live pending account receives a reservation; abandoned pending setup rows are ignored.
+ */
+export async function backfillMachineFreeEntitlements(): Promise<void> {
+ try {
+ const freePlans = await prisma.subscriptionPlan.findMany({
+ where: {
+ authMode: 'managed',
+ campaignCode: env.HARNESS_CAMPAIGN_CODE,
+ priceUsd: 0,
+ },
+ })
+ let created = 0
+ for (const free of freePlans) {
+ const bindings = await prisma.machine.findMany({
+ where: { planId: free.id, autonomousEnv: free.autonomousEnv },
+ orderBy: { createdAt: 'asc' },
+ })
+ const firstByUser = new Map<string, typeof bindings[number]>()
+ for (const binding of bindings) {
+ const activated = binding.billingStatus !== 'pending' || !!binding.billingActivatedAt
+ // A failed checkout can leave a soft-deleted pending binding for audit. It never consumed the
+ // Free entitlement and must not prevent the account from trying Free again.
+ if (binding.deletedAt && !activated) continue
+ const current = firstByUser.get(binding.userId)
+ // Prefer any machine that reached activation over a merely pending live reservation.
+ const currentActivated = current && (current.billingStatus !== 'pending' || !!current.billingActivatedAt)
+ if (!current || (!currentActivated && activated)) firstByUser.set(binding.userId, binding)
+ }
+ for (const binding of firstByUser.values()) {
+ const claimed = binding.billingStatus !== 'pending' || !!binding.billingActivatedAt
+ try {
+ await prisma.machineFreeEntitlement.create({
+ data: {
+ userId: binding.userId,
+ autonomousEnv: free.autonomousEnv,
+ machineId: binding.machineId,
+ status: claimed ? 'claimed' : 'reserved',
+ ...(claimed ? { claimedAt: binding.billingActivatedAt ?? binding.createdAt } : {}),
+ },
+ })
+ created++
+ } catch {
+ // Unique account/environment/machine already backfilled by an earlier boot.
+ }
+ }
+ }
+ if (created) logger.info('Free machine entitlements backfilled', { created })
+ } catch (err) {
+ logger.error('Free machine entitlement backfill failed; worker will retry on next boot', err)
+ }
+}
diff --git a/backend/src/lib/db/migrate.ts b/backend/src/lib/db/migrate.ts
new file mode 100644
index 000000000..a5f125a46
--- /dev/null
+++ b/backend/src/lib/db/migrate.ts
@@ -0,0 +1,303 @@
+import { execFileSync } from 'child_process'
+import { existsSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { env } from '../../config/env.js'
+import { logger } from '../../utils/logger.js'
+import { prisma } from '../prisma.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+// src/lib/db or dist/lib/db → package root
+const root = join(__dirname, '..', '..', '..')
+
+/**
+ * Push the Prisma schema to MongoDB before serving. No migration files — `prisma db
+ * push` creates the `users` + `agent_bindings` collections + indexes; idempotent. It
+ * does NOT touch the manager-owned `agent_nodes`/`managers` collections (they aren't in
+ * this schema), so the shared DB is safe.
+ */
+export function ensureSchema(): void {
+ process.env.DATABASE_URL ??= env.DATABASE_URL
+
+ const prismaCli = join(root, 'node_modules', 'prisma', 'build', 'index.js')
+ if (!existsSync(prismaCli)) {
+ logger.warn('prisma CLI not found — skipping db push', { prismaCli })
+ return
+ }
+
+ const schema = join(root, 'prisma', 'schema.prisma')
+ try {
+ execFileSync(process.execPath, [prismaCli, 'db', 'push', '--schema', schema, '--skip-generate'], {
+ stdio: 'inherit',
+ env: process.env,
+ })
+ logger.info('Prisma db push ok (backend schema)')
+ } catch (err) {
+ logger.error('Prisma db push failed — continuing (collections may already exist)', err)
+ }
+}
+
+type MongoIndex = { name?: string; key?: Record<string, number>; unique?: boolean }
+
+async function dropLegacyUniqueIndex(collection: string, field: string): Promise<void> {
+ try {
+ const result = (await prisma.$runCommandRaw({ listIndexes: collection, cursor: {} })) as {
+ cursor?: { firstBatch?: MongoIndex[] }
+ }
+ const index = result.cursor?.firstBatch?.find((candidate) =>
+ candidate.unique === true &&
+ candidate.key != null &&
+ Object.keys(candidate.key).length === 1 &&
+ candidate.key[field] === 1)
+ if (!index?.name) return
+ await prisma.$runCommandRaw({ dropIndexes: collection, index: index.name })
+ logger.info('legacy environment-global unique index removed', { collection, index: index.name })
+ } catch (err) {
+ // NamespaceNotFound is expected on a cold database. Any real failure will also be retried on the
+ // next worker boot, while ensureSchema logs whether the replacement indexes could be installed.
+ logger.warn('legacy unique index cleanup skipped', { collection, field, error: String(err) })
+ }
+}
+
+/**
+ * Prepare the environment split before Prisma installs the new compound indexes. All rows that
+ * predate the split belong to the formerly process-global staging plane. New rows are unaffected:
+ * User defaults to prod and every dependent row copies its user/machine environment explicitly.
+ */
+export async function migrateAutonomousEnvironment(): Promise<void> {
+ // This is deliberately not configurable: every row that predates the split was created while
+ // staging was process-global. Runtime defaults are production only for records created later.
+ const autonomousEnv = 'stag'
+ const collections = [
+ 'users',
+ 'machines',
+ 'subscription_plans',
+ 'machine_checkout_attempts',
+ 'machine_free_entitlements',
+ ]
+ for (const collection of collections) {
+ try {
+ const result = (await prisma.$runCommandRaw({
+ update: collection,
+ updates: [{
+ q: { autonomousEnv: { $exists: false } },
+ u: { $set: { autonomousEnv } },
+ multi: true,
+ }],
+ })) as { nModified?: number }
+ if (result.nModified) {
+ logger.info('Autonomous environment backfilled', { collection, autonomousEnv, modified: result.nModified })
+ }
+ } catch (err) {
+ logger.warn('Autonomous environment backfill skipped', { collection, error: String(err) })
+ }
+ }
+
+ // The old global constraints prevent storing the same plan name/free entitlement in both planes.
+ // Drop only those exact single-field unique indexes; Prisma recreates the compound replacements.
+ await dropLegacyUniqueIndex('subscription_plans', 'name')
+ await dropLegacyUniqueIndex('machine_free_entitlements', 'userId')
+}
+
+const PENDING_EMAIL_SUFFIX = '@pending.harness.invalid'
+
+function migrationEmail(email: string, externalId: string): string {
+ const normalized = email.trim().toLowerCase()
+ return normalized || `device-${externalId.trim().toLowerCase()}${PENDING_EMAIL_SUFFIX}`
+}
+
+/**
+ * One-time identity split, before db push installs the unique email index:
+ * - normalized email becomes the SSO identity;
+ * - the old subject is moved to stagExternalId for staging users;
+ * - externalId remains the unique production/device subject slot.
+ */
+export async function migrateUserIdentityByEmail(): Promise<void> {
+ const users = await prisma.user.findMany({
+ select: {
+ id: true,
+ email: true,
+ externalId: true,
+ stagExternalId: true,
+ autonomousEnv: true,
+ },
+ })
+
+ const owners = new Map<string, string>()
+ const prepared = users.map((user) => {
+ const email = migrationEmail(user.email, user.externalId)
+ const duplicate = owners.get(email)
+ if (duplicate && duplicate !== user.id) {
+ throw new Error(`Cannot migrate users to email identity: duplicate normalized email ${email}`)
+ }
+ owners.set(email, user.id)
+ const staging = user.autonomousEnv === 'stag'
+ return {
+ user,
+ email,
+ externalId: staging && !user.stagExternalId ? `local-prod-${user.id}` : user.externalId,
+ stagExternalId: staging ? (user.stagExternalId || user.externalId) : user.stagExternalId,
+ }
+ })
+
+ for (const next of prepared) {
+ const data = {
+ ...(next.user.email !== next.email ? { email: next.email } : {}),
+ ...(next.user.externalId !== next.externalId ? { externalId: next.externalId } : {}),
+ ...(next.user.stagExternalId !== next.stagExternalId
+ ? { stagExternalId: next.stagExternalId }
+ : {}),
+ }
+ if (Object.keys(data).length) {
+ await prisma.user.update({ where: { id: next.user.id }, data })
+ }
+ }
+
+ if (prepared.length) {
+ logger.info('user email identity migration complete', { users: prepared.length })
+ }
+}
+
+/**
+ * One-time (idempotent) backfill: legacy `machines` rows created before `authMode` was
+ * denormalized get it stamped from their plan (no-planId rows → 'self'). Runs at boot on the
+ * pushing instance, after ensureSchema/ensurePlans and BEFORE the server accepts connections, so
+ * every read site can rely on `binding.authMode` alone (the plan is never consulted for authMode).
+ * Raw `$exists: false` is required — Prisma-Mongo `where: { authMode: null }` does NOT match
+ * documents where the field is absent.
+ */
+export async function backfillMachineAuthMode(): Promise<void> {
+ try {
+ const plans = await prisma.subscriptionPlan.findMany()
+ const updates = plans.map((p) => ({
+ q: { planId: p.id, authMode: { $exists: false } },
+ u: { $set: { authMode: p.authMode } },
+ multi: true,
+ }))
+ // Catch-all last: anything still missing (no/unknown planId) defaults to 'self'.
+ updates.push({ q: { authMode: { $exists: false } } as never, u: { $set: { authMode: 'self' } }, multi: true })
+ const res = (await prisma.$runCommandRaw({ update: 'machines', updates })) as { nModified?: number }
+ if (res.nModified) logger.info('machines authMode backfilled', { modified: res.nModified })
+ } catch (err) {
+ logger.error('authMode backfill failed — continuing (legacy rows read as self until next boot)', err)
+ }
+}
+
+/**
+ * Drop every device row that predates computer-backed devices, and the pairing-code collection with it.
+ *
+ * `/api/device-ws` is SSO-only now: a row is resolved from `userId + autonomousEnv + computerId`, and the
+ * device token that authenticated the old rows is not accepted anywhere. Nothing can ever connect as one
+ * of them again, but left in place they would show forever in `GET /api/devices` and in the mobile
+ * overview as permanently-offline devices the user cannot explain or get rid of.
+ *
+ * Raw `$exists: false` is required — Prisma-Mongo `where: { computerId: null }` does NOT match documents
+ * where the field is absent, which is exactly the shape every legacy row has.
+ */
+export async function pruneLegacyDeviceBindings(): Promise<void> {
+ try {
+ const res = (await prisma.$runCommandRaw({
+ delete: 'device_bindings',
+ deletes: [{ q: { computerId: { $exists: false } }, limit: 0 }],
+ } as never)) as { n?: number }
+ if (res.n) logger.info('legacy device bindings pruned', { deleted: res.n })
+ // `db push` drops the model's indexes but leaves the collection itself behind.
+ await prisma.$runCommandRaw({ drop: 'pairing_codes' } as never).catch(() => {})
+ } catch (err) {
+ logger.error('legacy device binding prune failed — continuing (stale rows read as offline devices)', err)
+ }
+}
+
+// ── Machine rename migration (one-time, idempotent) ────────────────────────────────────────────────
+// The entity formerly called a "harness" is now a MACHINE. Renamed collections are COPIED (the old
+// ones are kept as the rollback and cleaned up by hand later); collections that keep their name get
+// an in-place field rename.
+//
+// Idempotency is a MARKER, deliberately not "is the target populated?" — the HTTP server is a
+// cluster that boots independently of this worker, so it can write one fresh row into `machines`
+// before the migration runs. A populated-target guard would then read that as "already migrated" and
+// silently strand every legacy row. `$merge` matches on `_id`, so a concurrent new row is harmless.
+
+type FieldRenames = Record<string, string>
+
+async function count(coll: string, query: Record<string, unknown> = {}): Promise<number> {
+ const r = (await prisma.$runCommandRaw({ count: coll, query } as never)) as { n?: number }
+ return r.n ?? 0
+}
+
+/** Has this migration id already been applied? Missing `migrations` collection reads as "no". */
+async function migrationApplied(id: string): Promise<boolean> {
+ return (await count('migrations', { _id: id })) > 0
+}
+
+async function markMigrationApplied(id: string): Promise<void> {
+ await prisma.$runCommandRaw({
+ insert: 'migrations',
+ documents: [{ _id: id, appliedAt: new Date().toISOString() }],
+ } as never)
+}
+
+/** Copy `from` → `into`, applying `renames`. `$merge` (not `$out`) so the indexes `db push` just
+ * created survive — `$out` drops and recreates the namespace. `whenMatched:'fail'` turns a partial
+ * re-run into a loud error instead of silent duplication. */
+async function copyRenamed(from: string, into: string, renames: FieldRenames): Promise<void> {
+ const n = await count(from)
+ if (n === 0) { logger.info('machine-rename: skip (source empty)', { from }); return }
+ const added: Record<string, string> = {}
+ for (const [oldName, newName] of Object.entries(renames)) added[newName] = `$${oldName}`
+ const pipeline: Record<string, unknown>[] = [
+ { $addFields: added },
+ { $unset: Object.keys(renames) },
+ { $merge: { into, whenMatched: 'fail' } },
+ ]
+ await prisma.$runCommandRaw({ aggregate: from, pipeline, cursor: {} } as never)
+ logger.info('machine-rename: copied', { from, into, docs: n })
+}
+
+/** In-place field rename for a collection that keeps its name. One update per pair, each guarded on
+ * "old present AND new absent" so a re-run is a no-op and a half-applied run resumes. */
+async function renameFieldsInPlace(coll: string, renames: FieldRenames): Promise<void> {
+ let modified = 0
+ for (const [oldName, newName] of Object.entries(renames)) {
+ const res = (await prisma.$runCommandRaw({
+ update: coll,
+ updates: [{
+ q: { [oldName]: { $exists: true }, [newName]: { $exists: false } },
+ u: { $rename: { [oldName]: newName } },
+ multi: true,
+ }],
+ } as never)) as { nModified?: number }
+ modified += res.nModified ?? 0
+ }
+ if (modified) logger.info('machine-rename: fields renamed in place', { coll, modified })
+}
+
+const MACHINE_RENAME_ID = 'machine-rename-v1'
+
+/** Run AFTER ensureSchema (db push created the new collections + their indexes), before serving. */
+export async function migrateMachineRename(): Promise<void> {
+ try {
+ if (await migrationApplied(MACHINE_RENAME_ID)) return
+
+ const idOnly: FieldRenames = { harnessId: 'machineId' }
+ await copyRenamed('harness_bindings', 'machines', { harnessId: 'machineId', machineName: 'name' })
+ await copyRenamed('harness_agents', 'machine_agents', idOnly)
+ await copyRenamed('harness_free_entitlements', 'machine_free_entitlements', idOnly)
+ await copyRenamed('harness_voice_daily_usage', 'machine_voice_daily_usage', idOnly)
+ await copyRenamed('harness_voice_reservations', 'machine_voice_reservations', idOnly)
+ await copyRenamed('harness_checkout_attempts', 'machine_checkout_attempts', idOnly)
+
+ await renameFieldsInPlace('device_bindings', { harnessId: 'machineId', activeHarnessId: 'activeMachineId' })
+ await renameFieldsInPlace('subdomains', idOnly)
+ await renameFieldsInPlace('subscription_plans', { maxProjects: 'maxAgents' })
+
+ // `harness_join_codes` is deliberately left alone — its model was deleted, and the collection is
+ // the rollback copy. `Machine.hostname` is deliberately NOT backfilled: it is the connecting
+ // computer's hostname and self-heals on the next adapter connect.
+ await markMigrationApplied(MACHINE_RENAME_ID)
+ logger.info('machine-rename: complete')
+ } catch (err) {
+ // Not marked → the next boot retries. Leaving the legacy collections in place is the rollback.
+ logger.error('machine-rename migration failed — continuing (legacy data stays in harness_* collections)', err)
+ }
+}
diff --git a/backend/src/lib/db/seed.test.ts b/backend/src/lib/db/seed.test.ts
new file mode 100644
index 000000000..10b479b0b
--- /dev/null
+++ b/backend/src/lib/db/seed.test.ts
@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const planDb = vi.hoisted(() => ({
+ upsert: vi.fn(),
+ findMany: vi.fn(),
+ updateMany: vi.fn(),
+ update: vi.fn(),
+}))
+const fetchPlans = vi.hoisted(() => vi.fn())
+
+vi.mock('../../config/env.js', () => ({
+ env: {
+ HARNESS_BILLING_ENABLED: true,
+ HARNESS_CAMPAIGN_CODE: 'ai-harness-device',
+ AUTONOMOUS_BFF_URL: 'https://apiv2.autonomous.ai',
+ },
+}))
+vi.mock('../autonomousBff.js', () => ({ fetchCampaignPlans: fetchPlans }))
+vi.mock('../prisma.js', () => ({ prisma: { subscriptionPlan: planDb } }))
+vi.mock('../../utils/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn() } }))
+
+import { ensurePlansForEnvironment } from './seed.js'
+
+describe('campaign catalog cache isolation', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ planDb.upsert.mockResolvedValue({})
+ planDb.updateMany.mockResolvedValue({ count: 0 })
+ planDb.update.mockResolvedValue({})
+ fetchPlans.mockResolvedValue([])
+ })
+
+ it('hides staging cached plans when the production catalog cannot be refreshed', async () => {
+ planDb.findMany.mockResolvedValue([
+ { name: 'Free', available: true, externalPlanId: 37, campaignCode: 'ai-harness-device', catalogSource: 'https://apiv2.staging.autonomousdev.xyz' },
+ { name: 'Pro', available: true, externalPlanId: 38, campaignCode: 'ai-harness-device', catalogSource: 'https://apiv2.staging.autonomousdev.xyz' },
+ { name: 'Max', available: true, externalPlanId: 39, campaignCode: 'ai-harness-device', catalogSource: 'https://apiv2.staging.autonomousdev.xyz' },
+ { name: 'Remote', available: true, externalPlanId: 40, campaignCode: 'ai-harness-device', catalogSource: 'https://apiv2.staging.autonomousdev.xyz' },
+ { name: 'Provider', available: true, externalPlanId: 45, campaignCode: 'ai-harness-device', catalogSource: 'https://apiv2.staging.autonomousdev.xyz' },
+ ])
+
+ await ensurePlansForEnvironment('prod')
+
+ expect(planDb.updateMany).toHaveBeenCalledWith({
+ where: { autonomousEnv: 'prod', name: { in: ['Free', 'Pro', 'Max', 'Remote', 'Provider'] } },
+ data: { available: false, isDefault: false },
+ })
+ expect(planDb.update).not.toHaveBeenCalled()
+ })
+
+ /** The live catalog, verified 2026-08-04: five tiers, Provider at $10/month (prod plan_id 45). */
+ const FULL_CATALOG = [
+ { code: 'free', id: 41, amount: 0, currency: 'USD', name: 'Free', metadata: {} },
+ { code: 'pro', id: 42, amount: 20, currency: 'USD', name: 'Pro', metadata: {} },
+ { code: 'max', id: 43, amount: 100, currency: 'USD', name: 'Max', metadata: {} },
+ { code: 'remote', id: 44, amount: 10, currency: 'USD', name: 'Remote', metadata: {} },
+ { code: 'provider', id: 45, amount: 10, currency: 'USD', name: 'Provider', metadata: {} },
+ ]
+
+ it('synchronizes Remote only when the same environment returns the complete catalog', async () => {
+ fetchPlans.mockResolvedValue(FULL_CATALOG)
+
+ await ensurePlansForEnvironment('prod')
+
+ expect(planDb.upsert).toHaveBeenCalledWith(expect.objectContaining({
+ where: { autonomousEnv_name: { autonomousEnv: 'prod', name: 'Remote' } },
+ update: expect.objectContaining({
+ authMode: 'remote',
+ priceUsd: 10,
+ dailyVoiceLimitSeconds: 3600,
+ externalPlanId: 44,
+ available: true,
+ }),
+ }))
+ expect(planDb.update).toHaveBeenCalledWith({
+ where: { autonomousEnv_name: { autonomousEnv: 'prod', name: 'Free' } },
+ data: { isDefault: true },
+ })
+ })
+
+ it('synchronizes Provider with its upstream plan id', async () => {
+ fetchPlans.mockResolvedValue(FULL_CATALOG)
+
+ await ensurePlansForEnvironment('prod')
+
+ expect(planDb.upsert).toHaveBeenCalledWith(expect.objectContaining({
+ where: { autonomousEnv_name: { autonomousEnv: 'prod', name: 'Provider' } },
+ update: expect.objectContaining({ authMode: 'provider', priceUsd: 10, externalPlanId: 45, available: true }),
+ }))
+ })
+
+ it('refuses the WHOLE catalog when one tier price disagrees with upstream', async () => {
+ // The trap this guards: `completeCatalog` validates every tier's price, so a local price that
+ // drifts from upstream does not disable one plan — it silently takes Free/Pro/Max/Remote down
+ // with it, falling back to cache or hiding everything.
+ fetchPlans.mockResolvedValue(FULL_CATALOG.map((p) => (p.code === 'provider' ? { ...p, amount: 20 } : p)))
+ planDb.findMany.mockResolvedValue([]) // no cache, so the hide path runs
+
+ await ensurePlansForEnvironment('prod')
+
+ expect(planDb.upsert).not.toHaveBeenCalledWith(expect.objectContaining({
+ where: { autonomousEnv_name: { autonomousEnv: 'prod', name: 'Remote' } },
+ update: expect.objectContaining({ available: true }),
+ }))
+ expect(planDb.updateMany).toHaveBeenCalledWith({
+ where: { autonomousEnv: 'prod', name: { in: ['Free', 'Pro', 'Max', 'Remote', 'Provider'] } },
+ data: { available: false, isDefault: false },
+ })
+ })
+})
diff --git a/backend/src/lib/db/seed.ts b/backend/src/lib/db/seed.ts
new file mode 100644
index 000000000..1e72caa41
--- /dev/null
+++ b/backend/src/lib/db/seed.ts
@@ -0,0 +1,218 @@
+import type { Prisma } from '@prisma/client'
+import { env } from '../../config/env.js'
+import {
+ autonomousEnvironmentConfig,
+ autonomousEnvironments,
+ type AutonomousEnvironment,
+} from '../autonomousEnvironment.js'
+import { fetchCampaignPlans, type CampaignPlan } from '../autonomousBff.js'
+import { prisma } from '../prisma.js'
+import { logger } from '../../utils/logger.js'
+
+const LEGACY_TIERS = [
+ { name: 'Self-Auth', authMode: 'self', priceUsd: 10 },
+ { name: 'Managed', authMode: 'managed', priceUsd: 30 },
+] as const
+
+const CAMPAIGN_TIERS = {
+ free: { name: 'Free', cpus: '1', memory: '1g', maxAgents: 3, priceUsd: 0, dailyVoiceLimitSeconds: 10 * 60, authMode: 'managed', isDefault: true },
+ pro: { name: 'Pro', cpus: '1', memory: '2g', maxAgents: 10, priceUsd: 20, dailyVoiceLimitSeconds: 30 * 60, authMode: 'managed', isDefault: false },
+ max: { name: 'Max', cpus: '2', memory: '4g', maxAgents: 50, priceUsd: 100, dailyVoiceLimitSeconds: 0, authMode: 'managed', isDefault: false },
+ remote: { name: 'Remote', cpus: '1', memory: '2g', maxAgents: 1, priceUsd: 10, dailyVoiceLimitSeconds: 60 * 60, authMode: 'remote', isDefault: false },
+ // A provider machine runs NO container of ours — the model and the machine are the third party's.
+ // cpus/memory/maxAgents are therefore inert rather than plausible-looking lies: projects come
+ // from the provider's own agent list, so a local cap would mean nothing.
+ //
+ // ⚠ priceUsd MUST equal the upstream amount. `completeCatalog` below validates every tier's price
+ // against the campaign catalog and returns undefined on ANY mismatch — which falls back to the
+ // cached catalog, or hides EVERY campaign plan when there is no cache. A wrong number here breaks
+ // Free/Pro/Max/Remote too, not just this row. Upstream: $10/month (prod plan_id 45, staging 41).
+ provider: { name: 'Provider', cpus: '0', memory: '0', maxAgents: 0, priceUsd: 10, dailyVoiceLimitSeconds: 60 * 60, authMode: 'provider', isDefault: false },
+} as const
+
+function planKey(autonomousEnv: AutonomousEnvironment, name: string) {
+ return { autonomousEnv_name: { autonomousEnv, name } }
+}
+
+function catalogSource(autonomousEnv: AutonomousEnvironment): string {
+ return new URL(autonomousEnvironmentConfig(autonomousEnv).bffUrl).origin
+}
+
+async function seedLocalPlans(autonomousEnv: AutonomousEnvironment): Promise<void> {
+ for (const tier of LEGACY_TIERS) {
+ await prisma.subscriptionPlan.upsert({
+ where: planKey(autonomousEnv, tier.name),
+ update: { authMode: tier.authMode, dailyVoiceLimitSeconds: 0, isDefault: false, available: false },
+ create: {
+ ...tier,
+ autonomousEnv,
+ cpus: '1', memory: '2g', maxAgents: 1,
+ authMode: tier.authMode, dailyVoiceLimitSeconds: 0, isDefault: false, available: false,
+ },
+ })
+ }
+ // Seed backend-owned resource/voice policy independently of the upstream catalog. Do not overwrite
+ // availability or external ids on an existing row: a same-environment cache stays usable while the
+ // provider is temporarily unavailable.
+ for (const tier of Object.values(CAMPAIGN_TIERS)) {
+ await prisma.subscriptionPlan.upsert({
+ where: planKey(autonomousEnv, tier.name),
+ update: {
+ cpus: tier.cpus,
+ memory: tier.memory,
+ maxAgents: tier.maxAgents,
+ priceUsd: tier.priceUsd,
+ authMode: tier.authMode,
+ dailyVoiceLimitSeconds: tier.dailyVoiceLimitSeconds,
+ },
+ create: {
+ ...tier,
+ autonomousEnv,
+ available: false,
+ isDefault: false,
+ },
+ })
+ }
+}
+
+function completeCatalog(plans: CampaignPlan[]): Map<keyof typeof CAMPAIGN_TIERS, CampaignPlan> | undefined {
+ const out = new Map<keyof typeof CAMPAIGN_TIERS, CampaignPlan>()
+ for (const plan of plans) out.set(plan.code, plan)
+ const valid = (Object.entries(CAMPAIGN_TIERS) as Array<[keyof typeof CAMPAIGN_TIERS, typeof CAMPAIGN_TIERS[keyof typeof CAMPAIGN_TIERS]]>)
+ .every(([code, expected]) => out.get(code)?.amount === expected.priceUsd && out.get(code)?.currency === 'USD')
+ return out.size === Object.keys(CAMPAIGN_TIERS).length && valid ? out : undefined
+}
+
+async function hasCachedCatalog(autonomousEnv: AutonomousEnvironment): Promise<boolean> {
+ const source = catalogSource(autonomousEnv)
+ const rows = await prisma.subscriptionPlan.findMany({
+ where: {
+ autonomousEnv,
+ name: { in: Object.values(CAMPAIGN_TIERS).map((x) => x.name) },
+ },
+ select: {
+ name: true,
+ priceUsd: true,
+ authMode: true,
+ available: true,
+ externalPlanId: true,
+ campaignCode: true,
+ catalogSource: true,
+ },
+ })
+ return rows.length === Object.keys(CAMPAIGN_TIERS).length && rows.every((plan) => {
+ const expected = Object.values(CAMPAIGN_TIERS).find((tier) => tier.name === plan.name)
+ return !!expected &&
+ plan.priceUsd === expected.priceUsd &&
+ plan.authMode === expected.authMode &&
+ plan.available === true &&
+ !!plan.externalPlanId &&
+ plan.campaignCode === env.HARNESS_CAMPAIGN_CODE &&
+ plan.catalogSource === source
+ })
+}
+
+async function exposeRollbackRemote(autonomousEnv: AutonomousEnvironment): Promise<void> {
+ await prisma.subscriptionPlan.updateMany({
+ where: {
+ autonomousEnv,
+ name: { in: Object.values(CAMPAIGN_TIERS).map((x) => x.name) },
+ },
+ data: { available: false, isDefault: false },
+ })
+ await prisma.subscriptionPlan.update({
+ where: planKey(autonomousEnv, 'Remote'),
+ data: { priceUsd: 0, available: true, isDefault: true },
+ })
+}
+
+async function hideCampaignPlans(autonomousEnv: AutonomousEnvironment): Promise<void> {
+ await prisma.subscriptionPlan.updateMany({
+ where: {
+ autonomousEnv,
+ name: { in: Object.values(CAMPAIGN_TIERS).map((x) => x.name) },
+ },
+ data: { available: false, isDefault: false },
+ })
+}
+
+/** Synchronize one upstream catalog without ever reading/writing the other environment's rows. */
+export async function ensurePlansForEnvironment(autonomousEnv: AutonomousEnvironment): Promise<void> {
+ try {
+ await seedLocalPlans(autonomousEnv)
+ if (!env.HARNESS_BILLING_ENABLED) {
+ await exposeRollbackRemote(autonomousEnv)
+ logger.info('machine billing disabled; only Remote is available', { autonomousEnv })
+ return
+ }
+
+ let catalog: Map<keyof typeof CAMPAIGN_TIERS, CampaignPlan> | undefined
+ try {
+ catalog = completeCatalog(await fetchCampaignPlans(autonomousEnv))
+ } catch (err) {
+ logger.warn('campaign plan sync failed; retaining cached catalog', {
+ autonomousEnv,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ }
+ if (!catalog) {
+ if (!(await hasCachedCatalog(autonomousEnv))) await hideCampaignPlans(autonomousEnv)
+ return
+ }
+
+ const source = catalogSource(autonomousEnv)
+ const syncedAt = new Date()
+ for (const [code, local] of Object.entries(CAMPAIGN_TIERS) as Array<[keyof typeof CAMPAIGN_TIERS, typeof CAMPAIGN_TIERS[keyof typeof CAMPAIGN_TIERS]]>) {
+ const external = catalog.get(code)!
+ await prisma.subscriptionPlan.upsert({
+ where: planKey(autonomousEnv, local.name),
+ update: {
+ cpus: local.cpus, memory: local.memory, maxAgents: local.maxAgents,
+ priceUsd: external.amount, dailyVoiceLimitSeconds: local.dailyVoiceLimitSeconds,
+ authMode: local.authMode, available: true,
+ externalPlanId: external.id, externalPlanName: external.name,
+ campaignCode: env.HARNESS_CAMPAIGN_CODE, catalogSource: source,
+ externalMetadata: external.metadata as Prisma.InputJsonValue,
+ catalogSyncedAt: syncedAt, isDefault: false,
+ },
+ create: {
+ autonomousEnv,
+ name: local.name, cpus: local.cpus, memory: local.memory,
+ maxAgents: local.maxAgents, priceUsd: external.amount,
+ dailyVoiceLimitSeconds: local.dailyVoiceLimitSeconds,
+ authMode: local.authMode, available: true, externalPlanId: external.id,
+ externalPlanName: external.name, campaignCode: env.HARNESS_CAMPAIGN_CODE,
+ catalogSource: source,
+ externalMetadata: external.metadata as Prisma.InputJsonValue,
+ catalogSyncedAt: syncedAt, isDefault: false,
+ },
+ })
+ }
+ await prisma.subscriptionPlan.updateMany({
+ where: { autonomousEnv, isDefault: true },
+ data: { isDefault: false },
+ })
+ await prisma.subscriptionPlan.update({
+ where: planKey(autonomousEnv, CAMPAIGN_TIERS.free.name),
+ data: { isDefault: true },
+ })
+ logger.info('campaign subscription plans synchronized', {
+ autonomousEnv,
+ campaignCode: env.HARNESS_CAMPAIGN_CODE,
+ catalogSource: source,
+ plans: [...catalog.values()].map((plan) => ({ code: plan.code, id: plan.id, amount: plan.amount })),
+ })
+ } catch (err) {
+ logger.warn('ensurePlansForEnvironment failed (continuing)', {
+ autonomousEnv,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ }
+}
+
+/** Worker startup refreshes both independent upstream catalogs. */
+export async function ensurePlans(): Promise<void> {
+ for (const autonomousEnv of autonomousEnvironments) {
+ await ensurePlansForEnvironment(autonomousEnv)
+ }
+}
diff --git a/backend/src/lib/deepgram.ts b/backend/src/lib/deepgram.ts
new file mode 100644
index 000000000..f882aee2f
--- /dev/null
+++ b/backend/src/lib/deepgram.ts
@@ -0,0 +1,65 @@
+import { env } from '../config/env.js'
+import { logger } from '../utils/logger.js'
+
+// Deepgram pre-recorded (batch) STT. We buffer the device's streamed PCM and send it as one
+// request here. Audio is raw linear16 (16-bit LE) mono at 16 kHz — declared via query params.
+// - nova-3: latest model. Every language below is on its supported list, so one model covers them all.
+// - language: pinned to the speaker's language (chosen in the device Settings, sent per utterance) —
+// pinning is more accurate on short clips than auto-detect.
+// - smart_format=false: keep it verbatim — smart_format rewrites numbers/dates and would mangle
+// spoken commands; we still punctuate for readability.
+// Unlike Gemini, this is a dedicated ASR: it returns an empty transcript on silence instead of
+// hallucinating a sentence.
+// The languages the device's Settings > Voice picker offers, and the ONE place that list lives —
+// `stt.ts` re-exports it and `deviceWs.ts` gates the inbound `voice_start` on it, so a language can
+// never be offered on the device but silently rewritten here. Adding one is this line plus the
+// firmware's LANGS table.
+//
+// An unrecognised code is coerced rather than passed through: Deepgram answers an unsupported
+// `language` with a 400, which would lose the whole utterance instead of transcribing it imperfectly.
+export const VOICE_LANGS = ['en', 'vi', 'es', 'fr', 'ja', 'it'] as const
+export type VoiceLang = (typeof VOICE_LANGS)[number]
+const ALLOWED_LANGS = new Set<string>(VOICE_LANGS)
+/** Coerce anything to a supported code. Unknown/absent → 'en', matching the device's factory default. */
+export function normalizeLang(lang: unknown): VoiceLang {
+ return typeof lang === 'string' && ALLOWED_LANGS.has(lang) ? (lang as VoiceLang) : 'en'
+}
+const dgUrl = (sampleRate: number, lang: string) =>
+ `https://api.deepgram.com/v1/listen?model=nova-3&language=${lang}&punctuate=true&smart_format=false&encoding=linear16&sample_rate=${sampleRate}&channels=1`
+
+/** Transcribe raw linear16/mono PCM at `sampleRate` Hz in `lang` (see VOICE_LANGS). Returns '' if empty. */
+export async function transcribe(pcm: Buffer, sampleRate = 16000, lang = 'en'): Promise<string> {
+ if (!env.DEEPGRAM_API_KEY) throw new Error('DEEPGRAM_API_KEY not set')
+ const language = normalizeLang(lang)
+ const res = await fetch(dgUrl(sampleRate, language), {
+ method: 'POST',
+ headers: {
+ Authorization: `Token ${env.DEEPGRAM_API_KEY}`,
+ 'Content-Type': 'application/octet-stream',
+ },
+ body: pcm,
+ })
+ if (!res.ok) {
+ const body = await res.text().catch(() => '')
+ throw new Error(`Deepgram HTTP ${res.status}: ${body.slice(0, 200)}`)
+ }
+ const data = (await res.json()) as {
+ results?: {
+ channels?: Array<{
+ detected_language?: string
+ language_confidence?: number
+ alternatives?: Array<{ transcript?: string; confidence?: number }>
+ }>
+ }
+ }
+ const channel = data.results?.channels?.[0]
+ const alt = channel?.alternatives?.[0]
+ const transcript = (alt?.transcript ?? '').trim()
+ logger.info('deepgram transcript', {
+ chars: transcript.length,
+ lang: channel?.detected_language,
+ langConf: channel?.language_confidence,
+ conf: alt?.confidence,
+ })
+ return transcript
+}
diff --git a/backend/src/lib/deepgramWav.ts b/backend/src/lib/deepgramWav.ts
new file mode 100644
index 000000000..350b2be4e
--- /dev/null
+++ b/backend/src/lib/deepgramWav.ts
@@ -0,0 +1,55 @@
+// Transcribing a WAV upload with Deepgram — the one path every voice surface shares.
+//
+// Lifted out of routes/cursor.ts so the dial's own endpoint (routes/voice.ts) cannot end up with a second
+// copy of a decision that was MEASURED rather than chosen. The model-per-language map below cost a real
+// afternoon to establish; two copies of it is how one of them silently stops matching.
+import { env } from '../config/env.js'
+
+/**
+ * A TWIN of VOICE_LANGS in lib/deepgram.ts, copied rather than imported.
+ *
+ * That module opens a network connection and owns the device's voice path; importing it here would put
+ * this file's blast radius back onto the path it was written to stay clear of. Six short strings are a
+ * cheaper price than that coupling — but they ARE a twin, so a language added there belongs here too.
+ */
+export const VOICE_WAV_LANGS = new Set(['en', 'vi', 'es', 'fr', 'ja', 'it'])
+
+/** The language the audio is in, or `en` when the caller named one this path does not serve. */
+export function pickWavLang(raw: unknown): string {
+ const lang = typeof raw === 'string' ? raw.trim().toLowerCase() : ''
+ return VOICE_WAV_LANGS.has(lang) ? lang : 'en'
+}
+
+/**
+ * Deepgram, called directly rather than through lib/deepgram.ts, because that module's `transcribe()`
+ * declares `encoding=linear16&sample_rate=…&channels=1` — a headerless PCM stream, which is exactly what
+ * a WAV is not. A WAV opens with a 44-byte RIFF header and states its own rate; declaring those params
+ * would feed the header in as audio and pin the wrong sample rate.
+ *
+ * So the query carries no encoding hints at all and the file goes up under its real Content-Type. Deepgram
+ * reads the container and honours whatever rate and channel count the app actually recorded at.
+ */
+export async function transcribeWavWithDeepgram(audio: Buffer, contentType: string, lang: string): Promise<string> {
+ if (!env.DEEPGRAM_API_KEY) throw new Error('DEEPGRAM_API_KEY not set')
+ // Model per language, and this is measured, not assumed. On a real 5s Vietnamese WAV, nova-3 with
+ // `language=vi` returns an EMPTY transcript — no error, confidence 0.0, correct duration in the
+ // metadata, just nothing. nova-2 transcribes the same file almost perfectly. nova-3 does handle `en`
+ // (verified on an English WAV), so it stays for English, where it is the better model.
+ // `language=multi` on nova-3 was also tried and came back as garbled cross-script noise.
+ const model = lang === 'vi' ? 'nova-2' : 'nova-3'
+ const url = `https://api.deepgram.com/v1/listen?model=${model}&language=${lang}&punctuate=true&smart_format=false`
+ const res = await fetch(url, {
+ method: 'POST',
+ headers: { Authorization: `Token ${env.DEEPGRAM_API_KEY}`, 'Content-Type': contentType },
+ body: new Uint8Array(audio),
+ })
+ if (!res.ok) {
+ const detail = await res.text().catch(() => '')
+ throw new Error(`Deepgram HTTP ${res.status}: ${detail.slice(0, 200)}`)
+ }
+ const data = (await res.json()) as {
+ results?: { channels?: Array<{ alternatives?: Array<{ transcript?: string; confidence?: number }> }> }
+ }
+ const alt = data.results?.channels?.[0]?.alternatives?.[0]
+ return (alt?.transcript ?? '').trim()
+}
diff --git a/backend/src/lib/deviceAuth.ts b/backend/src/lib/deviceAuth.ts
new file mode 100644
index 000000000..480a78dbd
--- /dev/null
+++ b/backend/src/lib/deviceAuth.ts
@@ -0,0 +1,154 @@
+import { randomBytes, createHash } from 'crypto'
+import { pub } from './bus.js'
+import { logger } from '../utils/logger.js'
+
+/**
+ * Device-authorization grant (RFC 8628-shaped) for the `harness` CLI and the desktop app.
+ *
+ * Neither can do a browser OAuth redirect: `/api/auth/authorize` pins `redirect_uri` to the WEB
+ * callback page, and registering a native/loopback redirect with the SSO client is not something this
+ * repo controls. So instead of inventing a second auth path, the client never sees a credential of the
+ * user's at all — it shows a short code, the user approves it in a browser where they are ALREADY
+ * signed in, and the client polls until a machine key comes back.
+ *
+ * What the client receives is a machine apiKey, not an SSO token: it is a machine, and that is the only
+ * credential a machine ever needs. Nothing user-scoped is minted for it.
+ *
+ * Redis, not Mongo: every record here is dead within ten minutes and a crashed worker losing one costs
+ * the user a retry, not data.
+ */
+
+const TTL_SEC = 600 // 10 minutes to walk to a browser and type six characters
+const POLL_MIN_INTERVAL_SEC = 2
+
+// Crockford base32 minus I/L/O/U — same alphabet the device pairing code uses, for the same reason:
+// these get read off one screen and typed into another.
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+
+export type DeviceAuthState = 'pending' | 'approved' | 'denied'
+
+export interface DeviceAuthRecord {
+ state: DeviceAuthState
+ computerId: string
+ label: string
+ /** Set once approved: the machine the user chose for this computer. */
+ machineId?: string
+ apiKey?: string
+ userId?: string
+ error?: string
+}
+
+const codeKey = (userCode: string): string => `devauth:code:${userCode}`
+const deviceKey = (deviceHash: string): string => `devauth:dev:${deviceHash}`
+const claimKey = (deviceHash: string): string => `devauth:claim:${deviceHash}`
+
+/** The device code is a bearer secret, so only its hash is stored — a Redis dump must not be a key store. */
+const hash = (s: string): string => createHash('sha256').update(s).digest('hex')
+
+function newUserCode(): string {
+ const b = randomBytes(6)
+ return Array.from(b, (x) => ALPHABET[x % ALPHABET.length]).join('')
+}
+
+export interface StartResult {
+ deviceCode: string
+ userCode: string
+ expiresInSec: number
+ intervalSec: number
+}
+
+export async function startDeviceAuth(computerId: string, label: string): Promise<StartResult> {
+ const deviceCode = randomBytes(32).toString('hex')
+ // One retry on collision; the space is 32^6 and records live ten minutes, so a second clash is noise.
+ let userCode = newUserCode()
+ if (await pub.exists(codeKey(userCode))) userCode = newUserCode()
+
+ const record: DeviceAuthRecord = { state: 'pending', computerId, label }
+ const payload = JSON.stringify(record)
+ await pub.set(deviceKey(hash(deviceCode)), payload, 'EX', TTL_SEC)
+ // The user-facing code maps to the device record, so approving by code can find it.
+ await pub.set(codeKey(userCode), hash(deviceCode), 'EX', TTL_SEC)
+ return { deviceCode, userCode, expiresInSec: TTL_SEC, intervalSec: POLL_MIN_INTERVAL_SEC }
+}
+
+/** Look up a pending request by the code the human typed. */
+export async function findByUserCode(userCode: string): Promise<{ deviceHash: string; record: DeviceAuthRecord } | null> {
+ const normalized = normalizeUserCode(userCode)
+ const deviceHash = await pub.get(codeKey(normalized))
+ if (!deviceHash) return null
+ const raw = await pub.get(deviceKey(deviceHash))
+ if (!raw) return null
+ try { return { deviceHash, record: JSON.parse(raw) as DeviceAuthRecord } } catch { return null }
+}
+
+export async function resolveDeviceAuth(
+ deviceHash: string,
+ update: Partial<DeviceAuthRecord>,
+): Promise<void> {
+ const raw = await pub.get(deviceKey(deviceHash))
+ if (!raw) return
+ let record: DeviceAuthRecord
+ try { record = JSON.parse(raw) as DeviceAuthRecord } catch { return }
+ const next = { ...record, ...update }
+ // Keep the remaining TTL rather than extending it: approval does not entitle the app to another
+ // ten minutes of polling.
+ const ttl = await pub.ttl(deviceKey(deviceHash))
+ await pub.set(deviceKey(deviceHash), JSON.stringify(next), 'EX', ttl > 0 ? ttl : 60)
+}
+
+/**
+ * Take exclusive ownership of a pending request before acting on it.
+ *
+ * `findByUserCode` + "is it still pending?" is check-then-act, and approving is NOT idempotent: it can
+ * create a machine. Two approvals racing the same code therefore both saw `pending`, both found no
+ * machine bound to the computer, and both created one — two machines, one computer, a millisecond
+ * apart. React's StrictMode double-invoking an effect is enough to trigger it, and so is a double-click.
+ *
+ * `SET NX` is the whole lock: the first caller gets it, everyone else is told the code is spent. It
+ * inherits the request's remaining TTL, so a crashed approval cannot wedge a code for longer than the
+ * code itself lives.
+ */
+export async function claimDeviceAuth(deviceHash: string): Promise<boolean> {
+ const ttl = await pub.ttl(deviceKey(deviceHash))
+ const res = await pub.set(claimKey(deviceHash), '1', 'EX', ttl > 0 ? ttl : 60, 'NX')
+ return res === 'OK'
+}
+
+/** Hand the claim back when an approval fails, so the user can fix the problem and retry the code. */
+export async function releaseDeviceAuthClaim(deviceHash: string): Promise<void> {
+ try { await pub.del(claimKey(deviceHash)) } catch (err) { logger.error('[devauth] claim release failed', err) }
+}
+
+/**
+ * Poll. A successful read is DESTRUCTIVE — the apiKey is handed over exactly once, so a leaked device
+ * code cannot be replayed later to fetch the same machine key again.
+ */
+export async function pollDeviceAuth(deviceCode: string): Promise<DeviceAuthRecord | null> {
+ const dh = hash(deviceCode)
+ const raw = await pub.get(deviceKey(dh))
+ if (!raw) return null
+ let record: DeviceAuthRecord
+ try { record = JSON.parse(raw) as DeviceAuthRecord } catch { return null }
+ if (record.state === 'approved' || record.state === 'denied') {
+ try { await pub.del(deviceKey(dh), claimKey(dh)) } catch (err) { logger.error('[devauth] cleanup failed', err) }
+ }
+ return record
+}
+
+/**
+ * One wire form for a computer id, whoever sent it: the CLI persists a dashed uuid
+ * (`~/.harness/computer-id`) while the Mac app already hashes to 32 hex. Lowercased and de-dashed so
+ * the SAME computer is the same string in Mongo regardless of which client asked — the reuse lookup
+ * in machineService.resolveOrCreateForComputer is an equality match and would otherwise miss.
+ * Returns null when it is not a plausible id (the caller answers 400).
+ */
+export function normalizeComputerId(raw: string): string | null {
+ const v = raw.trim().toLowerCase().replace(/-/g, '')
+ return /^[a-f0-9]{16,64}$/.test(v) ? v : null
+}
+
+/** Uppercase, strip separators, fold look-alikes — the user is copying this off a screen. */
+export function normalizeUserCode(code: string): string {
+ return code.toUpperCase().replace(/[\s\-_·]/g, '')
+ .replace(/I/g, '1').replace(/L/g, '1').replace(/O/g, '0').replace(/U/g, 'V')
+}
diff --git a/backend/src/lib/deviceRevoke.ts b/backend/src/lib/deviceRevoke.ts
new file mode 100644
index 000000000..eb9be4dc7
--- /dev/null
+++ b/backend/src/lib/deviceRevoke.ts
@@ -0,0 +1,32 @@
+import { deviceService } from '../services/index.js'
+import { pushDeviceRevoked } from './hub.js'
+import { publishDeviceControl } from './bus.js'
+import { logger } from '../utils/logger.js'
+
+/**
+ * Revoke one of a user's devices and tell it, on every channel that can reach it.
+ *
+ * Extracted because there are now TWO callers (the web's `/api/devices/:id` and the mobile group's
+ * own DELETE) and the three steps are not optional:
+ *
+ * 1. delete the binding, which is what makes the next connect fail;
+ * 2. push `device_revoked` on EVERY machine of the owner — a per-user device is attached under
+ * whichever machine it currently has selected, and only the socket holding it delivers;
+ * 3. push on the devctl channel too, which covers a device parked on the machine PICKER (no hub
+ * attach at all) and closes the socket, so even firmware that ignores the frame falls into its
+ * reconnect → 401 → re-pair path.
+ *
+ * A second copy of this that forgot step 2 or 3 would leave a revoked device holding a live socket,
+ * which is exactly the bug this function exists to make impossible.
+ *
+ * Returns false when the device is not this user's (or does not exist) — callers answer 404.
+ */
+export async function revokeDeviceForUser(deviceId: string, userId: string): Promise<boolean> {
+ const revoked = await deviceService.revoke(deviceId, userId)
+ if (!revoked) return false
+ for (const machineId of revoked.machineIds) pushDeviceRevoked(machineId, revoked.deviceId)
+ // Duplicate delivery is harmless — the first frame reboots the device.
+ void publishDeviceControl(revoked.deviceId, { action: 'revoked' })
+ logger.info('device revoked', { deviceId: revoked.deviceId, machines: revoked.machineIds.length, by: userId })
+ return true
+}
diff --git a/backend/src/lib/deviceWs.ts b/backend/src/lib/deviceWs.ts
new file mode 100644
index 000000000..e3d876511
--- /dev/null
+++ b/backend/src/lib/deviceWs.ts
@@ -0,0 +1,1404 @@
+import type { IncomingMessage } from 'http'
+import type { Duplex } from 'stream'
+import { WebSocketServer, WebSocket, type RawData } from 'ws'
+import { randomUUID } from 'crypto'
+import { attachHubClient, trackSocketLiveness, DEVICE_IDLE_DEADLINE_MS, type HubClient } from './hub.js'
+import {
+ getAgentPresence,
+ getMachineAppState,
+ subscribeUp,
+ setDevicePresence,
+ clearDevicePresence,
+ publishDeviceStatus,
+ subscribeDeviceControl,
+ publishDeviceControl,
+ subscribeDeviceMachineListChanged,
+ setDeviceLastMachine,
+ getDeviceLastMachine,
+ parkVoiceUpload,
+ resumeVoiceUpload,
+ evictVoiceUpload,
+} from './bus.js'
+import * as registry from './registry.js'
+import { nodeRequest } from './nodeRpc.js'
+import type { Frame } from './tunnel.js'
+import { transcribe, MAX_PCM, normalizeLang } from './stt.js'
+import { prisma } from './prisma.js'
+import { deviceService } from '../services/index.js'
+import { agentLimit, recordCreatedAgent } from './agentTracker.js'
+import { env } from '../config/env.js'
+import { logger } from '../utils/logger.js'
+import { ensureMachineReady, getMachineLifecycleStatus, type MachineLifecycleStatus } from './machineLifecycle.js'
+import { normalizeComputerId } from './deviceAuth.js'
+import { authenticateAccessToken, SsoAuthError } from './ssoAuth.js'
+import { parseAutonomousEnvironment } from './autonomousEnvironment.js'
+import { AppError } from '../errors/index.js'
+import type { Machine } from '@prisma/client'
+import {
+ VoiceQuotaExceededError,
+ voiceQuotaService,
+ type VoiceQuotaSnapshot,
+} from './voiceQuota.js'
+
+// Application-level relay for the device WebSocket (`/api/device-ws`).
+//
+// PER-USER: the device authenticates with the OWNER'S SSO ACCESS TOKEN plus a `?computer=` id, from which
+// the backend resolves — and on first sight creates — the device row. MULTI-ATTACH: a `multi_machine`-capable firmware becomes a `commander` on
+// ALL the user's machines at once — ONE socket holding N per-machine hub clients (`commanderClients`, keyed
+// by machineId), so every machine's node sees commander>0 and runs its recap, and a background machine's
+// turn-done can badge the device. `activeMachineId` is the ONE machine the device currently renders; device→
+// node traffic (voice/RPC/message) routes to `activeClient()`. `machine_select {machineId}` (ownership-checked
+// against `Machine.userId`) just MOVES the active pointer (no detach). Up-frames are tagged with their
+// machineId at `hub.deliverUpLocal` so the device demuxes them. LEGACY firmware without the cap falls back to
+// single-attach (only the selected machine is held, detach-on-switch — the web's one-machine-at-a-time model).
+// `machines_watch`→`machines_status` gives the device its live machine list for the picker.
+//
+// The backend still SNIFFS the device-native frames: voice (`voice_start` / binary PCM / `voice_end`
+// → STT → injected as a `{type:'message'}` turn on the selected machine), `device_hello` (OTA + deviceId
+// tagging), and agent RPCs. Remote machines (`authMode==='remote'`) attach the same way as self/managed;
+// their user content and adapter data are end-to-end encrypted between the device and the machine-adapter
+// (E2EE `e2e_*` frames and data RPCs relay through the hub — backend sees ciphertext).
+//
+// LEGACY fallback: an old firmware's per-machine apiKey that hashes to a bound machine is pre-selected to
+// that single machine (the old firmware never sends machine_select), so a rolling deploy doesn't brick it.
+
+// Echo the offered subprotocol (the device token) so the ESP client accepts the handshake.
+const wss = new WebSocketServer({
+ noServer: true,
+ handleProtocols: (protocols) => {
+ const first = [...protocols][0]
+ return first ?? false
+ },
+})
+
+// Presence refresh must beat the key TTL (45s in bus.setDevicePresence) with margin.
+const DEVICE_PRESENCE_REFRESH_MS = 15_000
+// How long a graceful close gets to complete before the socket is forced shut.
+const CLOSE_GRACE_MS = 2_000
+// Device chunks normally arrive every ~20ms. A 10s idle window tolerates transient network stalls
+// while ensuring a failed upload that never sends voice_end cannot hold PCM + outbound frames forever.
+const VOICE_CHUNK_IDLE_TIMEOUT_MS = 10_000
+// Current firmware uploads at most 2MB at ~64KB/s (~32s). Keep a wider absolute backstop so a peer
+// cannot retain the connection-scoped voice buffer indefinitely by trickling chunks under the idle limit.
+// All turn voices (route / normal / goal) now stream PCM live during capture and support long "ramble" input
+// (Karpathy-style), so the upload window spans the whole recording (device auto-stops at 10 min; 12 min here
+// gives margin for the final chunks + voice_end). Ask-mode is short and self-limits well under this.
+const VOICE_UPLOAD_MAX_MS = 12 * 60_000
+
+function clampSr(sr: unknown): number {
+ const n = parseInt(String(sr ?? 16000), 10) || 16000
+ return Math.min(48000, Math.max(8000, n))
+}
+
+function safeSend(ws: WebSocket, obj: unknown): void {
+ if (ws.readyState === WebSocket.OPEN) {
+ try { ws.send(JSON.stringify(obj)) } catch { /* ignore */ }
+ }
+}
+
+type DeviceSend = (obj: unknown) => void
+
+function errMsg(err: unknown): string {
+ return err instanceof Error ? err.message : String(err)
+}
+
+function payloadOf(msg: CommanderMsg): Record<string, unknown> {
+ return msg.payload && typeof msg.payload === 'object' ? msg.payload as Record<string, unknown> : {}
+}
+
+const DEVICE_RECENT_SAFE_FRAME_BYTES = Math.floor(16 * 1024 * 0.9)
+const DEVICE_AGENT_LIST_LIMIT = 100
+const DEVICE_AGENT_NAME_MAX_CODEPOINTS = 15
+const DEVICE_AGENT_NAME_MAX_BYTES = 39 // device project_t.name[40], including trailing NUL on-device.
+const DEVICE_ELLIPSIS = '…'
+
+function byteLen(s: string): number {
+ return Buffer.byteLength(s, 'utf8')
+}
+
+function truncateUtf8(input: string, maxBytes: number): string {
+ if (maxBytes <= 0) return ''
+ if (byteLen(input) <= maxBytes) return input
+ let out = ''
+ let used = 0
+ for (const ch of input) {
+ const n = byteLen(ch)
+ if (used + n > maxBytes) break
+ out += ch
+ used += n
+ }
+ return out
+}
+
+// ── the device picker's machine row ────────────────────────────────────────────────────────────────
+export type MachineStatus = {
+ machineId: string
+ name: string
+ online: boolean
+ status?: MachineLifecycleStatus
+ authMode: 'self' | 'managed' | 'remote' | 'provider'
+ remote: boolean
+ reason?: string
+ appEngine?: string // which desktop app this COMPUTER drives ("cursor"); NOT the per-agent engine
+ appState?: string // 'open' | 'closed' | 'missing'
+}
+export type MachineMeta = { name: string; authMode: MachineStatus['authMode']; remote: boolean }
+
+/**
+ * The ONE place a status row is shaped, and pure so the invariant below is directly testable.
+ *
+ * The app keys are emitted only when the machine is ONLINE, even if a stale app state is still known.
+ * That is what stops "Cursor is open" from outliving the socket that asserted it: a client never has
+ * to reason about staleness, and every row is a complete snapshot rather than a delta.
+ */
+export function buildMachineRow(
+ machineId: string,
+ online: boolean,
+ meta: MachineMeta | undefined,
+ app: { engine: string; state: string } | undefined,
+ extra: { status?: MachineLifecycleStatus; reason?: string } = {},
+): MachineStatus {
+ return {
+ machineId,
+ name: meta?.name ?? '',
+ authMode: meta?.authMode ?? 'self',
+ remote: meta?.remote ?? false,
+ online,
+ ...(extra.status ? { status: extra.status } : {}),
+ ...(extra.reason ? { reason: extra.reason } : {}),
+ ...(online && app ? { appEngine: app.engine, appState: app.state } : {}),
+ }
+}
+
+function clipDeviceAgentName(input: string): string {
+ const chars = [...input]
+ if (chars.length <= DEVICE_AGENT_NAME_MAX_CODEPOINTS && byteLen(input) <= DEVICE_AGENT_NAME_MAX_BYTES) return input
+ const ellipsisBytes = byteLen(DEVICE_ELLIPSIS)
+ let out = ''
+ for (const ch of chars.slice(0, DEVICE_AGENT_NAME_MAX_CODEPOINTS)) {
+ if (byteLen(out) + byteLen(ch) + ellipsisBytes > DEVICE_AGENT_NAME_MAX_BYTES) break
+ out += ch
+ }
+ return `${out}${DEVICE_ELLIPSIS}`
+}
+
+function deviceAgentListItem(
+ raw: unknown,
+): { id: unknown; name?: string; engine?: 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'hermes' | 'commandcode' | 'devin'; selectedModel?: string | null } {
+ const o = (raw ?? {}) as Record<string, unknown>
+ const item: { id: unknown; name?: string; engine?: 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'hermes' | 'commandcode' | 'devin'; selectedModel?: string | null } = { id: o.id }
+ if (typeof o.name === 'string') item.name = clipDeviceAgentName(o.name)
+ if (o.engine === 'claude' || o.engine === 'codex' || o.engine === 'cursor' || o.engine === 'opencode' || o.engine === 'pi' || o.engine === 'hermes' || o.engine === 'commandcode' || o.engine === 'devin') item.engine = o.engine
+ if (typeof o.selectedModel === 'string' || o.selectedModel === null) item.selectedModel = o.selectedModel
+ return item
+}
+
+function deviceRecentFrameBytes(requestId: unknown, agentId: unknown, events: Array<{ kind: unknown; text: unknown; recap?: string }>): number {
+ return Buffer.byteLength(JSON.stringify({ type: 'agent_recent_result', payload: { requestId, agentId, events } }), 'utf8')
+}
+
+function trimRecentEvents(raw: unknown, limit: number, requestId?: unknown, agentId?: unknown): Array<{ kind: unknown; text: unknown; recap?: string }> {
+ if (!Array.isArray(raw)) return []
+ const events = raw.slice(0, Math.max(1, limit)).map((e) => {
+ const o = (e ?? {}) as Record<string, unknown>
+ return {
+ kind: o.kind,
+ text: o.text,
+ ...(typeof o.recap === 'string' && o.recap ? { recap: o.recap } : {}),
+ }
+ })
+ if (deviceRecentFrameBytes(requestId, agentId, events) < DEVICE_RECENT_SAFE_FRAME_BYTES) return events
+ const first = events[0] ?? { kind: 'summary', text: '' }
+ const kind = typeof first.kind === 'string' && first.kind ? first.kind : 'summary'
+ const text = typeof first.text === 'string' ? first.text : ''
+ const recap = typeof first.recap === 'string' ? first.recap : ''
+ const make = (nextText: string, nextRecap: string) => [{ kind, text: nextText || nextRecap || kind, ...(nextRecap ? { recap: nextRecap } : {}) }]
+ const fitTextForRecap = (nextRecap: string): string => {
+ let lo = 0, hi = byteLen(text), bestText = ''
+ while (lo <= hi) {
+ const mid = Math.floor((lo + hi) / 2)
+ const candidate = truncateUtf8(text, mid)
+ if (deviceRecentFrameBytes(requestId, agentId, make(candidate, nextRecap)) < DEVICE_RECENT_SAFE_FRAME_BYTES) {
+ bestText = candidate
+ lo = mid + 1
+ } else {
+ hi = mid - 1
+ }
+ }
+ return bestText
+ }
+ const bestText = fitTextForRecap(recap)
+ if (deviceRecentFrameBytes(requestId, agentId, make(bestText, recap)) < DEVICE_RECENT_SAFE_FRAME_BYTES) return make(bestText, recap)
+ let lo = 0, hi = byteLen(recap)
+ let bestRecap = ''
+ while (lo <= hi) {
+ const mid = Math.floor((lo + hi) / 2)
+ const candidate = truncateUtf8(recap, mid)
+ if (deviceRecentFrameBytes(requestId, agentId, make(text, candidate)) < DEVICE_RECENT_SAFE_FRAME_BYTES) {
+ bestRecap = candidate
+ lo = mid + 1
+ } else {
+ hi = mid - 1
+ }
+ }
+ if (bestRecap) return make(fitTextForRecap(bestRecap) || text, bestRecap)
+ lo = 0; hi = byteLen(recap)
+ while (lo <= hi) {
+ const mid = Math.floor((lo + hi) / 2)
+ const candidate = truncateUtf8(recap, mid)
+ const candidateText = fitTextForRecap(candidate)
+ const hasRequiredText = !text || candidateText.length > 0
+ if (hasRequiredText && deviceRecentFrameBytes(requestId, agentId, make(candidateText, candidate)) < DEVICE_RECENT_SAFE_FRAME_BYTES) {
+ bestRecap = candidate
+ lo = mid + 1
+ } else {
+ hi = mid - 1
+ }
+ }
+ return make(fitTextForRecap(bestRecap), bestRecap)
+}
+
+
+type CommanderMsg = {
+ type?: string
+ payload?: unknown
+ // Multi-attach: a device frame explicitly TARGETED at a specific machine's node (eager E2EE hello to a
+ // BACKGROUND machine). Absent on normal frames, which route to the active machine.
+ machineId?: string
+ agentId?: string // workspace unit (= old wire agentId)
+ sessionId?: string
+ sr?: unknown
+ requestId?: string
+ lang?: unknown
+ goal?: boolean // voice_start with goal:true → the utterance is a GOAL command (device long-press-3s)
+ // voice_start with loop:true → the utterance becomes a "/loop <text>" command. A SEPARATE boolean
+ // rather than a `mode` value on purpose: `mode` already carries autonomy ('plan'|'auto'), and
+ // goal:true is already shipping from the square board and the OrangePi client. Additive keeps every
+ // existing client correct. The two are mutually exclusive on the device; goal wins if both arrive.
+ loop?: boolean
+ mode?: string // voice_start autonomy for this turn: 'plan' | 'auto' (device per-agent control; default auto)
+ route?: boolean // voice_start with route:true (from the Overview tile) → the router picks the target agent
+ uploadId?: string // stable per-utterance id (voice_start / voice_resume) → resume a streamed upload after a WS drop
+}
+
+interface RelayOpts {
+ userId: string
+ deviceId: string | null
+ /** The plane the OWNER signed in against. Machines are filtered by it: the same person legitimately has
+ * separate rows per Autonomous environment, and a device must never see — or be able to select — a
+ * machine from the other one. `webWs` has always enforced this; the device plane could not, because
+ * until SSO auth landed here there was no authenticated env to compare against. */
+ autonomousEnv: 'prod' | 'stag'
+}
+
+/** Hook from server.ts `upgrade` for `/api/device-ws`.
+ *
+ * AUTH IS THE USER'S SSO ACCESS TOKEN, and it is the only mechanism. The token is the first (and only)
+ * WS subprotocol; `?computer=` names the machine-independent computer the dial is plugged into. There is
+ * no device token, no pairing code and no broker handshake any more: a device row is RESOLVED from the
+ * computer id, created on first sight, and owned by whoever the token says.
+ *
+ * Deliberately unlike `/api/adapter-ws`, which this otherwise mirrors: no 402 and no 409. Billing gates a
+ * MACHINE, not a device; and a device is a `commander` hub client, of which N may coexist per machine, so
+ * two dials on two computers of the same account must both work. A same-computer reconnect is handled
+ * inside `relay()` by the presence-token supersede, not by refusing the upgrade. */
+export function handleDeviceUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
+ // Explicit HTTP statuses rather than a silent destroy: the harness CLI reads "Unexpected server response:
+ // 401" as a real deauthorization and stops retrying, where a close-1006 would loop forever.
+ const denyWith = (status: number, text: string): void => {
+ try { socket.write(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`) } catch { /* ignore */ }
+ socket.destroy()
+ }
+ const deny = (): void => denyWith(401, 'Unauthorized')
+
+ const accessToken = accessTokenFromProtocol(req)
+ if (!accessToken) { deny(); return }
+
+ let computerId: string | undefined
+ let label: string | undefined
+ let autonomousEnv: 'prod' | 'stag' = 'prod'
+ try {
+ const params = new URL(req.url ?? '', 'http://x').searchParams
+ computerId = normalizeComputerId(params.get('computer') ?? '') ?? undefined
+ label = params.get('label') || undefined
+ autonomousEnv = parseAutonomousEnvironment(params.get('autonomousEnv'))
+ } catch { deny(); return }
+ // Required: without it there is no stable identity to hang the device row on, and every reconnect
+ // would mint a new one.
+ if (!computerId) { deny(); return }
+
+ void (async () => {
+ let user
+ try {
+ user = await authenticateAccessToken(accessToken, autonomousEnv)
+ } catch (err) {
+ if (err instanceof SsoAuthError && (err.code === 'AUTONOMOUS_ENV_MISMATCH' || err.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')) {
+ denyWith(403, 'Forbidden')
+ return
+ }
+ deny()
+ return
+ }
+ const device = await deviceService.resolveOrCreateForComputer(
+ user.sub,
+ user.autonomousEnv,
+ computerId!,
+ label ?? 'computer',
+ )
+ wss.handleUpgrade(req, socket, head, (ws) =>
+ relay(ws, { userId: device.userId, deviceId: device.deviceId, autonomousEnv: user.autonomousEnv }))
+ })().catch((err) => {
+ if (err instanceof AppError) { denyWith(err.statusCode, 'Service Unavailable'); return }
+ logger.warn('device-ws upgrade failed', { error: errMsg(err) })
+ denyWith(503, 'Service Unavailable')
+ })
+}
+
+/** Device authentication is SSO-only: accept precisely the first WS subprotocol, never x-api-key. */
+function accessTokenFromProtocol(req: IncomingMessage): string | undefined {
+ const raw = req.headers['sec-websocket-protocol']
+ const first = (Array.isArray(raw) ? raw[0] : raw)?.split(',')[0]?.trim()
+ return first || undefined
+}
+
+
+function relay(device: WebSocket, opts: RelayOpts): void {
+ const { userId } = opts
+ // Never arm timers/subscriptions on a socket that already died — nothing would fire to clear them.
+ if (device.readyState !== WebSocket.OPEN) {
+ logger.warn('device relay entered on a non-open socket — skipping', { userId, deviceId: opts.deviceId })
+ return
+ }
+ // A device holds hub clients only once it attaches to a machine, so track the socket itself: parked on
+ // the picker (or short of `device_hello`) it would otherwise never be pinged and a half-open drop would
+ // never be reaped — leaving presence green, the MQTT bridge open and this relay's timers running.
+ // The device pings US every 15s, so it earns a much shorter silence deadline than a browser.
+ const releaseLiveness = trackSocketLiveness(device, DEVICE_IDLE_DEADLINE_MS)
+ // Multi-attach: the device is a `commander` on ALL the user's machines at once — ONE per-user socket
+ // holding N per-machine commander clients, keyed by machineId. Each machine's node then sees commander>0 and
+ // runs its recap, so a background machine's turn-done can badge the device. `activeMachineId` is the ONE
+ // machine the device currently renders/interacts with — device→node traffic (voice/RPC/message) routes
+ // there. Gated on the `multi_machine` firmware cap; without it we fall back to single-attach (only the
+ // selected machine is held) so an un-flashed device keeps today's behavior.
+ const commanderClients = new Map<string, HubClient>() // machineId → hub client (all attached machines)
+ const machineRemote = new Map<string, boolean>() // machineId → authMode === 'remote'
+ let activeMachineId: string | null = null // the RENDERED/interacted machine (confirmed after bindMachine)
+ let activeBinding: Machine | null = null
+ let deviceMultiMachine = false // firmware cap: hold N machines at once vs single-attach
+ let deviceId = opts.deviceId // may be (re)set by device_hello
+ let closed = false
+ const activeClient = (): HubClient | null => (activeMachineId ? commanderClients.get(activeMachineId) ?? null : null)
+ const activeRemote = (): boolean => (activeMachineId ? machineRemote.get(activeMachineId) ?? false : false)
+ // Move the ACTIVE (rendered) machine pointer, flipping the `commanderActive` signal so ONLY the newly-active
+ // machine's node streams full turn cards; the previous one drops back to recap-only (background badge).
+ const setActiveMachine = (machineId: string | null): void => {
+ if (activeMachineId === machineId) return
+ const prev = activeMachineId
+ activeMachineId = machineId
+ if (prev) commanderClients.get(prev)?.setActive(false)
+ if (machineId) commanderClients.get(machineId)?.setActive(true)
+ // Mirror the pointer into the DB so a client with no socket of its own (the mobile app) can show
+ // which machine this device is on. Fire-and-forget: the service swallows its own errors, and this
+ // must never delay the active-machine switch the user is waiting on.
+ if (deviceId) void deviceService.setActiveMachine(deviceId, machineId)
+ }
+ // Attach/detach a per-machine commander client onto this one device socket. attachHubClient keys clients
+ // by (machineId, connId) NOT by socket, so N of them coexist on one socket (each its own up:{machineId} sub).
+ const attachCommander = (machineId: string, remote: boolean): HubClient => {
+ const c = attachHubClient(device, machineId, 'commander')
+ commanderClients.set(machineId, c)
+ machineRemote.set(machineId, remote)
+ if (deviceId) registry.setClientDeviceId(machineId, c.connId, deviceId)
+ logger.info('commander attached machine', { userId, machineId, connId: c.connId })
+ return c
+ }
+ const detachCommander = (machineId: string): void => {
+ const c = commanderClients.get(machineId)
+ if (!c) return
+ registry.clearCommanderVoiceQueue(machineId, c.connId)
+ c.detach()
+ commanderClients.delete(machineId)
+ machineRemote.delete(machineId)
+ // Through setActiveMachine rather than assigning the field, so the DB mirror has exactly ONE
+ // writer. Runs after the delete above, so its setActive(false) lookup is a no-op on the client
+ // we just detached.
+ if (activeMachineId === machineId) { setActiveMachine(null); activeBinding = null }
+ }
+ // Establish the active-machine pointer + binding for a known machineId (attaching a commander client if needed).
+ // Used by the auto-restore on reconnect AND by a resumed voice upload, whose finishVoice needs a machine before
+ // the device fires voice_end. Mirrors the watchMachines auto-restore; returns false if the machine isn't the user's.
+ const restoreActiveMachine = async (machineId: string): Promise<boolean> => {
+ if (activeMachineId === machineId) return true
+ const binding = await prisma.machine.findUnique({ where: { machineId } })
+ if (!binding || binding.deletedAt || binding.userId !== userId) return false
+ const remote = binding.authMode === 'remote'
+ const c = commanderClients.get(machineId) ?? attachCommander(machineId, remote)
+ machineRemote.set(machineId, remote)
+ setActiveMachine(machineId)
+ activeBinding = binding
+ if (deviceId) registry.setClientDeviceId(machineId, c.connId, deviceId)
+ return true
+ }
+
+ logger.info('device relay open (per-user)', { userId })
+
+ // ── Device presence (per-DEVICE: one key + refresh loop per connection; token-scoped supersede) ───
+ // Feeds the web's `devices_status` (webWs.watchDevices). The token makes teardown safe when the
+ // same device reconnects before the old socket dies: the new socket owns the key, our conditional
+ // clear no-ops and we skip the offline publish.
+ const connToken = randomUUID()
+ let presenceTimer: NodeJS.Timeout | null = null
+ let presenceDeviceId: string | null = null
+ let controlUnsub: (() => void) | null = null
+ let machineListUnsub: (() => void) | null = null
+ const startPresence = (id: string): void => {
+ if (closed || presenceDeviceId === id) return
+ presenceDeviceId = id
+ void setDevicePresence(id, connToken)
+ void publishDeviceStatus(userId, { deviceId: id, online: true })
+ if (presenceTimer) clearInterval(presenceTimer)
+ presenceTimer = setInterval(() => { void setDevicePresence(id, connToken) }, DEVICE_PRESENCE_REFRESH_MS)
+ // Control channel: a revoke must reach the device even when it's parked on the machine PICKER
+ // (no hub attach → the machine-targeted pushDeviceRevoked can't reach it). Deliver the frame the
+ // firmware already handles (wipe token + reboot to pair screen), then close the socket so a
+ // firmware that misses the frame still falls into its reconnect→401→re-pair path.
+ void subscribeDeviceControl(id, (msg) => {
+ if (msg.action === 'superseded') {
+ // A newer connection for this device authenticated. On an abrupt device-side drop (WiFi blip) our
+ // socket is half-open and the hub heartbeat won't reap it for ~75-100s — long after the device has
+ // reconnected and asked to resume. Close NOW so closeBoth PARKS the in-flight voice upload before the
+ // device's voice_resume arrives (else it finds nothing → reject → lost recording). Ignore our own echo.
+ if (msg.by && msg.by === connToken) return
+ logger.info('device control: superseded by a newer connection — parking + closing', { userId, deviceId: id })
+ closeBoth()
+ return
+ }
+ if (msg.action !== 'revoked') return
+ logger.info('device control: revoked — notifying + closing socket', { userId, deviceId: id })
+ safeSend(device, { type: 'device_revoked' })
+ setTimeout(() => closeBoth(), 250) // let the frame flush before tearing down
+ }).then((unsub) => {
+ if (closed) { unsub(); return }
+ controlUnsub?.()
+ controlUnsub = unsub
+ void publishDeviceControl(id, { action: 'superseded', by: connToken }) // force any older half-open socket to park now
+ })
+ }
+ if (deviceId) startPresence(deviceId)
+
+ // ── Voice capture state (per connection) ─────────────────────────────────────────────────────────
+ let voiceActive = false
+ let voiceMode: 'turn' | 'ask' = 'turn' // 'turn' = STT → dispatch a new message; 'ask' = STT → return transcript only
+ let voiceGoal = false // 'turn' + goal → dispatch the transcript as a "/goal <text>" command
+ let voiceLoop = false // 'turn' + loop → dispatch the transcript as a "/loop <text>" command
+ let voiceAutonomy: 'plan' | 'auto' = 'auto' // 'turn' autonomy from the device's per-agent Mode control
+ let voiceRequestId: string | null = null // the AskUserQuestion requestId, for 'ask' mode
+ let voiceAgentId: string | null = null
+ let voiceSessionId: string | null = null
+ let voiceRoute = false // 'turn' + route → let the router pick the agent (voice from Overview)
+ let voiceUploadId: string | null = null // stable per-utterance id; drives park-on-drop / resume (Redis)
+ let voiceMachineId: string | null = null // machine pinned at voice_start; selection changes cannot reroute the utterance
+ let voiceQuotaCheck: Promise<VoiceQuotaSnapshot> | null = null
+ // Voice router: transcripts awaiting a device route_confirm (medium/low confidence). Keyed by routeId,
+ // pruned by TTL on lookup. auto-dispatch (high confidence) never touches this map.
+ // The device's mode select turns an utterance into a slash command. Written ONCE because the prefix is
+ // applied at three separate dispatch sites (fixed agent, router auto-dispatch, route_confirm) and they
+ // drifted apart easily — a second command added inline would have to be remembered in all three.
+ //
+ // Prepended UNCONDITIONALLY: this side does not know the target engine. On the routed path the agent is
+ // picked only after transcription and `voice_route` replies without an engine. The machine-adapter strips
+ // what the engine cannot take (see lib/goalCommand.ts) — it is the one place that always knows.
+ const withCommand = (text: string, goal: boolean, loop: boolean): string =>
+ goal ? `/goal ${text}` : loop ? `/loop ${text}` : text
+
+ const ROUTE_AUTO_THRESHOLD = 0.75
+ const ROUTE_PENDING_TTL_MS = 60_000
+ const pendingRoutes = new Map<string, { text: string; goal: boolean; loop: boolean; ts: number }>()
+ let voiceSr = 16000
+ let voiceLang: string = 'en' // STT language for this utterance (device Settings; see VOICE_LANGS)
+ let chunks: Buffer[] = []
+ let voiceSize = 0
+ let voiceIdleTimer: NodeJS.Timeout | null = null
+ let voiceMaxTimer: NodeJS.Timeout | null = null
+ let deviceFirmwareVersion: string | null = null
+ // Capability: firmware that can run device↔adapter E2EE for DATA RPCs (decrypts encrypted
+ // agents_list_result / agent_recent_result / … under the pairwise/group key). Advertised in
+ // device_hello (`caps: ['e2ee_data']`). For REMOTE adapter machines this cap is mandatory: without it,
+ // backend refuses adapter data with E2EE_REQUIRED instead of terminating RPCs via nodeRequest and
+ // reading plaintext. With it, backend RELAYS the RPCs to the machine like webWs; adapter encrypts the
+ // result per connId-session and backend sees only ciphertext. See
+ // docs/plans/2026-07-15_device-adapter-e2ee-comprehensive.md.
+ let deviceE2eeData = false
+ // Agent of the in-flight user turn (set on dispatch) so the turn_end log can name it.
+ let currentTurnAgentId: string | null = null
+
+ const sendDevice = (obj: unknown): void => {
+ const payload = JSON.stringify(obj)
+ const ac = activeClient()
+ if (ac && activeMachineId && registry.queueCommanderFrame(activeMachineId, ac.connId, obj, payload)) return
+ if (device.readyState === WebSocket.OPEN) {
+ try { device.send(payload) } catch { /* ignore */ }
+ }
+ }
+ const sendDeviceNow = (obj: unknown): void => safeSend(device, obj)
+ const clearVoiceQueue = (): void => {
+ const ac = activeClient()
+ if (ac && activeMachineId) registry.clearCommanderVoiceQueue(activeMachineId, ac.connId)
+ }
+ const flushVoiceQueue = (reason: string): void => {
+ const ac = activeClient()
+ if (!ac || !activeMachineId) return
+ const queued = registry.flushCommanderVoiceQueue(activeMachineId, ac.connId)
+ if (!queued.length) return
+ for (const q of queued) {
+ if (device.readyState !== WebSocket.OPEN) break
+ try { device.send(q.payload) } catch { /* ignore */ }
+ }
+ logger.info('commander voice queue flushed', { userId, machineId: activeMachineId, connId: ac.connId, frames: queued.length, reason })
+ }
+ const clearVoiceTimers = (): void => {
+ if (voiceIdleTimer) { clearTimeout(voiceIdleTimer); voiceIdleTimer = null }
+ if (voiceMaxTimer) { clearTimeout(voiceMaxTimer); voiceMaxTimer = null }
+ }
+ const discardVoiceUpload = (): void => {
+ clearVoiceTimers()
+ voiceActive = false
+ chunks = []
+ voiceSize = 0
+ voiceMode = 'turn'
+ voiceRequestId = null
+ voiceAgentId = null
+ voiceSessionId = null
+ voiceRoute = false
+ voiceUploadId = null
+ voiceMachineId = null
+ voiceQuotaCheck = null
+ }
+ const abortVoiceUpload = (reason: 'voice_idle_timeout' | 'voice_max_timeout' | 'voice_restarted'): void => {
+ if (!voiceActive) { clearVoiceTimers(); return }
+ const bytes = voiceSize
+ const agentId = voiceAgentId
+ discardVoiceUpload()
+ flushVoiceQueue(reason)
+ logger.warn('commander voice upload aborted', { userId, machineId: activeMachineId, agentId, bytes, reason })
+ }
+ const armVoiceIdleTimer = (): void => {
+ if (voiceIdleTimer) clearTimeout(voiceIdleTimer)
+ voiceIdleTimer = setTimeout(() => abortVoiceUpload('voice_idle_timeout'), VOICE_CHUNK_IDLE_TIMEOUT_MS)
+ voiceIdleTimer.unref()
+ }
+ const armVoiceTimers = (): void => {
+ clearVoiceTimers()
+ armVoiceIdleTimer()
+ voiceMaxTimer = setTimeout(() => abortVoiceUpload('voice_max_timeout'), VOICE_UPLOAD_MAX_MS)
+ voiceMaxTimer.unref()
+ }
+
+ // ── Live machine-list feed for the device picker (ported from webWs.watchAgents; enriched name+authMode) ─
+ const statusSubs = new Map<string, () => void>()
+ // Per-machine identity, refreshed by every watchMachines pass. The subscribeUp closure below reads
+ // through this map instead of capturing its machine row: subscriptions are installed once and never
+ // replaced (`if (statusSubs.has(id)) continue`), so a captured row went stale on rename and every
+ // partial status frame reverted the machine's name to the one it had when the device connected.
+ const machineMeta = new Map<string, MachineMeta>()
+ // Desktop-app presence asserted by the adapter (see machine_app_status in adapterWs).
+ const machineApp = new Map<string, { engine: string; state: string }>()
+ const machineRow = (
+ machineId: string,
+ online: boolean,
+ extra: { status?: MachineLifecycleStatus; reason?: string } = {},
+ ): MachineStatus =>
+ buildMachineRow(machineId, online, machineMeta.get(machineId), machineApp.get(machineId), extra)
+ const sendMachines = (statuses: MachineStatus[], full = false): void => {
+ if (device.readyState !== WebSocket.OPEN || (!full && statuses.length === 0)) return
+ sendDevice({ type: 'machines_status', payload: { ...(full ? { full: true } : {}), statuses } })
+ }
+ let watchGen = 0
+ const watchMachines = async (): Promise<void> => {
+ const gen = ++watchGen
+ const machines = await deviceService.machinesForUser(userId, opts.autonomousEnv) // ALWAYS re-derived from the DB
+ if (gen !== watchGen || closed) return
+ const wanted = new Map(machines.map((f) => [f.machineId, f]))
+ for (const [id, unsub] of statusSubs) {
+ if (!wanted.has(id)) { unsub(); statusSubs.delete(id) } // machine deleted
+ }
+ // Drop commander clients for machines that no longer exist (deleted/unbound). detachCommander clears
+ // activeMachineId when the removed machine was the active/rendered one.
+ for (const id of [...commanderClients.keys()]) {
+ if (!wanted.has(id)) {
+ if (id === activeMachineId) { selectGen++; discardVoiceUpload(); clearVoiceQueue() }
+ detachCommander(id)
+ }
+ }
+ for (const [id, f] of wanted) machineMeta.set(id, { name: f.name, authMode: f.authMode, remote: f.remote })
+ for (const id of [...machineMeta.keys()]) if (!wanted.has(id)) { machineMeta.delete(id); machineApp.delete(id) }
+ for (const [id] of wanted) {
+ if (statusSubs.has(id)) continue
+ // Bus subscriptions are refcounted — co-existing with the commander's up:{id} sub is fine.
+ const unsub = await subscribeUp(id, (msg) => {
+ const fr = msg.frame as { type?: string; payload?: { online?: boolean; status?: MachineLifecycleStatus; reason?: string; engine?: string; state?: string } }
+ // Desktop-app presence: one single-row status frame, the same partial path node_status uses.
+ // Deliberately NOT publishDeviceMachineListChanged — that re-queries Mongo per device and
+ // pushes machines_changed to every browser tab, so quitting Cursor would cost a DB round trip.
+ if (fr?.type === 'machine_app_status') {
+ const engine = fr.payload?.engine
+ const state = fr.payload?.state
+ if (!engine || !state) return
+ machineApp.set(id, { engine, state })
+ sendMachines([machineRow(id, true)])
+ return
+ }
+ if (fr?.type === 'node_status') {
+ const online = fr.payload?.online === true
+ // A machine that went offline has no app state; drop it so a reconnect must re-assert.
+ if (!online) machineApp.delete(id)
+ sendMachines([machineRow(id, online, { status: fr.payload?.status, reason: fr.payload?.reason })])
+ // The picker list is not this frame's only consumer. The Overview's "Node offline" guide is driven
+ // by a `node_status` addressed to the DEVICE, and that was only ever sent by seedNodeStatus — which
+ // runs on bindMachine and nowhere else. So a remote machine that dropped and came back updated the
+ // picker while the device kept waiting for an online flip that never arrived: it sat in the join
+ // guide, telling the user to run `harness join` against a machine that was already running, until
+ // they re-picked it by hand. Mirror the flip for whichever machine is being rendered.
+ if (id === activeMachineId) {
+ const status = fr.payload?.status
+ sendDevice({ type: 'node_status', payload: { online, status: online ? 'running' : !status || status === 'unknown' ? 'offline' : status } })
+ }
+ }
+ })
+ if (closed || gen !== watchGen) { unsub(); return }
+ statusSubs.set(id, unsub)
+ }
+ // Multi-attach: hold a `commander` client on EVERY machine so each machine's node runs its recap and can
+ // push its turn-done to the device (badge) even while another machine is active/rendered. Gated on the
+ // firmware cap; without it only the selected machine is attached (via bindMachine), exactly like today.
+ if (deviceMultiMachine && !closed) {
+ for (const [id, f] of wanted) {
+ if (commanderClients.has(id)) { machineRemote.set(id, f.remote); continue }
+ attachCommander(id, f.remote)
+ }
+ }
+ // Seed the full current picture (presence keys = source of truth) so the list is right immediately.
+ const statuses = await Promise.all(
+ [...wanted.values()].map(async (f) => {
+ const online = !!(await getAgentPresence(f.machineId))
+ const status = online ? 'running' : await getMachineLifecycleStatus(f.machineId)
+ // Seed the app state from Redis too, so a device that connects while the Mac has been up for
+ // an hour sees "Cursor open" immediately instead of waiting for the next transition. Issued
+ // inside the existing Promise.all, so it adds no wall-clock latency.
+ const app = online ? await getMachineAppState(f.machineId) : null
+ if (app) machineApp.set(f.machineId, app); else machineApp.delete(f.machineId)
+ return machineRow(f.machineId, online, { status: status === 'unknown' ? 'offline' as const : status })
+ }),
+ )
+ if (gen === watchGen && !closed) sendMachines(statuses, true)
+
+ // Auto-restore the active machine on (re)connect. A multi_machine device renders agents by attaching to
+ // every machine WITHOUT sending machine_select, so `activeMachineId` would otherwise stay null and both voice
+ // (route AND fixed-agent) and RPCs fail with "no machine selected". Rebind the device's last-selected
+ // machine if it's still one of the user's machines. Single-attach firmware still sets it via its own
+ // machine_select, and this no-ops once a machine is active.
+ if (!activeMachineId && deviceId && gen === watchGen && !closed) {
+ const last = await getDeviceLastMachine(deviceId)
+ if (last && wanted.has(last)) {
+ const binding = await prisma.machine.findUnique({ where: { machineId: last } })
+ if (binding && !binding.deletedAt && binding.billingStatus !== 'pending' && binding.billingStatus !== 'suspended' && binding.userId === userId && !activeMachineId && gen === watchGen && !closed) {
+ // LIGHTWEIGHT restore: the machine is already attached (multi-attach) and rendering, so just move the
+ // active pointer + binding. Do NOT ensureMachineReady here — that provision-wakes via the manager and
+ // would make reconnect fragile (a transient manager-WS blip would leave activeMachineId null). A real
+ // wake still runs on the next turn dispatch (ensureActiveReady) if the node is actually stopped.
+ const remote = binding.authMode === 'remote'
+ const c = commanderClients.get(last) ?? attachCommander(last, remote)
+ machineRemote.set(last, remote)
+ setActiveMachine(last)
+ activeBinding = binding
+ if (deviceId) registry.setClientDeviceId(last, c.connId, deviceId)
+ logger.info('commander machine auto-restored on connect', { userId, machineId: last })
+ }
+ }
+ }
+ }
+
+ // ── Machine selection (ported from webWs.bindAgent; + remote guard + deviceId re-tag) ───────────────
+ let selectGen = 0
+ const seedNodeStatus = (machineId: string): void => {
+ void getAgentPresence(machineId).then((mgr) => {
+ if (device.readyState === WebSocket.OPEN && activeMachineId === machineId) {
+ const online = !!mgr
+ void getMachineLifecycleStatus(machineId).then((status) => {
+ if (device.readyState === WebSocket.OPEN && activeMachineId === machineId) {
+ sendDevice({ type: 'node_status', payload: { online, status: online ? 'running' : status === 'unknown' ? 'offline' : status } })
+ }
+ })
+ }
+ })
+ }
+ const bindMachine = async (machineIdRaw: unknown): Promise<void> => {
+ if (typeof machineIdRaw !== 'string' || !machineIdRaw) return
+ const machineId = machineIdRaw
+ const gen = ++selectGen
+ const binding = await prisma.machine.findUnique({ where: { machineId } })
+ if (closed || gen !== selectGen) return // superseded by a newer select
+ if (!binding || binding.deletedAt || binding.userId !== userId) {
+ logger.warn('commander machine_select rejected', { userId, machineId })
+ sendDeviceNow({ type: 'machine_select_error', payload: { machineId, error: 'NOT_YOUR_MACHINE' } })
+ return
+ }
+ // Same plane, or nothing. The machine list is already filtered by environment, so reaching here with a
+ // mismatch means the id was guessed or is stale — either way the token that authenticated this socket
+ // cannot drive that machine, and `webWs` has always refused it for the same reason.
+ if (binding.autonomousEnv !== opts.autonomousEnv) {
+ logger.warn('commander machine_select rejected — environment mismatch', { userId, machineId })
+ sendDeviceNow({ type: 'machine_select_error', payload: { machineId, error: 'MACHINE_ENV_MISMATCH' } })
+ return
+ }
+ if (binding.billingStatus === 'pending') {
+ sendDeviceNow({ type: 'machine_select_error', payload: { machineId, error: 'MACHINE_PAYMENT_PENDING' } })
+ return
+ }
+ if (binding.billingStatus === 'suspended') {
+ sendDeviceNow({ type: 'machine_select_error', payload: { machineId, error: 'MACHINE_SUBSCRIPTION_REQUIRED' } })
+ return
+ }
+ try {
+ await ensureMachineReady(binding)
+ } catch (err) {
+ if (!closed && gen === selectGen) {
+ const code = err instanceof Error && 'code' in err ? String((err as { code?: unknown }).code) : 'MACHINE_START_FAILED'
+ sendDeviceNow({ type: 'machine_select_error', payload: { machineId, error: code } })
+ }
+ return
+ }
+ if (closed || gen !== selectGen) return
+ // Same-machine reselect still wakes a stopped machine, but preserves the existing commander connId.
+ if (machineId === activeMachineId && commanderClients.has(machineId)) {
+ activeBinding = binding
+ sendDeviceNow({ type: 'machine_selected', payload: { machineId } })
+ seedNodeStatus(machineId)
+ return
+ }
+ // Voice belongs to the previously-active machine — discard it on switch.
+ discardVoiceUpload()
+ clearVoiceQueue()
+ // Single-attach firmware (no multi_machine cap): only ONE machine is held at a time, so detach every other
+ // machine on switch (today's behavior). Multi-machine firmware keeps ALL machines attached (watchMachines holds
+ // them for their recap/badge) and just moves the ACTIVE pointer.
+ if (!deviceMultiMachine) {
+ for (const id of [...commanderClients.keys()]) if (id !== machineId) detachCommander(id)
+ }
+ // Ensure THIS machine is attached as a commander. Multi-machine: watchMachines already attached it on connect,
+ // but a select can race ahead → attach on demand. Remote machines (machine-adapter) attach the SAME way as
+ // self/managed: the device is a 'commander' hub client on down:{machineId}, the adapter occupies the node
+ // side, and device↔adapter content is end-to-end encrypted (E2EE frames relay through the hub as
+ // ciphertext). See docs/design/e2e-encrypted-client-channel.md.
+ const remote = binding.authMode === 'remote'
+ const c = commanderClients.get(machineId) ?? attachCommander(machineId, remote)
+ machineRemote.set(machineId, remote)
+ setActiveMachine(machineId) // marks this machine's commander active (stream), previous one inactive (recap-only)
+ activeBinding = binding
+ // Remember this selection so a reconnect (backend restart / device re-flash / WS drop) restores the
+ // active machine instead of leaving it null — see the auto-restore in watchMachines.
+ if (deviceId) void setDeviceLastMachine(deviceId, machineId)
+ // Re-tag this connection's deviceId so a revoke can target it (connId is stable per machine now).
+ if (deviceId) registry.setClientDeviceId(machineId, c.connId, deviceId)
+ logger.info('commander selected machine', { userId, machineId, connId: c.connId })
+ sendDeviceNow({ type: 'machine_selected', payload: { machineId } })
+ seedNodeStatus(machineId)
+ }
+
+ const closeBoth = (): void => {
+ if (closed) return
+ closed = true
+ releaseLiveness()
+ if (presenceTimer) { clearInterval(presenceTimer); presenceTimer = null }
+ if (controlUnsub) { controlUnsub(); controlUnsub = null }
+ if (machineListUnsub) { machineListUnsub(); machineListUnsub = null }
+ if (presenceDeviceId) {
+ const id = presenceDeviceId
+ // Conditional clear: only publish offline if the key is really gone (a superseding reconnect
+ // keeps its own key → we stay silent). lastSeenAt = the moment the device actually went away.
+ const seenAt = new Date()
+ void clearDevicePresence(id, connToken).then((gone) => {
+ if (gone) void publishDeviceStatus(userId, { deviceId: id, online: false, lastSeenAt: seenAt.toISOString() })
+ })
+ void prisma.deviceBinding.update({ where: { deviceId: id }, data: { lastSeenAt: seenAt } }).catch(() => { /* best effort */ })
+ }
+ for (const [, unsub] of statusSubs) unsub()
+ statusSubs.clear()
+ // Resumable upload: if a streamed recording is still in flight (no voice_end seen) and the firmware sent
+ // an uploadId, PARK it in Redis (grace ~60s) instead of discarding, so the device's reconnect can resume
+ // it — possibly on a different backend instance. Otherwise discard as before.
+ if (voiceActive && deviceId && voiceUploadId) {
+ const meta = {
+ uploadId: voiceUploadId, mode: voiceMode, route: voiceRoute, goal: voiceGoal, loop: voiceLoop, autonomy: voiceAutonomy,
+ agentId: voiceAgentId, sessionId: voiceSessionId, requestId: voiceRequestId, sr: voiceSr,
+ lang: voiceLang, size: voiceSize, machineId: voiceMachineId ?? activeMachineId,
+ }
+ const pcm = Buffer.concat(chunks)
+ clearVoiceTimers(); voiceActive = false
+ void parkVoiceUpload(deviceId, meta, pcm)
+ logger.info('commander voice parked (WS drop mid-stream)', { userId, deviceId, uploadId: voiceUploadId, bytes: pcm.length })
+ } else {
+ discardVoiceUpload()
+ }
+ clearVoiceQueue()
+ for (const [, c] of commanderClients) c.detach() // drop commander on EVERY attached machine (count → 0)
+ commanderClients.clear()
+ machineRemote.clear()
+ activeMachineId = null
+ // Polite close first (revoke needs its frame to land), then force it: on a half-open socket the close
+ // handshake never completes and ws would hold the fd until its own timeout.
+ try { device.close() } catch { /* ignore */ }
+ setTimeout(() => {
+ if (device.readyState !== WebSocket.CLOSED) { try { device.terminate() } catch { /* ignore */ } }
+ }, CLOSE_GRACE_MS).unref?.()
+ }
+
+ // ── Device-native frames (synchronous — must stay in sync with the binary PCM frames) ─────────────
+ const startVoice = (msg: CommanderMsg): void => {
+ if (voiceActive) abortVoiceUpload('voice_restarted')
+ voiceActive = true
+ voiceMode = msg.type === 'voice_ask_start' ? 'ask' : 'turn'
+ voiceGoal = voiceMode === 'turn' && msg.goal === true // ask mode is never a goal
+ // goal wins if a client somehow sets both — they are one control on the device, and a defined
+ // precedence beats an arbitrary one.
+ voiceLoop = voiceMode === 'turn' && msg.loop === true && !voiceGoal
+ voiceAutonomy = msg.mode === 'plan' ? 'plan' : 'auto' // device per-agent Mode (default auto/bypass)
+ voiceRequestId = msg.requestId ?? null
+ voiceAgentId = msg.agentId ?? null
+ voiceSessionId = msg.sessionId || null
+ voiceRoute = voiceMode === 'turn' && msg.route === true // Overview voice → router picks the agent
+ voiceUploadId = typeof msg.uploadId === 'string' && msg.uploadId ? msg.uploadId : randomUUID()
+ voiceMachineId = activeMachineId
+ voiceSr = clampSr(msg.sr)
+ // Was a two-way en/vi clamp, which silently rewrote every other language the device offered to 'vi'.
+ // normalizeLang gates on the SAME list Deepgram enforces; firmware older than the picker sends no
+ // `lang` at all and lands on the default.
+ voiceLang = normalizeLang(msg.lang)
+ chunks = []; voiceSize = 0
+ // A fresh utterance invalidates any parked partial from a previous (abandoned) recording on this device.
+ if (deviceId) void evictVoiceUpload(deviceId)
+ const ac = activeClient()
+ if (ac && activeMachineId) registry.startCommanderVoiceQueue(activeMachineId, ac.connId)
+ armVoiceTimers()
+ logger.info('commander voice_start', {
+ userId,
+ machineId: voiceMachineId,
+ mode: voiceMode,
+ goal: voiceGoal,
+ loop: voiceLoop,
+ agentId: voiceAgentId,
+ sr: voiceSr,
+ lang: voiceLang,
+ uploadId: voiceUploadId,
+ })
+ const startedUploadId = voiceUploadId
+ const startedMachineId = voiceMachineId
+ const startedBinding = activeBinding && activeBinding.machineId === startedMachineId ? activeBinding : null
+ voiceQuotaCheck = startedMachineId ? voiceQuotaService.snapshotForMachine(startedMachineId) : null
+ if (voiceQuotaCheck) {
+ void voiceQuotaCheck.then((quota) => {
+ if (!voiceActive || voiceUploadId !== startedUploadId) return
+ sendDeviceNow({ type: 'voice_quota_status', payload: { ...quota, uploadId: startedUploadId } })
+ if (quota.limitSeconds > 0 && quota.remainingSeconds === 0) {
+ discardVoiceUpload()
+ flushVoiceQueue('voice_quota_exceeded')
+ sendDeviceNow({ type: 'voice_quota_exceeded', payload: { ...quota, uploadId: startedUploadId } })
+ return
+ }
+ // A real voice turn wakes its machine only after quota passes, so an exhausted machine stays Idle.
+ if (msg.type === 'voice_start' && startedBinding) {
+ void ensureMachineReady(startedBinding).catch(() => { /* ensureMachineReady already logs */ })
+ }
+ }).catch((err) => {
+ if (!voiceActive || voiceUploadId !== startedUploadId) return
+ discardVoiceUpload()
+ flushVoiceQueue('voice_quota_unavailable')
+ logger.warn('commander voice quota precheck failed', {
+ userId,
+ machineId: startedMachineId,
+ error: errMsg(err),
+ })
+ sendDeviceNow({ type: 'error', message: 'VOICE_QUOTA_UNAVAILABLE' })
+ })
+ }
+ }
+
+ // Device reconnected mid-stream and wants to resume its parked upload. Rehydrate this (fresh) connection's
+ // voice state from Redis and tell the device the byte offset we already have so it re-sends only the gap.
+ // Async (Redis read) — safe because the device WAITS for voice_resume_ack before re-sending any PCM, so no
+ // binary frame races ahead of voiceActive being set here. Runs AFTER the reconnect's machine_select, so
+ // activeMachineId is set for the eventual finishVoice dispatch.
+ const handleVoiceResume = async (msg: CommanderMsg): Promise<void> => {
+ const uploadId = typeof msg.uploadId === 'string' ? msg.uploadId : ''
+ if (!uploadId || !deviceId) { sendDeviceNow({ type: 'voice_resume_reject', uploadId }); return }
+ const parked = await resumeVoiceUpload(deviceId)
+ if (!parked || parked.meta.uploadId !== uploadId) {
+ sendDeviceNow({ type: 'voice_resume_reject', uploadId })
+ if (parked) void evictVoiceUpload(deviceId) // stale/mismatched entry → drop it
+ logger.info('commander voice_resume rejected', { userId, deviceId, uploadId, found: !!parked })
+ return
+ }
+ const m = parked.meta
+ voiceActive = true
+ voiceMode = m.mode; voiceRoute = m.route; voiceGoal = m.goal; voiceLoop = m.loop === true; voiceAutonomy = m.autonomy
+ voiceAgentId = m.agentId; voiceSessionId = m.sessionId; voiceRequestId = m.requestId
+ voiceSr = m.sr; voiceLang = m.lang; voiceUploadId = uploadId
+ voiceMachineId = m.machineId
+ chunks = [parked.pcm]; voiceSize = parked.pcm.length
+ armVoiceTimers() // fresh idle/max timers on this connection; incoming chunks refresh the idle one
+ // This fresh relay() closure has no active machine yet (the reconnect's machine_select/auto-restore is async).
+ // Restore it from the parked meta.machineId BEFORE the ack — the device gates voice_end on the ack, so doing
+ // it now guarantees finishVoice has a machine (else it throws NO_MACHINE_SELECTED and loses the whole ramble).
+ if (!activeMachineId && m.machineId) await restoreActiveMachine(m.machineId).catch((err) => logger.warn('voice_resume machine restore failed', { userId, deviceId, machineId: m.machineId, error: errMsg(err) }))
+ voiceQuotaCheck = voiceMachineId ? voiceQuotaService.snapshotForMachine(voiceMachineId) : null
+ if (voiceQuotaCheck) {
+ try {
+ const quota = await voiceQuotaCheck
+ sendDeviceNow({ type: 'voice_quota_status', payload: { ...quota, uploadId } })
+ if (quota.limitSeconds > 0 && quota.remainingSeconds === 0) {
+ discardVoiceUpload()
+ void evictVoiceUpload(deviceId)
+ sendDeviceNow({ type: 'voice_quota_exceeded', payload: { ...quota, uploadId } })
+ return
+ }
+ } catch (err) {
+ discardVoiceUpload()
+ void evictVoiceUpload(deviceId)
+ logger.warn('commander voice_resume quota check failed', {
+ userId,
+ deviceId,
+ machineId: m.machineId,
+ error: errMsg(err),
+ })
+ sendDeviceNow({ type: 'voice_resume_reject', uploadId })
+ sendDeviceNow({ type: 'error', message: 'VOICE_QUOTA_UNAVAILABLE' })
+ return
+ }
+ }
+ sendDeviceNow({ type: 'voice_resume_ack', uploadId, offset: voiceSize })
+ logger.info('commander voice_resume', { userId, deviceId, uploadId, offset: voiceSize, machineId: activeMachineId })
+ // The Redis entry is kept (not evicted) so if THIS connection also drops, closeBoth re-parks the fuller
+ // buffer over it. finishVoice evicts on completion; a fresh voice_start evicts on a new utterance.
+ }
+
+ const handleHello = (msg: CommanderMsg): void => {
+ const payload = payloadOf(msg)
+ deviceFirmwareVersion = typeof payload.firmwareVersion === 'string' && payload.firmwareVersion ? payload.firmwareVersion : null
+ // E2EE-for-data capability (firmware that decrypts encrypted *_result frames). When present we
+ // relay agent RPCs to the machine instead of reading them at the backend (see deviceE2eeData decl).
+ deviceE2eeData = Array.isArray(payload.caps) && payload.caps.includes('e2ee_data')
+ // Multi-machine cap: firmware that holds N machines at once (routes frames by the machineId tag + badges a
+ // background machine's turn-done). Without it we stay single-attach. device_hello arrives AFTER the
+ // connect-time watchMachines ran, so flipping the cap here needs a re-run to attach every machine.
+ const wasMultiMachine = deviceMultiMachine
+ deviceMultiMachine = Array.isArray(payload.caps) && payload.caps.includes('multi_machine')
+ // Prefer the token-resolved deviceId (trusted); fall back to the self-reported one for legacy fw.
+ const reported = typeof payload.deviceId === 'string' && payload.deviceId ? payload.deviceId : null
+ if (reported && !deviceId) deviceId = reported
+ if (deviceId) startPresence(deviceId) // legacy fw path: deviceId only known after hello
+ if (deviceId) for (const [fid, c] of commanderClients) registry.setClientDeviceId(fid, c.connId, deviceId)
+ // Snapshot what the device just reported, so a client with no socket of its own (the mobile app)
+ // can render firmware/chip/WiFi over REST. BOTH auth modes reach relay(), so this one call covers
+ // the whole fleet — unlike attachSdsBridgeToSocket's own hello listener, which is SDS-only and
+ // exists to feed the MQTT `info` payload.
+ // `ssid`/`rssi` need firmware that puts them in device_hello; until then they simply never appear
+ // and recordHello leaves the columns untouched rather than blanking them.
+ if (deviceId) {
+ const rssiRaw = typeof payload.rssi === 'number' ? payload.rssi
+ : typeof payload.rssi === 'string' ? Number(payload.rssi)
+ : null
+ void deviceService.recordHello({
+ deviceId,
+ firmwareVersion: deviceFirmwareVersion,
+ chip: typeof payload.chip === 'string' ? payload.chip : null,
+ ssid: typeof payload.ssid === 'string' ? payload.ssid : null,
+ rssi: rssiRaw !== null && Number.isFinite(rssiRaw) ? rssiRaw : null,
+ })
+ }
+ logger.info('commander device_hello', { userId, firmwareVersion: deviceFirmwareVersion, deviceId, multiMachine: deviceMultiMachine })
+ if (deviceMultiMachine && !wasMultiMachine) void watchMachines().catch((err) => logger.warn('device watchMachines failed', { userId, error: errMsg(err) }))
+ }
+
+ // ── Ordered (machine-select / RPC / chat) frames ────────────────────────────────────────────────────
+ const ensureActiveReady = async (): Promise<void> => {
+ if (!activeBinding) throw new Error('NO_MACHINE_SELECTED')
+ await ensureMachineReady(activeBinding)
+ }
+
+ const handleFrame = async (msg: CommanderMsg): Promise<void> => {
+ const type = msg.type
+ if (type === 'machine_select') { await bindMachine(payloadOf(msg).machineId); return }
+ if (type === 'machine_deselect') {
+ selectGen++ // cancel any in-flight bindMachine
+ discardVoiceUpload()
+ clearVoiceQueue()
+ // Multi-machine: stop RENDERING a machine but stay attached to all (background badges keep flowing) —
+ // drop the active pointer so no machine streams. Single-attach: detach the one held machine (today).
+ setActiveMachine(null)
+ activeBinding = null
+ if (!deviceMultiMachine) for (const id of [...commanderClients.keys()]) detachCommander(id)
+ return
+ }
+ if (type === 'machines_watch') { await watchMachines(); return }
+ if (type === 'route_confirm') {
+ // The device confirmed (or corrected) a router pick that wasn't auto-dispatched. Dispatch the held
+ // transcript to the chosen agent, resuming its latest session (same path as a fixed-agent voice turn).
+ const p = payloadOf(msg)
+ const routeId = typeof p.routeId === 'string' ? p.routeId : ''
+ const agentId = typeof p.agentId === 'string' ? p.agentId : ''
+ const now = Date.now()
+ for (const [k, v] of pendingRoutes) if (now - v.ts > ROUTE_PENDING_TTL_MS) pendingRoutes.delete(k)
+ const pending = routeId ? pendingRoutes.get(routeId) : undefined
+ if (!pending) { sendDeviceNow({ type: 'error', message: 'route expired' }); return }
+ pendingRoutes.delete(routeId)
+ if (!agentId || agentId === 'new') { sendDeviceNow({ type: 'error', message: 'route needs an agent' }); return } // 'new' (create-agent) is a later phase
+ const ac = activeClient()
+ if (!ac) { sendDeviceNow({ type: 'error', message: 'NO_MACHINE_SELECTED' }); return }
+ try {
+ await ensureActiveReady()
+ sendDeviceNow({ type: 'commander_event', agentId, payload: { kind: 'processing' } })
+ currentTurnAgentId = agentId
+ const confirmContent = withCommand(pending.text, pending.goal, pending.loop === true)
+ ac.sendDown({ type: 'message', payload: { content: confirmContent, agentId, mode: 'auto', resumeLatest: true } } as Frame)
+ sendDeviceNow({ type: 'dispatched' })
+ logger.info('commander route_confirm dispatch', { userId, machineId: activeMachineId, agentId })
+ } catch (err) {
+ sendDeviceNow({ type: 'error', message: errMsg(err) })
+ }
+ return
+ }
+ // User actions must survive an idle stop. The strict frameChain holds them until the node has
+ // re-registered; background multi-machine E2EE frames intentionally bypass this active-machine wake.
+ if (type === 'message' || type === 'agents_list' || type === 'agent_create' || type === 'agent_recent' || type === 'agent_update' || type === 'models_list') {
+ try {
+ await ensureActiveReady()
+ } catch (err) {
+ const requestId = payloadOf(msg).requestId
+ if (typeof requestId === 'string' && type !== 'message') {
+ sendDeviceNow({ type: `${type}_result`, payload: { requestId, error: errMsg(err) } })
+ } else {
+ sendDeviceNow({ type: 'error', message: errMsg(err) })
+ }
+ return
+ }
+ }
+ if (type === 'agents_list' || type === 'agent_create' || type === 'agent_recent' || type === 'agent_update' || type === 'models_list') {
+ // Only remote adapter machines may use the E2EE relay path. Local managed/self machines still answer
+ // through backend-owned nodeRequest; relaying these RPCs to agent-node leaves the device hanging
+ // because that node path does not implement the device's agents_list RPC contract.
+ //
+ // Judged on the TARGET machine, not the active one. A multi_machine device (the harness daemon
+ // driving a cabled dial) shows every machine's agents at once and tags each RPC with the machine it
+ // is about, so reading `activeRemote()` here would send a question about machine B down machine A's
+ // path — and it would be ANSWERED, with A's agents, which is indistinguishable from B having them.
+ if (!targetRemote(msg)) { await handleAgentRpc(msg); return }
+
+ // Remote adapter machines: never use backend-terminated nodeRequest here. Without E2EE-data support
+ // the old plaintext bridge would let backend read adapter data, so fail closed.
+ if (!deviceE2eeData) {
+ const requestId = payloadOf(msg).requestId
+ sendDevice({ type: `${type}_result`, payload: { requestId, error: 'E2EE_REQUIRED' } })
+ return
+ }
+ // E2EE-capable firmware on remote adapter machines: relay the RPC to the machine like webWs
+ // (fall through to sendDown below). The adapter encrypts content-bearing results per connId-session.
+ }
+ if (type === 'message') {
+ const p = payloadOf(msg)
+ currentTurnAgentId = (typeof p.agentId === 'string' ? p.agentId : undefined) ?? (typeof msg.agentId === 'string' ? msg.agentId : null)
+ logger.info('commander turn_start', { userId, machineId: activeMachineId, agentId: currentTurnAgentId, source: 'typed' })
+ }
+ // Multi-attach: a frame the device explicitly targets at a specific machine (eager E2EE hello/handshake to a
+ // BACKGROUND machine, so its recaps can be decrypted without the user opening it) routes to THAT machine's
+ // node — not the active one. Ownership-safe: commanderClients only holds this user's attached machines. Only
+ // device-tagged frames (e2e_*) carry msg.machineId; message/RPC never do, so the active path is unaffected.
+ if (typeof msg.machineId === 'string' && commanderClients.has(msg.machineId)) {
+ commanderClients.get(msg.machineId)!.sendDown(msg as Frame)
+ return
+ }
+ const ac = activeClient()
+ if (ac) { ac.sendDown(msg as Frame); return } // normal commander frame → down to the ACTIVE node
+ // No machine selected: fast-fail RPCs (echo the requestId) so the device's request() doesn't hang.
+ const requestId = payloadOf(msg).requestId
+ if (typeof requestId === 'string' && typeof type === 'string') {
+ sendDeviceNow({ type: `${type}_result`, payload: { requestId, error: 'NO_MACHINE_SELECTED' } })
+ }
+ }
+
+ // Device → backend. Binary is voice PCM (buffered for STT); JSON is routed by type. Voice + hello are
+ // synchronous; machine-select / RPC / chat go through a strict in-order chain (bindMachine awaits a DB
+ // lookup, and a machine_select followed immediately by agents_list must not be routed by the PREVIOUS
+ // selection — the same leak webWs guards against).
+ let frameChain: Promise<void> = Promise.resolve()
+ device.on('message', (raw: RawData, isBinary: boolean) => {
+ if (isBinary) {
+ if (voiceActive) {
+ const buf = raw as Buffer
+ if (voiceSize + buf.length <= MAX_PCM) {
+ chunks.push(buf)
+ voiceSize += buf.length
+ armVoiceIdleTimer()
+ }
+ }
+ return // audio is NOT forwarded upstream; non-voice binary is dropped
+ }
+ let msg: CommanderMsg
+ try { msg = JSON.parse(raw.toString()) } catch { return }
+ if (msg.type === 'voice_start' || msg.type === 'voice_ask_start') { startVoice(msg); return }
+ if (msg.type === 'voice_end') { void finishVoice(); return }
+ if (msg.type === 'voice_resume') { void handleVoiceResume(msg); return }
+ if (msg.type === 'device_hello') { handleHello(msg); return }
+ frameChain = frameChain
+ .then(() => handleFrame(msg))
+ .catch((err) => logger.warn('commander frame failed', { userId, type: msg.type, error: errMsg(err) }))
+ })
+ device.on('close', closeBoth)
+ device.on('error', closeBoth)
+
+ // Seed the live machine list right away so the picker is instant when the user opens Settings → Machines;
+ // the device then drives selection with machine_select (or its saved-machine auto-select on connect).
+ void subscribeDeviceMachineListChanged(userId, (msg) => {
+ logger.info('device machine list changed — refreshing picker', { userId, reason: msg.reason })
+ void watchMachines().catch((err) => logger.warn('device watchMachines failed', { userId, error: errMsg(err) }))
+ }).then((unsub) => {
+ if (closed) { unsub(); return }
+ machineListUnsub = unsub
+ })
+ void watchMachines().catch((err) => logger.warn('device watchMachines failed', { userId, error: errMsg(err) }))
+
+ async function finishVoice(): Promise<void> {
+ if (!voiceActive) return
+ clearVoiceTimers()
+ voiceActive = false
+ const pcm = Buffer.concat(chunks); chunks = []; voiceSize = 0
+ if (deviceId && voiceUploadId) void evictVoiceUpload(deviceId) // finalizing → the parked copy is obsolete
+ const uploadId = voiceUploadId ?? randomUUID()
+ const quotaCheck = voiceQuotaCheck
+ const machineId = voiceMachineId ?? activeMachineId
+ voiceUploadId = null
+ voiceMachineId = null
+ voiceQuotaCheck = null
+ const agentId = voiceAgentId
+ const sessionId = voiceSessionId
+ const sr = voiceSr
+ const lang = voiceLang
+ const mode = voiceMode
+ const goal = voiceGoal
+ const loop = voiceLoop
+ const autonomy = voiceAutonomy
+ const requestId = voiceRequestId
+ const route = voiceRoute
+ voiceMode = 'turn'; voiceGoal = false; voiceLoop = false; voiceAutonomy = 'auto'; voiceRequestId = null; voiceRoute = false
+ const ac = machineId ? commanderClients.get(machineId) ?? null : null
+ const remote = machineId ? machineRemote.get(machineId) ?? false : false
+ logger.info('commander voice_end', { userId, machineId, mode, agentId, bytes: pcm.length, sr })
+ flushVoiceQueue('voice_end')
+ try {
+ if (!machineId || !ac) throw new Error('no machine selected')
+ if (!route && !agentId) throw new Error('no agentId')
+ // Duration-based floor (~300 ms) — works at any sample rate; sub-300ms clips hallucinate.
+ if (pcm.length < ((sr * 2) / 1000) * 300) { sendDeviceNow({ type: 'too_short', requestId }); return }
+ if (!route && !remote) {
+ const owned = await prisma.machineAgent.findFirst({ where: { machineId, agentId: agentId! } })
+ if (!owned) throw new Error('agent not on this machine')
+ }
+ if (quotaCheck) await quotaCheck
+ const voiceBinding = activeBinding?.machineId === machineId
+ ? activeBinding
+ : await prisma.machine.findUnique({ where: { machineId } })
+ if (!voiceBinding || voiceBinding.deletedAt) throw new Error('machine not found')
+ const durationMs = pcm.length / ((sr * 2) / 1000)
+ const reservation = await voiceQuotaService.reserve(machineId, uploadId, durationMs)
+ if (reservation.state !== 'reserved') {
+ logger.info('commander duplicate voice upload ignored', {
+ userId,
+ machineId,
+ uploadId,
+ state: reservation.state,
+ })
+ sendDeviceNow({ type: 'empty' })
+ return
+ }
+ const transcribeReserved = async (): Promise<string> => {
+ try {
+ const text = await transcribe(pcm, sr, lang)
+ await voiceQuotaService.commit(uploadId)
+ return text
+ } catch (err) {
+ await voiceQuotaService.release(uploadId).catch(() => { /* worker releases stale pending */ })
+ throw err
+ }
+ }
+
+ // Dispatch a transcribed turn to `targetId`, resuming its latest session unless a specific one is
+ // given. Re-asserts the "processing" indicator on that agent while the turn's own events start.
+ const dispatchTurn = async (targetId: string, content: string, sess: string | null, aut: 'plan' | 'auto'): Promise<void> => {
+ sendDeviceNow({ type: 'commander_event', agentId: targetId, dbSessionId: sess ?? undefined, payload: { kind: 'processing' } })
+ const payload = sess
+ ? { content, agentId: targetId, mode: aut, sessionId: sess }
+ : { content, agentId: targetId, mode: aut, resumeLatest: true }
+ currentTurnAgentId = targetId
+ await ensureMachineReady(voiceBinding)
+ ac.sendDown({ type: 'message', payload } as Frame)
+ sendDeviceNow({ type: 'dispatched' })
+ }
+
+ // ── ROUTE MODE (voice from Overview): transcribe, ask the router which agent should handle it, then
+ // auto-dispatch on high confidence or push a `voice_routed` for the device to confirm/pick.
+ if (route) {
+ const text = await transcribeReserved()
+ sendDeviceNow({ type: 'transcript', requestId, text })
+ if (!text) { sendDeviceNow({ type: 'empty' }); return }
+ const d = await nodeRequest<{ agentId?: string; agentName?: string; confidence?: number; reason?: string; needNewAgent?: boolean }>(
+ machineId, 'voice_route', { transcript: text },
+ )
+ const agentId = typeof d.agentId === 'string' ? d.agentId : ''
+ const agentName = typeof d.agentName === 'string' ? d.agentName : ''
+ const confidence = typeof d.confidence === 'number' ? d.confidence : 0
+ const reason = typeof d.reason === 'string' ? d.reason : ''
+ const needNewAgent = d.needNewAgent === true
+ logger.info('commander voice_route', { userId, machineId, agentId, agentName, confidence, needNewAgent })
+ // Overview mode select: the routed transcript becomes a "/goal <text>" or "/loop <text>" command
+ // on whichever agent the router picked.
+ const routedContent = withCommand(text, goal, loop)
+ if (agentId && !needNewAgent && confidence >= ROUTE_AUTO_THRESHOLD) {
+ sendDeviceNow({ type: 'voice_routed', autoSent: true, agentId, agentName, confidence, reason })
+ await dispatchTurn(agentId, routedContent, null, 'auto')
+ } else {
+ const routeId = randomUUID()
+ pendingRoutes.set(routeId, { text, goal, loop, ts: Date.now() })
+ sendDeviceNow({ type: 'voice_routed', autoSent: false, routeId, agentId, agentName, confidence, reason, needNewAgent })
+ }
+ return
+ }
+
+ // ── FIXED-AGENT MODE (voice from a specific tile): "processing" heartbeat over the STT gap, dispatch.
+ const beat = () => sendDeviceNow({
+ type: 'commander_event', agentId: agentId!, dbSessionId: sessionId ?? undefined, payload: { kind: 'processing' },
+ })
+ // Bare terminal 'done' (no text) = clear the "processing" busy WITHOUT a card (empty transcript / ask).
+ const clearBusy = () => sendDeviceNow({
+ type: 'commander_event', agentId: agentId!, dbSessionId: sessionId ?? undefined, payload: { kind: 'done' },
+ })
+ beat()
+ const hb = setInterval(beat, 5000)
+ let text: string
+ try { text = await transcribeReserved() } finally { clearInterval(hb) }
+ sendDeviceNow({ type: 'transcript', requestId, text })
+ // 'ask' mode = answering an AskUserQuestion: just return the transcript, never dispatch a turn.
+ if (mode === 'ask') { clearBusy(); return }
+ if (text) {
+ // GOAL command → send the transcript as the "/goal <text>" slash-command so the agent sets a
+ // persistent goal instead of running it as a one-off prompt.
+ const content = withCommand(text, goal, loop)
+ logger.info('commander turn_start', { userId, machineId, agentId, sessionId, goal, mode: autonomy, source: 'voice' })
+ await dispatchTurn(agentId!, content, sessionId, autonomy)
+ } else {
+ clearBusy()
+ sendDeviceNow({ type: 'empty' })
+ }
+ } catch (err) {
+ logger.warn('commander voice failed', { userId, error: errMsg(err) })
+ if (agentId) sendDeviceNow({ type: 'commander_event', agentId: agentId, dbSessionId: sessionId ?? undefined, payload: { kind: 'done' } })
+ if (err instanceof VoiceQuotaExceededError) {
+ sendDeviceNow({ type: 'voice_quota_exceeded', payload: { ...err.snapshot, uploadId } })
+ } else {
+ sendDeviceNow({ type: 'error', message: errMsg(err) })
+ }
+ }
+ }
+
+ /** The machine a device frame is about: its own tag when it names an attached machine, else the active one. */
+ function targetMachine(msg: CommanderMsg): string | null {
+ const tagged = typeof msg.machineId === 'string' ? msg.machineId : ''
+ // `commanderClients.has` is the ownership check: it only ever holds machines this user's socket
+ // attached, so a self-declared id cannot reach anybody else's machine.
+ return tagged && commanderClients.has(tagged) ? tagged : activeMachineId
+ }
+ const targetRemote = (msg: CommanderMsg): boolean => {
+ const id = targetMachine(msg)
+ return id ? machineRemote.get(id) ?? false : false
+ }
+
+ async function handleAgentRpc(msg: CommanderMsg): Promise<void> {
+
+ const payload = payloadOf(msg)
+ const requestId = payload.requestId
+ const resultType =
+ msg.type === 'agents_list' ? 'agents_list_result'
+ : msg.type === 'agent_create' ? 'agent_create_result'
+ : msg.type === 'agent_update' ? 'agent_update_result'
+ : msg.type === 'models_list' ? 'models_list_result'
+ : 'agent_recent_result'
+ const machineId = targetMachine(msg)
+ if (!machineId) { sendDeviceNow({ type: resultType, payload: { requestId, error: 'NO_MACHINE_SELECTED' } }); return }
+
+ try {
+ if (msg.type === 'agents_list') {
+ const r = await nodeRequest<{ agents?: unknown }>(machineId, 'agents_list', {})
+ const rawAgents = Array.isArray(r?.agents) ? r.agents : []
+ // Keep the list metadata-only. The device restores recap/summary lazily via one agent_recent RPC at
+ // a time so large machines never produce a giant agents_list_result frame.
+ const projects = rawAgents.slice(0, DEVICE_AGENT_LIST_LIMIT).map(deviceAgentListItem)
+ sendDevice({ type: 'agents_list_result', payload: { requestId, agents: projects } })
+ return
+ }
+
+ if (msg.type === 'agent_create') {
+ const { count, max } = await agentLimit(machineId)
+ if (count >= max) {
+ sendDevice({ type: 'agent_create_result', payload: { requestId, error: 'AGENT_LIMIT' } })
+ return
+ }
+ const name = typeof payload.name === 'string' && payload.name.trim() ? payload.name : 'Agent'
+ const r = await nodeRequest<{ agent?: { id?: unknown; name?: unknown } }>(machineId, 'agent_create', { name })
+ await recordCreatedAgent(machineId, r?.agent)
+ const projObj = (r?.agent ?? {}) as Record<string, unknown>
+ const project = r?.agent ? { id: projObj.id, name: projObj.name } : null
+ sendDevice({ type: 'agent_create_result', payload: { requestId, agent: project } })
+ return
+ }
+
+ if (msg.type === 'agent_update') {
+ // Device per-agent Model control → persist to Project.selectedModel on the node (read back at each
+ // turn for --model). Fire-and-forget from the device; we still ack so it isn't left hanging.
+ const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
+ if (!agentId) throw new Error('MISSING_AGENT_ID')
+ const selectedModel = 'selectedModel' in payload ? (payload.selectedModel as string | null) : undefined
+ await nodeRequest(machineId, 'agent_update', { agentId: agentId, selectedModel })
+ sendDevice({ type: 'agent_update_result', payload: { requestId } })
+ return
+ }
+
+ if (msg.type === 'models_list') {
+ // Terminated HERE for the same reason the other four are, and it is not symmetry for its own
+ // sake: `hub.deliverUpLocal` drops every `*_result` frame addressed to a commander client unless
+ // it carries a targetConnId, and managers never set one. Relayed, this reply is eaten in transit
+ // and the dial's Model picker sits empty forever with nothing logged anywhere.
+ const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
+ const r = await nodeRequest<{ models?: unknown }>(machineId, 'models_list', {
+ agentId,
+ compact: payload.compact === true,
+ pickerMode: typeof payload.pickerMode === 'string' ? payload.pickerMode : undefined,
+ selectedModel: typeof payload.selectedModel === 'string' ? payload.selectedModel : undefined,
+ })
+ const models = Array.isArray(r?.models) ? r.models : []
+ sendDevice({ type: 'models_list_result', payload: { requestId, agentId, models } })
+ return
+ }
+
+ if (msg.type === 'agent_recent') {
+ const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
+ if (!agentId) throw new Error('MISSING_AGENT_ID')
+ const nRaw = typeof payload.n === 'number' || typeof payload.n === 'string' ? parseInt(String(payload.n), 10) : 2
+ const n = Number.isFinite(nRaw) && nRaw > 0 ? nRaw : 2
+ const r = await nodeRequest<{ events?: unknown }>(machineId, 'agent_recent', { agentId: agentId, n })
+ // Trim to kind + text + optional recap headline (the device drops everything else).
+ const events = trimRecentEvents(r?.events, n, requestId, agentId)
+ sendDevice({ type: 'agent_recent_result', payload: { requestId, agentId: agentId, events } })
+ }
+ } catch (err) {
+ sendDevice({ type: resultType, payload: { requestId, error: errMsg(err) } })
+ }
+ }
+}
diff --git a/backend/src/lib/gemini.ts b/backend/src/lib/gemini.ts
new file mode 100644
index 000000000..c7760d5b9
--- /dev/null
+++ b/backend/src/lib/gemini.ts
@@ -0,0 +1,102 @@
+import { env } from '../config/env.js'
+import { logger } from '../utils/logger.js'
+
+// Gemini batch STT for the device voice endpoint. The device streams raw linear16/16k/mono PCM;
+// Gemini's inline audio wants a container, so we prepend a 44-byte WAV header and send audio/wav.
+
+const CHANNELS = 1
+const BITS = 16
+
+// Minimal canonical WAV (PCM) header for the given data length at `sampleRate` Hz.
+function wavHeader(dataLen: number, sampleRate: number): Buffer {
+ const byteRate = (sampleRate * CHANNELS * BITS) / 8
+ const blockAlign = (CHANNELS * BITS) / 8
+ const h = Buffer.alloc(44)
+ h.write('RIFF', 0)
+ h.writeUInt32LE(36 + dataLen, 4)
+ h.write('WAVE', 8)
+ h.write('fmt ', 12)
+ h.writeUInt32LE(16, 16) // fmt chunk size
+ h.writeUInt16LE(1, 20) // PCM
+ h.writeUInt16LE(CHANNELS, 22)
+ h.writeUInt32LE(sampleRate, 24)
+ h.writeUInt32LE(byteRate, 28)
+ h.writeUInt16LE(blockAlign, 32)
+ h.writeUInt16LE(BITS, 34)
+ h.write('data', 36)
+ h.writeUInt32LE(dataLen, 40)
+ return h
+}
+
+// Instruction goes in systemInstruction (not the user turn) so the model treats it as a rule,
+// not content to reason about — this keeps thinking-capable models from echoing deliberation.
+const SYSTEM =
+ 'You transcribe audio to plain text. Output ONLY the exact words spoken, as a single line of ' +
+ 'plain text. Absolutely do NOT add timestamps, time codes, "-->" ranges, SRT or WebVTT/caption ' +
+ 'formatting, speaker names, brackets, or notes. Do NOT apologize, refuse, or explain — even if ' +
+ 'the audio is short, noisy, or unclear, just write the words you hear. If you truly hear no ' +
+ 'words at all, output nothing (an empty response).'
+
+// Belt-and-suspenders: strip caption artifacts the model sometimes emits despite the instruction
+// (SRT/VTT timestamps, cue numbers, the WEBVTT header) so they never reach the agent as a turn.
+function cleanTranscript(raw: string): string {
+ return raw
+ .replace(/^?WEBVTT.*$/gim, '')
+ // "00:00:00,000 --> 00:00:01,000" (also ':' or '.' as the ms separator)
+ .replace(/\d{1,2}:\d{2}:\d{2}[.,:]\d{1,3}\s*-->\s*\d{1,2}:\d{2}:\d{2}[.,:]\d{1,3}.*$/gim, '')
+ .replace(/^\s*\d+\s*$/gm, '') // lone SRT cue numbers
+ .replace(/\s+/g, ' ')
+ .trim()
+}
+
+/** Transcribe raw linear16/mono PCM at `sampleRate` Hz via Gemini. Returns the transcript ('' if none). */
+export async function transcribe(pcm: Buffer, sampleRate = 16000): Promise<string> {
+ if (!env.GEMINI_API_KEY) throw new Error('GEMINI_API_KEY not set')
+ const wav = Buffer.concat([wavHeader(pcm.length, sampleRate), pcm])
+ const url =
+ `https://generativelanguage.googleapis.com/v1beta/models/${env.GEMINI_STT_MODEL}:generateContent` +
+ `?key=${env.GEMINI_API_KEY}`
+
+ const payload = JSON.stringify({
+ systemInstruction: { parts: [{ text: SYSTEM }] },
+ contents: [
+ {
+ parts: [
+ { text: 'Transcribe:' },
+ { inline_data: { mime_type: 'audio/wav', data: wav.toString('base64') } },
+ ],
+ },
+ ],
+ // thinkingBudget 0 disables 2.5 "thinking" — STT needs none, and it keeps latency low and
+ // stops the model from deliberating/refusing instead of just transcribing.
+ generationConfig: { temperature: 0, thinkingConfig: { thinkingBudget: 0 } },
+ })
+
+ // Retry transient overload (503/UNAVAILABLE, 429) with backoff — flash-lite spikes are common.
+ let res!: Response
+ for (let attempt = 0; attempt < 4; attempt++) {
+ res = await fetch(url, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: payload,
+ })
+ if (res.ok || (res.status !== 503 && res.status !== 429)) break
+ const backoff = 400 * 2 ** attempt // 400, 800, 1600 ms
+ logger.warn('gemini transient error — retrying', { status: res.status, attempt, backoff })
+ await new Promise((r) => setTimeout(r, backoff))
+ }
+ if (!res.ok) {
+ const body = await res.text().catch(() => '')
+ throw new Error(`Gemini HTTP ${res.status}: ${body.slice(0, 200)}`)
+ }
+ const data = (await res.json()) as {
+ candidates?: Array<{ content?: { parts?: Array<{ text?: string; thought?: boolean }> } }>
+ }
+ const rawText = (data.candidates?.[0]?.content?.parts ?? [])
+ .filter((p) => !p.thought) // drop reasoning parts from thinking models
+ .map((p) => p.text ?? '')
+ .join('')
+ const transcript = cleanTranscript(rawText)
+ logger.info('gemini transcript', { chars: transcript.length, model: env.GEMINI_STT_MODEL })
+ return transcript
+}
diff --git a/backend/src/lib/hub.ts b/backend/src/lib/hub.ts
new file mode 100644
index 000000000..3eaae0fd8
--- /dev/null
+++ b/backend/src/lib/hub.ts
@@ -0,0 +1,381 @@
+/**
+ * Shared client-hub plumbing used by both terminating endpoints — web (`lib/webWs.ts`) and device
+ * (`lib/deviceWs.ts`). A client (web or commander) attaches here; the hub:
+ * - registers it (so client-counts + the `__clients` presence signal to the node are right),
+ * - ensures ONE up:{machineId} Redis subscription per agent on this instance that fans events to all
+ * local clients (web get everything with webEligible; commander gets commanderEligible only),
+ * - exposes publishClientDown for the caller to send client→node messages.
+ */
+import { WebSocket } from 'ws'
+import { randomUUID } from 'crypto'
+import {
+ bumpCommanderJoinGeneration,
+ getAgentClientTotals,
+ getCommanderJoinGeneration,
+ publishDown,
+ publishTerminalDown,
+ publishUp,
+ setAgentClientCount,
+ subscribeUp,
+ subscribeTerminalUp,
+} from './bus.js'
+import { INSTANCE_ID } from './instance.js'
+import * as registry from './registry.js'
+import type { ClientKind } from './registry.js'
+import type { Frame, UpBusMsg } from './tunnel.js'
+import { routeDown } from './providerLink.js'
+import { logger } from '../utils/logger.js'
+import { decodeTerminalHop, encodeTerminalHop, TerminalHopDirection } from './terminalBinary.js'
+
+// Reserved inner-frame type: backend→node client-presence signal (drives the node's event buffering
+// and replay-on-connect + commander recap warm). Never surfaced to a real client.
+export const CLIENTS_FRAME = '__clients'
+
+// Reserved down-frame type: a client-holding backend pokes B_m (the manager-socket owner) to recompute
+// + re-emit CLIENTS_FRAME from the GLOBAL total. Intercepted in managerWs's down subscription — never
+// forwarded to the node.
+export const CLIENTS_DIRTY = '__clients_dirty'
+
+// machineId → unsubscribe for the single up:{machineId} subscription held while ≥1 local client exists.
+const upSubs = new Map<string, () => void>()
+const terminalUpSubs = new Map<string, () => void>()
+
+export function deliverTerminalUpLocal(machineId: string, packet: Uint8Array): void {
+ const decoded = decodeTerminalHop(packet)
+ if (!decoded || decoded.direction !== TerminalHopDirection.up) return
+ const client = registry.clientsFor(machineId).find((candidate) => candidate.kind === 'web' && candidate.connId === decoded.connId)
+ if (!client || client.socket.readyState !== WebSocket.OPEN) return
+ try { client.socket.send(decoded.clientFrame) } catch { /* ignore */ }
+}
+
+/** Deliver an up-frame to every local client of the agent (device/exclude filters applied). Called both
+ * directly by the manager-ws 'up' handler (co-located fast-path) and from the Redis up subscription. */
+export function deliverUpLocal(machineId: string, msg: UpBusMsg): void {
+ const payload = JSON.stringify(msg.frame)
+ const frameType = (msg.frame as { type?: string }).type
+ // A device (commander) socket holds N machines at once (multi-attach) → tag the OUTER frame with its
+ // machineId (= machineId) so the device can route/badge/pick-its-E2EE-key WITHOUT decrypting the payload.
+ // The payload itself is untouched (stays E2EE-encrypted for remote machines). Web sockets re-attach per
+ // agent (one machine at a time) so they never need it — keep their wire byte-identical. Computed lazily.
+ let commanderPayload: string | null = null
+ for (const c of registry.clientsFor(machineId)) {
+ if (msg.excludeConnId && c.connId === msg.excludeConnId) continue
+ // Device-targeted push (e.g. device_revoked): only the commander socket whose reported deviceId
+ // matches. A socket that hasn't reported one (legacy fw / pre-hello) never matches — harmless.
+ if (msg.targetDeviceId && c.deviceId !== msg.targetDeviceId) continue
+ // Connection-targeted push (E2EE pairing/welcome + per-client encrypted RPC replies): only the
+ // one web socket that owns this connId. Absent ⇒ normal fan-out.
+ if (msg.targetConnId && c.connId !== msg.targetConnId) continue
+ if (msg.targetKind && c.kind !== msg.targetKind) continue
+ // A `targetConnId`-addressed frame is E2EE traffic for exactly ONE connection (pairing/welcome/rekey,
+ // per-client encrypted RPC replies) — for a WEB browser OR a hardware device. It bypasses the
+ // kind/eligibility/`_result` filters below: those trim the broadcast fan-out, but a connId-targeted
+ // frame is not a broadcast. Without this, `e2e_status_result` etc. never reach a paired device
+ // (commanders are filtered by `!commanderEligible` and by the `_result` suppression).
+ if (!msg.targetConnId) {
+ if (c.kind === 'web' && msg.webEligible === false) continue // device-only frame (forwardToCommander)
+ if (c.kind === 'commander' && !msg.commanderEligible) continue // preserve COMMANDER_FORWARD filter
+ // RPC replies (`<x>_result`) are answered to the device directly by deviceWs (trimmed); the
+ // raw node reply must never reach a device — it's only for the backend nodeRequest awaiter / web.
+ if (c.kind === 'commander' && typeof frameType === 'string' && frameType.endsWith('_result')) continue
+ }
+ // Commander gets the machineId-tagged frame; web gets the untagged one.
+ const out = c.kind === 'commander'
+ ? (commanderPayload ??= JSON.stringify({ ...(msg.frame as Record<string, unknown>), machineId: machineId }))
+ : payload
+ if (c.kind === 'commander' && registry.queueCommanderFrame(machineId, c.connId, msg.frame, out)) continue
+ if (c.socket.readyState === WebSocket.OPEN) {
+ try { c.socket.send(out) } catch { /* ignore */ }
+ }
+ }
+}
+
+/**
+ * Push a `device_revoked` frame to the ONE just-revoked device so it wipes its pairing and reboots to
+ * the pair screen. Targeted by deviceId (set on the ClientConn from device_hello), so sibling devices of
+ * the same agent are untouched. Published to up:{machineId} → every instance delivers, but the
+ * targetDeviceId filter in deliverUpLocal means only the instance holding that socket actually sends it.
+ */
+export function pushDeviceRevoked(machineId: string, deviceId: string): void {
+ void publishUp(machineId, {
+ webEligible: false,
+ commanderEligible: true,
+ targetDeviceId: deviceId,
+ frame: { type: 'device_revoked' },
+ })
+}
+
+/**
+ * Publish this instance's local client counts and make the node's `__clients` frame reflect the GLOBAL
+ * total. `registry.clientCounts` is per-process, so a naive publish would let another instance's snapshot
+ * clobber ours at the node (last-writer-wins). Instead: write our field to Redis, then have exactly ONE
+ * writer — B_m, the instance holding this agent's manager control socket — emit the summed frame in-order
+ * over that socket. If we're not B_m, poke B_m (via down:{machineId}, whose sole subscriber IS B_m).
+ * Call after the local registry mutation (attach/detach) so clientCounts reflects the new state.
+ */
+export async function sendClientsControl(machineId: string, commanderJoined = false): Promise<void> {
+ const { ui, commander, commanderActive } = registry.clientCounts(machineId) // capture sync (post-mutation), before await
+ await setAgentClientCount(machineId, INSTANCE_ID, ui, commander, commanderActive)
+ // Count snapshots can coalesce (1→0→1 may be observed as 1→1). Persist a separate join generation so
+ // every real commander attach still forces the node/adapter to replay its live state.
+ if (commanderJoined) await bumpCommanderJoinGeneration(machineId)
+ if (registry.controlSocketFor(machineId)) { await recomputeAndSendClients(machineId); return }
+ void publishDown(machineId, { connId: '', frame: { type: CLIENTS_DIRTY } })
+}
+
+/** B_m-only: read the cross-instance total and emit `__clients` down the local manager control socket
+ * (single in-order writer → the node's last frame is always the true global state). */
+export async function recomputeAndSendClients(machineId: string): Promise<void> {
+ const [{ ui, commander, commanderActive }, commanderJoinGeneration] = await Promise.all([
+ getAgentClientTotals(machineId),
+ getCommanderJoinGeneration(machineId),
+ ])
+ const frame = {
+ type: CLIENTS_FRAME,
+ payload: { ui, commander, commanderActive, ...(commanderJoinGeneration != null ? { commanderJoinGeneration } : {}) },
+ }
+ const local = registry.controlSocketFor(machineId)
+ if (local && local.readyState === WebSocket.OPEN) {
+ try { local.send(JSON.stringify({ t: 'down', machineId: machineId, connId: '', frame })) } catch { /* ignore */ }
+ return
+ }
+ // B_m's control socket briefly gone (mid-failover) → best-effort via Redis (sole subscriber is B_m).
+ void publishDown(machineId, { connId: '', frame })
+}
+
+export interface HubClient {
+ connId: string
+ /** Send a client→node message (chat/control). */
+ sendDown: (frame: Frame) => void
+ /** Send an opaque E2EE terminal input frame over the binary relay. */
+ sendTerminalDown: (clientFrame: Uint8Array) => void
+ /** Mark this client as the actively-rendered machine (commander multi-attach) → re-emits `__clients` with
+ * the updated `commanderActive` count so the node/adapter can gate full-stream cards. No-op if unchanged. */
+ setActive: (active: boolean) => void
+ /** Call on socket close/error. */
+ detach: () => void
+}
+
+type Alive = WebSocket & {
+ __hubLastAlive?: number
+ __hubLastPing?: number
+ __hubDeadlineMs?: number
+ __hubLivenessWired?: boolean
+}
+
+// Liveness is a DEADLINE ON SILENCE, not a count of sweeps. Counting tied how fast a dead peer is noticed
+// to how often we ping, so making detection quicker also meant pinging every client harder. Splitting the
+// two lets the tick be short (prompt detection, no 25s rounding) while each socket keeps its own patience.
+/** How often liveness is evaluated. Cheap — it only walks local sockets. */
+export const LIVENESS_TICK_MS = 5_000
+/** Silence tolerated from a BROWSER. It cannot ping on its own, sits behind proxies/LBs, and a tab in a
+ * background window gets throttled — so it keeps the long-standing generous window. */
+export const CLIENT_IDLE_DEADLINE_MS = 75_000
+/** Silence tolerated from a DEVICE. The firmware opens the socket with `ping_interval_sec = 15`
+ * (apps/esp32-circle/main/commander_client.c), so it proves itself every 15s without us asking. Two missed
+ * device pings is already conclusive; waiting out the browser-sized window just left the web showing a
+ * green dot for a device that had been unplugged for over a minute. */
+export const DEVICE_IDLE_DEADLINE_MS = 35_000
+
+/** Wire the once-per-socket liveness listeners. Any inbound frame proves the peer and path are alive:
+ * application messages (including device PCM chunks) and peer ping frames count as well as pong, so a
+ * delayed control-frame pong cannot terminate a socket that is actively sending data. */
+function wireLiveness(socket: WebSocket): void {
+ if ((socket as Alive).__hubLivenessWired) return
+ ;(socket as Alive).__hubLivenessWired = true
+ const markAlive = (): void => { (socket as Alive).__hubLastAlive = Date.now() }
+ socket.on('message', markAlive)
+ socket.on('ping', markAlive)
+ socket.on('pong', markAlive)
+}
+
+// Sockets that must be kept alive even while they hold ZERO hub clients: a device socket only enters the
+// client registry once it attaches to a machine (deviceWs.attachCommander), and a web socket parked on
+// the Machines page has no agent selected. Neither was reachable by a registry-driven sweep, so a
+// half-open drop (WiFi cut / power loss, no FIN) left 'close' unfired forever — presence key refreshed on
+// a timer, MQTT bridge held, web dot green. Tracked sockets ride the SAME sweep, so policy lives in one
+// place instead of each endpoint growing its own heartbeat.
+const trackedSockets = new Set<WebSocket>()
+
+/** Keep `socket` in the liveness sweep regardless of hub-client attachment, with an optional custom
+ * silence deadline (the deadline is stored ON the socket, so it still applies once clients attach).
+ * Returns the release fn. */
+export function trackSocketLiveness(socket: WebSocket, deadlineMs?: number): () => void {
+ ;(socket as Alive).__hubLastAlive ??= Date.now()
+ if (deadlineMs != null) (socket as Alive).__hubDeadlineMs = deadlineMs
+ wireLiveness(socket)
+ trackedSockets.add(socket)
+ return () => { trackedSockets.delete(socket) }
+}
+
+/** Ping the socket, or terminate it once it has been silent past its deadline. Returns false when the
+ * socket is not OPEN — the caller decides what that means for the thing holding it. */
+function pingOrTerminate(ws: Alive, info: Record<string, unknown>): boolean {
+ if (ws.readyState !== WebSocket.OPEN) return false
+ const now = Date.now()
+ const deadline = ws.__hubDeadlineMs ?? CLIENT_IDLE_DEADLINE_MS
+ const idleMs = now - (ws.__hubLastAlive ??= now)
+ if (idleMs >= deadline) {
+ logger.warn('hub client heartbeat timed out', { ...info, idleMs, deadline })
+ try { ws.terminate() } catch { /* ignore */ }
+ return true
+ }
+ // Three chances to answer inside the window, so a single lost control frame is never fatal.
+ const pingEvery = Math.max(LIVENESS_TICK_MS, Math.floor(deadline / 3))
+ if (now - (ws.__hubLastPing ?? 0) >= pingEvery) {
+ ws.__hubLastPing = now
+ try { ws.ping() } catch { /* ignore */ }
+ }
+ return true
+}
+
+// Liveness sweep. Deliberately separate from the count refresh below: this one wants to run often (a
+// deadline you only check every 25s is really a deadline plus up to 25s), while the Redis writes down
+// there must NOT get 5× more frequent.
+setInterval(() => {
+ // Evaluate each SOCKET once per tick. Under device multi-attach ONE socket backs N commander
+ // ClientConns (one per machine), so a per-client loop would ping the same socket N times a tick.
+ const swept = new Set<WebSocket>()
+ const clients = registry.allClients()
+ const orphaned = new Set<WebSocket>() // closed sockets whose clients were never detached
+ for (const c of clients) {
+ const ws = c.socket as Alive
+ if (swept.has(ws)) continue
+ swept.add(ws)
+ if (!pingOrTerminate(ws, { machineId: c.machineId, kind: c.kind, connId: c.connId })) orphaned.add(ws)
+ }
+ // Sockets kept alive on their own (a device holding no machine, a web tab with no agent selected).
+ for (const ws of trackedSockets) {
+ if ((ws as Alive).readyState !== WebSocket.OPEN) { trackedSockets.delete(ws); continue }
+ if (swept.has(ws)) continue
+ swept.add(ws)
+ pingOrTerminate(ws as Alive, { kind: 'tracked' })
+ }
+ // A ClientConn on an already-CLOSED socket means its 'close' handler never ran (it was wired after the
+ // socket died). Nothing else would ever remove it, while the count refresh keeps re-publishing it — so
+ // an adapter/node would hold a ghost commander forever (recap warm, cards streamed to nobody).
+ for (const c of clients) {
+ if (!orphaned.has(c.socket)) continue
+ logger.warn('hub reaping client on a closed socket', { machineId: c.machineId, kind: c.kind, connId: c.connId })
+ detachConn(c.machineId, c.connId)
+ }
+}, LIVENESS_TICK_MS).unref?.()
+
+// Client-count upkeep. Cadence is bound to the Redis field TTL, NOT to how fast a dead peer is noticed.
+export const CLIENT_HEARTBEAT_MS = 25_000
+setInterval(() => {
+ // Refresh this instance's client-count fields (25s < 45s TTL) so an idle client isn't garbage-collected
+ // out of the global total. A crashed instance simply stops refreshing → its fields expire.
+ for (const machineId of registry.localAgentIds()) {
+ const { ui, commander, commanderActive } = registry.clientCounts(machineId)
+ void setAgentClientCount(machineId, INSTANCE_ID, ui, commander, commanderActive)
+ }
+ // B_m periodic resync: re-emit the summed `__clients` for every agent whose control socket lives
+ // here. Field EXPIRY (a client-holding instance crashed — its fields age out of the hash after 45s)
+ // has no attach/detach event to poke a recompute, so without this the node keeps the ghost count
+ // forever (brain recap stays warm for a device that's gone). Receivers apply the absolute value
+ // idempotently, so re-sending an unchanged count is a no-op — and doubles as self-heal for any
+ // `__clients` frame lost to a pub/sub drop. Converges ≤ TTL(45s) + sweep(25s).
+ for (const machineId of registry.controlAgentIds()) {
+ void recomputeAndSendClients(machineId)
+ }
+}, CLIENT_HEARTBEAT_MS).unref?.()
+
+/** Register a client socket into the hub. The caller still owns the socket's 'message' handler. */
+export function attachHubClient(socket: WebSocket, machineId: string, kind: ClientKind): HubClient {
+ const connId = randomUUID()
+ ;(socket as Alive).__hubLastAlive = Date.now()
+ // Wired ONCE per socket because a web socket re-attaches on every agent switch. Note this does NOT
+ // touch __hubDeadlineMs: a device sets its own (shorter) deadline before any machine attaches.
+ wireLiveness(socket)
+ const first = registry.addClient({ connId, machineId, kind, socket })
+
+ if (first) {
+ void subscribeUp(machineId, (msg) => {
+ // Skip our OWN publish looping back — the manager-ws 'up' handler already delivered to local
+ // clients directly before publishing (only remote instances need the Redis copy).
+ if (msg.originPid === registry.PROCESS_ID) return
+ deliverUpLocal(machineId, msg)
+ })
+ .then((unsub) => {
+ // Drop this subscription instead of publishing it when either:
+ // - every client left while the Redis SUBSCRIBE was in flight, or
+ // - another attach already owns this agent's slot. Overwriting there would orphan the
+ // incumbent's unsub handle, leaving TWO callbacks on up:{machineId} forever — every frame
+ // would then fan out twice (each streamed delta rendered twice in the UI).
+ // A detach→re-attach inside the pending window (webWs.bindAgent does exactly that on every
+ // agent switch) makes this race routine, not theoretical.
+ if (registry.clientsFor(machineId).length === 0 || upSubs.has(machineId)) unsub()
+ else upSubs.set(machineId, unsub)
+ })
+ .catch(() => { /* logged in bus */ })
+ void subscribeTerminalUp(machineId, (packet) => deliverTerminalUpLocal(machineId, packet))
+ .then((unsub) => {
+ if (registry.clientsFor(machineId).length === 0 || terminalUpSubs.has(machineId)) unsub()
+ else terminalUpSubs.set(machineId, unsub)
+ })
+ .catch(() => { /* logged in bus */ })
+ }
+ void sendClientsControl(machineId, kind === 'commander')
+
+ const sendDown = (frame: Frame): void => {
+ // Fast-path: if THIS instance holds the agent's control manager socket (co-located), send the
+ // down frame straight to it — no Redis. Local delivery is guaranteed reachable (socket open).
+ const local = registry.controlSocketFor(machineId)
+ if (local && local.readyState === WebSocket.OPEN) {
+ try { local.send(JSON.stringify({ t: 'down', machineId: machineId, connId, frame })) } catch { /* ignore */ }
+ return
+ }
+ // publishDown returns the Redis subscriber count. 0 = no backend holds this agent's manager
+ // socket right now (node offline, or a mid-failover gap where B_m crashed and the manager hasn't
+ // re-registered on a new instance) → the message was NOT delivered. Tell the client so it flips
+ // offline instead of showing a stale-green while messages are silently dropped.
+ void routeDown(machineId, { connId, frame }, () => publishDown(machineId, { connId, frame })).then((n) => {
+ // HANDLED_IN_PROCESS = a provider machine, which has no socket to count. Only a real zero
+ // means "nobody holds this machine right now".
+ if (n === 0 && socket.readyState === WebSocket.OPEN) {
+ try { socket.send(JSON.stringify({ type: 'node_status', payload: { online: false, reason: 'unreachable' } })) } catch { /* ignore */ }
+ }
+ }).catch(() => { /* ignore */ })
+ }
+
+ return {
+ connId,
+ sendDown,
+ sendTerminalDown: (clientFrame: Uint8Array) => {
+ const packet = encodeTerminalHop(TerminalHopDirection.down, connId, clientFrame)
+ if (!packet) return
+ void publishTerminalDown(machineId, packet).then((subscribers) => {
+ if (subscribers === 0 && socket.readyState === WebSocket.OPEN) {
+ try { socket.send(JSON.stringify({ type: 'terminal_transport_error', payload: { code: 'TERMINAL_UNREACHABLE' } })) } catch { /* ignore */ }
+ }
+ }).catch(() => { /* ignore */ })
+ },
+ setActive: (active: boolean) => {
+ if (registry.setClientActive(machineId, connId, active)) void sendClientsControl(machineId)
+ },
+ detach: () => {
+ // The Harness owns per-connection E2EE state and terminal controller
+ // leases. Aggregate __clients counts cannot identify which connId left,
+ // so send an authoritative backend-only teardown frame before removing
+ // the route. This makes a real transport drop release the lease promptly
+ // instead of waiting for the 30-second heartbeat expiry.
+ sendDown({ type: '__client_disconnected', payload: {} })
+ detachConn(machineId, connId)
+ },
+ }
+}
+
+/** Remove one client and republish the count. Dropping the LAST client for an agent also releases its
+ * `up:{machineId}` subscription — the heartbeat reaper needs the same teardown, so it lives here rather
+ * than inside the HubClient closure. */
+function detachConn(machineId: string, connId: string): void {
+ const last = registry.removeClient(machineId, connId)
+ if (last) {
+ const unsub = upSubs.get(machineId)
+ if (unsub) { unsub(); upSubs.delete(machineId) }
+ const terminalUnsub = terminalUpSubs.get(machineId)
+ if (terminalUnsub) { terminalUnsub(); terminalUpSubs.delete(machineId) }
+ }
+ void sendClientsControl(machineId)
+}
diff --git a/backend/src/lib/instance.ts b/backend/src/lib/instance.ts
new file mode 100644
index 000000000..5a31c98f3
--- /dev/null
+++ b/backend/src/lib/instance.ts
@@ -0,0 +1,19 @@
+/**
+ * Stable identity + mesh endpoint for THIS backend instance/worker (Phase 2 data-plane mesh).
+ *
+ * Under a pm2 cluster many workers share the public port but each is a separate process, so the mesh
+ * listener must bind a DISTINCT internal port per worker (MESH_PORT_BASE + worker index). The instance
+ * id must be unique per worker and stable for the process lifetime.
+ */
+import { hostname } from 'os'
+import { env } from '../config/env.js'
+
+// pm2 sets NODE_APP_INSTANCE to the 0-based worker index; a bare `node dist/server.js` has none → 0.
+const WORKER_INDEX = Number(process.env.NODE_APP_INSTANCE ?? '0') || 0
+
+/** Unique + stable id for this instance/worker (used as the value of agent:{machineId}:appinst). */
+export const INSTANCE_ID = `${env.BACKEND_INSTANCE_ID || hostname()}-${WORKER_INDEX}`
+
+/** This worker's internal mesh port + the endpoint advertised to peers (host:port). */
+export const MESH_PORT = env.MESH_PORT_BASE + WORKER_INDEX
+export const MESH_ENDPOINT = `${env.MESH_HOST}:${MESH_PORT}`
diff --git a/backend/src/lib/jsonBodyParser.test.ts b/backend/src/lib/jsonBodyParser.test.ts
new file mode 100644
index 000000000..c50244d14
--- /dev/null
+++ b/backend/src/lib/jsonBodyParser.test.ts
@@ -0,0 +1,61 @@
+// A bodyless DELETE that still carries `Content-Type: application/json`.
+//
+// This is not a hypothetical: the mobile app sends it on device unpair, and Fastify's default parser
+// rejected it with FST_ERR_CTP_EMPTY_JSON_BODY *before the route ran*. The visible symptom was an
+// error in the log; the invisible one was that `revokeDeviceForUser` never executed, so the device
+// kept its socket and was never told it had been revoked. Hence a real Fastify instance here rather
+// than a unit test of the callback — the registration itself is the thing that has to be right.
+import Fastify from 'fastify'
+import { describe, expect, it } from 'vitest'
+import { registerJsonBodyParser } from './jsonBodyParser.js'
+
+async function buildApp() {
+ const app = Fastify()
+ registerJsonBodyParser(app)
+ app.delete('/thing/:id', async (req) => ({ ran: true, id: (req.params as { id: string }).id, body: req.body ?? null }))
+ app.post('/thing', async (req) => ({ body: req.body }))
+ await app.ready()
+ return app
+}
+
+describe('application/json body parser', () => {
+ it('runs the route when the body is empty — the unpair case', async () => {
+ const app = await buildApp()
+ const res = await app.inject({
+ method: 'DELETE',
+ url: '/thing/6a730145e13f6277cdf98c1a',
+ headers: { 'content-type': 'application/json' },
+ payload: '',
+ })
+ expect(res.statusCode).toBe(200)
+ expect(res.json()).toEqual({ ran: true, id: '6a730145e13f6277cdf98c1a', body: null })
+ await app.close()
+ })
+
+ it('treats whitespace as empty too', async () => {
+ const app = await buildApp()
+ const res = await app.inject({
+ method: 'DELETE', url: '/thing/x', headers: { 'content-type': 'application/json' }, payload: ' \n ',
+ })
+ expect(res.statusCode).toBe(200)
+ await app.close()
+ })
+
+ it('still parses a real body', async () => {
+ const app = await buildApp()
+ const res = await app.inject({
+ method: 'POST', url: '/thing', headers: { 'content-type': 'application/json' }, payload: '{"name":"Kitchen"}',
+ })
+ expect(res.json()).toEqual({ body: { name: 'Kitchen' } })
+ await app.close()
+ })
+
+ it('still rejects malformed JSON with a 400 — tolerance must not become "accept anything"', async () => {
+ const app = await buildApp()
+ const res = await app.inject({
+ method: 'POST', url: '/thing', headers: { 'content-type': 'application/json' }, payload: '{"name":',
+ })
+ expect(res.statusCode).toBe(400)
+ await app.close()
+ })
+})
diff --git a/backend/src/lib/jsonBodyParser.ts b/backend/src/lib/jsonBodyParser.ts
new file mode 100644
index 000000000..71e0ebba1
--- /dev/null
+++ b/backend/src/lib/jsonBodyParser.ts
@@ -0,0 +1,27 @@
+import type { FastifyInstance } from 'fastify'
+
+/**
+ * Accept `Content-Type: application/json` with an EMPTY body.
+ *
+ * A DELETE with no body is ordinary HTTP, but plenty of clients — the Autonomous mobile app among
+ * them — still send the JSON content-type on one. Fastify's default parser treats an empty body as an
+ * error (`FST_ERR_CTP_EMPTY_JSON_BODY`), so those requests died at the parser BEFORE reaching the
+ * route. That is how a device unpair could return an error while never revoking anything: the
+ * handler, and therefore the revoke push down to the device, never ran.
+ *
+ * Empty now means "no body". Anything non-empty must still be valid JSON.
+ */
+export function registerJsonBodyParser(app: FastifyInstance): void {
+ app.addContentTypeParser('application/json', { parseAs: 'string' }, (_req, body, done) => {
+ const raw = typeof body === 'string' ? body.trim() : ''
+ if (!raw) { done(null, undefined); return }
+ try {
+ done(null, JSON.parse(raw))
+ } catch {
+ const err = new Error('Body is not valid JSON') as Error & { statusCode?: number; code?: string }
+ err.statusCode = 400
+ err.code = 'FST_ERR_CTP_INVALID_JSON_BODY'
+ done(err)
+ }
+ })
+}
diff --git a/backend/src/lib/machineCredential.test.ts b/backend/src/lib/machineCredential.test.ts
new file mode 100644
index 000000000..4ae3595b8
--- /dev/null
+++ b/backend/src/lib/machineCredential.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('../config/env.js', () => ({
+ env: { HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' },
+}))
+
+import { decryptMachineCredential, encryptMachineCredential } from './machineCredential.js'
+
+describe('machine credential envelope', () => {
+ it('round-trips without storing plaintext and rejects tampering', () => {
+ const secret = 'campaign-secret'
+ const encrypted = encryptMachineCredential(secret)
+ expect(encrypted).not.toContain(secret)
+ expect(decryptMachineCredential(encrypted)).toBe(secret)
+ expect(() => decryptMachineCredential(`${encrypted.slice(0, -1)}x`)).toThrow()
+ })
+})
diff --git a/backend/src/lib/machineCredential.ts b/backend/src/lib/machineCredential.ts
new file mode 100644
index 000000000..718c83ce2
--- /dev/null
+++ b/backend/src/lib/machineCredential.ts
@@ -0,0 +1,26 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+import { env } from '../config/env.js'
+
+const PREFIX = 'v1'
+
+function key(): Buffer {
+ const value = Buffer.from(env.HARNESS_CREDENTIAL_ENCRYPTION_KEY, 'base64')
+ if (value.length !== 32) throw new Error('Machine credential encryption key is not configured')
+ return value
+}
+
+/** AES-256-GCM envelope: version.iv.tag.ciphertext (all binary values are base64url). */
+export function encryptMachineCredential(value: string): string {
+ const iv = randomBytes(12)
+ const cipher = createCipheriv('aes-256-gcm', key(), iv)
+ const encrypted = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()])
+ return [PREFIX, iv.toString('base64url'), cipher.getAuthTag().toString('base64url'), encrypted.toString('base64url')].join('.')
+}
+
+export function decryptMachineCredential(envelope: string): string {
+ const [version, ivRaw, tagRaw, bodyRaw, extra] = envelope.split('.')
+ if (version !== PREFIX || !ivRaw || !tagRaw || !bodyRaw || extra) throw new Error('Invalid machine credential envelope')
+ const decipher = createDecipheriv('aes-256-gcm', key(), Buffer.from(ivRaw, 'base64url'))
+ decipher.setAuthTag(Buffer.from(tagRaw, 'base64url'))
+ return Buffer.concat([decipher.update(Buffer.from(bodyRaw, 'base64url')), decipher.final()]).toString('utf8')
+}
diff --git a/backend/src/lib/machineLifecycle.test.ts b/backend/src/lib/machineLifecycle.test.ts
new file mode 100644
index 000000000..5cc097afb
--- /dev/null
+++ b/backend/src/lib/machineLifecycle.test.ts
@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const state = vi.hoisted(() => ({
+ online: false,
+ provision: vi.fn(),
+ publishUp: vi.fn(),
+}))
+
+vi.mock('./bus.js', () => ({
+ getAgentPresence: vi.fn(async () => state.online ? 'manager-1' : null),
+ publishUp: state.publishUp,
+}))
+vi.mock('./provision.js', () => ({
+ provisionViaManager: state.provision,
+}))
+vi.mock('./prisma.js', () => ({
+ prisma: {
+ $runCommandRaw: vi.fn(async () => ({ cursor: { firstBatch: [{ status: 'stopped', stopReason: 'manual_stop' }] } })),
+ },
+}))
+
+import { ensureMachineReady, getMachineLifecycleState } from './machineLifecycle.js'
+
+describe('machine wake gate', () => {
+ beforeEach(() => {
+ state.online = false
+ state.provision.mockReset()
+ state.publishUp.mockReset()
+ state.provision.mockImplementation(async () => { state.online = true; return { status: 'running' } })
+ })
+
+ it('preserves the manager stop reason for lifecycle broadcasts', async () => {
+ await expect(getMachineLifecycleState('machine-stopped')).resolves.toEqual({
+ status: 'stopped',
+ stopReason: 'manual_stop',
+ })
+ })
+
+ it('coalesces concurrent cold-starts and caches readiness for 30 seconds', async () => {
+ const binding = { machineId: `machine-${Date.now()}`, managerId: 'manager-1', authMode: 'managed' }
+ await Promise.all([ensureMachineReady(binding), ensureMachineReady(binding), ensureMachineReady(binding)])
+ expect(state.provision).toHaveBeenCalledTimes(1)
+ await ensureMachineReady(binding)
+ expect(state.provision).toHaveBeenCalledTimes(1)
+ expect(state.publishUp).toHaveBeenCalledWith(binding.machineId, expect.objectContaining({
+ frame: { type: 'node_status', payload: { online: true, status: 'running' } },
+ }))
+ })
+
+ it('uses a separate readiness key for a public app port', async () => {
+ const binding = { machineId: `machine-app-${Date.now()}`, managerId: 'manager-1', authMode: 'self' }
+ state.online = true
+ await ensureMachineReady(binding)
+ await ensureMachineReady(binding, { subdomain: 'demo' })
+ expect(state.provision).toHaveBeenCalledTimes(2)
+ expect(state.provision).toHaveBeenLastCalledWith('manager-1', 'start', { machineId: binding.machineId, subdomain: 'demo' })
+ })
+})
diff --git a/backend/src/lib/machineLifecycle.ts b/backend/src/lib/machineLifecycle.ts
new file mode 100644
index 000000000..cfb42d9f8
--- /dev/null
+++ b/backend/src/lib/machineLifecycle.ts
@@ -0,0 +1,110 @@
+import { isNodeless } from '../services/MachineService.js'
+import type { Machine } from '@prisma/client'
+import { prisma } from './prisma.js'
+import { getAgentPresence, publishUp } from './bus.js'
+import { provisionViaManager } from './provision.js'
+import { logger } from '../utils/logger.js'
+import { assertMachineBillingActive } from './billingState.js'
+
+export type MachineLifecycleStatus = 'creating' | 'starting' | 'running' | 'stopping' | 'stopped' | 'offline' | 'failed' | 'unknown'
+
+const READY_TIMEOUT_MS = 65_000
+const POLL_MS = 250
+const READY_CACHE_MS = 30_000
+const wakes = new Map<string, Promise<void>>()
+const readyUntil = new Map<string, number>()
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export class MachineWakeError extends Error {
+ constructor(message: string, readonly code: 'MACHINE_START_FAILED' | 'MACHINE_START_TIMEOUT') {
+ super(message)
+ this.name = 'MachineWakeError'
+ }
+}
+
+/** Read the manager-owned machine_nodes lifecycle without adding that model to the backend Prisma schema. */
+export async function getMachineLifecycleState(machineId: string): Promise<{ status: MachineLifecycleStatus; stopReason?: string }> {
+ try {
+ const raw = (await prisma.$runCommandRaw({
+ find: 'machine_nodes',
+ filter: { machineId },
+ projection: { status: 1, stopReason: 1, _id: 0 },
+ limit: 1,
+ })) as { cursor?: { firstBatch?: Array<{ status?: string; stopReason?: string }> } }
+ const row = raw.cursor?.firstBatch?.[0]
+ return {
+ status: typeof row?.status === 'string' ? row.status as MachineLifecycleStatus : 'unknown',
+ ...(typeof row?.stopReason === 'string' ? { stopReason: row.stopReason } : {}),
+ }
+ } catch {
+ return { status: 'unknown' }
+ }
+}
+
+export async function getMachineLifecycleStatus(machineId: string): Promise<MachineLifecycleStatus> {
+ return (await getMachineLifecycleState(machineId)).status
+}
+
+export function publishMachineLifecycle(machineId: string, status: MachineLifecycleStatus, reason?: string): void {
+ void publishUp(machineId, {
+ webEligible: true,
+ commanderEligible: true,
+ frame: { type: 'node_status', payload: { online: status === 'running', status, ...(reason ? { reason } : {}) } },
+ })
+}
+
+type WakeBinding = Pick<Machine, 'machineId' | 'managerId' | 'authMode'> & { billingStatus?: string | null }
+
+async function wake(binding: WakeBinding, subdomain?: string): Promise<void> {
+ assertMachineBillingActive(binding)
+ if (isNodeless(binding.authMode) || !binding.managerId) return
+ const before = await getMachineLifecycleStatus(binding.machineId)
+ const alreadyOnline = !!(await getAgentPresence(binding.machineId))
+ if (!alreadyOnline || before !== 'running') publishMachineLifecycle(binding.machineId, 'starting')
+
+ try {
+ await provisionViaManager(binding.managerId, 'start', { machineId: binding.machineId, ...(subdomain ? { subdomain } : {}) })
+ } catch (err) {
+ const timeout = err instanceof Error && (err.name === 'ProvisionTimeoutError' || /timed out/i.test(err.message))
+ const code = timeout ? 'MACHINE_START_TIMEOUT' : 'MACHINE_START_FAILED'
+ // An app-specific readiness failure can happen after the node itself is already healthy. Keep
+ // machine lifecycle accurate while returning the proxy failure to this request.
+ const nodeOnline = !!(await getAgentPresence(binding.machineId))
+ publishMachineLifecycle(binding.machineId, nodeOnline ? 'running' : timeout ? 'offline' : 'failed', code.toLowerCase())
+ throw new MachineWakeError(err instanceof Error ? err.message : String(err), code)
+ }
+
+ const deadline = Date.now() + READY_TIMEOUT_MS
+ while (Date.now() < deadline) {
+ if (await getAgentPresence(binding.machineId)) {
+ publishMachineLifecycle(binding.machineId, 'running')
+ return
+ }
+ await sleep(POLL_MS)
+ }
+ publishMachineLifecycle(binding.machineId, 'offline', 'start_timeout')
+ throw new MachineWakeError(`machine ${binding.machineId} did not register after start`, 'MACHINE_START_TIMEOUT')
+}
+
+/** Idempotent and herd-safe within this backend instance. The manager independently coalesces too. */
+export async function ensureMachineReady(
+ binding: WakeBinding,
+ opts: { subdomain?: string } = {},
+): Promise<void> {
+ assertMachineBillingActive(binding)
+ if (isNodeless(binding.authMode) || !binding.managerId) return Promise.resolve()
+ const key = opts.subdomain ? `${binding.machineId}:app:${opts.subdomain}` : binding.machineId
+ if (Date.now() < (readyUntil.get(key) ?? 0) && await getAgentPresence(binding.machineId)) return
+ const pending = wakes.get(key)
+ if (pending) return pending
+ const p = wake(binding, opts.subdomain)
+ .then(() => { readyUntil.set(key, Date.now() + READY_CACHE_MS) })
+ .catch((err) => {
+ logger.warn('machine wake failed', { machineId: binding.machineId, managerId: binding.managerId, error: err instanceof Error ? err.message : String(err) })
+ throw err
+ })
+ .finally(() => { if (wakes.get(key) === p) wakes.delete(key) })
+ wakes.set(key, p)
+ return p
+}
diff --git a/backend/src/lib/machineMessage.ts b/backend/src/lib/machineMessage.ts
new file mode 100644
index 000000000..5980eb77a
--- /dev/null
+++ b/backend/src/lib/machineMessage.ts
@@ -0,0 +1,28 @@
+import { publishDown } from './bus.js'
+import { routeDown } from './providerLink.js'
+import { logger } from '../utils/logger.js'
+
+/**
+ * Trigger a turn in one of an agent's projects from the BACKEND (e.g. after voice STT).
+ *
+ * Inverted transport: instead of opening a WS to the manager, we `publishDown` the same inbound
+ * `message` envelope the device/web use. It reaches the machine's node over the hub (down:{machineId} →
+ * manager → node); the node creates/continues the session and runs the turn, and `done`/`result`
+ * flow back to whatever commander sockets are connected (incl. the device). Fire-and-forget.
+ */
+export async function sendMessageToMachine(
+ machineId: string,
+ agentId: string,
+ content: string,
+ sessionId?: string | null,
+): Promise<void> {
+ // Continue the SAME session the device last saw for this project (from its tracked completion
+ // events); on the first turn fall back to resumeLatest so the node picks the project's most recent
+ // session rather than fragmenting history into a fresh session per utterance.
+ const payload = sessionId
+ ? { content, agentId, mode: 'auto', sessionId }
+ : { content, agentId, mode: 'auto', resumeLatest: true }
+ const down = { connId: '', frame: { type: 'message', payload } }
+ await routeDown(machineId, down, () => publishDown(machineId, down))
+ logger.info('voice turn dispatched', { machineId, agentId })
+}
diff --git a/backend/src/lib/managerWs.test.ts b/backend/src/lib/managerWs.test.ts
new file mode 100644
index 000000000..3b1ec4f6b
--- /dev/null
+++ b/backend/src/lib/managerWs.test.ts
@@ -0,0 +1,113 @@
+import { EventEmitter } from 'node:events'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const state = vi.hoisted(() => ({
+ subscribeDown: vi.fn(),
+ setAgentPresence: vi.fn(async () => undefined),
+ clearAgentPresence: vi.fn(async () => undefined),
+ publishUp: vi.fn(async () => 1),
+ recomputeAndSendClients: vi.fn(async () => undefined),
+ agentsByManager: new Map<string, Set<string>>(),
+ controlSockets: new Map<string, unknown>(),
+}))
+
+vi.mock('./prisma.js', () => ({ prisma: { manager: { findUnique: vi.fn() } } }))
+vi.mock('./bus.js', () => ({
+ publishUp: state.publishUp,
+ subscribeDown: state.subscribeDown,
+ setAgentPresence: state.setAgentPresence,
+ clearAgentPresence: state.clearAgentPresence,
+ subscribeMgr: vi.fn(async () => vi.fn()),
+ publishReply: vi.fn(async () => 1),
+ subscribeAppDown: vi.fn(async () => vi.fn()),
+ publishAppUp: vi.fn(async () => 1),
+ setAppInstance: vi.fn(async () => undefined),
+ clearAppInstance: vi.fn(async () => undefined),
+}))
+vi.mock('../config/env.js', () => ({ env: { MESH_ENABLED: false } }))
+vi.mock('./instance.js', () => ({ INSTANCE_ID: 'backend-test' }))
+vi.mock('./registry.js', () => ({
+ PROCESS_ID: 'backend-test',
+ addManager: (key: string) => { state.agentsByManager.set(key, new Set()) },
+ removeManager: (key: string) => {
+ const agents = [...(state.agentsByManager.get(key) ?? [])]
+ state.agentsByManager.delete(key)
+ return agents
+ },
+ bindAgentManager: (machineId: string, key: string) => { state.agentsByManager.get(key)?.add(machineId) },
+ unbindAgent: (machineId: string, key: string) => { state.agentsByManager.get(key)?.delete(machineId) },
+ agentsForManager: (key: string) => [...(state.agentsByManager.get(key) ?? [])],
+ bindControlSocket: (machineId: string, ws: unknown) => { state.controlSockets.set(machineId, ws) },
+ unbindControlSocket: (machineId: string, ws: unknown) => {
+ if (state.controlSockets.get(machineId) === ws) state.controlSockets.delete(machineId)
+ },
+ controlSocketFor: (machineId: string) => state.controlSockets.get(machineId),
+ bindAppSocket: vi.fn(),
+ unbindAppSocket: vi.fn(),
+}))
+vi.mock('./appTunnel.js', () => ({ deliverAppUpLocal: vi.fn(() => false) }))
+vi.mock('./hub.js', () => ({
+ CLIENTS_DIRTY: '__clients_dirty',
+ deliverUpLocal: vi.fn(),
+ recomputeAndSendClients: state.recomputeAndSendClients,
+}))
+vi.mock('./agentTracker.js', () => ({ recordCreatedAgent: vi.fn(), recordDeletedAgent: vi.fn() }))
+vi.mock('./machineLifecycle.js', () => ({
+ getMachineLifecycleState: vi.fn(async () => ({ status: 'stopped', stopReason: 'idle_timeout' })),
+}))
+vi.mock('../utils/logger.js', () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}))
+
+import { attachManager } from './managerWs.js'
+
+class FakeManagerSocket extends EventEmitter {
+ readyState = 1
+ send = vi.fn()
+ terminate = vi.fn()
+}
+
+describe('manager node readiness', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ state.agentsByManager.clear()
+ state.controlSockets.clear()
+ })
+
+ it('does not advertise presence until the cross-instance down route is subscribed', async () => {
+ let finishSubscribe: ((unsub: () => void) => void) | undefined
+ let deliverDown: ((msg: { connId: string; frame: unknown }) => void) | undefined
+ state.subscribeDown.mockImplementation((_machineId, callback) => {
+ deliverDown = callback
+ return new Promise<() => void>((resolve) => { finishSubscribe = resolve })
+ })
+ const ws = new FakeManagerSocket()
+ attachManager(ws as never, 'manager-1', 'control')
+
+ ws.emit('message', Buffer.from(JSON.stringify({ t: 'register', machineId: 'machine-1' })))
+ ws.emit('message', Buffer.from(JSON.stringify({ t: 'ping' })))
+ await Promise.resolve()
+
+ expect(state.subscribeDown).toHaveBeenCalledWith('machine-1', expect.any(Function))
+ expect(state.setAgentPresence).not.toHaveBeenCalled()
+ expect(state.publishUp).not.toHaveBeenCalledWith('machine-1', expect.objectContaining({
+ frame: { type: 'node_status', payload: { online: true, status: 'running' } },
+ }))
+
+ finishSubscribe?.(vi.fn())
+ await vi.waitFor(() => expect(state.setAgentPresence).toHaveBeenCalledWith('machine-1', 'manager-1', 30))
+ await vi.waitFor(() => expect(state.publishUp).toHaveBeenCalledWith('machine-1', expect.objectContaining({
+ frame: { type: 'node_status', payload: { online: true, status: 'running' } },
+ })))
+ deliverDown?.({ connId: 'device-1', frame: { type: 'message', payload: { content: 'voice transcript' } } })
+ expect(ws.send).toHaveBeenCalledTimes(1)
+ expect(JSON.parse(ws.send.mock.calls[0][0])).toEqual({
+ t: 'down',
+ machineId: 'machine-1',
+ connId: 'device-1',
+ frame: { type: 'message', payload: { content: 'voice transcript' } },
+ })
+
+ ws.emit('close')
+ })
+})
diff --git a/backend/src/lib/managerWs.ts b/backend/src/lib/managerWs.ts
new file mode 100644
index 000000000..0a07e65ba
--- /dev/null
+++ b/backend/src/lib/managerWs.ts
@@ -0,0 +1,306 @@
+/**
+ * Backend hub — manager-facing terminating endpoint (`/api/manager-ws`). Managers DIAL IN and
+ * multiplex all their agents over one socket, so the backend no longer needs `Manager.publicHost`
+ * or any manager address. Auth = the manager's own key (`x-api-key` + `managerId`), validated
+ * against the `managers` collection.
+ *
+ * Per agent this backend instance becomes `B_m` (the single owner of that agent's manager socket):
+ * - on `register machineId` → subscribeDown(machineId) so any client-holding backend's publishDown
+ * reaches this manager socket → node; only then set the agent→manager presence key.
+ * - on `up` → publishUp(machineId) so every client-holding backend fans it to its clients.
+ */
+import type { IncomingMessage } from 'http'
+import type { Duplex } from 'stream'
+import { randomUUID } from 'crypto'
+import { WebSocketServer, WebSocket, type RawData } from 'ws'
+import { prisma } from './prisma.js'
+import {
+ publishUp,
+ subscribeDown,
+ setAgentPresence,
+ clearAgentPresence,
+ subscribeMgr,
+ publishReply,
+ subscribeAppDown,
+ publishAppUp,
+ setAppInstance,
+ clearAppInstance,
+} from './bus.js'
+import { env } from '../config/env.js'
+import { INSTANCE_ID } from './instance.js'
+import * as registry from './registry.js'
+import { deliverAppUpLocal } from './appTunnel.js'
+import { deliverUpLocal, recomputeAndSendClients, CLIENTS_DIRTY } from './hub.js'
+import { recordCreatedAgent, recordDeletedAgent } from './agentTracker.js'
+import type { ManagerFrame, DownBusMsg } from './tunnel.js'
+import { logger } from '../utils/logger.js'
+import { getMachineLifecycleState } from './machineLifecycle.js'
+
+const PRESENCE_TTL_SEC = 30
+
+const wss = new WebSocketServer({ noServer: true })
+
+/** Fastify/http upgrade hook for `/api/manager-ws`. Auth = manager apiKey (`x-api-key`) + `managerId`. */
+export function handleManagerUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
+ const apiKey = typeof req.headers['x-api-key'] === 'string' ? req.headers['x-api-key'] : undefined
+ const url = new URL(req.url ?? '', 'http://localhost')
+ const managerId = url.searchParams.get('managerId') ?? ''
+ // Dedicated app-proxy pool sockets dial with ?pool=app (observability only — subscriptions are driven
+ // by the register / app_register frames the manager sends, not by this).
+ const poolKind = url.searchParams.get('pool') === 'app' ? 'app' : 'control'
+ if (!apiKey || !managerId) { socket.destroy(); return }
+ void (async () => {
+ const m = await prisma.manager.findUnique({ where: { managerId } })
+ if (!m || !m.apiKey || m.apiKey !== apiKey) { socket.destroy(); return }
+ wss.handleUpgrade(req, socket, head, (ws) => attachManager(ws, managerId, poolKind))
+ })().catch((err) => { logger.warn('manager-ws upgrade failed', { error: String(err) }); socket.destroy() })
+}
+
+export function attachManager(ws: WebSocket, managerId: string, poolKind: 'control' | 'app'): void {
+ // Managers run as a PM2 cluster sharing one MANAGER_ID, so key the registry by a UNIQUE
+ // per-connection id (else cluster instances collide). `managerId` stays the logical value used
+ // for presence + provisioning placement.
+ const connKey = `${managerId}#${randomUUID()}`
+ registry.addManager(connKey, ws)
+ logger.info('manager connected', { managerId, connKey, pool: poolKind })
+
+ // machineId → unsubscribe for its down:{machineId} subscription (this instance is B_m for that agent).
+ const downSubs = new Map<string, () => void>()
+ // machineId → unsubscribe for its appdown:{machineId} subscription (app-proxy tunnel client→app frames).
+ const appDownSubs = new Map<string, () => void>()
+ // machineIds whose subscribe is IN FLIGHT. Reserved synchronously because `downSubs.set` only happens
+ // after the Redis SUBSCRIBE resolves: without this, two `register` frames for the same agent arriving
+ // inside that window both pass the `has()` check, and the second unsub overwrites (and orphans) the
+ // first — leaving two live callbacks, so every down-frame reaches the node TWICE (one user message
+ // → two agent turns). The manager does send `register` twice back-to-back: attachNode queues one
+ // while the socket is still connecting, then onOpen re-registers AND flushes the queued copy.
+ const downSubPending = new Set<string>()
+ const appDownSubPending = new Set<string>()
+
+ // Liveness: the manager app-pings every ~15s. If we hear NOTHING for 45s the socket is half-open →
+ // terminate so the manager's backendSocket reconnects and re-registers its nodes.
+ let lastSeen = Date.now()
+ const staleSweep = setInterval(() => {
+ if (Date.now() - lastSeen > 45_000) { try { ws.terminate() } catch { /* ignore */ } }
+ }, 20_000)
+
+ // Provisioning RPC: forward mgr:{managerId} commands over THIS socket. Subscribed ONLY on the
+ // manager→backend pool's CONTROL socket (`hello.control`), so a provision command is forwarded once,
+ // not once per pool socket. The manager replies with a provision_result frame, which we republish to
+ // mgrreply:{requestId} for the requesting backend.
+ let unsubMgr: (() => void) | null = null
+ const subscribeProvisioning = (): void => {
+ if (unsubMgr) return
+ void subscribeMgr(managerId, (msg) => {
+ const cmd = msg as { requestId?: string; cmd?: 'create' | 'start' | 'stop' | 'destroy' | 'app_create' | 'app_delete'; payload?: Record<string, unknown> }
+ if (!cmd?.requestId || !cmd.cmd) return
+ if (ws.readyState === WebSocket.OPEN) {
+ try { ws.send(JSON.stringify({ t: 'provision', requestId: cmd.requestId, cmd: cmd.cmd, payload: cmd.payload ?? {} })) } catch { /* ignore */ }
+ }
+ }).then((u) => { unsubMgr = u }).catch((err) => logger.error('manager-ws subscribeMgr failed', err, { managerId }))
+ }
+
+ const refreshPresence = (): void => {
+ for (const machineId of registry.agentsForManager(connKey)) {
+ // Control socket → node-liveness presence; app socket → instance-affinity for the mesh (Phase 2).
+ if (poolKind === 'app') { if (env.MESH_ENABLED) void setAppInstance(machineId, INSTANCE_ID, PRESENCE_TTL_SEC) }
+ // Presence is also the cross-instance down-route readiness gate used by ensureMachineReady(). Do
+ // not refresh it while Redis SUBSCRIBE is still pending, or a client on another backend can
+ // publish into that gap and lose its message (Redis Pub/Sub has no backlog).
+ else if (downSubs.has(machineId)) void setAgentPresence(machineId, managerId, PRESENCE_TTL_SEC)
+ }
+ }
+
+ const announceControlReady = (machineId: string): void => {
+ if (!downSubs.has(machineId) || registry.controlSocketFor(machineId) !== ws ||
+ !registry.agentsForManager(connKey).includes(machineId)) return
+ void setAgentPresence(machineId, managerId, PRESENCE_TTL_SEC)
+ // Node came online AND its cross-instance down route is live. Clients may now safely release
+ // messages that were held by ensureMachineReady() during an idle wake.
+ void publishUp(machineId, { webEligible: true, commanderEligible: true, frame: { type: 'node_status', payload: { online: true, status: 'running' } } })
+ // Resync client counts over the local control socket, avoiding another Redis round-trip.
+ void recomputeAndSendClients(machineId)
+ logger.info('node registered', { managerId, machineId })
+ }
+
+ // Chat/control register — arrives on the manager's CONTROL-pool socket for this agent.
+ const register = (machineId: string): void => {
+ registry.bindAgentManager(machineId, connKey)
+ registry.bindControlSocket(machineId, ws) // local chat-down fast-path
+ if (downSubs.has(machineId)) {
+ announceControlReady(machineId)
+ return
+ }
+ if (!downSubs.has(machineId) && !downSubPending.has(machineId)) {
+ downSubPending.add(machineId)
+ void subscribeDown(machineId, (msg: DownBusMsg) => {
+ // A client-holding backend pokes us (B_m) to recompute the GLOBAL client total — don't forward
+ // it to the node; re-emit the summed `__clients` frame over this control socket instead.
+ if ((msg.frame as { type?: string })?.type === CLIENTS_DIRTY) { void recomputeAndSendClients(machineId); return }
+ // Forward a client message down this manager socket → manager → node.
+ if (ws.readyState === WebSocket.OPEN) {
+ try { ws.send(JSON.stringify({ t: 'down', machineId: machineId, connId: msg.connId, frame: msg.frame })) } catch { /* ignore */ }
+ }
+ }).then((unsub) => {
+ downSubPending.delete(machineId)
+ // Drop it if the agent left this manager meanwhile, or if another register already claimed
+ // the slot — overwriting would orphan the incumbent callback and double-deliver every frame.
+ if (!registry.agentsForManager(connKey).includes(machineId) ||
+ registry.controlSocketFor(machineId) !== ws || downSubs.has(machineId)) {
+ unsub()
+ } else {
+ downSubs.set(machineId, unsub)
+ announceControlReady(machineId)
+ }
+ }).catch((err) => {
+ downSubPending.delete(machineId)
+ logger.error('manager-ws subscribeDown failed', err, { machineId })
+ })
+ }
+ }
+
+ const unregister = (machineId: string): void => {
+ registry.unbindAgent(machineId, connKey)
+ registry.unbindControlSocket(machineId, ws)
+ const unsub = downSubs.get(machineId)
+ if (unsub) { unsub(); downSubs.delete(machineId) }
+ void clearAgentPresence(machineId)
+ // Intentional manual/idle stop is a first-class lifecycle state; unexpected detach remains `offline`.
+ void getMachineLifecycleState(machineId).then(({ status: rawStatus, stopReason }) => {
+ const stopped = rawStatus === 'stopping' || rawStatus === 'stopped'
+ return publishUp(machineId, {
+ webEligible: true,
+ commanderEligible: true,
+ frame: {
+ type: 'node_status',
+ payload: stopped
+ ? { online: false, status: 'stopped', reason: stopReason ?? 'stopped' }
+ : { online: false, status: 'offline', reason: 'node offline' },
+ },
+ })
+ })
+ logger.info('node unregistered', { managerId, machineId })
+ }
+
+ // App-proxy register — arrives on the manager's APP-pool socket for this agent (or the CONTROL socket
+ // when the manager runs no dedicated app pool, MANAGER_APP_POOL_SIZE=0). Subscribes client→app frames
+ // (app_req/app_body/app_ws_*/app_abort) to forward down THIS socket → manager appTunnel → container app.
+ // Single subscriber per agent (no dup under clustering); the app stream rides the agent's app-shard socket.
+ const appRegister = (machineId: string): void => {
+ registry.bindAgentManager(machineId, connKey)
+ registry.bindAppSocket(machineId, ws) // local app-proxy fast-path (skip Redis when co-located)
+ if (env.MESH_ENABLED) void setAppInstance(machineId, INSTANCE_ID, PRESENCE_TTL_SEC) // affinity for the mesh
+ if (!appDownSubs.has(machineId) && !appDownSubPending.has(machineId)) {
+ appDownSubPending.add(machineId)
+ void subscribeAppDown(machineId, (frame) => {
+ if (ws.readyState === WebSocket.OPEN) {
+ try { ws.send(JSON.stringify(frame)) } catch { /* ignore */ }
+ }
+ }).then((unsub) => {
+ appDownSubPending.delete(machineId)
+ // Same reservation rule as the control plane: never overwrite an incumbent subscription.
+ if (!registry.agentsForManager(connKey).includes(machineId) || appDownSubs.has(machineId)) unsub()
+ else appDownSubs.set(machineId, unsub)
+ }).catch((err) => {
+ appDownSubPending.delete(machineId)
+ logger.error('manager-ws subscribeAppDown failed', err, { machineId })
+ })
+ }
+ }
+
+ const appUnregister = (machineId: string): void => {
+ registry.unbindAgent(machineId, connKey)
+ registry.unbindAppSocket(machineId, ws)
+ if (env.MESH_ENABLED) void clearAppInstance(machineId)
+ const appUnsub = appDownSubs.get(machineId)
+ if (appUnsub) { appUnsub(); appDownSubs.delete(machineId) }
+ }
+
+ ws.on('message', (raw: RawData) => {
+ lastSeen = Date.now()
+ let env: ManagerFrame
+ try { env = JSON.parse(raw.toString()) as ManagerFrame } catch { return }
+ switch (env.t) {
+ case 'up': {
+ // Tap project lifecycle to maintain machine_agents (plan cap) — replaces the old /proxy
+ // response tap; works for BOTH web and device WS create/delete.
+ const f = env.frame as { type?: string; payload?: { agent?: { id?: unknown; name?: unknown }; agentId?: unknown; machineId?: unknown } }
+ if (f?.type === 'agent_synced') {
+ void recordCreatedAgent(env.machineId, f.payload?.agent).catch(() => { /* best effort */ })
+ } else if (f?.type === 'agent_deleted' && typeof f.payload?.agentId === 'string') {
+ // See adapterWs.ts: producers send `agentId`, so reading `machineId` recorded nothing.
+ void recordDeletedAgent(env.machineId, f.payload.agentId).catch(() => { /* best effort */ })
+ }
+ const upMsg = {
+ excludeConnId: env.excludeConnId,
+ webEligible: env.webEligible,
+ commanderEligible: env.commanderEligible,
+ frame: env.frame,
+ originPid: registry.PROCESS_ID,
+ }
+ // Fast-path: hand straight to THIS instance's local clients (no Redis round-trip); the tagged
+ // publish still fans out to clients on other instances, which won't double-deliver here.
+ deliverUpLocal(env.machineId, upMsg)
+ void publishUp(env.machineId, upMsg)
+ break
+ }
+ case 'register':
+ register(env.machineId)
+ break
+ case 'unregister':
+ unregister(env.machineId)
+ break
+ case 'app_register':
+ appRegister(env.machineId)
+ break
+ case 'app_unregister':
+ appUnregister(env.machineId)
+ break
+ case 'hello':
+ // capacity advertised for placement; presence refreshed opportunistically. Only the pool's
+ // CONTROL socket subscribes provisioning (so a provision command isn't forwarded N times).
+ if (env.control) subscribeProvisioning()
+ refreshPresence()
+ break
+ case 'ping':
+ refreshPresence()
+ break
+ case 'provision_result':
+ void publishReply(env.requestId, { ok: env.ok, data: env.data, error: env.error })
+ break
+ case 'app_res':
+ case 'app_body':
+ case 'app_res_body':
+ case 'app_ws_msg':
+ case 'app_ws_close':
+ case 'app_abort':
+ // App-proxy tunnel app→client frame. Fast-path: if the origin client stream is on THIS instance
+ // (co-located), hand it straight to the local handler — no Redis. Else republish by streamId.
+ if (!deliverAppUpLocal(env.streamId, env)) void publishAppUp(env.streamId, env)
+ break
+ default:
+ break
+ }
+ })
+
+ const cleanup = (): void => {
+ clearInterval(staleSweep)
+ if (unsubMgr) { unsubMgr(); unsubMgr = null }
+ const agents = registry.removeManager(connKey)
+ for (const machineId of agents) {
+ registry.unbindControlSocket(machineId, ws)
+ registry.unbindAppSocket(machineId, ws)
+ if (env.MESH_ENABLED && poolKind === 'app') void clearAppInstance(machineId)
+ const unsub = downSubs.get(machineId)
+ if (unsub) { unsub(); downSubs.delete(machineId) }
+ const appUnsub = appDownSubs.get(machineId)
+ if (appUnsub) { appUnsub(); appDownSubs.delete(machineId) }
+ void clearAgentPresence(machineId)
+ // Manager socket dropped → its nodes are unreachable; tell clients they're offline.
+ void publishUp(machineId, { webEligible: true, commanderEligible: true, frame: { type: 'node_status', payload: { online: false, status: 'offline', reason: 'manager offline' } } })
+ }
+ logger.info('manager disconnected', { managerId, agents: agents.length })
+ }
+ ws.on('close', cleanup)
+ ws.on('error', cleanup)
+}
diff --git a/backend/src/lib/managers.ts b/backend/src/lib/managers.ts
new file mode 100644
index 000000000..1ac41604d
--- /dev/null
+++ b/backend/src/lib/managers.ts
@@ -0,0 +1,34 @@
+import { prisma, machineAlive } from './prisma.js'
+import { AppError } from '../errors/index.js'
+
+// A manager is a candidate only if it heartbeated recently (3 missed beats @ 30s).
+const ALIVE_MS = 90_000
+
+/**
+ * Placement — pick the manager to provision the next node on. Provisioning + all data go over the
+ * manager socket (Redis `mgr:{managerId}`), so we only need the chosen managerId (+ liveness/capacity
+ * from the DB), never a reachable address (publicHost is gone). Best-fit: the live manager with the
+ * LEAST free capacity that still has room, packing nodes onto the fullest manager first.
+ * Throws NO_MANAGER when none is alive, NO_CAPACITY when all live ones are full.
+ */
+export async function selectManagerId(): Promise<{ managerId: string }> {
+ const cutoff = new Date(Date.now() - ALIVE_MS)
+ const managers = await prisma.manager.findMany({ where: { lastSeenAt: { gte: cutoff } } })
+ if (managers.length === 0) throw new AppError('No live agent-manager available', 503, 'NO_MANAGER')
+ const reservations = await prisma.machine.groupBy({
+ by: ['managerId'],
+ where: {
+ managerId: { in: managers.map((m) => m.managerId) },
+ billingStatus: 'pending',
+ ...machineAlive,
+ },
+ _count: { _all: true },
+ })
+ const pendingByManager = new Map(reservations.map((r) => [r.managerId, r._count._all]))
+ const withRoom = managers
+ .map((m) => ({ m, free: m.maxNodes - m.nodeCount - (pendingByManager.get(m.managerId) ?? 0) }))
+ .filter((x) => x.free > 0)
+ .sort((a, b) => a.free - b.free || b.m.nodeCount - a.m.nodeCount)
+ if (withRoom.length === 0) throw new AppError('No manager has free capacity', 503, 'NO_CAPACITY')
+ return { managerId: withRoom[0].m.managerId }
+}
diff --git a/backend/src/lib/nodeRole.ts b/backend/src/lib/nodeRole.ts
new file mode 100644
index 000000000..363b3b3e3
--- /dev/null
+++ b/backend/src/lib/nodeRole.ts
@@ -0,0 +1,125 @@
+/**
+ * The NODE ROLE, shared by every backer of a machine.
+ *
+ * A machine needs exactly one thing on the far side of its `machineId`: something that consumes
+ * `down:{machineId}` and publishes back up. Three things play that part —
+ *
+ * - `agent-manager`, for a docker agent-node (`managerWs.ts`, multiplexed, dials in)
+ * - `machine-adapter`, for the user's own machine (`adapterWs.ts`, one socket, dials in)
+ * - `providerLink`, for a third-party provider endpoint (dials OUT over HTTP+SSE)
+ *
+ * Everything they share lives here: the down subscription with its two control-frame intercepts, the
+ * presence key and its refresh, the `__clients` recompute, and the `node_status` transitions. What
+ * differs — how a frame actually reaches the backer, and how the backer is torn down — arrives as
+ * callbacks, because that is the only part that is genuinely transport-specific.
+ *
+ * Extracted from `adapterWs.ts` so `providerLink` does not become a second copy of it.
+ */
+import {
+ clearAgentPresence,
+ publishUp,
+ setAgentPresence,
+ subscribeDown,
+} from './bus.js'
+import { CLIENTS_DIRTY, recomputeAndSendClients } from './hub.js'
+import { REMOTE_BILLING_SUSPENDED_FRAME } from './billingState.js'
+import type { DownBusMsg } from './tunnel.js'
+
+/** Presence TTL, refreshed on the backer's own heartbeat. Mirrors the manager cadence. */
+export const PRESENCE_TTL_SEC = 30
+export const PRESENCE_REFRESH_MS = 15_000
+
+/** Written into `agent:{machineId}:mgr`; tells reads which kind of backer is holding the machine. */
+export type NodeRoleOwner = 'remote' | 'provider'
+
+export interface NodeRoleOptions {
+ machineId: string
+ owner: NodeRoleOwner
+ /**
+ * Deliver a client frame to the backer. Control frames never reach this — they are handled here.
+ * Returning nothing is fine; a dead transport should simply drop.
+ */
+ deliver: (msg: DownBusMsg) => void
+ /**
+ * Billing suspended this machine mid-session. A socket-backed role closes the socket; a
+ * request-based one has nothing to close and marks itself instead.
+ */
+ onBillingSuspended: () => void
+ /** Extra work on each presence refresh — the adapter renews its one-machine claim here. */
+ onHeartbeat?: () => void
+ /** Reason attached to the offline `node_status` when the role detaches. */
+ offlineReason: string
+}
+
+export interface NodeRoleHandle {
+ /** Refresh presence now — call from an application-level ping. */
+ touch: () => void
+ /** Release the down subscription, stop the timer, and mark the machine offline. */
+ detach: () => Promise<void>
+}
+
+/**
+ * Take the node role for one machine.
+ *
+ * `node_status { online: true }` goes out to web AND device: the device shows an "Offline" badge in
+ * place of "Reconnecting…" when its backer is down, so it needs the transitions just as the web does.
+ */
+export async function attachNodeRole(opts: NodeRoleOptions): Promise<NodeRoleHandle> {
+ const { machineId, owner } = opts
+
+ const unsub = await subscribeDown(machineId, (msg: DownBusMsg) => {
+ const type = (msg.frame as { type?: string })?.type
+
+ // A client (re)joining pokes B_m to recompute cross-instance client counts. For a machine whose
+ // backer is attached HERE, this endpoint *is* B_m — play the part: recompute and emit the summed
+ // `__clients` frame. Never forward the poke itself.
+ if (type === CLIENTS_DIRTY) {
+ void recomputeAndSendClients(machineId)
+ return
+ }
+ if (type === REMOTE_BILLING_SUSPENDED_FRAME) {
+ opts.onBillingSuspended()
+ return
+ }
+ opts.deliver(msg)
+ })
+
+ await setAgentPresence(machineId, owner, PRESENCE_TTL_SEC)
+ void publishUp(machineId, {
+ webEligible: true,
+ commanderEligible: true,
+ frame: { type: 'node_status', payload: { online: true } },
+ })
+ // Learn the current client counts on attach — a device may already be waiting, and the backer
+ // needs them to replay live state to it.
+ void recomputeAndSendClients(machineId)
+
+ const timer = setInterval(() => {
+ void setAgentPresence(machineId, owner, PRESENCE_TTL_SEC)
+ opts.onHeartbeat?.()
+ // Periodic B_m resync: re-emit the summed `__clients` so a client-instance crash (its fields
+ // expire with no attach/detach poke) or a lost frame converges, instead of leaving the backer on
+ // a ghost count. The value is absolute, so re-sending is idempotent.
+ void recomputeAndSendClients(machineId)
+ }, PRESENCE_REFRESH_MS)
+
+ let detached = false
+ return {
+ touch: () => {
+ void setAgentPresence(machineId, owner, PRESENCE_TTL_SEC)
+ opts.onHeartbeat?.()
+ },
+ detach: async () => {
+ if (detached) return
+ detached = true
+ clearInterval(timer)
+ await unsub()
+ await clearAgentPresence(machineId)
+ void publishUp(machineId, {
+ webEligible: true,
+ commanderEligible: true,
+ frame: { type: 'node_status', payload: { online: false, reason: opts.offlineReason } },
+ })
+ },
+ }
+}
diff --git a/backend/src/lib/nodeRpc.ts b/backend/src/lib/nodeRpc.ts
new file mode 100644
index 000000000..fa77e862b
--- /dev/null
+++ b/backend/src/lib/nodeRpc.ts
@@ -0,0 +1,54 @@
+/**
+ * Backend-side "call the node and await its reply" — the server analogue of the web's
+ * `wsClient.request`, over the hub. Used by device flows (deviceWs) that need a node result
+ * synchronously (agent list/create/recent) without the old REST `/proxy` round-trip.
+ *
+ * Flow: publishDown a `{ type, payload:{ ...payload, requestId } }` frame → node handles it and replies
+ * with an `<x>_result` up-frame (webEligible) → we match it on `up:{machineId}` by requestId. The reply
+ * also fans out to any real web clients of the agent, which harmlessly ignore an unknown requestId.
+ */
+import { randomUUID } from 'crypto'
+import { subscribeUp, publishDown } from './bus.js'
+import { routeDown } from './providerLink.js'
+import type { UpBusMsg } from './tunnel.js'
+
+export function nodeRequest<T = unknown>(
+ machineId: string,
+ type: string,
+ payload: Record<string, unknown> = {},
+ timeoutMs = 15000,
+): Promise<T> {
+ const requestId = randomUUID()
+ return new Promise<T>((resolve, reject) => {
+ let unsub: (() => void) | null = null
+ let done = false
+ const finish = (fn: () => void): void => {
+ if (done) return
+ done = true
+ if (unsub) unsub()
+ clearTimeout(timer)
+ fn()
+ }
+ const timer = setTimeout(
+ () => finish(() => reject(new Error(`node rpc timed out: ${type} (agent ${machineId})`))),
+ timeoutMs,
+ )
+ subscribeUp(machineId, (msg: UpBusMsg) => {
+ const f = msg.frame as { payload?: { requestId?: string; error?: unknown } }
+ if (f?.payload?.requestId !== requestId) return
+ finish(() =>
+ f.payload!.error != null
+ ? reject(new Error(String(f.payload!.error)))
+ : resolve(f.payload as T),
+ )
+ })
+ .then((u) => {
+ if (done) { u(); return }
+ unsub = u
+ // Publish only AFTER the subscription is live, else a fast reply is missed.
+ const down = { connId: '', frame: { type, payload: { ...payload, requestId } } }
+ void routeDown(machineId, down, () => publishDown(machineId, down))
+ })
+ .catch((err) => finish(() => reject(err instanceof Error ? err : new Error(String(err)))))
+ })
+}
diff --git a/backend/src/lib/p2pSignaling.test.ts b/backend/src/lib/p2pSignaling.test.ts
new file mode 100644
index 000000000..a18392928
--- /dev/null
+++ b/backend/src/lib/p2pSignaling.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import {
+ isEncryptedP2pFrame,
+ P2P_SIGNAL_MAX_FRAMES_PER_MINUTE,
+ p2pFrameBytes,
+ P2pSignalRateGuard,
+} from './p2pSignaling.js'
+
+describe('P2P signaling relay guard', () => {
+ it('accepts only opaque pairwise E2EE envelopes', () => {
+ const encrypted = {
+ type: 'p2p_offer',
+ payload: { __e2e: { v: 1, n: 3, k: 'p', ct: 'opaque-ciphertext' } },
+ }
+ expect(isEncryptedP2pFrame(encrypted)).toBe(true)
+ expect(p2pFrameBytes(encrypted)).toBe(Buffer.byteLength(JSON.stringify(encrypted)))
+ expect(isEncryptedP2pFrame({ ...encrypted, payload: { sessionId: 'plaintext' } })).toBe(false)
+ expect(isEncryptedP2pFrame({ ...encrypted, payload: { __e2e: { v: 1, n: 3, k: 'g', ct: 'x' } } })).toBe(false)
+ })
+
+ it('caps signaling frames per rolling minute and resets the fixed window', () => {
+ let now = 1_000
+ const guard = new P2pSignalRateGuard(() => now)
+ for (let i = 0; i < P2P_SIGNAL_MAX_FRAMES_PER_MINUTE; i++) expect(guard.allow(1)).toBe(true)
+ expect(guard.allow(1)).toBe(false)
+ now += 60_000
+ expect(guard.allow(1)).toBe(true)
+ })
+})
diff --git a/backend/src/lib/p2pSignaling.ts b/backend/src/lib/p2pSignaling.ts
new file mode 100644
index 000000000..5cd86abdb
--- /dev/null
+++ b/backend/src/lib/p2pSignaling.ts
@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto'
+import { env } from '../config/env.js'
+import { turnCredentials } from './turnCredentials.js'
+import type { Frame } from './tunnel.js'
+
+export const P2P_SIGNAL_PROTOCOL_VERSION = 1
+export const P2P_SIGNAL_MAX_BYTES = 128 * 1024
+export const P2P_SIGNAL_MAX_FRAMES_PER_MINUTE = 240
+export const P2P_SIGNAL_MAX_BYTES_PER_MINUTE = 4 * 1024 * 1024
+
+export const P2P_DOWN_TYPES = new Set(['p2p_offer', 'p2p_ice_candidate', 'p2p_abort'])
+export const P2P_UP_TYPES = new Set(['p2p_answer', 'p2p_ice_candidate', 'p2p_abort'])
+
+export function p2pFrameBytes(frame: Frame): number {
+ return Buffer.byteLength(JSON.stringify(frame), 'utf8')
+}
+
+/** The backend may route signaling but must never learn the candidate/SDP inside it. */
+export function isEncryptedP2pFrame(frame: Frame): boolean {
+ const payload = frame.payload
+ if (!payload || typeof payload !== 'object') return false
+ const envelope = (payload as { __e2e?: unknown }).__e2e
+ if (!envelope || typeof envelope !== 'object') return false
+ const value = envelope as { v?: unknown; n?: unknown; k?: unknown; ct?: unknown }
+ return value.v === 1
+ && Number.isSafeInteger(value.n)
+ && value.k === 'p'
+ && typeof value.ct === 'string'
+}
+
+export class P2pSignalRateGuard {
+ private startedAt = 0
+ private frames = 0
+ private bytes = 0
+
+ constructor(private readonly now: () => number = () => Date.now()) {}
+
+ allow(size: number): boolean {
+ const timestamp = this.now()
+ if (timestamp - this.startedAt >= 60_000) {
+ this.startedAt = timestamp
+ this.frames = 0
+ this.bytes = 0
+ }
+ if (this.frames + 1 > P2P_SIGNAL_MAX_FRAMES_PER_MINUTE
+ || this.bytes + size > P2P_SIGNAL_MAX_BYTES_PER_MINUTE) return false
+ this.frames++
+ this.bytes += size
+ return true
+ }
+}
+
+function rolloutBucket(userId: string, machineId: string): number {
+ return createHash('sha256').update(`${userId}\0${machineId}`).digest().readUInt32BE(0) % 100
+}
+
+function stunUrls(): string[] {
+ return env.TERMINAL_P2P_STUN_URLS.split(',')
+ .map((url) => url.trim())
+ .filter((url) => /^stuns?:/i.test(url))
+ .slice(0, 8)
+}
+
+/**
+ * Stays SYNCHRONOUS. Two of the three call sites are per-frame gates — one of them in adapterWs, whose
+ * onMessage cannot be awaited at all — so the TURN credential is read from a warm snapshot rather than
+ * fetched here. See the header of lib/turnCredentials.ts before changing this signature.
+ *
+ * `turn` is absent whenever TURN is unconfigured or Cloudflare is unreachable, and clients treat that
+ * as STUN-only, so every failure lands on the behaviour we shipped before TURN existed.
+ */
+export function terminalP2pPolicy(userId: string, machineId: string): {
+ enabled: boolean
+ protocolVersion: number
+ stunUrls: string[]
+ openWaitMs: number
+ turn?: { urls: string[]; username: string; credential: string }
+} {
+ const urls = stunUrls()
+ const turn = turnCredentials()
+ return {
+ enabled: urls.length > 0 && rolloutBucket(userId, machineId) < env.TERMINAL_P2P_ROLLOUT_PERCENT,
+ protocolVersion: P2P_SIGNAL_PROTOCOL_VERSION,
+ stunUrls: urls,
+ openWaitMs: env.TERMINAL_P2P_OPEN_WAIT_MS,
+ ...(turn ? { turn } : {}),
+ }
+}
diff --git a/backend/src/lib/password.ts b/backend/src/lib/password.ts
new file mode 100644
index 000000000..803bb313d
--- /dev/null
+++ b/backend/src/lib/password.ts
@@ -0,0 +1,18 @@
+import { randomBytes, scryptSync, timingSafeEqual } from 'crypto'
+
+// Format: "scrypt$<saltHex>$<hashHex>". Built-in scrypt → no native dependency.
+const KEYLEN = 64
+
+export function hashPassword(password: string): string {
+ const salt = randomBytes(16)
+ const dk = scryptSync(password, salt, KEYLEN)
+ return `scrypt$${salt.toString('hex')}$${dk.toString('hex')}`
+}
+
+export function verifyPassword(password: string, stored: string): boolean {
+ const [scheme, saltHex, hashHex] = stored.split('$')
+ if (scheme !== 'scrypt' || !saltHex || !hashHex) return false
+ const expected = Buffer.from(hashHex, 'hex')
+ const dk = scryptSync(password, Buffer.from(saltHex, 'hex'), expected.length)
+ return expected.length === dk.length && timingSafeEqual(expected, dk)
+}
diff --git a/backend/src/lib/prisma.ts b/backend/src/lib/prisma.ts
new file mode 100644
index 000000000..cfb603e09
--- /dev/null
+++ b/backend/src/lib/prisma.ts
@@ -0,0 +1,24 @@
+import { PrismaClient, type Prisma } from '@prisma/client'
+import { env } from '../config/env.js'
+import { logger } from '../utils/logger.js'
+
+// The Prisma CLI (db push) reads env("DATABASE_URL"); keep it in sync for any manual run.
+process.env.DATABASE_URL ??= env.DATABASE_URL
+
+export const prisma = new PrismaClient({
+ datasources: { db: { url: env.DATABASE_URL } },
+})
+
+/** "Not soft-deleted" filter for Machine findMany where-clauses. Mongo-Prisma gotcha: legacy
+ * rows have NO `deletedAt` field and `{deletedAt: null}` matches only an explicit null, so the
+ * filter must accept both null and absent. `findUnique` can't take this — post-check
+ * `binding.deletedAt` instead. */
+export const machineAlive: Prisma.MachineWhereInput = { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] }
+
+const gracefulShutdown = async () => {
+ logger.info('Disconnecting Prisma client...')
+ await prisma.$disconnect().catch(() => { /* ignore */ })
+}
+
+process.on('SIGINT', gracefulShutdown)
+process.on('SIGTERM', gracefulShutdown)
diff --git a/backend/src/lib/provider/client.ts b/backend/src/lib/provider/client.ts
new file mode 100644
index 000000000..69d9a82a8
--- /dev/null
+++ b/backend/src/lib/provider/client.ts
@@ -0,0 +1,257 @@
+/**
+ * Autonomous provider protocol client — the eight methods a `provider` machine speaks.
+ *
+ * JSON-RPC 2.0 over HTTPS POST, with SSE for the turn stream. There is **no WebSocket and nothing
+ * long-lived**: a turn is one HTTP request whose response body streams back. That is why a provider
+ * machine needs no owning worker, no `register`/`unregister`, and no socket to watch.
+ *
+ * EVERYTHING IS KEYED BY `agentId`. A provider has no session concept: one agent is one continuous
+ * transcript. The session the web keys its turn lifecycle on is synthesised on our side
+ * (`providerLink.ts`), so the provider never learns the concept exists.
+ *
+ * Every request goes through `providerFetch` — the URL came from the machine owner, so the SSRF guard
+ * is not optional. See `lib/providerUrl.ts`; the address policy is enforced at connect time.
+ *
+ * There is no discovery step: one URL, one credential header, and the methods below. Everything a
+ * client needs to know it learns by calling.
+ *
+ * Contract: autonomous-ai/autonomous-harness → provider/spec/README.md.
+ */
+import { providerFetch, readBodyCapped, type ProviderResponse } from '../providerUrl.js'
+
+export interface ProviderCallOptions {
+ url: string
+ credential: string
+ timeoutMs?: number
+ signal?: AbortSignal
+}
+
+export class ProviderError extends Error {
+ constructor(message: string, readonly kind: ProviderErrorKind, readonly status?: number) {
+ super(message)
+ this.name = 'ProviderError'
+ }
+}
+
+/**
+ * Each kind exists because it needs different words in front of the user.
+ *
+ * - `unauthenticated` — the credential is wrong. Not the same sentence as "the provider is down", and
+ * once the two are collapsed the distinction cannot be recovered downstream.
+ * - `refused` — the provider answered CORRECTLY and said no, with a reason of its own. Since nothing
+ * is declared in advance, this is how a provider whose agents are managed in its own product
+ * declines `agent.create`: the message ("agents are managed in Example Co") is the whole mitigation
+ * for having no capability declarations, so it must reach the user verbatim.
+ * - `protocol` — it answered, but not the way this protocol says to. Almost always a URL pointing at
+ * something else entirely.
+ * - `transport` / `not_streaming` — could not reach it, or it would not stream.
+ */
+export type ProviderErrorKind = 'unauthenticated' | 'refused' | 'transport' | 'protocol' | 'not_streaming'
+
+/** Error codes are strings, not numbers. */
+const UNAUTHENTICATED_CODES = new Set(['unauthenticated', 'unauthorized'])
+
+/** The codes this protocol defines. One of these means "answered, and said no" — not "malformed". */
+const REFUSAL_CODES = new Set(['not_found', 'unsupported', 'invalid_request', 'rate_limited', 'internal'])
+
+/**
+ * One header, by convention rather than by declaration.
+ *
+ * There is no discovery document to ask where the credential goes, which means a provider cannot
+ * choose a different header. That is the trade: `Authorization: Bearer` is near-universal, and the
+ * alternative was a whole unauthenticated round trip whose only other job was to say "use this
+ * header".
+ */
+function authHeaders(opts: ProviderCallOptions, extra: Record<string, string> = {}): Record<string, string> {
+ return { 'content-type': 'application/json', authorization: `Bearer ${opts.credential}`, ...extra }
+}
+
+/** An authentication failure, and a deliberate refusal, must each be distinguishable from an outage. */
+function classify(status: number, errorCode?: string): ProviderErrorKind | null {
+ if (status === 401 || status === 403 || (errorCode && UNAUTHENTICATED_CODES.has(errorCode))) return 'unauthenticated'
+ if (errorCode && REFUSAL_CODES.has(errorCode)) return 'refused'
+ if (errorCode) return 'protocol'
+ if (status >= 400) return 'transport'
+ return null
+}
+
+// ── JSON-RPC ─────────────────────────────────────────────────────────────────────────────────────
+
+async function rpc<T>(opts: ProviderCallOptions, method: string, params: unknown): Promise<T> {
+ const res = await providerFetch(opts.url, {
+ method: 'POST',
+ headers: authHeaders(opts),
+ body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+ timeoutMs: opts.timeoutMs ?? 15_000,
+ signal: opts.signal,
+ })
+ const text = await readBodyCapped(res)
+ let parsed: { result?: T; error?: { code?: string; message?: string } }
+ try {
+ parsed = JSON.parse(text) as typeof parsed
+ } catch {
+ throw new ProviderError('provider did not return JSON', 'protocol', res.status)
+ }
+ const kind = classify(res.status, parsed.error?.code)
+ if (kind) throw new ProviderError(parsed.error?.message ?? `provider error ${res.status}`, kind, res.status)
+ if (parsed.result === undefined) throw new ProviderError('provider returned no result', 'protocol', res.status)
+ return parsed.result
+}
+
+// ── agent.list ───────────────────────────────────────────────────────────────────────────────────
+
+export interface ProviderAgent { id?: string; name?: string; description?: string }
+
+/** Scoped to the tenant the credential selects — which is why it is authenticated, unlike the card. */
+export const listAgents = (opts: ProviderCallOptions): Promise<{ agents?: ProviderAgent[] }> =>
+ rpc<{ agents?: ProviderAgent[] }>(opts, 'agent.list', {})
+
+// ── agent.history ────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * One agent's transcript, windowed.
+ *
+ * `events` are the SAME objects the live stream emits, so there is no second shape to reconcile and
+ * no way for "what you saw live" to drift from "what you see after a refresh". `before` is an opaque
+ * cursor the provider mints; we never construct one.
+ */
+export interface AgentHistory {
+ agentId?: string
+ events?: unknown[]
+ nextBefore?: string
+ truncated?: boolean
+}
+
+export const fetchAgentHistory = (
+ opts: ProviderCallOptions,
+ agentId: string,
+ window: { limit?: number; before?: string } = {},
+): Promise<AgentHistory> =>
+ rpc<AgentHistory>(opts, 'agent.history', {
+ agentId,
+ ...(window.limit ? { limit: window.limit } : {}),
+ ...(window.before ? { before: window.before } : {}),
+ })
+
+// ── turn.cancel ──────────────────────────────────────────────────────────────────────────────────
+
+export const cancelTurn = (opts: ProviderCallOptions, turnId: string): Promise<{ cancelled?: boolean }> =>
+ rpc<{ cancelled?: boolean }>(opts, 'turn.cancel', { turnId })
+
+// ── agent.create / rename / delete ───────────────────────────────────────────────────────────────
+
+/**
+ * Mutations on the agent list.
+ *
+ * Required of every provider, but a provider whose agents are managed in its own product does NOT
+ * implement a fake mutation — it answers `invalid_request` with a message, and that message is shown
+ * to the user ("agents are managed in Example Co"). An explanation the user can read beats a control
+ * that is silently missing, which is why nothing has to be declared in advance for the client to know
+ * what to hide.
+ */
+export const createAgent = (opts: ProviderCallOptions, name: string, description?: string): Promise<ProviderAgent> =>
+ rpc<ProviderAgent>(opts, 'agent.create', { name, ...(description ? { description } : {}) })
+
+export const renameAgent = (opts: ProviderCallOptions, agentId: string, name: string): Promise<ProviderAgent> =>
+ rpc<ProviderAgent>(opts, 'agent.rename', { agentId, name })
+
+export const deleteAgent = (opts: ProviderCallOptions, agentId: string): Promise<{ deleted?: boolean }> =>
+ rpc<{ deleted?: boolean }>(opts, 'agent.delete', { agentId })
+
+// ── agent.recap ──────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The agent's LAST recap — the device's tile text.
+ *
+ * The same object `recap_end` pushes on a turn's own stream, so there is one shape for a recap however
+ * it reaches us. A provider that summarises nothing answers with no `recap`, and the backend excerpts
+ * the turn itself instead.
+ */
+export const fetchRecap = (opts: ProviderCallOptions, agentId: string): Promise<ProviderRecap> =>
+ rpc<ProviderRecap>(opts, 'agent.recap', { agentId })
+
+export interface ProviderRecap {
+ recap?: unknown
+ text?: unknown
+ /** Which turn it summarises. Optional on the wire, and load-bearing — see `fetchProviderRecap`. */
+ turnId?: unknown
+}
+
+// ── agent.send (streaming) ───────────────────────────────────────────────────────────────────────
+
+export interface SendMessage {
+ agentId: string
+ /** Minted by US, before the request leaves — so `turn.cancel` is valid from the first millisecond. */
+ turnId: string
+ text: string
+ /** Set when answering a `turn_input_required`: same turn, continued. */
+ resume?: boolean
+}
+
+/**
+ * `agent.send`, yielding parsed SSE payloads in order.
+ *
+ * The response is consumed as a stream rather than buffered: a turn can run for minutes, and the
+ * whole point of the protocol is that partial output reaches the user while it does.
+ */
+export async function* sendMessage(
+ opts: ProviderCallOptions,
+ message: SendMessage,
+): AsyncGenerator<Record<string, unknown>> {
+ const res: ProviderResponse = await providerFetch(opts.url, {
+ method: 'POST',
+ headers: authHeaders(opts, { accept: 'text/event-stream' }),
+ body: JSON.stringify({
+ jsonrpc: '2.0',
+ id: 1,
+ method: 'agent.send',
+ params: {
+ agentId: message.agentId,
+ turnId: message.turnId,
+ ...(message.resume ? { resume: true } : {}),
+ message: { text: message.text },
+ },
+ }),
+ // A turn is long; the per-request budget must not cut it off mid-answer.
+ timeoutMs: opts.timeoutMs ?? 10 * 60_000,
+ signal: opts.signal,
+ })
+
+ const kind = classify(res.status)
+ if (kind) {
+ res.stream.destroy()
+ throw new ProviderError(`provider refused the turn (${res.status})`, kind, res.status)
+ }
+ // A non-SSE reply here means the provider is not conformant, and the client cannot stream.
+ const contentType = String(res.headers['content-type'] ?? '')
+ if (!contentType.includes('text/event-stream')) {
+ res.stream.destroy()
+ throw new ProviderError(`expected text/event-stream, got "${contentType}"`, 'not_streaming', res.status)
+ }
+
+ let buffer = ''
+ let seen = 0
+ for await (const chunk of res.stream) {
+ seen += (chunk as Buffer).length
+ // A provider that never stops streaming must not be able to exhaust this process.
+ if (seen > MAX_STREAM_BYTES) {
+ res.stream.destroy()
+ throw new ProviderError('provider stream exceeded the size limit', 'transport')
+ }
+ buffer += (chunk as Buffer).toString('utf8')
+ const frames = buffer.split('\n\n')
+ buffer = frames.pop() ?? ''
+ for (const frame of frames) {
+ const line = frame.split('\n').find((l) => l.startsWith('data:'))
+ if (!line) continue
+ try {
+ yield JSON.parse(line.slice(5).trim()) as Record<string, unknown>
+ } catch {
+ // A frame we cannot parse is dropped rather than failing the turn: the stream is
+ // third-party output and one malformed event must not lose the ones after it.
+ }
+ }
+ }
+}
+
+export const MAX_STREAM_BYTES = 32 * 1024 * 1024
diff --git a/backend/src/lib/provider/events.test.ts b/backend/src/lib/provider/events.test.ts
new file mode 100644
index 000000000..15c7e3699
--- /dev/null
+++ b/backend/src/lib/provider/events.test.ts
@@ -0,0 +1,140 @@
+// The trust boundary. Everything here arrives from a third party at a URL the machine owner typed,
+// and lands on the web UI and the physical device screen — so the assertions that matter are about
+// what gets REFUSED, not what gets through.
+import { describe, expect, it } from 'vitest'
+import { ALLOWED_KINDS, MAX_CONSECUTIVE_INVALID, TERMINAL_KINDS, eventToFrame, mapEvent, turnOutcome } from './events.js'
+
+const frames = (raw: unknown): Array<{ type: string; payload: Record<string, unknown> }> => {
+ const m = mapEvent(raw)
+ return m.kind === 'frames' || m.kind === 'terminal' ? m.frames as never : []
+}
+const one = (raw: unknown): { type: string; payload: Record<string, unknown> } | undefined => frames(raw)[0]
+
+describe('the vocabulary and the switch cannot drift', () => {
+ it('every allowed kind maps to a frame', () => {
+ // The rule that keeps ALLOWED_KINDS honest: it is documentation unless something proves the
+ // switch agrees with it. A kind added to the set but not the switch fails here.
+ const carrier: Record<string, Record<string, unknown>> = {
+ user_message: { text: 'hi' },
+ thinking_delta: { text: 'mm' },
+ thinking_title: { text: 'Considering' },
+ text_delta: { text: 'out' },
+ tool_start: { toolId: 'c1', tool: 'Read' },
+ tool_end: { toolId: 'c1', ok: true },
+ context_compact: {},
+ done: { text: 'done' },
+ recap_start: {},
+ recap_end: { recap: 'r' },
+ }
+ for (const kind of ALLOWED_KINDS) {
+ expect(eventToFrame({ kind, ...carrier[kind] }, kind), `${kind} maps to nothing`).toBeTruthy()
+ }
+ })
+
+ it('an unrecognised kind is dropped, not forwarded', () => {
+ expect(mapEvent({ kind: 'exec_shell', text: 'rm -rf /' }).kind).toBe('ignore')
+ })
+
+ it('a kind that is not a string is not a kind', () => {
+ expect(mapEvent({ kind: 42, text: 'hi' }).kind).toBe('frames') // falls back to plain text
+ expect(mapEvent({ kind: {}, text: '' }).kind).toBe('invalid')
+ })
+
+ it('a non-object is invalid rather than throwing', () => {
+ for (const raw of [null, undefined, 'a string', 7, true]) {
+ expect(mapEvent(raw).kind, String(raw)).toBe('invalid')
+ }
+ })
+
+ it('bounds how much malformed input a provider may send', () => {
+ expect(MAX_CONSECUTIVE_INVALID).toBeGreaterThan(0)
+ })
+})
+
+describe('richness is opt-in', () => {
+ it('a bare {text} renders as assistant output — the simplest correct implementation', () => {
+ expect(one({ text: 'just words' })).toEqual({ type: 'text_delta', payload: { content: 'just words' } })
+ })
+
+ it('but an event carrying neither kind nor text is invalid', () => {
+ expect(mapEvent({}).kind).toBe('invalid')
+ })
+})
+
+describe('turn lifecycle is first-class, not derived', () => {
+ it('each terminal kind ends the stream', () => {
+ for (const kind of TERMINAL_KINDS) {
+ expect(mapEvent({ kind }).kind, kind).toBe('terminal')
+ }
+ })
+
+ it('turn_started renders nothing — it carries ids we already know', () => {
+ expect(mapEvent({ kind: 'turn_started', turnId: 't', agentId: 'a' }).kind).toBe('ignore')
+ })
+
+ it('separates cancelled from failed, because the UI says different words', () => {
+ const cancelled = mapEvent({ kind: 'turn_cancelled' })
+ const failed = mapEvent({ kind: 'turn_failed', error: { message: 'boom' } })
+ expect(cancelled.kind === 'terminal' && turnOutcome(cancelled.end)).toEqual({ aborted: true, failed: false })
+ expect(failed.kind === 'terminal' && turnOutcome(failed.end)).toEqual({ aborted: false, failed: true })
+ })
+
+ it('input_required is NOT a failure — the turn is paused, not broken', () => {
+ const m = mapEvent({ kind: 'turn_input_required', prompt: 'Delete 3 files?' })
+ expect(m.kind).toBe('terminal')
+ if (m.kind !== 'terminal') return
+ expect(m.end).toEqual({ outcome: 'input_required', prompt: 'Delete 3 files?' })
+ expect(turnOutcome(m.end)).toEqual({ aborted: false, failed: false })
+ })
+})
+
+describe('tool calls', () => {
+ it('drops a tool_start with no id — an unpaired call renders as a row that never resolves', () => {
+ expect(one({ kind: 'tool_start', tool: 'Read' })).toBeUndefined()
+ })
+
+ it('drops a tool_end with no id for the same reason', () => {
+ expect(one({ kind: 'tool_end', ok: true })).toBeUndefined()
+ })
+
+ it('carries the id through so start and end pair up even when tools overlap', () => {
+ expect(one({ kind: 'tool_start', toolId: 'c7', tool: 'Bash' })!.payload)
+ .toMatchObject({ id: 'c7', tool: 'Bash' })
+ })
+
+ it('treats ok:false as the error flag, and a MISSING ok as not-an-error', () => {
+ // "The provider did not say" is not the same as "the provider said it failed".
+ expect(one({ kind: 'tool_end', toolId: 'c7', ok: false })!.payload.isError).toBe(true)
+ expect(one({ kind: 'tool_end', toolId: 'c7' })!.payload.isError).toBe(false)
+ })
+
+ it('names an unnamed tool rather than rendering a blank row', () => {
+ expect(one({ kind: 'tool_end', toolId: 'c7' })!.payload.tool).toBe('tool')
+ })
+})
+
+describe('the recap phase', () => {
+ it('recap_end with no headline still produces a frame', () => {
+ // An absent recap is the provider saying "nothing to show". Swallowing it would leave the
+ // client's "preparing a recap" indicator open forever.
+ expect(one({ kind: 'recap_end' })).toEqual({ type: 'recap_end', payload: {} })
+ })
+
+ it('carries the headline and the body separately, under the names agent.recap uses', () => {
+ // `{recap, text}` — the identical object `agent.recap` hands back, so one mapper serves the
+ // pushed recap and the pulled one.
+ expect(one({ kind: 'recap_end', recap: 'Fixed it', text: 'The longer story.' })!.payload)
+ .toEqual({ recap: 'Fixed it', text: 'The longer story.' })
+ })
+})
+
+describe('empty payloads', () => {
+ it('a delta with no text is dropped rather than emitted as an empty bubble', () => {
+ expect(one({ kind: 'text_delta', text: '' })).toBeUndefined()
+ expect(one({ kind: 'thinking_delta' })).toBeUndefined()
+ })
+
+ it('context_compact always says something, since it has no text of its own', () => {
+ expect(one({ kind: 'context_compact' })!.payload.message).toBe('Context compacted')
+ })
+})
diff --git a/backend/src/lib/provider/events.ts b/backend/src/lib/provider/events.ts
new file mode 100644
index 000000000..c114bb93f
--- /dev/null
+++ b/backend/src/lib/provider/events.ts
@@ -0,0 +1,219 @@
+/**
+ * Provider events → our wire frames. **The trust boundary.**
+ *
+ * Everything arriving here was produced by a third party at a URL the machine owner typed. It goes
+ * straight to the web UI and to the physical device screen, so this module treats it as untrusted
+ * input: known event kinds are mapped, everything else is dropped and counted, and a stream that
+ * keeps violating the shape gets closed.
+ *
+ * `adapterWs.ts` forwards its frames verbatim and opaque, which is fine because the adapter is our
+ * code. That is exactly the property a provider does not have — dropping E2EE for this mode did not
+ * reduce the need for validation here, it raised it.
+ *
+ * The frames it emits are the ones the web and the device already speak — this module is the only
+ * place a provider's vocabulary becomes ours.
+ *
+ * Spec: autonomous-ai/autonomous-harness → provider/spec/README.md.
+ */
+import type { Frame } from '../tunnel.js'
+
+/**
+ * The event vocabulary.
+ *
+ * ENFORCEMENT LIVES IN THE `switch` in `eventToFrame`, whose `default` drops anything unrecognised.
+ * This set exists so the vocabulary can be asserted and reasoned about from outside — an earlier
+ * version also checked it before the switch, which a mutation test exposed as dead code: removing
+ * that check changed nothing, because the switch already refused. Two lists for one rule is how they
+ * drift, so there is one rule and one list, and `every allowed kind maps to a frame` keeps them
+ * honest.
+ */
+export const ALLOWED_KINDS = new Set([
+ 'user_message',
+ 'thinking_delta',
+ 'thinking_title',
+ 'text_delta',
+ 'tool_start',
+ 'tool_end',
+ 'context_compact',
+ 'done',
+ 'recap_start',
+ 'recap_end',
+])
+
+/**
+ * Terminal kinds, which end the stream. Exactly one must arrive.
+ *
+ * Explicit rather than derived from a state machine, which is what makes "every stream ends properly"
+ * a single assertion instead of a state table.
+ */
+export const TERMINAL_KINDS = new Set(['turn_completed', 'turn_failed', 'turn_cancelled', 'turn_input_required'])
+
+export interface ProviderEvent {
+ kind?: string
+ [field: string]: unknown
+}
+
+export type TurnEnd =
+ | { outcome: 'completed' }
+ | { outcome: 'failed'; message?: string }
+ | { outcome: 'cancelled' }
+ /** Not a failure: the turn is PAUSED for a human answer, which arrives as a resumed `agent.send`. */
+ | { outcome: 'input_required'; prompt?: string }
+
+export type MappedEvent =
+ | { kind: 'frames'; frames: Frame[] }
+ | { kind: 'terminal'; end: TurnEnd; frames: Frame[] }
+ | { kind: 'invalid'; reason: string }
+ | { kind: 'ignore' }
+
+/**
+ * Per-field ceiling on anything a provider sends.
+ *
+ * `MAX_FRAMES_PER_TURN` bounds how MANY events arrive and `MAX_STREAM_BYTES` bounds a whole turn at
+ * 32 MB — neither stops one event from carrying all of it. Every frame here fans out through Redis to
+ * every open web tab and to the device screen, so a single 32 MB `text_delta` is amplified once per
+ * client. 100k characters is far past any real assistant message and far short of a problem.
+ */
+export const MAX_FIELD_CHARS = 100_000
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v.slice(0, MAX_FIELD_CHARS) : undefined)
+const num = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) ? v : undefined)
+
+/**
+ * Tool input is arbitrary JSON, so it is bounded by its SERIALISED size — there is no length to slice.
+ * Oversized input is replaced by a marked preview rather than dropped: the tool row still renders, and
+ * it says plainly that there was more.
+ */
+function boundedInput(v: unknown): unknown {
+ if (v == null) return {}
+ const json = JSON.stringify(v) ?? ''
+ return json.length <= MAX_FIELD_CHARS ? v : { truncated: true, preview: json.slice(0, 1_000) }
+}
+
+/**
+ * Map one SSE payload.
+ *
+ * Returns `invalid` rather than throwing so the caller can count violations and decide when a
+ * provider has misbehaved enough to disconnect — one malformed frame is not worth losing a turn over,
+ * a hundred is.
+ */
+export function mapEvent(raw: unknown): MappedEvent {
+ if (!raw || typeof raw !== 'object') return { kind: 'invalid', reason: 'event is not an object' }
+ const event = raw as ProviderEvent
+ const kind = str(event.kind)
+ // RICHNESS IS OPT-IN. A provider that only ever sends `{text: "…"}` is conformant, and its output
+ // renders as plain assistant text. Treating that as invalid would reject the simplest possible
+ // correct implementation — which is the one a partner writes first.
+ if (!kind) {
+ const plain = typeof event.text === 'string' ? event.text.slice(0, MAX_FIELD_CHARS) : ''
+ return plain
+ ? { kind: 'frames', frames: [{ type: 'text_delta', payload: { content: plain } }] }
+ : { kind: 'invalid', reason: 'event has neither a kind nor text' }
+ }
+
+ if (TERMINAL_KINDS.has(kind)) return { kind: 'terminal', end: terminalEnd(kind, event), frames: [] }
+
+ // `turn_started` carries only ids we already know; it exists so a provider can mark the boundary
+ // and so the conformance runner can require one. Nothing is rendered from it.
+ if (kind === 'turn_started') return { kind: 'ignore' }
+
+ const frame = eventToFrame(event, kind)
+ return frame ? { kind: 'frames', frames: [frame] } : { kind: 'ignore' }
+}
+
+function terminalEnd(kind: string, event: ProviderEvent): TurnEnd {
+ switch (kind) {
+ case 'turn_cancelled': return { outcome: 'cancelled' }
+ case 'turn_input_required': {
+ const prompt = str(event.prompt)
+ return { outcome: 'input_required', ...(prompt ? { prompt } : {}) }
+ }
+ case 'turn_failed': {
+ const err = (event.error ?? {}) as Record<string, unknown>
+ const message = str(err.message)
+ return { outcome: 'failed', ...(message ? { message } : {}) }
+ }
+ default: return { outcome: 'completed' }
+ }
+}
+
+/** One event → one client frame, or null when it carries nothing we render. */
+export function eventToFrame(event: ProviderEvent, kind: string): Frame | null {
+ const text = typeof event.text === 'string' ? event.text.slice(0, MAX_FIELD_CHARS) : ''
+
+ switch (kind) {
+ case 'text_delta':
+ case 'thinking_delta':
+ return text ? { type: kind, payload: { content: text, ...idOf(event.thinkingId) } } : null
+
+ case 'thinking_title': {
+ const title = str(event.title) ?? str(event.text)
+ return title ? { type: 'thinking_title', payload: { title, ...idOf(event.thinkingId) } } : null
+ }
+
+ case 'user_message':
+ return text ? { type: 'user_message', payload: { content: text } } : null
+
+ case 'tool_start': {
+ const id = str(event.toolId)
+ if (!id) return null // an unpaired tool call would render as a row that never resolves
+ return { type: 'tool_start', payload: { id, tool: str(event.tool) ?? 'tool', input: boundedInput(event.input) } }
+ }
+
+ case 'tool_end': {
+ const id = str(event.toolId)
+ if (!id) return null
+ const seconds = num(event.durationSeconds)
+ return {
+ type: 'tool_end',
+ payload: {
+ id,
+ tool: str(event.tool) ?? 'tool',
+ output: typeof event.output === 'string' ? event.output.slice(0, MAX_FIELD_CHARS) : text,
+ // `ok: false` is the failure signal; absent `ok` means the provider did not say, which is
+ // not the same as saying it failed.
+ isError: event.ok === false,
+ summary: str(event.summary) ?? '',
+ ...(seconds != null ? { durationSeconds: seconds } : {}),
+ },
+ }
+ }
+
+ case 'context_compact':
+ return { type: 'context_compact', payload: { message: text || 'Context compacted' } }
+
+ case 'done':
+ return { type: 'done', payload: { result: text } }
+
+ // The recap phase, bracketed. Neither of these is forwarded to a client as-is: `providerLink`
+ // consumes them and re-emits the frames the web and the device already speak.
+ case 'recap_start':
+ return { type: 'recap_start', payload: {} }
+
+ // Deliberately NOT null when the headline is missing: an absent `recap` is the provider saying
+ // "nothing to show", and swallowing that would leave the client's "preparing a recap" indicator
+ // open forever.
+ case 'recap_end': {
+ const recap = str(event.recap)
+ // `text`, not `body`: `agent.recap` hands back this same object, and one shape for the pushed
+ // and the pulled recap is what lets a single mapper serve both.
+ return { type: 'recap_end', payload: { ...(recap ? { recap } : {}), ...(text ? { text } : {}) } }
+ }
+
+ default:
+ return null
+ }
+}
+
+function idOf(v: unknown): Record<string, string> {
+ const id = str(v)
+ return id ? { thinkingId: id } : {}
+}
+
+/** Terminal end → how the turn ended, for `turn_ended` and the error surface. */
+export function turnOutcome(end: TurnEnd): { aborted: boolean; failed: boolean } {
+ return { aborted: end.outcome === 'cancelled', failed: end.outcome === 'failed' }
+}
+
+/** How many malformed events a provider may send before we stop listening to it. */
+export const MAX_CONSECUTIVE_INVALID = 20
diff --git a/backend/src/lib/provider/history.ts b/backend/src/lib/provider/history.ts
new file mode 100644
index 000000000..366839816
--- /dev/null
+++ b/backend/src/lib/provider/history.ts
@@ -0,0 +1,98 @@
+/**
+ * The transcript behind `session_get` for a `provider` machine.
+ *
+ * A provider has no sessions: one agent is one continuous transcript, fetched with `agent.history`
+ * and windowed by `{limit, before}`. History is REQUIRED of every provider, so there is no
+ * "undeclared" branch here any more — it either answers or it errors.
+ *
+ * The field names on OUR side are not a new invention and must not become one: `{limit, before}` in
+ * and `{hasMore, oldestCursor, staleCursor}` out is exactly the pager the node path already speaks
+ * (`machine-node/api/src/routes/websocket.ts` `session_get`, `SessionService.getSessionDetail`) and
+ * the web already drives (`web/src/lib/store/slices/messagesSlice/sessionActions.ts`). A provider
+ * machine has to be indistinguishable from a node one by the time the frame reaches the client — so
+ * the provider's `nextBefore` is translated into that pager here, and never leaked upward.
+ *
+ * Spec: autonomous-ai/autonomous-harness → provider/spec/README.md.
+ */
+import type { Frame } from '../tunnel.js'
+import { fetchAgentHistory, type ProviderCallOptions } from './client.js'
+import { eventToFrame, type ProviderEvent } from './events.js'
+
+/** The node's own ceiling, mirrored so a provider machine cannot be asked for a bigger window. */
+export const MAX_HISTORY_LIMIT = 500
+
+export interface AgentTranscript {
+ events: Frame[]
+ /** Present only for a WINDOWED answer — its absence is what marks a response as complete. */
+ hasMore?: boolean
+ oldestCursor?: string | null
+ /** The provider hit its own transcript ceiling and said so, rather than truncating in silence. */
+ truncated?: boolean
+}
+
+/**
+ * Provider events → the event stream the web actually renders.
+ *
+ * The client has two branches (`messagesSlice/sessionActions.ts`): `events`, which is structured and
+ * carries tool output, thinking and ordering; and a `messages` fallback that expects **Claude's own
+ * JSONL shape** (`msg.message.content[]`). A provider speaks neither, so the fallback would drop every
+ * entry on `if (!msg.message?.content) continue` and a provider transcript would render as an empty
+ * chat no matter how much history came back. Mapping to `events` is the honest translation.
+ *
+ * It goes through the SAME `eventToFrame` a live turn does — and now on the same objects, since
+ * `agent.history` returns exactly what the stream emitted. A replayed transcript and the live view
+ * cannot disagree about the same event, because there is only one shape and one mapper.
+ */
+export function historyToEvents(events: unknown[]): Frame[] {
+ const out: Frame[] = []
+ for (const raw of events) {
+ if (!raw || typeof raw !== 'object') continue
+ const event = raw as ProviderEvent
+ const kind = typeof event.kind === 'string' ? event.kind : ''
+ if (!kind) continue
+ const frame = eventToFrame(event, kind)
+ // The recap phase is a live-turn signal, not transcript content — it has no place in a replay,
+ // and the client's event vocabulary has no case for it.
+ if (frame && frame.type !== 'recap_start' && frame.type !== 'recap_end') out.push(frame)
+ }
+ return out
+}
+
+/** `undefined` for "no window asked for", which the wire treats as the whole transcript. */
+export function clampHistoryLimit(value: unknown): number | undefined {
+ const n = typeof value === 'number' ? value : Number(value)
+ if (!Number.isFinite(n) || n <= 0) return undefined
+ return Math.min(Math.floor(n), MAX_HISTORY_LIMIT)
+}
+
+/**
+ * One agent's transcript, already in client frames and client pager shape.
+ *
+ * `nextBefore` → `{hasMore, oldestCursor}` happens HERE rather than at the call site, because those
+ * two names are the client's contract and the provider must never see them. Note the asymmetry that
+ * mirrors the node path: the pager fields are attached only when a window was actually requested.
+ * Synthesising `hasMore: false` for a whole-transcript answer would tell the client "no older
+ * messages" about a response that was never windowed — true by accident, and false the moment paging
+ * is asked for.
+ */
+export async function fetchTranscript(
+ call: ProviderCallOptions,
+ agentId: string,
+ opts: { limit?: number; before?: string } = {},
+): Promise<AgentTranscript> {
+ const out = await fetchAgentHistory(call, agentId, {
+ ...(opts.limit ? { limit: opts.limit } : {}),
+ // A cursor without a window is meaningless — the same pairing the node enforces.
+ ...(opts.limit && opts.before ? { before: opts.before } : {}),
+ })
+ const transcript: AgentTranscript = {
+ events: historyToEvents(Array.isArray(out?.events) ? out.events : []),
+ }
+ if (opts.limit) {
+ const cursor = typeof out?.nextBefore === 'string' && out.nextBefore ? out.nextBefore : null
+ transcript.hasMore = cursor !== null
+ transcript.oldestCursor = cursor
+ }
+ if (out?.truncated === true) transcript.truncated = true
+ return transcript
+}
diff --git a/backend/src/lib/provider/recap.test.ts b/backend/src/lib/provider/recap.test.ts
new file mode 100644
index 000000000..08f6c9dc0
--- /dev/null
+++ b/backend/src/lib/provider/recap.test.ts
@@ -0,0 +1,109 @@
+// The device renders these on a round 466px screen, so the caps and the never-an-ellipsis rule are
+// the point — not the happy path.
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const call = vi.hoisted(() => vi.fn())
+vi.mock('./client.js', () => ({ fetchRecap: call }))
+
+const { BODY_MAX_CHARS, RECAP_MAX_CHARS, deriveRecap, fetchProviderRecap, toRecapEvent } =
+ await import('./recap.js')
+
+beforeEach(() => vi.clearAllMocks())
+
+describe('toRecapEvent', () => {
+ it('needs a headline — an entry without one renders as nothing', () => {
+ expect(toRecapEvent({ text: 'a body but no headline' })).toBeNull()
+ expect(toRecapEvent(undefined)).toBeNull()
+ expect(toRecapEvent({ recap: ' ' })).toBeNull()
+ })
+
+ it('falls back to the headline so the reader never opens on an empty pane', () => {
+ expect(toRecapEvent({ recap: 'Fixed it' })).toEqual({ kind: 'summary', recap: 'Fixed it', text: 'Fixed it' })
+ })
+
+ it('flattens whitespace — the tile is one line and newlines waste it', () => {
+ expect(toRecapEvent({ recap: 'a\n\n b\tc' })!.recap).toBe('a b c')
+ })
+
+ it('caps without ever appending an ellipsis', () => {
+ const long = 'word '.repeat(200)
+ const out = toRecapEvent({ recap: long, text: long })!
+ expect(out.recap.length).toBeLessThanOrEqual(RECAP_MAX_CHARS)
+ expect(out.text.length).toBeLessThanOrEqual(BODY_MAX_CHARS)
+ // A truncated line that ADVERTISES its truncation reads worse than one that simply ends.
+ expect(out.recap.endsWith('…')).toBe(false)
+ expect(out.recap.endsWith('...')).toBe(false)
+ })
+
+ it('cuts at a word boundary, but not so far back that the line collapses', () => {
+ const unbroken = 'x'.repeat(RECAP_MAX_CHARS + 50)
+ expect(toRecapEvent({ recap: unbroken })!.recap.length).toBe(RECAP_MAX_CHARS)
+ })
+})
+
+describe('deriveRecap — the gap-fill when a provider declares nothing', () => {
+ it('uses the opening sentence as the headline', () => {
+ const out = deriveRecap('Acme is at 118%. There is more detail after this.')!
+ expect(out.recap).toBe('Acme is at 118%.')
+ expect(out.text).toBe('Acme is at 118%. There is more detail after this.')
+ })
+
+ it('uses the whole thing when there is no sentence terminator', () => {
+ expect(deriveRecap('no terminator here')!.recap).toBe('no terminator here')
+ })
+
+ it('says nothing rather than inventing a tile for a silent turn', () => {
+ expect(deriveRecap('')).toBeNull()
+ expect(deriveRecap(' \n ')).toBeNull()
+ })
+})
+
+describe('fetchProviderRecap', () => {
+ const opts = { url: 'u', credential: 'k' }
+
+ it('asks for the agent’s LAST recap and maps it', async () => {
+ call.mockResolvedValue({ recap: 'Did the thing', text: 'Did the thing, at length' })
+ const out = await fetchProviderRecap(opts, 'alpha')
+ // No `n`: the method returns one recap, so there is nothing to page through and nothing to clamp.
+ expect(call).toHaveBeenCalledWith(opts, 'alpha')
+ expect(out).toEqual({ kind: 'summary', recap: 'Did the thing', text: 'Did the thing, at length' })
+ })
+
+ it('takes the SAME object shape the turn stream pushes', async () => {
+ // `agent.recap` and `recap_end` carry `{recap, text}` alike, which is what lets one mapper serve
+ // both. A pull that needed its own field names would need its own mapper, and two mappers are how
+ // the live tile and the restored tile end up saying different things about the same turn.
+ call.mockResolvedValue({ recap: 'Headline' })
+ expect(await fetchProviderRecap(opts, 'alpha')).toEqual(toRecapEvent({ recap: 'Headline' }))
+ })
+
+ it('NOTHING is legitimate — the caller then excerpts the turn instead', async () => {
+ // A provider that does not summarise says so by answering with no `recap`. There is no capability
+ // to declare and nothing to refuse; absence IS the answer.
+ call.mockResolvedValue({ agentId: 'alpha' })
+ expect(await fetchProviderRecap(opts, 'alpha')).toBeNull()
+ })
+
+ it('drops a recap belonging to a DIFFERENT turn', async () => {
+ // `agent.recap` is scoped to an agent and cannot be scoped to a turn, so the last recap a provider
+ // holds the instant a turn ends is very often the PREVIOUS turn's.
+ call.mockResolvedValue({ recap: 'stale', turnId: 't-old' })
+ expect(await fetchProviderRecap(opts, 'alpha', { turnId: 't-now' })).toBeNull()
+ })
+
+ it('keeps a recap that names no turn — the field is optional', async () => {
+ call.mockResolvedValue({ recap: 'untagged' })
+ const out = await fetchProviderRecap(opts, 'alpha', { turnId: 't-now' })
+ expect(out?.recap).toBe('untagged')
+ })
+
+ it('keeps a recap whose turn MATCHES', async () => {
+ call.mockResolvedValue({ recap: 'mine', turnId: 't-now' })
+ expect((await fetchProviderRecap(opts, 'alpha', { turnId: 't-now' }))?.recap).toBe('mine')
+ })
+
+ it('survives a provider answering with nothing at all', async () => {
+ call.mockResolvedValue(undefined)
+ expect(await fetchProviderRecap(opts, 'alpha')).toBeNull()
+ })
+})
diff --git a/backend/src/lib/provider/recap.ts b/backend/src/lib/provider/recap.ts
new file mode 100644
index 000000000..8cf1ba8c1
--- /dev/null
+++ b/backend/src/lib/provider/recap.ts
@@ -0,0 +1,122 @@
+/**
+ * Per-turn recap for a `provider` machine — the device's tile text.
+ *
+ * Two sources, in this order:
+ *
+ * 1. **The provider's own**, through `agent.recap`. This is a PULL by design, so it is asked for
+ * rather than pushed, and it is authoritative when the provider has one.
+ * 2. **Derived here**, when it answers with nothing. The backend does NOT run a model for this: it
+ * excerpts the turn's own assistant output. That keeps recap generation where it belongs (the
+ * engine that produced the turn) and still gives the device something true to show, instead of an
+ * empty tile for every provider that does not summarise.
+ *
+ * The caps are the wire's, not ours to pick: `recap` ≤ 200 comes from the recap schema, and 2000 for
+ * the body is what the node path and the `harness` CLI both use for a commander part. Nothing here
+ * ever appends an ellipsis — the same rule `capRecap` enforces in
+ * `machine-node/brain/src/prefrontal/recap.ts`, because a truncated line that ADVERTISES its
+ * truncation reads worse on a round 466px display than one that simply ends.
+ *
+ * Spec: autonomous-ai/autonomous-harness → provider/spec/README.md.
+ */
+import { fetchRecap, type ProviderCallOptions, type ProviderRecap } from './client.js'
+
+/** The `recap` ceiling — what fits a tile on a round 466px display at a glance. */
+export const RECAP_MAX_CHARS = 200
+/** One commander part — matches `SessionService.getRecentEvents` and the CLI's `MAX_PART`. */
+export const BODY_MAX_CHARS = 2000
+
+/**
+ * One tile.
+ *
+ * This is the shape `SessionService.getRecentEvents` returns for a node-backed machine and the shape
+ * `deviceWs.trimRecentEvents` already knows how to shrink — a provider machine must be
+ * indistinguishable from a node one by the time the frame reaches the device.
+ */
+export interface RecapEvent {
+ kind: 'summary'
+ /** The fuller body, shown in the device's tap-to-read reader. */
+ text: string
+ /** The headline shown on the tile at a glance. */
+ recap: string
+}
+
+/**
+ * A recap, however it reached us → the tile we render.
+ *
+ * The ONE place the caps and the body fallback live, because a recap arrives two ways — pulled with
+ * `agent.recap` and pushed on the turn's own stream as `recap_end` — and two copies of "cap at 200,
+ * fall back to the headline" is how the device ends up rendering two different strings for the same
+ * turn. Both carry the SAME object, which is what makes one mapper enough.
+ *
+ * Null when there is no headline: `recap` is the only field that must be present, and a recap without
+ * one renders as nothing.
+ */
+export function toRecapEvent(entry: { recap?: unknown; text?: unknown } | undefined): RecapEvent | null {
+ const recap = cap(flatten(entry?.recap), RECAP_MAX_CHARS)
+ if (!recap) return null
+ // `text` is optional. Falling back to the headline keeps the reader from opening on an empty pane.
+ return { kind: 'summary', recap, text: cap(flatten(entry?.text), BODY_MAX_CHARS) || recap }
+}
+
+/**
+ * Ask the provider for the agent's LAST recap.
+ *
+ * `null` is legitimate, not a failure: a provider that does not summarise says so by answering with
+ * no `recap`, and the caller excerpts the turn instead.
+ */
+export async function fetchProviderRecap(
+ call: ProviderCallOptions,
+ agentId: string,
+ opts: { turnId?: string } = {},
+): Promise<RecapEvent | null> {
+ const result: ProviderRecap = (await fetchRecap(call, agentId)) ?? {}
+ // Asking for ONE specific turn's recap. `agent.recap` is scoped to an AGENT and cannot be scoped to
+ // a turn, so the check happens here: the last recap a provider holds the instant a turn ends is very
+ // often the PREVIOUS turn's, and showing that as this turn's summary is worse than showing none. A
+ // recap that names no turn (the field is optional) is accepted, as it always was.
+ if (opts.turnId && typeof result.turnId === 'string' && result.turnId !== opts.turnId) return null
+ return toRecapEvent(result)
+}
+
+/**
+ * The gap-fill: excerpt the turn's own output.
+ *
+ * An excerpt, deliberately — not a generated summary and not a statistic. The headline is the answer's
+ * opening sentence, which for an assistant reply is very often the answer itself; the body is the
+ * reply.
+ *
+ * Returns null when the turn produced no assistant text at all, and the caller then shows nothing.
+ * Inventing a tile for a turn that said nothing is worse than an empty one.
+ */
+export function deriveRecap(assistantText: string): RecapEvent | null {
+ const body = cap(flatten(assistantText), BODY_MAX_CHARS)
+ if (!body) return null
+ const recap = cap(firstSentence(body), RECAP_MAX_CHARS)
+ if (!recap) return null
+ return { kind: 'summary', recap, text: body }
+}
+
+/** Whitespace collapsed to single spaces: the device renders one line, and newlines waste it. */
+function flatten(value: unknown): string {
+ if (typeof value !== 'string') return ''
+ return value.replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Hard cap, cut at a word boundary when there is one, and NEVER with an ellipsis appended.
+ *
+ * The boundary search is bounded to the last 40% so a long unbroken token cannot collapse the line to
+ * a couple of words.
+ */
+function cap(text: string, max: number): string {
+ if (text.length <= max) return text
+ const cut = text.slice(0, max)
+ const space = cut.lastIndexOf(' ')
+ return (space > max * 0.6 ? cut.slice(0, space) : cut).trimEnd()
+}
+
+/** Up to the first sentence terminator; the whole string when it has none. */
+function firstSentence(text: string): string {
+ const match = /[.!?](\s|$)/.exec(text)
+ return match ? text.slice(0, match.index + 1) : text
+}
diff --git a/backend/src/lib/providerLink.e2e.test.ts b/backend/src/lib/providerLink.e2e.test.ts
new file mode 100644
index 000000000..5bf42b729
--- /dev/null
+++ b/backend/src/lib/providerLink.e2e.test.ts
@@ -0,0 +1,823 @@
+// End-to-end for the provider path, against a REAL provider server over a real socket.
+//
+// Everything below the seam is genuine: HTTP, SSE framing, the SSRF-guarded client, the event
+// mapper. Only the machine's surroundings (Mongo, Redis, billing) are stubbed, because the thing
+// under test is the wire path, not the database.
+//
+// This exists because every unit test in this feature passed while the flow was still broken end to
+// end — the web never even fetched a project list, since a provider machine reported itself offline.
+// A test that speaks the actual protocol is the only kind that would have caught that.
+import { createServer, type Server, type ServerResponse } from 'node:http'
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const published = vi.hoisted(() => [] as Array<{ machineId: string; frame: { type?: string; payload?: Record<string, unknown> } }>)
+const binding = vi.hoisted(() => ({ current: null as Record<string, unknown> | null }))
+
+vi.mock('../config/env.js', () => ({ env: { PROVIDER_ALLOW_INSECURE_URLS: true } }))
+vi.mock('./prisma.js', () => ({
+ prisma: { machine: { findUnique: vi.fn(async () => binding.current) } },
+}))
+// The recap cache is Redis in production (four cluster workers share it); an in-memory stand-in is
+// enough here, and keeping it real rather than a no-op is what lets the `agent_recent` fallback be
+// tested at all.
+const recapCache = vi.hoisted(() => new Map<string, unknown[]>())
+vi.mock('./bus.js', () => ({
+ publishUp: vi.fn(async (machineId: string, msg: { frame: unknown }) => {
+ published.push({ machineId, frame: msg.frame as { type?: string } })
+ return 1
+ }),
+ pushMachineRecap: vi.fn(async (machineId: string, agentId: string, entry: unknown) => {
+ if (!agentId) return
+ const key = `${machineId}:${agentId}`
+ recapCache.set(key, [entry, ...(recapCache.get(key) ?? [])].slice(0, 5))
+ }),
+ getMachineRecaps: vi.fn(async (machineId: string, agentId: string, n: number) =>
+ (recapCache.get(`${machineId}:${agentId}`) ?? []).slice(0, n)),
+}))
+vi.mock('./machineCredential.js', () => ({ decryptMachineCredential: (v: string) => v.replace('enc:', '') }))
+vi.mock('./billingState.js', () => ({ machineBillingAllowsDataPlane: () => true }))
+vi.mock('../utils/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }))
+
+const { dispatch, forgetMachineMode, machineOnline } = await import('./providerLink.js')
+
+// ── A minimal but genuine provider ───────────────────────────────────────────────────────────────
+
+interface ServerBehaviour {
+ streaming: boolean
+ /** Emitted in order; `null` cuts the stream with NO terminal frame — a protocol violation. */
+ script: Array<Record<string, unknown> | null>
+ rejectCredential: boolean
+ /** This fake has recaps to hand back; false means it answers with an empty list. */
+ declareRecap: boolean
+ /**
+ * The provider manages its agents in its own product and declines to mutate them.
+ *
+ * There is nothing to declare in advance, so this is the ONLY way a client can learn that — by
+ * calling and reading the reason. That makes the message load-bearing, not decoration.
+ */
+ refuseMutations: string | null
+ /** What `agent.recap` hands back — ONE recap, or nothing. */
+ recapEntry: Record<string, unknown> | null
+ /** Unused: history is required of every provider. Kept so scenarios read unchanged. */
+ declareHistory: boolean
+ /** What `agent.history` answers. */
+ historyResult: Record<string, unknown>
+ /** Unused: with one transcript per agent there is no per-turn tag to drop. */
+ untaggedTasks: boolean
+ /** Unused: a session cannot be mis-attributed when it IS the agent. */
+ strayTask: boolean
+ /** Holds the stream open before the terminal frame, so a turn can outlive a heartbeat interval. */
+ holdMs: number
+}
+
+const behaviour: ServerBehaviour = {
+ streaming: true, script: [], rejectCredential: false, declareRecap: false, recapEntry: null,
+ refuseMutations: null,
+ declareHistory: false, historyResult: { agentId: 'alpha', events: [] }, untaggedTasks: false,
+ strayTask: false, holdMs: 0,
+}
+/** The params the last turn was sent with — proves the agent selector goes out. */
+let lastTurnMessage: Record<string, unknown> | undefined
+/** The params `agent.history` was last called with — proves paging is forwarded. */
+let lastHistoryParams: Record<string, unknown> | undefined
+/** How many times the recap was PULLED — a recap pushed on the stream must make that zero. */
+let recapCalls = 0
+/** The credential this fake was handed, so the header convention itself is under test. */
+let lastAuthHeader: string | undefined
+let server: Server
+let baseUrl = ''
+
+/**
+ * The agent list is AUTHENTICATED, which is exactly why it is a method and not a public document —
+ * two credentials may legitimately see two different lists.
+ */
+const AGENTS = () => [
+ { id: 'alpha', name: 'Alpha', description: 'first' },
+ { id: 'beta', name: 'Beta' },
+]
+
+const json = (res: ServerResponse, status: number, body: unknown): void => {
+ const payload = JSON.stringify(body)
+ res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) })
+ res.end(payload)
+}
+
+beforeAll(async () => {
+ server = createServer((req, res) => {
+ lastAuthHeader = req.headers.authorization
+ if (behaviour.rejectCredential) return json(res, 401, { jsonrpc: '2.0', id: 1, error: { code: 'unauthenticated', message: 'nope' } })
+
+ let body = ''
+ req.on('data', (c) => { body += c })
+ req.on('end', () => {
+ const parsed = JSON.parse(body || '{}') as { method?: string; params?: Record<string, unknown> }
+ const method = parsed.method
+ if (method === 'agent.list') {
+ return json(res, 200, { jsonrpc: '2.0', id: 1, result: { agents: AGENTS() } })
+ }
+ if (method === 'agent.history') {
+ lastHistoryParams = parsed.params
+ return json(res, 200, { jsonrpc: '2.0', id: 1, result: behaviour.historyResult })
+ }
+ if (method === 'turn.cancel') {
+ return json(res, 200, { jsonrpc: '2.0', id: 1, result: { cancelled: true } })
+ }
+ if (method === 'agent.recap') {
+ recapCalls += 1
+ // ALWAYS answered. A provider that does not summarise answers with NO `recap` — there is no
+ // capability to declare and nothing to refuse, so `declareRecap` now only decides whether this
+ // fake HAS anything to give back.
+ const entry = behaviour.declareRecap ? behaviour.recapEntry : null
+ return json(res, 200, { jsonrpc: '2.0', id: 1, result: { agentId: 'alpha', ...(entry ?? {}) } })
+ }
+ if (method === 'agent.create' || method === 'agent.rename' || method === 'agent.delete') {
+ if (behaviour.refuseMutations) {
+ // `invalid_request`, NOT `unsupported`: the difference is that this one carries a sentence
+ // the product can put in front of the user.
+ return json(res, 200, { jsonrpc: '2.0', id: 1, error: { code: 'invalid_request', message: behaviour.refuseMutations } })
+ }
+ if (method === 'agent.delete') return json(res, 200, { jsonrpc: '2.0', id: 1, result: { deleted: true } })
+ const params = (parsed.params ?? {}) as { agentId?: string; name?: string; description?: string }
+ const id = method === 'agent.create' ? String(params.name ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-') : String(params.agentId ?? '')
+ return json(res, 200, {
+ jsonrpc: '2.0', id: 1,
+ result: { id, name: params.name, ...(params.description ? { description: params.description } : {}) },
+ })
+ }
+ if (method !== 'agent.send') return json(res, 200, { jsonrpc: '2.0', id: 1, error: { code: 'unsupported', message: 'no' } })
+ lastTurnMessage = parsed.params as Record<string, unknown> | undefined
+
+ res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' })
+ const script = [...behaviour.script]
+ const drain = (): void => {
+ while (script.length) {
+ const event = script.shift()
+ if (event === null) { res.destroy(); return }
+ // Hold the stream open just before the terminal event, so a turn can outlive a heartbeat.
+ if (behaviour.holdMs && script.length === 0) {
+ setTimeout(() => { res.write(`event: message\ndata: ${JSON.stringify(event)}\n\n`); res.end() }, behaviour.holdMs)
+ return
+ }
+ res.write(`event: message\ndata: ${JSON.stringify(event)}\n\n`)
+ }
+ res.end()
+ }
+ drain()
+ })
+ })
+ await new Promise<void>((r) => server.listen(0, '127.0.0.1', r))
+ const addr = server.address()
+ baseUrl = `http://127.0.0.1:${typeof addr === 'object' && addr ? addr.port : 0}`
+})
+
+afterAll(() => new Promise<void>((r) => server.close(() => r())))
+
+beforeEach(() => {
+ published.length = 0
+ recapCache.clear()
+ behaviour.streaming = true
+ behaviour.rejectCredential = false
+ behaviour.script = []
+ behaviour.declareRecap = false
+ behaviour.recapEntry = null
+ behaviour.refuseMutations = null
+ behaviour.declareHistory = false
+ behaviour.historyResult = { agentId: 'alpha', events: [] }
+ lastHistoryParams = undefined
+ lastTurnMessage = undefined
+ behaviour.untaggedTasks = false
+ behaviour.strayTask = false
+ recapCalls = 0
+ behaviour.holdMs = 0
+ binding.current = {
+ machineId: 'h1',
+ userId: 'u1',
+ authMode: 'provider',
+ deletedAt: null,
+ providerUrl: baseUrl,
+ providerCredentialEncrypted: 'enc:secret',
+ createdAt: new Date('2026-08-04T00:00:00Z'),
+ }
+ forgetMachineMode('h1')
+})
+
+/** Turn lifecycle, as first-class events. */
+const started = (): Record<string, unknown> => ({ kind: 'turn_started', turnId: 'task-1', agentId: 'alpha' })
+const completed = (): Record<string, unknown> => ({ kind: 'turn_completed' })
+const cancelled = (): Record<string, unknown> => ({ kind: 'turn_cancelled' })
+const failed = (message: string): Record<string, unknown> =>
+ ({ kind: 'turn_failed', error: { code: 'internal', message } })
+
+/** One event, flat — no `Part`, no metadata namespace. */
+const part = (kind: string, text: string, fields: Record<string, unknown> = {}): Record<string, unknown> =>
+ ({ kind, ...(text ? { text } : {}), ...fields })
+
+const types = (): string[] => published.map((p) => p.frame.type ?? '')
+
+describe('a full turn over a real socket', () => {
+ it('streams a Claude-shaped turn through to client frames', async () => {
+ behaviour.script = [
+ started(),
+ part('thinking_delta', 'weighing it up'),
+ part('tool_start', '', { toolId: 'c7', tool: 'Read' }),
+ part('tool_end', 'ok', { toolId: 'c7', tool: 'Read' }),
+ part('text_delta', 'Here is the answer.'),
+ completed(),
+ ]
+
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'what is in note.txt?' } } })
+
+ // The whole contract in one list: the turn opens, immediately says it is alive, streams, closes,
+ // then settles a recap. `turn_heartbeat` sits right behind `turn_started` on purpose — waiting a
+ // full interval would leave the device blank for the first 5s of every turn.
+ // `commander_event` is the DEVICE's half, interleaved with the web's. It appears here and not
+ // before because the provider is addressed by agent now: with no agentId in the payload we fall
+ // back to the machine's sole/first agent, so the device gets its tile instead of nothing.
+ expect(types().filter((t) => t !== 'commander_event')).toEqual([
+ 'session_created', 'turn_started', 'turn_heartbeat',
+ 'thinking_delta', 'tool_start', 'tool_end', 'text_delta',
+ 'turn_ended', 'turn_summary_pending', 'turn_summary',
+ ])
+ const text = published.find((p) => p.frame.type === 'text_delta')!.frame.payload!.content
+ expect(text).toBe('Here is the answer.')
+ })
+
+ it('announces the session and tags EVERY frame with it', async () => {
+ // The web keys its whole turn lifecycle on `dbSessionId`. Without it the user's own message is
+ // never revealed and the send spinner never clears — the input reads "sending…" forever even
+ // though every event arrived. Found by using the real UI, not by any unit test.
+ behaviour.script = [
+ started(),
+ part('text_delta', 'hi'),
+ completed(),
+ ]
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hello' } } })
+
+ const created = published.find((p) => p.frame.type === 'session_created')
+ expect(created, 'a new chat must announce its session').toBeTruthy()
+ const sessionId = created!.frame.payload!.sessionId as string
+ expect(sessionId).toBeTruthy()
+
+ for (const p of published) {
+ if (p.frame.type === 'session_created') continue
+ expect(
+ (p.frame as { dbSessionId?: string }).dbSessionId,
+ `${p.frame.type} is untagged — the web cannot bind it to a session`,
+ ).toBe(sessionId)
+ }
+ })
+
+ it('reuses the session the client supplied when it names a real agent', async () => {
+ // `sessions_list` hands out `id: agentId`, so this is what the web sends back — and re-announcing
+ // a session it already knows would make its spinner migrate twice.
+ behaviour.script = [started(), completed()]
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi', sessionId: 'beta' } } })
+ expect(published.some((p) => p.frame.type === 'session_created')).toBe(false)
+ expect((published.at(-1)!.frame as { dbSessionId?: string }).dbSessionId).toBe('beta')
+ })
+
+ it('opens with turn_started and always closes with turn_ended', async () => {
+ behaviour.script = [started(), completed()]
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi' } } })
+ // session_created leads for a brand-new chat; the turn itself still brackets the events.
+ expect(types().filter((t) => t !== 'session_created')[0]).toBe('turn_started')
+ // `turn_ended` closes the TURN. The recap settles after it — deliberately, since the turn is
+ // over by then and the web must not be held on a spinner while a summary is fetched.
+ const closed = types().indexOf('turn_ended')
+ expect(closed).toBeGreaterThan(-1)
+ expect(types().slice(closed + 1).filter((t) => t !== 'commander_event')
+ .every((t) => t.startsWith('turn_summary'))).toBe(true)
+ })
+
+ it('closes the turn even when the provider cuts the stream with no terminal state', async () => {
+ // The one-terminal rule broken on their side. The client must not be left with a spinner forever.
+ behaviour.script = [started(), part('text_delta', 'half a'), null]
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi' } } })
+ expect(types()).toContain('error')
+ expect(types().filter((t) => t !== 'commander_event').at(-1)).toBe('turn_ended')
+ })
+
+ it('marks an aborted turn as aborted, not merely finished', async () => {
+ behaviour.script = [started(), cancelled()]
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi' } } })
+ // `reason` is required on the client's turn_ended union; this path used to omit it, which only
+ // typechecked because the frame is opaque at the transport layer.
+ expect(published.filter((p) => p.frame.type !== 'commander_event').at(-1)!.frame)
+ .toMatchObject({ type: 'turn_ended', payload: { reason: 'interrupt', aborted: true } })
+ })
+
+ it('emits exactly ONE error for a failed turn, not two', async () => {
+ // Running it for real produced two: the transport failure, and then "ended the stream without
+ // finishing" on top — which is redundant and wrong, since there was never a stream.
+ binding.current = { ...binding.current!, providerUrl: 'http://127.0.0.1:1' }
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi' } } })
+ expect(types().filter((t) => t === 'error')).toHaveLength(1)
+ expect(types().at(-1)).toBe('turn_ended')
+ })
+
+ it('never leaks the host and port we dialled into the UI', async () => {
+ // A raw ECONNREFUSED carries our infrastructure's view of the world. The owner gets a sentence;
+ // the address stays in the logs.
+ binding.current = { ...binding.current!, providerUrl: 'http://127.0.0.1:1' }
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi' } } })
+ const message = String(published.find((p) => p.frame.type === 'error')?.frame.payload?.message)
+ expect(message).not.toMatch(/127\.0\.0\.1|:1\b|ECONNREFUSED/)
+ expect(message).toMatch(/could not reach/i)
+ })
+
+ it('reports a rejected credential in words the owner can act on', async () => {
+ behaviour.rejectCredential = true
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi' } } })
+ const error = published.find((p) => p.frame.type === 'error')
+ expect(String(error?.frame.payload?.message)).toMatch(/re-enter/i)
+ })
+})
+
+// ── Liveness and recap ───────────────────────────────────────────────────────────────────────────
+
+/** The device-facing cards for one agent, in order. The web and the device speak different frames. */
+const cards = (agentId = 'alpha'): Array<Record<string, unknown>> =>
+ published
+ .filter((p) => p.frame.type === 'commander_event' && (p.frame as { agentId?: string }).agentId === agentId)
+ .map((p) => p.frame.payload as Record<string, unknown>)
+
+const turn = (payload: Record<string, unknown>): Promise<void> =>
+ dispatch('h1', { connId: '', frame: { type: 'message', payload } })
+
+describe('a running turn says it is still running', () => {
+ it('beats for BOTH clients, and keeps beating past the watchdogs', async () => {
+ // THE bug this feature fixes. A provider turn used to emit turn_started and then nothing until it
+ // finished, so the web's 10s watchdog killed the indicator and the device's 25s BUSY_TIMEOUT
+ // cleared the tile — mid-turn, on every turn longer than a few seconds.
+ //
+ // Deliberately a slow test: the beat is 5s, so nothing shorter than that can prove the interval
+ // actually fires, and an immediate-beat-only assertion would have passed against the broken code.
+ behaviour.script = [started(), completed()]
+ behaviour.holdMs = 5_200
+
+ await turn({ text: 'take your time', agentId: 'alpha' })
+
+ const beats = types().filter((t) => t === 'turn_heartbeat')
+ expect(beats.length, 'the web indicator dies without these').toBeGreaterThanOrEqual(2)
+ const processing = cards().filter((c) => c.kind === 'processing' && !c.text)
+ expect(processing.length, 'the device tile clears without these').toBeGreaterThanOrEqual(2)
+ }, 20_000)
+
+ it('stops beating once the turn is over — no leaked interval', async () => {
+ behaviour.script = [started(), completed()]
+ await turn({ text: 'hi', agentId: 'alpha' })
+ const settled = types().filter((t) => t === 'turn_heartbeat').length
+ await new Promise((r) => setTimeout(r, 5_500))
+ expect(types().filter((t) => t === 'turn_heartbeat')).toHaveLength(settled)
+ }, 20_000)
+})
+
+describe('the recap', () => {
+ const script = (answer: string): void => {
+ behaviour.script = [
+ started(),
+ part('text_delta', answer),
+ completed(),
+ ]
+ }
+
+ it('prefers the provider’s own when it has one', async () => {
+ behaviour.declareRecap = true
+ behaviour.recapEntry = { recap: 'Flagged Acme overspend at 118% of pacing', text: 'The weekly query returned 7 rows.' }
+ script('Acme is at 118% of pacing this week.')
+
+ await turn({ text: 'how is acme pacing?', agentId: 'alpha' })
+
+ const summary = cards().find((c) => c.kind === 'summary')!
+ expect(summary.recap).toBe('Flagged Acme overspend at 118% of pacing')
+ expect(summary.text).toBe('The weekly query returned 7 rows.')
+ })
+
+ it('derives one from the turn’s own output when the provider declares nothing', async () => {
+ // Most providers summarise nothing and answer with an empty list. An empty tile for all of them is worse
+ // than an honest excerpt of what the agent actually said.
+ script('Acme is at 118% of pacing. I also rebuilt the weekly alert query and scheduled it.')
+
+ await turn({ text: 'how is acme pacing?', agentId: 'alpha' })
+
+ const summary = cards().find((c) => c.kind === 'summary')!
+ expect(summary.recap, 'the headline is the opening sentence, nothing appended').toBe('Acme is at 118% of pacing.')
+ expect(summary.text).toBe('Acme is at 118% of pacing. I also rebuilt the weekly alert query and scheduled it.')
+ })
+
+ it('clears the busy tile BEFORE painting the card', async () => {
+ // Get this backwards and the card is immediately wiped by the clear. The node path emits
+ // done-then-summary for exactly this reason.
+ script('All done.')
+ await turn({ text: 'hi', agentId: 'alpha' })
+ const kinds = cards().map((c) => c.kind)
+ expect(kinds.indexOf('done')).toBeLessThan(kinds.indexOf('summary'))
+ })
+
+ it('holds the device busy while the recap is being fetched', async () => {
+ script('All done.')
+ await turn({ text: 'hi', agentId: 'alpha' })
+ expect(cards().some((c) => c.kind === 'processing' && c.text === 'Summarizing…')).toBe(true)
+ expect(types()).toContain('turn_summary_pending')
+ })
+
+ it('gives a FAILED turn no recap at all', async () => {
+ // Summarising a failure produces a tile that reads like an accomplishment.
+ behaviour.script = [started(), failed('boom')]
+ await turn({ text: 'hi', agentId: 'alpha' })
+ expect(cards().some((c) => c.kind === 'summary')).toBe(false)
+ expect(types()).not.toContain('turn_summary')
+ expect(cards().at(-1)!.kind, 'the tile must still be released').toBe('done')
+ })
+
+ it('says nothing rather than inventing a tile for a silent turn', async () => {
+ behaviour.script = [started(), completed()]
+ await turn({ text: 'hi', agentId: 'alpha' })
+ expect(cards().some((c) => c.kind === 'summary')).toBe(false)
+ const pending = published.filter((p) => p.frame.type === 'turn_summary_pending')
+ expect(pending.at(-1)!.frame.payload, 'the web row must close, not hang').toMatchObject({ done: true })
+ })
+
+ it('ignores a pulled recap that belongs to a DIFFERENT turn', async () => {
+ // The bug this closes: `agent.recap` is scoped to an agent and takes no turn id, so the newest
+ // entry a provider holds the instant a turn ends is very often the PREVIOUS turn's — and it was
+ // being shown as this turn's summary. An entry that names another turn is now no answer.
+ behaviour.declareRecap = true
+ behaviour.recapEntry = { recap: 'The previous turn’s headline', text: 'Stale body.', turnId: 't-other' }
+ script('This turn said something else entirely.')
+
+ await turn({ text: 'hi', agentId: 'alpha' })
+
+ const summary = cards().find((c) => c.kind === 'summary')!
+ expect(summary.recap).toBe('This turn said something else entirely.')
+ })
+})
+
+describe('the recap, pushed on the turn’s own stream', () => {
+ const withRecap = (answer: string, recapParts: Array<Record<string, unknown>>): void => {
+ behaviour.script = [
+ started(),
+ part('text_delta', answer),
+ part('recap_start', ''),
+ ...recapParts,
+ completed(),
+ ]
+ }
+
+ it('uses the pushed recap and never asks for one', async () => {
+ behaviour.declareRecap = true
+ behaviour.recapEntry = { recap: 'A stale headline from another turn', text: 'Stale.' }
+ withRecap('Acme is at 118% of pacing.', [
+ part('recap_end', 'The weekly query returned 7 rows.', { recap: 'Flagged Acme overspend at 118% of pacing' }),
+ ])
+
+ await turn({ text: 'how is acme pacing?', agentId: 'alpha' })
+
+ const summary = cards().find((c) => c.kind === 'summary')!
+ expect(summary.recap).toBe('Flagged Acme overspend at 118% of pacing')
+ expect(summary.text).toBe('The weekly query returned 7 rows.')
+ // The stream wins outright: asking again could only reintroduce the wrong-turn guess.
+ expect(recapCalls, 'a pushed recap must make the pull unnecessary').toBe(0)
+ })
+
+ it('never leaks the recap_* frames to a client that cannot read them', async () => {
+ withRecap('All done.', [part('recap_end', 'Body.', { recap: 'Did the thing' })])
+ await turn({ text: 'hi', agentId: 'alpha' })
+ expect(types()).not.toContain('recap_start')
+ expect(types()).not.toContain('recap_end')
+ })
+
+ it('opens the "Summarizing…" indicator when the wait STARTS, not after it', async () => {
+ // The whole reason the phase is bracketed: summarising is seconds of real time during which the
+ // turn has stopped speaking. Announced at the end it explains nothing, and the web shows a stall.
+ withRecap('All done.', [part('recap_end', 'Body.', { recap: 'Did the thing' })])
+ await turn({ text: 'hi', agentId: 'alpha' })
+
+ const order = types()
+ const pendingAt = order.indexOf('turn_summary_pending')
+ expect(pendingAt).toBeGreaterThan(-1)
+ expect(pendingAt, 'the indicator must precede the end of the turn').toBeLessThan(order.indexOf('turn_ended'))
+ expect(cards().some((c) => c.kind === 'processing' && c.text === 'Summarizing…')).toBe(true)
+ // Still done-before-summary: reversed, the clear wipes the card the moment it is painted.
+ const kinds = cards().map((c) => c.kind)
+ expect(kinds.indexOf('done')).toBeLessThan(kinds.indexOf('summary'))
+ })
+
+ it('closes the indicator when the provider ends the phase with nothing to show', async () => {
+ // `recap_end` without a headline means "no recap". A start with no end would spin forever.
+ behaviour.script = [
+ started(),
+ part('recap_start', ''),
+ part('recap_end', ''),
+ completed(),
+ ]
+ await turn({ text: 'hi', agentId: 'alpha' })
+
+ expect(cards().some((c) => c.kind === 'summary')).toBe(false)
+ const pending = published.filter((p) => p.frame.type === 'turn_summary_pending')
+ expect(pending.at(-1)!.frame.payload, 'the web row must close, not hang').toMatchObject({ done: true })
+ expect(cards().at(-1)!.kind, 'the tile must still be released').toBe('done')
+ })
+
+ it('falls back to the turn’s own words when the summariser came back empty', async () => {
+ behaviour.script = [
+ started(),
+ part('text_delta', 'Acme is at 118% of pacing. More detail here.'),
+ part('recap_start', ''),
+ part('recap_end', ''),
+ completed(),
+ ]
+ await turn({ text: 'hi', agentId: 'alpha' })
+ // The same excerpt any other provider gets — an excerpt of what was actually said, never invented.
+ expect(cards().find((c) => c.kind === 'summary')!.recap).toBe('Acme is at 118% of pacing.')
+ })
+})
+
+describe('agent_recent — the device restoring its tiles', () => {
+ it('answers live from the provider when it has one', async () => {
+ behaviour.declareRecap = true
+ behaviour.recapEntry = { recap: 'Shipped the pacing alert', text: 'Full body.' }
+ await dispatch('h1', { connId: '', frame: { type: 'agent_recent', payload: { requestId: 'r9', agentId: 'alpha', n: 1 } } })
+
+ const reply = published.at(-1)!.frame
+ expect(reply.type).toBe('agent_recent_result')
+ expect(reply.payload).toMatchObject({ requestId: 'r9', agentId: 'alpha' })
+ expect(reply.payload!.events).toEqual([{ kind: 'summary', recap: 'Shipped the pacing alert', text: 'Full body.' }])
+ })
+
+ it('falls back to the last turn’s recap when the provider summarises nothing', async () => {
+ // Without this a provider machine's tiles are blank after every device reboot — which is what
+ // `agent_recent` answering UNSUPPORTED used to guarantee.
+ behaviour.script = [
+ started(),
+ part('text_delta', 'Rebuilt the weekly report.'),
+ completed(),
+ ]
+ await turn({ text: 'rebuild it', agentId: 'alpha' })
+ published.length = 0
+
+ await dispatch('h1', { connId: '', frame: { type: 'agent_recent', payload: { requestId: 'r10', agentId: 'alpha', n: 2 } } })
+ expect(published.at(-1)!.frame.payload!.events).toEqual([
+ { kind: 'summary', recap: 'Rebuilt the weekly report.', text: 'Rebuilt the weekly report.' },
+ ])
+ })
+
+ it('returns an empty list before anything has been summarised', async () => {
+ await dispatch('h1', { connId: '', frame: { type: 'agent_recent', payload: { requestId: 'r11', agentId: 'beta' } } })
+ // Correct, not a failure: the device then shows nothing rather than stale text.
+ expect(published.at(-1)!.frame.payload!.events).toEqual([])
+ })
+
+ it('refuses without an agent instead of guessing one', async () => {
+ await dispatch('h1', { connId: '', frame: { type: 'agent_recent', payload: { requestId: 'r12' } } })
+ expect(published.at(-1)!.frame.payload).toMatchObject({ error: 'MISSING_AGENT_ID' })
+ })
+})
+
+describe('the RPCs the web needs to render anything', () => {
+ it('agents_list returns the provider skills as projects', async () => {
+ // This is what fills the project tabs. An empty answer here is the difference between a usable
+ // machine and a blank screen.
+ await dispatch('h1', { connId: '', frame: { type: 'agents_list', payload: { requestId: 'r1' } } })
+ const reply = published.at(-1)!.frame
+ expect(reply.type).toBe('agents_list_result')
+ expect(reply.payload!.requestId).toBe('r1')
+ const agents = reply.payload!.agents as Array<{ id: string; name: string; userId: string }>
+ expect(agents.map((a) => a.id)).toEqual(['alpha', 'beta'])
+ // Fields the protocol does not carry are synthesised by us, never invented by the provider.
+ expect(agents[0]!.userId).toBe('u1')
+ })
+
+ it('sessions_list synthesises ONE session per agent', async () => {
+ // A provider has no sessions to fold, so there is nothing to ask it and nothing to get wrong.
+ // The whole "a chat answered twice appeared twice" bug class is structurally impossible now.
+ await dispatch('h1', { connId: '', frame: { type: 'sessions_list', payload: { requestId: 'r2', agentId: 'alpha' } } })
+ const sessions = published.at(-1)!.frame.payload!.sessions as Array<Record<string, unknown>>
+ expect(sessions).toHaveLength(1)
+ expect(sessions[0]).toMatchObject({ id: 'alpha', title: 'Alpha' })
+ // Omitted, not zero — the client hides a count it did not receive, and fabricating one is banned.
+ expect('messageCount' in sessions[0]!).toBe(false)
+ })
+
+ it('tells the provider WHICH agent the turn belongs to', async () => {
+ // The provider is ADDRESSED by agent now, so this is a required parameter rather than a metadata
+ // hint a provider was free to ignore.
+ behaviour.script = [started(), completed()]
+ await turn({ text: 'hi', agentId: 'beta' })
+ expect(lastTurnMessage).toMatchObject({ agentId: 'beta' })
+ })
+
+ it('mints the turnId itself, so an instant cancel has something to name', async () => {
+ // A provider-minted id would arrive only with the first event — too late for a user who has
+ // already pressed stop.
+ behaviour.script = [started(), completed()]
+ await turn({ text: 'hi', agentId: 'alpha' })
+ expect(typeof lastTurnMessage?.turnId).toBe('string')
+ expect(lastTurnMessage!.turnId as string).toBeTruthy()
+ })
+
+ it('sessions_list shows only the SELECTED agent', async () => {
+ await dispatch('h1', { connId: '', frame: { type: 'sessions_list', payload: { requestId: 'r2', agentId: 'beta' } } })
+ const sessions = published.at(-1)!.frame.payload!.sessions as Array<Record<string, unknown>>
+ expect(sessions.map((s) => s.id)).toEqual(['beta'])
+ })
+
+ it('sessions_list answers empty for an agent this machine does not have', async () => {
+ // Better an empty list than somebody else's row: the id came from the client, not from us.
+ await dispatch('h1', { connId: '', frame: { type: 'sessions_list', payload: { requestId: 'r2', agentId: 'ghost' } } })
+ expect(published.at(-1)!.frame.payload!.sessions).toEqual([])
+ })
+
+ it('sessions_list unscoped lists every agent', async () => {
+ await dispatch('h1', { connId: '', frame: { type: 'sessions_list', payload: { requestId: 'r2' } } })
+ const sessions = published.at(-1)!.frame.payload!.sessions as Array<Record<string, unknown>>
+ expect(sessions.map((s) => s.id)).toEqual(['alpha', 'beta'])
+ })
+
+ it('session_get reads the agent’s whole transcript', async () => {
+ behaviour.historyResult = {
+ agentId: 'alpha',
+ events: [part('user_message', 'how is acme pacing?'), part('text_delta', 'Acme is at 118%.')],
+ }
+ // `sessionId` is the id `sessions_list` handed out — which IS the agentId.
+ await dispatch('h1', { connId: '', frame: { type: 'session_get', payload: { requestId: 'r3', sessionId: 'alpha' } } })
+ const reply = published.at(-1)!.frame.payload!
+ expect(reply).toMatchObject({ id: 'alpha', title: 'Alpha' })
+ expect(reply.events).toHaveLength(2)
+ expect(lastHistoryParams).toMatchObject({ agentId: 'alpha' })
+ })
+
+ it('session_get hands back EVENTS, the only transcript shape the web can render', async () => {
+ // The bug this closes: raw provider entries were passed through as `messages`, and the client's
+ // fallback for that field parses Claude's JSONL shape (`message.content[]`). Every entry failed
+ // `!msg.message?.content` and was dropped, so the chat rendered empty however much came back.
+ behaviour.historyResult = {
+ agentId: 'alpha',
+ events: [
+ part('user_message', 'run it'),
+ part('tool_start', '', { toolId: 'c7', tool: 'Bash' }),
+ part('text_delta', 'Done.'),
+ ],
+ }
+ await dispatch('h1', { connId: '', frame: { type: 'session_get', payload: { requestId: 'r3', sessionId: 'alpha' } } })
+ const reply = published.at(-1)!.frame.payload!
+ const events = reply.events as Array<{ type: string; payload: Record<string, unknown> }>
+
+ // Exactly the vocabulary `eventsToMessages` switches on, with the payload field names it reads.
+ expect(events.map((e) => e.type)).toEqual(['user_message', 'tool_start', 'text_delta'])
+ expect(events[0]!.payload).toMatchObject({ content: 'run it' })
+ expect(events[1]!.payload).toMatchObject({ id: 'c7', tool: 'Bash' })
+ // The dead branch must stay dead: anything left here would be dropped silently by the client.
+ expect(reply.messages).toEqual([])
+ })
+
+ it('the SAME event objects render live and in history', async () => {
+ // One shape, one mapper. This is what makes "what you saw live" and "what you see after a
+ // refresh" incapable of disagreeing — and what let `historyToEvents` stop being a translation.
+ const stream = [part('text_delta', 'Done.'), part('tool_start', '', { toolId: 'c7', tool: 'Bash' })]
+ behaviour.script = [started(), ...stream.map((e) => e as Record<string, unknown>), completed()]
+ await turn({ text: 'hi', agentId: 'alpha' })
+ const live = published.filter((p) => p.frame.type === 'text_delta' || p.frame.type === 'tool_start')
+ .map((p) => ({ type: p.frame.type, payload: p.frame.payload }))
+
+ published.length = 0
+ behaviour.historyResult = { agentId: 'alpha', events: stream }
+ await dispatch('h1', { connId: '', frame: { type: 'session_get', payload: { requestId: 'r3', sessionId: 'alpha' } } })
+ const replayed = published.at(-1)!.frame.payload!.events
+
+ expect(replayed).toEqual(live)
+ })
+
+ it('session_get forwards the window and hands the cursor back', async () => {
+ behaviour.historyResult = { agentId: 'alpha', events: [part('text_delta', 'x')], nextBefore: 'u4' }
+ await dispatch('h1', {
+ connId: '',
+ frame: { type: 'session_get', payload: { requestId: 'r3', sessionId: 'alpha', limit: 60, before: 'u9' } },
+ })
+ // The names going OUT are the node path's, deliberately: a provider machine must be
+ // indistinguishable from a node one by the time the frame reaches the web. `nextBefore` is the
+ // provider's word and never reaches a client.
+ expect(lastHistoryParams).toMatchObject({ agentId: 'alpha', limit: 60, before: 'u9' })
+ expect(published.at(-1)!.frame.payload).toMatchObject({ hasMore: true, oldestCursor: 'u4' })
+ })
+
+ it('session_get clamps an absurd window rather than passing it on', async () => {
+ await dispatch('h1', {
+ connId: '',
+ frame: { type: 'session_get', payload: { requestId: 'r3', sessionId: 'alpha', limit: 10_000 } },
+ })
+ expect(lastHistoryParams).toMatchObject({ limit: 500 })
+ })
+
+ it('session_get reports the end of the transcript as hasMore false', async () => {
+ behaviour.historyResult = { agentId: 'alpha', events: [] }
+ await dispatch('h1', {
+ connId: '',
+ frame: { type: 'session_get', payload: { requestId: 'r3', sessionId: 'alpha', limit: 60, before: 'gone' } },
+ })
+ expect(published.at(-1)!.frame.payload).toMatchObject({ hasMore: false, oldestCursor: null })
+ })
+
+ it('session_get omits the paging fields entirely when no window was asked for', async () => {
+ behaviour.historyResult = { agentId: 'alpha', events: [part('text_delta', 'x')] }
+ await dispatch('h1', { connId: '', frame: { type: 'session_get', payload: { requestId: 'r3', sessionId: 'alpha' } } })
+ const reply = published.at(-1)!.frame.payload!
+ // Absent, not `false` — their absence is how the client tells a complete answer from a windowed one.
+ expect('hasMore' in reply).toBe(false)
+ expect('oldestCursor' in reply).toBe(false)
+ expect('limit' in (lastHistoryParams ?? {})).toBe(false)
+ })
+
+ it('answers an out-of-scope RPC AT ONCE instead of leaving a spinner', async () => {
+ // The web times out at 20s. Silence is the worst possible answer.
+ await dispatch('h1', { connId: '', frame: { type: 'models_list', payload: { requestId: 'r4' } } })
+ expect(published.at(-1)!.frame).toMatchObject({ type: 'models_list_result', payload: { error: 'UNSUPPORTED', requestId: 'r4' } })
+ })
+
+ it('cancel reaches the provider', async () => {
+ await expect(dispatch('h1', { connId: '', frame: { type: 'cancel', payload: { taskId: 't1' } } })).resolves.toBeUndefined()
+ })
+
+ it('sends the credential as `Authorization: Bearer`, the one header there is', async () => {
+ // Fixed by convention rather than by declaration. A provider cannot choose a different one, so
+ // this is the only place the whole scheme is pinned.
+ await dispatch('h1', { connId: '', frame: { type: 'agents_list', payload: { requestId: 'auth-1' } } })
+ expect(lastAuthHeader).toBe('Bearer secret')
+ })
+})
+
+describe('creating, renaming and deleting agents', () => {
+ it('forwards all three to the provider', async () => {
+ await dispatch('h1', { connId: '', frame: { type: 'agent_create', payload: { requestId: 'c1', name: 'New Skill' } } })
+ expect(published.at(-1)!.frame).toMatchObject({
+ type: 'agent_create_result',
+ payload: { requestId: 'c1', agent: { id: 'new-skill', name: 'New Skill' } },
+ })
+
+ await dispatch('h1', { connId: '', frame: { type: 'agent_update', payload: { requestId: 'u1', agentId: 'alpha', name: 'Renamed' } } })
+ expect(published.at(-1)!.frame).toMatchObject({
+ type: 'agent_update_result',
+ payload: { requestId: 'u1', agent: { id: 'alpha', name: 'Renamed' } },
+ })
+
+ await dispatch('h1', { connId: '', frame: { type: 'agent_delete', payload: { requestId: 'd1', agentId: 'beta' } } })
+ expect(published.at(-1)!.frame).toMatchObject({ type: 'agent_delete_result', payload: { requestId: 'd1' } })
+ })
+
+ it('hands the provider’s OWN refusal to the user, word for word', async () => {
+ // The mitigation for having nothing declared in advance. The web cannot hide a control it never
+ // asked about, so the answer has to explain itself — and a generic "could not reach the provider"
+ // wrapped around this sentence would turn an explanation into a lie.
+ behaviour.refuseMutations = 'Agents are managed in Example Co — create one there and it appears here'
+ await dispatch('h1', { connId: '', frame: { type: 'agent_create', payload: { requestId: 'c2', name: 'Nope' } } })
+ expect(published.at(-1)!.frame.payload).toEqual({
+ requestId: 'c2',
+ error: 'Agents are managed in Example Co — create one there and it appears here',
+ })
+ })
+
+ it('refuses a model switch rather than half-applying it', async () => {
+ // `agent_update` carries either a rename or a model choice. Model selection belongs to whatever
+ // runs the agent, which for a provider machine is not us.
+ await dispatch('h1', { connId: '', frame: { type: 'agent_update', payload: { requestId: 'u2', agentId: 'alpha', selectedModel: 'opus' } } })
+ expect(published.at(-1)!.frame.payload).toMatchObject({ requestId: 'u2', error: 'UNSUPPORTED' })
+ })
+})
+
+describe('always online', () => {
+ it('reports a provider machine online even with no presence key', async () => {
+ // THE bug that made the whole feature look broken: presence is the source of truth for every
+ // other mode, but a provider never writes one, so reading presence alone said `false` — and the
+ // web then refuses to fetch anything at all (`AgentTabs`: if (nodeOnline === false) return).
+ // The machine rendered dead and never loaded its projects.
+ expect(await machineOnline('h1', false)).toBe(true)
+ })
+
+ it('does not claim any OTHER mode is online when presence says otherwise', async () => {
+ binding.current = { ...binding.current!, authMode: 'remote' }
+ forgetMachineMode('h1')
+ expect(await machineOnline('h1', false)).toBe(false)
+ })
+
+ it('still reports online when presence does say so', async () => {
+ binding.current = { ...binding.current!, authMode: 'managed' }
+ forgetMachineMode('h1')
+ expect(await machineOnline('h1', true)).toBe(true)
+ })
+})
+
+describe('refusals', () => {
+ it('says so when the machine is not a provider machine', async () => {
+ binding.current = { ...binding.current!, authMode: 'remote' }
+ forgetMachineMode('h1')
+ await dispatch('h1', { connId: '', frame: { type: 'agents_list', payload: { requestId: 'r5' } } })
+ expect(published.at(-1)!.frame.payload!.error).toBeTruthy()
+ })
+
+ it('says so when the provider details are missing', async () => {
+ binding.current = { ...binding.current!, providerUrl: null }
+ await dispatch('h1', { connId: '', frame: { type: 'message', payload: { text: 'hi' } } })
+ expect(types()).toContain('error')
+ expect(types().filter((t) => t !== 'commander_event').at(-1)).toBe('turn_ended')
+ })
+})
diff --git a/backend/src/lib/providerLink.realProvider.e2e.test.ts b/backend/src/lib/providerLink.realProvider.e2e.test.ts
new file mode 100644
index 000000000..54fdaa880
--- /dev/null
+++ b/backend/src/lib/providerLink.realProvider.e2e.test.ts
@@ -0,0 +1,235 @@
+// The WHOLE chain, across both repositories:
+//
+// client frame → providerLink → HTTP/SSE → the real reference-provider → frames back
+//
+// `providerLink.e2e.test.ts` drives a provider this repository defines in-test, which proves our
+// client against OUR reading of the protocol. That is exactly the test that cannot notice when the
+// two readings drift. This one talks to the published implementation instead.
+//
+// GATED ON `PROVIDER_E2E=1`, and deliberately not skipped by default when the checkout is missing —
+// see the resolution block. A test that quietly does nothing reports green forever.
+import { spawn, type ChildProcess } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const ENABLED = process.env.PROVIDER_E2E === '1'
+const HERE = dirname(fileURLToPath(import.meta.url))
+/** The published contract lives in a sibling checkout. */
+const PROVIDER_DIR = resolve(HERE, '../../../../../autonomous-harness/provider/reference-provider')
+
+const published = vi.hoisted(() => [] as Array<{ machineId: string; frame: { type?: string; payload?: Record<string, unknown> } }>)
+const binding = vi.hoisted(() => ({ current: null as Record<string, unknown> | null }))
+
+vi.mock('../config/env.js', () => ({ env: { PROVIDER_ALLOW_INSECURE_URLS: true } }))
+vi.mock('./prisma.js', () => ({ prisma: { machine: { findUnique: vi.fn(async () => binding.current) } } }))
+vi.mock('./bus.js', () => ({
+ publishUp: vi.fn(async (machineId: string, msg: { frame: unknown }) => {
+ published.push({ machineId, frame: msg.frame as { type?: string } })
+ return 1
+ }),
+ pushMachineRecap: vi.fn(async () => {}),
+ getMachineRecaps: vi.fn(async () => []),
+}))
+vi.mock('./machineCredential.js', () => ({ decryptMachineCredential: (v: string) => v.replace('enc:', '') }))
+vi.mock('./billingState.js', () => ({ machineBillingAllowsDataPlane: () => true }))
+vi.mock('../utils/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }))
+
+const { dispatch, forgetMachineMode } = await import('./providerLink.js')
+
+let child: ChildProcess | undefined
+let baseUrl = ''
+
+/**
+ * Boot the published reference provider and wait for it to announce its URL.
+ *
+ * Its own stdout is the handshake: parsing it is more reliable than guessing a free port and racing
+ * the listen.
+ */
+async function bootPublishedProvider(): Promise<string> {
+ return new Promise<string>((ok, reject) => {
+ const proc = spawn('npx', ['tsx', 'src/server.ts'], {
+ cwd: PROVIDER_DIR,
+ // A small per-step pause, not zero. A turn that completes inside one tick cannot be cancelled
+ // mid-flight, and the cancel path is the one thing here that only exists for a RUNNING turn.
+ env: { ...process.env, PORT: '0', STEP_DELAY_MS: '15' },
+ stdio: ['ignore', 'pipe', 'pipe'],
+ })
+ child = proc
+ const timer = setTimeout(() => reject(new Error('reference-provider did not start within 60s')), 60_000)
+ let stderr = ''
+ proc.stdout?.on('data', (chunk: Buffer) => {
+ const match = /http:\/\/127\.0\.0\.1:\d+/.exec(chunk.toString())
+ if (match) { clearTimeout(timer); ok(match[0]) }
+ })
+ proc.stderr?.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+ proc.on('exit', (code) => { clearTimeout(timer); reject(new Error(`reference-provider exited ${code}: ${stderr.slice(0, 500)}`)) })
+ })
+}
+
+const describeIf = ENABLED ? describe : describe.skip
+
+if (!ENABLED) {
+ console.log('[provider-e2e] SKIPPED — set PROVIDER_E2E=1 to run the cross-repository chain against the published provider.')
+}
+
+describeIf('the real chain, against the published reference-provider', () => {
+ beforeAll(async () => {
+ // Set but unresolvable is a FAILURE, not a skip. Once CI opts in, a missing checkout has to be
+ // loud — otherwise the tier silently stops existing and nobody notices for months.
+ if (!existsSync(PROVIDER_DIR)) {
+ throw new Error(
+ `PROVIDER_E2E=1 but the published provider is not at ${PROVIDER_DIR}. `
+ + 'Check out autonomous-ai/autonomous-harness beside this repository, or unset PROVIDER_E2E.',
+ )
+ }
+ baseUrl = await bootPublishedProvider()
+ }, 90_000)
+
+ afterAll(() => { child?.kill('SIGKILL') })
+
+ beforeEach(() => {
+ published.length = 0
+ binding.current = {
+ machineId: 'h1',
+ userId: 'u1',
+ authMode: 'provider',
+ deletedAt: null,
+ providerUrl: baseUrl,
+ providerCredentialEncrypted: 'enc:e2e',
+ createdAt: new Date('2026-08-06T00:00:00Z'),
+ }
+ forgetMachineMode('h1')
+ })
+
+ const types = (): string[] => published.map((p) => p.frame.type ?? '')
+ const send = (text: string, payload: Record<string, unknown> = {}): Promise<void> =>
+ dispatch('h1', { connId: '', frame: { type: 'message', payload: { text, agentId: 'alpha', ...payload } } })
+
+ it('runs a full turn end to end and hands the clients their own frames', async () => {
+ await send('hello')
+
+ // The vocabulary the WEB speaks. If the published provider and our client ever disagree about the
+ // protocol, this is where it shows — as a missing frame rather than as a subtle mismatch.
+ const web = types().filter((t) => t !== 'commander_event')
+ expect(web).toContain('turn_started')
+ expect(web).toContain('text_delta')
+ expect(web).toContain('turn_ended')
+ // …and the DEVICE's half, which speaks a different vocabulary off the same stream.
+ expect(types()).toContain('commander_event')
+ }, 60_000)
+
+ it('carries tool events through with their ids intact', async () => {
+ await send('hello')
+ const start = published.find((p) => p.frame.type === 'tool_start')
+ const end = published.find((p) => p.frame.type === 'tool_end')
+ expect(start?.frame.payload?.id).toBeTruthy()
+ expect(end?.frame.payload?.id).toBe(start?.frame.payload?.id)
+ }, 60_000)
+
+ it('closes a turn the provider cut without a terminal frame', async () => {
+ // The `die` scenario breaks the one-terminal rule on purpose. The client must not be left on a spinner.
+ await send('die')
+ expect(types()).toContain('error')
+ expect(types().filter((t) => t !== 'commander_event').at(-1)).toBe('turn_ended')
+ }, 60_000)
+
+ it('reports a failed turn as an error, not as a silent finish', async () => {
+ await send('fail')
+ expect(types()).toContain('error')
+ const ended = published.filter((p) => p.frame.type === 'turn_ended').at(-1)
+ expect(ended?.frame.payload).toMatchObject({ reason: 'error' })
+ }, 60_000)
+
+ it('rebuilds a transcript the client can render', async () => {
+ await send('hello')
+ published.length = 0
+ await dispatch('h1', { connId: '', frame: { type: 'session_get', payload: { requestId: 'r1', sessionId: 'alpha' } } })
+ const reply = published.at(-1)!.frame.payload!
+ expect(reply.id).toBe('alpha')
+ expect((reply.events as unknown[]).length).toBeGreaterThan(0)
+ // The dead branch stays dead: anything here is silently dropped by the web.
+ expect(reply.messages).toEqual([])
+ }, 60_000)
+
+ it('lists the provider’s agents as the client’s agents', async () => {
+ await dispatch('h1', { connId: '', frame: { type: 'agents_list', payload: { requestId: 'r2' } } })
+ const agents = published.at(-1)!.frame.payload!.agents as Array<{ id: string }>
+ expect(agents.map((a) => a.id)).toEqual(['alpha', 'beta'])
+ }, 60_000)
+
+ it('reports a rejected credential in words the owner can act on', async () => {
+ binding.current = { ...binding.current!, providerCredentialEncrypted: 'enc:bad-key' }
+ await send('hello')
+ const error = published.find((p) => p.frame.type === 'error')
+ expect(String(error?.frame.payload?.message)).toMatch(/credential/i)
+ }, 60_000)
+
+ it('accepts every kind the published provider can emit', async () => {
+ // THE cross-repository check. Both repositories keep their own copy of the vocabulary — ours in
+ // `ALLOWED_KINDS`, theirs in the scenarios — and nothing but this notices when they drift. The
+ // `everything` scenario emits all of them in one turn, so a kind we silently drop shows up here
+ // as a missing client frame rather than as an empty row in production.
+ await send('everything')
+ const web = types().filter((t) => t !== 'commander_event')
+ for (const expected of ['turn_started', 'thinking_delta', 'tool_start', 'tool_end', 'text_delta', 'turn_ended']) {
+ expect(web, expected).toContain(expected)
+ }
+ // Nothing was dropped as unrenderable: an unmapped kind produces no frame at all.
+ expect(published.some((p) => p.frame.type === 'error')).toBe(false)
+ }, 60_000)
+
+ it('stops a turn the user interrupted while it was still speaking', async () => {
+ // The Stop button, end to end and across the repository boundary: our `cancel` frame becomes
+ // `turn.cancel` on the published provider, whose stream terminates with `turn_cancelled`, which
+ // has to come back to the client as an INTERRUPT — not as an error, and not as a normal finish.
+ const turn = send('everything')
+ // Wait for real output rather than sleeping: a fixed delay is how this test becomes flaky on a
+ // loaded machine, and cancelling before the turn starts exercises a different path entirely.
+ for (let i = 0; i < 200 && !published.some((p) => p.frame.type === 'text_delta'); i++) {
+ await new Promise((r) => setTimeout(r, 10))
+ }
+ expect(published.some((p) => p.frame.type === 'text_delta'), 'turn never started speaking').toBe(true)
+
+ await dispatch('h1', { connId: '', frame: { type: 'cancel', payload: {} } })
+ await turn
+
+ const ended = published.filter((p) => p.frame.type === 'turn_ended').at(-1)
+ expect(ended?.frame.payload).toMatchObject({ reason: 'interrupt', aborted: true })
+ // An interrupted turn is not a broken one. An error toast here tells the user something went
+ // wrong when in fact they are the thing that went wrong.
+ expect(published.some((p) => p.frame.type === 'error')).toBe(false)
+ }, 60_000)
+
+ it('restores the device’s tiles from the recap the provider pushed', async () => {
+ // `agent_recent` is the device's cold-start path: it has no stream to read, so this is the only
+ // way yesterday's work reaches the screen.
+ await send('recap')
+ published.length = 0
+ await dispatch('h1', { connId: '', frame: { type: 'agent_recent', payload: { requestId: 'r9', agentId: 'alpha', n: 2 } } })
+ const events = published.at(-1)!.frame.payload!.events as Array<{ recap?: string }>
+ expect(events.length).toBeGreaterThan(0)
+ expect(events[0]!.recap).toBeTruthy()
+ }, 60_000)
+
+ it('creates, renames and deletes an agent on the published provider', async () => {
+ await dispatch('h1', { connId: '', frame: { type: 'agent_create', payload: { requestId: 'c1', name: 'Cross Repo' } } })
+ const created = published.at(-1)!.frame.payload!.agent as { id: string; name: string }
+ expect(created).toMatchObject({ name: 'Cross Repo' })
+
+ await dispatch('h1', { connId: '', frame: { type: 'agent_update', payload: { requestId: 'u1', agentId: created.id, name: 'Renamed' } } })
+ expect((published.at(-1)!.frame.payload!.agent as { name: string }).name).toBe('Renamed')
+
+ // The freshly created agent is addressable, which is the trap a snapshotted id list falls into.
+ published.length = 0
+ await send('hello', { agentId: created.id })
+ expect(types()).toContain('turn_ended')
+ expect(published.some((p) => p.frame.type === 'error')).toBe(false)
+
+ await dispatch('h1', { connId: '', frame: { type: 'agent_delete', payload: { requestId: 'd1', agentId: created.id } } })
+ await dispatch('h1', { connId: '', frame: { type: 'agents_list', payload: { requestId: 'r3' } } })
+ const agents = published.at(-1)!.frame.payload!.agents as Array<{ id: string }>
+ expect(agents.map((a) => a.id)).not.toContain(created.id)
+ }, 60_000)
+})
diff --git a/backend/src/lib/providerLink.ts b/backend/src/lib/providerLink.ts
new file mode 100644
index 000000000..0d02a9496
--- /dev/null
+++ b/backend/src/lib/providerLink.ts
@@ -0,0 +1,694 @@
+/**
+ * The `provider` machine backer — the node role played over HTTP + SSE.
+ *
+ * Unlike every other backer there is **no persistent connection**. The protocol is request-per-turn,
+ * so this module holds no socket, needs no owning worker, and does not appear in the
+ * `down:{machineId}` subscription at all: the worker that receives a client frame calls the provider
+ * itself (see `routeDown`). That is what removed the owner-election and multiplexing problems from
+ * the WebSocket design this replaced.
+ *
+ * A provider machine is therefore **always online** — see `isAlwaysOnline`. Failure surfaces on the
+ * turn that hit it, which is more precise than a status dot: "credential rejected" and "provider
+ * unreachable" are different sentences, and a dot cannot say either.
+ *
+ * **A PROVIDER HAS NO SESSIONS — ONLY AGENTS.** One agent is one continuous transcript, and the
+ * protocol keys everything on `agentId`. The web, however, keys its ENTIRE turn lifecycle on
+ * `dbSessionId`: without one the user's own message is never revealed, the `__pending__` spinner
+ * never migrates onto a real session, and the input sits on "sending…" forever while every event
+ * arrives correctly. So the session is SYNTHESISED here — `sessionId === agentId`, one per agent —
+ * and the clients keep the exact shape they already speak. Nothing above this file can tell the
+ * difference; that is the point.
+ */
+import type { Machine } from '@prisma/client'
+import { randomUUID } from 'node:crypto'
+import { getMachineRecaps, publishUp, pushMachineRecap } from './bus.js'
+import { decryptMachineCredential } from './machineCredential.js'
+import { prisma } from './prisma.js'
+import { logger } from '../utils/logger.js'
+import { machineBillingAllowsDataPlane } from './billingState.js'
+import type { DownBusMsg, Frame } from './tunnel.js'
+import {
+ ProviderError,
+ cancelTurn,
+ createAgent,
+ deleteAgent,
+ listAgents,
+ renameAgent,
+ sendMessage,
+ type ProviderAgent,
+ type ProviderCallOptions,
+} from './provider/client.js'
+import { MAX_CONSECUTIVE_INVALID, MAX_FIELD_CHARS, mapEvent, turnOutcome, type TurnEnd } from './provider/events.js'
+import { clampHistoryLimit, fetchTranscript } from './provider/history.js'
+import {
+ BODY_MAX_CHARS,
+ deriveRecap,
+ fetchProviderRecap,
+ toRecapEvent,
+ type RecapEvent,
+} from './provider/recap.js'
+
+/** True for a machine whose backer has no liveness to measure — see the module header. */
+export function isAlwaysOnline(binding: { authMode?: string | null }): boolean {
+ return binding.authMode === 'provider'
+}
+
+/**
+ * Node liveness for any machine, by id.
+ *
+ * A provider machine is ALWAYS ONLINE, and this is where that has to be asserted rather than
+ * assumed. The presence key is the source of truth for every other mode, but a provider never writes
+ * one — there is no socket to keep alive — so reading presence alone reports `false`, and the web
+ * then refuses to load anything at all (`AgentTabs`: `if (nodeOnline === false) return`). The machine
+ * renders dead and never fetches its projects. Asserting it here is the whole fix.
+ */
+export async function machineOnline(machineId: string, presenceOnline: boolean): Promise<boolean> {
+ if (presenceOnline) return true
+ return (await authModeOf(machineId)) === 'provider'
+}
+
+interface LinkContext {
+ binding: Machine
+ call: ProviderCallOptions
+ agents: ProviderAgent[]
+}
+
+/**
+ * The agent list, cached per machine; it changes rarely and would otherwise be fetched on every turn.
+ *
+ * There is nothing else to cache: a provider publishes no discovery document, so the list IS what the
+ * client knows about it. It is an authenticated call, scoped to the tenant this machine's credential
+ * selects, which is why two machines pointed at the same endpoint can legitimately see different
+ * agents.
+ */
+interface CachedProfile { agents: ProviderAgent[]; at: number }
+const profileCache = new Map<string, CachedProfile>()
+const PROFILE_TTL_MS = 5 * 60_000
+
+async function context(machineId: string): Promise<LinkContext | null> {
+ const binding = await prisma.machine.findUnique({ where: { machineId } })
+ if (!binding || binding.deletedAt || binding.authMode !== 'provider') return null
+ if (!binding.providerUrl || !binding.providerCredentialEncrypted) return null
+ // Billing is the ONLY enforcement point for this mode: there is no socket to close when a
+ // subscription lapses, so the check has to happen before every dial.
+ if (!machineBillingAllowsDataPlane(binding)) return null
+
+ let credential: string
+ try {
+ credential = decryptMachineCredential(binding.providerCredentialEncrypted)
+ } catch {
+ logger.warn('provider credential could not be decrypted', { machineId })
+ return null
+ }
+
+ const call: ProviderCallOptions = { url: binding.providerUrl, credential }
+
+ const cached = profileCache.get(machineId)
+ if (cached && Date.now() - cached.at < PROFILE_TTL_MS) return { binding, agents: cached.agents, call }
+
+ // The first and only call needed to know anything about this provider. It is authenticated, so it
+ // also tells a wrong credential from an unreachable host without a separate probe.
+ const { agents } = await listAgents(call)
+ const list = (agents ?? []).filter((a): a is ProviderAgent & { id: string } => typeof a?.id === 'string' && !!a.id)
+ profileCache.set(machineId, { agents: list, at: Date.now() })
+ return { binding, agents: list, call }
+}
+
+export function invalidateProfile(machineId: string): void {
+ profileCache.delete(machineId)
+}
+
+/**
+ * Frames a single turn may push at the clients.
+ *
+ * The other backers are our own code, so nothing capped them. A provider is not: a misbehaving or
+ * hostile endpoint can emit SSE events as fast as the socket allows, and every one of them fans out
+ * through Redis to every web tab and to the device screen. This bounds the damage to one turn
+ * instead of the instance.
+ *
+ * Sized for a long, tool-heavy turn with token-level deltas — a real turn against the example
+ * provider produces a few hundred.
+ */
+export const MAX_FRAMES_PER_TURN = 20_000
+
+/**
+ * Publish a frame upward, TAGGED WITH THE SESSION.
+ *
+ * `dbSessionId` is not decoration: the web keys its entire turn lifecycle on it. Without it `sid` is
+ * undefined, the user's own message is never revealed, the `__pending__` send-spinner is never
+ * migrated onto a real session — and the input sits on "sending…" forever even though every event
+ * arrived correctly. That is exactly what happened the first time this ran against the real UI.
+ *
+ * For a provider the session IS the agent (see the module header), so `agentId` is what we tag with.
+ */
+/**
+ * Provider agent → the shape the client expects.
+ *
+ * `userId`, `status` and the timestamps are SYNTHESISED from the binding: the protocol does not carry
+ * them, and inventing them on the provider side would be fabrication. `engine` is omitted — a
+ * provider machine runs none of the CLIs, and the client treats absent as provider-backed.
+ */
+function toAgent(
+ agent: { id?: string; name?: string; description?: string },
+ ctx: LinkContext,
+): Record<string, unknown> {
+ return {
+ id: agent.id ?? '',
+ name: agent.name ?? agent.id ?? 'Agent',
+ description: agent.description ?? '',
+ userId: ctx.binding.userId,
+ status: 'active',
+ createdAt: ctx.binding.createdAt.toISOString(),
+ updatedAt: ctx.binding.createdAt.toISOString(),
+ }
+}
+
+const up = (machineId: string, frame: Frame, sessionId?: string): void => {
+ void publishUp(machineId, {
+ webEligible: true,
+ commanderEligible: true,
+ frame: sessionId ? { ...frame, dbSessionId: sessionId } : frame,
+ })
+}
+
+/**
+ * A device-facing card, the way the node emits them (`emitCommanderEvent`).
+ *
+ * The device speaks a DIFFERENT vocabulary from the web: it never sees `turn_heartbeat` or
+ * `turn_summary`, only `commander_event` kinds, and it keys every tile by the top-level `agentId`.
+ * So the turn lifecycle has to be said twice, once in each language — which is exactly what
+ * `machine-node/api/src/routes/websocket.ts` does for a node-backed machine.
+ *
+ * Without an agentId there is no tile to address, so the frame is dropped rather than broadcast at
+ * whatever the device happens to be showing. The web still gets its half.
+ */
+const commander = (machineId: string, agentId: string, sessionId: string, payload: Record<string, unknown>): void => {
+ if (!agentId) return
+ up(machineId, { type: 'commander_event', agentId, payload }, sessionId)
+}
+
+/** Reply to an RPC the way a node would: `<type>_result` carrying the caller's requestId. */
+const reply = (machineId: string, type: string, requestId: unknown, payload: Record<string, unknown>): void => {
+ up(machineId, { type: `${type}_result`, payload: { ...payload, ...(requestId ? { requestId } : {}) } })
+}
+
+/**
+ * Handle one client frame for a provider machine.
+ *
+ * Never throws: a failure here is reported to the client as a failed turn or an RPC error, because
+ * the alternative is a spinner that never resolves.
+ */
+export async function dispatch(machineId: string, msg: DownBusMsg): Promise<void> {
+ const frame = msg.frame as { type?: string; payload?: Record<string, unknown> }
+ const type = frame?.type
+ if (!type) return
+ const payload = frame.payload ?? {}
+ const requestId = payload.requestId
+
+ let ctx: LinkContext | null
+ try {
+ ctx = await context(machineId)
+ } catch (err) {
+ failTurn(machineId, type, requestId, describe(err))
+ return
+ }
+ if (!ctx) {
+ failTurn(machineId, type, requestId, 'This machine is not available')
+ return
+ }
+
+ try {
+ switch (type) {
+ case 'message':
+ await runTurn(machineId, ctx, payload)
+ return
+ case 'cancel': {
+ const turnId = typeof payload.taskId === 'string' ? payload.taskId : activeTurns.get(machineId)
+ if (turnId) await cancelTurn(ctx.call, turnId)
+ return
+ }
+ case 'agents_list':
+ reply(machineId, type, requestId, { agents: ctx.agents.map((a) => toAgent(a, ctx!)) })
+ return
+ case 'sessions_list': {
+ // ONE session per agent, synthesised. The provider has no session concept to ask about, so
+ // there is nothing to fetch here and nothing to fold — which is also why the old bug class
+ // ("a chat answered twice appeared twice") cannot come back.
+ //
+ // The client's list is always scoped to ONE agent (the node path refuses the call without an
+ // id), so an unknown agent gets an empty list rather than somebody else's row.
+ const wanted = typeof payload.agentId === 'string' ? payload.agentId : ''
+ const scoped = wanted ? ctx.agents.filter((a) => a.id === wanted) : ctx.agents
+ const now = new Date().toISOString()
+ reply(machineId, type, requestId, {
+ sessions: scoped.map((a) => ({
+ id: a.id ?? '',
+ title: a.name ?? a.id ?? 'Untitled',
+ // The provider publishes no clock for a transcript that has no beginning. "Now" keeps the
+ // field the client sorts on populated; with one row per agent nothing depends on the order.
+ timestamp: now,
+ lastActivity: now,
+ // messageCount and participants are deliberately omitted: fabricating statistics is
+ // forbidden, and the client hides a count it did not receive.
+ })),
+ })
+ return
+ }
+ case 'session_get': {
+ // The session IS the agent. `sessions_list` hands out `id: agentId`, so what comes back here
+ // is an agentId and is used directly as one.
+ const agentId = typeof payload.sessionId === 'string' ? payload.sessionId : ''
+ const limit = clampHistoryLimit(payload.limit)
+ const before = typeof payload.before === 'string' && payload.before ? payload.before : undefined
+ const agent = ctx.agents.find((a) => a.id === agentId)
+
+ const transcript = await fetchTranscript(ctx.call, agentId, { limit, before })
+
+ reply(machineId, type, requestId, {
+ id: agentId,
+ title: agent?.name ?? agent?.id ?? 'Untitled',
+ timestamp: new Date().toISOString(),
+ events: transcript.events,
+ // Deliberately NOT the raw provider events. The client's `messages` fallback parses Claude's
+ // JSONL shape (`message.content[]`), which a provider never produces, so handing it provider
+ // events means every message is silently dropped and the chat renders empty. Everything
+ // renderable is in `events` above; leaving this empty keeps that dead branch from running.
+ messages: [],
+ ...(typeof transcript.hasMore === 'boolean'
+ ? { hasMore: transcript.hasMore, oldestCursor: transcript.oldestCursor ?? null }
+ : {}),
+ })
+ return
+ }
+ case 'agent_recent': {
+ // The device's tile restore. Asked of the provider every time (a PULL by design, never
+ // replayed from cache); a provider that summarises nothing answers with an empty list, and we
+ // fall back to what the last turns left behind.
+ const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
+ if (!agentId) {
+ reply(machineId, type, requestId, { error: 'MISSING_AGENT_ID' })
+ return
+ }
+ // `payload.n` is deliberately ignored: the device sends `n: 1` and the provider method has no
+ // `n` to forward it to. The REPLY still carries an `events` array — the device iterates it and
+ // `deviceWs.trimRecentEvents` expects a list, so the frame is unchanged and no firmware moves.
+ const live = await fetchProviderRecap(ctx.call, agentId)
+ const events = live ? [live] : await getMachineRecaps<RecapEvent>(machineId, agentId, 1)
+ // An empty array is the CORRECT answer before anything has been summarised — the device then
+ // shows nothing, rather than resurrecting stale text.
+ reply(machineId, type, requestId, { agentId, events })
+ return
+ }
+ // The three mutations are forwarded WITHOUT a local gate. A provider whose agents are managed in
+ // its own product answers `invalid_request` with a message, and `failTurn` below hands that
+ // message to the user — "agents are managed in Example Co" tells them what to do, where a
+ // silently-hidden control tells them nothing.
+ case 'agent_create': {
+ // Validated, not cast. `String({})` puts "[object Object]" on somebody else's wire, and a
+ // non-string `description` forwarded as-is makes US the one sending a malformed request.
+ const description = typeof payload.description === 'string' ? payload.description : undefined
+ const created = await createAgent(ctx.call, name(payload.name), description)
+ invalidateProfile(machineId) // the provider's agent list just changed
+ reply(machineId, type, requestId, { agent: toAgent(created, ctx) })
+ return
+ }
+ case 'agent_delete': {
+ await deleteAgent(ctx.call, String(payload.agentId ?? ''))
+ invalidateProfile(machineId)
+ reply(machineId, type, requestId, { message: 'deleted' })
+ return
+ }
+ case 'agent_update': {
+ // Only the rename half. Model selection is out of scope for this mode entirely, so a payload
+ // carrying `selectedModel` and no name is refused rather than half-applied.
+ if (typeof payload.name !== 'string') {
+ if (requestId) reply(machineId, type, requestId, { error: 'UNSUPPORTED' })
+ return
+ }
+ const renamed = await renameAgent(ctx.call, String(payload.agentId ?? ''), name(payload.name))
+ invalidateProfile(machineId)
+ reply(machineId, type, requestId, { agent: toAgent(renamed, ctx) })
+ return
+ }
+ default:
+ // Everything else — model switching, logins, session writes — is out of scope for this mode
+ // (spec §9). Answer at once: an unanswered RPC is a 20-second spinner in the web.
+ if (requestId) reply(machineId, type, requestId, { error: 'UNSUPPORTED' })
+ return
+ }
+ } catch (err) {
+ failTurn(machineId, type, requestId, describe(err))
+ }
+}
+
+// ── The routing seam ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `authMode` per machine. Immutable once the binding is created (see the schema comment), so this
+ * can be cached for the process lifetime without a staleness problem — the only way it changes is a
+ * new machine, which is a new key.
+ */
+const modeCache = new Map<string, string>()
+
+async function authModeOf(machineId: string): Promise<string> {
+ const cached = modeCache.get(machineId)
+ if (cached) return cached
+ const row = await prisma.machine.findUnique({ where: { machineId }, select: { authMode: true } })
+ const mode = row?.authMode ?? 'self'
+ modeCache.set(machineId, mode)
+ return mode
+}
+
+export function forgetMachineMode(machineId: string): void {
+ modeCache.delete(machineId)
+ profileCache.delete(machineId)
+}
+
+/**
+ * Send a client frame toward whatever backs this machine.
+ *
+ * **The one branch.** A `provider` machine has no `down:{machineId}` consumer — there is no socket at
+ * the other end — so its frames are handled in-process by calling the provider over HTTP. Every other
+ * mode keeps the existing publish. Three call sites carry user traffic and route through here:
+ * `hub.ts` (client frames), `nodeRpc.ts` (RPCs) and `machineMessage.ts` (the device/voice path);
+ * node-only control frames deliberately do not.
+ */
+export const HANDLED_IN_PROCESS = Symbol('provider-handled')
+
+export async function routeDown(
+ machineId: string,
+ msg: DownBusMsg,
+ fallback: () => Promise<number>,
+): Promise<number | typeof HANDLED_IN_PROCESS> {
+ let mode: string
+ try {
+ mode = await authModeOf(machineId)
+ } catch {
+ return fallback()
+ }
+ if (mode !== 'provider') return fallback()
+
+ // Never let a provider failure reject into the caller: these call sites are fire-and-forget, and
+ // an unhandled rejection there would take down more than one machine's turn.
+ await dispatch(machineId, msg).catch((err) => {
+ logger.warn('provider dispatch failed', { machineId, error: describe(err) })
+ })
+ // NOT `0`. Callers read the publish count as "how many backends hold this machine's socket", and
+ // zero means offline. A provider machine has no socket and never will, so returning 0 here would
+ // flip the client to "unreachable" on every single message. This sentinel says "delivered, and the
+ // count does not apply" — the always-online property, expressed where it actually matters.
+ return HANDLED_IN_PROCESS
+}
+
+/** turnId of the turn currently running per machine, so a `cancel` without one still works. */
+const activeTurns = new Map<string, string>()
+
+/**
+ * How often a running turn says it is still running.
+ *
+ * The brain's own `TURN_HEARTBEAT_MS`. It has to stay under BOTH watchdogs, which were sized against
+ * it: the web gives up after 10s (`messagesSlice/eventHandlers.ts`) and the device clears its busy
+ * tile after 25s (`ui_screens.c` `BUSY_TIMEOUT_US`). At 5s each tolerates a dropped beat.
+ */
+const TURN_HEARTBEAT_MS = 5_000
+
+/** Enough of the turn's own output to excerpt a recap from, without holding a whole turn in memory. */
+const ASSISTANT_TEXT_BUDGET = BODY_MAX_CHARS * 4
+
+async function runTurn(machineId: string, ctx: LinkContext, payload: Record<string, unknown>): Promise<void> {
+ const text = typeof payload.text === 'string' ? payload.text : typeof payload.content === 'string' ? payload.content : ''
+ if (!text.trim()) return
+
+ // Which agent the turn belongs to. The device keys its tiles by it, the provider is addressed by
+ // it, and — since a provider has no sessions — it IS the session id the clients are given.
+ //
+ // The client's own `sessionId` is accepted as the agent when it names one we know, because that is
+ // exactly what `sessions_list` handed it. Falling back to the sole agent covers a single-agent
+ // provider whose client sent nothing to disambiguate.
+ const claimed = typeof payload.agentId === 'string' && payload.agentId ? payload.agentId : ''
+ const fromSession = typeof payload.sessionId === 'string' && payload.sessionId ? payload.sessionId : ''
+ const agentId = ctx.agents.some((a) => a.id === claimed) ? claimed
+ : ctx.agents.some((a) => a.id === fromSession) ? fromSession
+ : claimed || ctx.agents[0]?.id || ''
+ if (!agentId) {
+ up(machineId, { type: 'error', payload: { message: 'This machine has no agents to send to' } })
+ up(machineId, { type: 'turn_ended', payload: { reason: 'error' } })
+ return
+ }
+
+ // The session the CLIENTS see. One per agent — see the module header for why it cannot simply be
+ // omitted. The web cannot bind a turn to a session it has not been told about, and will not reveal
+ // the user's own message without one.
+ const sessionId = agentId
+ const isNewSession = fromSession !== sessionId
+
+ // Announce the session BEFORE the turn, so the web can migrate its '__pending__' spinner onto a
+ // real id — the same contract the node satisfies with `session_created`.
+ if (isNewSession) {
+ up(machineId, {
+ type: 'session_created',
+ payload: { sessionId, title: text.slice(0, 80), createdAt: new Date().toISOString() },
+ })
+ }
+
+ up(machineId, { type: 'turn_started', payload: { userMessage: text } }, sessionId)
+
+ // Say it in both languages at once: `turn_heartbeat` for the web, a `processing` card for the
+ // device. Immediately, then on the interval — otherwise the device shows nothing for the first 5s
+ // of every turn.
+ const beat = (): void => {
+ up(machineId, { type: 'turn_heartbeat', payload: {} }, sessionId)
+ commander(machineId, agentId, sessionId, { kind: 'processing' })
+ }
+ beat()
+ // UNCONDITIONAL, deliberately: it is not gated on the provider sending anything. A conformant
+ // provider may emit nothing at all until its final answer, so "no SSE event for 30s" is not
+ // evidence of a stall and must not be allowed to end a live turn. The 10-minute per-request budget
+ // in `provider/client.ts` stays the only backstop.
+ const heartbeat = setInterval(beat, TURN_HEARTBEAT_MS)
+
+ // OURS, minted before the request leaves — so a cancel in the first 200ms has something to name.
+ // A provider-minted id would arrive only with the first event, by which time the user has already
+ // pressed stop and there is nothing to send.
+ const turnId = `t-${randomUUID()}`
+ activeTurns.set(machineId, turnId)
+
+ let invalid = 0
+ let frames = 0
+ let end: TurnEnd | undefined
+ let reported = false
+ // The recap, when the provider pushes it on this turn's own stream.
+ // `handled`: either recap kind arrived, so the provider owns this phase and the pull must not run.
+ // `pending`: the "Summarizing…" indicator is up and something must eventually close it.
+ let recapHandled = false
+ let recapPending = false
+ let streamedRecap: RecapEvent | null = null
+ // The turn's own assistant output, kept only to excerpt a recap from when the provider declares no
+ // `agent.recap`. `done` carries the final result text and supersedes the deltas.
+ let deltas = ''
+ let finalResult = ''
+ const collect = (f: Frame): void => {
+ const body = (f.payload ?? {}) as { content?: unknown; result?: unknown }
+ if (f.type === 'text_delta' && typeof body.content === 'string' && deltas.length < ASSISTANT_TEXT_BUDGET) {
+ deltas += body.content
+ } else if (f.type === 'done' && typeof body.result === 'string') {
+ finalResult = body.result.slice(0, ASSISTANT_TEXT_BUDGET)
+ }
+ }
+ try {
+ const resume = typeof payload.resume === 'boolean' ? payload.resume : false
+ for await (const event of sendMessage(ctx.call, { agentId, turnId, text, ...(resume ? { resume } : {}) })) {
+ const mapped = mapEvent(event)
+ if (mapped.kind === 'invalid') {
+ // A provider that keeps sending shapes we do not recognise is disconnected rather than
+ // allowed to keep pushing at the UI indefinitely.
+ if (++invalid >= MAX_CONSECUTIVE_INVALID) {
+ logger.warn('provider stream dropped after repeated invalid events', { machineId, reason: mapped.reason })
+ break
+ }
+ continue
+ }
+ invalid = 0
+ if (mapped.kind === 'ignore') continue
+ for (const f of mapped.frames) {
+ if (++frames > MAX_FRAMES_PER_TURN) break
+ // The recap phase is CONSUMED here, never forwarded: clients speak `turn_summary_pending` and
+ // `commander_event`, not `recap_*`. Announcing the wait the moment it starts is the whole
+ // reason the provider brackets it — the summary takes seconds during which the turn has
+ // stopped speaking, and without this the UI shows a stall.
+ if (f.type === 'recap_start') {
+ recapHandled = true
+ if (!recapPending) {
+ recapPending = true
+ up(machineId, { type: 'turn_summary_pending', payload: { sessionId } }, sessionId)
+ commander(machineId, agentId, sessionId, { kind: 'processing', text: 'Summarizing…' })
+ }
+ continue
+ }
+ if (f.type === 'recap_end') {
+ recapHandled = true
+ streamedRecap = toRecapEvent(f.payload as { recap?: unknown; text?: unknown })
+ continue
+ }
+ collect(f)
+ up(machineId, f, sessionId)
+ }
+ if (frames > MAX_FRAMES_PER_TURN) {
+ logger.warn('provider exceeded the per-turn frame budget; turn cut short', { machineId, frames })
+ up(machineId, { type: 'error', payload: { message: 'The provider sent more output than a single turn allows' } }, sessionId)
+ break
+ }
+ if (mapped.kind === 'terminal') { end = mapped.end; break }
+ }
+ } catch (err) {
+ up(machineId, { type: 'error', payload: { message: describe(err) } }, sessionId)
+ reported = true
+ } finally {
+ clearInterval(heartbeat)
+ activeTurns.delete(machineId)
+ }
+
+ // A stream that ended without a terminal frame is a protocol violation on their side, and the turn
+ // must still be closed here or the client waits forever.
+ const outcome = end ? turnOutcome(end) : { aborted: false, failed: true }
+ // `input_required` is NOT a failure: the turn is paused for a human answer, which arrives as a
+ // resumed `agent.send`. The clients have no vocabulary for a paused turn, so it is surfaced the way
+ // the node surfaces a question — as the turn's final text — and the turn is closed normally.
+ if (end?.outcome === 'input_required' && end.prompt) {
+ up(machineId, { type: 'done', payload: { result: end.prompt } }, sessionId)
+ }
+ // A failed turn carries a REASON, and it has to reach the user. `turn_ended{reason:'error'}` only
+ // says that something went wrong; without this the provider's own explanation — "upstream refused
+ // the connection" — is parsed, stored on the terminal frame, and then dropped on the floor.
+ if (end?.outcome === 'failed' && end.message) {
+ up(machineId, { type: 'error', payload: { message: end.message } }, sessionId)
+ reported = true
+ }
+ // Only when the stream actually started and then stopped short. If the call itself failed we have
+ // already said why, and adding "ended the stream without finishing" on top is both redundant and
+ // wrong — there was never a stream to end.
+ if (!end && !reported) {
+ up(machineId, { type: 'error', payload: { message: 'The provider ended the turn without finishing it' } }, sessionId)
+ }
+ // `reason` is REQUIRED on the client's `turn_ended` (`web/src/lib/types/events.ts`); this path used
+ // to omit it entirely, which typechecked only because the frame is opaque at the transport layer.
+ const reason = outcome.aborted ? 'interrupt' : outcome.failed ? 'error' : 'result'
+ up(machineId, { type: 'turn_ended', payload: { reason, ...(outcome.aborted ? { aborted: true } : {}) } }, sessionId)
+
+ await settleRecap(machineId, ctx, agentId, sessionId, {
+ failed: outcome.aborted || outcome.failed,
+ assistantText: finalResult || deltas,
+ turnId,
+ }, { handled: recapHandled, pending: recapPending, recap: streamedRecap })
+}
+
+/**
+ * The recap phase, after the turn has closed.
+ *
+ * Ordering mirrors the node path exactly (`machine-node/api/src/routes/websocket.ts`): the device
+ * gets `done` BEFORE `summary`, so it clears the busy tile and then repaints it with the card. Get
+ * that backwards and the card is immediately wiped by the clear.
+ *
+ * A broken turn gets no recap — the same gate the brain applies (`if (!isErr …)` in `finalizeTurn`).
+ * Summarising a failure produces a tile that reads like an accomplishment.
+ */
+async function settleRecap(
+ machineId: string,
+ ctx: LinkContext,
+ agentId: string,
+ sessionId: string,
+ turn: { failed: boolean; assistantText: string; turnId?: string },
+ streamed: { handled: boolean; pending: boolean; recap: RecapEvent | null },
+): Promise<void> {
+ if (turn.failed) {
+ // A provider that opened the indicator and then failed still has to have it closed, or the web
+ // sits on "Preparing a recap" for a turn that is already over.
+ if (streamed.pending) {
+ up(machineId, { type: 'turn_summary_pending', payload: { sessionId, done: true } }, sessionId)
+ }
+ commander(machineId, agentId, sessionId, { kind: 'done' })
+ return
+ }
+
+ let event: RecapEvent | null = null
+ if (streamed.handled) {
+ // The provider summarised on the turn's own stream, and the wait was already shown as it
+ // happened. Nothing to ask for: this recap is unambiguously THIS turn's, which is exactly what
+ // the pull below cannot promise. A `recap_end` that carried no headline still falls through to
+ // the excerpt, the same gap-fill any other provider gets.
+ event = streamed.recap ?? deriveRecap(turn.assistantText)
+ } else {
+ // Tell both clients a recap is coming BEFORE fetching it: the web shows "Preparing a recap", and
+ // the `processing` card holds the device's busy tile open across the round trip. No repeating beat
+ // is needed the way the node needs one — the node is waiting on a model, this is one HTTP call
+ // inside a 15s budget, comfortably under the device's 25s timeout.
+ up(machineId, { type: 'turn_summary_pending', payload: { sessionId } }, sessionId)
+ commander(machineId, agentId, sessionId, { kind: 'processing', text: 'Summarizing…' })
+
+ try {
+ // The provider's own recap is authoritative when it has one; ours is only a gap-fill. Skipped
+ // without an agent to scope it to — `agent.recap` requires one, so asking anyway would just
+ // trade a working fallback for a logged invalid_request.
+ const live = agentId ? await fetchProviderRecap(ctx.call, agentId, { turnId: turn.turnId }) : null
+ event = live ?? deriveRecap(turn.assistantText)
+ } catch (err) {
+ // A recap is a nicety. Losing one must not retroactively fail a turn that succeeded, so this is
+ // logged and swallowed — and the fallback still runs, since the turn's own text is right here.
+ logger.warn('provider recap failed', { machineId, agentId, error: describe(err) })
+ event = deriveRecap(turn.assistantText)
+ }
+ }
+
+ if (!event) {
+ // `done: true` closes the web's "Preparing a recap" row without claiming one arrived.
+ up(machineId, { type: 'turn_summary_pending', payload: { sessionId, done: true } }, sessionId)
+ commander(machineId, agentId, sessionId, { kind: 'done' })
+ return
+ }
+
+ commander(machineId, agentId, sessionId, { kind: 'done' })
+ commander(machineId, agentId, sessionId, { kind: 'summary', text: event.text, recap: event.recap })
+ // The web reads only the flag off this frame, never the text — but the shape is the node's
+ // ("<recap>\n\n<body>"), so the two paths stay interchangeable.
+ up(machineId, { type: 'turn_summary', payload: { sessionId, summary: `${event.recap}\n\n${event.text}` } }, sessionId)
+
+ await pushMachineRecap(machineId, agentId, event)
+}
+
+function failTurn(machineId: string, type: string, requestId: unknown, message: string): void {
+ if (requestId) {
+ reply(machineId, type, requestId, { error: message })
+ return
+ }
+ if (type === 'message') {
+ up(machineId, { type: 'error', payload: { message } })
+ up(machineId, { type: 'turn_ended', payload: {} })
+ }
+}
+
+/** A client-supplied agent name, as a string or not at all — never `"[object Object]"`. */
+const name = (v: unknown): string => (typeof v === 'string' ? v : '')
+
+/** Turns an error into something worth showing the owner — the auth/transport split is the point. */
+export function describe(err: unknown): string {
+ if (err instanceof ProviderError) {
+ if (err.kind === 'unauthenticated') return 'The provider rejected the stored credential — re-enter it'
+ if (err.kind === 'not_streaming') return 'The provider did not stream its reply'
+ // A refusal is the provider's OWN sentence, and it goes through untouched. This is the whole
+ // mitigation for having nothing declared in advance: the web cannot hide a control it has not
+ // asked about, so the answer it gets has to explain itself ("agents are managed in Example Co").
+ // Prefixing "Could not reach the provider" onto that would turn an explanation into a lie.
+ // Capped: this is third-party text on its way to a toast, and `readBodyCapped` bounds the whole
+ // JSON-RPC body, not this one field within it.
+ if (err.kind === 'refused') return err.message.slice(0, MAX_FIELD_CHARS)
+ return `Could not reach the provider: ${err.message}`
+ }
+ // Raw socket errors carry the host and port we dialled. That is our infrastructure's view of the
+ // world, not the owner's — and it should not be echoed into their UI at all. Say what happened and
+ // leave the address in the logs.
+ const code = (err as NodeJS.ErrnoException | undefined)?.code
+ if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EHOSTUNREACH' || code === 'ETIMEDOUT' || code === 'ECONNRESET') {
+ return 'Could not reach the provider'
+ }
+ return err instanceof Error ? err.message : String(err)
+}
diff --git a/backend/src/lib/providerProbe.ts b/backend/src/lib/providerProbe.ts
new file mode 100644
index 000000000..c508bf2c0
--- /dev/null
+++ b/backend/src/lib/providerProbe.ts
@@ -0,0 +1,83 @@
+/**
+ * Prove a provider URL + credential before a machine is created.
+ *
+ * Without this step a wrong credential is indistinguishable from an outage — the machine is created,
+ * looks fine, and only fails when somebody eventually types a message. That is the worst failure mode
+ * in this design, and the whole reason the create flow blocks on a live check.
+ *
+ * ONE authenticated call does the whole job. `agent.list` proves the URL, the credential and that the
+ * endpoint speaks this protocol at once, and it returns exactly what the create screen wants to show
+ * next — so there is nothing to fetch beforehand.
+ *
+ * Four outcomes, four different sentences. They are different because each has a different fix:
+ * change the URL, wait, pick a different provider, or paste the right credential.
+ */
+import { ProviderError, listAgents, type ProviderAgent } from './provider/client.js'
+import { checkProviderUrl, ProviderUrlError } from './providerUrl.js'
+
+export type ProbeFailure =
+ | 'PROVIDER_URL_REFUSED'
+ | 'PROVIDER_UNREACHABLE'
+ | 'PROVIDER_NOT_STREAMING'
+ | 'PROVIDER_CREDENTIAL_REJECTED'
+
+export class ProviderProbeError extends Error {
+ constructor(message: string, readonly code: ProbeFailure) {
+ super(message)
+ this.name = 'ProviderProbeError'
+ }
+}
+
+export interface ProbeResult {
+ /** Normalised URL to store. */
+ url: string
+ /** Agent ids, so the UI can show what it just connected to. */
+ agents: Array<{ id: string; name: string; description?: string }>
+}
+
+export async function probeProvider(rawUrl: string, credential: string): Promise<ProbeResult> {
+ let url: string
+ try {
+ url = (await checkProviderUrl(rawUrl)).url
+ } catch (err) {
+ // The guard's own message names the actual problem (private address, bad scheme, no DNS), which
+ // is more useful than a generic "invalid URL".
+ throw new ProviderProbeError(err instanceof ProviderUrlError ? err.message : 'That is not a usable URL', 'PROVIDER_URL_REFUSED')
+ }
+
+ let agents: ProviderAgent[]
+ try {
+ agents = (await listAgents({ url, credential, timeoutMs: 10_000 })).agents ?? []
+ } catch (err) {
+ if (err instanceof ProviderError && err.kind === 'unauthenticated') {
+ throw new ProviderProbeError('The provider rejected that credential', 'PROVIDER_CREDENTIAL_REJECTED')
+ }
+ // `protocol` errors mean it answered, but not the way this protocol says to — most often because
+ // the URL points at something else entirely. That is a different fix from "wait for it to come
+ // back", so it keeps its own code.
+ if (err instanceof ProviderError && err.kind === 'protocol') {
+ throw new ProviderProbeError('That endpoint did not answer as a provider', 'PROVIDER_NOT_STREAMING')
+ }
+ // A refusal means it IS a provider and it said no — to listing agents, of all things. Its own
+ // sentence is the only thing here that tells the owner what to do about it.
+ if (err instanceof ProviderError && err.kind === 'refused') {
+ throw new ProviderProbeError(`The provider refused to list its agents: ${err.message}`, 'PROVIDER_NOT_STREAMING')
+ }
+ throw new ProviderProbeError(
+ `Could not reach that provider${err instanceof Error && err.message ? `: ${err.message}` : ''}`,
+ 'PROVIDER_UNREACHABLE',
+ )
+ }
+
+ const usable = agents.filter((a): a is ProviderAgent & { id: string } => typeof a?.id === 'string' && !!a.id)
+ // An empty list is a real failure, not an empty state: the machine would be created and then have
+ // nothing to talk to, which reads to the owner as a broken product rather than a bad endpoint.
+ if (!usable.length) {
+ throw new ProviderProbeError('That provider returned no agents to talk to', 'PROVIDER_NOT_STREAMING')
+ }
+
+ return {
+ url,
+ agents: usable.map((a) => ({ id: a.id, name: a.name ?? a.id, description: a.description })),
+ }
+}
diff --git a/backend/src/lib/providerUrl.ts b/backend/src/lib/providerUrl.ts
new file mode 100644
index 000000000..7c3190ab9
--- /dev/null
+++ b/backend/src/lib/providerUrl.ts
@@ -0,0 +1,299 @@
+/**
+ * SSRF guard for user-supplied provider endpoints.
+ *
+ * A `provider` machine is reached at a URL the OWNER typed. That is a deliberate product decision and
+ * it puts an attacker-controlled string in front of an outbound request from our infrastructure — the
+ * classic route to a cloud metadata endpoint or an internal service. This module is the mitigation,
+ * and every request to a provider MUST go through `providerFetch`.
+ *
+ * The rule people usually miss is #3 below. Validating the URL when the machine is created is not
+ * enough: DNS can return a public address at save time and a private one at request time (rebinding).
+ * So validation happens **inside the socket's `lookup` hook**, on the address actually being dialled —
+ * there is no window between the check and the connection.
+ *
+ * Deliberately built on `node:https` rather than `fetch`: only the raw request API exposes `lookup`,
+ * and pinning the resolved address is the whole point. No new dependency either.
+ */
+import { request as httpRequest, type IncomingMessage } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import { isIP } from 'node:net'
+import { lookup as dnsLookup } from 'node:dns/promises'
+import { env } from '../config/env.js'
+
+export class ProviderUrlError extends Error {
+ constructor(message: string, readonly code: ProviderUrlErrorCode) {
+ super(message)
+ this.name = 'ProviderUrlError'
+ }
+}
+
+export type ProviderUrlErrorCode =
+ | 'INVALID_URL'
+ | 'INSECURE_SCHEME'
+ | 'BLOCKED_ADDRESS'
+ | 'DNS_FAILED'
+ | 'REDIRECT_REFUSED'
+ | 'TIMEOUT'
+ | 'RESPONSE_TOO_LARGE'
+
+/** Messages are shown to the owner in the create dialog, so they say what to do about it. */
+const REASONS: Record<ProviderUrlErrorCode, string> = {
+ INVALID_URL: 'That is not a valid URL',
+ INSECURE_SCHEME: 'The provider URL must use https://',
+ BLOCKED_ADDRESS: 'That URL points at a private or internal network address',
+ DNS_FAILED: 'That hostname could not be resolved',
+ REDIRECT_REFUSED: 'The provider redirected the request, which is not allowed',
+ TIMEOUT: 'The provider did not respond in time',
+ RESPONSE_TOO_LARGE: 'The provider sent more data than allowed',
+}
+
+export const reasonFor = (code: ProviderUrlErrorCode): string => REASONS[code]
+
+// ── Address policy ───────────────────────────────────────────────────────────────────────────────
+
+/**
+ * True for an address we refuse to dial.
+ *
+ * `169.254.0.0/16` is the important one and the reason this list is not just "private ranges":
+ * `169.254.169.254` is the cloud instance-metadata endpoint on AWS, GCP and Azure, and reaching it
+ * from our infrastructure hands over instance credentials.
+ */
+export function isBlockedAddress(ip: string): boolean {
+ const family = isIP(ip)
+ if (family === 4) return isBlockedIPv4(ip)
+ if (family === 6) return isBlockedIPv6(ip)
+ return true // not an address we can reason about → refuse
+}
+
+function isBlockedIPv4(ip: string): boolean {
+ const parts = ip.split('.').map((p) => Number(p))
+ if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true
+ const [a, b] = parts as [number, number, number, number]
+ if (a === 0) return true // 0.0.0.0/8 "this network"
+ if (a === 10) return true // private
+ if (a === 127) return true // loopback
+ if (a === 169 && b === 254) return true // link-local — cloud metadata
+ if (a === 172 && b >= 16 && b <= 31) return true // private
+ if (a === 192 && b === 168) return true // private
+ if (a === 100 && b >= 64 && b <= 127) return true // CGNAT
+ if (a === 192 && b === 0) return true // IETF protocol assignments / 192.0.2.0 TEST-NET
+ if (a >= 224) return true // multicast + reserved + broadcast
+ return false
+}
+
+function isBlockedIPv6(raw: string): boolean {
+ const ip = raw.toLowerCase().replace(/^\[|\]$/g, '')
+ if (ip === '::' || ip === '::1') return true // unspecified, loopback
+ // IPv4-mapped (::ffff:10.0.0.1) and IPv4-compatible forms must be judged as IPv4, or every rule
+ // above is trivially bypassed.
+ const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(ip) ?? /^::(\d+\.\d+\.\d+\.\d+)$/.exec(ip)
+ if (mapped) return isBlockedIPv4(mapped[1]!)
+ if (/^f[cd]/.test(ip)) return true // fc00::/7 unique-local
+ if (/^fe[89ab]/.test(ip)) return true // fe80::/10 link-local
+ if (/^ff/.test(ip)) return true // multicast
+ return false
+}
+
+// ── URL policy ───────────────────────────────────────────────────────────────────────────────────
+
+export interface CheckedTarget {
+ /** Normalised absolute URL. */
+ url: string
+ hostname: string
+ port: number
+ /** The address it resolved to at check time — informational; the connection re-checks. */
+ ip: string
+}
+
+function allowInsecure(): boolean {
+ return env.PROVIDER_ALLOW_INSECURE_URLS === true
+}
+
+/**
+ * The address policy, with the dev escape hatch applied.
+ *
+ * `isBlockedAddress` is the pure policy and stays that way so it can be asserted directly. This is
+ * the enforcement point, and it has to honour the dev flag for the same reason the flag exists: a
+ * local `example-provider` (autonomous-ai/autonomous-harness) lives at `http://127.0.0.1:4502`, which
+ * is refused on BOTH counts —
+ * plain http AND loopback. Lifting only the scheme left the flag unable to do the one job it was
+ * added for, which is exactly what happened until someone tried to test locally.
+ */
+function refuseAddress(ip: string): boolean {
+ return isBlockedAddress(ip) && !allowInsecure()
+}
+
+/**
+ * Parse and vet a user-supplied URL. Throws `ProviderUrlError` with a code the UI can map.
+ *
+ * Passing this does NOT make the URL permanently safe — `providerFetch` re-checks at connect time.
+ * This exists to reject obvious mistakes at the moment the owner types them, with a useful message.
+ */
+export async function checkProviderUrl(raw: string): Promise<CheckedTarget> {
+ let url: URL
+ try {
+ url = new URL(raw.trim())
+ } catch {
+ throw new ProviderUrlError(REASONS.INVALID_URL, 'INVALID_URL')
+ }
+
+ if (url.protocol !== 'https:' && !(url.protocol === 'http:' && allowInsecure())) {
+ throw new ProviderUrlError(
+ url.protocol === 'http:' ? REASONS.INSECURE_SCHEME : REASONS.INVALID_URL,
+ url.protocol === 'http:' ? 'INSECURE_SCHEME' : 'INVALID_URL',
+ )
+ }
+ if (url.username || url.password) throw new ProviderUrlError(REASONS.INVALID_URL, 'INVALID_URL')
+
+ const hostname = url.hostname.replace(/^\[|\]$/g, '')
+ const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+
+ // A literal address skips DNS but not the policy.
+ if (isIP(hostname)) {
+ if (refuseAddress(hostname)) throw new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS')
+ return { url: url.toString(), hostname, port, ip: hostname }
+ }
+
+ const resolved = await resolveAll(hostname)
+ // EVERY address must pass: a hostname with one public and one private A record is not safe just
+ // because the resolver happened to return the public one first.
+ for (const addr of resolved) {
+ if (refuseAddress(addr)) throw new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS')
+ }
+ return { url: url.toString(), hostname, port, ip: resolved[0]! }
+}
+
+async function resolveAll(hostname: string): Promise<string[]> {
+ try {
+ const entries = await dnsLookup(hostname, { all: true, verbatim: true })
+ if (!entries.length) throw new Error('no addresses')
+ return entries.map((e) => e.address)
+ } catch {
+ throw new ProviderUrlError(REASONS.DNS_FAILED, 'DNS_FAILED')
+ }
+}
+
+// ── The guarded request ──────────────────────────────────────────────────────────────────────────
+
+export interface ProviderRequestInit {
+ method?: string
+ headers?: Record<string, string>
+ body?: string
+ /** Whole-request budget. Streaming callers pass a large value. */
+ timeoutMs?: number
+ signal?: AbortSignal
+}
+
+export interface ProviderResponse {
+ status: number
+ headers: Record<string, string | string[] | undefined>
+ /** Raw stream — SSE callers read it incrementally. */
+ stream: IncomingMessage
+}
+
+export const DEFAULT_TIMEOUT_MS = 10_000
+export const MAX_BODY_BYTES = 5 * 1024 * 1024
+
+/**
+ * Make a request to a provider with the address policy enforced **at connect time**.
+ *
+ * The `lookup` hook is the load-bearing part: it runs when the socket is about to connect, resolves
+ * the name itself, and refuses to hand back a blocked address. There is no gap between validating an
+ * address and connecting to it, which is what defeats DNS rebinding.
+ */
+export function providerFetch(target: string, init: ProviderRequestInit = {}): Promise<ProviderResponse> {
+ return new Promise((resolve, reject) => {
+ let url: URL
+ try {
+ url = new URL(target)
+ } catch {
+ reject(new ProviderUrlError(REASONS.INVALID_URL, 'INVALID_URL'))
+ return
+ }
+ const secure = url.protocol === 'https:'
+ if (!secure && !(url.protocol === 'http:' && allowInsecure())) {
+ reject(new ProviderUrlError(REASONS.INSECURE_SCHEME, 'INSECURE_SCHEME'))
+ return
+ }
+
+ const timeoutMs = init.timeoutMs ?? DEFAULT_TIMEOUT_MS
+ const req = (secure ? httpsRequest : httpRequest)(
+ {
+ protocol: url.protocol,
+ hostname: url.hostname.replace(/^\[|\]$/g, ''),
+ port: url.port || (secure ? '443' : '80'),
+ path: `${url.pathname}${url.search}`,
+ method: init.method ?? 'GET',
+ headers: init.headers,
+ // THE guard. Called by the socket layer with the host it is about to connect to.
+ lookup: guardedLookup,
+ timeout: timeoutMs,
+ },
+ (res) => {
+ // No redirects. Following one would re-open every check on a URL the owner never typed.
+ if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+ res.destroy()
+ reject(new ProviderUrlError(REASONS.REDIRECT_REFUSED, 'REDIRECT_REFUSED'))
+ return
+ }
+ resolve({ status: res.statusCode ?? 0, headers: res.headers, stream: res })
+ },
+ )
+
+ req.on('timeout', () => {
+ req.destroy(new ProviderUrlError(REASONS.TIMEOUT, 'TIMEOUT'))
+ })
+ req.on('error', (err) => reject(err))
+ init.signal?.addEventListener('abort', () => req.destroy(), { once: true })
+ if (init.body) req.write(init.body)
+ req.end()
+ })
+}
+
+/** Matches Node's `net.LookupFunction` callback: `address` is required, so errors pass an empty one. */
+type LookupCallback = (err: NodeJS.ErrnoException | null, address: string, family: number) => void
+
+/**
+ * `dns.lookup`-shaped hook that refuses blocked addresses.
+ *
+ * Node calls this with the hostname at connect time; whatever it returns is what the socket dials.
+ * Refusing here means a rebinding attack has nothing to rebind to.
+ */
+function guardedLookup(hostname: string, options: unknown, callback: LookupCallback): void {
+ if (isIP(hostname)) {
+ if (refuseAddress(hostname)) {
+ callback(new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS') as NodeJS.ErrnoException, '', 0)
+ return
+ }
+ callback(null, hostname, isIP(hostname))
+ return
+ }
+ dnsLookup(hostname, { all: true, verbatim: true })
+ .then((entries) => {
+ const usable = entries.find((e) => !refuseAddress(e.address))
+ const blocked = entries.some((e) => refuseAddress(e.address))
+ // Any blocked address in the answer set disqualifies the host outright — picking the "good"
+ // one would let an attacker keep a public A record purely to pass the check.
+ if (blocked || !usable) {
+ callback(new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS') as NodeJS.ErrnoException, '', 0)
+ return
+ }
+ callback(null, usable.address, usable.family)
+ })
+ .catch(() => callback(new ProviderUrlError(REASONS.DNS_FAILED, 'DNS_FAILED') as NodeJS.ErrnoException, '', 0))
+}
+
+/** Read a guarded response as text, refusing anything over the cap. */
+export async function readBodyCapped(res: ProviderResponse, max = MAX_BODY_BYTES): Promise<string> {
+ const chunks: Buffer[] = []
+ let size = 0
+ for await (const chunk of res.stream) {
+ size += (chunk as Buffer).length
+ if (size > max) {
+ res.stream.destroy()
+ throw new ProviderUrlError(REASONS.RESPONSE_TOO_LARGE, 'RESPONSE_TOO_LARGE')
+ }
+ chunks.push(chunk as Buffer)
+ }
+ return Buffer.concat(chunks).toString('utf8')
+}
diff --git a/backend/src/lib/provision.ts b/backend/src/lib/provision.ts
new file mode 100644
index 000000000..a56581426
--- /dev/null
+++ b/backend/src/lib/provision.ts
@@ -0,0 +1,62 @@
+/**
+ * Provisioning RPC over the manager socket (Phase 3) — replaces the backend→manager control HTTP
+ * (`lib/manager.ts` create/destroy), so the backend no longer needs `Manager.publicHost`.
+ *
+ * Flow (works across backend instances behind a LB): the requesting backend publishes the command to
+ * `mgr:{managerId}` and waits on `mgrreply:{requestId}`. Whichever backend holds a socket to that
+ * manager (subscribed in managerWs) forwards it over the socket; the manager runs it and replies, which
+ * that backend republishes to `mgrreply:{requestId}`. The manager op is idempotent on machineId, so if
+ * multiple cluster sockets forward it, the duplicate simply errors and the first reply wins.
+ */
+import { randomUUID } from 'crypto'
+import { publishMgr, subscribeReply } from './bus.js'
+
+const PROVISION_TIMEOUT_MS = 60_000
+
+/** No reply arrived before the deadline — the manager op's outcome is UNKNOWN (it may still be
+ * running / the container may still come up). Callers that fire-and-forget a `create` use this to
+ * avoid rolling back a binding whose container might yet register. A definitive failure (manager
+ * replied `ok:false`) rejects with a plain Error instead. */
+export class ProvisionTimeoutError extends Error {
+ readonly code = 'TIMEOUT' as const
+ constructor(message: string) {
+ super(message)
+ this.name = 'ProvisionTimeoutError'
+ }
+}
+
+export function provisionViaManager(
+ managerId: string,
+ cmd: 'create' | 'start' | 'stop' | 'destroy' | 'app_create' | 'app_delete',
+ payload: Record<string, unknown>,
+): Promise<unknown> {
+ const requestId = randomUUID()
+ return new Promise<unknown>((resolve, reject) => {
+ let done = false
+ let unsub: (() => void) | null = null
+ const finish = (fn: () => void): void => {
+ if (done) return
+ done = true
+ if (unsub) unsub()
+ clearTimeout(timer)
+ fn()
+ }
+ // Cold-start can include Docker boot + agent health + restoring a deployed app port.
+ const timeoutMs = cmd === 'start' ? 125_000 : PROVISION_TIMEOUT_MS
+ const timer = setTimeout(
+ () => finish(() => reject(new ProvisionTimeoutError(`provision ${cmd} timed out (manager ${managerId} unreachable)`))),
+ timeoutMs,
+ )
+ void subscribeReply(requestId, (msg) => {
+ const r = msg as { ok?: boolean; data?: unknown; error?: string }
+ finish(() => (r?.ok ? resolve(r.data) : reject(new Error(r?.error || 'provision failed'))))
+ })
+ .then((u) => {
+ if (done) { u(); return }
+ unsub = u
+ void publishMgr(managerId, { requestId, cmd, payload })
+ .catch((err) => finish(() => reject(err instanceof Error ? err : new Error(String(err)))))
+ })
+ .catch((err) => finish(() => reject(err instanceof Error ? err : new Error(String(err)))))
+ })
+}
diff --git a/backend/src/lib/registry.ts b/backend/src/lib/registry.ts
new file mode 100644
index 000000000..ac802d824
--- /dev/null
+++ b/backend/src/lib/registry.ts
@@ -0,0 +1,268 @@
+/**
+ * Per-instance connection registry for the backend hub.
+ *
+ * This is deliberately PER-PROCESS (like the old agentTargetCache) — cross-instance routing is done
+ * with Redis (lib/bus.ts), never shared connection state. Each backend instance tracks only the
+ * sockets it locally terminates:
+ * - client sockets (web + device/commander) it accepted, grouped by machineId
+ * - manager sockets that dialed into it, by managerId
+ * - which local manager socket owns a given machineId's node (for down routing)
+ */
+import { randomUUID } from 'crypto'
+import type { WebSocket } from 'ws'
+
+/** Stable id for THIS backend process — tags up-frames so the origin instance skips its own Redis
+ * loopback after delivering to local clients directly (chat-up local fast-path). */
+export const PROCESS_ID = randomUUID()
+
+export type ClientKind = 'web' | 'commander'
+
+export interface ClientConn {
+ connId: string
+ machineId: string
+ kind: ClientKind
+ socket: WebSocket
+ // Resolved from a commander socket's `device_hello` (self-reported deviceId). Lets a revoke frame
+ // target exactly one device of an agent (see hub.deliverUpLocal targetDeviceId filter). Undefined for
+ // web clients and for legacy firmware that doesn't report it.
+ deviceId?: string
+ // Multi-attach: a commander (device) holds N machines at once but RENDERS only one. `active` marks the
+ // machine this connection currently renders → drives the per-machine `commanderActive` count in `__clients`
+ // so the node/adapter streams full turn cards only to an actively-viewed machine, while still running the
+ // (cheaper) recap for every attached commander. Always false/undefined for web + background machines.
+ active?: boolean
+}
+
+export interface QueuedCommanderFrame {
+ frame: unknown
+ payload: string
+}
+
+// machineId → (connId → client) held on THIS instance
+const clientsByAgent = new Map<string, Map<string, ClientConn>>()
+// `${machineId}:${connId}` → low-priority backend→commander frames held while that device uploads voice.
+const commanderVoiceQueues = new Map<string, { frames: Map<string, QueuedCommanderFrame>; order: string[] }>()
+// managerId → manager socket held on THIS instance
+const managerSockets = new Map<string, WebSocket>()
+// machineId → managerId: which locally-held manager socket owns this agent's node (down routing)
+const agentToManager = new Map<string, string>()
+// managerId → set of machineIds it currently owns (for cleanup on manager disconnect)
+const managerAgents = new Map<string, Set<string>>()
+// machineId → the LOCAL manager socket held on THIS instance for the app-proxy / control planes, so the
+// data-plane can short-circuit Redis when this instance holds both the client and the manager socket
+// (co-located). Keyed by plane because app + chat ride separate pool sockets (possibly this vs another
+// instance independently).
+const appSocketByAgent = new Map<string, WebSocket>()
+const controlSocketByAgent = new Map<string, WebSocket>()
+const MAX_COMMANDER_VOICE_QUEUE = 32
+
+// ── clients ──────────────────────────────────────────────────────────────────────────────────────
+
+/** Returns true if this is the FIRST client for the agent on this instance (→ subscribe up:{machineId}). */
+export function addClient(conn: ClientConn): boolean {
+ let m = clientsByAgent.get(conn.machineId)
+ const first = !m || m.size === 0
+ if (!m) {
+ m = new Map()
+ clientsByAgent.set(conn.machineId, m)
+ }
+ m.set(conn.connId, conn)
+ return first
+}
+
+/** Returns true if that was the LAST client for the agent on this instance (→ unsubscribe up:{machineId}). */
+export function removeClient(machineId: string, connId: string): boolean {
+ const m = clientsByAgent.get(machineId)
+ if (!m) return false
+ clearCommanderVoiceQueue(machineId, connId)
+ m.delete(connId)
+ if (m.size === 0) {
+ clientsByAgent.delete(machineId)
+ return true
+ }
+ return false
+}
+
+export function clientsFor(machineId: string): ClientConn[] {
+ const m = clientsByAgent.get(machineId)
+ return m ? [...m.values()] : []
+}
+
+/** Every local client (web + commander) across all agents — for the hub keep-alive sweep. */
+export function allClients(): ClientConn[] {
+ const out: ClientConn[] = []
+ for (const m of clientsByAgent.values()) out.push(...m.values())
+ return out
+}
+
+/** machineIds with ≥1 local client on this instance — for the hub heartbeat's client-count refresh. */
+export function localAgentIds(): string[] {
+ return [...clientsByAgent.keys()]
+}
+
+/** Tag a commander connection with the deviceId it reported in device_hello (for targeted delivery). */
+export function setClientDeviceId(machineId: string, connId: string, deviceId: string): void {
+ const c = clientsByAgent.get(machineId)?.get(connId)
+ if (c) c.deviceId = deviceId
+}
+
+/** Mark/unmark a commander connection as actively RENDERING this machine. Returns true if the flag changed
+ * (so the caller re-emits `__clients` only on a real transition). */
+export function setClientActive(machineId: string, connId: string, active: boolean): boolean {
+ const c = clientsByAgent.get(machineId)?.get(connId)
+ if (!c || !!c.active === active) return false
+ c.active = active
+ return true
+}
+
+export function clientCounts(machineId: string): { ui: number; commander: number; commanderActive: number } {
+ const m = clientsByAgent.get(machineId)
+ let ui = 0
+ let commander = 0
+ let commanderActive = 0
+ if (m) for (const c of m.values()) {
+ if (c.kind === 'commander') { commander++; if (c.active) commanderActive++ }
+ else ui++
+ }
+ return { ui, commander, commanderActive }
+}
+
+function commanderQueueId(machineId: string, connId: string): string {
+ return `${machineId}:${connId}`
+}
+
+function frameType(frame: unknown): string {
+ return typeof (frame as { type?: unknown })?.type === 'string' ? (frame as { type: string }).type : 'unknown'
+}
+
+function framePayload(frame: unknown): Record<string, unknown> {
+ const payload = (frame as { payload?: unknown })?.payload
+ return payload && typeof payload === 'object' ? payload as Record<string, unknown> : {}
+}
+
+function textPart(value: unknown): string {
+ return typeof value === 'string' || typeof value === 'number' ? String(value) : ''
+}
+
+function queueKeyForFrame(frame: unknown): string {
+ const type = frameType(frame)
+ const payload = framePayload(frame)
+ const top = frame as { machineId?: unknown; dbSessionId?: unknown; requestId?: unknown }
+ const requestId = textPart(payload.requestId) || textPart(top.requestId)
+ const machineId = textPart(top.machineId) || textPart(payload.machineId)
+ const sessionId = textPart(top.dbSessionId) || textPart(payload.sessionId)
+ const kind = textPart(payload.kind)
+ if (type.endsWith('_result') && requestId) return `${type}:req:${requestId}`
+ if (type === 'commander_event') return `${type}:${machineId}:${sessionId}:${kind}`
+ if (type === 'machines_status' || type === 'node_status') return type
+ return `${type}:${machineId}:${sessionId}:${requestId}`
+}
+
+function isVoiceCriticalFrame(frame: unknown): boolean {
+ const type = frameType(frame)
+ if (type === 'device_revoked' || type === 'transcript' || type === 'too_short' || type === 'error' || type === 'empty' || type === 'dispatched') return true
+ if (type !== 'commander_event') return false
+ const kind = framePayload(frame).kind
+ return kind === 'processing' || kind === 'done'
+}
+
+export function startCommanderVoiceQueue(machineId: string, connId: string): void {
+ commanderVoiceQueues.set(commanderQueueId(machineId, connId), { frames: new Map(), order: [] })
+}
+
+export function flushCommanderVoiceQueue(machineId: string, connId: string): QueuedCommanderFrame[] {
+ const id = commanderQueueId(machineId, connId)
+ const q = commanderVoiceQueues.get(id)
+ if (!q) return []
+ commanderVoiceQueues.delete(id)
+ return q.order.map((key) => q.frames.get(key)).filter((f): f is QueuedCommanderFrame => !!f)
+}
+
+export function clearCommanderVoiceQueue(machineId: string, connId: string): void {
+ commanderVoiceQueues.delete(commanderQueueId(machineId, connId))
+}
+
+/** Returns true when the frame was queued instead of being sent immediately. */
+export function queueCommanderFrame(machineId: string, connId: string, frame: unknown, payload: string): boolean {
+ if (isVoiceCriticalFrame(frame)) return false
+ const q = commanderVoiceQueues.get(commanderQueueId(machineId, connId))
+ if (!q) return false
+ const key = queueKeyForFrame(frame)
+ if (!q.frames.has(key)) {
+ q.order.push(key)
+ if (q.order.length > MAX_COMMANDER_VOICE_QUEUE) {
+ const dropped = q.order.shift()
+ if (dropped) q.frames.delete(dropped)
+ }
+ }
+ q.frames.set(key, { frame, payload })
+ return true
+}
+
+// ── managers ─────────────────────────────────────────────────────────────────────────────────────
+
+export function addManager(managerId: string, socket: WebSocket): void {
+ managerSockets.set(managerId, socket)
+ if (!managerAgents.has(managerId)) managerAgents.set(managerId, new Set())
+}
+
+export function removeManager(managerId: string): string[] {
+ managerSockets.delete(managerId)
+ const agents = [...(managerAgents.get(managerId) ?? [])]
+ managerAgents.delete(managerId)
+ for (const machineId of agents) {
+ if (agentToManager.get(machineId) === managerId) agentToManager.delete(machineId)
+ }
+ return agents
+}
+
+export function managerSocketFor(managerId: string): WebSocket | undefined {
+ return managerSockets.get(managerId)
+}
+
+export function bindAgentManager(machineId: string, managerId: string): void {
+ agentToManager.set(machineId, managerId)
+ let set = managerAgents.get(managerId)
+ if (!set) {
+ set = new Set()
+ managerAgents.set(managerId, set)
+ }
+ set.add(machineId)
+}
+
+export function unbindAgent(machineId: string, managerId: string): void {
+ if (agentToManager.get(machineId) === managerId) agentToManager.delete(machineId)
+ managerAgents.get(managerId)?.delete(machineId)
+}
+
+export function agentsForManager(managerId: string): string[] {
+ return [...(managerAgents.get(managerId) ?? [])]
+}
+
+// ── local manager-socket ownership (data-plane fast-path: skip Redis when co-located) ──────────────
+
+/** The app-pool manager socket for this agent, IF held on this instance (else undefined → use Redis). */
+export function appSocketFor(machineId: string): WebSocket | undefined {
+ return appSocketByAgent.get(machineId)
+}
+export function bindAppSocket(machineId: string, ws: WebSocket): void {
+ appSocketByAgent.set(machineId, ws)
+}
+export function unbindAppSocket(machineId: string, ws: WebSocket): void {
+ if (appSocketByAgent.get(machineId) === ws) appSocketByAgent.delete(machineId)
+}
+
+/** The control manager socket for this agent, IF held on this instance (chat-down fast-path). */
+export function controlSocketFor(machineId: string): WebSocket | undefined {
+ return controlSocketByAgent.get(machineId)
+}
+/** Agents whose control socket is bound on THIS instance — i.e. the agents this instance is B_m for. */
+export function controlAgentIds(): string[] {
+ return [...controlSocketByAgent.keys()]
+}
+export function bindControlSocket(machineId: string, ws: WebSocket): void {
+ controlSocketByAgent.set(machineId, ws)
+}
+export function unbindControlSocket(machineId: string, ws: WebSocket): void {
+ if (controlSocketByAgent.get(machineId) === ws) controlSocketByAgent.delete(machineId)
+}
diff --git a/backend/src/lib/sso.test.ts b/backend/src/lib/sso.test.ts
new file mode 100644
index 000000000..f28a69871
--- /dev/null
+++ b/backend/src/lib/sso.test.ts
@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const state = vi.hoisted(() => ({
+ set: vi.fn(),
+ eval: vi.fn(),
+}))
+
+vi.mock('./bus.js', () => ({ pub: state }))
+
+import { consumeTx, createTx, refreshAccessToken, SsoTokenError, type SsoTx } from './sso.js'
+
+const tx: SsoTx = {
+ verifier: 'verifier',
+ state: 'state',
+ next: '/machine/1',
+ redirectUri: 'http://localhost:3000/auth/callback',
+ webOrigin: 'http://localhost:3000',
+ autonomousEnv: 'stag',
+}
+
+describe('SSO PKCE transaction store', () => {
+ beforeEach(() => {
+ state.set.mockReset()
+ state.eval.mockReset()
+ })
+
+ afterEach(() => {
+ vi.unstubAllGlobals()
+ })
+
+ it('stores an opaque one-time id in Redis for ten minutes', async () => {
+ state.set.mockResolvedValue('OK')
+ const id = await createTx(tx)
+
+ expect(id).toMatch(/^[A-Za-z0-9_-]{40,}$/)
+ expect(state.set).toHaveBeenCalledWith(
+ `sso:tx:${id}`,
+ JSON.stringify(tx),
+ 'EX',
+ 600,
+ 'NX',
+ )
+ })
+
+ it('atomically consumes and validates a transaction', async () => {
+ state.eval.mockResolvedValue(JSON.stringify(tx))
+ await expect(consumeTx('opaque-id')).resolves.toEqual(tx)
+ expect(state.eval).toHaveBeenCalledWith(expect.stringContaining("redis.call('del'"), 1, 'sso:tx:opaque-id')
+ })
+
+ it('rejects missing or malformed transactions', async () => {
+ state.eval.mockResolvedValueOnce(null).mockResolvedValueOnce('{bad json')
+ await expect(consumeTx('missing')).resolves.toBeNull()
+ await expect(consumeTx('malformed')).resolves.toBeNull()
+ })
+
+ it('exchanges a refresh token with the selected environment client', async () => {
+ const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
+ access_token: 'new-access',
+ refresh_token: 'rotated-refresh',
+ expires_in: 3600,
+ }), { status: 200, headers: { 'Content-Type': 'application/json' } }))
+ vi.stubGlobal('fetch', fetchMock)
+
+ await expect(refreshAccessToken('old-refresh', 'stag')).resolves.toMatchObject({
+ access_token: 'new-access',
+ refresh_token: 'rotated-refresh',
+ expires_in: 3600,
+ })
+ const [url, init] = fetchMock.mock.calls[0]
+ expect(String(url)).toContain('auth.staging.autonomousdev.xyz/oauth2/token')
+ const body = init?.body as URLSearchParams
+ expect(body.get('grant_type')).toBe('refresh_token')
+ expect(body.get('refresh_token')).toBe('old-refresh')
+ expect(body.get('client_id')).toBeTruthy()
+ })
+
+ it('distinguishes invalid refresh tokens from token-service outages', async () => {
+ vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValueOnce(new Response(
+ JSON.stringify({ error: 'invalid_grant' }),
+ { status: 400, headers: { 'Content-Type': 'application/json' } },
+ )).mockRejectedValueOnce(new Error('offline')))
+
+ await expect(refreshAccessToken('expired', 'prod')).rejects.toMatchObject({
+ code: 'INVALID_GRANT',
+ } satisfies Partial<SsoTokenError>)
+ await expect(refreshAccessToken('valid', 'prod')).rejects.toMatchObject({
+ code: 'TOKEN_SERVICE_UNAVAILABLE',
+ } satisfies Partial<SsoTokenError>)
+ })
+})
diff --git a/backend/src/lib/sso.ts b/backend/src/lib/sso.ts
new file mode 100644
index 000000000..178d2dc5f
--- /dev/null
+++ b/backend/src/lib/sso.ts
@@ -0,0 +1,241 @@
+/**
+ * Autonomous SSO — OAuth2 Authorization Code + PKCE.
+ *
+ * The backend builds the authorize URL, keeps PKCE verifier + CSRF state in a one-time Redis
+ * transaction, and exchanges the code itself. The resulting SSO access token is returned to the web
+ * and validated on subsequent control-plane requests through the Autonomous profile API.
+ */
+import { createHash, randomBytes } from 'crypto'
+import { env } from '../config/env.js'
+import { pub } from './bus.js'
+import {
+ autonomousEnvironmentConfig,
+ isAutonomousEnvironment,
+ type AutonomousEnvironment,
+} from './autonomousEnvironment.js'
+
+const b64url = (b: Buffer): string =>
+ b.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+
+/** A PKCE verifier (kept secret in the Redis transaction) + its S256 challenge. */
+export function pkcePair(): { verifier: string; challenge: string } {
+ const verifier = b64url(randomBytes(32))
+ const challenge = b64url(createHash('sha256').update(verifier).digest())
+ return { verifier, challenge }
+}
+
+export const randomState = (): string => b64url(randomBytes(16))
+
+const SSO_TX_TTL_SEC = 10 * 60
+const ssoTxKey = (id: string): string => `sso:tx:${id}`
+
+/** Per-login transaction stored server-side for 10 minutes. The browser only receives an opaque id. */
+export interface SsoTx {
+ verifier: string
+ state: string
+ next: string
+ redirectUri: string
+ webOrigin: string
+ autonomousEnv: AutonomousEnvironment
+}
+
+function validTx(raw: unknown): raw is SsoTx {
+ const tx = raw as Partial<SsoTx> | null
+ return !!tx && typeof tx.verifier === 'string' && typeof tx.state === 'string' &&
+ typeof tx.next === 'string' && typeof tx.redirectUri === 'string' && typeof tx.webOrigin === 'string' &&
+ (tx.autonomousEnv === undefined || isAutonomousEnvironment(tx.autonomousEnv))
+}
+
+export async function createTx(tx: SsoTx): Promise<string> {
+ for (let attempt = 0; attempt < 3; attempt++) {
+ const id = b64url(randomBytes(32))
+ const stored = await pub.set(ssoTxKey(id), JSON.stringify(tx), 'EX', SSO_TX_TTL_SEC, 'NX')
+ if (stored === 'OK') return id
+ }
+ throw new Error('could not allocate sso transaction')
+}
+
+/** Atomically read + delete so an authorization code transaction cannot be replayed. */
+export async function consumeTx(id: string): Promise<SsoTx | null> {
+ const raw = await pub.eval(
+ "local v = redis.call('get', KEYS[1]); if v then redis.call('del', KEYS[1]) end; return v",
+ 1,
+ ssoTxKey(id),
+ )
+ if (typeof raw !== 'string') return null
+ try {
+ const parsed: unknown = JSON.parse(raw)
+ return validTx(parsed)
+ ? { ...parsed, autonomousEnv: parsed.autonomousEnv ?? 'prod' }
+ : null
+ } catch {
+ return null
+ }
+}
+
+// --- Origin derivation (so live→live, local→local without hardcoding) ------------------------------
+const firstHeader = (v: string | string[] | undefined): string | undefined =>
+ (Array.isArray(v) ? v[0] : v)?.split(',')[0].trim()
+
+/** The SPA origin that initiated the login, from an explicit ?origin, else the Origin/Referer header. */
+export function requestedWebOrigin(
+ query: { origin?: string },
+ headers: Record<string, string | string[] | undefined>,
+): string | undefined {
+ if (query.origin) return query.origin
+ const origin = firstHeader(headers['origin'])
+ if (origin) return origin
+ const ref = firstHeader(headers['referer'])
+ if (ref) {
+ try {
+ const u = new URL(ref)
+ return `${u.protocol}//${u.host}`
+ } catch {
+ /* ignore */
+ }
+ }
+ return undefined
+}
+
+/** Allowlist of SPA origins the post-login token may be redirected to (WEB_URL + WEB_ORIGINS). */
+export function allowedWebOrigins(): string[] {
+ return [env.WEB_URL, ...env.WEB_ORIGINS.split(',')]
+ .map((s) => s.trim().replace(/\/$/, ''))
+ .filter(Boolean)
+}
+
+/** Resolve the (trusted) SPA origin: the requested one IF allowlisted, else the primary WEB_URL. */
+export function resolveWebOrigin(requested: string | undefined): string {
+ const allow = allowedWebOrigins()
+ const norm = requested?.trim().replace(/\/$/, '')
+ return norm && allow.includes(norm) ? norm : allow[0] || env.WEB_URL
+}
+
+/** The WEB callback URL (the new SSO redirect_uri) — a page on the web origin, so the browser never
+ * lands on the API. An explicit SSO_REDIRECT_URI pins it; else it's the (allowlisted) web origin. */
+/** Loopback-only redirect URIs for native/desktop OAuth. Accepts 127.0.0.1, localhost, [::1]. */
+export function isLoopbackRedirectUri(redirectUri: string): boolean {
+ let u: URL
+ try { u = new URL(redirectUri) } catch { return false }
+ if (u.protocol !== 'http:' && u.protocol !== 'https:') return false
+ const host = u.hostname.toLowerCase()
+ return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]'
+}
+
+export function webCallbackUri(webOrigin: string): string {
+ return env.SSO_REDIRECT_URI || `${webOrigin.replace(/\/$/, '')}/auth/callback`
+}
+
+/** Where to send the browser to log in. `prompt=select_account` (env) forces the account picker so
+ * a user can switch accounts even when an SSO session already exists. */
+export function authorizeUrl(
+ challenge: string,
+ state: string,
+ redirectUri: string,
+ autonomousEnv: AutonomousEnvironment,
+): string {
+ const config = autonomousEnvironmentConfig(autonomousEnv)
+ const u = new URL('/oauth2/authorize', config.ssoIssuer)
+ u.searchParams.set('response_type', 'code')
+ u.searchParams.set('client_id', config.ssoClientId)
+ u.searchParams.set('redirect_uri', redirectUri)
+ u.searchParams.set('scope', env.SSO_SCOPE)
+ u.searchParams.set('code_challenge', challenge)
+ u.searchParams.set('code_challenge_method', 'S256')
+ u.searchParams.set('state', state)
+ if (env.SSO_PROMPT) u.searchParams.set('prompt', env.SSO_PROMPT)
+ return u.toString()
+}
+
+/** End-session URL — clears the SSO session so the next login isn't silently auto-completed. */
+export function logoutUrl(webOrigin: string, autonomousEnv: AutonomousEnvironment): string {
+ const config = autonomousEnvironmentConfig(autonomousEnv)
+ const u = new URL('/oauth2/logout', config.ssoIssuer)
+ u.searchParams.set('client_id', config.ssoClientId)
+ u.searchParams.set('post_logout_redirect_uri', webOrigin)
+ return u.toString()
+}
+
+export interface SsoTokens {
+ access_token?: string
+ id_token?: string
+ refresh_token?: string
+ token_type?: string
+ expires_in?: number
+}
+
+export class SsoTokenError extends Error {
+ constructor(
+ message: string,
+ readonly code: 'INVALID_GRANT' | 'TOKEN_SERVICE_UNAVAILABLE',
+ ) {
+ super(message)
+ this.name = 'SsoTokenError'
+ }
+}
+
+async function requestTokens(
+ body: URLSearchParams,
+ autonomousEnv: AutonomousEnvironment,
+): Promise<SsoTokens> {
+ const config = autonomousEnvironmentConfig(autonomousEnv)
+ if (config.ssoClientSecret) body.set('client_secret', config.ssoClientSecret)
+
+ let res: Response
+ try {
+ res = await fetch(new URL('/oauth2/token', config.ssoIssuer).toString(), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+ body,
+ signal: AbortSignal.timeout(env.SSO_PROFILE_TIMEOUT_MS),
+ })
+ } catch {
+ throw new SsoTokenError('SSO token service unavailable', 'TOKEN_SERVICE_UNAVAILABLE')
+ }
+
+ if (!res.ok) {
+ const detail = await res.text().catch(() => '')
+ const invalidGrant = res.status === 400 && /invalid[_ -]?grant|invalid.*refresh|expired.*refresh/i.test(detail)
+ throw new SsoTokenError(
+ `SSO token endpoint returned ${res.status}`,
+ invalidGrant ? 'INVALID_GRANT' : 'TOKEN_SERVICE_UNAVAILABLE',
+ )
+ }
+
+ try {
+ return (await res.json()) as SsoTokens
+ } catch {
+ throw new SsoTokenError('SSO token service returned invalid JSON', 'TOKEN_SERVICE_UNAVAILABLE')
+ }
+}
+
+/** Exchange the authorization code for tokens (public client + PKCE; no secret unless configured). */
+export async function exchangeCode(
+ code: string,
+ verifier: string,
+ redirectUri: string,
+ autonomousEnv: AutonomousEnvironment,
+): Promise<SsoTokens> {
+ const config = autonomousEnvironmentConfig(autonomousEnv)
+ const body = new URLSearchParams({
+ grant_type: 'authorization_code',
+ code,
+ redirect_uri: redirectUri, // MUST match the one sent to /authorize
+ client_id: config.ssoClientId,
+ code_verifier: verifier,
+ })
+ return requestTokens(body, autonomousEnv)
+}
+
+/** Exchange a browser-held refresh token for a fresh SSO access token. */
+export async function refreshAccessToken(
+ refreshToken: string,
+ autonomousEnv: AutonomousEnvironment,
+): Promise<SsoTokens> {
+ const config = autonomousEnvironmentConfig(autonomousEnv)
+ return requestTokens(new URLSearchParams({
+ grant_type: 'refresh_token',
+ refresh_token: refreshToken,
+ client_id: config.ssoClientId,
+ }), autonomousEnv)
+}
diff --git a/backend/src/lib/ssoAuth.test.ts b/backend/src/lib/ssoAuth.test.ts
new file mode 100644
index 000000000..8117c3390
--- /dev/null
+++ b/backend/src/lib/ssoAuth.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const findByEmail = vi.hoisted(() => vi.fn())
+const findByExternal = vi.hoisted(() => vi.fn())
+const upsertFromSso = vi.hoisted(() => vi.fn())
+
+vi.mock('../services/UserService.js', () => ({
+ userService: { findByEmail, findByExternal, upsertFromSso },
+ normalizeUserEmail: (email: string) => email.trim().toLowerCase(),
+ isProvisionalUserEmail: (email: string) => email.endsWith('@pending.harness.invalid'),
+}))
+
+import { authenticateAccessToken, fetchSsoProfile, SsoAuthError } from './ssoAuth.js'
+
+function response(status: number, body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status,
+ headers: { 'Content-Type': 'application/json' },
+ })
+}
+
+describe('SSO profile authentication', () => {
+ it('sends the SSO access token and required locale header', async () => {
+ const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(response(200, {
+ status: 1,
+ data: { id: 'external-1', email: '[email protected]' },
+ }))
+
+ await expect(fetchSsoProfile('access.token.value', fetchMock)).resolves.toEqual({
+ id: 'external-1',
+ email: '[email protected]',
+ })
+ expect(fetchMock).toHaveBeenCalledOnce()
+ const [, init] = fetchMock.mock.calls[0]
+ expect(init?.headers).toMatchObject({
+ Accept: 'application/json',
+ 'Content-Type': 'application/json',
+ Location: 'en-US',
+ Authorization: 'Bearer access.token.value',
+ })
+ })
+
+ it('classifies 401 as an invalid token', async () => {
+ const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(response(401, { message: 'Invalid or expired JWT' }))
+ await expect(fetchSsoProfile('expired', fetchMock)).rejects.toMatchObject({ code: 'INVALID_TOKEN' } satisfies Partial<SsoAuthError>)
+ })
+
+ it('classifies network and malformed-profile failures as service unavailable', async () => {
+ const network = vi.fn<typeof fetch>().mockRejectedValue(new Error('offline'))
+ await expect(fetchSsoProfile('token', network)).rejects.toMatchObject({ code: 'AUTH_SERVICE_UNAVAILABLE' } satisfies Partial<SsoAuthError>)
+
+ const malformed = vi.fn<typeof fetch>().mockResolvedValue(response(200, { status: -1, message: 'missing location' }))
+ await expect(fetchSsoProfile('token', malformed)).rejects.toMatchObject({ code: 'AUTH_SERVICE_UNAVAILABLE' } satisfies Partial<SsoAuthError>)
+ })
+})
+
+describe('authenticated user resolution', () => {
+ afterEach(() => {
+ vi.clearAllMocks()
+ vi.unstubAllGlobals()
+ })
+
+ function profileFetch(id: string, email: string): void {
+ vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(response(200, {
+ status: 1,
+ data: { id, email },
+ })))
+ }
+
+ it('uses normalized email as identity and saves the staging subject separately', async () => {
+ profileFetch('stag-sub-1', ' [email protected] ')
+ const existing = {
+ id: 'u1',
+ email: '[email protected]',
+ externalId: 'prod-sub-1',
+ stagExternalId: null,
+ role: 'user',
+ autonomousEnv: 'stag',
+ }
+ findByEmail.mockResolvedValue(existing)
+ upsertFromSso.mockResolvedValue({ ...existing, stagExternalId: 'stag-sub-1' })
+
+ await expect(authenticateAccessToken('a.e30.c', 'stag')).resolves.toEqual({
+ sub: 'u1',
+ email: '[email protected]',
+ role: 'user',
+ autonomousEnv: 'stag',
+ })
+ expect(upsertFromSso).toHaveBeenCalledWith(expect.objectContaining({
+ externalId: 'stag-sub-1',
+ email: '[email protected]',
+ autonomousEnv: 'stag',
+ }))
+ expect(findByExternal).not.toHaveBeenCalled()
+ })
+
+ it('claims a prod provisional row by User.externalId', async () => {
+ profileFetch('prod-sub-1', '[email protected]')
+ findByEmail.mockResolvedValue(null)
+ findByExternal.mockResolvedValue({
+ id: 'pending',
+ email: '[email protected]',
+ externalId: 'prod-sub-1',
+ role: 'user',
+ autonomousEnv: 'prod',
+ })
+ upsertFromSso.mockResolvedValue({
+ id: 'pending',
+ email: '[email protected]',
+ role: 'user',
+ })
+
+ await expect(authenticateAccessToken('a.e30.c', 'prod')).resolves.toMatchObject({ sub: 'pending' })
+ expect(upsertFromSso).toHaveBeenCalledOnce()
+ })
+
+ it('keeps unknown staging emails closed', async () => {
+ profileFetch('stag-sub-new', '[email protected]')
+ findByEmail.mockResolvedValue(null)
+
+ await expect(authenticateAccessToken('a.e30.c', 'stag')).rejects.toMatchObject({
+ code: 'AUTONOMOUS_ENV_NOT_ALLOWED',
+ requiredEnv: 'prod',
+ })
+ expect(upsertFromSso).not.toHaveBeenCalled()
+ })
+
+ it('rejects the wrong environment without mutating identity fields', async () => {
+ profileFetch('prod-sub-1', '[email protected]')
+ findByEmail.mockResolvedValue({
+ id: 'u1',
+ email: '[email protected]',
+ externalId: 'local-prod-u1',
+ role: 'user',
+ autonomousEnv: 'stag',
+ })
+
+ await expect(authenticateAccessToken('a.e30.c', 'prod')).rejects.toMatchObject({
+ code: 'AUTONOMOUS_ENV_MISMATCH',
+ requiredEnv: 'stag',
+ })
+ expect(upsertFromSso).not.toHaveBeenCalled()
+ })
+})
diff --git a/backend/src/lib/ssoAuth.ts b/backend/src/lib/ssoAuth.ts
new file mode 100644
index 000000000..ab80a81fd
--- /dev/null
+++ b/backend/src/lib/ssoAuth.ts
@@ -0,0 +1,174 @@
+import { env } from '../config/env.js'
+import {
+ isProvisionalUserEmail,
+ normalizeUserEmail,
+ userService,
+} from '../services/UserService.js'
+import {
+ autonomousEnvironmentConfig,
+ storedAutonomousEnvironment,
+ type AutonomousEnvironment,
+} from './autonomousEnvironment.js'
+
+/** Internal identity attached to authenticated backend requests and user WebSockets. */
+export interface AuthUser {
+ sub: string // internal database user id
+ email: string
+ role: string
+ autonomousEnv: AutonomousEnvironment
+}
+
+export interface SsoProfile {
+ id: string
+ email: string
+}
+
+export class SsoAuthError extends Error {
+ constructor(
+ message: string,
+ readonly code: 'INVALID_TOKEN' | 'AUTH_SERVICE_UNAVAILABLE' | 'AUTONOMOUS_ENV_MISMATCH' | 'AUTONOMOUS_ENV_NOT_ALLOWED',
+ readonly requiredEnv?: AutonomousEnvironment,
+ ) {
+ super(message)
+ this.name = 'SsoAuthError'
+ }
+}
+
+export function bearerToken(header: string | undefined): string | undefined {
+ if (!header) return undefined
+ const m = /^Bearer\s+(.+)$/i.exec(header)
+ return m ? m[1].trim() : undefined
+}
+
+type FetchLike = typeof fetch
+
+/** Validate the SSO access token against the Autonomous profile service. */
+export async function fetchSsoProfile(
+ token: string,
+ autonomousEnvOrFetch: AutonomousEnvironment | FetchLike = 'prod',
+ fetchOverride?: FetchLike,
+): Promise<SsoProfile> {
+ // Preserve the old test/helper call shape fetchSsoProfile(token, fetchImpl) while production code
+ // always supplies the environment explicitly.
+ const autonomousEnv = typeof autonomousEnvOrFetch === 'function' ? 'prod' : autonomousEnvOrFetch
+ const fetchImpl = typeof autonomousEnvOrFetch === 'function' ? autonomousEnvOrFetch : (fetchOverride ?? fetch)
+ let res: Response
+ try {
+ res = await fetchImpl(autonomousEnvironmentConfig(autonomousEnv).ssoProfileUrl, {
+ method: 'GET',
+ headers: {
+ Accept: 'application/json',
+ 'Content-Type': 'application/json',
+ Location: 'en-US',
+ Authorization: `Bearer ${token}`,
+ },
+ signal: AbortSignal.timeout(env.SSO_PROFILE_TIMEOUT_MS),
+ })
+ } catch {
+ throw new SsoAuthError('SSO profile service unavailable', 'AUTH_SERVICE_UNAVAILABLE')
+ }
+
+ if (res.status === 401 || res.status === 403) {
+ throw new SsoAuthError('Invalid or expired SSO access token', 'INVALID_TOKEN')
+ }
+ if (!res.ok) {
+ throw new SsoAuthError(`SSO profile service returned ${res.status}`, 'AUTH_SERVICE_UNAVAILABLE')
+ }
+
+ let raw: unknown
+ try { raw = await res.json() } catch {
+ throw new SsoAuthError('SSO profile service returned invalid JSON', 'AUTH_SERVICE_UNAVAILABLE')
+ }
+ const body = raw as { status?: unknown; message?: unknown; data?: { id?: unknown; email?: unknown } }
+ if (body.status !== 1 || typeof body.data?.id !== 'string' || !body.data.id ||
+ typeof body.data.email !== 'string' || !body.data.email) {
+ const message = typeof body.message === 'string' ? body.message : ''
+ if (/invalid|expired|unauthorized/i.test(message)) {
+ throw new SsoAuthError('Invalid or expired SSO access token', 'INVALID_TOKEN')
+ }
+ throw new SsoAuthError('SSO profile service returned an invalid profile', 'AUTH_SERVICE_UNAVAILABLE')
+ }
+ return { id: body.data.id, email: body.data.email }
+}
+
+/** Optional metadata is read only AFTER the profile service has authenticated this access token. */
+function accessTokenMetadata(token: string): { name?: string; roles?: string[] } {
+ try {
+ const part = token.split('.')[1]
+ if (!part) return {}
+ const raw = JSON.parse(Buffer.from(part, 'base64url').toString('utf8')) as Record<string, unknown>
+ const flat: Record<string, unknown> = {}
+ for (const container of ['ext_info', 'user', 'profile', 'data', 'claims', 'userInfo', 'user_info']) {
+ const value = raw[container]
+ if (value && typeof value === 'object') Object.assign(flat, value)
+ }
+ Object.assign(flat, raw)
+ const pick = (...keys: string[]): string | undefined => {
+ for (const key of keys) {
+ const value = flat[key]
+ if (value != null && value !== '') return String(value)
+ }
+ return undefined
+ }
+ const given = pick('given_name', 'givenName', 'firstName', 'first_name')
+ const family = pick('family_name', 'familyName', 'lastName', 'last_name')
+ const name =
+ pick('name', 'fullName', 'full_name', 'displayName', 'display_name', 'nickname', 'user_name', 'username') ??
+ ([given, family].filter(Boolean).join(' ') || undefined)
+ const roles = Array.isArray(flat.roles) ? flat.roles.map(String) : undefined
+ return { ...(name ? { name } : {}), ...(roles ? { roles } : {}) }
+ } catch {
+ return {}
+ }
+}
+
+/** Validate the token, mirror the external identity, then return the app's internal user identity. */
+/**
+ * @param enforceEnv Gate the caller on the account plane their user row is stamped with. TRUE for the
+ * web, which can be pointed at either plane and must not let the two identities cross.
+ *
+ * FALSE for a surface that is production-only by construction — today that is `/api/mobile/*`. There
+ * the token is always validated against PROD SSO, so a staging token simply fails the profile fetch;
+ * what the flag drops is only the refusal to serve a user whose row happens to be stamped `stag`.
+ * Those rows are legacy (the schema backfilled every pre-existing user to staging), and rejecting
+ * them would lock long-standing customers out of the mobile app for a reason that has nothing to do
+ * with them. It is not a widening of access: the identity served is still the one prod SSO just
+ * verified, and `upsertFromSso` never rewrites `autonomousEnv`, so the user's web experience is
+ * untouched.
+ */
+export async function authenticateAccessToken(
+ token: string,
+ autonomousEnv: AutonomousEnvironment = 'prod',
+ { enforceEnv = true }: { enforceEnv?: boolean } = {},
+): Promise<AuthUser> {
+ const profile = await fetchSsoProfile(token, autonomousEnv)
+ const metadata = accessTokenMetadata(token)
+ const email = normalizeUserEmail(profile.email)
+ if (!email) throw new SsoAuthError('SSO profile service returned an invalid profile', 'AUTH_SERVICE_UNAVAILABLE')
+
+ // Email is the account identity across Autonomous planes. Production may additionally claim the
+ // deterministic provisional row created when an SDS device connected before its owner's first login.
+ const byEmail = await userService.findByEmail(email)
+ const byProdExternal = !byEmail && autonomousEnv === 'prod'
+ ? await userService.findByExternal(profile.id)
+ : null
+ const provisional = !!byProdExternal && isProvisionalUserEmail(byProdExternal.email)
+ const existing = byEmail ?? (provisional ? byProdExternal : null)
+
+ if (enforceEnv && !existing && autonomousEnv === 'stag') {
+ throw new SsoAuthError('Staging access is not enabled for this user', 'AUTONOMOUS_ENV_NOT_ALLOWED', 'prod')
+ }
+ if (enforceEnv && existing && !provisional) {
+ const requiredEnv = storedAutonomousEnvironment(existing.autonomousEnv)
+ if (requiredEnv !== autonomousEnv) {
+ throw new SsoAuthError('Sign in through the configured Autonomous environment', 'AUTONOMOUS_ENV_MISMATCH', requiredEnv)
+ }
+ }
+ const user = await userService.upsertFromSso({
+ externalId: profile.id,
+ email,
+ autonomousEnv,
+ ...metadata,
+ })
+ return { sub: user.id, email: user.email, role: user.role, autonomousEnv }
+}
diff --git a/backend/src/lib/stt.ts b/backend/src/lib/stt.ts
new file mode 100644
index 000000000..184856847
--- /dev/null
+++ b/backend/src/lib/stt.ts
@@ -0,0 +1,27 @@
+import { env } from '../config/env.js'
+import { transcribe as deepgramTranscribe } from './deepgram.js'
+// Re-exported so the transport layer gates on the same list the provider enforces, without
+// importing a provider module directly.
+export { VOICE_LANGS, normalizeLang, type VoiceLang } from './deepgram.js'
+import { transcribe as geminiTranscribe } from './gemini.js'
+
+// Speech-to-text provider dispatch. The device sends raw linear16/mono PCM (8 or 16 kHz — it records
+// at 8 kHz to halve the upload over its flaky WiFi); the concrete provider is selected by
+// VOICE_PROVIDER so the voice endpoint stays provider-agnostic.
+
+/** Hard cap on one utterance's PCM — ~10 min @ 16k or ~20 min @ 8k (the device records at 8k, so this
+ * covers a long Overview ramble). Callers buffer up to this and drop the rest rather than growing
+ * unbounded on a device that never sends its end frame. */
+export const MAX_PCM = 20 * 1024 * 1024
+
+/** Transcribe raw linear16/mono PCM at `sampleRate` Hz in `lang` (see VOICE_LANGS) using the configured
+ * provider. Gemini auto-detects, so it ignores `lang`; Deepgram pins to it. */
+export async function transcribe(pcm: Buffer, sampleRate = 16000, lang = 'en'): Promise<string> {
+ switch (env.VOICE_PROVIDER) {
+ case 'gemini':
+ return geminiTranscribe(pcm, sampleRate)
+ case 'deepgram':
+ default:
+ return deepgramTranscribe(pcm, sampleRate, lang)
+ }
+}
diff --git a/backend/src/lib/subdomainProxy.ts b/backend/src/lib/subdomainProxy.ts
new file mode 100644
index 000000000..489c896e1
--- /dev/null
+++ b/backend/src/lib/subdomainProxy.ts
@@ -0,0 +1,168 @@
+import http from 'http'
+import type { IncomingMessage, ServerResponse } from 'http'
+import type { Socket } from 'net'
+import type { Duplex } from 'stream'
+import httpProxy from 'http-proxy'
+import { env } from '../config/env.js'
+import { prisma } from './prisma.js'
+import { getCachedAppAgent, setCachedAppAgent } from './appTargetCache.js'
+import { getAppInstance, getMeshEndpoint, setMeshEndpoint } from './bus.js'
+import { INSTANCE_ID, MESH_PORT, MESH_ENDPOINT } from './instance.js'
+import { tunnelHttp, tunnelWs } from './appTunnel.js'
+import { logger } from '../utils/logger.js'
+import { ensureMachineReady, MachineWakeError } from './machineLifecycle.js'
+
+// Filled alongside the positive subdomain cache. A hot public app should not need a second Mongo
+// Machine lookup on every request just to recover the managerId needed for cold-start.
+const managerByAgentId = new Map<string, string>()
+
+/**
+ * PUBLIC subdomain reverse-proxy (its own :PORT_APP_PROXY listener). Routing = the SUBDOMAIN from the
+ * Host header (NO api key — public app traffic). `[sub].<APP_DOMAIN_SUFFIX>` → the `subdomains` record →
+ * owning machineId → tunnelled over that agent's manager socket to the container app (see lib/appTunnel.ts).
+ *
+ * Phase 2 mesh: if this instance does NOT hold the agent's app manager-socket, the request is forwarded
+ * over an internal mesh connection to the instance that does (agent:{machineId}:appinst → inst:{id}:mesh),
+ * so the data path is a direct backpressured socket instead of a Redis relay. Falls back to the Redis
+ * tunnel (appTunnel redis-mode) when affinity/endpoint is unknown.
+ */
+
+/** Strip APP_DOMAIN_SUFFIX from a Host header to get the subdomain label. */
+export function hostToSubdomain(host: string | undefined): string | undefined {
+ if (!host) return undefined
+ const h = host.split(':')[0].toLowerCase() // drop any port
+ const suffix = env.APP_DOMAIN_SUFFIX.toLowerCase()
+ if (h.endsWith(suffix) && h.length > suffix.length) return h.slice(0, -suffix.length)
+ return undefined
+}
+
+/** subdomain → owning machineId (the tunnel routes app traffic by machineId), or undefined if unknown. */
+export async function agentForSubdomain(subdomain: string): Promise<string | undefined> {
+ const cached = getCachedAppAgent(subdomain)
+ if (cached !== undefined) return cached ?? undefined // string = hit; null = cached-missing → NO_APP, no DB
+ const record = await prisma.subdomain.findUnique({ where: { subdomain } })
+ setCachedAppAgent(subdomain, record?.machineId ?? null) // cache positive OR negative (unknown subdomain)
+ if (record) managerByAgentId.set(record.machineId, record.managerId)
+ return record?.machineId
+}
+
+// Forward proxy to a peer instance's mesh endpoint (direct socket, native backpressure — no Redis).
+const meshProxy = httpProxy.createProxyServer({ ws: true, xfwd: true })
+meshProxy.on('error', (err: Error, _req: IncomingMessage, res: ServerResponse | Socket) => {
+ logger.warn('mesh forward error', { error: err.message })
+ if (res instanceof http.ServerResponse) { if (!res.headersSent) res.writeHead(502); res.end('mesh unreachable') }
+ else { try { res.destroy() } catch { /* ignore */ } }
+})
+
+function denyHttp(res: ServerResponse, status: number, code: string, message: string): void {
+ res.writeHead(status, { 'content-type': 'application/json' })
+ res.end(JSON.stringify({ success: false, error: { code, message } }))
+}
+
+function denyWs(socket: Duplex, status: number, reason: string): void {
+ try {
+ socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`)
+ } catch { /* ignore */ }
+ socket.destroy()
+}
+
+async function wakeApp(machineId: string, subdomain: string): Promise<void> {
+ // Billing state can change while a subdomain target stays cached. Re-read the binding before every
+ // cold-start so a just-suspended machine cannot be woken through an old app route.
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt || binding.billingStatus === 'pending' || binding.billingStatus === 'suspended' || !binding.managerId) {
+ throw new Error('machine binding unavailable')
+ }
+ managerByAgentId.set(machineId, binding.managerId)
+ await ensureMachineReady(binding, { subdomain })
+}
+
+/**
+ * Resolve the mesh endpoint of the instance that holds this agent's app socket, IF it's a DIFFERENT
+ * instance and mesh is enabled. undefined ⇒ handle locally / via Redis tunnel here.
+ */
+async function peerMeshFor(machineId: string): Promise<string | undefined> {
+ if (!env.MESH_ENABLED) return undefined
+ const inst = await getAppInstance(machineId)
+ if (!inst || inst === INSTANCE_ID) return undefined
+ const endpoint = await getMeshEndpoint(inst)
+ return endpoint ?? undefined
+}
+
+// allowForward=false on the mesh listener → a forwarded request handles here (this instance owns the
+// socket), never bounces again.
+function handleAppRequest(req: IncomingMessage, res: ServerResponse, allowForward: boolean): void {
+ const sub = hostToSubdomain(req.headers.host)
+ if (!sub) return denyHttp(res, 400, 'NO_SUBDOMAIN', 'Unknown host')
+ void (async () => {
+ const machineId = await agentForSubdomain(sub)
+ if (!machineId) return denyHttp(res, 404, 'NO_APP', 'Unknown subdomain')
+ try {
+ await wakeApp(machineId, sub)
+ } catch (err) {
+ const timeout = err instanceof MachineWakeError && err.code === 'MACHINE_START_TIMEOUT'
+ return denyHttp(res, timeout ? 504 : 503, timeout ? 'MACHINE_START_TIMEOUT' : 'MACHINE_START_FAILED', timeout ? 'Machine start timed out' : 'Machine could not be started')
+ }
+ if (allowForward) {
+ const peer = await peerMeshFor(machineId)
+ if (peer) { meshProxy.web(req, res, { target: `http://${peer}` }); return }
+ }
+ await tunnelHttp(req, res, machineId, sub)
+ })().catch((err) => {
+ logger.error('app-proxy request failed', err)
+ if (!res.headersSent) denyHttp(res, 500, 'PROXY_ERROR', 'proxy error')
+ else res.end()
+ })
+}
+
+function handleAppUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, allowForward: boolean): void {
+ const sub = hostToSubdomain(req.headers.host)
+ if (!sub) { socket.destroy(); return }
+ void (async () => {
+ const machineId = await agentForSubdomain(sub)
+ if (!machineId) { socket.destroy(); return }
+ try {
+ await wakeApp(machineId, sub)
+ } catch (err) {
+ const timeout = err instanceof MachineWakeError && err.code === 'MACHINE_START_TIMEOUT'
+ denyWs(socket, timeout ? 504 : 503, timeout ? 'Gateway Timeout' : 'Service Unavailable')
+ return
+ }
+ if (allowForward) {
+ const peer = await peerMeshFor(machineId)
+ if (peer) { meshProxy.ws(req, socket as Socket, head, { target: `http://${peer}` }); return }
+ }
+ await tunnelWs(req, socket, head, machineId, sub)
+ })().catch((err) => {
+ logger.error('app-proxy upgrade failed', err)
+ socket.destroy()
+ })
+}
+
+/** Start the dedicated public app-proxy on PORT_APP_PROXY. Returns the server for shutdown. */
+export function startSubdomainProxy(): http.Server {
+ const server = http.createServer((req, res) => handleAppRequest(req, res, true))
+ server.on('upgrade', (req, socket, head) => handleAppUpgrade(req, socket, head, true))
+ server.listen(env.PORT_APP_PROXY, '0.0.0.0', () => {
+ logger.info(`backend subdomain app-proxy listening on ${env.PORT_APP_PROXY}`, { suffix: env.APP_DOMAIN_SUFFIX })
+ })
+ return server
+}
+
+/**
+ * Start the INTERNAL mesh listener (Phase 2). A peer instance forwards a public app request here when
+ * THIS instance holds the agent's app socket; we handle it locally (allowForward=false). Advertises this
+ * instance's endpoint in Redis so peers can find it. No-op when MESH_ENABLED is false.
+ */
+export function startMeshProxy(): http.Server | undefined {
+ if (!env.MESH_ENABLED) return undefined
+ const server = http.createServer((req, res) => handleAppRequest(req, res, false))
+ server.on('upgrade', (req, socket, head) => handleAppUpgrade(req, socket, head, false))
+ server.listen(MESH_PORT, '0.0.0.0', () => {
+ logger.info(`backend mesh listener on ${MESH_PORT}`, { instance: INSTANCE_ID, endpoint: MESH_ENDPOINT })
+ })
+ const advertise = (): void => { void setMeshEndpoint(INSTANCE_ID, MESH_ENDPOINT, 30) }
+ advertise()
+ setInterval(advertise, 15_000).unref?.()
+ return server
+}
diff --git a/backend/src/lib/terminalBinary.test.ts b/backend/src/lib/terminalBinary.test.ts
new file mode 100644
index 000000000..46df7eaec
--- /dev/null
+++ b/backend/src/lib/terminalBinary.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import {
+ decodeTerminalHop,
+ encodeTerminalHop,
+ parseTerminalClientFrame,
+ TERMINAL_BINARY_CLIENT_UP_KINDS,
+ TerminalBinaryKind,
+ TerminalHopDirection,
+} from './terminalBinary.js'
+
+function opaque(kind: TerminalBinaryKind): Buffer {
+ const out = Buffer.alloc(36)
+ out.write('HTRM')
+ out[4] = 3
+ out[5] = kind
+ out.writeUInt32BE(16, 16)
+ return out
+}
+
+describe('opaque terminal binary relay codec', () => {
+ it('routes a valid encrypted client frame without changing it', () => {
+ const frame = opaque(TerminalBinaryKind.output)
+ const packet = encodeTerminalHop(TerminalHopDirection.up, '00112233-4455-6677-8899-aabbccddeeff', frame)!
+ expect(decodeTerminalHop(packet)).toMatchObject({
+ direction: TerminalHopDirection.up,
+ connId: '00112233-4455-6677-8899-aabbccddeeff',
+ kind: TerminalBinaryKind.output,
+ clientFrame: frame,
+ })
+ })
+
+ it('routes an encrypted sync frame without changing it', () => {
+ const frame = opaque(TerminalBinaryKind.sync)
+ const packet = encodeTerminalHop(TerminalHopDirection.up, '00112233-4455-6677-8899-aabbccddeeff', frame)!
+ expect(decodeTerminalHop(packet)).toMatchObject({
+ direction: TerminalHopDirection.up,
+ connId: '00112233-4455-6677-8899-aabbccddeeff',
+ kind: TerminalBinaryKind.sync,
+ clientFrame: frame,
+ })
+ })
+
+ it('rejects malformed lengths and unsupported kinds', () => {
+ const frame = opaque(TerminalBinaryKind.input)
+ frame.writeUInt32BE(15, 16)
+ expect(parseTerminalClientFrame(frame)).toBeNull()
+ frame.writeUInt32BE(16, 16); frame[5] = 9
+ expect(parseTerminalClientFrame(frame)).toBeNull()
+ })
+
+ // Regression for a real bug: this file's TerminalBinaryKind used to lag the CLI's copy by three
+ // kinds, so a paste/imagePaste/pasteFile frame relayed toward a remote machine parsed as null and
+ // hub.ts's sendTerminalDown silently no-op'd on it — no error, nothing ever arrived.
+ it('routes paste/imagePaste/pasteFile frames, mirroring the CLI kinds added for remote copy-paste', () => {
+ for (const kind of [TerminalBinaryKind.paste, TerminalBinaryKind.imagePaste, TerminalBinaryKind.pasteFile]) {
+ const frame = opaque(kind)
+ const packet = encodeTerminalHop(TerminalHopDirection.down, '00112233-4455-6677-8899-aabbccddeeff', frame)!
+ expect(packet).not.toBeNull()
+ expect(decodeTerminalHop(packet)).toMatchObject({
+ direction: TerminalHopDirection.down,
+ connId: '00112233-4455-6677-8899-aabbccddeeff',
+ kind,
+ clientFrame: frame,
+ })
+ }
+ })
+
+ // Regression: webWs.ts's own binary handlers gate on this set with a hardcoded check independent
+ // of the kind enum/parser above — paste/imagePaste/pasteFile landed in both of those but were never
+ // added here, so every such frame from a web/relay client was rejected as TERMINAL_BINARY_REJECTED
+ // (freezing the whole pane) even though the wire-level parsing above was already correct.
+ it('accepts every client-originated kind a web/relay connection may send up, and no others', () => {
+ expect(TERMINAL_BINARY_CLIENT_UP_KINDS.has(TerminalBinaryKind.input)).toBe(true)
+ expect(TERMINAL_BINARY_CLIENT_UP_KINDS.has(TerminalBinaryKind.paste)).toBe(true)
+ expect(TERMINAL_BINARY_CLIENT_UP_KINDS.has(TerminalBinaryKind.imagePaste)).toBe(true)
+ expect(TERMINAL_BINARY_CLIENT_UP_KINDS.has(TerminalBinaryKind.pasteFile)).toBe(true)
+ expect(TERMINAL_BINARY_CLIENT_UP_KINDS.has(TerminalBinaryKind.output)).toBe(false)
+ expect(TERMINAL_BINARY_CLIENT_UP_KINDS.has(TerminalBinaryKind.keyframe)).toBe(false)
+ expect(TERMINAL_BINARY_CLIENT_UP_KINDS.has(TerminalBinaryKind.sync)).toBe(false)
+ })
+})
diff --git a/backend/src/lib/terminalBinary.ts b/backend/src/lib/terminalBinary.ts
new file mode 100644
index 000000000..52f834f00
--- /dev/null
+++ b/backend/src/lib/terminalBinary.ts
@@ -0,0 +1,97 @@
+import { Buffer } from 'node:buffer'
+
+export const TERMINAL_BINARY_VERSION = 3
+export const TERMINAL_BINARY_HEADER_BYTES = 20
+export const TERMINAL_HOP_HEADER_BYTES = 24
+export const TERMINAL_BINARY_MAX_BYTES = 512 * 1024
+
+export const enum TerminalBinaryKind {
+ input = 1,
+ output = 2,
+ keyframe = 3,
+ sync = 4,
+ // Mirrors the CLI's own copy in autonomous-harness/cli/src/lib/terminalBinary.ts — keep the two
+ // in step. Without these three, a paste/imagePaste/pasteFile frame silently fails to relay: this
+ // file's `parseTerminalClientFrame` rejects any other kind, and hub.ts's `sendTerminalDown` just
+ // no-ops on a null `encodeTerminalHop` result, so the frame vanishes with no error anywhere.
+ paste = 5,
+ imagePaste = 6,
+ pasteFile = 7,
+}
+
+export const enum TerminalHopDirection {
+ down = 1,
+ up = 2,
+}
+
+/** Kinds a web/relay-client connection may legitimately send UPWARD (client → adapter) — never
+ * `output`/`keyframe`/`sync`, which only ever flow the other way. `webWs.ts`'s per-connection binary
+ * handlers gate on this directly (their own hardcoded check, independent of `parseTerminalClientFrame`
+ * above, which just validates wire shape and accepts every kind); missing `paste`/`imagePaste`/
+ * `pasteFile` here left every such frame rejected as `TERMINAL_BINARY_REJECTED` even after those kinds
+ * were added to the enum and to `parseTerminalClientFrame` — the same silent-drop shape as the
+ * `TERMINAL_DOWN_TYPES`/`TERMINAL_UP_TYPES` gap those two already got fixed for. */
+export const TERMINAL_BINARY_CLIENT_UP_KINDS: ReadonlySet<TerminalBinaryKind> = new Set([
+ TerminalBinaryKind.input,
+ TerminalBinaryKind.paste,
+ TerminalBinaryKind.imagePaste,
+ TerminalBinaryKind.pasteFile,
+])
+
+const CLIENT_MAGIC = Buffer.from('HTRM')
+const HOP_MAGIC = Buffer.from('HTRH')
+
+function uuidBytes(id: string): Buffer | null {
+ const hex = id.replaceAll('-', '')
+ return /^[0-9a-fA-F]{32}$/.test(hex) ? Buffer.from(hex, 'hex') : null
+}
+
+function uuidString(bytes: Uint8Array): string {
+ const hex = Buffer.from(bytes).toString('hex')
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+export function parseTerminalClientFrame(raw: Uint8Array): { kind: TerminalBinaryKind; bytes: Buffer } | null {
+ const bytes = Buffer.from(raw)
+ if (bytes.length < TERMINAL_BINARY_HEADER_BYTES + 16 || bytes.length > TERMINAL_BINARY_MAX_BYTES) return null
+ if (!bytes.subarray(0, 4).equals(CLIENT_MAGIC) || bytes[4] !== TERMINAL_BINARY_VERSION
+ || (bytes[5] !== TerminalBinaryKind.input && bytes[5] !== TerminalBinaryKind.output
+ && bytes[5] !== TerminalBinaryKind.keyframe && bytes[5] !== TerminalBinaryKind.sync
+ && bytes[5] !== TerminalBinaryKind.paste && bytes[5] !== TerminalBinaryKind.imagePaste
+ && bytes[5] !== TerminalBinaryKind.pasteFile)
+ || bytes[7] !== 0) return null
+ const ciphertextLength = bytes.readUInt32BE(16)
+ if (ciphertextLength < 16 || ciphertextLength !== bytes.length - TERMINAL_BINARY_HEADER_BYTES) return null
+ return { kind: bytes[5], bytes }
+}
+
+export function encodeTerminalHop(direction: TerminalHopDirection, connId: string, clientFrame: Uint8Array): Buffer | null {
+ const id = uuidBytes(connId)
+ const parsed = parseTerminalClientFrame(clientFrame)
+ if (!id || !parsed || (direction !== TerminalHopDirection.down && direction !== TerminalHopDirection.up)) return null
+ const out = Buffer.allocUnsafe(TERMINAL_HOP_HEADER_BYTES + parsed.bytes.length)
+ HOP_MAGIC.copy(out, 0)
+ out[4] = TERMINAL_BINARY_VERSION
+ out[5] = direction
+ out[6] = 0
+ out[7] = 0
+ id.copy(out, 8)
+ parsed.bytes.copy(out, TERMINAL_HOP_HEADER_BYTES)
+ return out
+}
+
+export function decodeTerminalHop(raw: Uint8Array): { direction: TerminalHopDirection; connId: string; clientFrame: Buffer; kind: TerminalBinaryKind } | null {
+ const bytes = Buffer.from(raw)
+ if (bytes.length < TERMINAL_HOP_HEADER_BYTES + TERMINAL_BINARY_HEADER_BYTES + 16
+ || !bytes.subarray(0, 4).equals(HOP_MAGIC) || bytes[4] !== TERMINAL_BINARY_VERSION
+ || (bytes[5] !== TerminalHopDirection.down && bytes[5] !== TerminalHopDirection.up)
+ || bytes[6] !== 0 || bytes[7] !== 0) return null
+ const parsed = parseTerminalClientFrame(bytes.subarray(TERMINAL_HOP_HEADER_BYTES))
+ if (!parsed) return null
+ return {
+ direction: bytes[5],
+ connId: uuidString(bytes.subarray(8, 24)),
+ clientFrame: parsed.bytes,
+ kind: parsed.kind,
+ }
+}
diff --git a/backend/src/lib/terminalRelay.test.ts b/backend/src/lib/terminalRelay.test.ts
new file mode 100644
index 000000000..c35c559cc
--- /dev/null
+++ b/backend/src/lib/terminalRelay.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+import {
+ isEncryptedTerminalFrame,
+ TERMINAL_DOWN_TYPES,
+ TERMINAL_UP_TYPES,
+ terminalFrameBytes,
+ terminalFrameNeedsWake,
+ TerminalRateGuard,
+} from './terminalRelay.js'
+
+describe('terminal opaque relay contract', () => {
+ it('keeps the expected direction allowlists disjoint', () => {
+ expect([...TERMINAL_DOWN_TYPES].sort()).toEqual([
+ 'terminal_ack', 'terminal_alive', 'terminal_capabilities', 'terminal_chunked_upload_begin',
+ 'terminal_chunked_upload_cancel', 'terminal_close', 'terminal_input', 'terminal_open',
+ 'terminal_resize', 'terminal_resync', 'terminal_scroll',
+ ])
+ expect([...TERMINAL_UP_TYPES].sort()).toEqual([
+ 'terminal_capabilities_result', 'terminal_chunked_upload_begin_result',
+ 'terminal_chunked_upload_progress', 'terminal_closed', 'terminal_error',
+ 'terminal_keyframe', 'terminal_output', 'terminal_paste_file_result',
+ 'terminal_paste_image_result', 'terminal_ready',
+ ])
+ expect([...TERMINAL_DOWN_TYPES].some((type) => TERMINAL_UP_TYPES.has(type))).toBe(false)
+ expect(TERMINAL_DOWN_TYPES.has('terminal_future_unreviewed')).toBe(false)
+ expect(TERMINAL_UP_TYPES.has('terminal_future_unreviewed')).toBe(false)
+ })
+
+ it('accepts only structurally valid ciphertext without opening it', () => {
+ const frame = {
+ type: 'terminal_input',
+ payload: { __e2e: { v: 1, k: 'p', n: 7, ct: 'opaque-ciphertext' } },
+ }
+ expect(isEncryptedTerminalFrame(frame)).toBe(true)
+ expect(terminalFrameBytes(frame)).toBe(Buffer.byteLength(JSON.stringify(frame)))
+ expect(isEncryptedTerminalFrame({ type: 'terminal_input', payload: { data: 'plaintext' } })).toBe(false)
+ expect(isEncryptedTerminalFrame({ type: 'terminal_input', payload: { __e2e: null } })).toBe(false)
+ expect(isEncryptedTerminalFrame({ type: 'terminal_input', payload: { __e2e: { v: 1, k: 'p', n: '7', ct: 'x' } } })).toBe(false)
+ })
+
+ it('rate-limits per type in a bounded one-minute window', () => {
+ let now = 1_000
+ const guard = new TerminalRateGuard(() => now)
+ for (let i = 0; i < 60; i++) expect(guard.allow('terminal_open', 100)).toBe(true)
+ expect(guard.allow('terminal_open', 100)).toBe(false)
+ expect(guard.allow('terminal_input', 100)).toBe(true)
+ now += 60_000
+ expect(guard.allow('terminal_open', 100)).toBe(true)
+ })
+
+ it('lets a busy renderer ack for a whole window without losing its stream', () => {
+ let now = 1_000
+ const guard = new TerminalRateGuard(() => now)
+ // What the desktop client actually emits under sustained output: one ack per 16ms render
+ // window for a full minute. Every one of them has to pass — a rejected ack is reported as
+ // transport loss, so tripping this limit kills the pane rather than throttling it.
+ const acksPerMinute = Math.ceil(60_000 / 16)
+ for (let i = 0; i < acksPerMinute; i++) {
+ expect(guard.allow('terminal_ack', 120)).toBe(true)
+ }
+ // Heartbeats and user-driven frames keep the tighter, unrelated budget.
+ for (let i = 0; i < 1_200; i++) expect(guard.allow('terminal_alive', 100)).toBe(true)
+ expect(guard.allow('terminal_alive', 100)).toBe(false)
+ expect(guard.allow('terminal_ack', 120)).toBe(true)
+ })
+
+ it('wakes only for terminal_open, never per input/mouse/resize/ack frame', () => {
+ expect(terminalFrameNeedsWake('terminal_open')).toBe(true)
+ for (const type of TERMINAL_DOWN_TYPES) {
+ if (type !== 'terminal_open') expect(terminalFrameNeedsWake(type)).toBe(false)
+ }
+ })
+})
diff --git a/backend/src/lib/terminalRelay.ts b/backend/src/lib/terminalRelay.ts
new file mode 100644
index 000000000..38e92ad3a
--- /dev/null
+++ b/backend/src/lib/terminalRelay.ts
@@ -0,0 +1,80 @@
+import type { Frame } from './tunnel.js'
+
+export const TERMINAL_ENVELOPE_MAX_BYTES = 512 * 1024
+export const TERMINAL_DOWN_TYPES = new Set([
+ 'terminal_capabilities', 'terminal_open', 'terminal_alive', 'terminal_ack',
+ 'terminal_input', 'terminal_resize', 'terminal_resync', 'terminal_close', 'terminal_scroll',
+ 'terminal_chunked_upload_begin', 'terminal_chunked_upload_cancel',
+])
+
+export const TERMINAL_UP_TYPES = new Set([
+ 'terminal_capabilities_result', 'terminal_ready', 'terminal_keyframe',
+ 'terminal_output', 'terminal_closed', 'terminal_error', 'terminal_paste_image_result',
+ 'terminal_paste_file_result', 'terminal_chunked_upload_begin_result',
+ 'terminal_chunked_upload_progress',
+])
+
+export function terminalFrameBytes(frame: Frame): number {
+ return Buffer.byteLength(JSON.stringify(frame), 'utf8')
+}
+
+export function terminalFrameNeedsWake(type: string): boolean {
+ return type === 'terminal_open'
+}
+
+/** Backend may inspect only enough envelope structure to fail closed; ciphertext remains opaque. */
+export function isEncryptedTerminalFrame(frame: Frame): boolean {
+ const payload = frame.payload
+ if (!payload || typeof payload !== 'object') return false
+ const envelope = (payload as { __e2e?: unknown }).__e2e
+ if (!envelope || typeof envelope !== 'object') return false
+ const value = envelope as { v?: unknown; n?: unknown; k?: unknown; ct?: unknown }
+ return value.v === 1
+ && Number.isSafeInteger(value.n)
+ && (value.k === 'p' || value.k === 'g')
+ && typeof value.ct === 'string'
+}
+
+interface Bucket {
+ startedAt: number
+ frames: number
+ bytes: number
+}
+
+function limits(type: string): { frames: number; bytes: number } {
+ if (type === 'terminal_input') return { frames: 15_000, bytes: 64 * 1024 * 1024 }
+ if (type === 'terminal_output') return { frames: 20_000, bytes: 128 * 1024 * 1024 }
+ if (type === 'terminal_sync') return { frames: 1_200, bytes: 8 * 1024 * 1024 }
+ // Acks are renderer flow control, not user actions. The client emits one per 16ms render window
+ // (plus one per 64 KiB rendered), so roughly 3,750/min while output is flowing. Sharing the
+ // human-paced 1,200 below meant a pane streaming a build log exhausted the window in about 19
+ // seconds, and a rejected ack is not dropped quietly — it answers TERMINAL_FRAME_REJECTED, which
+ // the client reads as transport loss and freezes the pane mid-output. Sized ~2.7x the client's
+ // own ceiling; the byte cap still bounds actual volume.
+ if (type === 'terminal_ack') return { frames: 10_000, bytes: 8 * 1024 * 1024 }
+ if (type === 'terminal_alive' || type === 'terminal_resize' || type === 'terminal_scroll') {
+ return { frames: 1_200, bytes: 8 * 1024 * 1024 }
+ }
+ if (type === 'terminal_open' || type === 'terminal_capabilities') return { frames: 60, bytes: 4 * 1024 * 1024 }
+ return { frames: 600, bytes: 64 * 1024 * 1024 }
+}
+
+/** Socket-local one-minute guard. It never stores terminal payloads and has no cross-request persistence. */
+export class TerminalRateGuard {
+ private readonly buckets = new Map<string, Bucket>()
+ constructor(private readonly now: () => number = () => Date.now()) {}
+
+ allow(type: string, bytes: number): boolean {
+ const timestamp = this.now()
+ let bucket = this.buckets.get(type)
+ if (!bucket || timestamp - bucket.startedAt >= 60_000) {
+ bucket = { startedAt: timestamp, frames: 0, bytes: 0 }
+ this.buckets.set(type, bucket)
+ }
+ const limit = limits(type)
+ if (bucket.frames + 1 > limit.frames || bucket.bytes + bytes > limit.bytes) return false
+ bucket.frames++
+ bucket.bytes += bytes
+ return true
+ }
+}
diff --git a/backend/src/lib/terminalRouting.test.ts b/backend/src/lib/terminalRouting.test.ts
new file mode 100644
index 000000000..7daefecb2
--- /dev/null
+++ b/backend/src/lib/terminalRouting.test.ts
@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { WebSocket } from 'ws'
+import { encodeTerminalHop, TerminalBinaryKind, TerminalHopDirection } from './terminalBinary.js'
+
+const bus = vi.hoisted(() => ({
+ publishDown: vi.fn(async () => 1),
+}))
+
+vi.mock('./bus.js', () => ({
+ subscribeUp: async () => () => undefined,
+ subscribeTerminalUp: async () => () => undefined,
+ publishUp: async () => 1,
+ publishDown: bus.publishDown,
+ publishTerminalDown: async () => 1,
+ setAgentClientCount: async () => undefined,
+ getAgentClientTotals: async () => ({ ui: 0, commander: 0, commanderActive: 0 }),
+ bumpCommanderJoinGeneration: async () => 1,
+ getCommanderJoinGeneration: async () => 1,
+}))
+
+const { attachHubClient, deliverTerminalUpLocal, deliverUpLocal } = await import('./hub.js')
+
+describe('terminal target routing', () => {
+ const attached: Array<ReturnType<typeof attachHubClient>> = []
+ const socket = (out: unknown[]): WebSocket => ({
+ readyState: 1,
+ send: (data: unknown) => { out.push(data) },
+ on: () => undefined,
+ } as unknown as WebSocket)
+
+ beforeEach(() => {
+ while (attached.length) attached.pop()!.detach()
+ bus.publishDown.mockClear()
+ })
+
+ it('delivers ciphertext only to the addressed web connection', () => {
+ const machineId = `terminal-target-${Date.now()}`
+ const webSent: string[] = []
+ const commanderSent: string[] = []
+ const web = attachHubClient(socket(webSent), machineId, 'web')
+ const commander = attachHubClient(socket(commanderSent), machineId, 'commander')
+ attached.push(web, commander)
+
+ deliverUpLocal(machineId, {
+ targetConnId: web.connId,
+ targetKind: 'web',
+ webEligible: true,
+ commanderEligible: false,
+ frame: {
+ type: 'terminal_output',
+ payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'opaque' } },
+ },
+ })
+
+ expect(webSent).toHaveLength(1)
+ expect(webSent[0]).toContain('terminal_output')
+ expect(commanderSent).toHaveLength(0)
+ })
+
+ it('delivers an opaque binary frame only to its addressed web connection', () => {
+ const machineId = `terminal-binary-target-${Date.now()}`
+ const webSent: unknown[] = []
+ const otherSent: unknown[] = []
+ const web = attachHubClient(socket(webSent), machineId, 'web')
+ const other = attachHubClient(socket(otherSent), machineId, 'web')
+ attached.push(web, other)
+ const frame = Buffer.alloc(36)
+ frame.write('HTRM')
+ frame[4] = 3
+ frame[5] = TerminalBinaryKind.output
+ frame.writeUInt32BE(16, 16)
+ const packet = encodeTerminalHop(
+ TerminalHopDirection.up,
+ web.connId,
+ frame,
+ )!
+
+ deliverTerminalUpLocal(machineId, packet)
+
+ expect(Buffer.from(webSent[0] as Uint8Array)).toEqual(frame)
+ expect(otherSent).toHaveLength(0)
+ })
+
+ it('notifies Harness of the exact connId before a web route detaches', async () => {
+ const machineId = `terminal-disconnect-${Date.now()}`
+ const web = attachHubClient(socket([]), machineId, 'web')
+ attached.push(web)
+
+ web.detach()
+
+ await vi.waitFor(() => {
+ expect(bus.publishDown).toHaveBeenCalledWith(machineId, {
+ connId: web.connId,
+ frame: { type: '__client_disconnected', payload: {} },
+ })
+ })
+ attached.pop()
+ })
+})
diff --git a/backend/src/lib/tunnel.ts b/backend/src/lib/tunnel.ts
new file mode 100644
index 000000000..1b95229b2
--- /dev/null
+++ b/backend/src/lib/tunnel.ts
@@ -0,0 +1,186 @@
+/**
+ * Tunnel envelope types for the inverted WS transport.
+ *
+ * The inverted chain is: node ─dial▶ manager ─dial▶ backend; web/device ─dial▶ backend.
+ * The inner "frame" is the existing client/server WS message ({ type, dbSessionId?, payload? }) —
+ * opaque at the transport layer. These envelopes wrap it as it is tunnelled up/down the chain and
+ * as it crosses backend instances via Redis (see lib/bus.ts).
+ *
+ * Directions:
+ * - up = node → manager → backend → clients (brain events, acks)
+ * - down = clients → backend → manager → node (chat messages, control)
+ */
+
+/** The inner WS message (existing ClientEvent / BrainEvent shape). Opaque here. */
+export type Frame = Record<string, unknown>
+
+// ── Frames on the manager↔backend socket (multiplexed: many agents over one socket) ──────────────
+
+/** node/brain event travelling toward clients. `machineId` (= routing key, sha256(apiKey)[:32]) carried because the socket is multiplexed. */
+export interface UpEnvelope {
+ t: 'up'
+ machineId: string
+ /** origin client connId to skip when re-delivering (preserves broadcastToOthers). */
+ excludeConnId?: string
+ /** deliver to web/UI sockets (default true when absent). false = device-only (forwardToCommander). */
+ webEligible?: boolean
+ /** deliver to device/commander sockets (COMMANDER_FORWARD set, or curated commander frames). */
+ commanderEligible?: boolean
+ frame: Frame
+}
+
+/** client message travelling toward the node. */
+export interface DownEnvelope {
+ t: 'down'
+ machineId: string
+ /** originating client connId (so the node can tag its emitted events with excludeConnId). */
+ connId: string
+ frame: Frame
+}
+
+/** manager tells its backend a node connected/disconnected → backend (un)subscribes down:{machineId}.
+ * `app_register`/`app_unregister` are the app-proxy variant, sent on the APP-pool socket (or the control
+ * socket when no dedicated app pool) → backend (un)subscribes appdown:{machineId} on that socket. */
+export interface RegisterEnvelope {
+ t: 'register' | 'unregister' | 'app_register' | 'app_unregister'
+ machineId: string
+}
+
+/** manager identifies itself + advertises capacity on connect and on heartbeat. */
+export interface HelloEnvelope {
+ t: 'hello'
+ managerId: string
+ capacity?: number
+ nodeCount?: number
+ // The manager→backend pool's CONTROL socket sets this; the backend subscribes mgr:{managerId} only
+ // for control sockets, so provisioning isn't forwarded once per pool socket.
+ control?: boolean
+ // Set by the manager's dedicated APP-pool sockets (cosmetic/observability — routing is driven by the
+ // app_register frame + machineId, not this flag).
+ app?: boolean
+}
+
+export interface PingEnvelope {
+ t: 'ping'
+}
+
+/** backend→manager provisioning command over the manager socket (Phase 3; replaces control HTTP).
+ * `app_create`/`app_delete` register/remove a public app deployment (subdomain → node app port). */
+export interface ProvisionEnvelope {
+ t: 'provision'
+ requestId: string
+ cmd: 'create' | 'start' | 'stop' | 'destroy' | 'app_create' | 'app_delete'
+ payload: Record<string, unknown>
+}
+
+// ── App-proxy tunnel: transparent HTTP/WS reverse proxy for public app hosting, streamed over the
+// manager socket so the backend never needs the manager's address. Multiplexed by `streamId`
+// (one stream = one client connection). down = backend→manager; up = manager→backend.
+export interface AppReqEnvelope {
+ t: 'app_req'
+ streamId: string
+ subdomain: string
+ method: string
+ url: string
+ headers: Record<string, string | string[] | undefined>
+}
+export interface AppBodyEnvelope {
+ t: 'app_body' | 'app_res_body'
+ streamId: string
+ chunk?: string // base64
+ end?: boolean
+}
+export interface AppResEnvelope {
+ t: 'app_res'
+ streamId: string
+ status: number
+ headers: Record<string, string | string[] | undefined>
+}
+export interface AppWsOpenEnvelope {
+ t: 'app_ws_open'
+ streamId: string
+ subdomain: string
+ url: string
+ headers: Record<string, string | string[] | undefined>
+}
+export interface AppWsMsgEnvelope {
+ t: 'app_ws_msg'
+ streamId: string
+ data: string // base64
+ binary: boolean
+}
+export interface AppWsCloseEnvelope {
+ t: 'app_ws_close'
+ streamId: string
+ code?: number
+ ok?: boolean
+}
+export interface AppAbortEnvelope {
+ t: 'app_abort'
+ streamId: string
+ reason?: string
+}
+export type AppDownFrame = AppReqEnvelope | AppBodyEnvelope | AppWsOpenEnvelope | AppWsMsgEnvelope | AppWsCloseEnvelope | AppAbortEnvelope
+export type AppUpFrame = AppResEnvelope | AppBodyEnvelope | AppWsMsgEnvelope | AppWsCloseEnvelope | AppAbortEnvelope
+
+/** manager→backend provisioning result. */
+export interface ProvisionResultEnvelope {
+ t: 'provision_result'
+ requestId: string
+ ok: boolean
+ data?: unknown
+ error?: string
+}
+
+/** backend informs the node of its current client counts so it can gate event buffering/replay. */
+export interface ClientsEnvelope {
+ t: 'clients'
+ machineId: string
+ ui: number
+ commander: number
+}
+
+export type ManagerFrame =
+ | UpEnvelope
+ | DownEnvelope
+ | RegisterEnvelope
+ | HelloEnvelope
+ | PingEnvelope
+ | ClientsEnvelope
+ | ProvisionResultEnvelope // manager → backend (reply to a ProvisionEnvelope sent down)
+ | AppResEnvelope // app-proxy tunnel: manager → backend (response head/body/ws/abort), keyed by streamId
+ | AppBodyEnvelope
+ | AppWsMsgEnvelope
+ | AppWsCloseEnvelope
+ | AppAbortEnvelope
+
+// ── Frames on the node↔manager socket (single machine per socket: machineId implicit) ────────────────
+
+export type NodeUpFrame = Omit<UpEnvelope, 'machineId'>
+export type NodeDownFrame = Omit<DownEnvelope, 'machineId'>
+export type NodeFrame = NodeUpFrame | NodeDownFrame | ClientsEnvelope | PingEnvelope
+
+// ── Redis bus payloads (machineId is encoded in the channel name, not the body) ────────────────────
+
+export interface UpBusMsg {
+ excludeConnId?: string
+ webEligible?: boolean
+ commanderEligible?: boolean
+ // Deliver ONLY to the commander socket whose resolved deviceId matches (device-targeted push, e.g.
+ // `device_revoked`). Absent ⇒ normal per-machine fan-out.
+ targetDeviceId?: string
+ // Deliver ONLY to the client socket with this connId (adapter-targeted push: E2EE pairing/welcome
+ // and per-client RPC replies). Absent ⇒ normal per-machine fan-out.
+ targetConnId?: string
+ /** Optional kind constraint for connId-targeted traffic. Terminal streams are web/Desktop-only. */
+ targetKind?: 'web' | 'commander'
+ frame: Frame
+ // Publisher's PROCESS_ID — the origin instance already delivered to its local clients directly, so its
+ // own Redis loopback delivery is skipped (chat-up local fast-path). Absent on legacy/other publishers.
+ originPid?: string
+}
+
+export interface DownBusMsg {
+ connId: string
+ frame: Frame
+}
diff --git a/backend/src/lib/turnCredentials.test.ts b/backend/src/lib/turnCredentials.test.ts
new file mode 100644
index 000000000..1f6ff4e22
--- /dev/null
+++ b/backend/src/lib/turnCredentials.test.ts
@@ -0,0 +1,178 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const envMock = {
+ TERMINAL_P2P_TURN_KEY_ID: 'key-1',
+ TERMINAL_P2P_TURN_API_TOKEN: 'token-1',
+ TERMINAL_P2P_TURN_TTL_SECONDS: 7200,
+ TERMINAL_P2P_TURN_TIMEOUT_MS: 5000,
+}
+
+vi.mock('../config/env.js', () => ({ env: envMock }))
+
+const { resetTurnCredentialsForTest, turnCredentials, startTurnCredentialRefresh } =
+ await import('./turnCredentials.js')
+
+const TTL_MS = envMock.TERMINAL_P2P_TURN_TTL_SECONDS * 1000
+
+function iceResponse(username = 'u1', credential = 'c1'): Response {
+ return new Response(JSON.stringify({
+ iceServers: [
+ { urls: ['stun:stun.cloudflare.com:3478'] },
+ {
+ urls: [
+ 'turn:turn.cloudflare.com:3478?transport=udp',
+ 'turns:turn.cloudflare.com:443?transport=tcp',
+ ],
+ username,
+ credential,
+ },
+ ],
+ }), { status: 201, headers: { 'Content-Type': 'application/json' } })
+}
+
+/** Lets the queued microtasks behind the mocked fetch run before the next synchronous read. */
+const settle = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0))
+
+let clock = 1_000_000
+
+beforeEach(() => {
+ clock = 1_000_000
+ envMock.TERMINAL_P2P_TURN_KEY_ID = 'key-1'
+ envMock.TERMINAL_P2P_TURN_API_TOKEN = 'token-1'
+ resetTurnCredentialsForTest()
+})
+
+afterEach(() => {
+ resetTurnCredentialsForTest()
+ vi.clearAllMocks()
+})
+
+const now = (): number => clock
+
+describe('Cloudflare TURN credentials', () => {
+ it('mints once and then serves the snapshot synchronously', async () => {
+ const fetchImpl = vi.fn<typeof fetch>(async () => iceResponse())
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+
+ expect(fetchImpl).toHaveBeenCalledTimes(1)
+ const [url, init] = fetchImpl.mock.calls[0]!
+ expect(String(url)).toBe('https://rtc.live.cloudflare.com/v1/turn/keys/key-1/credentials/generate-ice-servers')
+ expect(init?.method).toBe('POST')
+ expect((init?.headers as Record<string, string>).Authorization).toBe('Bearer token-1')
+ expect(JSON.parse(String(init?.body))).toEqual({ ttl: 7200 })
+
+ const creds = turnCredentials({ now, fetchImpl })
+ expect(creds).toEqual({
+ urls: ['turn:turn.cloudflare.com:3478?transport=udp', 'turns:turn.cloudflare.com:443?transport=tcp'],
+ username: 'u1',
+ credential: 'c1',
+ })
+ // Repeated reads inside the ttl never touch the network — this is the whole point of the snapshot.
+ turnCredentials({ now, fetchImpl })
+ turnCredentials({ now, fetchImpl })
+ expect(fetchImpl).toHaveBeenCalledTimes(1)
+ })
+
+ it('keeps the stun-only entry out of the credential', async () => {
+ const fetchImpl = vi.fn<typeof fetch>(async () => iceResponse())
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+ expect(turnCredentials({ now, fetchImpl })!.urls.every((u) => u.startsWith('turn'))).toBe(true)
+ })
+
+ it('tops up in the background once past three quarters of the ttl, still serving the old one', async () => {
+ const fetchImpl = vi.fn<typeof fetch>(async () => iceResponse('u1', 'c1'))
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+
+ clock += TTL_MS * 0.5
+ expect(turnCredentials({ now, fetchImpl })!.credential).toBe('c1')
+ expect(fetchImpl).toHaveBeenCalledTimes(1)
+
+ fetchImpl.mockImplementation(async () => iceResponse('u2', 'c2'))
+ clock += TTL_MS * 0.3 // now 80% through, inside the refresh window
+ // The read still answers with the live credential rather than blocking on the refresh.
+ expect(turnCredentials({ now, fetchImpl })!.credential).toBe('c1')
+ await settle()
+ expect(fetchImpl).toHaveBeenCalledTimes(2)
+ expect(turnCredentials({ now, fetchImpl })!.credential).toBe('c2')
+ })
+
+ it('keeps serving a still-valid credential when Cloudflare starts failing', async () => {
+ const fetchImpl = vi.fn<typeof fetch>(async () => iceResponse())
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+
+ fetchImpl.mockImplementation(async () => new Response('nope', { status: 500 }))
+ clock += TTL_MS * 0.8
+ expect(turnCredentials({ now, fetchImpl })!.credential).toBe('c1')
+ await settle()
+ expect(turnCredentials({ now, fetchImpl })!.credential).toBe('c1')
+ })
+
+ it('degrades to null once the credential actually expires, and never throws', async () => {
+ const fetchImpl = vi.fn<typeof fetch>(async () => iceResponse())
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+
+ fetchImpl.mockImplementation(async () => { throw new Error('network down') })
+ clock += TTL_MS + 1
+ expect(turnCredentials({ now, fetchImpl })).toBeNull()
+ await settle()
+ expect(turnCredentials({ now, fetchImpl })).toBeNull()
+ })
+
+ it('backs off after a failure instead of refetching on every read', async () => {
+ const fetchImpl = vi.fn<typeof fetch>(async () => new Response('bad', { status: 401 }))
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+ expect(fetchImpl).toHaveBeenCalledTimes(1)
+
+ for (let i = 0; i < 5; i++) {
+ expect(turnCredentials({ now, fetchImpl })).toBeNull()
+ await settle()
+ }
+ expect(fetchImpl).toHaveBeenCalledTimes(1)
+
+ clock += 60_001 // past the retry backoff
+ turnCredentials({ now, fetchImpl })
+ await settle()
+ expect(fetchImpl).toHaveBeenCalledTimes(2)
+ })
+
+ it.each([
+ ['not json', new Response('<html>', { status: 201 })],
+ ['no iceServers', new Response(JSON.stringify({}), { status: 201 })],
+ ['stun-only pool', new Response(JSON.stringify({ iceServers: [{ urls: ['stun:x:3478'] }] }), { status: 201 })],
+ ['turn entry without credentials', new Response(JSON.stringify({ iceServers: [{ urls: ['turn:x:3478'] }] }), { status: 201 })],
+ ])('treats a malformed response (%s) as no credential, without throwing', async (_label, body) => {
+ const fetchImpl = vi.fn<typeof fetch>(async () => body.clone())
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+ expect(turnCredentials({ now, fetchImpl })).toBeNull()
+ })
+
+ it('de-duplicates concurrent mints', async () => {
+ let release!: (value: Response) => void
+ const gate = new Promise<Response>((resolve) => { release = resolve })
+ const fetchImpl = vi.fn<typeof fetch>(() => gate)
+
+ startTurnCredentialRefresh({ now, fetchImpl })
+ turnCredentials({ now, fetchImpl })
+ turnCredentials({ now, fetchImpl })
+ release(iceResponse())
+ await settle()
+
+ expect(fetchImpl).toHaveBeenCalledTimes(1)
+ })
+
+ it('never touches the network when TURN is unconfigured', async () => {
+ envMock.TERMINAL_P2P_TURN_KEY_ID = ''
+ const fetchImpl = vi.fn<typeof fetch>(async () => iceResponse())
+ startTurnCredentialRefresh({ now, fetchImpl })
+ await settle()
+ expect(turnCredentials({ now, fetchImpl })).toBeNull()
+ expect(fetchImpl).not.toHaveBeenCalled()
+ })
+})
diff --git a/backend/src/lib/turnCredentials.ts b/backend/src/lib/turnCredentials.ts
new file mode 100644
index 000000000..ec5569caa
--- /dev/null
+++ b/backend/src/lib/turnCredentials.ts
@@ -0,0 +1,187 @@
+/**
+ * Cloudflare Realtime TURN credentials, minted once and served from memory.
+ *
+ * READ THIS BEFORE MAKING ANY OF IT ASYNC. The snapshot getter is synchronous on purpose, because the
+ * only consumer — `terminalP2pPolicy()` — is called from three places that each reject an await for a
+ * different reason:
+ * - `webWs.ts` `ack()`: awaiting IS safe there (frames are serialised through `frameChain`), but it
+ * would put a Cloudflare round trip in the middle of every `machine_select` and would need a fresh
+ * `selectGen` staleness re-check afterwards. Latency for no benefit.
+ * - `webWs.ts` per-frame signaling gate: an await there sits IN FRONT of the rate limiter and the
+ * size check, so a flood of `p2p_ice_candidate` frames would each hold the chain open uncounted.
+ * - `adapterWs.ts` gate: `onMessage` is a synchronous `void` arrow, adapterWs has no frame
+ * serialisation at all, and it replays a buffered queue in order at attach. Cannot await, period.
+ *
+ * So: a background refresh keeps a snapshot warm and every read is a property lookup. The credential
+ * is account-wide rather than per-user (Cloudflare does not scope it to our users), so one snapshot
+ * shared by every worker is correct — unlike bus.ts, which needs Redis because ITS values are
+ * per-machine and the worker that wrote one is rarely the worker that reads it. Four cluster workers
+ * minting four credentials every couple of hours is far cheaper than putting Redis in the path of
+ * something that must degrade quietly.
+ *
+ * Every failure degrades to `null`, which the policy renders as STUN-only — the exact behaviour we
+ * shipped before TURN existed. Nothing here ever throws.
+ */
+import { env } from '../config/env.js'
+import { logger } from '../utils/logger.js'
+
+export interface TurnCredentials {
+ urls: string[]
+ username: string
+ credential: string
+}
+
+interface Snapshot {
+ credentials: TurnCredentials
+ /** Epoch ms after which the credential must not be handed out any more. */
+ expiresAt: number
+}
+
+export interface TurnCredentialDeps {
+ now?: () => number
+ fetchImpl?: typeof fetch
+}
+
+/** Refresh once the credential is more than three quarters through its lifetime. */
+const REFRESH_AT_REMAINING = 0.25
+/** After a failure, do not hammer Cloudflare on every tick. */
+const RETRY_AFTER_MS = 60_000
+const CLOUDFLARE_TURN_API = 'https://rtc.live.cloudflare.com/v1/turn/keys'
+
+let snapshot: Snapshot | null = null
+let inflight: Promise<Snapshot | null> | null = null
+let nextAttemptAt = 0
+let timer: ReturnType<typeof setInterval> | null = null
+
+function configured(): boolean {
+ return !!env.TERMINAL_P2P_TURN_KEY_ID && !!env.TERMINAL_P2P_TURN_API_TOKEN
+}
+
+function parseIceServers(body: unknown): TurnCredentials | null {
+ if (!body || typeof body !== 'object') return null
+ const servers = (body as { iceServers?: unknown }).iceServers
+ if (!Array.isArray(servers)) return null
+ for (const entry of servers) {
+ if (!entry || typeof entry !== 'object') continue
+ const { urls, username, credential } = entry as Record<string, unknown>
+ if (typeof username !== 'string' || !username) continue
+ if (typeof credential !== 'string' || !credential) continue
+ const list = (Array.isArray(urls) ? urls : [urls])
+ .filter((url): url is string => typeof url === 'string' && /^turns?:/i.test(url))
+ if (list.length > 0) return { urls: list, username, credential }
+ }
+ return null
+}
+
+async function mint(deps: Required<TurnCredentialDeps>): Promise<Snapshot | null> {
+ const ttl = env.TERMINAL_P2P_TURN_TTL_SECONDS
+ let response: Response
+ try {
+ response = await deps.fetchImpl(
+ `${CLOUDFLARE_TURN_API}/${env.TERMINAL_P2P_TURN_KEY_ID}/credentials/generate-ice-servers`,
+ {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${env.TERMINAL_P2P_TURN_API_TOKEN}`,
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify({ ttl }),
+ signal: AbortSignal.timeout(env.TERMINAL_P2P_TURN_TIMEOUT_MS),
+ },
+ )
+ } catch (err) {
+ logger.warn('turn credential request failed', { error: String(err) })
+ return null
+ }
+ if (!response.ok) {
+ const detail = await response.text().catch(() => '')
+ logger.warn('turn credential rejected', { status: response.status, detail: detail.slice(0, 200) })
+ return null
+ }
+ let body: unknown
+ try {
+ body = await response.json()
+ } catch {
+ logger.warn('turn credential response was not json')
+ return null
+ }
+ const credentials = parseIceServers(body)
+ if (!credentials) {
+ logger.warn('turn credential response carried no usable turn entry')
+ return null
+ }
+ return { credentials, expiresAt: deps.now() + ttl * 1000 }
+}
+
+async function refresh(deps: Required<TurnCredentialDeps>): Promise<Snapshot | null> {
+ if (inflight) return inflight
+ const run = mint(deps)
+ .then((next) => {
+ if (next) {
+ snapshot = next
+ nextAttemptAt = 0
+ return next
+ }
+ // Keep whatever is still valid; a Cloudflare blip must not disable TURN mid-flight.
+ nextAttemptAt = deps.now() + RETRY_AFTER_MS
+ return snapshot
+ })
+ .catch(() => snapshot) // mint() already swallows everything; this is belt and braces
+ .finally(() => { inflight = null })
+ inflight = run
+ return run
+}
+
+function resolveDeps(deps: TurnCredentialDeps = {}): Required<TurnCredentialDeps> {
+ return {
+ now: deps.now ?? ((): number => Date.now()),
+ fetchImpl: deps.fetchImpl ?? fetch,
+ }
+}
+
+/** Synchronous snapshot. `null` means "ship a STUN-only policy" — never an error. */
+export function turnCredentials(deps: TurnCredentialDeps = {}): TurnCredentials | null {
+ if (!configured()) return null
+ const { now } = resolveDeps(deps)
+ const current = snapshot
+ if (!current) {
+ // First read before the boot fetch landed (or after a total failure): kick one off and answer
+ // STUN-only for now. The next machine_select gets the credential.
+ if (now() >= nextAttemptAt) void refresh(resolveDeps(deps))
+ return null
+ }
+ const ttlMs = env.TERMINAL_P2P_TURN_TTL_SECONDS * 1000
+ const remaining = current.expiresAt - now()
+ if (remaining <= 0) {
+ if (now() >= nextAttemptAt) void refresh(resolveDeps(deps))
+ return null
+ }
+ if (remaining < ttlMs * REFRESH_AT_REMAINING && now() >= nextAttemptAt) {
+ void refresh(resolveDeps(deps)) // still serving the current one below; this is a background top-up
+ }
+ return current.credentials
+}
+
+/** Boot hook: mint immediately so the first machine_select already has TURN, then top up on a timer. */
+export function startTurnCredentialRefresh(deps: TurnCredentialDeps = {}): void {
+ if (!configured()) {
+ logger.info('terminal p2p TURN disabled (no TERMINAL_P2P_TURN_KEY_ID)')
+ return
+ }
+ const resolved = resolveDeps(deps)
+ void refresh(resolved)
+ if (timer) clearInterval(timer)
+ // A quarter of the ttl: guarantees at least one attempt inside the refresh window even if one fails.
+ const period = Math.max(60_000, (env.TERMINAL_P2P_TURN_TTL_SECONDS * 1000) / 4)
+ timer = setInterval(() => { void turnCredentials(deps) }, period)
+ timer.unref?.()
+}
+
+/** Test seam: forget the snapshot, the in-flight mint and the retry backoff. */
+export function resetTurnCredentialsForTest(): void {
+ snapshot = null
+ inflight = null
+ nextAttemptAt = 0
+ if (timer) clearInterval(timer)
+ timer = null
+}
diff --git a/backend/src/lib/voiceQuota.test.ts b/backend/src/lib/voiceQuota.test.ts
new file mode 100644
index 000000000..ceee9a035
--- /dev/null
+++ b/backend/src/lib/voiceQuota.test.ts
@@ -0,0 +1,247 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const state = vi.hoisted(() => ({
+ limitSeconds: 600,
+ usage: null as null | { machineId: string; dayKey: string; usedMs: number; expiresAt: Date },
+ reservations: new Map<string, Record<string, unknown>>(),
+}))
+
+const db = vi.hoisted(() => ({
+ bindingFind: vi.fn(),
+ planFind: vi.fn(),
+ usageFind: vi.fn(),
+ usageUpsert: vi.fn(),
+ usageUpdateMany: vi.fn(),
+ usageDeleteMany: vi.fn(),
+ reservationFind: vi.fn(),
+ reservationFindMany: vi.fn(),
+ reservationCreate: vi.fn(),
+ reservationUpdate: vi.fn(),
+ reservationUpdateMany: vi.fn(),
+ reservationDeleteMany: vi.fn(),
+ transaction: vi.fn(),
+}))
+
+vi.mock('./prisma.js', () => {
+ const prisma = {
+ machine: { findUnique: db.bindingFind },
+ subscriptionPlan: { findUnique: db.planFind },
+ machineVoiceDailyUsage: {
+ findUnique: db.usageFind,
+ upsert: db.usageUpsert,
+ updateMany: db.usageUpdateMany,
+ deleteMany: db.usageDeleteMany,
+ },
+ machineVoiceReservation: {
+ findUnique: db.reservationFind,
+ findMany: db.reservationFindMany,
+ create: db.reservationCreate,
+ update: db.reservationUpdate,
+ updateMany: db.reservationUpdateMany,
+ deleteMany: db.reservationDeleteMany,
+ },
+ $transaction: db.transaction,
+ }
+ return { prisma }
+})
+vi.mock('../utils/logger.js', () => ({ logger: { warn: vi.fn() } }))
+
+import { VoiceQuotaExceededError, voiceQuotaService } from './voiceQuota.js'
+
+describe('daily voice quota', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ state.limitSeconds = 600
+ state.usage = null
+ state.reservations.clear()
+ db.bindingFind.mockResolvedValue({ planId: 'plan-1', deletedAt: null })
+ db.planFind.mockImplementation(async () => ({ dailyVoiceLimitSeconds: state.limitSeconds }))
+ db.usageFind.mockImplementation(async () => state.usage)
+ db.usageUpsert.mockImplementation(async ({ create, update }: {
+ create: { machineId: string; dayKey: string; usedMs: number; expiresAt: Date }
+ update: { expiresAt: Date }
+ }) => {
+ if (!state.usage) state.usage = { ...create }
+ else state.usage.expiresAt = update.expiresAt
+ return { ...state.usage }
+ })
+ db.usageUpdateMany.mockImplementation(async ({ where, data }: {
+ where: { usedMs?: { lte?: number } }
+ data: { usedMs: { increment?: number; decrement?: number }; expiresAt?: Date }
+ }) => {
+ if (!state.usage) return { count: 0 }
+ if (where.usedMs?.lte != null && state.usage.usedMs > where.usedMs.lte) return { count: 0 }
+ state.usage.usedMs += data.usedMs.increment ?? -(data.usedMs.decrement ?? 0)
+ if (data.expiresAt) state.usage.expiresAt = data.expiresAt
+ return { count: 1 }
+ })
+ db.usageDeleteMany.mockResolvedValue({ count: 0 })
+ db.reservationFind.mockImplementation(async ({ where }: { where: { uploadId: string } }) =>
+ state.reservations.get(where.uploadId) ?? null)
+ db.reservationCreate.mockImplementation(async ({ data }: { data: Record<string, unknown> }) => {
+ state.reservations.set(String(data.uploadId), { ...data })
+ return data
+ })
+ db.reservationUpdate.mockImplementation(async ({ where, data }: {
+ where: { uploadId: string }
+ data: Record<string, unknown>
+ }) => {
+ const current = state.reservations.get(where.uploadId) ?? {}
+ const next = { ...current, ...data }
+ state.reservations.set(where.uploadId, next)
+ return next
+ })
+ db.reservationUpdateMany.mockImplementation(async ({ where, data }: {
+ where: { uploadId: string; status?: string }
+ data: Record<string, unknown>
+ }) => {
+ const current = state.reservations.get(where.uploadId)
+ if (!current || (where.status && current.status !== where.status)) return { count: 0 }
+ state.reservations.set(where.uploadId, { ...current, ...data })
+ return { count: 1 }
+ })
+ db.reservationFindMany.mockImplementation(async ({ where }: {
+ where: { status: string; releaseAt: { lte: Date } }
+ }) => [...state.reservations.values()]
+ .filter((item) => item.status === where.status
+ && item.releaseAt instanceof Date
+ && item.releaseAt <= where.releaseAt.lte)
+ .map((item) => ({ uploadId: item.uploadId })))
+ db.reservationDeleteMany.mockResolvedValue({ count: 0 })
+ db.transaction.mockImplementation(async (action: (tx: unknown) => Promise<unknown>) => action({
+ machine: { findUnique: db.bindingFind },
+ subscriptionPlan: { findUnique: db.planFind },
+ machineVoiceDailyUsage: {
+ findUnique: db.usageFind,
+ upsert: db.usageUpsert,
+ updateMany: db.usageUpdateMany,
+ },
+ machineVoiceReservation: {
+ findUnique: db.reservationFind,
+ create: db.reservationCreate,
+ update: db.reservationUpdate,
+ },
+ }))
+ })
+
+ it('uses a UTC calendar day and reports the next UTC reset', async () => {
+ const result = await voiceQuotaService.snapshotForMachine(
+ 'machine-1',
+ new Date('2026-07-24T23:59:30.000Z'),
+ )
+ expect(result).toMatchObject({
+ dayKey: '2026-07-24',
+ limitSeconds: 600,
+ usedSeconds: 0,
+ remainingSeconds: 600,
+ resetAt: '2026-07-25T00:00:00.000Z',
+ })
+ })
+
+ it('reserves atomically and rejects an utterance that would cross the remaining limit', async () => {
+ const now = new Date('2026-07-24T12:00:00.000Z')
+ await expect(voiceQuotaService.reserve('machine-1', 'upload-a', 590_000, now)).resolves.toMatchObject({
+ state: 'reserved',
+ snapshot: { usedSeconds: 590, remainingSeconds: 10 },
+ })
+ await expect(voiceQuotaService.reserve('machine-1', 'upload-b', 20_000, now))
+ .rejects.toBeInstanceOf(VoiceQuotaExceededError)
+ expect(state.usage?.usedMs).toBe(590_000)
+ })
+
+ it('does not charge the same upload twice and commits it once', async () => {
+ const now = new Date('2026-07-24T12:00:00.000Z')
+ await voiceQuotaService.reserve('machine-1', 'upload-a', 30_000, now)
+ await expect(voiceQuotaService.reserve('machine-1', 'upload-a', 30_000, now))
+ .resolves.toMatchObject({ state: 'pending' })
+ expect(state.usage?.usedMs).toBe(30_000)
+ await voiceQuotaService.commit('upload-a', now)
+ expect(state.reservations.get('upload-a')?.status).toBe('committed')
+ })
+
+ it('retries a concurrent unique uploadId winner and returns its pending reservation', async () => {
+ const now = new Date('2026-07-24T12:00:00.000Z')
+ db.transaction.mockImplementationOnce(async () => {
+ state.usage = {
+ machineId: 'machine-1',
+ dayKey: '2026-07-24',
+ usedMs: 30_000,
+ expiresAt: new Date('2026-08-29T00:00:00.000Z'),
+ }
+ state.reservations.set('upload-race', {
+ uploadId: 'upload-race',
+ machineId: 'machine-1',
+ dayKey: '2026-07-24',
+ durationMs: 30_000,
+ status: 'pending',
+ })
+ throw Object.assign(new Error('Unique constraint failed'), { code: 'P2002' })
+ })
+ db.transaction.mockImplementationOnce(async (action: (tx: unknown) => Promise<unknown>) => action({
+ machine: { findUnique: db.bindingFind },
+ subscriptionPlan: { findUnique: db.planFind },
+ machineVoiceDailyUsage: {
+ findUnique: db.usageFind,
+ upsert: db.usageUpsert,
+ updateMany: db.usageUpdateMany,
+ },
+ machineVoiceReservation: {
+ findUnique: db.reservationFind,
+ create: db.reservationCreate,
+ update: db.reservationUpdate,
+ },
+ }))
+
+ await expect(voiceQuotaService.reserve('machine-1', 'upload-race', 30_000, now))
+ .resolves.toMatchObject({ state: 'pending' })
+ expect(state.usage?.usedMs).toBe(30_000)
+ expect(db.transaction).toHaveBeenCalledTimes(2)
+ })
+
+ it('keeps concurrent devices inside the shared machine allowance', async () => {
+ const now = new Date('2026-07-24T12:00:00.000Z')
+ const results = await Promise.allSettled([
+ voiceQuotaService.reserve('machine-1', 'upload-a', 590_000, now),
+ voiceQuotaService.reserve('machine-1', 'upload-b', 20_000, now),
+ ])
+ expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1)
+ expect(results.filter((result) => result.status === 'rejected')).toHaveLength(1)
+ expect(state.usage?.usedMs).toBeLessThanOrEqual(600_000)
+ })
+
+ it('releases failed or stale pending STT reservations', async () => {
+ const now = new Date('2026-07-24T12:00:00.000Z')
+ await voiceQuotaService.reserve('machine-1', 'upload-a', 30_000, now)
+ const cleanup = await voiceQuotaService.cleanup(new Date('2026-07-24T12:21:00.000Z'))
+ expect(cleanup.released).toBe(1)
+ expect(state.usage?.usedMs).toBe(0)
+ expect(state.reservations.get('upload-a')?.status).toBe('released')
+ })
+
+ it('tracks usage without blocking the zero/unlimited plan', async () => {
+ state.limitSeconds = 0
+ const result = await voiceQuotaService.reserve(
+ 'machine-1',
+ 'upload-unlimited',
+ 3_700_000,
+ new Date('2026-07-24T12:00:00.000Z'),
+ )
+ expect(result.snapshot).toMatchObject({
+ limitSeconds: 0,
+ usedSeconds: 3700,
+ remainingSeconds: null,
+ })
+ })
+
+ it('keeps the same daily bucket when the machine changes plan', async () => {
+ const now = new Date('2026-07-24T12:00:00.000Z')
+ await voiceQuotaService.reserve('machine-1', 'upload-free', 590_000, now)
+ state.limitSeconds = 1800
+ const upgraded = await voiceQuotaService.reserve('machine-1', 'upload-pro', 100_000, now)
+ expect(upgraded.snapshot).toMatchObject({ usedSeconds: 690, remainingSeconds: 1110 })
+ state.limitSeconds = 600
+ await expect(voiceQuotaService.reserve('machine-1', 'upload-after-downgrade', 1_000, now))
+ .rejects.toBeInstanceOf(VoiceQuotaExceededError)
+ expect(state.usage?.usedMs).toBe(690_000)
+ })
+})
diff --git a/backend/src/lib/voiceQuota.ts b/backend/src/lib/voiceQuota.ts
new file mode 100644
index 000000000..78d1786c9
--- /dev/null
+++ b/backend/src/lib/voiceQuota.ts
@@ -0,0 +1,240 @@
+import type { Prisma } from '@prisma/client'
+import { prisma } from './prisma.js'
+import { logger } from '../utils/logger.js'
+
+const PENDING_RESERVATION_MS = 20 * 60_000
+const RETENTION_MS = 35 * 24 * 60 * 60_000
+const TRANSACTION_RETRIES = 3
+
+export interface VoiceQuotaSnapshot {
+ machineId: string
+ dayKey: string
+ limitSeconds: number
+ usedSeconds: number
+ remainingSeconds: number | null
+ resetAt: string
+}
+
+export interface VoiceQuotaReservationResult {
+ snapshot: VoiceQuotaSnapshot
+ state: 'reserved' | 'pending' | 'committed'
+}
+
+export class VoiceQuotaExceededError extends Error {
+ readonly code = 'DAILY_VOICE_LIMIT_REACHED'
+
+ constructor(readonly snapshot: VoiceQuotaSnapshot) {
+ super('Daily voice limit reached')
+ this.name = 'VoiceQuotaExceededError'
+ }
+}
+
+type DbClient = Prisma.TransactionClient | typeof prisma
+
+function utcWindow(now: Date): { dayKey: string; resetAt: Date; expiresAt: Date } {
+ const dayKey = now.toISOString().slice(0, 10)
+ const resetAt = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1))
+ return { dayKey, resetAt, expiresAt: new Date(resetAt.getTime() + RETENTION_MS) }
+}
+
+function snapshot(
+ machineId: string,
+ dayKey: string,
+ resetAt: Date,
+ usedMs: number,
+ limitSeconds: number,
+): VoiceQuotaSnapshot {
+ const limitMs = limitSeconds * 1000
+ return {
+ machineId,
+ dayKey,
+ limitSeconds,
+ usedSeconds: Math.floor(Math.max(0, usedMs) / 1000),
+ remainingSeconds: limitSeconds === 0
+ ? null
+ : Math.floor(Math.max(0, limitMs - usedMs) / 1000),
+ resetAt: resetAt.toISOString(),
+ }
+}
+
+async function limitForMachine(machineId: string, db: DbClient = prisma): Promise<number> {
+ const binding = await db.machine.findUnique({
+ where: { machineId },
+ select: { planId: true, deletedAt: true },
+ })
+ if (!binding || binding.deletedAt) throw new Error('machine not found')
+ if (!binding.planId) return 0
+ const plan = await db.subscriptionPlan.findUnique({
+ where: { id: binding.planId },
+ select: { dailyVoiceLimitSeconds: true },
+ })
+ // Missing/legacy plans remain unlimited for backwards compatibility.
+ return Math.max(0, plan?.dailyVoiceLimitSeconds ?? 0)
+}
+
+function transientTransactionError(err: unknown): boolean {
+ const code = typeof err === 'object' && err ? (err as { code?: unknown }).code : undefined
+ const message = err instanceof Error ? err.message : String(err)
+ // Concurrent first delivery of the same upload can race on the unique uploadId. Retrying P2002
+ // re-reads the winner's reservation and returns pending/committed without charging a second time.
+ return code === 'P2002' || code === 'P2034'
+ || /write conflict|transienttransactionerror|transaction.*aborted/i.test(message)
+}
+
+async function withTransactionRetry<T>(
+ action: (tx: Prisma.TransactionClient) => Promise<T>,
+): Promise<T> {
+ let lastError: unknown
+ for (let attempt = 1; attempt <= TRANSACTION_RETRIES; attempt++) {
+ try {
+ return await prisma.$transaction(action)
+ } catch (err) {
+ lastError = err
+ if (!transientTransactionError(err) || attempt === TRANSACTION_RETRIES) throw err
+ }
+ }
+ throw lastError
+}
+
+export const voiceQuotaService = {
+ async snapshotForMachine(machineId: string, now = new Date()): Promise<VoiceQuotaSnapshot> {
+ const [{ dayKey, resetAt }, limitSeconds] = await Promise.all([
+ Promise.resolve(utcWindow(now)),
+ limitForMachine(machineId),
+ ])
+ const usage = await prisma.machineVoiceDailyUsage.findUnique({
+ where: { machineId_dayKey: { machineId, dayKey } },
+ select: { usedMs: true },
+ })
+ return snapshot(machineId, dayKey, resetAt, usage?.usedMs ?? 0, limitSeconds)
+ },
+
+ async reserve(
+ machineId: string,
+ uploadId: string,
+ durationMs: number,
+ now = new Date(),
+ ): Promise<VoiceQuotaReservationResult> {
+ if (!uploadId) throw new Error('voice uploadId is required')
+ const roundedDurationMs = Math.max(1, Math.ceil(durationMs))
+ const { dayKey, resetAt, expiresAt } = utcWindow(now)
+
+ return withTransactionRetry(async (tx) => {
+ // Resolve the plan inside the same transaction as the usage increment so a concurrent plan
+ // change cannot validate against one tier and charge against another snapshot.
+ const limitSeconds = await limitForMachine(machineId, tx)
+ const limitMs = limitSeconds * 1000
+ const existing = await tx.machineVoiceReservation.findUnique({ where: { uploadId } })
+ if (existing && (existing.machineId !== machineId || existing.dayKey !== dayKey)) {
+ throw new Error('voice uploadId belongs to another machine or UTC day')
+ }
+ const usage = await tx.machineVoiceDailyUsage.upsert({
+ where: { machineId_dayKey: { machineId, dayKey } },
+ update: { expiresAt },
+ create: { machineId, dayKey, usedMs: 0, expiresAt },
+ })
+ if (existing?.status === 'committed' || existing?.status === 'pending') {
+ return {
+ snapshot: snapshot(machineId, dayKey, resetAt, usage.usedMs, limitSeconds),
+ state: existing.status,
+ }
+ }
+ if (limitSeconds > 0 && usage.usedMs + roundedDurationMs > limitMs) {
+ throw new VoiceQuotaExceededError(snapshot(machineId, dayKey, resetAt, usage.usedMs, limitSeconds))
+ }
+
+ const updated = await tx.machineVoiceDailyUsage.updateMany({
+ where: {
+ machineId,
+ dayKey,
+ ...(limitSeconds > 0 ? { usedMs: { lte: limitMs - roundedDurationMs } } : {}),
+ },
+ data: { usedMs: { increment: roundedDurationMs }, expiresAt },
+ })
+ if (updated.count !== 1) {
+ const current = await tx.machineVoiceDailyUsage.findUnique({
+ where: { machineId_dayKey: { machineId, dayKey } },
+ })
+ throw new VoiceQuotaExceededError(snapshot(machineId, dayKey, resetAt, current?.usedMs ?? 0, limitSeconds))
+ }
+
+ const releaseAt = new Date(now.getTime() + PENDING_RESERVATION_MS)
+ if (existing?.status === 'released') {
+ await tx.machineVoiceReservation.update({
+ where: { uploadId },
+ data: {
+ durationMs: roundedDurationMs,
+ status: 'pending',
+ releaseAt,
+ expiresAt,
+ committedAt: null,
+ releasedAt: null,
+ },
+ })
+ } else {
+ await tx.machineVoiceReservation.create({
+ data: {
+ uploadId,
+ machineId,
+ dayKey,
+ durationMs: roundedDurationMs,
+ status: 'pending',
+ releaseAt,
+ expiresAt,
+ },
+ })
+ }
+ return {
+ snapshot: snapshot(machineId, dayKey, resetAt, usage.usedMs + roundedDurationMs, limitSeconds),
+ state: 'reserved',
+ }
+ })
+ },
+
+ async commit(uploadId: string, now = new Date()): Promise<void> {
+ await prisma.machineVoiceReservation.updateMany({
+ where: { uploadId, status: 'pending' },
+ data: { status: 'committed', committedAt: now, releaseAt: null },
+ })
+ },
+
+ async release(uploadId: string, now = new Date()): Promise<boolean> {
+ return withTransactionRetry(async (tx) => {
+ const reservation = await tx.machineVoiceReservation.findUnique({ where: { uploadId } })
+ if (!reservation || reservation.status !== 'pending') return false
+ await tx.machineVoiceDailyUsage.updateMany({
+ where: { machineId: reservation.machineId, dayKey: reservation.dayKey },
+ data: { usedMs: { decrement: reservation.durationMs } },
+ })
+ await tx.machineVoiceReservation.update({
+ where: { uploadId },
+ data: { status: 'released', releasedAt: now, releaseAt: null },
+ })
+ return true
+ })
+ },
+
+ async cleanup(now = new Date(), batchSize = 100): Promise<{ released: number; deleted: number }> {
+ const stale = await prisma.machineVoiceReservation.findMany({
+ where: { status: 'pending', releaseAt: { lte: now } },
+ orderBy: { releaseAt: 'asc' },
+ take: batchSize,
+ select: { uploadId: true },
+ })
+ let released = 0
+ for (const { uploadId } of stale) {
+ try {
+ if (await this.release(uploadId, now)) released++
+ } catch (err) {
+ logger.warn('stale voice quota reservation release failed', { uploadId, error: String(err) })
+ }
+ }
+ const [reservations, usage] = await Promise.all([
+ prisma.machineVoiceReservation.deleteMany({
+ where: { status: { in: ['committed', 'released'] }, expiresAt: { lte: now } },
+ }),
+ prisma.machineVoiceDailyUsage.deleteMany({ where: { expiresAt: { lte: now } } }),
+ ])
+ return { released, deleted: reservations.count + usage.count }
+ },
+}
diff --git a/backend/src/lib/webWs.ts b/backend/src/lib/webWs.ts
new file mode 100644
index 000000000..3ec6ceb8a
--- /dev/null
+++ b/backend/src/lib/webWs.ts
@@ -0,0 +1,494 @@
+/**
+ * Backend hub — web client terminating endpoint (`/api/web-ws`).
+ *
+ * Two auth modes share the path (the subprotocol carries the credential — browsers can't set WS headers):
+ *
+ * - PER-USER (current): the subprotocol is the user's SSO access token → ONE socket per user.
+ * The socket starts UNATTACHED; the client scopes it with `machine_select {machineId}` (ownership-checked
+ * against `agentBinding.userId`), which detaches the previous hub client and attaches a fresh one
+ * (new connId — keeps the (agent, connId) invariant that E2EE and reply-targeting rely on). While
+ * attached, frames flow exactly like the legacy mode (sendDown / up:{machineId} fan-out). The socket
+ * also live-watches ALL the user's agents and pushes `machines_status` frames (node_status transitions
+ * tagged with machineId) so the Machines list stays live without REST polling.
+ *
+ * - LEGACY (fallback): the subprotocol is an agent apiKey → the socket is bound to that ONE agent for
+ * its whole life. Kept for stale tabs running the old bundle during a rolling deploy. Collision-safe:
+ * a 64-hex apiKey is recognized before any SSO profile request, so agent keys are never sent to
+ * the external identity service.
+ */
+import type { IncomingMessage } from 'http'
+import type { Duplex } from 'stream'
+import { WebSocketServer, WebSocket, type RawData } from 'ws'
+import { extractKey } from '../utils/crypto.js'
+import { machineIdFromKey } from '../utils/crypto.js'
+import { prisma, machineAlive } from './prisma.js'
+import { getAgentPresence, subscribeUp, getDevicePresence, subscribeDeviceStatus, subscribeDeviceMachineListChanged, subscribeDeviceE2eePair } from './bus.js'
+import { attachHubClient, trackSocketLiveness, type HubClient } from './hub.js'
+import { authenticateAccessToken, SsoAuthError, type AuthUser } from './ssoAuth.js'
+import type { Frame, UpBusMsg } from './tunnel.js'
+import { machineOnline } from './providerLink.js'
+import { logger } from '../utils/logger.js'
+import { ensureMachineReady, getMachineLifecycleStatus, type MachineLifecycleStatus } from './machineLifecycle.js'
+import type { Machine } from '@prisma/client'
+import { machineBillingAllowsDataPlane } from './billingState.js'
+import { parseAutonomousEnvironment, storedAutonomousEnvironment } from './autonomousEnvironment.js'
+import {
+ isEncryptedTerminalFrame,
+ TERMINAL_DOWN_TYPES,
+ TERMINAL_ENVELOPE_MAX_BYTES,
+ terminalFrameBytes,
+ terminalFrameNeedsWake,
+ TerminalRateGuard,
+} from './terminalRelay.js'
+import { parseTerminalClientFrame, TerminalBinaryKind, TERMINAL_BINARY_CLIENT_UP_KINDS } from './terminalBinary.js'
+import {
+ isEncryptedP2pFrame,
+ P2P_DOWN_TYPES,
+ P2P_SIGNAL_MAX_BYTES,
+ p2pFrameBytes,
+ P2pSignalRateGuard,
+ terminalP2pPolicy,
+} from './p2pSignaling.js'
+
+const wss = new WebSocketServer({
+ noServer: true,
+ handleProtocols: (protocols) => {
+ const first = [...protocols][0]
+ return first ?? false
+ },
+})
+
+// Device-status re-seed: covers the silent-offline case (worker crash → presence TTL 45s ages out
+// with no transition published) — the watcher re-reads presence keys on this cadence.
+const DEVICE_RESEED_MS = 30_000
+
+/** HTTP upgrade hook for `/api/web-ws`. Subprotocol = SSO access token or legacy agent apiKey. */
+export function handleWebUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
+ const cred = extractKey(req)
+ if (!cred) { socket.destroy(); return }
+
+ // LEGACY per-agent mode: classify the fixed 64-hex key first so it is never sent to SSO.
+ if (/^[a-f0-9]{64}$/i.test(cred)) {
+ const machineId = machineIdFromKey(cred)
+ void (async () => {
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt || !machineBillingAllowsDataPlane(binding)) { socket.destroy(); return }
+ wss.handleUpgrade(req, socket, head, (ws) => attachWebClient(ws, machineId))
+ })().catch((err) => { logger.warn('web-ws legacy upgrade failed', { error: String(err) }); socket.destroy() })
+ return
+ }
+
+ // PER-USER mode: profile validation is async, so authenticate before completing the upgrade.
+ void (async () => {
+ try {
+ const requestedEnvironment = parseAutonomousEnvironment(
+ new URL(req.url ?? '/api/web-ws', 'http://backend.local').searchParams.get('autonomousEnv'),
+ )
+ const user = await authenticateAccessToken(cred, requestedEnvironment)
+ if (socket.destroyed) return
+ wss.handleUpgrade(req, socket, head, (ws) => attachUserClient(ws, user))
+ } catch (err) {
+ if (socket.destroyed) return
+ const invalid = err instanceof SsoAuthError && err.code === 'INVALID_TOKEN'
+ const mismatch = err instanceof SsoAuthError &&
+ (err.code === 'AUTONOMOUS_ENV_MISMATCH' || err.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')
+ const code = invalid ? 4401 : mismatch ? 4403 : 1013
+ const reason = invalid
+ ? 'auth expired'
+ : mismatch
+ ? `env:${err.requiredEnv ?? 'prod'}`
+ : 'auth service unavailable'
+ wss.handleUpgrade(req, socket, head, (ws) => { try { ws.close(code, reason) } catch { /* ignore */ } })
+ }
+ })().catch((err) => { logger.warn('web-ws upgrade failed', { error: String(err) }); socket.destroy() })
+}
+
+/** PER-USER socket: starts unattached; `machine_select` scopes it to one owned machine at a time. */
+function attachUserClient(ws: WebSocket, user: AuthUser): void {
+ let client: HubClient | null = null
+ let currentAgentId: string | null = null
+ let currentBinding: Machine | null = null
+ let closed = false
+ // Monotonic guards: async lookups from two rapid selects (or watch refreshes) must not finish
+ // out of order and leave the socket bound to the older target.
+ let selectGen = 0
+ let watchGen = 0
+ const terminalRate = new TerminalRateGuard()
+ const p2pSignalRate = new P2pSignalRateGuard()
+
+ logger.info('web user connected', { userId: user.sub })
+ try { ws.send(JSON.stringify({ type: 'connected', payload: { userId: user.sub } })) } catch { /* ignore */ }
+
+ // An unattached socket (user parked on the Machines page, no agent selected) holds no hub client, so a
+ // registry-driven sweep can't see it — it would be killed by LB idle timeouts, or never reaped when
+ // dead. This used to be a second heartbeat loop here, carefully disabled while attached so the two
+ // sweeps couldn't race; the hub now tracks the socket itself, which is one sweep for both states.
+ const releaseLiveness = trackSocketLiveness(ws)
+
+ // ── Live Machines-list feed ──────────────────────────────────────────────────────────────────
+ // Subscribe node_status for EVERY agent the user owns and forward it tagged with the machineId (the
+ // raw node_status frame doesn't carry one). Re-armed via `machines_watch` (sent after create/delete).
+ // The agent set is ALWAYS re-derived from the DB — the client never supplies it.
+ const statusSubs = new Map<string, () => void>()
+ const sendStatuses = (statuses: Array<{ machineId: string; online: boolean; status?: MachineLifecycleStatus; reason?: string }>): void => {
+ if (ws.readyState !== WebSocket.OPEN || statuses.length === 0) return
+ try { ws.send(JSON.stringify({ type: 'machines_status', payload: { statuses } })) } catch { /* ignore */ }
+ }
+ const watchAgents = async (): Promise<void> => {
+ const gen = ++watchGen
+ const bindings = await prisma.machine.findMany({
+ where: { userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive },
+ select: { machineId: true, billingStatus: true },
+ })
+ if (gen !== watchGen || closed) return // superseded / socket gone
+ const wanted = new Set(bindings.filter(machineBillingAllowsDataPlane).map((b) => b.machineId))
+ for (const [id, unsub] of statusSubs) {
+ if (!wanted.has(id)) { unsub(); statusSubs.delete(id) } // agent deleted
+ }
+ for (const id of wanted) {
+ if (statusSubs.has(id)) continue
+ // Bus subscriptions are refcounted — co-existing with the hub's up:{machineId} sub is fine.
+ const unsub = await subscribeUp(id, (msg: UpBusMsg) => {
+ const f = msg.frame as { type?: string; payload?: { online?: boolean; status?: MachineLifecycleStatus; reason?: string } }
+ if (f?.type === 'node_status') {
+ sendStatuses([{ machineId: id, online: f.payload?.online === true, ...(f.payload?.status ? { status: f.payload.status } : {}), ...(f.payload?.reason ? { reason: f.payload.reason } : {}) }])
+ }
+ })
+ if (closed || gen !== watchGen) { unsub(); return } // raced a close / newer watch reconciles
+ statusSubs.set(id, unsub)
+ }
+ // Seed the full current picture (presence keys = source of truth) so the list is right immediately.
+ const statuses = await Promise.all(
+ [...wanted].map(async (id) => {
+ // Same assertion as the per-agent seeds: a provider machine has no presence key and is always
+ // online, so reading presence alone would list it as offline on the machine cards too.
+ const online = await machineOnline(id, !!(await getAgentPresence(id)))
+ const lifecycle = online ? 'running' : await getMachineLifecycleStatus(id)
+ return { machineId: id, online, status: lifecycle === 'unknown' ? 'offline' as const : lifecycle }
+ }),
+ )
+ if (gen === watchGen && !closed) sendStatuses(statuses)
+ }
+ void watchAgents().catch((err) => logger.warn('web-ws watchAgents failed', { userId: user.sub, error: String(err) }))
+
+ // ── Live device-status feed (mirror of watchAgents; per-DEVICE statuses over one per-user sub) ──
+ // Transitions ride the user-scoped `devstatus:{userId}` channel (deviceWs publishes on connect/
+ // disconnect), so a device paired AFTER the watch armed still reports without re-deriving the set.
+ // The 30s re-seed poll covers the silent case: a worker holding a device socket crashes → nobody
+ // publishes offline, the presence key just ages out (TTL 45s) — the poll notices within ~30s.
+ const sendDeviceStatuses = (statuses: Array<{ deviceId: string; online: boolean; lastSeenAt?: string | null }>): void => {
+ if (ws.readyState !== WebSocket.OPEN || statuses.length === 0) return
+ try { ws.send(JSON.stringify({ type: 'devices_status', payload: { statuses } })) } catch { /* ignore */ }
+ }
+ let deviceStatusUnsub: (() => void) | null = null
+ let deviceSeedTimer: NodeJS.Timeout | null = null
+ const seedDeviceStatuses = async (): Promise<void> => {
+ const rows = await prisma.deviceBinding.findMany({ where: { userId: user.sub }, select: { deviceId: true, lastSeenAt: true } })
+ if (closed) return
+ const statuses = await Promise.all(
+ rows.map(async (d) => ({ deviceId: d.deviceId, online: await getDevicePresence(d.deviceId), lastSeenAt: d.lastSeenAt?.toISOString() ?? null })),
+ )
+ if (!closed) sendDeviceStatuses(statuses)
+ }
+ const watchDevices = async (): Promise<void> => {
+ if (!deviceStatusUnsub) {
+ deviceStatusUnsub = await subscribeDeviceStatus(user.sub, (msg) => {
+ sendDeviceStatuses([{ deviceId: msg.deviceId, online: msg.online === true, ...(msg.lastSeenAt ? { lastSeenAt: msg.lastSeenAt } : {}) }])
+ })
+ if (closed) { deviceStatusUnsub(); deviceStatusUnsub = null; return }
+ }
+ if (!deviceSeedTimer) {
+ deviceSeedTimer = setInterval(() => { void seedDeviceStatuses().catch(() => { /* ignore */ }) }, DEVICE_RESEED_MS)
+ }
+ await seedDeviceStatuses()
+ }
+ void watchDevices().catch((err) => logger.warn('web-ws watchDevices failed', { userId: user.sub, error: String(err) }))
+
+ // ── Live machine-LIST invalidation ─────────────────────────────────────────────────────────────
+ // The `devmachines:{userId}` channel (despite the device-era name) is the per-user "machine list
+ // changed" bus: create/delete/rename publish here from whatever worker served the REST call.
+ // Forward it as `machines_changed` so every open tab re-fetches the list (names stay in sync
+ // across tabs without F5).
+ let machineListUnsub: (() => void) | null = null
+ void (async () => {
+ machineListUnsub = await subscribeDeviceMachineListChanged(user.sub, (msg) => {
+ if (ws.readyState !== WebSocket.OPEN) return
+ if (msg.reason === 'environment_changed' && msg.autonomousEnv && msg.autonomousEnv !== user.autonomousEnv) {
+ try { ws.close(4403, `env:${msg.autonomousEnv}`) } catch { /* ignore */ }
+ return
+ }
+ try { ws.send(JSON.stringify({ type: 'machines_changed', payload: { reason: msg.reason } })) } catch { /* ignore */ }
+ })
+ if (closed) { machineListUnsub(); machineListUnsub = null }
+ })().catch((err) => logger.warn('web-ws machine-list watch failed', { userId: user.sub, error: String(err) }))
+
+ // ── User-level E2EE device-pair requests ─────────────────────────────────────────────────────
+ // Not tied to current machine selection: any logged-in page can receive the notice, then the frontend
+ // checks whether this browser already trusts the target machine before showing the global popup.
+ let deviceE2eePairUnsub: (() => void) | null = null
+ void (async () => {
+ deviceE2eePairUnsub = await subscribeDeviceE2eePair(user.sub, (msg) => {
+ if (ws.readyState !== WebSocket.OPEN) return
+ const { kind, ...payload } = msg
+ const type = kind === 'cleared' ? 'device_e2ee_pair_cleared' : 'device_e2ee_pair_pending'
+ try { ws.send(JSON.stringify({ type, payload })) } catch { /* ignore */ }
+ })
+ if (closed) { deviceE2eePairUnsub(); deviceE2eePairUnsub = null }
+ })().catch((err) => logger.warn('web-ws device-e2ee-pair watch failed', { userId: user.sub, error: String(err) }))
+
+ // ── Agent selection ──────────────────────────────────────────────────────────────────────────
+ const ack = (machineId: string): void => {
+ try {
+ ws.send(JSON.stringify({
+ type: 'connected',
+ payload: { machineId: machineId, p2p: terminalP2pPolicy(user.sub, machineId) },
+ }))
+ } catch { /* ignore */ }
+ // Authoritative node-liveness for the newly-scoped agent (same seed the legacy mode sends).
+ void getAgentPresence(machineId).then(async (mgr) => {
+ if (ws.readyState === WebSocket.OPEN && currentAgentId === machineId) {
+ const online = await machineOnline(machineId, !!mgr)
+ void getMachineLifecycleStatus(machineId).then((lifecycle) => {
+ if (ws.readyState === WebSocket.OPEN && currentAgentId === machineId) {
+ try { ws.send(JSON.stringify({ type: 'node_status', payload: { online, status: online ? 'running' : lifecycle === 'unknown' ? 'offline' : lifecycle } })) } catch { /* ignore */ }
+ }
+ })
+ }
+ })
+ }
+ const bindAgent = async (machineIdRaw: unknown): Promise<void> => {
+ if (typeof machineIdRaw !== 'string' || !machineIdRaw) return
+ const machineId = machineIdRaw
+ const gen = ++selectGen
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (closed || gen !== selectGen) return // superseded by a newer select
+ if (!binding || binding.deletedAt || binding.userId !== user.sub) {
+ logger.warn('machine_select rejected', { userId: user.sub, machineId })
+ try { ws.send(JSON.stringify({ type: 'machine_select_error', payload: { machineId: machineId, error: 'NOT_YOUR_MACHINE' } })) } catch { /* ignore */ }
+ return
+ }
+ if (storedAutonomousEnvironment(binding.autonomousEnv) !== user.autonomousEnv) {
+ logger.warn('machine_select environment rejected', { userId: user.sub, machineId, autonomousEnv: user.autonomousEnv })
+ try { ws.send(JSON.stringify({ type: 'machine_select_error', payload: { machineId: machineId, error: 'MACHINE_ENV_MISMATCH' } })) } catch { /* ignore */ }
+ return
+ }
+ if (binding.billingStatus === 'pending') {
+ try { ws.send(JSON.stringify({ type: 'machine_select_error', payload: { machineId: machineId, error: 'MACHINE_PAYMENT_PENDING' } })) } catch { /* ignore */ }
+ return
+ }
+ if (binding.billingStatus === 'suspended') {
+ try { ws.send(JSON.stringify({ type: 'machine_select_error', payload: { machineId: machineId, error: 'MACHINE_SUBSCRIPTION_REQUIRED' } })) } catch { /* ignore */ }
+ return
+ }
+ try {
+ await ensureMachineReady(binding)
+ } catch (err) {
+ if (!closed && gen === selectGen) {
+ const code = err instanceof Error && 'code' in err ? String((err as { code?: unknown }).code) : 'MACHINE_START_FAILED'
+ try { ws.send(JSON.stringify({ type: 'machine_select_error', payload: { machineId: machineId, error: code } })) } catch { /* ignore */ }
+ }
+ return
+ }
+ if (closed || gen !== selectGen) return
+ // Idempotent same-agent re-select keeps the connId, but still passed through ensureMachineReady so
+ // selecting a deliberately stopped machine wakes it before the readiness ack.
+ if (client && machineId === currentAgentId) { currentBinding = binding; ack(machineId); return }
+ client?.detach()
+ client = attachHubClient(ws, machineId, 'web')
+ currentAgentId = machineId
+ currentBinding = binding
+ logger.info('web user selected agent', { userId: user.sub, machineId, connId: client.connId })
+ ack(machineId)
+ }
+
+ const handleFrame = async (frame: Frame): Promise<void> => {
+ const type = frame.type as string | undefined
+ // Double-underscore frames are backend-to-Harness control messages. A web
+ // client must never be able to forge its own lifecycle notification.
+ if (typeof type === 'string' && type.startsWith('__')) return
+ const isTerminal = typeof type === 'string' && TERMINAL_DOWN_TYPES.has(type)
+ const terminalNamespace = typeof type === 'string' && type.startsWith('terminal_')
+ if (terminalNamespace && !isTerminal) {
+ try { ws.send(JSON.stringify({ type: 'terminal_transport_error', payload: { code: 'TERMINAL_TYPE_REJECTED' } })) } catch { /* ignore */ }
+ return
+ }
+ if (isTerminal) {
+ const bytes = terminalFrameBytes(frame)
+ if (bytes > TERMINAL_ENVELOPE_MAX_BYTES || !isEncryptedTerminalFrame(frame) || !terminalRate.allow(type!, bytes)) {
+ try { ws.send(JSON.stringify({ type: 'terminal_transport_error', payload: { code: 'TERMINAL_FRAME_REJECTED' } })) } catch { /* ignore */ }
+ return
+ }
+ }
+ const p2pNamespace = typeof type === 'string' && type.startsWith('p2p_')
+ const isP2pSignal = typeof type === 'string' && P2P_DOWN_TYPES.has(type)
+ if (type === 'p2p_result') {
+ const payload = (frame.payload ?? {}) as Record<string, unknown>
+ const outcome = typeof payload.outcome === 'string' ? payload.outcome : ''
+ const allowed = new Set(['direct', 'timeout', 'failed', 'dropped', 'relay'])
+ if (client && currentBinding && allowed.has(outcome)) {
+ const setupMs = Number(payload.setupMs)
+ logger.info('terminal p2p result', {
+ userId: user.sub,
+ machineId: currentBinding.machineId,
+ outcome,
+ ...(Number.isFinite(setupMs) && setupMs >= 0 && setupMs <= 60_000 ? { setupMs: Math.round(setupMs) } : {}),
+ ...(typeof payload.reason === 'string' ? { reason: payload.reason.slice(0, 64) } : {}),
+ })
+ }
+ return
+ }
+ if (p2pNamespace && !isP2pSignal) {
+ try { ws.send(JSON.stringify({ type: 'p2p_transport_error', payload: { code: 'P2P_TYPE_REJECTED' } })) } catch { /* ignore */ }
+ return
+ }
+ if (isP2pSignal) {
+ const bytes = p2pFrameBytes(frame)
+ const policyEnabled = currentBinding
+ ? terminalP2pPolicy(user.sub, currentBinding.machineId).enabled
+ : false
+ if (!policyEnabled || bytes > P2P_SIGNAL_MAX_BYTES
+ || !isEncryptedP2pFrame(frame) || !p2pSignalRate.allow(bytes)) {
+ try { ws.send(JSON.stringify({ type: 'p2p_transport_error', payload: { code: 'P2P_SIGNAL_REJECTED' } })) } catch { /* ignore */ }
+ return
+ }
+ }
+ if (type === 'machine_select') {
+ const machineId = (frame.payload as { machineId?: unknown } | undefined)?.machineId
+ await bindAgent(machineId)
+ return
+ }
+ if (type === 'machine_deselect') {
+ selectGen++ // cancel any in-flight bindAgent
+ client?.detach()
+ client = null
+ currentAgentId = null
+ currentBinding = null
+ return
+ }
+ if (type === 'machines_watch') {
+ void watchAgents().catch(() => { /* logged above */ })
+ return
+ }
+ if (type === 'devices_watch') {
+ void watchDevices().catch(() => { /* logged above */ })
+ return
+ }
+ if (client && currentBinding) {
+ // A selected machine can idle-stop while the tab remains open. Turn-producing messages always
+ // refresh the wake lease; other frames wake only when presence says the node is down.
+ try {
+ if ((isTerminal && terminalFrameNeedsWake(type!)) || (!isTerminal && (type === 'message' || !(await getAgentPresence(currentBinding.machineId))))) {
+ await ensureMachineReady(currentBinding)
+ }
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Machine could not be started'
+ try { ws.send(JSON.stringify({ type: 'error', payload: { message } })) } catch { /* ignore */ }
+ return
+ }
+ client.sendDown(frame)
+ return
+ }
+ // No agent selected: fast-fail RPCs (echo the requestId) so wsClient.request doesn't burn its
+ // 20s timeout; drop fire-and-forget frames.
+ const requestId = (frame.payload as { requestId?: unknown } | undefined)?.requestId
+ if (typeof requestId === 'string' && typeof type === 'string') {
+ try { ws.send(JSON.stringify({ type: `${type}_result`, payload: { requestId, error: 'NO_MACHINE_SELECTED' } })) } catch { /* ignore */ }
+ }
+ }
+
+ // STRICT in-order frame processing. `bindAgent` awaits a DB lookup; without this chain a frame
+ // arriving in that gap (the web sends `agent_select` then its RPCs back-to-back) would be routed
+ // by the PREVIOUS selection's client — an agent-switch could leak the old agent's projects/replies
+ // into the new view, or lose the RPC entirely. The chain makes every frame wait for the frames
+ // (incl. selects) before it, restoring the single-socket ordering guarantee end-to-end.
+ let frameChain: Promise<void> = Promise.resolve()
+ ws.on('message', (raw: RawData, isBinary: boolean) => {
+ if (isBinary) {
+ const parsed = parseTerminalClientFrame(new Uint8Array(raw as Buffer))
+ // A web/relay client only ever originates input, or a paste/imagePaste/pasteFile chunk —
+ // output/keyframe/sync flow the other way. This gate is `parseTerminalClientFrame`'s own kind
+ // check (which just validates wire shape and accepts every kind) plus that directionality —
+ // paste/imagePaste/pasteFile were missing here even after being added to the kind enum and to
+ // that parser, so every such frame was rejected as TERMINAL_BINARY_REJECTED, freezing the pane.
+ const rateKey = parsed?.kind === TerminalBinaryKind.input ? 'terminal_input' : 'terminal_paste'
+ if (!client || !currentBinding || !parsed || !TERMINAL_BINARY_CLIENT_UP_KINDS.has(parsed.kind)
+ || !terminalRate.allow(rateKey, parsed.bytes.length)) {
+ try { ws.send(JSON.stringify({ type: 'terminal_transport_error', payload: { code: 'TERMINAL_BINARY_REJECTED' } })) } catch { /* ignore */ }
+ return
+ }
+ client.sendTerminalDown(parsed.bytes)
+ return
+ }
+ let frame: Frame
+ try { frame = JSON.parse(raw.toString()) as Frame } catch { return }
+ frameChain = frameChain
+ .then(() => handleFrame(frame))
+ .catch((err) => logger.warn('web-ws frame failed', { userId: user.sub, type: frame.type, error: String(err) }))
+ })
+
+ const cleanup = (): void => {
+ if (closed) return
+ closed = true
+ releaseLiveness()
+ client?.detach()
+ client = null
+ currentBinding = null
+ for (const [, unsub] of statusSubs) unsub()
+ statusSubs.clear()
+ if (deviceSeedTimer) { clearInterval(deviceSeedTimer); deviceSeedTimer = null }
+ if (deviceStatusUnsub) { deviceStatusUnsub(); deviceStatusUnsub = null }
+ if (machineListUnsub) { machineListUnsub(); machineListUnsub = null }
+ if (deviceE2eePairUnsub) { deviceE2eePairUnsub(); deviceE2eePairUnsub = null }
+ logger.info('web user disconnected', { userId: user.sub, machineId: currentAgentId ?? undefined })
+ }
+ ws.on('close', cleanup)
+ ws.on('error', cleanup)
+}
+
+/** LEGACY per-agent socket (old bundle during rolling deploys): bound to one agent for life. */
+function attachWebClient(ws: WebSocket, machineId: string): void {
+ const client = attachHubClient(ws, machineId, 'web')
+ const terminalRate = new TerminalRateGuard()
+ logger.info('web client connected (legacy)', { machineId, connId: client.connId })
+
+ ws.send(JSON.stringify({ type: 'connected', payload: { machineId: machineId } }))
+
+ // Authoritative node-liveness signal on connect (presence key = source of truth, set on register +
+ // refreshed by the manager ping). Explicit BOTH ways so a client that connects while the node is
+ // already up gets `online:true` immediately, not just inferred from the absence of an offline event.
+ void getAgentPresence(machineId).then(async (mgr) => {
+ const online = await machineOnline(machineId, !!mgr)
+ if (ws.readyState === WebSocket.OPEN) {
+ try { ws.send(JSON.stringify({ type: 'node_status', payload: { online } })) } catch { /* ignore */ }
+ }
+ })
+
+ ws.on('message', (raw: RawData, isBinary: boolean) => {
+ if (isBinary) {
+ const parsed = parseTerminalClientFrame(new Uint8Array(raw as Buffer))
+ // Same client-originated kinds as the current per-user handler above — see its comment.
+ const rateKey = parsed?.kind === TerminalBinaryKind.input ? 'terminal_input' : 'terminal_paste'
+ if (parsed && TERMINAL_BINARY_CLIENT_UP_KINDS.has(parsed.kind) && terminalRate.allow(rateKey, parsed.bytes.length)) {
+ client.sendTerminalDown(parsed.bytes)
+ }
+ return
+ }
+ let frame: Frame
+ try { frame = JSON.parse(raw.toString()) as Frame } catch { return }
+ const type = frame.type as string | undefined
+ if (typeof type === 'string' && type.startsWith('__')) return
+ if (typeof type === 'string' && type.startsWith('terminal_') && !TERMINAL_DOWN_TYPES.has(type)) return
+ if (typeof type === 'string' && TERMINAL_DOWN_TYPES.has(type)) {
+ const bytes = terminalFrameBytes(frame)
+ if (bytes > TERMINAL_ENVELOPE_MAX_BYTES || !isEncryptedTerminalFrame(frame) || !terminalRate.allow(type, bytes)) return
+ }
+ client.sendDown(frame)
+ })
+
+ const cleanup = (): void => {
+ client.detach()
+ logger.info('web client disconnected (legacy)', { machineId, connId: client.connId })
+ }
+ ws.on('close', cleanup)
+ ws.on('error', cleanup)
+}
diff --git a/backend/src/middlewares/authMiddleware.test.ts b/backend/src/middlewares/authMiddleware.test.ts
new file mode 100644
index 000000000..7b625da0b
--- /dev/null
+++ b/backend/src/middlewares/authMiddleware.test.ts
@@ -0,0 +1,66 @@
+import Fastify from 'fastify'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { SsoAuthError } from '../lib/ssoAuth.js'
+import { registerAuthMiddleware, resolveSsoAuth, shouldSkipAuth } from './authMiddleware.js'
+
+const authenticate = vi.fn()
+
+async function request() {
+ const app = Fastify()
+ registerAuthMiddleware(app, authenticate)
+ app.get('/private', async (req) => ({ user: req.user }))
+ const result = await app.inject({ method: 'GET', url: '/private', headers: { authorization: 'Bearer sso-token' } })
+ await app.close()
+ return result
+}
+
+describe('control-plane SSO auth middleware', () => {
+ beforeEach(() => authenticate.mockReset())
+
+ it('attaches the internal user resolved from a valid access token', async () => {
+ authenticate.mockResolvedValue({ sub: 'internal-1', email: '[email protected]', role: 'user' })
+ const res = await request()
+ expect(res.statusCode).toBe(200)
+ expect(res.json().user.sub).toBe('internal-1')
+ expect(authenticate).toHaveBeenCalledWith('sso-token', 'prod')
+ })
+
+ it('keeps only the native SSO flow public and rejects legacy machine-key routes', () => {
+ expect(shouldSkipAuth('/api/machines/leave')).toBe(false)
+ expect(shouldSkipAuth('/api/auth/authorize-native')).toBe(true)
+ expect(shouldSkipAuth('/api/auth/refresh')).toBe(true)
+ expect(shouldSkipAuth('/api/machines/join/code')).toBe(false)
+ expect(shouldSkipAuth('/api/machines/join/poll')).toBe(false)
+ })
+
+ it('returns 401 only for invalid or expired tokens', async () => {
+ const authenticateInvalid = async () => { throw new SsoAuthError('expired', 'INVALID_TOKEN') }
+ await expect(resolveSsoAuth('sso-token', authenticateInvalid)).resolves.toEqual({
+ status: 401,
+ code: 'UNAUTHORIZED',
+ message: 'Unauthorized',
+ })
+ })
+
+ it('returns 503 when the profile service is unavailable', async () => {
+ const authenticateUnavailable = async () => { throw new SsoAuthError('offline', 'AUTH_SERVICE_UNAVAILABLE') }
+ await expect(resolveSsoAuth('sso-token', authenticateUnavailable)).resolves.toEqual({
+ status: 503,
+ code: 'AUTH_SERVICE_UNAVAILABLE',
+ message: 'Authentication service unavailable',
+ })
+ })
+
+ it('returns the persisted environment when the token came from the wrong SSO plane', async () => {
+ const mismatch = async () => {
+ throw new SsoAuthError('wrong plane', 'AUTONOMOUS_ENV_MISMATCH', 'stag')
+ }
+ await expect(resolveSsoAuth('sso-token', mismatch, 'prod')).resolves.toEqual({
+ status: 403,
+ code: 'AUTONOMOUS_ENV_MISMATCH',
+ message: 'wrong plane',
+ requiredEnv: 'stag',
+ })
+ })
+})
diff --git a/backend/src/middlewares/authMiddleware.ts b/backend/src/middlewares/authMiddleware.ts
new file mode 100644
index 000000000..e02723ee9
--- /dev/null
+++ b/backend/src/middlewares/authMiddleware.ts
@@ -0,0 +1,123 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify'
+import { authenticateAccessToken, bearerToken, SsoAuthError } from '../lib/ssoAuth.js'
+import type { AuthUser } from '../lib/ssoAuth.js'
+import { ForbiddenError } from '../errors/index.js'
+import { parseAutonomousEnvironment, type AutonomousEnvironment } from '../lib/autonomousEnvironment.js'
+
+/**
+ * Public local routes (no user access token). Data-plane requests never reach Fastify — they're
+ * intercepted in the serverFactory (see server.ts) — so this gate only sees the control
+ * API. Everything except health + login requires a valid SSO access token.
+ */
+export function shouldSkipAuth(url: string): boolean {
+ const path = url.split('?')[0]
+ return (
+ path === '/api/health' ||
+ // Web-driven SSO login (pre-session): /authorize returns the SSO URL, /exchange trades the code
+ // for the SSO access token, /logout-url returns the SSO end-session URL. All fetched by web XHR.
+ path === '/api/auth/authorize' ||
+ path === '/api/auth/authorize-native' ||
+ path === '/api/auth/exchange' ||
+ path === '/api/auth/refresh' ||
+ path === '/api/auth/logout-url' ||
+ // Public app-deploy registration — agent-key gated (x-api-key), self-validated in its
+ // own preHandler (agentAuth). Called by the agent-node's domain MCP, not the web SSO token.
+ path === '/api/apps' ||
+ path.startsWith('/api/apps/') ||
+ // Public agent-key validation — agent-key gated (x-api-key), self-validated in the handler.
+ // Called by the shared CCR gateway to authorize an agent-node's Claude CLI bearer token.
+ path === '/api/machines/validate' ||
+ // Analytics collector write path — machine-key gated (x-api-key), self-validated in its own
+ // preHandler (machineAuth). The READ endpoints under /api/analytics/ are NOT listed here: they
+ // are dashboard calls and must carry the owner's SSO token.
+ path === '/api/analytics/report' ||
+ // The mobile group is production-only by construction and runs its own SSO preHandler, which
+ // pins the plane to prod and skips the account-plane gate (see routes/mobile.ts). It is NOT
+ // unauthenticated — skipping here only means "not gated by THIS hook".
+ path.startsWith('/api/mobile/') ||
+ // The Cursor desktop app's two standalone endpoints — both shared-secret gated (`api_key` header),
+ // self-validated in their own preHandler (routes/cursor.ts). That client has no SSO token. Listed
+ // one by one on purpose: a future /api/cursor/* route must not inherit the skip by accident.
+ path === '/api/cursor/stt' ||
+ path === '/api/cursor/summarize' ||
+ path === '/api/cursor/route' ||
+ // Device-authorization grant for the desktop app. These two are unauthenticated BY DESIGN — the app
+ // has no credential yet, which is the entire reason the flow exists. Neither reveals anything:
+ // `start` returns codes it just minted, and `poll` needs the 32-byte device code and answers once.
+ // The approve/deny/lookup half is NOT listed and stays SSO-gated — that is where the user's identity
+ // and their machine list are involved. Listed one by one, like the cursor pair above.
+ path === '/api/device-auth/start' ||
+ path === '/api/device-auth/poll'
+ )
+}
+
+export function registerAuthMiddleware(
+ app: FastifyInstance,
+ authenticate: typeof authenticateAccessToken = authenticateAccessToken,
+): void {
+ app.addHook('onRequest', async (request: FastifyRequest, reply: FastifyReply) => {
+ if (shouldSkipAuth(request.url)) return
+ const token = bearerToken(request.headers['authorization'])
+ if (!token) {
+ return reply.code(401).send({ success: false, error: { code: 'UNAUTHORIZED', message: 'Unauthorized' } })
+ }
+ let autonomousEnv: AutonomousEnvironment
+ try {
+ autonomousEnv = parseAutonomousEnvironment(request.headers['x-autonomous-env'])
+ } catch {
+ return reply.code(400).send({ success: false, error: { code: 'INVALID_AUTONOMOUS_ENV', message: 'Invalid Autonomous environment' } })
+ }
+ const auth = await resolveSsoAuth(token, authenticate, autonomousEnv)
+ if ('user' in auth) {
+ request.user = auth.user
+ return
+ }
+ return reply.code(auth.status).send({
+ success: false,
+ error: {
+ code: auth.code,
+ message: auth.message,
+ ...(auth.requiredEnv ? { requiredEnv: auth.requiredEnv } : {}),
+ },
+ })
+ })
+}
+
+export async function resolveSsoAuth(
+ token: string,
+ authenticate: typeof authenticateAccessToken = authenticateAccessToken,
+ autonomousEnv: AutonomousEnvironment = 'prod',
+): Promise<
+ | { user: AuthUser }
+ | {
+ status: 401 | 403 | 503
+ code: 'UNAUTHORIZED' | 'AUTH_SERVICE_UNAVAILABLE' | 'AUTONOMOUS_ENV_MISMATCH' | 'AUTONOMOUS_ENV_NOT_ALLOWED'
+ message: string
+ requiredEnv?: AutonomousEnvironment
+ }
+> {
+ try {
+ return { user: await authenticate(token, autonomousEnv) }
+ } catch (err) {
+ if (err instanceof SsoAuthError && err.code === 'AUTH_SERVICE_UNAVAILABLE') {
+ return { status: 503, code: 'AUTH_SERVICE_UNAVAILABLE', message: 'Authentication service unavailable' }
+ }
+ if (err instanceof SsoAuthError &&
+ (err.code === 'AUTONOMOUS_ENV_MISMATCH' || err.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')) {
+ return {
+ status: 403,
+ code: err.code,
+ message: err.message,
+ ...(err.requiredEnv ? { requiredEnv: err.requiredEnv } : {}),
+ }
+ }
+ return { status: 401, code: 'UNAUTHORIZED', message: 'Unauthorized' }
+ }
+}
+
+/** Throw 403 unless the authenticated user is an admin. */
+export function requireAdmin(request: FastifyRequest): void {
+ if (request.user?.role !== 'admin') {
+ throw new ForbiddenError('Admin only')
+ }
+}
diff --git a/backend/src/middlewares/errorHandler.ts b/backend/src/middlewares/errorHandler.ts
new file mode 100644
index 000000000..a2e6bfb9e
--- /dev/null
+++ b/backend/src/middlewares/errorHandler.ts
@@ -0,0 +1,45 @@
+import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify'
+import { AppError } from '../errors/index.js'
+import { sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+
+export async function errorHandler(
+ error: FastifyError,
+ request: FastifyRequest,
+ reply: FastifyReply
+): Promise<void> {
+ if (error instanceof AppError) {
+ logger.warn('Application error', {
+ code: error.code,
+ statusCode: error.statusCode,
+ path: request.url,
+ method: request.method,
+ message: error.message,
+ })
+ sendError(reply, error.message, error.code || 'APP_ERROR', error.statusCode)
+ return
+ }
+
+ if (error.validation) {
+ sendError(reply, error.validation[0]?.message || 'Validation failed', 'VALIDATION_ERROR', 400)
+ return
+ }
+
+ // Fastify's own client errors (malformed JSON, unsupported media type, body too large) carry a 4xx
+ // statusCode. Logging those at ERROR as "unhandled" buries real server faults in caller noise, and
+ // reporting them as INTERNAL_ERROR tells the caller the wrong thing about whose fault it is.
+ const status = error.statusCode ?? 500
+ if (status >= 400 && status < 500) {
+ logger.warn('Client error', {
+ code: error.code, statusCode: status, path: request.url, method: request.method, message: error.message,
+ })
+ sendError(reply, error.message || 'Bad request', error.code || 'BAD_REQUEST', status)
+ return
+ }
+
+ logger.error('Unhandled error', error, { name: error.name, path: request.url, method: request.method })
+ // Only hide the real message in explicit production. Local dev often has NODE_ENV unset, and masking
+ // there just surfaces a useless "internal server error" to the caller (e.g. the UI toast).
+ const hideDetail = process.env.NODE_ENV === 'production'
+ sendError(reply, hideDetail ? 'An internal server error occurred' : (error.message || 'Internal error'), 'INTERNAL_ERROR', error.statusCode || 500)
+}
diff --git a/backend/src/middlewares/index.ts b/backend/src/middlewares/index.ts
new file mode 100644
index 000000000..ca03270c7
--- /dev/null
+++ b/backend/src/middlewares/index.ts
@@ -0,0 +1,3 @@
+export * from './authMiddleware.js'
+export * from './errorHandler.js'
+export * from './validation.js'
diff --git a/backend/src/middlewares/validation.ts b/backend/src/middlewares/validation.ts
new file mode 100644
index 000000000..212bc931d
--- /dev/null
+++ b/backend/src/middlewares/validation.ts
@@ -0,0 +1,33 @@
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { z } from 'zod'
+import { ValidationError } from '../errors/index.js'
+
+export function validateBody<T extends z.ZodTypeAny>(schema: T) {
+ return async (request: FastifyRequest<{ Body: z.infer<T> }>, _reply: FastifyReply): Promise<void> => {
+ const result = schema.safeParse(request.body)
+ if (!result.success) {
+ throw new ValidationError(result.error.issues[0]?.message || 'Invalid request body')
+ }
+ request.body = result.data as z.infer<T>
+ }
+}
+
+export function validateParams<T extends z.ZodTypeAny>(schema: T) {
+ return async (request: FastifyRequest<{ Params: z.infer<T> }>, _reply: FastifyReply): Promise<void> => {
+ const result = schema.safeParse(request.params)
+ if (!result.success) {
+ throw new ValidationError(result.error.issues[0]?.message || 'Invalid request parameters')
+ }
+ request.params = result.data as z.infer<T>
+ }
+}
+
+export function validateQuery<T extends z.ZodTypeAny>(schema: T) {
+ return async (request: FastifyRequest<{ Querystring: z.infer<T> }>, _reply: FastifyReply): Promise<void> => {
+ const result = schema.safeParse(request.query)
+ if (!result.success) {
+ throw new ValidationError(result.error.issues[0]?.message || 'Invalid query parameters')
+ }
+ request.query = result.data as z.infer<T>
+ }
+}
diff --git a/backend/src/routes/agentRoute.test.ts b/backend/src/routes/agentRoute.test.ts
new file mode 100644
index 000000000..95289a465
--- /dev/null
+++ b/backend/src/routes/agentRoute.test.ts
@@ -0,0 +1,274 @@
+// POST /api/route/agents — the agent router's backend half.
+//
+// What is pinned here is the part that is easy to break quietly: that a model's answer is filtered
+// against the ids we actually offered, that the caller's clock wins over this endpoint's, and that an
+// agent with no questions on record is described honestly in the prompt rather than being given
+// somebody else's text.
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import Fastify, { type FastifyInstance, type InjectOptions } from 'fastify'
+
+const authenticateAccessToken = vi.hoisted(() => vi.fn())
+// Only the SSO network call is faked. bearerToken, resolveSsoAuth and the middleware's own 401 mapping
+// stay REAL, so this route's gating is genuinely exercised rather than assumed.
+vi.mock('../lib/ssoAuth.js', async (importActual) => ({
+ ...(await importActual<typeof import('../lib/ssoAuth.js')>()),
+ authenticateAccessToken,
+}))
+
+import {
+ agentRouteRoutes,
+ buildRankPrompt,
+ parseRanking,
+ resolveBudgetMs,
+ resetRouteRateLimits,
+ AGENT_ROUTE_PATH,
+ type RouteBody,
+} from './agentRoute.js'
+import { errorHandler } from '../middlewares/errorHandler.js'
+import { registerAuthMiddleware, shouldSkipAuth } from '../middlewares/authMiddleware.js'
+import { SsoAuthError } from '../lib/ssoAuth.js'
+import { env } from '../config/env.js'
+
+const body = (over: Partial<RouteBody> = {}): RouteBody => ({
+ task: 'so sanh iphone vs samsung',
+ agents: [
+ { id: 'a1', name: 'Phones', prompts: ['iphone 17 gia bao nhieu'] },
+ { id: 'a2', name: 'Frontend', prompts: [] },
+ ],
+ ...over,
+})
+
+/** The app as the server builds it: the global SSO gate in front, then the route. */
+async function build(): Promise<FastifyInstance> {
+ const app = Fastify()
+ app.setErrorHandler(errorHandler)
+ registerAuthMiddleware(app, authenticateAccessToken)
+ await app.register(agentRouteRoutes)
+ await app.ready()
+ return app
+}
+
+function post(app: FastifyInstance, payload: unknown, opts: { noAuth?: boolean } = {}) {
+ const options: InjectOptions = {
+ method: 'POST',
+ url: AGENT_ROUTE_PATH,
+ payload: payload as InjectOptions['payload'],
+ headers: opts.noAuth ? {} : { authorization: 'Bearer sso-token' },
+ }
+ return app.inject(options)
+}
+
+/** One OpenAI-compatible reply, as `fetch` would hand it back. */
+const llmSays = (content: string) =>
+ vi.fn(async () => new Response(JSON.stringify({ model: 'test-model', choices: [{ message: { content } }] }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ }))
+
+describe('POST /api/route/agents', () => {
+ beforeEach(() => {
+ vi.restoreAllMocks()
+ resetRouteRateLimits()
+ authenticateAccessToken.mockReset()
+ authenticateAccessToken.mockResolvedValue({ sub: 'u1', email: '[email protected]', role: 'user', autonomousEnv: 'prod' })
+ env.CURSOR_LLM_BASE_URL = 'https://llm.example/v1'
+ env.CURSOR_LLM_API_KEY = 'llm-key'
+ })
+
+ it('is gated by the ordinary SSO middleware — the daemon signs in as a person', () => {
+ // NOT in the skip-list, unlike /api/analytics/report. The `harness` daemon holds an SSO access
+ // token and no machine api key, so a machine-key gate would refuse every real caller.
+ expect(shouldSkipAuth(AGENT_ROUTE_PATH)).toBe(false)
+ })
+
+ it('refuses without a token', async () => {
+ const app = await build()
+ expect((await post(app, body(), { noAuth: true })).statusCode).toBe(401)
+ })
+
+ it('refuses a token the SSO service rejects', async () => {
+ authenticateAccessToken.mockRejectedValue(new SsoAuthError('nope', 'INVALID_TOKEN'))
+ const app = await build()
+ expect((await post(app, body())).statusCode).toBe(401)
+ })
+
+ it('answers the single-agent case without spending a call', async () => {
+ const fetchSpy = vi.spyOn(globalThis, 'fetch')
+ const app = await build()
+ const res = await post(app, body({ agents: [{ id: 'only', name: 'One', prompts: [] }] }))
+ expect(res.statusCode).toBe(200)
+ expect(res.json().data.ranking).toEqual([{ agentId: 'only', score: 1, reason: 'only conversation' }])
+ expect(fetchSpy).not.toHaveBeenCalled()
+ })
+
+ it('ranks from the model', async () => {
+ vi.spyOn(globalThis, 'fetch').mockImplementation(
+ llmSays('{"ranking":[{"agentId":"a1","score":0.9,"reason":"phones"},{"agentId":"a2","score":0.1,"reason":"no"}]}') as never,
+ )
+ const app = await build()
+ const res = await post(app, body())
+ expect(res.statusCode).toBe(200)
+ const ranking = res.json().data.ranking
+ expect(ranking[0]).toMatchObject({ agentId: 'a1', score: 0.9 })
+ expect(ranking).toHaveLength(2)
+ })
+
+ it('passes the caller\'s budget to the model call, not its own', async () => {
+ const spy = vi.spyOn(globalThis, 'fetch').mockImplementation(
+ llmSays('{"ranking":[{"agentId":"a1","score":0.9}]}') as never,
+ )
+ const app = await build()
+ await post(app, body({ budgetMs: 12_000 }))
+ const init = spy.mock.calls[0][1] as RequestInit
+ expect(init.signal).toBeInstanceOf(AbortSignal)
+ })
+
+ it('is a 502 when the model names nothing we offered', async () => {
+ vi.spyOn(globalThis, 'fetch').mockImplementation(
+ llmSays('{"ranking":[{"agentId":"invented","score":0.9}]}') as never,
+ )
+ const app = await build()
+ expect((await post(app, body())).statusCode).toBe(502)
+ })
+
+ it('is a 502 when the call itself fails — no scored fallback here', async () => {
+ vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('upstream down') as never)
+ const app = await build()
+ expect((await post(app, body())).statusCode).toBe(502)
+ })
+
+ it('refuses when no model is configured, rather than answering another way', async () => {
+ env.CURSOR_LLM_API_KEY = undefined
+ const app = await build()
+ expect((await post(app, body())).statusCode).toBe(503)
+ })
+
+ it('rejects a body with no agents', async () => {
+ const app = await build()
+ expect((await post(app, { task: 'hi', agents: [] })).statusCode).toBe(400)
+ })
+
+ it('rejects more than fifteen agents rather than silently weighing some', async () => {
+ const many = Array.from({ length: 16 }, (_, i) => ({ id: `a${i}`, name: `n${i}`, prompts: [] }))
+ const app = await build()
+ expect((await post(app, { task: 'hi', agents: many })).statusCode).toBe(400)
+ })
+})
+
+describe('resolveBudgetMs', () => {
+ // The caller owns the clock: the CLI gives a spoken task 12s, and an endpoint that waits longer
+ // produces answers nobody is still listening for.
+ it('takes the caller\'s budget', () => expect(resolveBudgetMs(12_000)).toBe(12_000))
+ it('clamps an absurdly long one', () => expect(resolveBudgetMs(600_000)).toBe(20_000))
+ it('clamps an impossibly short one', () => expect(resolveBudgetMs(1)).toBe(3_000))
+ it('falls back when not asked', () => expect(resolveBudgetMs(undefined)).toBe(10_000))
+ it('falls back on a non-number', () => expect(resolveBudgetMs(NaN)).toBe(10_000))
+})
+
+describe('parseRanking', () => {
+ const offered = new Set(['a1', 'a2', 'a3'])
+
+ it('reads a bare object', () => {
+ expect(parseRanking('{"ranking":[{"agentId":"a1","score":0.7,"reason":"r"}]}', offered))
+ .toEqual([{ agentId: 'a1', score: 0.7, reason: 'r' }])
+ })
+
+ it('survives a code fence and a sentence of preamble', () => {
+ const raw = 'Sure, here you go:\n```json\n{"ranking":[{"agentId":"a2","score":0.5}]}\n```'
+ expect(parseRanking(raw, offered)).toEqual([{ agentId: 'a2', score: 0.5, reason: '' }])
+ })
+
+ it('drops an id that was never offered instead of correcting it', () => {
+ const raw = '{"ranking":[{"agentId":"ghost","score":0.9},{"agentId":"a1","score":0.4}]}'
+ expect(parseRanking(raw, offered)).toEqual([{ agentId: 'a1', score: 0.4, reason: '' }])
+ })
+
+ it('drops a repeat', () => {
+ const raw = '{"ranking":[{"agentId":"a1","score":0.9},{"agentId":"a1","score":0.2}]}'
+ expect(parseRanking(raw, offered)).toHaveLength(1)
+ })
+
+ it('drops a row whose score is not a number', () => {
+ const raw = '{"ranking":[{"agentId":"a1","score":"high"},{"agentId":"a2","score":0.3}]}'
+ expect(parseRanking(raw, offered)).toEqual([{ agentId: 'a2', score: 0.3, reason: '' }])
+ })
+
+ it('clamps a score outside 0..1', () => {
+ expect(parseRanking('{"ranking":[{"agentId":"a1","score":4}]}', offered)?.[0].score).toBe(1)
+ expect(parseRanking('{"ranking":[{"agentId":"a1","score":-2}]}', offered)?.[0].score).toBe(0)
+ })
+
+ it('caps at five rows', () => {
+ const ids = ['a1', 'a2', 'a3', 'a4', 'a5', 'a6']
+ const wide = new Set(ids)
+ const raw = `{"ranking":[${ids.map((id) => `{"agentId":"${id}","score":0.5}`).join(',')}]}`
+ expect(parseRanking(raw, wide)).toHaveLength(5)
+ })
+
+ it('is null on unparseable text — a failed call, not an empty ranking', () => {
+ expect(parseRanking('I could not decide.', offered)).toBeNull()
+ expect(parseRanking('{"ranking":', offered)).toBeNull()
+ expect(parseRanking('{"winner":"a1"}', offered)).toBeNull()
+ })
+
+ it('is null when every row was dropped — answering in shape but naming nobody is a failure', () => {
+ expect(parseRanking('{"ranking":[{"agentId":"ghost","score":1}]}', offered)).toBeNull()
+ })
+})
+
+describe('buildRankPrompt', () => {
+ it('lists a person\'s questions as theirs, numbered and newest first', () => {
+ const prompt = buildRankPrompt(body({
+ agents: [{ id: 'a1', name: 'Phones', prompts: ['newest one', 'older one'] }, { id: 'a2', name: 'X', prompts: [] }],
+ }))
+ expect(prompt).toContain('asked, newest first:')
+ expect(prompt.indexOf('1. "newest one"')).toBeLessThan(prompt.indexOf('2. "older one"'))
+ expect(prompt).toContain("THE PERSON'S OWN QUESTIONS")
+ })
+
+ it('says an agent has nothing on record rather than filling it with the machine\'s replies', () => {
+ // The fault this whole endpoint was written to fix: the old prompt announced "recently asked" over
+ // text that was a summary of what the AGENT said back.
+ const prompt = buildRankPrompt(body({ agents: [{ id: 'a1', name: 'Fresh', prompts: [] }, { id: 'a2', name: 'B', prompts: ['x'] }] }))
+ expect(prompt).toContain('(no questions on record)')
+ })
+
+ it('names how many rows it wants, and says a low score is still an answer', () => {
+ // A model asked for "the five best" when nothing fits answers with ONE row and thinks itself
+ // honest — and the picker then draws a single number over a list of eight.
+ const prompt = buildRankPrompt(body({
+ agents: Array.from({ length: 8 }, (_, i) => ({ id: `a${i}`, name: `n${i}`, prompts: [] })),
+ }))
+ expect(prompt).toContain('ALWAYS return 5 rows')
+ expect(prompt).toContain('A low score is an answer')
+ expect(prompt).toContain('The array has 5 entries')
+ })
+
+ it('asks for one row per conversation when there are fewer than five', () => {
+ const prompt = buildRankPrompt(body({
+ agents: [{ id: 'a1', name: 'A', prompts: [] }, { id: 'a2', name: 'B', prompts: [] }],
+ }))
+ expect(prompt).toContain('The array has 2 entries')
+ })
+
+ it('scores on an absolute scale, not against each other', () => {
+ const prompt = buildRankPrompt(body())
+ expect(prompt).toContain('NOT relative to the others')
+ })
+
+ it('carries the task verbatim and forbids translating it', () => {
+ const prompt = buildRankPrompt(body({ task: 'so sánh iphone với samsung' }))
+ expect(prompt).toContain('so sánh iphone với samsung')
+ expect(prompt).toContain('do NOT translate')
+ })
+
+ it('states continuity as a fact with its age, and omits it entirely when absent', () => {
+ const withCarry = buildRankPrompt(body({ continuity: { agentId: 'a2', agoMs: 30_000 } }))
+ expect(withCarry).toContain('previous task to id=a2, 30s ago')
+ expect(buildRankPrompt(body())).not.toContain('previous task')
+ })
+
+ it('does not mention a machine — the old prompt printed one and never explained it', () => {
+ expect(buildRankPrompt(body())).not.toContain('machine=')
+ })
+})
diff --git a/backend/src/routes/agentRoute.ts b/backend/src/routes/agentRoute.ts
new file mode 100644
index 000000000..86496173c
--- /dev/null
+++ b/backend/src/routes/agentRoute.ts
@@ -0,0 +1,322 @@
+/**
+ * Which agent a task belongs to — ranked, scored, and decided HERE rather than on the machine.
+ *
+ * POST /api/route/agents SSO access token → { ranking: [{ agentId, score, reason }] }
+ *
+ * WHY THIS LIVES IN THE BACKEND. The router used to build its prompt inside the `harness` CLI, which
+ * means every wording change is a release, a GCS upload, and a wait for every machine to self-update.
+ * A prompt that is still being corrected cannot converge on that loop. Here it changes with a deploy.
+ *
+ * WHY NOT /api/cursor/route. That endpoint belongs to the Cursor desktop app and says so in its first
+ * line; it is deliberately self-contained, caps at eight conversations, carries one blob of "recent"
+ * text per agent, and authenticates with a single shared secret. This one weighs fifteen agents, takes
+ * the person's own last three questions per agent, returns a RANKING rather than a winner, and bills
+ * each machine for its own call. Two products, two files — the fifteen lines of duplicated `fetch` are
+ * cheaper than one prompt serving both.
+ *
+ * THE CALLER OWNS THE CLOCK. `budgetMs` is not decoration: the CLI gives a spoken task 12s and a typed
+ * one 20s, and an endpoint that waits longer than that produces answers nobody is still listening for.
+ * See BUDGET_MS_RANGE.
+ */
+import type { FastifyInstance } from 'fastify'
+import { z } from 'zod'
+import { env } from '../config/env.js'
+import { validateBody } from '../middlewares/validation.js'
+import { sendSuccess, sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+
+export const AGENT_ROUTE_PATH = '/api/route/agents'
+
+/** Agents weighed in one request. The CLI's own cap (ROUTE_MAX_CANDIDATES) is the same number. */
+const MAX_AGENTS = 15
+
+/** Questions kept per agent — what `commander.ts` records (RECENT_TURNS). */
+const MAX_PROMPTS_PER_AGENT = 3
+
+/**
+ * One question, bounded.
+ *
+ * NOT a trim of ordinary speech: the CLI stores asks at 1000 characters and sends them whole, because
+ * cutting a Vietnamese sentence takes the object with it and the object is the topic. This exists for
+ * the other case — somebody pasting a stack trace at an agent — which must not walk into the prompt.
+ */
+const MAX_PROMPT_CHARS = 4_000
+
+/** Rows the model is asked to rank, and the most it may return. Mirrors ROUTE_SCORED_ROWS in the CLI. */
+const MAX_RANKED = 5
+
+/** What a caller may ask to wait. Clamped, never trusted — see the header. */
+const BUDGET_MS_RANGE = { min: 3_000, max: 20_000, fallback: 10_000 } as const
+
+/** Per-account budget. Routing is a keypress, not a loop. */
+const RATE_LIMIT_WINDOW_MS = 60_000
+const RATE_LIMIT_MAX = 60
+
+const rateBuckets = new Map<string, { count: number; resetAt: number }>()
+
+export function routeRateLimitAllows(userId: string, now = Date.now()): boolean {
+ const bucket = rateBuckets.get(userId)
+ if (!bucket || now >= bucket.resetAt) {
+ rateBuckets.set(userId, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS })
+ return true
+ }
+ if (bucket.count >= RATE_LIMIT_MAX) return false
+ bucket.count++
+ return true
+}
+
+/** Test seam: process-local by design, like the analytics limiter it copies. */
+export function resetRouteRateLimits(): void {
+ rateBuckets.clear()
+}
+
+const agentSchema = z.object({
+ id: z.string().min(1).max(128),
+ name: z.string().max(200).default(''),
+ /** The person's own last questions to this agent, newest first. Absent for a fresh agent. */
+ prompts: z.array(z.string()).max(MAX_PROMPTS_PER_AGENT).default([]),
+})
+
+const routeBodySchema = z.object({
+ task: z.string().min(1).max(MAX_PROMPT_CHARS),
+ agents: z.array(agentSchema).min(1).max(MAX_AGENTS),
+ budgetMs: z.number().int().optional(),
+ /** Who the previous task went to, and how long ago. Optional: a first task has no predecessor. */
+ continuity: z.object({ agentId: z.string().min(1), agoMs: z.number().min(0) }).optional(),
+})
+
+export type RouteBody = z.infer<typeof routeBodySchema>
+
+/** A caller's budget, or this endpoint's own when it did not say. Clamped either way. */
+export function resolveBudgetMs(asked: number | undefined): number {
+ if (typeof asked !== 'number' || !Number.isFinite(asked)) return BUDGET_MS_RANGE.fallback
+ return Math.max(BUDGET_MS_RANGE.min, Math.min(BUDGET_MS_RANGE.max, Math.round(asked)))
+}
+
+/**
+ * The prompt.
+ *
+ * Rewritten from the CLI's `buildRouterPrompt`, which had four faults worth naming here so they are not
+ * reintroduced by a later edit:
+ *
+ * 1. IT MISLABELLED ITS OWN DATA. It announced "recently asked: …" over text that was, for any agent
+ * with no recorded question, a summary of what the MACHINE replied. Measured in that repo: "which
+ * year did the second world war end" summarised to "1945." — an answer, presented as the person's
+ * question, to a model asked to recognise a topic. An agent with nothing on record now says so.
+ * 2. IT SCORED ONLY THE WINNER. The 0.85/0.6/0.3 scale described one agent's fit and said nothing
+ * about the rest, so the runners-up carried numbers that meant nothing next to each other or next
+ * to the threshold the app dispatches on.
+ * 3. IT TOLD THE MODEL THE RUNNERS-UP DID NOT MATTER — "never dispatched to on their own" — while the
+ * app shows them on every unsure route.
+ * 4. IT REPEATED "you MUST pick exactly one" three times, pushing for a decisive answer in the same
+ * breath as asking for an honest low score.
+ *
+ * The ranking IS the answer here; the pick is simply its first row.
+ */
+export function buildRankPrompt(body: RouteBody): string {
+ // Named in the prompt, not left to be inferred. A model asked for "the five best" when nothing fits
+ // well answers with one row and considers itself honest — and the picker then shows a single number
+ // over a list of eight, which is the one shape it cannot be read in.
+ const rows = Math.min(MAX_RANKED, body.agents.length)
+ const list = body.agents
+ .map((agent, index) => {
+ const head = `[${index + 1}] id=${agent.id} | name="${agent.name}"`
+ const prompts = agent.prompts.map((p) => p.replace(/\s+/g, ' ').trim()).filter(Boolean)
+ if (prompts.length === 0) return `${head}\n (no questions on record)`
+ const asked = prompts.map((p, at) => ` ${at + 1}. "${p}"`).join('\n')
+ return `${head}\n asked, newest first:\n${asked}`
+ })
+ .join('\n')
+
+ // Stated as a fact with its age, not as an order to obey: a follow-up usually belongs to the same
+ // agent, a new subject spoken thirty seconds later does not, and only the model can tell them apart.
+ // Placed directly under the task because it is a fact ABOUT the task.
+ const carry = body.continuity
+ ? `\nThis person sent their previous task to id=${body.continuity.agentId}, ` +
+ `${Math.max(1, Math.round(body.continuity.agoMs / 1000))}s ago. A follow-up — a pronoun, a ` +
+ `comparison, or the same subject asked a second way — usually belongs there. A task about a ` +
+ `plainly different subject does not.\n`
+ : ''
+
+ return (
+ `You rank conversations by how well each one fits an incoming task.\n\n` +
+ `TASK (verbatim; may be Vietnamese — do NOT translate it):\n"${body.task.trim()}"\n` +
+ carry +
+ `\nCONVERSATIONS:\n${list}\n\n` +
+ `HOW TO READ ONE\n` +
+ `- The NAME is written by the person. Sometimes it is a role ("Frontend", "Auth"), and sometimes it\n` +
+ ` is simply THE FIRST THING THEY ASKED — a name like "Worldcup dc to chuc may lan roi" means that\n` +
+ ` conversation is about the World Cup. Read both kinds as its subject.\n` +
+ `- The lines under it are THE PERSON'S OWN QUESTIONS to that conversation, newest first. Nothing\n` +
+ ` there is the machine's answer.\n` +
+ `- "(no questions on record)" means a new conversation: it has a name and nothing else. That is not\n` +
+ ` a reason to rank it last, nor a reason to rank it first.\n\n` +
+ `HOW TO SCORE — score each conversation 0..1 against the TASK, on this one scale:\n` +
+ ` 0.85-1.0 the task plainly belongs here: it names this conversation, or it continues one of the\n` +
+ ` questions listed under it.\n` +
+ ` 0.5-0.84 the same subject area, but nothing pins the task to this one.\n` +
+ ` 0.2-0.49 a weak link — one shared word, or a guess from the name alone.\n` +
+ ` 0.0-0.19 unrelated.\n\n` +
+ `Score each one on its own merits, NOT relative to the others. Two conversations that both fit well\n` +
+ `both score high. A task that fits nowhere is said by scoring EVERYTHING low — never by giving the\n` +
+ `least-bad one a high score.\n\n` +
+ `ALWAYS return ${MAX_RANKED} rows — or one row per conversation if there are fewer than ` +
+ `${MAX_RANKED}. Highest score first.\n\n` +
+ `A low score is an answer, not a reason to leave a row out. When the task fits nowhere, the right\n` +
+ `reply is still ${MAX_RANKED} rows that are all scored low — a person reading this needs the list\n` +
+ `in order to pick the one you could not find, and a single row gives them nothing to choose from.\n\n` +
+ `Respond with ONLY this JSON, no prose, no markdown fence. The array has ${rows} entries:\n` +
+ `{"ranking":[{"agentId":"<id from the list>","score":<0..1>,"reason":"<max 10 words>"}]}`
+ )
+}
+
+/**
+ * The LLM, over an OpenAI-compatible endpoint with plain `fetch`.
+ *
+ * A second copy of what `routes/cursor.ts` does, and knowingly so: that file documents its own
+ * self-containment as a decision, and importing across two products' routing to save a `fetch` would
+ * couple a Harness deploy to the Cursor app's behaviour.
+ */
+async function callLlm(prompt: string, timeoutMs: number): Promise<{ text: string; model: string }> {
+ const model = env.CURSOR_LLM_MODEL
+ const res = await fetch(`${env.CURSOR_LLM_BASE_URL!.replace(/\/+$/, '')}/chat/completions`, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${env.CURSOR_LLM_API_KEY}`, 'Content-Type': 'application/json' },
+ body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
+ signal: AbortSignal.timeout(timeoutMs),
+ })
+ if (!res.ok) {
+ const detail = await res.text().catch(() => '')
+ throw new Error(`LLM HTTP ${res.status}: ${detail.slice(0, 200)}`)
+ }
+ const data = (await res.json()) as { model?: string; choices?: Array<{ message?: { content?: string } }> }
+ return { text: (data.choices?.[0]?.message?.content ?? '').trim(), model: data.model || model }
+}
+
+export interface RankedRow { agentId: string; score: number; reason: string }
+
+/**
+ * The ranking, parsed defensively.
+ *
+ * "Respond with only JSON" is a request, not a guarantee — a fence or a sentence of preamble is normal
+ * from the model this runs on. Rows are DROPPED rather than corrected: an id that was never offered, a
+ * repeat, or a score that is not a number would each draw a bar in the app for something that is not
+ * there, and a picker showing an agent the machine does not have is worse than one showing nothing.
+ *
+ * Returns null when nothing usable came back at all, which the caller treats as a failed call rather
+ * than as an empty ranking — the two need opposite handling on the machine.
+ */
+export function parseRanking(raw: string, offered: Set<string>): RankedRow[] | null {
+ const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i)
+ const body = (fenced ? fenced[1] : raw).trim()
+ const start = body.indexOf('{')
+ const end = body.lastIndexOf('}')
+ if (start < 0 || end <= start) return null
+ let parsed: unknown
+ try {
+ parsed = JSON.parse(body.slice(start, end + 1))
+ } catch {
+ return null
+ }
+ const rows = (parsed as { ranking?: unknown })?.ranking
+ if (!Array.isArray(rows)) return null
+
+ const seen = new Set<string>()
+ const out: RankedRow[] = []
+ for (const row of rows) {
+ if (!row || typeof row !== 'object') continue
+ const entry = row as Record<string, unknown>
+ const agentId = typeof entry.agentId === 'string' ? entry.agentId : ''
+ if (!agentId || !offered.has(agentId) || seen.has(agentId)) continue
+ const value = typeof entry.score === 'number' ? entry.score : Number(entry.score)
+ if (!Number.isFinite(value)) continue
+ seen.add(agentId)
+ out.push({
+ agentId,
+ score: Math.max(0, Math.min(1, value)),
+ reason: typeof entry.reason === 'string' ? entry.reason.slice(0, 120) : '',
+ })
+ if (out.length >= MAX_RANKED) break
+ }
+ // A model that answered in the right shape but named nothing we offered has failed, not abstained.
+ return out.length > 0 ? out : null
+}
+
+/**
+ * ORDINARY SSO GATING — this route is NOT in the auth middleware's skip-list, and that is the whole
+ * point of how it authenticates.
+ *
+ * The `harness` daemon signs in as a person: `~/.harness/auth/session.json` holds an SSO access token
+ * and an Autonomous environment, and that is what it already presents to `/api/device-ws`. It holds no
+ * machine api key at all, so gating this on one — the arrangement `/api/analytics/report` uses — would
+ * have refused every real caller with "Unknown machine".
+ *
+ * The middleware puts the resolved account on `request.user`, which is what the limiter below counts.
+ */
+export async function agentRouteRoutes(app: FastifyInstance): Promise<void> {
+ app.post<{ Body: RouteBody }>(
+ AGENT_ROUTE_PATH,
+ { preHandler: [validateBody(routeBodySchema)] },
+ async (req, reply) => {
+ // Fail CLOSED on an unconfigured model, like the Cursor routes: an absent credential must never
+ // read as "answer some other way" on a path that spends credit.
+ if (!env.CURSOR_LLM_BASE_URL || !env.CURSOR_LLM_API_KEY) {
+ logger.error('agent-route: CURSOR_LLM_BASE_URL/CURSOR_LLM_API_KEY not configured — refusing')
+ sendError(reply, 'Routing is not configured', 'LLM_NOT_CONFIGURED', 503)
+ return
+ }
+
+ const body = req.body
+ const userId = req.user?.sub ?? ''
+ if (!routeRateLimitAllows(userId)) {
+ sendError(reply, 'Too many routing requests', 'RATE_LIMITED', 429)
+ return
+ }
+
+ // One conversation is not a decision. Answered here so the single-agent case cannot fail for a
+ // reason that has nothing to do with the person — and so it costs no call.
+ if (body.agents.length === 1) {
+ sendSuccess(reply, { ranking: [{ agentId: body.agents[0].id, score: 1, reason: 'only conversation' }] })
+ return
+ }
+
+ const budgetMs = resolveBudgetMs(body.budgetMs)
+ const offered = new Set(body.agents.map((a) => a.id))
+ const started = Date.now()
+
+ try {
+ const { text, model } = await callLlm(buildRankPrompt(body), budgetMs)
+ const ranking = parseRanking(text, offered)
+ if (!ranking) {
+ logger.error('agent-route: unusable answer', { model, userId, sample: text.slice(0, 200) })
+ sendError(reply, 'Routing failed', 'ROUTE_FAILED', 502)
+ return
+ }
+ logger.info('agent-route', {
+ userId,
+ agents: body.agents.length,
+ // With no questions on record an agent is ranked on its name alone. How many are in that
+ // state is the first thing to look at when a route reads wrong.
+ bare: body.agents.filter((a) => a.prompts.length === 0).length,
+ chars: body.task.length,
+ model,
+ ms: Date.now() - started,
+ top: ranking[0].score,
+ rows: ranking.length,
+ })
+ sendSuccess(reply, { ranking })
+ } catch (err) {
+ // No scored fallback here, deliberately. The machine already has one (pickAgentHeuristic) and it
+ // sees things this endpoint cannot — which agents are open in the window, what the person just
+ // routed to. Two different word-matchers racing to answer one question is how a product ends up
+ // with two behaviours nobody can account for.
+ logger.error('agent-route failed', {
+ userId,
+ ms: Date.now() - started,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ sendError(reply, 'Routing failed', 'ROUTE_FAILED', 502)
+ }
+ },
+ )
+}
diff --git a/backend/src/routes/analytics.ts b/backend/src/routes/analytics.ts
new file mode 100644
index 000000000..c5f2cbe4e
--- /dev/null
+++ b/backend/src/routes/analytics.ts
@@ -0,0 +1,262 @@
+/**
+ * Harness Analytics API.
+ *
+ * Two different credentials meet in this file, deliberately:
+ *
+ * POST /api/analytics/report machine api key — the collector write path. In the auth
+ * middleware skip-list; gated by `machineAuth`.
+ * GET /api/analytics/overview SSO access token — the dashboard read path.
+ * GET /api/analytics/consent SSO access token — collector state for the consent screen.
+ * POST /api/analytics/consent SSO access token — turn collection on/off, account or machine.
+ * POST /api/analytics/delete SSO access token — erase and bump the epoch.
+ *
+ * Design: docs/design/harness-analytics.md
+ */
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify'
+import { z } from 'zod'
+import { prisma, machineAlive } from '../lib/prisma.js'
+import { machineIdFromKey } from '../utils/crypto.js'
+import { validateBody, validateQuery } from '../middlewares/validation.js'
+import { sendSuccess, sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import { AnalyticsEpochError, ingestReport } from '../lib/analyticsIngest.js'
+import { analyticsOverview, buildConsentView } from '../lib/analyticsQuery.js'
+import {
+ ANALYTICS_SCHEMA_VERSION,
+ CONSENT_STATES,
+ ENGINES,
+ MAX_BUCKETS_PER_DAY,
+ MAX_DAYS_PER_REPORT,
+ MODES,
+ ORIGINS,
+ type AnalyticsReportRequest,
+} from '../types/analytics.js'
+
+/** 512 KB is far above a real backlog flush and far below anything that could hurt the process. */
+const REPORT_BODY_LIMIT = 512 * 1024
+
+/** Per-machine write budget. A healthy collector uploads on a timer, not in a loop. */
+const RATE_LIMIT_WINDOW_MS = 60_000
+const RATE_LIMIT_MAX = 30
+
+const rateBuckets = new Map<string, { count: number; resetAt: number }>()
+
+export function rateLimitAllows(machineId: string, now = Date.now()): boolean {
+ const bucket = rateBuckets.get(machineId)
+ if (!bucket || now >= bucket.resetAt) {
+ rateBuckets.set(machineId, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS })
+ return true
+ }
+ if (bucket.count >= RATE_LIMIT_MAX) return false
+ bucket.count++
+ return true
+}
+
+/** Test seam: the limiter is process-local by design (one more report is not worth a Redis hop). */
+export function resetRateLimits(): void {
+ rateBuckets.clear()
+}
+
+const engineEnum = z.enum(ENGINES)
+
+const bucketSchema = z.object({
+ engine: engineEnum,
+ mode: z.enum(MODES),
+ origin: z.enum(ORIGINS),
+ instructions: z.number().int().min(0),
+ turnsStarted: z.number().int().min(0),
+ turnsCompleted: z.number().int().min(0),
+ turnsFailed: z.number().int().min(0),
+ turnsCancelled: z.number().int().min(0),
+ turnsInputNeeded: z.number().int().min(0),
+ agentRuntimeMs: z.number().min(0),
+})
+
+const daySchema = z.object({
+ dayUtc: z.string().min(8),
+ machineDay: z.object({
+ wallClockActiveMs: z.number().min(0),
+ activeAgents: z.number().int().min(0),
+ uptimeMs: z.number().min(0),
+ reported: z.boolean(),
+ }),
+ buckets: z.array(bucketSchema).max(MAX_BUCKETS_PER_DAY),
+})
+
+const reportSchema = z.object({
+ schemaVersion: z.number().int().min(1).max(ANALYTICS_SCHEMA_VERSION),
+ epoch: z.number().int().min(0),
+ generatedAt: z.string().min(8),
+ collector: z.object({
+ version: z.string().min(1).max(64),
+ engineCoverage: z.array(engineEnum).max(ENGINES.length),
+ enginesPresent: z.array(engineEnum).max(ENGINES.length).optional(),
+ }),
+ days: z.array(daySchema).max(MAX_DAYS_PER_REPORT),
+})
+
+const overviewQuery = z.object({
+ days: z.coerce.number().int().min(1).max(400).default(30),
+ machineId: z.string().min(1).optional(),
+})
+
+const consentBody = z.object({
+ consent: z.enum(CONSENT_STATES),
+ /** Omitted = apply to every machine on the account. */
+ machineId: z.string().min(1).optional(),
+})
+
+interface MachineCtx { machineId: string; userId: string; mode: string }
+type WithMachine = FastifyRequest & { machineCtx?: MachineCtx }
+
+/**
+ * Resolve the reporting machine from its api key. Identity is derived server-side and the body's
+ * opinion about who it is, if any, is ignored — a client never chooses a `userId`.
+ */
+async function machineAuth(req: FastifyRequest, reply: FastifyReply): Promise<void> {
+ const key = req.headers['x-api-key']
+ if (typeof key !== 'string' || !key) {
+ sendError(reply, 'Missing machine api key', 'UNAUTHORIZED', 401)
+ return
+ }
+ const machineId = machineIdFromKey(key)
+ const binding = await prisma.machine.findUnique({ where: { machineId } })
+ if (!binding || binding.deletedAt) {
+ sendError(reply, 'Unknown machine', 'NO_MACHINE', 404)
+ return
+ }
+ if (!rateLimitAllows(machineId)) {
+ sendError(reply, 'Too many analytics reports', 'RATE_LIMITED', 429)
+ return
+ }
+ ;(req as WithMachine).machineCtx = { machineId, userId: binding.userId, mode: binding.authMode ?? 'managed' }
+}
+
+async function ownedMachineIds(userId: string): Promise<string[]> {
+ const rows = await prisma.machine.findMany({
+ where: { userId, ...machineAlive },
+ select: { machineId: true },
+ })
+ return rows.map((r) => r.machineId)
+}
+
+export async function analyticsRoutes(app: FastifyInstance): Promise<void> {
+ // ---- collector write path (machine api key) ---------------------------------------------------
+ app.post<{ Body: z.infer<typeof reportSchema> }>(
+ '/api/analytics/report',
+ { bodyLimit: REPORT_BODY_LIMIT, preHandler: [machineAuth, validateBody(reportSchema)] },
+ async (req, reply) => {
+ const ctx = (req as WithMachine).machineCtx!
+ try {
+ const body = req.body as AnalyticsReportRequest
+ const result = await ingestReport(ctx, {
+ ...body,
+ collector: { ...body.collector, enginesPresent: body.collector.enginesPresent ?? [] },
+ })
+ return sendSuccess(reply, result)
+ } catch (err) {
+ if (err instanceof AnalyticsEpochError) {
+ // 409 is the collector's signal to drop its local queue: this history was deleted.
+ return sendError(
+ reply,
+ `Analytics history was reset; current epoch is ${err.currentEpoch}`,
+ 'ANALYTICS_EPOCH_STALE',
+ 409,
+ )
+ }
+ logger.error('POST /api/analytics/report failed', err, { machineId: ctx.machineId })
+ return sendError(reply, 'Could not store analytics report', 'ANALYTICS_INGEST_FAILED', 500)
+ }
+ },
+ )
+
+ // ---- dashboard read path (SSO) ----------------------------------------------------------------
+ app.get<{ Querystring: z.infer<typeof overviewQuery> }>(
+ '/api/analytics/overview',
+ { preHandler: [validateQuery(overviewQuery)] },
+ async (req, reply) => {
+ const userId = req.user?.sub
+ if (!userId) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)
+ const { days, machineId } = req.query
+ if (machineId) {
+ const owned = await prisma.machine.findFirst({
+ where: { machineId, userId, ...machineAlive },
+ select: { machineId: true },
+ })
+ if (!owned) return sendError(reply, 'Unknown machine', 'NO_MACHINE', 404)
+ }
+ const overview = await analyticsOverview({ userId, days, machineId })
+ return sendSuccess(reply, overview)
+ },
+ )
+
+ // ---- consent surfaces (SSO) -------------------------------------------------------------------
+ app.get('/api/analytics/consent', async (req, reply) => {
+ const userId = req.user?.sub
+ if (!userId) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)
+ const [machines, states] = await Promise.all([
+ prisma.machine.findMany({
+ where: { userId, ...machineAlive },
+ select: { machineId: true, name: true, hostname: true, authMode: true },
+ }),
+ prisma.analyticsMachineState.findMany({ where: { userId } }),
+ ])
+ return sendSuccess(reply, buildConsentView(machines, states))
+ })
+
+ app.post<{ Body: z.infer<typeof consentBody> }>(
+ '/api/analytics/consent',
+ { preHandler: [validateBody(consentBody)] },
+ async (req, reply) => {
+ const userId = req.user?.sub
+ if (!userId) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)
+ const { consent, machineId } = req.body
+ const targets = machineId ? [machineId] : await ownedMachineIds(userId)
+ if (machineId && !(await ownedMachineIds(userId)).includes(machineId)) {
+ return sendError(reply, 'Unknown machine', 'NO_MACHINE', 404)
+ }
+ for (const target of targets) {
+ await prisma.analyticsMachineState.upsert({
+ where: { machineId: target },
+ create: { machineId: target, userId, consent, engineCoverage: [], enginesPresent: [] },
+ update: { consent },
+ })
+ }
+ logger.info('analytics consent updated', { userId, consent, machines: targets.length })
+ return sendSuccess(reply, { consent, machines: targets.length })
+ },
+ )
+
+ /**
+ * Erase every stored figure for the account and bump the epoch.
+ *
+ * The bump is the durable half: without it a collector still holding queued records would simply
+ * upload them again on its next attempt, and the delete would be cosmetic.
+ */
+ app.post('/api/analytics/delete', async (req, reply) => {
+ const userId = req.user?.sub
+ if (!userId) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)
+ const [buckets, machineDays] = await Promise.all([
+ prisma.analyticsDailyBucket.deleteMany({ where: { userId } }),
+ prisma.analyticsDailyMachine.deleteMany({ where: { userId } }),
+ ])
+ const states = await prisma.analyticsMachineState.findMany({ where: { userId } })
+ for (const state of states) {
+ await prisma.analyticsMachineState.update({
+ where: { machineId: state.machineId },
+ data: { epoch: state.epoch + 1, lastReportAt: null },
+ })
+ }
+ logger.info('analytics data deleted', {
+ userId,
+ buckets: buckets.count,
+ machineDays: machineDays.count,
+ machines: states.length,
+ })
+ return sendSuccess(reply, {
+ deletedBuckets: buckets.count,
+ deletedMachineDays: machineDays.count,
+ machines: states.length,
+ })
+ })
+}
diff --git a/backend/src/routes/apps.ts b/backend/src/routes/apps.ts
new file mode 100644
index 000000000..4f3c06016
--- /dev/null
+++ b/backend/src/routes/apps.ts
@@ -0,0 +1,125 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify'
+import { z } from 'zod'
+import { env } from '../config/env.js'
+import { prisma } from '../lib/prisma.js'
+import { machineIdFromKey, generateSubdomain } from '../utils/crypto.js'
+import { provisionViaManager } from '../lib/provision.js'
+import { evictCachedAppTarget } from '../lib/appTargetCache.js'
+import { validateBody, validateParams } from '../middlewares/validation.js'
+import { sendSuccess, sendCreated, sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import { billingStatusOf } from '../lib/billingState.js'
+
+// The port Claude ran its app on (any port except the agent-node's reserved brain/api ports).
+const RESERVED_PORTS = new Set<number>([8080, 8081])
+const registerBody = z.object({
+ agentId: z.string().min(1), // the agent unit this app belongs to
+ port: z.number().int().min(1).max(65535).refine((p) => !RESERVED_PORTS.has(p), 'Port 8080/8081 are reserved (brain/api)'),
+})
+const subdomainParams = z.object({ subdomain: z.string().min(1) })
+
+interface AgentCtx { machineId: string; managerId: string; userId: string }
+type WithAgent = FastifyRequest & { agentCtx?: AgentCtx }
+
+const publicUrl = (subdomain: string) => `https://${subdomain}${env.APP_DOMAIN_SUFFIX}`
+
+/**
+ * Resolve the caller's agent from its api key (NOT the JWT). The agent-node's domain MCP calls these
+ * endpoints with `x-api-key: API_KEY`; we derive machineId = sha256(key)[:32] and find its binding
+ * (owner + owning manager). These routes are in the auth-middleware skip-list (see authMiddleware).
+ */
+async function agentAuth(req: FastifyRequest, reply: FastifyReply): Promise<void> {
+ const key = req.headers['x-api-key']
+ if (typeof key !== 'string' || !key) {
+ sendError(reply, 'Missing agent api key', 'UNAUTHORIZED', 401)
+ return
+ }
+ const machineId = machineIdFromKey(key)
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt) {
+ sendError(reply, 'Unknown machine', 'NO_MACHINE', 404)
+ return
+ }
+ if (binding.billingStatus === 'pending') {
+ sendError(reply, 'Machine payment is pending', 'MACHINE_PAYMENT_PENDING', 409)
+ return
+ }
+ if (billingStatusOf(binding) === 'suspended') {
+ sendError(reply, 'Machine subscription is required', 'MACHINE_SUBSCRIPTION_REQUIRED', 402)
+ return
+ }
+ ;(req as WithAgent).agentCtx = { machineId, managerId: binding.managerId, userId: binding.userId }
+}
+
+/**
+ * Public app-deploy registration API — agent-key gated (NOT JWT). Generates a random subdomain, asks
+ * the owning manager to allocate an app port + route, and persists the `subdomains` routing record.
+ */
+export async function appRoutes(app: FastifyInstance): Promise<void> {
+ app.post<{ Body: z.infer<typeof registerBody> }>(
+ '/api/apps/register',
+ { preHandler: [agentAuth, validateBody(registerBody)] },
+ async (req, reply) => {
+ const { machineId, managerId, userId } = (req as WithAgent).agentCtx!
+ const { agentId, port } = req.body
+ try {
+ // Random, unique subdomain (retry on the rare collision).
+ let subdomain = ''
+ for (let i = 0; i < 5 && !subdomain; i++) {
+ const cand = generateSubdomain()
+ const exists = await prisma.subdomain.findUnique({ where: { subdomain: cand } })
+ if (!exists) subdomain = cand
+ }
+ if (!subdomain) return sendError(reply, 'could not allocate a subdomain', 'ALLOC_FAILED', 500)
+
+ // Register the app on the owning manager over its socket (no manager address needed).
+ const { appPort } = await provisionViaManager(managerId, 'app_create', { machineId, subdomain, agentId, port }) as { appPort: number }
+
+ try {
+ await prisma.subdomain.create({ data: { subdomain, machineId, agentId, managerId, userId } })
+ evictCachedAppTarget(subdomain) // drop any negative-cache marker so it's reachable immediately
+ } catch (err) {
+ // Roll back the manager-side deploy so we don't leak an orphan route/port.
+ await provisionViaManager(managerId, 'app_delete', { subdomain }).catch(() => { /* best effort */ })
+ throw err
+ }
+
+ logger.info('subdomain registered', { machineId, subdomain, agentId })
+ return sendCreated(reply, { url: publicUrl(subdomain), appPort, subdomain })
+ } catch (err) {
+ logger.error('POST /api/apps/register failed', err, { machineId, agentId })
+ return sendError(reply, err instanceof Error ? err.message : 'register failed', 'REGISTER_FAILED', 500)
+ }
+ },
+ )
+
+ app.get<{ Querystring: { machineId?: string } }>(
+ '/api/apps',
+ { preHandler: agentAuth },
+ async (req, reply) => {
+ const { machineId } = (req as WithAgent).agentCtx!
+ const rows = await prisma.subdomain.findMany({
+ where: { machineId: machineId, ...(req.query.machineId ? { machineId: req.query.machineId } : {}) },
+ orderBy: { createdAt: 'desc' },
+ })
+ return sendSuccess(reply, {
+ apps: rows.map((r) => ({ subdomain: r.subdomain, machineId: r.machineId, url: publicUrl(r.subdomain), createdAt: r.createdAt })),
+ })
+ },
+ )
+
+ app.delete<{ Params: z.infer<typeof subdomainParams> }>(
+ '/api/apps/:subdomain',
+ { preHandler: [agentAuth, validateParams(subdomainParams)] },
+ async (req, reply) => {
+ const { machineId, managerId } = (req as WithAgent).agentCtx!
+ const { subdomain } = req.params
+ const rec = await prisma.subdomain.findUnique({ where: { subdomain } })
+ if (!rec || rec.machineId !== machineId) return sendError(reply, 'not found', 'NOT_FOUND', 404)
+ await provisionViaManager(managerId, 'app_delete', { subdomain }).catch((e) => logger.warn('manager app_delete failed', { subdomain, error: String(e) }))
+ await prisma.subdomain.delete({ where: { subdomain } }).catch(() => { /* gone */ })
+ evictCachedAppTarget(subdomain)
+ return sendSuccess(reply, { deleted: true })
+ },
+ )
+}
diff --git a/backend/src/routes/auth.ts b/backend/src/routes/auth.ts
new file mode 100644
index 000000000..cb7d88b6b
--- /dev/null
+++ b/backend/src/routes/auth.ts
@@ -0,0 +1,202 @@
+import type { FastifyInstance } from 'fastify'
+import { userService } from '../services/index.js'
+import { sendSuccess, sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import { authenticateAccessToken, SsoAuthError } from '../lib/ssoAuth.js'
+import {
+ pkcePair,
+ randomState,
+ createTx,
+ consumeTx,
+ authorizeUrl,
+ logoutUrl,
+ exchangeCode,
+ refreshAccessToken,
+ SsoTokenError,
+ webCallbackUri,
+ isLoopbackRedirectUri,
+ resolveWebOrigin,
+ requestedWebOrigin,
+ type SsoTx,
+} from '../lib/sso.js'
+import { parseAutonomousEnvironment, type AutonomousEnvironment } from '../lib/autonomousEnvironment.js'
+
+export async function authRoutes(app: FastifyInstance): Promise<void> {
+ // 1) Start login (web-driven). The web fetches this (XHR, so the API URL never hits the address
+ // bar), stashes the returned opaque `tx` id in sessionStorage, and navigates the browser to
+ // `authorizeUrl` (the SSO provider). redirect_uri is the WEB callback page, not the API.
+ app.post<{ Body: { next?: string; origin?: string; autonomousEnv?: AutonomousEnvironment } }>('/api/auth/authorize', async (req, reply) => {
+ const { verifier, challenge } = pkcePair()
+ const state = randomState()
+ const next = typeof req.body?.next === 'string' && req.body.next ? req.body.next : '/'
+ const webOrigin = resolveWebOrigin(requestedWebOrigin(req.body ?? {}, req.headers))
+ const redirectUri = webCallbackUri(webOrigin)
+ let autonomousEnv: AutonomousEnvironment
+ try { autonomousEnv = parseAutonomousEnvironment(req.body?.autonomousEnv) } catch {
+ return sendError(reply, 'invalid Autonomous environment', 'INVALID_AUTONOMOUS_ENV', 400)
+ }
+ try {
+ const tx = await createTx({ verifier, state, next, redirectUri, webOrigin, autonomousEnv })
+ return sendSuccess(reply, { authorizeUrl: authorizeUrl(challenge, state, redirectUri, autonomousEnv), tx })
+ } catch {
+ return sendError(reply, 'login transaction service unavailable', 'AUTH_SERVICE_UNAVAILABLE', 503)
+ }
+ })
+
+ // 2) Exchange the SSO code for its access token (web-driven). The web `/auth/callback` page reads
+ // ?code&state + the `tx` it stashed, and POSTs them here (XHR). The BACKEND exchanges the code
+ // then validates the access token through the profile service, mirrors the user and returns that
+ // SAME access token in the body. No backend-owned session JWT is minted.
+ app.post<{ Body: { code?: string; state?: string; tx?: string } }>(
+ '/api/auth/exchange',
+ async (req, reply) => {
+ const { code, state, tx: txRaw } = req.body ?? {}
+ let tx: SsoTx | null = null
+ try {
+ tx = txRaw ? await consumeTx(txRaw) : null
+ } catch {
+ return sendError(reply, 'login transaction service unavailable', 'AUTH_SERVICE_UNAVAILABLE', 503)
+ }
+ if (!code || !state || !tx || tx.state !== state) {
+ return sendError(reply, 'invalid_state', 'INVALID_STATE', 400)
+ }
+ try {
+ const tokens = await exchangeCode(code, tx.verifier, tx.redirectUri, tx.autonomousEnv)
+ const token = tokens.access_token
+ if (!token) throw new Error('sso response had no access_token')
+ const user = await authenticateAccessToken(token, tx.autonomousEnv)
+ logger.info('sso login', {
+ userId: user.sub,
+ email: user.email || '(empty)',
+ autonomousEnv: user.autonomousEnv,
+ hasRefreshToken: !!tokens.refresh_token,
+ expiresIn: tokens.expires_in,
+ })
+ return sendSuccess(reply, {
+ token,
+ next: tx.next,
+ autonomousEnv: tx.autonomousEnv,
+ ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+ ...(typeof tokens.expires_in === 'number' ? { expiresIn: tokens.expires_in } : {}),
+ })
+ } catch (e) {
+ if (e instanceof SsoAuthError && e.code === 'AUTH_SERVICE_UNAVAILABLE') {
+ return sendError(reply, e.message, e.code, 503)
+ }
+ if (e instanceof SsoAuthError &&
+ (e.code === 'AUTONOMOUS_ENV_MISMATCH' || e.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')) {
+ return reply.code(403).send({
+ success: false,
+ error: {
+ code: e.code,
+ message: e.message,
+ ...(e.requiredEnv ? { requiredEnv: e.requiredEnv } : {}),
+ },
+ })
+ }
+ return sendError(reply, e instanceof Error ? e.message : 'sso_failed', 'SSO_FAILED', 502)
+ }
+ },
+ )
+
+ app.post<{ Body: { refreshToken?: string; autonomousEnv?: AutonomousEnvironment } }>(
+ '/api/auth/refresh',
+ async (req, reply) => {
+ const refreshToken = typeof req.body?.refreshToken === 'string' ? req.body.refreshToken.trim() : ''
+ if (!refreshToken) return sendError(reply, 'refresh token is required', 'INVALID_REFRESH_REQUEST', 400)
+
+ let autonomousEnv: AutonomousEnvironment
+ try { autonomousEnv = parseAutonomousEnvironment(req.body?.autonomousEnv) } catch {
+ return sendError(reply, 'invalid Autonomous environment', 'INVALID_AUTONOMOUS_ENV', 400)
+ }
+
+ try {
+ const tokens = await refreshAccessToken(refreshToken, autonomousEnv)
+ const token = tokens.access_token
+ if (!token) throw new SsoTokenError('SSO refresh returned no access token', 'TOKEN_SERVICE_UNAVAILABLE')
+ const user = await authenticateAccessToken(token, autonomousEnv)
+ logger.info('sso token refreshed', {
+ userId: user.sub,
+ autonomousEnv,
+ rotatedRefreshToken: !!tokens.refresh_token,
+ expiresIn: tokens.expires_in,
+ })
+ return sendSuccess(reply, {
+ token,
+ ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+ ...(typeof tokens.expires_in === 'number' ? { expiresIn: tokens.expires_in } : {}),
+ })
+ } catch (e) {
+ if (e instanceof SsoTokenError) {
+ return sendError(
+ reply,
+ e.code === 'INVALID_GRANT' ? 'Refresh token is invalid or expired' : 'Authentication service unavailable',
+ e.code === 'INVALID_GRANT' ? 'REFRESH_TOKEN_INVALID' : 'AUTH_SERVICE_UNAVAILABLE',
+ e.code === 'INVALID_GRANT' ? 401 : 503,
+ )
+ }
+ if (e instanceof SsoAuthError && e.code === 'AUTH_SERVICE_UNAVAILABLE') {
+ return sendError(reply, e.message, e.code, 503)
+ }
+ if (e instanceof SsoAuthError &&
+ (e.code === 'AUTONOMOUS_ENV_MISMATCH' || e.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')) {
+ return reply.code(403).send({
+ success: false,
+ error: {
+ code: e.code,
+ message: e.message,
+ ...(e.requiredEnv ? { requiredEnv: e.requiredEnv } : {}),
+ },
+ })
+ }
+ return sendError(reply, 'Unable to refresh SSO session', 'AUTH_SERVICE_UNAVAILABLE', 503)
+ }
+ },
+ )
+
+ // 1b) Native/desktop-driven login (loopback OAuth). Accepts an explicit loopback redirect_uri so a
+ // desktop client can run a local HTTP listener to capture the SSO callback; unlike the web
+ // authorize, it never derives redirect_uri from a web origin. /exchange reuses tx.redirectUri.
+ app.post<{ Body: { redirectUri?: string; autonomousEnv?: AutonomousEnvironment } }>(
+ '/api/auth/authorize-native',
+ async (req, reply) => {
+ const redirectUri = typeof req.body?.redirectUri === 'string' ? req.body.redirectUri.trim() : ''
+ if (!redirectUri || !isLoopbackRedirectUri(redirectUri)) {
+ return sendError(reply, 'redirectUri must be a loopback address (http://127.0.0.1:<port> or http://localhost:<port>)', 'INVALID_REDIRECT_URI', 400)
+ }
+ let autonomousEnv: AutonomousEnvironment
+ try { autonomousEnv = parseAutonomousEnvironment(req.body?.autonomousEnv) } catch {
+ return sendError(reply, 'invalid Autonomous environment', 'INVALID_AUTONOMOUS_ENV', 400)
+ }
+ try {
+ const { verifier, challenge } = pkcePair()
+ const state = randomState()
+ const webOrigin = new URL(redirectUri).origin
+ const tx = await createTx({ verifier, state, next: '/', redirectUri, webOrigin, autonomousEnv })
+ return sendSuccess(reply, { authorizeUrl: authorizeUrl(challenge, state, redirectUri, autonomousEnv), tx })
+ } catch {
+ return sendError(reply, 'login transaction service unavailable', 'AUTH_SERVICE_UNAVAILABLE', 503)
+ }
+ },
+ )
+
+ // 3) SSO end-session URL (web-driven). The web fetches this (XHR), then navigates the browser to the
+ // returned issuer logout URL — without this the issuer's session cookie survives and the next
+ // login silently auto-completes with the same account. The API URL never hits the address bar.
+ app.get<{ Querystring: { origin?: string; autonomousEnv?: AutonomousEnvironment } }>('/api/auth/logout-url', async (req, reply) => {
+ let autonomousEnv: AutonomousEnvironment
+ try { autonomousEnv = parseAutonomousEnvironment(req.query.autonomousEnv) } catch {
+ return sendError(reply, 'invalid Autonomous environment', 'INVALID_AUTONOMOUS_ENV', 400)
+ }
+ return sendSuccess(reply, {
+ logoutUrl: logoutUrl(resolveWebOrigin(requestedWebOrigin(req.query, req.headers)), autonomousEnv),
+ })
+ })
+
+ // Current session's mirrored user, SSO-access-token gated by the auth middleware.
+ app.get('/api/auth/me', async (req, reply) => {
+ const user = await userService.get(req.user!.sub)
+ if (!user) return sendError(reply, 'user not found', 'NOT_FOUND', 404)
+ return sendSuccess(reply, { user: userService.toPublic(user), avatarUrl: null, description: null })
+ })
+}
diff --git a/backend/src/routes/cursor.ts b/backend/src/routes/cursor.ts
new file mode 100644
index 000000000..702b97717
--- /dev/null
+++ b/backend/src/routes/cursor.ts
@@ -0,0 +1,444 @@
+/**
+ * Everything the Cursor desktop app calls, and nothing else.
+ *
+ * POST /api/cursor/stt `api_key` header, multipart file field `file` → { transcript, lang }
+ * POST /api/cursor/summarize `api_key` header, JSON { prompt } → { text, model }
+ *
+ * DELIBERATELY SELF-CONTAINED. The device's voice path (firmware streams raw PCM over /api/device-ws,
+ * deviceWs.ts hands it to lib/stt.ts) is untouched and unshared: this file owns its own Deepgram call,
+ * its own LLM call, its own auth and its own multipart scope, so nothing here can regress that path
+ * and nothing there constrains this one. The only imports are leaf utilities (env, logger, response,
+ * sha256hex).
+ *
+ * Both routes are in the auth middleware's skip-list — NOT unauthenticated, they simply validate their
+ * own shared secret rather than an SSO token, the same arrangement /api/analytics/report has with
+ * machineAuth. One credential (CURSOR_STT_API_KEY) gates both: the app holds a single key.
+ */
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify'
+import multipart from '@fastify/multipart'
+import { timingSafeEqual } from 'crypto'
+import { env } from '../config/env.js'
+import { sha256hex } from '../utils/crypto.js'
+import { sendSuccess, sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import { VOICE_WAV_LANGS, transcribeWavWithDeepgram } from '../lib/deepgramWav.js'
+
+export const CURSOR_STT_PATH = '/api/cursor/stt'
+export const CURSOR_SUMMARIZE_PATH = '/api/cursor/summarize'
+export const CURSOR_ROUTE_PATH = '/api/cursor/route'
+
+
+/** Most conversations one routing request may weigh. The device sends the ones it is showing, newest
+ * first; past this the prompt grows without the pick getting better. */
+const MAX_ROUTE_AGENTS = 8
+
+/** Per-agent recent-activity text. Enough for three turns' worth of gist, bounded so one chatty agent
+ * cannot crowd the others out of the prompt. */
+const MAX_RECENT_CHARS = 600
+
+/** ~25 MB — far above any dictation clip this serves, while still bounding one request's buffer. */
+const MAX_AUDIO_BYTES = 25 * 1024 * 1024
+
+/** Far above any dictation-sized prompt, but a bound: a looping client must not burn LLM credit. */
+const MAX_PROMPT_CHARS = 100_000
+
+/**
+ * Generation can legitimately think for a while; without a deadline a stalled upstream pins a socket.
+ *
+ * Kept UNDER the gateway's own limit, deliberately. ingress-nginx cuts a proxied response at 60s
+ * (`proxy_read_timeout`), so a 120s budget here could never be honoured: a slow relay produced a bare 504
+ * with no body, and the client saw a generic failure instead of this service's answer. Measured during a
+ * relay degradation — "Say OK" took 49s and a real routing call 504'd at 60.3s. Finishing first is what
+ * lets the fallback below run at all.
+ */
+const LLM_TIMEOUT_MS = 45_000
+
+
+/**
+ * The LLM behind /api/cursor/summarize: an OpenAI-compatible endpoint, called with plain `fetch`.
+ *
+ * No `openai` SDK dependency — with a `base_url` that already ends in `/v1`, the SDK's
+ * `chat.completions.create` is exactly this one POST, so pulling in a package to make it would buy
+ * nothing and cost this file its self-containment.
+ *
+ * Base URL, key and model all come from env: the relay URL embeds a network id and the key is a
+ * long-lived JWT, neither of which belongs in the repo.
+ */
+async function callLlm(prompt: string): Promise<{ text: string; model: string }> {
+ const model = env.CURSOR_LLM_MODEL
+ const res = await fetch(`${env.CURSOR_LLM_BASE_URL!.replace(/\/+$/, '')}/chat/completions`, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${env.CURSOR_LLM_API_KEY}`, 'Content-Type': 'application/json' },
+ // The prompt goes up verbatim as the single user message — no system prompt, no wrapping. What the
+ // app asks for is what the model sees, so changing the wording is a client-side change, not a deploy.
+ body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
+ signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
+ })
+ if (!res.ok) {
+ const detail = await res.text().catch(() => '')
+ throw new Error(`LLM HTTP ${res.status}: ${detail.slice(0, 200)}`)
+ }
+ const data = (await res.json()) as {
+ model?: string
+ choices?: Array<{ message?: { content?: string } }>
+ }
+ return { text: (data.choices?.[0]?.message?.content ?? '').trim(), model: data.model || model }
+}
+
+/**
+ * Both endpoints' only credential: a shared secret in the `api_key` header.
+ *
+ * Fails CLOSED when CURSOR_STT_API_KEY is unset — an absent secret must never read as "no auth needed"
+ * on routes that spend Deepgram and LLM credit. Both sides are hashed before comparison so
+ * timingSafeEqual receives equal-length buffers: it throws on a length mismatch, and the real key's
+ * length is itself something better not leaked through a distinguishable error.
+ */
+async function cursorAuth(req: FastifyRequest, reply: FastifyReply): Promise<void> {
+ const expected = env.CURSOR_STT_API_KEY
+ if (!expected) {
+ logger.error('cursor: CURSOR_STT_API_KEY is not configured — refusing the request')
+ sendError(reply, 'This endpoint is not configured', 'CURSOR_NOT_CONFIGURED', 503)
+ return
+ }
+ // BOTH spellings, and the dashed one is the reason this works in production at all: ingress-nginx
+ // defaults to `underscores_in_headers off`, which DROPS any header containing `_`. So `api_key` — the
+ // name this endpoint was specified with — arrives when you call the service directly and silently
+ // vanishes behind the ingress, surfacing as "Missing api key" for a request that did send it.
+ // Measured, not guessed: on prod a dashed `x-api-key` reaches another route fine while `api_key` does
+ // not, and locally (no proxy) `api_key` works. Keep both — `api_key` for direct/local callers,
+ // `api-key` for anything crossing the ingress.
+ const raw = req.headers['api_key'] ?? req.headers['api-key']
+ const provided = Array.isArray(raw) ? raw[0] : raw
+ if (typeof provided !== 'string' || !provided) {
+ sendError(reply, 'Missing api key', 'UNAUTHORIZED', 401)
+ return
+ }
+ const a = Buffer.from(sha256hex(provided), 'hex')
+ const b = Buffer.from(sha256hex(expected), 'hex')
+ if (!timingSafeEqual(a, b)) {
+ sendError(reply, 'Invalid api key', 'UNAUTHORIZED', 401)
+ return
+ }
+}
+
+/**
+ * Pin the language rather than auto-detect: on a short clip detection is worse than being told.
+ *
+ * Anything unrecognised falls back to 'vi' — this endpoint's callers are Vietnamese-first, and that was
+ * the behaviour before the other five languages were accepted.
+ */
+function pickLang(value: unknown): string {
+ const v = typeof value === 'string' ? value.toLowerCase() : ''
+ return VOICE_WAV_LANGS.has(v) ? v : 'vi'
+}
+
+
+/**
+ * One routing decision, parsed defensively.
+ *
+ * The model behind this endpoint is NOT the one the prompt was written for — the brain's router runs Haiku
+ * through the Claude CLI, this runs whatever CURSOR_LLM_MODEL names (DeepSeek at the time of writing). So
+ * "respond with only JSON" is a request, not a guarantee: a fenced block or a sentence of preamble is a
+ * normal thing to get back, and the caller cannot act on either.
+ */
+function parseDecision(text: string, ids: Set<string>): { agentId: string; confidence: number; reason: string } | null {
+ const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)
+ const body = (fenced ? fenced[1] : text).trim()
+ const brace = body.indexOf('{')
+ const close = body.lastIndexOf('}')
+ if (brace < 0 || close <= brace) return null
+ let obj: unknown
+ try {
+ obj = JSON.parse(body.slice(brace, close + 1))
+ } catch {
+ return null
+ }
+ const o = obj as { agentId?: unknown; confidence?: unknown; reason?: unknown }
+ const agentId = typeof o.agentId === 'string' ? o.agentId : ''
+ // The id MUST be one we offered. A model that invents an id is not a low-confidence pick, it is a failed
+ // request: routing to an id the caller does not have would put the words nowhere and report success.
+ if (!ids.has(agentId)) return null
+ const raw = typeof o.confidence === 'number' ? o.confidence : 0
+ return {
+ agentId,
+ confidence: Math.max(0, Math.min(1, raw)),
+ reason: typeof o.reason === 'string' ? o.reason.slice(0, 120) : '',
+ }
+}
+
+/**
+ * Ported from machine-node/brain's prefrontal/voiceRouter.ts, which routes voice for BACKEND machines and
+ * cannot serve this one: it runs inside a machine-node, and a cabled Cursor machine has no node. Same job,
+ * same shape of answer, so the wording is kept close enough that the two can be compared — including the
+ * instruction not to translate, which is what stops a Vietnamese task coming back as an English summary.
+ */
+function buildRoutePrompt(transcript: string, agents: Array<{ id: string; name: string; recent: string }>): string {
+ const lines = agents
+ .map((a) => `- id=${a.id} | name="${a.name}" | recent: ${a.recent.trim() || '(no activity yet)'}`)
+ .join('\n')
+ return (
+ `You are a ROUTER. Assign ONE incoming voice task to the single best-fit conversation from the fixed ` +
+ `list below. You MUST always choose exactly one id from the list — there is NO "none" option and you ` +
+ `may NOT decline. The NAME is a strong signal. Each conversation's RECENT activity disambiguates when ` +
+ `names alone are ambiguous. If nothing matches well, still pick the CLOSEST one and give it a low ` +
+ `confidence.\n\n` +
+ `Voice task (verbatim; may be Vietnamese — do NOT translate it): "${transcript}"\n\n` +
+ `Conversations:\n${lines}\n\n` +
+ `Set confidence 0..1 for how good the fit is:\n` +
+ `- 0.85+ when the name and/or recent activity clearly match\n` +
+ `- ~0.6 when it is a reasonable but not certain match\n` +
+ `- ~0.3 when nothing fits well but this is the closest.\n\n` +
+ `Respond with ONLY a single JSON object, no prose, no markdown fence:\n` +
+ `{"agentId":"<one id from the list>","confidence":<0..1>,"reason":"<max 12 words>"}`
+ )
+}
+
+export async function cursorRoutes(app: FastifyInstance): Promise<void> {
+ // Registered inside this plugin's scope, not in server.ts: multipart parsing exists for the STT route
+ // and nothing else, so no other endpoint's body handling changes by adding it. The JSON route below
+ // is unaffected — Fastify still parses application/json normally.
+ await app.register(multipart, { limits: { fileSize: MAX_AUDIO_BYTES, files: 1 } })
+
+ app.post(CURSOR_STT_PATH, { preHandler: [cursorAuth] }, async (req, reply) => {
+ let file
+ try {
+ file = await req.file()
+ } catch {
+ sendError(reply, 'Expected a multipart/form-data upload', 'BAD_REQUEST', 400)
+ return
+ }
+ if (!file) {
+ sendError(reply, 'Missing audio file (multipart field "file")', 'NO_FILE', 400)
+ return
+ }
+
+ // Oversize is NOT checked here. @fastify/multipart throws FST_REQ_FILE_TOO_LARGE past the limit and
+ // the shared errorHandler already renders that as a 413 in the usual envelope. An explicit
+ // `file.file.truncated` branch would be dead code — do not add one.
+ const audio = await file.toBuffer()
+ if (audio.length === 0) {
+ sendError(reply, 'Audio file is empty', 'EMPTY_FILE', 400)
+ return
+ }
+
+ // Language may ride the query string or the form; the query wins so a caller can override without
+ // rebuilding the body. Form fields arrive as objects carrying `.value`, not bare strings.
+ const formLang = file.fields?.lang
+ const formLangValue = formLang && !Array.isArray(formLang) && 'value' in formLang ? formLang.value : undefined
+ const lang = pickLang((req.query as { lang?: unknown } | undefined)?.lang ?? formLangValue)
+
+ try {
+ const transcript = await transcribeWavWithDeepgram(audio, file.mimetype || 'audio/wav', lang)
+ logger.info('cursor-stt transcribe', { bytes: audio.length, mimetype: file.mimetype, lang, chars: transcript.length })
+ sendSuccess(reply, { transcript, lang })
+ } catch (err) {
+ // Deepgram's message can name the upstream project/key, so it stays in the log and the caller gets
+ // a plain 502 — this endpoint's one client cannot act on the detail anyway.
+ logger.error('cursor-stt transcribe failed', { error: err instanceof Error ? err.message : String(err) })
+ sendError(reply, 'Transcription failed', 'STT_FAILED', 502)
+ }
+ })
+
+ app.post(CURSOR_SUMMARIZE_PATH, { preHandler: [cursorAuth] }, async (req, reply) => {
+ // Same fail-closed rule as the shared secret: an unconfigured LLM is a 503, never a silent fallback.
+ if (!env.CURSOR_LLM_BASE_URL || !env.CURSOR_LLM_API_KEY) {
+ logger.error('cursor-summarize: CURSOR_LLM_BASE_URL/CURSOR_LLM_API_KEY not configured — refusing')
+ sendError(reply, 'Summarization is not configured', 'LLM_NOT_CONFIGURED', 503)
+ return
+ }
+
+ const prompt = (req.body as { prompt?: unknown } | undefined)?.prompt
+ if (typeof prompt !== 'string' || !prompt.trim()) {
+ sendError(reply, 'Missing prompt', 'BAD_REQUEST', 400)
+ return
+ }
+ if (prompt.length > MAX_PROMPT_CHARS) {
+ sendError(reply, `Prompt exceeds ${MAX_PROMPT_CHARS} characters`, 'PROMPT_TOO_LARGE', 400)
+ return
+ }
+
+ try {
+ const { text, model } = await callLlm(prompt)
+ logger.info('cursor-summarize', { chars: prompt.length, outChars: text.length, model })
+ sendSuccess(reply, { text, model })
+ } catch (err) {
+ // Same reasoning as the STT branch: the upstream message can name the relay network or the key,
+ // so it stays in the log and the caller gets a plain 502.
+ logger.error('cursor-summarize failed', { error: err instanceof Error ? err.message : String(err) })
+ sendError(reply, 'Summarization failed', 'LLM_FAILED', 502)
+ }
+ })
+
+ /**
+ * Pick which Cursor conversation a spoken task belongs to.
+ *
+ * The cabled machine's Overview voice: the dial records, the Mac ships the audio to /stt above, then asks
+ * here which of its open conversations should receive the words. The decision is a pure function of what
+ * the caller sends — this endpoint holds no state and knows nothing about any machine.
+ */
+/**
+ * Function words only. A preposition matching a name is noise wearing a signal's clothes — verbs and nouns
+ * stay, because "research", "deploy" and "parser" are exactly what routing runs on. The last row is the
+ * Vietnamese equivalents, which arrive unaccented from the tokenizer below.
+ */
+const ROUTE_STOP = new Set([
+ 'the', 'a', 'an', 'and', 'or', 'for', 'to', 'of', 'in', 'on', 'at',
+ 'about', 'with', 'from', 'into', 'over', 'under', 'up', 'down', 'out',
+ 'my', 'our', 'your', 'his', 'her', 'its', 'their', 'me', 'you', 'we',
+ 'it', 'this', 'that', 'these', 'those', 'is', 'are', 'was', 'were',
+ 'be', 'been', 'do', 'does', 'did', 'have', 'has', 'had', 'will',
+ 'would', 'can', 'could', 'should', 'please', 'what', 'when', 'where',
+ 'which', 'who', 'how', 'why',
+ 'agent', 'task', 'chat', 'new', 'cua', 'va', 'cho', 'voi',
+])
+
+/**
+ * Fold to the alphabet the matcher works in: lowercase, unaccented, split on anything that is not a letter
+ * or digit.
+ *
+ * Unaccented because a spoken "sửa parser" transcribed by an English recogniser arrives as "sua parser",
+ * and a conversation named "Sửa parser" would otherwise never match itself. `đ` needs its own rule — NFD
+ * does not decompose it, so stripping combining marks alone leaves "đăng" as "đang" and never as "dang".
+ */
+function routeTokens(s: string): string[] {
+ return s
+ .normalize('NFD')
+ .replace(/[\u0300-\u036f]/g, '')
+ .replace(/đ/gi, 'd')
+ .toLowerCase()
+ .split(/[^a-z0-9]+/)
+ .filter((t) => t.length > 1 && !ROUTE_STOP.has(t))
+}
+
+/**
+ * The name is worth far more than the history, and deliberately so: people name conversations by what they
+ * are for, and say what they want done. Recent activity is a tie-breaker for names that do not settle it.
+ * Normalised by the NAME's length, not the sentence's — matching both words of a two-word name is a strong
+ * signal, and dividing by a long sentence would bury it.
+ */
+function scoreAgent(a: { name: string; recent: string }, said: Set<string>) {
+ const name = new Set(routeTokens(a.name))
+ const recent = new Set(routeTokens(a.recent))
+ if (said.size === 0) return { score: 0, named: 0 }
+ const hits = (set: Set<string>) => [...set].filter((t) => said.has(t)).length
+ const nameHits = hits(name)
+ const nameScore = name.size === 0 ? 0 : nameHits / name.size
+ const recentScore = recent.size === 0 ? 0 : Math.min(hits(recent) / 3, 1)
+ return { score: nameScore * 3 + recentScore, named: nameHits }
+}
+
+/**
+ * Decide by counting words, and say when counting is not enough.
+ *
+ * A PORT of QuickDialKit/VoiceRouter.swift in autonomous-macroz, thresholds included — it was measured
+ * against real misroutes there, and this endpoint answers the same question for the same device. The
+ * reason it exists here rather than only in the model: an LLM call is a network dependency on every spoken
+ * turn, and when the relay degrades (49s for "Say OK", measured) an unambiguous name match should not be
+ * waiting on it at all.
+ *
+ * THE NAME OUTRANKS THE TOPIC. Saying words from exactly one conversation's name IS the decision, however
+ * much another one's recent activity overlaps the subject: a name is chosen by the user, a topic history
+ * accretes — and accretes fastest on whichever conversation earlier misroutes fed.
+ */
+function pickByScore(transcript: string, agents: Array<{ id: string; name: string; recent: string }>) {
+ const said = new Set(routeTokens(transcript))
+ const scored = agents.map((a) => ({ a, ...scoreAgent(a, said) }))
+
+ // Several names said: they compete among THEMSELVES — a conversation matched only by topic does not
+ // referee a contest between named ones.
+ const named = scored.filter((s) => s.named > 0)
+ if (named.length === 1) {
+ const only = named[0]
+ return { agentId: only.a.id, confidence: Math.max(0.8, Math.min(1, 0.6 + only.score / 6)),
+ reason: 'only name said', ambiguous: false }
+ }
+ const pool = named.length > 1 ? named : scored
+ const ranked = [...pool].sort((x, y) => y.score - x.score)
+ const top = ranked[0]
+ const gap = top.score - (ranked[1]?.score ?? 0)
+
+ // Nothing scored at all: the words matched no name and no history, so there is nothing to be confident
+ // about and the model gets it.
+ if (top.score <= 0) return { agentId: top.a.id, confidence: 0, reason: 'nothing matched', ambiguous: true }
+ // A clear winner both scores something AND leads the runner-up by half a name-word. Below that the two
+ // are not distinguishable by counting words, which is the definition of a question for a model.
+ if (gap >= 1.5) return { agentId: top.a.id, confidence: Math.min(1, 0.6 + gap / 6),
+ reason: 'name matched', ambiguous: false }
+ return { agentId: top.a.id, confidence: 0.3 + gap / 5, reason: 'closest of several', ambiguous: true }
+}
+
+ app.post(CURSOR_ROUTE_PATH, { preHandler: [cursorAuth] }, async (req, reply) => {
+ if (!env.CURSOR_LLM_BASE_URL || !env.CURSOR_LLM_API_KEY) {
+ logger.error('cursor-route: CURSOR_LLM_BASE_URL/CURSOR_LLM_API_KEY not configured — refusing')
+ sendError(reply, 'Routing is not configured', 'LLM_NOT_CONFIGURED', 503)
+ return
+ }
+
+ const body = req.body as { transcript?: unknown; agents?: unknown } | undefined
+ const transcript = typeof body?.transcript === 'string' ? body.transcript.trim() : ''
+ if (!transcript) {
+ sendError(reply, 'Missing transcript', 'BAD_REQUEST', 400)
+ return
+ }
+ if (!Array.isArray(body?.agents) || body.agents.length === 0) {
+ sendError(reply, 'Missing agents', 'BAD_REQUEST', 400)
+ return
+ }
+
+ const agents = (body.agents as Array<Record<string, unknown>>)
+ .map((a) => ({
+ id: typeof a.id === 'string' ? a.id : '',
+ name: typeof a.name === 'string' ? a.name : '',
+ recent: typeof a.recent === 'string' ? a.recent.slice(0, MAX_RECENT_CHARS) : '',
+ }))
+ .filter((a) => a.id && a.name)
+ .slice(0, MAX_ROUTE_AGENTS)
+ if (agents.length === 0) {
+ sendError(reply, 'No usable agents', 'BAD_REQUEST', 400)
+ return
+ }
+
+ // One conversation is not a decision. Answering it locally saves a call, and more importantly it means
+ // the single-agent case cannot fail for a reason that has nothing to do with the user.
+ if (agents.length === 1) {
+ sendSuccess(reply, { agentId: agents[0].id, confidence: 1, reason: 'only conversation' })
+ return
+ }
+
+ // Count words first. Most spoken turns name the conversation they are about, and for those the model
+ // adds latency and a failure mode without adding an answer.
+ const scored = pickByScore(transcript, agents)
+ if (!scored.ambiguous) {
+ logger.info('cursor-route: by score', { agents: agents.length, chars: transcript.length, reason: scored.reason })
+ sendSuccess(reply, { agentId: scored.agentId, confidence: scored.confidence, reason: scored.reason })
+ return
+ }
+
+ try {
+ const { text, model } = await callLlm(buildRoutePrompt(transcript, agents))
+ const decision = parseDecision(text, new Set(agents.map((a) => a.id)))
+ if (!decision) {
+ logger.error('cursor-route: unusable answer', { model, sample: text.slice(0, 200) })
+ sendError(reply, 'Routing failed', 'ROUTE_FAILED', 502)
+ return
+ }
+ logger.info('cursor-route', { agents: agents.length, chars: transcript.length, model, confidence: decision.confidence })
+ sendSuccess(reply, decision)
+ } catch (err) {
+ // The model was the TIE-BREAKER, not the router. When it cannot answer, the scored pick is still the
+ // best information available, and returning it beats throwing away words the user has already spoken
+ // — the device's alternative is an apology and a lost turn.
+ //
+ // Only when something actually matched, though: `nothing matched` means the words hit no name and no
+ // history, and delivering that to an arbitrary conversation is worse than saying so.
+ logger.error('cursor-route failed', { error: err instanceof Error ? err.message : String(err) })
+ if (scored.confidence > 0) {
+ logger.warn('cursor-route: falling back to the scored pick', { reason: scored.reason })
+ sendSuccess(reply, { agentId: scored.agentId, confidence: scored.confidence,
+ reason: `${scored.reason} (model unavailable)` })
+ return
+ }
+ sendError(reply, 'Routing failed', 'ROUTE_FAILED', 502)
+ }
+ })
+}
diff --git a/backend/src/routes/deviceAuth.ts b/backend/src/routes/deviceAuth.ts
new file mode 100644
index 000000000..ec2898497
--- /dev/null
+++ b/backend/src/routes/deviceAuth.ts
@@ -0,0 +1,183 @@
+import type { FastifyInstance } from 'fastify'
+import type { Machine } from '@prisma/client'
+import { prisma, machineAlive } from '../lib/prisma.js'
+import { machineService } from '../services/MachineService.js'
+import { userService } from '../services/UserService.js'
+import { storedAutonomousEnvironment } from '../lib/autonomousEnvironment.js'
+import { AppError } from '../errors/index.js'
+import { sendSuccess, sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import {
+ startDeviceAuth, pollDeviceAuth, findByUserCode, resolveDeviceAuth, normalizeUserCode,
+ normalizeComputerId, claimDeviceAuth, releaseDeviceAuthClaim,
+} from '../lib/deviceAuth.js'
+
+/**
+ * Device-authorization grant for clients that cannot do a browser redirect — the `harness` CLI and the
+ * desktop app (see lib/deviceAuth.ts for why it exists).
+ *
+ * app → POST /api/device-auth/start (no auth) → { userCode, deviceCode }
+ * user → web page, signed in → POST /api/device-auth/approve { userCode, machineId? }
+ * app → POST /api/device-auth/poll (no auth) → { status: pending | approved + apiKey }
+ *
+ * `machineId` is optional, and the two shapes are different products:
+ * WITH it — the Mac app's picker. The user chose a machine they already own; nothing is created.
+ * WITHOUT it — the CLI's `harness auth device`. The server answers with the machine already bound to
+ * the asking computer, or makes one. See machineService.resolveOrCreateForComputer.
+ *
+ * start/poll are unauthenticated BY DESIGN — the app has no credential yet, which is the whole point.
+ * They are safe because neither reveals anything: `start` returns codes it just minted, and `poll`
+ * requires the 32-byte device code and hands its payload over exactly once.
+ */
+export async function deviceAuthRoutes(app: FastifyInstance): Promise<void> {
+ // ── app: begin ───────────────────────────────────────────────────────────────────────────────────
+ app.post<{ Body: { computerId?: string; label?: string } }>('/api/device-auth/start', async (req, reply) => {
+ const computerId = normalizeComputerId(String(req.body?.computerId ?? ''))
+ const label = String(req.body?.label ?? '').trim().slice(0, 120)
+ if (!computerId) {
+ return sendError(reply, 'computerId must be a hex computer fingerprint', 'BAD_REQUEST', 400)
+ }
+ const out = await startDeviceAuth(computerId, label || 'computer')
+ return sendSuccess(reply, {
+ userCode: out.userCode,
+ deviceCode: out.deviceCode,
+ expiresIn: out.expiresInSec,
+ interval: out.intervalSec,
+ })
+ })
+
+ // ── app: poll ────────────────────────────────────────────────────────────────────────────────────
+ app.post<{ Body: { deviceCode?: string } }>('/api/device-auth/poll', async (req, reply) => {
+ const deviceCode = String(req.body?.deviceCode ?? '')
+ if (!/^[a-f0-9]{64}$/.test(deviceCode)) return sendError(reply, 'bad device code', 'BAD_REQUEST', 400)
+ const record = await pollDeviceAuth(deviceCode)
+ // Expired or already consumed. Deliberately the same answer for both: a caller holding a stale code
+ // learns nothing about whether it was ever valid.
+ if (!record) return sendSuccess(reply, { status: 'expired' })
+ if (record.state === 'pending') return sendSuccess(reply, { status: 'pending' })
+ if (record.state === 'denied') return sendSuccess(reply, { status: 'denied', error: record.error })
+ return sendSuccess(reply, { status: 'approved', apiKey: record.apiKey, machineId: record.machineId })
+ })
+
+ // ── web: what am I approving? (SSO-authed) ───────────────────────────────────────────────────────
+ // Shown before the user commits, so they can see WHICH computer is asking and pick the machine.
+ app.get<{ Querystring: { userCode?: string } }>('/api/device-auth/lookup', async (req, reply) => {
+ const found = await findByUserCode(String(req.query?.userCode ?? ''))
+ if (!found) return sendError(reply, 'that code is not valid or has expired', 'NOT_FOUND', 404)
+ if (found.record.state !== 'pending') return sendError(reply, 'that code has already been used', 'GONE', 410)
+
+ // Only machines the user could actually adapt: `remote` is the one authMode /api/adapter-ws accepts.
+ const machines = await prisma.machine.findMany({
+ where: { userId: req.user!.sub, authMode: 'remote', ...machineAlive },
+ orderBy: { createdAt: 'asc' },
+ })
+ return sendSuccess(reply, {
+ label: found.record.label,
+ computerId: found.record.computerId,
+ machines: machines.map((m) => ({
+ machineId: m.machineId,
+ name: m.name?.trim() || m.hostname || m.machineId.slice(0, 8),
+ hostname: m.hostname,
+ // The app supersedes whatever adapter currently holds a machine, so surface which one this
+ // computer has used before — reconnecting the same box is safe, taking someone else's is not.
+ isThisComputer: !!m.computerId && m.computerId === found.record.computerId,
+ billingBlocked: m.billingStatus === 'pending' || m.billingStatus === 'suspended',
+ })),
+ })
+ })
+
+ // ── web: approve (SSO-authed) ────────────────────────────────────────────────────────────────────
+ app.post<{ Body: { userCode?: string; machineId?: string } }>('/api/device-auth/approve', async (req, reply) => {
+ const found = await findByUserCode(String(req.body?.userCode ?? ''))
+ if (!found) return sendError(reply, 'that code is not valid or has expired', 'NOT_FOUND', 404)
+ if (found.record.state !== 'pending') return sendError(reply, 'that code has already been used', 'GONE', 410)
+
+ // Exclusive ownership BEFORE anything that can create a machine. Two approvals racing the same code
+ // used to both pass the `pending` check above and both create — see lib/deviceAuth.ts.
+ if (!(await claimDeviceAuth(found.deviceHash))) {
+ return sendError(reply, 'that code is already being used', 'GONE', 410)
+ }
+
+ const machineId = String(req.body?.machineId ?? '').trim()
+ let machine: Machine | null
+ let created = false
+
+ // Any failure past this point hands the claim back, so the user can fix the problem (finish a
+ // checkout, pick a different machine) and retry the SAME code while it is still alive.
+ const giveUp = async (message: string, code: string, status: number): Promise<void> => {
+ await releaseDeviceAuthClaim(found.deviceHash)
+ return sendError(reply, message, code, status)
+ }
+
+ if (machineId) {
+ // ── explicit pick (the Mac app) ────────────────────────────────────────────────────────────
+ // This branch deliberately NEVER creates a machine. Picking one from a list must not be able to
+ // start a paid subscription behind the user's back: they choose one they already own, and if
+ // they own none the web sends them through the normal purchase flow first. This is also why
+ // Cursor costs nothing extra — it reuses the Remote machine the user already bought.
+ machine = await prisma.machine.findFirst({
+ where: { machineId, userId: req.user!.sub, ...machineAlive },
+ })
+ if (!machine) return giveUp('machine not found', 'NOT_FOUND', 404)
+ if (machine.authMode !== 'remote') {
+ return giveUp('that machine is not a Remote machine', 'NOT_REMOTE', 400)
+ }
+ if (machine.billingStatus === 'pending' || machine.billingStatus === 'suspended') {
+ return giveUp('that machine needs its subscription completed first', 'BILLING', 402)
+ }
+ // Bind the asking computer to it, so a later `harness auth device` from the same box lands here
+ // instead of minting a second machine.
+ if (machine.computerId !== found.record.computerId) {
+ await prisma.machine.update({
+ where: { machineId: machine.machineId },
+ data: { computerId: found.record.computerId },
+ }).catch(() => { /* best effort — the adapter-ws connect stamps it too */ })
+ }
+ } else {
+ // ── no pick (the CLI) ──────────────────────────────────────────────────────────────────────
+ // The computer is the subject: reuse the machine already bound to it, else make one. Free, so
+ // there is nothing to charge and no checkout to run.
+ const owner = await userService.get(req.user!.sub)
+ if (!owner) return giveUp('user not found', 'NOT_FOUND', 404)
+ try {
+ const out = await machineService.resolveOrCreateForComputer(
+ req.user!.sub,
+ storedAutonomousEnvironment(owner.autonomousEnv),
+ found.record.computerId,
+ found.record.label,
+ )
+ machine = out.machine
+ created = out.created
+ } catch (err) {
+ await releaseDeviceAuthClaim(found.deviceHash)
+ if (err instanceof AppError) return sendError(reply, err.message, err.code ?? 'ERROR', err.statusCode)
+ throw err
+ }
+ }
+
+ await resolveDeviceAuth(found.deviceHash, {
+ state: 'approved',
+ machineId: machine.machineId,
+ apiKey: machine.apiKey,
+ userId: req.user!.sub,
+ })
+ logger.info('device-auth approved', {
+ userId: req.user!.sub, machineId: machine.machineId, computerId: found.record.computerId, created,
+ })
+ return sendSuccess(reply, {
+ machineId: machine.machineId,
+ machineName: machine.name?.trim() || machine.hostname || null,
+ created,
+ })
+ })
+
+ // ── web: deny (SSO-authed) ───────────────────────────────────────────────────────────────────────
+ app.post<{ Body: { userCode?: string } }>('/api/device-auth/deny', async (req, reply) => {
+ const found = await findByUserCode(String(req.body?.userCode ?? ''))
+ if (!found) return sendError(reply, 'that code is not valid or has expired', 'NOT_FOUND', 404)
+ await resolveDeviceAuth(found.deviceHash, { state: 'denied', error: 'declined on the web' })
+ return sendSuccess(reply, { ok: true })
+ })
+}
+
+export { normalizeUserCode }
diff --git a/backend/src/routes/devices.ts b/backend/src/routes/devices.ts
new file mode 100644
index 000000000..0d1833789
--- /dev/null
+++ b/backend/src/routes/devices.ts
@@ -0,0 +1,35 @@
+import type { FastifyInstance } from 'fastify'
+import { z } from 'zod'
+import { deviceService } from '../services/index.js'
+import { validateParams } from '../middlewares/validation.js'
+import { sendSuccess, sendError } from '../utils/response.js'
+import { revokeDeviceForUser } from '../lib/deviceRevoke.js'
+
+// A device is a COMPUTER running the `harness` daemon. It comes into existence by connecting to
+// /api/device-ws with its owner's SSO token and a `?computer=` id — there is no pairing handshake, no
+// device token and no OTA gate here any more, so both of the old public endpoints are gone and every
+// route below is SSO-gated like the rest of the control plane.
+
+const deviceParams = z.object({ deviceId: z.string().min(1) })
+
+export async function deviceRoutes(app: FastifyInstance): Promise<void> {
+ app.get('/api/devices', async (req, reply) => {
+ const devices = await deviceService.listForUser(req.user!.sub)
+ return sendSuccess(reply, { devices })
+ })
+
+ // FORGETS a dial; it is not a revocation. The row is deleted and the live socket is closed, but the
+ // daemon on that computer re-creates it on its next connect — the credential is the owner's SSO
+ // session, which this cannot touch. Naming it "revoke" in the UI would promise something it does not do.
+ app.delete<{ Params: z.infer<typeof deviceParams> }>(
+ '/api/devices/:deviceId',
+ { preHandler: validateParams(deviceParams) },
+ async (req, reply) => {
+ // Delete + all three revoke pushes live in revokeDeviceForUser — the mobile group calls the same
+ // helper, so the two surfaces cannot drift into revoking a device that keeps its socket.
+ const ok = await revokeDeviceForUser(req.params.deviceId, req.user!.sub)
+ if (!ok) return sendError(reply, 'Device not found', 'NOT_FOUND', 404)
+ return sendSuccess(reply, { deleted: true })
+ },
+ )
+}
diff --git a/backend/src/routes/health.ts b/backend/src/routes/health.ts
new file mode 100644
index 000000000..60ef325fa
--- /dev/null
+++ b/backend/src/routes/health.ts
@@ -0,0 +1,8 @@
+import type { FastifyInstance } from 'fastify'
+
+export async function healthRoutes(app: FastifyInstance): Promise<void> {
+ app.get('/api/health', async () => ({
+ success: true,
+ data: { status: 'ok' },
+ }))
+}
diff --git a/backend/src/routes/index.ts b/backend/src/routes/index.ts
new file mode 100644
index 000000000..41538a50f
--- /dev/null
+++ b/backend/src/routes/index.ts
@@ -0,0 +1,10 @@
+export * from './health.js'
+export * from './auth.js'
+export * from './users.js'
+export * from './machines.js'
+export * from './plans.js'
+export * from './devices.js'
+export * from './mobile.js'
+export * from './apps.js'
+export * from './analytics.js'
+export * from './agentRoute.js'
diff --git a/backend/src/routes/machines.ts b/backend/src/routes/machines.ts
new file mode 100644
index 000000000..1de95d026
--- /dev/null
+++ b/backend/src/routes/machines.ts
@@ -0,0 +1,383 @@
+import type { FastifyInstance } from 'fastify'
+import { z } from 'zod'
+import { machineService, machineBillingService, userService } from '../services/index.js'
+import { prisma } from '../lib/prisma.js'
+import { machineIdFromKey } from '../utils/crypto.js'
+import { validateBody, validateParams, validateQuery } from '../middlewares/validation.js'
+import { isMachineId } from '../utils/slug.js'
+import { sendSuccess, sendCreated, sendError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import { bearerToken } from '../lib/ssoAuth.js'
+import { requestedWebOrigin, resolveWebOrigin } from '../lib/sso.js'
+import { storedAutonomousEnvironment } from '../lib/autonomousEnvironment.js'
+import { env } from '../config/env.js'
+import { probeProvider, ProviderProbeError } from '../lib/providerProbe.js'
+import { normalizeComputerId } from '../lib/deviceAuth.js'
+
+const createBody = z.object({
+ // Defaults to the caller; admins may provision for another user.
+ userId: z.string().min(1).optional(),
+ workspaceId: z.string().optional(),
+ // Subscription plan id — REQUIRED: the caller must pick a tier. cpus/memory + authMode come from it.
+ planId: z.string().min(1),
+ // `provider` tier only. Both are REQUIRED when the chosen plan is a provider plan and REJECTED
+ // otherwise — enforced in the handler, where the plan's authMode is known. The URL is checked by
+ // lib/providerUrl.ts and the pair is proven live before anything is written.
+ providerUrl: z.string().trim().min(1).max(2048).optional(),
+ providerCredential: z.string().trim().min(1).max(4096).optional(),
+})
+
+const machineParams = z.object({
+ machineId: z.string().refine(isMachineId, 'Invalid machineId'),
+})
+const resolveMachineQuery = z.object({
+ deviceId: z.string().trim().min(1).max(128),
+})
+const resolveComputerBody = z.object({
+ computerId: z.string().trim().min(1).max(128),
+ label: z.string().trim().max(120).optional(),
+ // The machine id the caller still holds, when it has one. Lets the service answer 403 to a daemon
+ // whose machine was deleted instead of quietly minting it a new one. Absent on a first pairing.
+ machineId: z.string().trim().max(64).optional(),
+})
+
+// Rename: writes the machine's `name`. 40 chars max — the device picker's per-row buffer.
+// Empty string clears back to the default `machine-<id8>`.
+const renameBody = z.object({
+ name: z.string().trim().max(40),
+})
+const activateBody = z.object({
+ sessionId: z.string().min(1).optional(),
+ referenceCode: z.string().trim().min(1).max(128).optional(),
+})
+const billingCheckoutBody = z.object({ planId: z.string().min(1) })
+const billingCompleteBody = z.object({
+ operationId: z.string().uuid(),
+ outcome: z.enum(['success', 'cancelled']),
+ referenceCode: z.string().trim().min(1).max(128).optional(),
+})
+
+function requestAccessToken(authorization: string | undefined): string {
+ const token = bearerToken(authorization)
+ if (!token) throw new Error('Authenticated request is missing its SSO access token')
+ return token
+}
+
+function requestWebOrigin(req: { headers: Record<string, string | string[] | undefined> }): string {
+ return resolveWebOrigin(requestedWebOrigin({}, req.headers))
+}
+
+export async function machineRoutes(app: FastifyInstance): Promise<void> {
+ // Validate an agent api key (NOT JWT). Public + agent-key gated: derive machineId = sha256(key)[:32]
+ // and confirm an AgentBinding exists. Used by the shared CCR gateway to authorize an agent-node's
+ // Claude CLI (bearer `sk-ccr-<API_KEY>`). In the auth-middleware skip-list. Returns the machineId
+ // (safe public identity) — never echoes the raw key.
+ app.post('/api/machines/validate', async (req, reply) => {
+ const key = req.headers['x-api-key']
+ if (typeof key !== 'string' || !key) {
+ return sendError(reply, 'Missing agent api key', 'UNAUTHORIZED', 401)
+ }
+ const machineId = machineIdFromKey(key)
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt) {
+ return sendError(reply, 'Unknown machine', 'NO_MACHINE', 404)
+ }
+ if (binding.billingStatus === 'pending') {
+ return sendError(reply, 'Machine payment is pending', 'MACHINE_PAYMENT_PENDING', 409)
+ }
+ if (binding.billingStatus === 'suspended') {
+ return sendError(reply, 'Machine subscription is required', 'MACHINE_SUBSCRIPTION_REQUIRED', 402)
+ }
+ if (binding.billingStatus === 'active' && binding.authMode === 'managed') {
+ return sendError(reply, 'Externally billed machines use their campaign credential directly', 'CCR_NOT_ALLOWED', 403)
+ }
+ return sendSuccess(reply, { valid: true, machineId: machineId, userId: binding.userId, managerId: binding.managerId })
+ })
+
+ // Provision a node for the caller (or, if admin, for `userId`).
+ app.post<{ Body: z.infer<typeof createBody> }>(
+ '/api/machines',
+ { preHandler: validateBody(createBody) },
+ async (req, reply) => {
+ const isAdmin = req.user!.role === 'admin'
+ const userId = isAdmin && req.body.userId ? req.body.userId : req.user!.sub
+ const owner = userId === req.user!.sub ? await userService.get(req.user!.sub) : await userService.get(userId)
+ if (!owner) return sendError(reply, 'User not found', 'NOT_FOUND', 404)
+ const autonomousEnv = storedAutonomousEnvironment(owner.autonomousEnv)
+ if (userId !== req.user!.sub) {
+ const plan = await prisma.subscriptionPlan.findUnique({
+ where: { id: req.body.planId },
+ select: { authMode: true, autonomousEnv: true },
+ })
+ // External device/subscription ownership is derived from the caller's SSO access token and
+ // email. An admin therefore cannot start a campaign checkout on behalf of another account;
+ // doing so would permanently bind that user's machine to the admin's campaign device.
+ if (!plan || plan.autonomousEnv !== autonomousEnv ||
+ (env.HARNESS_BILLING_ENABLED && (plan.authMode === 'managed' || plan.authMode === 'remote' || plan.authMode === 'provider'))) {
+ return sendError(
+ reply,
+ 'Billed machines must be created by the subscription owner',
+ 'BILLING_OWNER_REQUIRED',
+ 403,
+ )
+ }
+ }
+ // A provider machine needs a URL and a credential, and BOTH are proven live before anything is
+ // written. Skipping the probe would make a wrong credential indistinguishable from an outage —
+ // the machine would look created and only fail on the first message.
+ const chosenPlan = await prisma.subscriptionPlan.findUnique({
+ where: { id: req.body.planId },
+ select: { authMode: true },
+ })
+ const wantsProvider = chosenPlan?.authMode === 'provider'
+ if (!wantsProvider && (req.body.providerUrl || req.body.providerCredential)) {
+ return sendError(reply, 'Provider details are only valid on a Provider plan', 'PROVIDER_NOT_APPLICABLE', 400)
+ }
+ let provider: { url: string; credential: string } | undefined
+ if (wantsProvider) {
+ if (!req.body.providerUrl || !req.body.providerCredential) {
+ return sendError(reply, 'A Provider machine needs a provider URL and credential', 'PROVIDER_DETAILS_REQUIRED', 400)
+ }
+ try {
+ const probe = await probeProvider(req.body.providerUrl, req.body.providerCredential)
+ provider = { url: probe.url, credential: req.body.providerCredential }
+ } catch (err) {
+ // Each failure has its own code because each has a different fix: change the URL, wait,
+ // pick another provider, or paste the right credential.
+ if (err instanceof ProviderProbeError) return sendError(reply, err.message, err.code, 400)
+ throw err
+ }
+ }
+
+ const agent = await machineService.create(userId, req.body.workspaceId, {
+ planId: req.body.planId,
+ autonomousEnv,
+ ...(provider ? { provider } : {}),
+ })
+ const checkout = agent.billingStatus === 'pending'
+ ? await machineBillingService.beginCheckout(
+ agent.machineId,
+ userId,
+ req.user!.email,
+ requestAccessToken(req.headers.authorization),
+ requestWebOrigin(req),
+ req.user!.autonomousEnv,
+ )
+ : undefined
+ return sendCreated(reply, { machine: agent, ...(checkout ? { checkout } : {}) })
+ },
+ )
+
+ // Continue a pending campaign machine with a fresh hosted checkout. Free uses the same endpoint to
+ // collect a card without charging it; an older attempt never prevents another explicit attempt.
+ app.post<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId/checkout',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ const checkout = await machineBillingService.beginCheckout(
+ req.params.machineId,
+ req.user!.sub,
+ req.user!.email,
+ requestAccessToken(req.headers.authorization),
+ requestWebOrigin(req),
+ req.user!.autonomousEnv,
+ )
+ return sendSuccess(reply, { checkout })
+ },
+ )
+
+ // Legacy payment callback verifier. Idempotent completion uses an authoritative
+ // device/subscription exact-match read; no separate checkout-complete endpoint is required.
+ app.post<{ Params: z.infer<typeof machineParams>; Body: z.infer<typeof activateBody> }>(
+ '/api/machines/:machineId/activate',
+ { preHandler: [validateParams(machineParams), validateBody(activateBody)] },
+ async (req, reply) => {
+ await machineBillingService.activate(
+ req.params.machineId,
+ req.user!.sub,
+ req.user!.email,
+ requestAccessToken(req.headers.authorization),
+ requestWebOrigin(req),
+ req.body.sessionId,
+ req.body.referenceCode,
+ req.user!.autonomousEnv,
+ )
+ const machine = await machineService.get(req.params.machineId, req.user!)
+ return sendSuccess(reply, { machine })
+ },
+ )
+
+ // Owner-only managed-plan view. Refreshes subscription metadata with the caller's short-lived SSO
+ // token but never persists that token; on a transient upstream failure it returns cached metadata.
+ app.get<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId/billing',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ const billing = await machineBillingService.getBilling(
+ req.params.machineId,
+ req.user!.sub,
+ requestAccessToken(req.headers.authorization),
+ req.user!.autonomousEnv,
+ )
+ return sendSuccess(reply, { billing })
+ },
+ )
+
+ // Start Free→paid subscribe, paid↔paid upgrade/downgrade, or Suspended→paid re-subscribe.
+ app.post<{ Params: z.infer<typeof machineParams>; Body: z.infer<typeof billingCheckoutBody> }>(
+ '/api/machines/:machineId/billing/checkout',
+ { preHandler: [validateParams(machineParams), validateBody(billingCheckoutBody)] },
+ async (req, reply) => {
+ const checkout = await machineBillingService.beginPlanCheckout(
+ req.params.machineId,
+ req.user!.sub,
+ req.body.planId,
+ req.user!.email,
+ requestAccessToken(req.headers.authorization),
+ requestWebOrigin(req),
+ req.user!.autonomousEnv,
+ )
+ return sendSuccess(reply, { checkout })
+ },
+ )
+
+ // Shared callback verifier for initial subscribe and later plan changes. Stripe cancellation only
+ // closes the local operation; it never mutates the machine's currently effective plan.
+ app.post<{ Params: z.infer<typeof machineParams>; Body: z.infer<typeof billingCompleteBody> }>(
+ '/api/machines/:machineId/billing/complete',
+ { preHandler: [validateParams(machineParams), validateBody(billingCompleteBody)] },
+ async (req, reply) => {
+ const billing = await machineBillingService.complete(
+ req.params.machineId,
+ req.user!.sub,
+ requestAccessToken(req.headers.authorization),
+ req.body.operationId,
+ req.body.outcome,
+ req.user!.autonomousEnv,
+ )
+ return sendSuccess(reply, { billing })
+ },
+ )
+
+ app.post<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId/billing/cancel',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ const billing = await machineBillingService.cancel(
+ req.params.machineId,
+ req.user!.sub,
+ requestAccessToken(req.headers.authorization),
+ req.user!.autonomousEnv,
+ )
+ return sendSuccess(reply, { billing })
+ },
+ )
+
+ app.post<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId/billing/renew',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ const billing = await machineBillingService.renew(
+ req.params.machineId,
+ req.user!.sub,
+ requestAccessToken(req.headers.authorization),
+ req.user!.autonomousEnv,
+ )
+ return sendSuccess(reply, { billing })
+ },
+ )
+
+ // List the caller's agent(s).
+ app.get('/api/machines', async (req, reply) => {
+ const bindings = await machineService.listForUser(req.user!.sub, req.user!.autonomousEnv)
+ return sendSuccess(reply, { machines: bindings })
+ })
+
+ // Canonical Remote-machine lookup for an authenticated Harness CLI. The computer id is stable
+ // across CLI restarts, so this is also the first-time create path before the adapter WebSocket dials.
+ app.post<{ Body: z.infer<typeof resolveComputerBody> }>(
+ '/api/machines/resolve-computer',
+ { preHandler: validateBody(resolveComputerBody) },
+ async (req, reply) => {
+ const computerId = normalizeComputerId(req.body.computerId)
+ if (!computerId) return sendError(reply, 'Invalid computer id', 'BAD_REQUEST', 400)
+ const result = await machineService.resolveOrCreateForComputer(
+ req.user!.sub,
+ req.user!.autonomousEnv,
+ computerId,
+ req.body.label ?? 'computer',
+ req.body.machineId,
+ )
+ // The server-internal machine API key must never leave this SSO endpoint.
+ return sendSuccess(reply, {
+ machine: { machineId: result.machine.machineId, computerId: result.machine.computerId },
+ created: result.created,
+ })
+ },
+ )
+
+ // Resolve an Autonomous campaign device deep-link to a machine owned by this exact user/env.
+ app.get<{ Querystring: z.infer<typeof resolveMachineQuery> }>(
+ '/api/machines/resolve',
+ { preHandler: validateQuery(resolveMachineQuery) },
+ async (req, reply) => {
+ const machine = await machineService.resolveByExternalDeviceId(req.query.deviceId, req.user!)
+ return sendSuccess(reply, { machine })
+ },
+ )
+
+ // Fetch one agent (incl. its apiKey) by id — owner or admin. Used by /machine/<id>.
+ app.get<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ const agent = await machineService.get(req.params.machineId, req.user!)
+ return sendSuccess(reply, { machine: agent })
+ },
+ )
+
+ // Explicit wake button. The response is delayed until the node has registered and is ready.
+ app.post<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId/start',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ await machineService.start(req.params.machineId, req.user!)
+ return sendSuccess(reply, { status: 'running' })
+ },
+ )
+
+ // Explicit resource-saving stop. The container/volume remains available for a later start.
+ app.post<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId/stop',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ await machineService.stop(req.params.machineId, req.user!)
+ return sendSuccess(reply, { status: 'stopped' })
+ },
+ )
+
+ // Rename a machine (owner or admin). Empty name → null (back to the default display name).
+ app.patch<{ Params: z.infer<typeof machineParams>; Body: z.infer<typeof renameBody> }>(
+ '/api/machines/:machineId',
+ { preHandler: [validateParams(machineParams), validateBody(renameBody)] },
+ async (req, reply) => {
+ const name = req.body.name || null
+ await machineService.rename(req.params.machineId, req.user!, name)
+ return sendSuccess(reply, { name })
+ },
+ )
+
+ // Destroy an agent (owner or admin).
+ app.delete<{ Params: z.infer<typeof machineParams> }>(
+ '/api/machines/:machineId',
+ { preHandler: validateParams(machineParams) },
+ async (req, reply) => {
+ await machineService.destroy(
+ req.params.machineId,
+ req.user!,
+ requestAccessToken(req.headers.authorization),
+ )
+ return sendSuccess(reply, { deleted: true })
+ },
+ )
+}
diff --git a/backend/src/routes/mobile.test.ts b/backend/src/routes/mobile.test.ts
new file mode 100644
index 000000000..ba562cd4b
--- /dev/null
+++ b/backend/src/routes/mobile.test.ts
@@ -0,0 +1,346 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import Fastify, { type FastifyInstance, type InjectOptions } from 'fastify'
+
+const listDetailedForUser = vi.hoisted(() => vi.fn())
+const detailForUser = vi.hoisted(() => vi.fn())
+const rename = vi.hoisted(() => vi.fn())
+const listForUser = vi.hoisted(() => vi.fn())
+const revokeDeviceForUser = vi.hoisted(() => vi.fn())
+const authenticateAccessToken = vi.hoisted(() => vi.fn())
+
+vi.mock('../services/index.js', () => ({
+ deviceService: { listDetailedForUser, detailForUser, rename },
+ machineService: { listForUser },
+ machineDisplayName: (id: string) => `machine-${id.slice(0, 6)}`,
+}))
+vi.mock('../lib/deviceRevoke.js', () => ({ revokeDeviceForUser }))
+// Only the SSO network call is faked. bearerToken, SsoAuthError and resolveSsoAuth stay REAL, so the
+// preHandler's token parsing and its 401/503/403 mapping are genuinely exercised.
+vi.mock('../lib/ssoAuth.js', async (importActual) => ({
+ ...(await importActual<typeof import('../lib/ssoAuth.js')>()),
+ authenticateAccessToken,
+}))
+
+import { mobileRoutes } from './mobile.js'
+import { errorHandler } from '../middlewares/errorHandler.js'
+import { SsoAuthError } from '../lib/ssoAuth.js'
+import { shouldSkipAuth } from '../middlewares/authMiddleware.js'
+
+/** The real OwnerMachine shape, apiKey included — that is the point of several tests below. */
+const machine = (over: Record<string, unknown> = {}): Record<string, unknown> => ({
+ machineId: '7f3ca1b29c4d5e6f7a8b9c0d1e2f3a4b',
+ apiKey: 'sk-super-secret-data-plane-key',
+ workspaceId: null,
+ planId: 'plan-pro',
+ autonomousEnv: 'prod',
+ authMode: 'managed',
+ planName: 'Pro',
+ billingStatus: 'active',
+ createdAt: new Date('2026-07-01T00:00:00Z'),
+ status: 'running',
+ agentCount: 2,
+ engine: 'claude',
+ name: null,
+ ...over,
+})
+
+const device = (over: Record<string, unknown> = {}): Record<string, unknown> => ({
+ deviceId: '6a70088ae13f6277cdf9015a',
+ name: 'device',
+ online: true,
+ lastSeenAt: new Date('2026-08-01T00:00:00Z'),
+ createdAt: new Date('2026-07-01T00:00:00Z'),
+ macAddress: 'AA:BB:CC:DD:EE:FF',
+ firmwareVersion: '0.2.8',
+ chip: 'esp32s3',
+ ssid: null,
+ rssi: null,
+ activeMachineId: null,
+ ...over,
+})
+
+const USER = { sub: 'u1', email: '[email protected]', role: 'user', autonomousEnv: 'prod' }
+
+async function buildApp(user: Record<string, unknown> | null = USER): Promise<FastifyInstance> {
+ if (user) authenticateAccessToken.mockResolvedValue(user)
+ const app = Fastify({ logger: false })
+ app.setErrorHandler(errorHandler)
+ await app.register(mobileRoutes)
+ await app.ready()
+ return app
+}
+
+/** Every call carries a token — the group authenticates itself now. */
+function call(app: FastifyInstance, opts: InjectOptions & { noAuth?: boolean }) {
+ const { noAuth, ...rest } = opts
+ return app.inject({ ...rest, headers: noAuth ? {} : { authorization: 'Bearer sso-token' } })
+}
+
+const overview = (app: FastifyInstance) => call(app, { method: 'GET', url: '/api/mobile/v1/overview' })
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ listDetailedForUser.mockResolvedValue([])
+ listForUser.mockResolvedValue([])
+ detailForUser.mockResolvedValue(null)
+ rename.mockResolvedValue(null)
+ revokeDeviceForUser.mockResolvedValue(true)
+})
+
+describe('auth — production-only, account-plane gate off', () => {
+ it('is excluded from the global hook, so its own preHandler is the gate', () => {
+ // If this ever flips back, the global hook re-applies the env gate and every legacy `stag` user
+ // gets a 403 from the mobile app.
+ expect(shouldSkipAuth('/api/mobile/v1/overview')).toBe(true)
+ expect(shouldSkipAuth('/api/machines')).toBe(false)
+ })
+
+ it('401s with no Authorization header', async () => {
+ const app = await buildApp()
+ const res = await call(app, { method: 'GET', url: '/api/mobile/v1/overview', noAuth: true })
+
+ expect(res.statusCode).toBe(401)
+ expect(authenticateAccessToken).not.toHaveBeenCalled()
+ })
+
+ it('always validates against PROD with the env gate disabled', async () => {
+ const app = await buildApp()
+ await overview(app)
+
+ expect(authenticateAccessToken).toHaveBeenCalledWith('sso-token', 'prod', { enforceEnv: false })
+ })
+
+ it('ignores x-autonomous-env — there is no staging mobile app', async () => {
+ const app = await buildApp()
+ await app.inject({
+ method: 'GET', url: '/api/mobile/v1/overview',
+ headers: { authorization: 'Bearer sso-token', 'x-autonomous-env': 'stag' },
+ })
+
+ expect(authenticateAccessToken).toHaveBeenCalledWith('sso-token', 'prod', { enforceEnv: false })
+ })
+
+ it('serves a user whose row is stamped stag — those rows are legacy, not an error', async () => {
+ // The web answers this user 403 AUTONOMOUS_ENV_MISMATCH. The mobile app must not.
+ const app = await buildApp({ ...USER, autonomousEnv: 'stag' })
+ listDetailedForUser.mockResolvedValue([device()])
+
+ expect((await overview(app)).statusCode).toBe(200)
+ })
+
+ it('401s a token prod SSO rejects', async () => {
+ authenticateAccessToken.mockRejectedValue(new SsoAuthError('nope', 'INVALID_TOKEN'))
+ const app = await buildApp(null)
+
+ expect((await overview(app)).statusCode).toBe(401)
+ })
+
+ it('503s when SSO itself is unreachable, so the app does not sign the user out', async () => {
+ authenticateAccessToken.mockRejectedValue(new SsoAuthError('down', 'AUTH_SERVICE_UNAVAILABLE'))
+ const app = await buildApp(null)
+ const res = await overview(app)
+
+ expect(res.statusCode).toBe(503)
+ expect(res.json().error.code).toBe('AUTH_SERVICE_UNAVAILABLE')
+ })
+})
+
+describe('machine list is by user, never by environment', () => {
+ it('passes no env filter, so legacy stag-stamped machines still appear', async () => {
+ const app = await buildApp({ ...USER, autonomousEnv: 'stag' })
+ await overview(app)
+
+ expect(listForUser).toHaveBeenCalledWith('u1')
+ expect(listForUser).not.toHaveBeenCalledWith('u1', expect.anything())
+ })
+
+ it('returns machines whose own row says stag', async () => {
+ listForUser.mockResolvedValue([machine({ autonomousEnv: 'stag' })])
+ const app = await buildApp()
+
+ expect(JSON.parse((await overview(app)).payload).data.machines).toHaveLength(1)
+ })
+})
+
+describe('apiKey containment', () => {
+ it('never serializes the data-plane key in /overview', async () => {
+ // Asserted on the raw payload, not on parsed top-level keys: a nested or renamed occurrence has
+ // to fail too, because possession of this key IS authentication for the machine.
+ listForUser.mockResolvedValue([machine(), machine({ machineId: 'b'.repeat(32), authMode: 'remote' })])
+ listDetailedForUser.mockResolvedValue([device()])
+ const app = await buildApp()
+
+ const res = await overview(app)
+
+ expect(res.statusCode).toBe(200)
+ expect(res.payload).not.toContain('sk-super-secret-data-plane-key')
+ expect(res.payload.toLowerCase()).not.toContain('apikey')
+ })
+
+ it('never serializes it on the single-device route either', async () => {
+ listForUser.mockResolvedValue([machine()])
+ detailForUser.mockResolvedValue(device({ activeMachineId: machine().machineId }))
+ const app = await buildApp()
+
+ const res = await call(app, { method: 'GET', url: '/api/mobile/v1/devices/6a70088ae13f6277cdf9015a' })
+
+ expect(res.payload).not.toContain('sk-super-secret-data-plane-key')
+ expect(res.payload.toLowerCase()).not.toContain('apikey')
+ })
+})
+
+describe('machine mapping', () => {
+ const kindOf = async (authMode: string): Promise<string> => {
+ listForUser.mockResolvedValue([machine({ authMode })])
+ const app = await buildApp()
+ return JSON.parse((await overview(app)).payload).data.machines[0].kind
+ }
+
+ it('maps every authMode onto a kind a person can distinguish', async () => {
+ expect(await kindOf('self')).toBe('cloud')
+ expect(await kindOf('managed')).toBe('cloud')
+ expect(await kindOf('remote')).toBe('remote')
+ expect(await kindOf('provider')).toBe('external')
+ })
+
+ it('publishes the unit count as agentCount, never the historical projectCount', async () => {
+ listForUser.mockResolvedValue([machine({ agentCount: 4 })])
+ const app = await buildApp()
+
+ const body = JSON.parse((await overview(app)).payload)
+
+ expect(body.data.machines[0].agentCount).toBe(4)
+ expect(body.data.machines[0]).not.toHaveProperty('projectCount')
+ })
+
+ it('prefers name and falls back to the device picker-s label', async () => {
+ listForUser.mockResolvedValue([
+ machine({ machineId: 'a'.repeat(32), name: ' MacBook-Pro-Kenny ' }),
+ machine({ machineId: '7f3ca1b29c4d5e6f7a8b9c0d1e2f3a4b', name: null }),
+ ])
+ const app = await buildApp()
+
+ const body = JSON.parse((await overview(app)).payload)
+
+ expect(body.data.machines.map((h: { name: string }) => h.name))
+ .toEqual(['MacBook-Pro-Kenny', 'machine-7f3ca1'])
+ })
+
+ it('keeps payment_pending visible — the device silently hides such machines', async () => {
+ listForUser.mockResolvedValue([machine({ status: 'payment_pending', billingStatus: 'pending' })])
+ const app = await buildApp()
+
+ const body = JSON.parse((await overview(app)).payload)
+
+ expect(body.data.machines[0]).toMatchObject({ status: 'payment_pending', billingStatus: 'pending' })
+ })
+})
+
+describe('device ↔ machine attachment', () => {
+ it('embeds the attached machine so the app never joins two lists itself', async () => {
+ const h = machine({ name: 'MacBook-Pro-Kenny', authMode: 'remote' })
+ listForUser.mockResolvedValue([h])
+ listDetailedForUser.mockResolvedValue([device({ activeMachineId: h.machineId })])
+ const app = await buildApp()
+
+ const body = JSON.parse((await overview(app)).payload)
+
+ expect(body.data.devices[0].activeMachine)
+ .toEqual({ machineId: h.machineId, name: 'MacBook-Pro-Kenny', kind: 'remote' })
+ })
+
+ it('renders a dangling pointer as null, not as a bare id', async () => {
+ // The machine was deleted out from under the device.
+ listForUser.mockResolvedValue([])
+ listDetailedForUser.mockResolvedValue([device({ activeMachineId: 'deleted-machine-id' })])
+ const app = await buildApp()
+
+ const res = await overview(app)
+
+ expect(JSON.parse(res.payload).data.devices[0].activeMachine).toBeNull()
+ expect(res.payload).not.toContain('deleted-machine-id')
+ })
+
+ it('does NOT leak the legacy pairing-origin machineId', async () => {
+ // DeviceBinding.machineId means something different and is null for every per-user device.
+ listDetailedForUser.mockResolvedValue([device()])
+ const app = await buildApp()
+
+ const body = JSON.parse((await overview(app)).payload)
+
+ expect(body.data.devices[0]).not.toHaveProperty('machineId')
+ })
+})
+
+describe('summary', () => {
+ it('counts online devices from the live flag', async () => {
+ listDetailedForUser.mockResolvedValue([
+ device({ deviceId: 'a', online: true }),
+ device({ deviceId: 'b', online: false }),
+ device({ deviceId: 'c', online: true }),
+ ])
+ listForUser.mockResolvedValue([machine()])
+ const app = await buildApp()
+
+ const body = JSON.parse((await overview(app)).payload)
+
+ expect(body.data.summary).toEqual({ deviceCount: 3, devicesOnline: 2, machineCount: 1 })
+ })
+})
+
+describe('rename', () => {
+ it('trims and accepts a normal name', async () => {
+ rename.mockResolvedValue(device({ name: 'Kitchen' }))
+ const app = await buildApp()
+
+ const res = await call(app, {
+ method: 'PATCH', url: '/api/mobile/v1/devices/dev-1', payload: { name: ' Kitchen ' },
+ })
+
+ expect(res.statusCode).toBe(200)
+ expect(rename).toHaveBeenCalledWith('dev-1', 'u1', 'Kitchen')
+ })
+
+ it('rejects a blank name', async () => {
+ const app = await buildApp()
+ const res = await call(app, { method: 'PATCH', url: '/api/mobile/v1/devices/dev-1', payload: { name: ' ' } })
+
+ expect(res.statusCode).toBe(400)
+ expect(rename).not.toHaveBeenCalled()
+ })
+
+ it('rejects an over-long name', async () => {
+ const app = await buildApp()
+ const res = await call(app, { method: 'PATCH', url: '/api/mobile/v1/devices/dev-1', payload: { name: 'x'.repeat(33) } })
+
+ expect(res.statusCode).toBe(400)
+ expect(rename).not.toHaveBeenCalled()
+ })
+
+ it('404s another user-s device', async () => {
+ rename.mockResolvedValue(null)
+ const app = await buildApp()
+
+ const res = await call(app, { method: 'PATCH', url: '/api/mobile/v1/devices/dev-1', payload: { name: 'Kitchen' } })
+
+ expect(res.statusCode).toBe(404)
+ })
+})
+
+describe('delete', () => {
+ it('goes through the shared revoke helper, so all three pushes happen', async () => {
+ const app = await buildApp()
+
+ const res = await call(app, { method: 'DELETE', url: '/api/mobile/v1/devices/dev-1' })
+
+ expect(res.statusCode).toBe(200)
+ expect(revokeDeviceForUser).toHaveBeenCalledWith('dev-1', 'u1')
+ })
+
+ it('404s when the device is not the caller-s', async () => {
+ revokeDeviceForUser.mockResolvedValue(false)
+ const app = await buildApp()
+
+ expect((await call(app, { method: 'DELETE', url: '/api/mobile/v1/devices/dev-1' })).statusCode).toBe(404)
+ })
+})
diff --git a/backend/src/routes/mobile.ts b/backend/src/routes/mobile.ts
new file mode 100644
index 000000000..8f8116ec7
--- /dev/null
+++ b/backend/src/routes/mobile.ts
@@ -0,0 +1,192 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import { z } from 'zod'
+import { machineService, deviceService, machineDisplayName, type DeviceDetail, type OwnerMachine } from '../services/index.js'
+import { validateBody, validateParams } from '../middlewares/validation.js'
+import { sendSuccess, sendError } from '../utils/response.js'
+import { revokeDeviceForUser } from '../lib/deviceRevoke.js'
+import { authenticateAccessToken, bearerToken } from '../lib/ssoAuth.js'
+import { resolveSsoAuth } from '../middlewares/authMiddleware.js'
+
+// The Autonomous MOBILE app's read surface for the Machine product tile.
+// Contract + screen designs: docs/specs/mobile-app-machine-ui.md.
+//
+// WHY A SEPARATE GROUP rather than widening /api/devices + /api/machines:
+//
+// 1. `/api/machines` returns OwnerMachine, which carries `apiKey` — the DATA-PLANE credential,
+// where possession *is* authentication for that machine. The web is a first-party client that
+// needs it. An app-store binary must never receive it. Here the mapper builds an allow-listed
+// object field by field and NEVER spreads OwnerMachine, so a future field on that interface
+// cannot silently leak. That is the whole reason this file exists; do not "simplify" it into a
+// spread plus a delete.
+// 2. The app renders one screen from devices + machines + the link between them, so it wants ONE
+// round trip. The web wants the two lists independently.
+// 3. App-store builds live in users' hands for months, so this contract has to stay stable while
+// `/api/machines` keeps evolving for the web. Hence the explicit /v1.
+//
+// AUTH: the same Autonomous SSO access token the web sends, but PRODUCTION-ONLY.
+//
+// There is no staging build of the mobile app, so this group pins the plane to prod and ignores
+// `x-autonomous-env` entirely. A staging token therefore fails the prod profile fetch and gets a
+// plain 401 — no cross-plane access is opened.
+//
+// What is deliberately dropped is the account-plane GATE (`enforceEnv: false`). Every user row that
+// predates the prod default was backfilled to `autonomousEnv: 'stag'`, and the web's gate answers
+// those with 403 AUTONOMOUS_ENV_MISMATCH. Applying it here would lock long-standing customers out of
+// the mobile app for a reason that has nothing to do with them. The identity served is still the one
+// prod SSO just verified, resolved by EMAIL, and upsertFromSso never rewrites `autonomousEnv`, so a
+// user's web experience is untouched.
+//
+// The same reasoning applies to the machine list: it is fetched by user, NOT filtered by env — see
+// the call sites. Filtering would authenticate a legacy user successfully and then show them nothing.
+//
+// Because of the above, `/api/mobile/` is listed in shouldSkipAuth: the GLOBAL hook must not run its
+// env gate on these paths. mobileAuth below is what actually authenticates them.
+//
+// VOCABULARY: this surface speaks the product model — machine -> agent -> session. A machine's
+// unit count is published as `agentCount` (never the historical `projectCount`), and the
+// billing-flavoured `authMode` as a plain `kind` the app can actually render.
+
+const deviceParams = z.object({ deviceId: z.string().min(1) })
+const renameBody = z.object({
+ // Trimmed before length-checking, so " " is rejected as empty rather than stored as blanks.
+ name: z.string().transform((s) => s.trim()).pipe(z.string().min(1, 'Name is required').max(32, 'Name is too long')),
+})
+
+/** What the app shows as the machine's type. Maps the billing-flavoured authMode onto the three
+ * things a person can actually distinguish (mobile spec §1.2). `self`/`managed` are both "a machine
+ * we run for you", and the difference between them is a billing tier, not something to render. */
+function machineKind(authMode: OwnerMachine['authMode']): 'cloud' | 'remote' | 'external' {
+ if (authMode === 'remote') return 'remote'
+ if (authMode === 'provider') return 'external'
+ return 'cloud'
+}
+
+interface MobileMachine {
+ machineId: string
+ name: string
+ kind: 'cloud' | 'remote' | 'external'
+ status: string
+ agentCount: number
+ engine: string
+ planName: string | null
+ billingStatus: string
+}
+
+/** Allow-list. Built field by field ON PURPOSE — see the `apiKey` note in the header. */
+function toMobileMachine(b: OwnerMachine): MobileMachine {
+ return {
+ machineId: b.machineId,
+ // Same fallback the device's own machine picker uses, so a machine is named identically on the
+ // phone and on the device screen.
+ name: b.name?.trim() || machineDisplayName(b.machineId),
+ kind: machineKind(b.authMode),
+ status: b.status,
+ agentCount: b.agentCount,
+ engine: b.engine,
+ planName: b.planName,
+ billingStatus: b.billingStatus,
+ }
+}
+
+/** A device plus the machine it is attached to, resolved against machines the CALLER owns. */
+function toMobileDevice(d: DeviceDetail, machinesById: Map<string, MobileMachine>): Record<string, unknown> {
+ // Resolve rather than echo the stored id: a machine can be deleted, or belong to the caller's other
+ // Autonomous environment, while the device still points at it. Both cases must read as "no machine",
+ // never as a dangling id the app would have to handle itself.
+ const active = d.activeMachineId ? machinesById.get(d.activeMachineId) ?? null : null
+ return {
+ deviceId: d.deviceId,
+ name: d.name,
+ online: d.online,
+ lastSeenAt: d.lastSeenAt,
+ createdAt: d.createdAt,
+ macAddress: d.macAddress,
+ firmwareVersion: d.firmwareVersion,
+ chip: d.chip,
+ ssid: d.ssid,
+ rssi: d.rssi,
+ activeMachine: active ? { machineId: active.machineId, name: active.name, kind: active.kind } : null,
+ }
+}
+
+/** Production-pinned SSO auth for this group. See the AUTH note in the header for why the plane is
+ * hard-coded and the account-plane gate is off. Reuses resolveSsoAuth so the error mapping (401 vs
+ * 503 vs 403) stays identical to the web's. */
+async function mobileAuth(req: FastifyRequest, reply: FastifyReply): Promise<void> {
+ const token = bearerToken(req.headers['authorization'])
+ if (!token) {
+ sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)
+ return
+ }
+ const auth = await resolveSsoAuth(token, (t) => authenticateAccessToken(t, 'prod', { enforceEnv: false }), 'prod')
+ if ('user' in auth) {
+ req.user = auth.user
+ return
+ }
+ sendError(reply, auth.message, auth.code, auth.status)
+}
+
+/** Every machine the user owns, in the app's shape. NOT filtered by Autonomous environment: the user
+ * is resolved by email and legacy rows carry `autonomousEnv: 'stag'`, so filtering would hand a
+ * successfully-authenticated customer an empty list. */
+async function mobileMachines(userId: string): Promise<MobileMachine[]> {
+ return (await machineService.listForUser(userId)).map(toMobileMachine)
+}
+
+export async function mobileRoutes(app: FastifyInstance): Promise<void> {
+ app.addHook('onRequest', mobileAuth)
+
+ /** Everything the group-detail screen needs, in one round trip. */
+ app.get('/api/mobile/v1/overview', async (req, reply) => {
+ const [devices, mapped] = await Promise.all([
+ deviceService.listDetailedForUser(req.user!.sub),
+ mobileMachines(req.user!.sub),
+ ])
+ const byId = new Map(mapped.map((h) => [h.machineId, h]))
+ return sendSuccess(reply, {
+ devices: devices.map((d) => toMobileDevice(d, byId)),
+ machines: mapped,
+ summary: {
+ deviceCount: devices.length,
+ devicesOnline: devices.filter((d) => d.online).length,
+ machineCount: mapped.length,
+ },
+ })
+ })
+
+ /** One device, in the SAME shape it has inside `overview` — the app parses one type, not two. */
+ app.get<{ Params: z.infer<typeof deviceParams> }>(
+ '/api/mobile/v1/devices/:deviceId',
+ { preHandler: validateParams(deviceParams) },
+ async (req, reply) => {
+ const device = await deviceService.detailForUser(req.params.deviceId, req.user!.sub)
+ if (!device) return sendError(reply, 'Device not found', 'NOT_FOUND', 404)
+ const byId = new Map((await mobileMachines(req.user!.sub)).map((h) => [h.machineId, h]))
+ return sendSuccess(reply, { device: toMobileDevice(device, byId) })
+ },
+ )
+
+ /** Rename. Devices are created with the literal name "device", so with more than one paired device
+ * this is what makes them tellable apart at all. */
+ app.patch<{ Params: z.infer<typeof deviceParams>; Body: z.infer<typeof renameBody> }>(
+ '/api/mobile/v1/devices/:deviceId',
+ { preHandler: [validateParams(deviceParams), validateBody(renameBody)] },
+ async (req, reply) => {
+ const device = await deviceService.rename(req.params.deviceId, req.user!.sub, req.body.name)
+ if (!device) return sendError(reply, 'Device not found', 'NOT_FOUND', 404)
+ const byId = new Map((await mobileMachines(req.user!.sub)).map((h) => [h.machineId, h]))
+ return sendSuccess(reply, { device: toMobileDevice(device, byId) })
+ },
+ )
+
+ /** Unpair. Same helper as the web's DELETE, so both surfaces perform all three revoke pushes. */
+ app.delete<{ Params: z.infer<typeof deviceParams> }>(
+ '/api/mobile/v1/devices/:deviceId',
+ { preHandler: validateParams(deviceParams) },
+ async (req, reply) => {
+ const ok = await revokeDeviceForUser(req.params.deviceId, req.user!.sub)
+ if (!ok) return sendError(reply, 'Device not found', 'NOT_FOUND', 404)
+ return sendSuccess(reply, { deleted: true })
+ },
+ )
+}
diff --git a/backend/src/routes/plans.ts b/backend/src/routes/plans.ts
new file mode 100644
index 000000000..ffcf05ce1
--- /dev/null
+++ b/backend/src/routes/plans.ts
@@ -0,0 +1,45 @@
+import type { FastifyInstance } from 'fastify'
+import { prisma } from '../lib/prisma.js'
+import { sendSuccess } from '../utils/response.js'
+import { env } from '../config/env.js'
+import { machineBillingService } from '../services/MachineBillingService.js'
+import { dailyTokenLimitForPlan } from '../lib/billingPlanMetadata.js'
+
+/**
+ * Subscription tiers offered at agent-create. Read-only catalog (writes happen via the seeder / DB);
+ * the web create-agent picker lists these and posts the chosen `planId` to POST /api/machines.
+ * SSO-access-token gated like the rest of the control API.
+ */
+export async function planRoutes(app: FastifyInstance): Promise<void> {
+ app.get('/api/plans', async (req, reply) => {
+ const [plans, free] = await Promise.all([
+ prisma.subscriptionPlan.findMany({
+ where: env.HARNESS_BILLING_ENABLED
+ ? { autonomousEnv: req.user!.autonomousEnv, available: true }
+ : { autonomousEnv: req.user!.autonomousEnv, name: 'Remote', available: true },
+ orderBy: { priceUsd: 'asc' },
+ }),
+ env.HARNESS_BILLING_ENABLED
+ ? machineBillingService.freeEligibility(req.user!.sub, req.user!.autonomousEnv)
+ : Promise.resolve({ eligible: false, reason: 'Machine billing is disabled' }),
+ ])
+ return sendSuccess(reply, {
+ plans: plans.map((p) => ({
+ id: p.id,
+ name: p.name,
+ priceUsd: p.priceUsd,
+ authMode: p.authMode,
+ cpus: p.cpus,
+ memory: p.memory,
+ maxAgents: p.maxAgents,
+ dailyTokenLimit: dailyTokenLimitForPlan(p),
+ dailyVoiceLimitSeconds: Math.max(0, p.dailyVoiceLimitSeconds ?? 0),
+ isDefault: p.isDefault,
+ eligible: !(p.authMode === 'managed' && p.priceUsd === 0) || free.eligible,
+ ...((p.authMode === 'managed' && p.priceUsd === 0 && !free.eligible)
+ ? { ineligibilityReason: free.reason }
+ : {}),
+ })),
+ })
+ })
+}
diff --git a/backend/src/routes/users.ts b/backend/src/routes/users.ts
new file mode 100644
index 000000000..b81deb429
--- /dev/null
+++ b/backend/src/routes/users.ts
@@ -0,0 +1,83 @@
+import type { FastifyInstance } from 'fastify'
+import { z } from 'zod'
+import { userService } from '../services/index.js'
+import { requireAdmin } from '../middlewares/authMiddleware.js'
+import { validateBody, validateParams } from '../middlewares/validation.js'
+import { sendSuccess, sendCreated } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import { publishDeviceMachineListChanged } from '../lib/bus.js'
+
+const idParams = z.object({ id: z.string().min(1) })
+
+const createBody = z.object({
+ email: z.string().email(),
+ password: z.string().min(6),
+ name: z.string().optional(),
+ role: z.enum(['user', 'admin']).optional(),
+ autonomousEnv: z.enum(['prod', 'stag']).optional(),
+})
+
+const updateBody = z.object({
+ name: z.string().optional(),
+ password: z.string().min(6).optional(),
+ role: z.enum(['user', 'admin']).optional(),
+ autonomousEnv: z.enum(['prod', 'stag']).optional(),
+})
+
+/** Admin-only user management. All routes already require a valid SSO access token. */
+export async function userRoutes(app: FastifyInstance): Promise<void> {
+ app.get('/api/users', async (req, reply) => {
+ requireAdmin(req)
+ const users = await userService.list()
+ return sendSuccess(reply, { users: users.map(userService.toPublic) })
+ })
+
+ app.post<{ Body: z.infer<typeof createBody> }>(
+ '/api/users',
+ { preHandler: validateBody(createBody) },
+ async (req, reply) => {
+ requireAdmin(req)
+ const user = await userService.create(req.body)
+ return sendCreated(reply, userService.toPublic(user))
+ },
+ )
+
+ app.patch<{ Params: z.infer<typeof idParams>; Body: z.infer<typeof updateBody> }>(
+ '/api/users/:id',
+ { preHandler: [validateParams(idParams), validateBody(updateBody)] },
+ async (req, reply) => {
+ requireAdmin(req)
+ const before = req.body.autonomousEnv
+ ? await userService.get(req.params.id)
+ : null
+ const user = await userService.update(req.params.id, req.body)
+ if (before && before.autonomousEnv !== user.autonomousEnv) {
+ logger.info('user Autonomous environment changed', {
+ userId: user.id,
+ from: before.autonomousEnv,
+ to: user.autonomousEnv,
+ by: req.user!.sub,
+ })
+ // Invalidate already-authenticated web sockets immediately. REST requests would reject the
+ // old plane on their next call, but an attached chat socket otherwise needs no REST traffic
+ // and could keep its old environment indefinitely. Device subscribers only refresh their
+ // cross-environment machine list; their protocol and visibility stay unchanged.
+ await publishDeviceMachineListChanged(user.id, {
+ reason: 'environment_changed',
+ autonomousEnv: user.autonomousEnv === 'stag' ? 'stag' : 'prod',
+ }).catch(() => { /* the next REST/WS auth still enforces the new environment */ })
+ }
+ return sendSuccess(reply, userService.toPublic(user))
+ },
+ )
+
+ app.delete<{ Params: z.infer<typeof idParams> }>(
+ '/api/users/:id',
+ { preHandler: validateParams(idParams) },
+ async (req, reply) => {
+ requireAdmin(req)
+ await userService.remove(req.params.id)
+ return sendSuccess(reply, { deleted: true })
+ },
+ )
+}
diff --git a/backend/src/routes/voice.ts b/backend/src/routes/voice.ts
new file mode 100644
index 000000000..b61f3bc59
--- /dev/null
+++ b/backend/src/routes/voice.ts
@@ -0,0 +1,82 @@
+/**
+ * Transcription for the cabled dial.
+ *
+ * POST /api/voice/stt?lang=vi multipart, one part `file` (WAV) → { transcript, lang }
+ *
+ * ONE difference from routes/cursor.ts's endpoint, and it is the whole reason this file exists: this one
+ * is authenticated by the caller's **SSO access token**, not by a shared secret. The `harness` CLI signs
+ * in (`harness login`) and holds a real bearer token that refreshes itself; the dial holds no credential
+ * at all and never talks to this service — it hands its audio down a USB cable to the daemon, and the
+ * daemon is the one with an account.
+ *
+ * That matters beyond tidiness. The CLI ships from a PUBLIC repository, so a shared secret baked into it
+ * is a secret nobody has. A bearer token is issued per person, expires, and can be revoked.
+ *
+ * NOT in the auth middleware's skip-list, deliberately: being absent from that list is what applies the
+ * SSO gate, so `req.user` is populated here and an unauthenticated request never reaches this handler.
+ */
+import type { FastifyInstance } from 'fastify'
+import multipart from '@fastify/multipart'
+
+import { VOICE_WAV_LANGS, transcribeWavWithDeepgram } from '../lib/deepgramWav.js'
+import { sendError, sendSuccess } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+
+export const VOICE_STT_PATH = '/api/voice/stt'
+
+/** ~25 MB — far above any dictation clip this serves, while still bounding one request's buffer. */
+const MAX_AUDIO_BYTES = 25 * 1024 * 1024
+
+/** The language the dial stated. Unknown values fall back rather than failing: a transcript in the wrong
+ * language is recoverable by the person; a 400 in the middle of a spoken turn is not. */
+function pickLang(value: unknown): string {
+ const v = typeof value === 'string' ? value.trim().toLowerCase() : ''
+ return VOICE_WAV_LANGS.has(v) ? v : 'en'
+}
+
+export async function voiceRoutes(app: FastifyInstance): Promise<void> {
+ // Registered inside this plugin's scope, not in server.ts: multipart parsing exists for this route and
+ // nothing else, so no other endpoint's body handling changes by adding it.
+ await app.register(multipart, { limits: { fileSize: MAX_AUDIO_BYTES, files: 1 } })
+
+ app.post(VOICE_STT_PATH, async (req, reply) => {
+ let file
+ try {
+ file = await req.file()
+ } catch {
+ sendError(reply, 'Expected a multipart/form-data upload', 'BAD_REQUEST', 400)
+ return
+ }
+ if (!file) {
+ sendError(reply, 'Missing audio file', 'BAD_REQUEST', 400)
+ return
+ }
+
+ const audio = await file.toBuffer()
+ if (audio.length === 0) {
+ sendError(reply, 'Empty audio file', 'BAD_REQUEST', 400)
+ return
+ }
+
+ const lang = pickLang((req.query as { lang?: unknown } | undefined)?.lang)
+ try {
+ const transcript = await transcribeWavWithDeepgram(audio, file.mimetype || 'audio/wav', lang)
+ // The user is logged, the words are not. A transcript is the most private thing this service sees,
+ // and the useful diagnostics — did it arrive, how big, what language, did it come back empty — do
+ // not require keeping it.
+ logger.info('voice-stt', {
+ user: req.user?.sub,
+ bytes: audio.length,
+ lang,
+ chars: transcript.length,
+ })
+ sendSuccess(reply, { transcript, lang })
+ } catch (err) {
+ logger.error('voice-stt failed', {
+ user: req.user?.sub,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ sendError(reply, 'Transcription failed', 'STT_FAILED', 502)
+ }
+ })
+}
diff --git a/backend/src/server.ts b/backend/src/server.ts
new file mode 100644
index 000000000..b9b3cea08
--- /dev/null
+++ b/backend/src/server.ts
@@ -0,0 +1,142 @@
+import 'dotenv/config'
+import cors from '@fastify/cors'
+import Fastify from 'fastify'
+import http from 'http'
+import net from 'net'
+import { env } from './config/env.js'
+import { registerJsonBodyParser } from './lib/jsonBodyParser.js'
+import { errorHandler } from './middlewares/errorHandler.js'
+import { registerAuthMiddleware } from './middlewares/authMiddleware.js'
+import { cursorRoutes } from './routes/cursor.js'
+import { voiceRoutes } from './routes/voice.js'
+import { deviceAuthRoutes } from './routes/deviceAuth.js'
+import { healthRoutes, authRoutes, userRoutes, machineRoutes, planRoutes, deviceRoutes, mobileRoutes, appRoutes, analyticsRoutes, agentRouteRoutes } from './routes/index.js'
+import { startSubdomainProxy, startMeshProxy } from './lib/subdomainProxy.js'
+import { handleDeviceUpgrade } from './lib/deviceWs.js'
+import { handleWebUpgrade } from './lib/webWs.js'
+import { handleManagerUpgrade } from './lib/managerWs.js'
+import { handleAdapterUpgrade } from './lib/adapterWs.js'
+import { logger } from './utils/logger.js'
+import { startTurnCredentialRefresh } from './lib/turnCredentials.js'
+
+// One http.Server fronts everything. Inverted transport: there is NO data-plane HTTP reverse-proxy
+// anymore (web + device data ride the hub WS). HTTP is entirely the Fastify control API
+// (auth / users / agents / health); WS upgrades are routed below (web-ws / manager-ws / commander-ws / voice).
+const app = Fastify({
+ logger: false,
+ requestIdLogLabel: 'reqId',
+ connectionTimeout: 120000,
+ keepAliveTimeout: 72000,
+ serverFactory: (handler) => {
+ const server = http.createServer((req, res) => {
+ handler(req, res)
+ })
+ server.on('upgrade', (req, socket, head) => {
+ // Interactive low-latency channels (terminal PTY bytes, voice frames, control chat) — disable
+ // Nagle's algorithm so small writes aren't held back up to ~40ms waiting to coalesce with more
+ // data. Nothing in this codebase called setNoDelay() before, so every socket here defaulted to
+ // Nagle-enabled.
+ if (socket instanceof net.Socket) socket.setNoDelay(true)
+ const path = (req.url ?? '').split('?')[0]
+ // Inverted-transport hub endpoints (terminated here, not proxied):
+ // /api/web-ws — web clients (replaces the old proxied /proxy/api/ws)
+ // /api/manager-ws — managers dial in and multiplex all their agents
+ if (path === '/api/web-ws') {
+ handleWebUpgrade(req, socket, head)
+ return
+ }
+ if (path === '/api/manager-ws') {
+ handleManagerUpgrade(req, socket, head)
+ return
+ }
+ // Remote-machine adapters (machine-adapter CLI) dial in and play the node role for their agent.
+ if (path === '/api/adapter-ws') {
+ handleAdapterUpgrade(req, socket, head)
+ return
+ }
+ // Device WS: TERMINATE + relay (per-user; we sniff voice frames for STT). Auth is the owner's
+ // SSO access token as the first subprotocol, plus a required `?computer=` id.
+ if (path === '/api/device-ws') {
+ handleDeviceUpgrade(req, socket, head)
+ return
+ }
+ // Inverted transport: all WS is now terminated above (web-ws / manager-ws / commander-ws / voice).
+ // Nothing is reverse-proxied over WS anymore (REST still rides /proxy → handleProxyRequest).
+ socket.destroy()
+ })
+ return server
+ },
+})
+
+async function start(): Promise<void> {
+ // Mint the Cloudflare TURN credential before the first socket lands; no-op when TURN is unconfigured.
+ startTurnCredentialRefresh()
+
+ app.setErrorHandler(errorHandler)
+
+ registerJsonBodyParser(app)
+
+ app.addHook('onSend', async (_request, reply) => {
+ reply.header('X-Content-Type-Options', 'nosniff')
+ reply.header('Referrer-Policy', 'strict-origin-when-cross-origin')
+ if (env.NODE_ENV === 'production') {
+ reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+ }
+ })
+
+ // Allow all origins (reflect the request origin so credentialed requests work too). Methods +
+ // headers are reflected (allowedHeaders omitted → echoes Access-Control-Request-Headers), so any
+ // client header (Authorization, x-api-key, …) passes preflight.
+ await app.register(cors, {
+ origin: true,
+ credentials: true,
+ methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'],
+ })
+
+ // SSO access-token gate for the control API (data-plane auth happens before Fastify).
+ registerAuthMiddleware(app)
+
+ await app.register(healthRoutes)
+ await app.register(authRoutes)
+ await app.register(userRoutes)
+ await app.register(machineRoutes)
+ await app.register(planRoutes)
+ await app.register(deviceRoutes)
+ await app.register(mobileRoutes)
+ await app.register(appRoutes)
+ await app.register(analyticsRoutes)
+ await app.register(agentRouteRoutes) // which agent a task belongs to — the prompt lives here, not in the CLI
+ await app.register(cursorRoutes) // standalone STT + LLM for the Cursor desktop app (self-contained)
+ // The cabled dial's transcription, authenticated by the caller's SSO token rather than a shared secret.
+ // Absent from the auth middleware's skip-list on purpose: that absence IS the gate.
+ await app.register(voiceRoutes)
+ await app.register(deviceAuthRoutes) // device-authorization grant: how the desktop app gets a machine key
+
+ // Dedicated public subdomain app-proxy on its own port (Host-header routed → tunnelled to the node app).
+ const appProxyServer = startSubdomainProxy()
+ // Internal mesh listener (Phase 2, MESH_ENABLED) — peers forward here when this instance owns the socket.
+ const meshServer = startMeshProxy()
+
+ const shutdown = async (signal: string) => {
+ logger.info(`Received ${signal}, shutting down...`)
+ try {
+ appProxyServer.close()
+ meshServer?.close()
+ await app.close()
+ process.exit(0)
+ } catch (err) {
+ logger.error('Error during shutdown', err)
+ process.exit(1)
+ }
+ }
+ process.on('SIGINT', () => void shutdown('SIGINT'))
+ process.on('SIGTERM', () => void shutdown('SIGTERM'))
+
+ await app.listen({ port: env.PORT, host: '0.0.0.0' })
+ logger.info(`backend listening on ${env.PORT}`)
+}
+
+start().catch((err) => {
+ logger.error('Failed to start backend', err)
+ process.exit(1)
+})
diff --git a/backend/src/services/DeviceService.test.ts b/backend/src/services/DeviceService.test.ts
new file mode 100644
index 000000000..468198a76
--- /dev/null
+++ b/backend/src/services/DeviceService.test.ts
@@ -0,0 +1,167 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const findMany = vi.hoisted(() => vi.fn())
+const findFirst = vi.hoisted(() => vi.fn())
+const update = vi.hoisted(() => vi.fn())
+const updateMany = vi.hoisted(() => vi.fn())
+const getDevicePresence = vi.hoisted(() => vi.fn())
+
+vi.mock('../lib/prisma.js', () => ({
+ prisma: {
+ deviceBinding: { findMany, findFirst, update, updateMany },
+ machine: { findMany: vi.fn() },
+ },
+ machineAlive: {},
+}))
+vi.mock('../lib/bus.js', () => ({ getDevicePresence }))
+
+import { deviceService } from './DeviceService.js'
+
+const device = (over: Record<string, unknown> = {}): Record<string, unknown> => ({
+ id: 'row1',
+ userId: 'u1',
+ deviceId: 'dev-1',
+ machineId: null,
+ authMode: 'sds',
+ macAddress: 'AA:BB:CC:DD:EE:FF',
+ tokenHash: 'h',
+ name: 'device',
+ lastSeenAt: new Date('2026-08-01T00:00:00Z'),
+ createdAt: new Date('2026-07-01T00:00:00Z'),
+ firmwareVersion: '0.2.8',
+ chip: 'esp32s3',
+ ssid: null,
+ rssi: null,
+ activeMachineId: null,
+ ...over,
+})
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ updateMany.mockResolvedValue({ count: 1 })
+ getDevicePresence.mockResolvedValue(false)
+})
+
+describe('listDetailedForUser', () => {
+ it('takes `online` from live presence, NOT from lastSeenAt', async () => {
+ // lastSeenAt is bumped by any token authenticate() call and says nothing about a live socket.
+ findMany.mockResolvedValue([device({ deviceId: 'a' }), device({ deviceId: 'b' })])
+ getDevicePresence.mockImplementation(async (id: string) => id === 'a')
+
+ const rows = await deviceService.listDetailedForUser('u1')
+
+ expect(rows.map((r) => [r.deviceId, r.online])).toEqual([['a', true], ['b', false]])
+ })
+
+ it('carries the reported hardware fields through', async () => {
+ findMany.mockResolvedValue([device({ ssid: 'Home', rssi: -52, activeMachineId: 'h1' })])
+
+ const [row] = await deviceService.listDetailedForUser('u1')
+
+ expect(row).toMatchObject({
+ firmwareVersion: '0.2.8', chip: 'esp32s3', ssid: 'Home', rssi: -52, activeMachineId: 'h1',
+ })
+ })
+
+ it('reports macAddress as null — the column left with the SDS path', () => {
+ // The field stays in the response shape so the mobile app's parser is unaffected; a computer-backed
+ // device has a hostname, not a MAC, so there is nothing true to put in it.
+ findMany.mockResolvedValue([device()])
+ return deviceService.listDetailedForUser('u1').then(([row]) => {
+ expect(row.macAddress).toBeNull()
+ })
+ })
+
+ it('never exposes the token hash', async () => {
+ findMany.mockResolvedValue([device()])
+ const [row] = await deviceService.listDetailedForUser('u1')
+ expect(JSON.stringify(row)).not.toContain('tokenHash')
+ expect(JSON.stringify(row)).not.toContain('"h"')
+ })
+})
+
+describe('recordHello', () => {
+ it('writes only the keys the device actually sent', async () => {
+ // Firmware without the WiFi fields must not blank values a newer build already recorded.
+ await deviceService.recordHello({ deviceId: 'dev-1', firmwareVersion: '0.2.9', chip: 'esp32s3' })
+
+ expect(updateMany).toHaveBeenCalledWith({
+ where: { deviceId: 'dev-1' },
+ data: { firmwareVersion: '0.2.9', chip: 'esp32s3' },
+ })
+ })
+
+ it('drops rssi 0 — the firmware sentinel for unknown/disconnected', async () => {
+ await deviceService.recordHello({ deviceId: 'dev-1', ssid: 'Home', rssi: 0 })
+
+ expect(updateMany).toHaveBeenCalledWith({ where: { deviceId: 'dev-1' }, data: { ssid: 'Home' } })
+ })
+
+ it('stores a real negative rssi', async () => {
+ await deviceService.recordHello({ deviceId: 'dev-1', rssi: -52 })
+ expect(updateMany).toHaveBeenCalledWith({ where: { deviceId: 'dev-1' }, data: { rssi: -52 } })
+ })
+
+ it('does not touch the DB when the device reported nothing usable', async () => {
+ await deviceService.recordHello({ deviceId: 'dev-1', firmwareVersion: null, chip: null })
+ expect(updateMany).not.toHaveBeenCalled()
+ })
+
+ it('swallows a DB failure — this runs on the device socket hot path', async () => {
+ updateMany.mockRejectedValue(new Error('mongo down'))
+ await expect(deviceService.recordHello({ deviceId: 'dev-1', chip: 'esp32s3' })).resolves.toBeUndefined()
+ })
+})
+
+describe('setActiveMachine', () => {
+ it('persists the pointer', async () => {
+ await deviceService.setActiveMachine('dev-1', 'h1')
+ expect(updateMany).toHaveBeenCalledWith({ where: { deviceId: 'dev-1' }, data: { activeMachineId: 'h1' } })
+ })
+
+ it('persists an explicit null when the machine goes away', async () => {
+ await deviceService.setActiveMachine('dev-1', null)
+ expect(updateMany).toHaveBeenCalledWith({ where: { deviceId: 'dev-1' }, data: { activeMachineId: null } })
+ })
+
+ it('swallows a DB failure', async () => {
+ updateMany.mockRejectedValue(new Error('mongo down'))
+ await expect(deviceService.setActiveMachine('dev-1', 'h1')).resolves.toBeUndefined()
+ })
+})
+
+describe('rename', () => {
+ it('refuses a device that is not the caller-s', async () => {
+ findFirst.mockResolvedValue(null)
+
+ expect(await deviceService.rename('dev-1', 'someone-else', 'Kitchen')).toBeNull()
+ expect(update).not.toHaveBeenCalled()
+ })
+
+ it('scopes the lookup by userId, so ownership cannot be bypassed', async () => {
+ findFirst.mockResolvedValue(device())
+ update.mockResolvedValue(device({ name: 'Kitchen' }))
+
+ await deviceService.rename('dev-1', 'u1', 'Kitchen')
+
+ expect(findFirst).toHaveBeenCalledWith({ where: { deviceId: 'dev-1', userId: 'u1' } })
+ expect(update).toHaveBeenCalledWith({ where: { id: 'row1' }, data: { name: 'Kitchen' } })
+ })
+
+ it('returns the renamed device with its live online state', async () => {
+ findFirst.mockResolvedValue(device())
+ update.mockResolvedValue(device({ name: 'Kitchen' }))
+ getDevicePresence.mockResolvedValue(true)
+
+ const row = await deviceService.rename('dev-1', 'u1', 'Kitchen')
+
+ expect(row).toMatchObject({ name: 'Kitchen', online: true })
+ })
+})
+
+describe('detailForUser', () => {
+ it('is null for another user-s device', async () => {
+ findFirst.mockResolvedValue(null)
+ expect(await deviceService.detailForUser('dev-1', 'u2')).toBeNull()
+ })
+})
diff --git a/backend/src/services/DeviceService.ts b/backend/src/services/DeviceService.ts
new file mode 100644
index 000000000..5954dc469
--- /dev/null
+++ b/backend/src/services/DeviceService.ts
@@ -0,0 +1,209 @@
+import type { DeviceBinding } from '@prisma/client'
+import { prisma, machineAlive } from '../lib/prisma.js'
+import { sha256hex } from '../utils/crypto.js'
+import { logger } from '../utils/logger.js'
+import { machineBillingAllowsDataPlane } from '../lib/billingState.js'
+import { getDevicePresence } from '../lib/bus.js'
+
+export interface DeviceView {
+ deviceId: string
+ name: string
+ // LEGACY per-machine pairing pinned the device to this ONE machine. Null for per-user devices, which pick
+ // machines themselves at runtime — kept only so the web can show a legacy device's origin.
+ machineId: string | null
+ lastSeenAt: Date | null
+ createdAt: Date
+}
+
+/**
+ * Everything a client can know about a device WITHOUT holding a socket of its own.
+ *
+ * Distinct from `DeviceView` on purpose. `DeviceView` is the web's shape and carries the LEGACY
+ * `machineId` (the immutable pairing origin, null for every per-user device); this one carries
+ * `activeMachineId`, which is where the device is attached right now. Conflating the two is the
+ * single easiest mistake to make against this model, so they never appear in the same object.
+ */
+export interface DeviceDetail {
+ deviceId: string
+ name: string
+ /** Live: the backend is holding this device's socket. NOT derived from `lastSeenAt`. */
+ online: boolean
+ lastSeenAt: Date | null
+ createdAt: Date
+ macAddress: string | null
+ firmwareVersion: string | null
+ chip: string | null
+ ssid: string | null
+ rssi: number | null
+ activeMachineId: string | null
+}
+
+/** Fallback label for a machine on the device machine-picker when it has no display name yet
+ * (`Machine.name`, the user-editable display name) — mirrors the web's fallback. */
+function machineDisplayName(machineId: string): string {
+ return `machine-${machineId.slice(0, 6)}`
+}
+
+/** Exported so the mobile surface labels a machine exactly like the device's own picker does. */
+export { machineDisplayName }
+
+function toDeviceView(d: DeviceBinding): DeviceView {
+ return { deviceId: d.deviceId, name: d.name, machineId: d.machineId, lastSeenAt: d.lastSeenAt, createdAt: d.createdAt }
+}
+
+function toDeviceDetail(d: DeviceBinding, online: boolean): DeviceDetail {
+ return {
+ deviceId: d.deviceId,
+ name: d.name,
+ online,
+ lastSeenAt: d.lastSeenAt,
+ createdAt: d.createdAt,
+ // The column is gone with the SDS path; a computer-backed dial has a hostname, not a MAC.
+ // Kept as a literal so the mobile response shape does not change.
+ macAddress: null,
+ firmwareVersion: d.firmwareVersion,
+ chip: d.chip,
+ ssid: d.ssid,
+ rssi: d.rssi,
+ activeMachineId: d.activeMachineId,
+ }
+}
+
+export const deviceService = {
+ /**
+ * The one way a device comes into existence: resolve the row for a COMPUTER, creating it on first sight.
+ *
+ * `deviceId` is DERIVED, never random, and each ingredient is load-bearing. `deviceId` is globally
+ * `@unique` while `computerId` is self-declared by the client — using the computer id verbatim would let
+ * one account squat another's row. Hashing the userId in namespaces it per account, and the environment
+ * keeps the "same person, separate rows per Autonomous plane" rule true regardless of how User rows are
+ * scoped. Determinism is what makes this a single idempotent upsert with no key to mint and therefore no
+ * create-lock: two daemons racing on the same computer converge on the same row.
+ *
+ * Identity is the SSO subject resolved upstream (`user.sub`), never email.
+ */
+ async resolveOrCreateForComputer(
+ userId: string,
+ autonomousEnv: 'prod' | 'stag',
+ computerId: string,
+ label: string,
+ ): Promise<DeviceBinding> {
+ const deviceId = `cmp-${sha256hex(`${userId}:${autonomousEnv}:${computerId}`).slice(0, 24)}`
+ const name = label.trim().slice(0, 120) || 'computer'
+ return prisma.deviceBinding.upsert({
+ where: { deviceId },
+ create: { userId, deviceId, computerId, name, lastSeenAt: new Date() },
+ // `userId` is re-applied so a computer that changed hands follows its owner. `name` is deliberately
+ // NOT overwritten: it is the user-editable display name, and a reconnect must not undo a rename —
+ // the same rule Machine.name follows.
+ update: { userId, computerId, lastSeenAt: new Date() },
+ })
+ },
+
+ /** The user's machines for the device machine-picker. Ordered oldest-first for a stable list.
+ *
+ * Scoped to ONE Autonomous plane. The same person legitimately owns separate machines per environment,
+ * and showing them together would let a device select a machine its token cannot drive — the check
+ * `webWs` has always made and this plane could not, until it gained an authenticated env of its own. */
+ async machinesForUser(userId: string, autonomousEnv?: 'prod' | 'stag'): Promise<Array<{ machineId: string; name: string; authMode: 'self' | 'managed' | 'remote' | 'provider' | 'provider'; remote: boolean }>> {
+ const rows = await prisma.machine.findMany({
+ where: { userId, ...(autonomousEnv ? { autonomousEnv } : {}), ...machineAlive },
+ orderBy: { createdAt: 'asc' },
+ })
+ return rows.filter(machineBillingAllowsDataPlane).map((r) => {
+ const authMode = r.authMode === 'managed' || r.authMode === 'remote' || r.authMode === 'provider' ? r.authMode : 'self'
+ // `remote` here means "backed by the owner's own machine", which drives the device's
+ // "Offline" badge. A provider machine is never offline in that sense, so it is NOT remote.
+ return { machineId: r.machineId, name: r.name?.trim() || machineDisplayName(r.machineId), authMode, remote: authMode === 'remote' }
+ })
+ },
+
+ /** A user's paired devices (no tokens). */
+ async listForUser(userId: string): Promise<DeviceView[]> {
+ const rows = await prisma.deviceBinding.findMany({ where: { userId }, orderBy: { createdAt: 'desc' } })
+ return rows.map(toDeviceView)
+ },
+
+ /** A user's devices with their live state, for a client that has no socket of its own (the mobile app).
+ * `online` is one Redis GET per device — fine at the scale a person owns; revisit with a pipeline if a
+ * single account ever holds dozens. */
+ async listDetailedForUser(userId: string): Promise<DeviceDetail[]> {
+ const rows = await prisma.deviceBinding.findMany({ where: { userId }, orderBy: { createdAt: 'desc' } })
+ const presence = await Promise.all(rows.map((r) => getDevicePresence(r.deviceId)))
+ return rows.map((r, i) => toDeviceDetail(r, presence[i]))
+ },
+
+ /** One of the user's devices, or null when it is not theirs. Ownership is enforced in the query. */
+ async detailForUser(deviceId: string, userId: string): Promise<DeviceDetail | null> {
+ const d = await prisma.deviceBinding.findFirst({ where: { deviceId, userId } })
+ if (!d) return null
+ return toDeviceDetail(d, await getDevicePresence(d.deviceId))
+ },
+
+ /**
+ * Snapshot what the device just told us in `device_hello`.
+ *
+ * Only keys the device ACTUALLY sent are written. That matters for `ssid`/`rssi`: firmware without
+ * them must not blank a value a newer build had already recorded, and a build that does send them
+ * refreshes on every connect. `rssi: 0` is the firmware's "unknown/disconnected" sentinel
+ * (`wifi_sta.c:136`), so it is dropped rather than stored as a real reading.
+ *
+ * Best-effort by design: this is called from the device socket's hot path, and a Mongo blip must
+ * never take a live device down.
+ */
+ async recordHello(input: {
+ deviceId: string
+ firmwareVersion?: string | null
+ chip?: string | null
+ ssid?: string | null
+ rssi?: number | null
+ }): Promise<void> {
+ const data: Record<string, unknown> = {}
+ if (input.firmwareVersion) data.firmwareVersion = input.firmwareVersion
+ if (input.chip) data.chip = input.chip
+ if (input.ssid) data.ssid = input.ssid
+ if (typeof input.rssi === 'number' && Number.isFinite(input.rssi) && input.rssi !== 0) data.rssi = Math.trunc(input.rssi)
+ if (Object.keys(data).length === 0) return
+ await prisma.deviceBinding
+ .updateMany({ where: { deviceId: input.deviceId }, data })
+ .catch((err: unknown) => logger.warn('recordHello failed', { deviceId: input.deviceId, error: String(err) }))
+ },
+
+ /**
+ * Persist which machine the device is attached to right now.
+ *
+ * NOT cleared when the socket closes, deliberately. A device that reconnects within milliseconds
+ * would otherwise race its own previous socket's teardown and flicker to null while genuinely
+ * attached. On an offline device the retained value reads as "last attached to", which is the more
+ * useful of the two answers anyway — clients gate this field on `online` (see the mobile spec).
+ * `null` is still written when a machine is deleted out from under the device.
+ */
+ async setActiveMachine(deviceId: string, machineId: string | null): Promise<void> {
+ await prisma.deviceBinding
+ .updateMany({ where: { deviceId }, data: { activeMachineId: machineId } })
+ .catch((err: unknown) => logger.warn('setActiveMachine failed', { deviceId, error: String(err) }))
+ },
+
+ /** Rename one of the user's devices. Null when the device is not theirs — same ownership rule as revoke. */
+ async rename(deviceId: string, userId: string, name: string): Promise<DeviceDetail | null> {
+ const d = await prisma.deviceBinding.findFirst({ where: { deviceId, userId } })
+ if (!d) return null
+ const updated = await prisma.deviceBinding.update({ where: { id: d.id }, data: { name } })
+ logger.info('device renamed', { userId, deviceId, name })
+ return toDeviceDetail(updated, await getDevicePresence(deviceId))
+ },
+
+ /** Revoke (delete) one of the user's devices. Returns the deviceId + ALL the user's machineIds so the
+ * caller can push a `device_revoked` frame on each (a per-user device is attached under whichever
+ * machine it currently has selected; the targetDeviceId filter means only that one socket receives it).
+ * Null if nothing matched. */
+ async revoke(deviceId: string, userId: string): Promise<{ deviceId: string; machineIds: string[] } | null> {
+ const d = await prisma.deviceBinding.findFirst({ where: { deviceId, userId } })
+ if (!d) return null
+ await prisma.deviceBinding.delete({ where: { id: d.id } }).catch(() => {})
+ const machines = await prisma.machine.findMany({
+ where: { userId, ...machineAlive }, select: { machineId: true, billingStatus: true },
+ })
+ return { deviceId: d.deviceId, machineIds: machines.filter(machineBillingAllowsDataPlane).map((f) => f.machineId) }
+ },
+}
diff --git a/backend/src/services/MachineBillingService.test.ts b/backend/src/services/MachineBillingService.test.ts
new file mode 100644
index 000000000..0c116d9cc
--- /dev/null
+++ b/backend/src/services/MachineBillingService.test.ts
@@ -0,0 +1,992 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const db = vi.hoisted(() => ({
+ transaction: vi.fn(),
+ bindingFind: vi.fn(),
+ bindingUpdate: vi.fn(),
+ bindingUpdateMany: vi.fn(),
+ planFind: vi.fn(),
+ planFindMany: vi.fn(),
+ planFindFirst: vi.fn(),
+ attemptFindFirst: vi.fn(),
+ attemptCreate: vi.fn(),
+ attemptUpdate: vi.fn(),
+ attemptUpdateMany: vi.fn(),
+ managerFind: vi.fn(),
+ freeFind: vi.fn(),
+ freeCreate: vi.fn(),
+ freeUpdate: vi.fn(),
+ freeDeleteMany: vi.fn(),
+}))
+const bff = vi.hoisted(() => ({
+ getDevice: vi.fn(),
+ listSubscriptions: vi.fn(),
+ createDevice: vi.fn(),
+ createCheckout: vi.fn(),
+ fireDevice: vi.fn(),
+ cancelSubscription: vi.fn(),
+ renewSubscription: vi.fn(),
+}))
+const provision = vi.hoisted(() => vi.fn())
+const publishDown = vi.hoisted(() => vi.fn())
+const encrypt = vi.hoisted(() => vi.fn(() => 'encrypted-key'))
+const voiceSnapshot = vi.hoisted(() => vi.fn())
+
+vi.mock('../config/env.js', () => ({
+ env: {
+ HARNESS_CAMPAIGN_CODE: 'ai-harness-device',
+ HARNESS_CHECKOUT_CALLBACK_URL: '',
+ },
+}))
+vi.mock('../lib/prisma.js', () => ({
+ // The real value — `suspendIfDue`'s guard is asserted below, so a stub would make that assertion
+ // check the stub instead of the filter.
+ machineAlive: { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] },
+ prisma: {
+ $transaction: db.transaction,
+ machine: { findUnique: db.bindingFind, update: db.bindingUpdate, updateMany: db.bindingUpdateMany },
+ subscriptionPlan: { findUnique: db.planFind, findMany: db.planFindMany, findFirst: db.planFindFirst },
+ machineCheckoutAttempt: {
+ findFirst: db.attemptFindFirst,
+ create: db.attemptCreate,
+ update: db.attemptUpdate,
+ updateMany: db.attemptUpdateMany,
+ },
+ machineFreeEntitlement: {
+ findUnique: db.freeFind,
+ create: db.freeCreate,
+ update: db.freeUpdate,
+ deleteMany: db.freeDeleteMany,
+ },
+ manager: { findUnique: db.managerFind },
+ },
+}))
+vi.mock('../lib/autonomousBff.js', () => ({
+ getCampaignDevice: bff.getDevice,
+ listCampaignSubscriptions: bff.listSubscriptions,
+ createCampaignDevice: bff.createDevice,
+ createCheckout: bff.createCheckout,
+ fireCampaignDevice: bff.fireDevice,
+ cancelCampaignSubscription: bff.cancelSubscription,
+ renewCampaignSubscription: bff.renewSubscription,
+}))
+vi.mock('../lib/bus.js', () => ({
+ pub: { set: vi.fn(async () => 'OK'), eval: vi.fn(async () => 1) },
+ publishDeviceMachineListChanged: vi.fn(async () => undefined),
+ publishDown,
+}))
+vi.mock('../lib/machineCredential.js', () => ({ encryptMachineCredential: encrypt }))
+vi.mock('../lib/managers.js', () => ({ selectManagerId: vi.fn(async () => ({ managerId: 'mgr-2' })) }))
+vi.mock('../lib/provision.js', () => ({ provisionViaManager: provision }))
+vi.mock('../utils/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }))
+vi.mock('../lib/voiceQuota.js', () => ({
+ voiceQuotaService: { snapshotForMachine: voiceSnapshot },
+}))
+
+import { machineBillingService } from './MachineBillingService.js'
+import { AppError } from '../errors/index.js'
+
+const future = new Date(Date.now() + 86_400_000)
+const overdue = new Date(Date.now() - 7_200_000)
+const withinGrace = new Date(Date.now() - 1_800_000)
+const binding = {
+ id: 'binding-id', userId: 'user-1', machineId: 'a'.repeat(32), apiKey: 'agent-key',
+ managerId: 'mgr-1', workspaceId: null, planId: 'plan-pro', authMode: 'managed', name: null,
+ autonomousEnv: 'prod',
+ billingStatus: 'pending', externalDeviceId: 'device-1', externalSubscriptionId: null,
+ externalSubscriptionStatus: null, externalSubscriptionEndAt: null, externalSubscriptionCancelledAt: null,
+ billingActivatedAt: null, billingError: null, billingErrorAt: null, llmApiKeyEncrypted: null,
+ deletedAt: null, createdAt: new Date(), updatedAt: new Date(),
+}
+const proPlan = {
+ id: 'plan-pro', name: 'Pro', cpus: '1', memory: '2g', maxAgents: 10, priceUsd: 20,
+ dailyVoiceLimitSeconds: 1800,
+ autonomousEnv: 'prod',
+ authMode: 'managed', isDefault: false, available: true, externalPlanId: 38,
+ externalPlanName: 'Pro', campaignCode: 'ai-harness-device', externalMetadata: null,
+ catalogSource: 'autonomous-bff', catalogSyncedAt: new Date(), createdAt: new Date(), updatedAt: new Date(),
+}
+const maxPlan = { ...proPlan, id: 'plan-max', name: 'Max', priceUsd: 100, dailyVoiceLimitSeconds: 0, externalPlanId: 39 }
+const freePlan = { ...proPlan, id: 'plan-free', name: 'Free', priceUsd: 0, dailyVoiceLimitSeconds: 600, externalPlanId: 37 }
+const remotePlan = {
+ ...proPlan,
+ id: 'plan-remote',
+ name: 'Remote',
+ priceUsd: 10,
+ externalPlanId: 40,
+ dailyVoiceLimitSeconds: 3600,
+ authMode: 'remote',
+}
+const attempt = {
+ id: 'attempt-1', machineId: binding.machineId, userId: binding.userId, externalPlanId: 38,
+ autonomousEnv: 'prod',
+ externalDeviceId: 'device-1', sessionId: 'operation-1', operationId: 'operation-1',
+ operationType: 'subscribe', sourcePlanId: 'plan-pro', targetPlanId: 'plan-pro',
+ providerSessionId: 'checkout-1', redirectUrl: 'https://checkout.example/session',
+ checkoutEmail: '[email protected]', successUrl: 'http://localhost/success',
+ failureUrl: 'http://localhost/failure', webOrigin: 'http://localhost:3000',
+ status: 'pending', error: null, completedAt: null, createdAt: new Date(), updatedAt: new Date(),
+}
+
+function planById(id?: string) {
+ if (id === freePlan.id) return freePlan
+ if (id === maxPlan.id) return maxPlan
+ if (id === remotePlan.id) return remotePlan
+ return proPlan
+}
+
+function exactSubscription(planId = 38, status = 2) {
+ return {
+ id: 'sub-1', campaignCode: 'ai-harness-device', referenceId: 'device-1',
+ planId, status, endAt: future,
+ }
+}
+
+describe('machine billing lifecycle', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ db.bindingFind.mockResolvedValue(binding)
+ db.bindingUpdate.mockImplementation(async ({ data }: { data: object }) => ({ ...binding, ...data }))
+ db.bindingUpdateMany.mockResolvedValue({ count: 1 })
+ db.planFind.mockImplementation(async ({ where }: { where: { id?: string } }) => planById(where.id))
+ db.planFindMany.mockResolvedValue([freePlan, proPlan, maxPlan])
+ db.planFindFirst.mockResolvedValue(proPlan)
+ // Checkout creation/pending-view queries return no operation by default. Legacy/new callback
+ // lookups use OR and resolve the immutable operation fixture.
+ db.attemptFindFirst.mockImplementation(async ({ where }: { where?: { OR?: unknown } }) => where?.OR ? attempt : null)
+ db.attemptCreate.mockImplementation(async ({ data }: { data: object }) => ({ id: 'attempt-new', ...data }))
+ db.attemptUpdate.mockResolvedValue(attempt)
+ db.attemptUpdateMany.mockResolvedValue({ count: 1 })
+ db.transaction.mockImplementation(async (action: (tx: unknown) => Promise<unknown>) => action({
+ machine: { update: db.bindingUpdate },
+ machineFreeEntitlement: {
+ findUnique: db.freeFind,
+ create: db.freeCreate,
+ update: db.freeUpdate,
+ },
+ }))
+ db.managerFind.mockResolvedValue({ managerId: 'mgr-1', lastSeenAt: new Date() })
+ db.freeFind.mockResolvedValue(null)
+ db.freeCreate.mockResolvedValue({})
+ db.freeUpdate.mockResolvedValue({})
+ db.freeDeleteMany.mockResolvedValue({ count: 1 })
+ bff.listSubscriptions.mockResolvedValue([])
+ bff.createDevice.mockResolvedValue('device-1')
+ bff.createCheckout.mockResolvedValue({ sessionId: 'checkout-1', redirectUrl: 'https://checkout.example/session' })
+ bff.fireDevice.mockResolvedValue(undefined)
+ bff.cancelSubscription.mockResolvedValue(undefined)
+ bff.renewSubscription.mockResolvedValue(undefined)
+ publishDown.mockResolvedValue(undefined)
+ provision.mockResolvedValue({})
+ voiceSnapshot.mockResolvedValue({
+ machineId: binding.machineId,
+ dayKey: '2026-07-24',
+ limitSeconds: 1800,
+ usedSeconds: 380,
+ remainingSeconds: 1420,
+ resetAt: '2026-07-25T00:00:00.000Z',
+ })
+ })
+
+ it('creates an immutable operation before checkout and never provisions a pending machine', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, externalDeviceId: null })
+
+ const result = await machineBillingService.beginCheckout(
+ binding.machineId, binding.userId, '[email protected]', 'sso-token', 'http://localhost:3000',
+ )
+
+ expect(result).toMatchObject({
+ operationId: expect.any(String), action: 'subscribe',
+ sessionId: 'checkout-1', redirectUrl: 'https://checkout.example/session',
+ })
+ expect(bff.createDevice).toHaveBeenCalledWith('prod', 'sso-token')
+ expect(db.attemptCreate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({
+ operationId: result!.operationId,
+ sessionId: result!.operationId,
+ targetPlanId: 'plan-pro',
+ externalPlanId: 38,
+ }),
+ }))
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('activates a paid Remote machine without an llm key, manager reservation, or Docker', async () => {
+ const remoteBinding = {
+ ...binding,
+ managerId: '',
+ planId: remotePlan.id,
+ authMode: 'remote',
+ billingStatus: 'pending',
+ }
+ const remoteAttempt = {
+ ...attempt,
+ externalPlanId: 40,
+ sourcePlanId: remotePlan.id,
+ targetPlanId: remotePlan.id,
+ }
+ db.bindingFind.mockResolvedValue(remoteBinding)
+ db.attemptFindFirst.mockResolvedValue(remoteAttempt)
+ db.bindingUpdate.mockImplementation(async ({ data }: { data: object }) => ({ ...remoteBinding, ...data }))
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', subscription: exactSubscription(40) })
+
+ await expect(machineBillingService.complete(
+ remoteBinding.machineId, remoteBinding.userId, 'sso-token', 'operation-1', 'success',
+ )).resolves.toMatchObject({ billingStatus: 'active' })
+
+ expect(db.bindingUpdate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({
+ managerId: '', planId: remotePlan.id, billingStatus: 'active', llmApiKeyEncrypted: null,
+ }),
+ }))
+ expect(encrypt).not.toHaveBeenCalled()
+ expect(db.managerFind).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('supersedes pending operations and creates a fresh checkout for every click', async () => {
+ const result = await machineBillingService.beginCheckout(
+ binding.machineId, binding.userId, '[email protected]', 'sso-token', 'http://localhost:3000',
+ )
+
+ expect(result).toMatchObject({
+ operationId: expect.any(String), sessionId: 'checkout-1',
+ redirectUrl: 'https://checkout.example/session', action: 'subscribe',
+ })
+ expect(result.operationId).not.toBe('operation-1')
+ expect(db.attemptUpdateMany).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId, status: { in: ['creating', 'pending'] } },
+ data: { status: 'cancelled', error: 'Superseded by a newer checkout' },
+ })
+ expect(bff.createCheckout).toHaveBeenCalledOnce()
+ expect(db.attemptCreate).toHaveBeenCalledOnce()
+ })
+
+ it('creates a hosted Free card setup without claiming or provisioning before the callback', async () => {
+ const pendingFree = { ...binding, planId: freePlan.id }
+ db.bindingFind.mockResolvedValue(pendingFree)
+ db.freeFind.mockResolvedValue({
+ userId: binding.userId,
+ machineId: binding.machineId,
+ status: 'reserved',
+ claimedAt: null,
+ })
+ const checkout = await machineBillingService.beginCheckout(
+ binding.machineId,
+ binding.userId,
+ 'sso-token',
+ 'http://localhost:3000',
+ )
+
+ expect(checkout).toMatchObject({
+ operationId: expect.any(String), action: 'subscribe',
+ sessionId: 'checkout-1', redirectUrl: 'https://checkout.example/session',
+ })
+ expect(bff.createCheckout).toHaveBeenCalledWith('prod', 'sso-token', expect.objectContaining({
+ planId: 37,
+ referenceId: 'device-1',
+ successUrl: expect.stringContaining(`machineId=${binding.machineId}`),
+ }))
+ expect(db.attemptCreate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({
+ operationId: checkout.operationId,
+ targetPlanId: freePlan.id,
+ externalPlanId: 37,
+ }),
+ }))
+ expect(db.freeUpdate).not.toHaveBeenCalled()
+ expect(encrypt).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('keeps Free pending when the provider does not return a hosted card setup URL', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, planId: freePlan.id })
+ bff.createCheckout.mockResolvedValue({ sessionId: 'checkout-1' })
+
+ await expect(machineBillingService.beginCheckout(
+ binding.machineId,
+ binding.userId,
+ 'sso-token',
+ 'http://localhost:3000',
+ )).rejects.toMatchObject({ code: 'BILLING_UPSTREAM_ERROR' })
+
+ expect(db.attemptUpdate).toHaveBeenCalledWith({
+ where: { id: 'attempt-new' },
+ data: {
+ status: 'failed',
+ error: 'Autonomous billing service did not return a Free card setup URL',
+ },
+ })
+ expect(db.bindingUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
+ where: { machineId: binding.machineId, billingStatus: 'pending' },
+ }))
+ expect(db.freeUpdate).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('creates a fresh plan-change checkout instead of exposing an existing pending attempt', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ billingStatus: 'active',
+ externalSubscriptionStatus: 2,
+ externalSubscriptionEndAt: future,
+ })
+
+ const result = await machineBillingService.beginPlanCheckout(
+ binding.machineId,
+ binding.userId,
+ maxPlan.id,
+ 'sso-token',
+ 'https://app.example.com',
+ )
+
+ expect(result).toMatchObject({
+ operationId: expect.any(String),
+ sessionId: 'checkout-1',
+ action: 'upgrade',
+ })
+ expect(db.attemptUpdateMany).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId, status: { in: ['creating', 'pending'] } },
+ data: { status: 'cancelled', error: 'Superseded by a newer checkout' },
+ })
+ expect(db.attemptCreate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({
+ operationType: 'plan_change',
+ sourcePlanId: proPlan.id,
+ targetPlanId: maxPlan.id,
+ }),
+ }))
+ expect(bff.createCheckout).toHaveBeenCalledOnce()
+ })
+
+ it('never allows an active Remote machine to change plans', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ managerId: '',
+ planId: remotePlan.id,
+ authMode: 'remote',
+ billingStatus: 'active',
+ externalSubscriptionStatus: 2,
+ })
+
+ await expect(machineBillingService.beginPlanCheckout(
+ binding.machineId, binding.userId, remotePlan.id, '[email protected]', 'sso-token', 'https://app.example.com',
+ )).rejects.toMatchObject({ code: 'REMOTE_PLAN_CHANGE_NOT_ALLOWED' })
+ expect(bff.createCheckout).not.toHaveBeenCalled()
+ })
+
+ it('lets a suspended Remote machine re-subscribe only to the same Remote plan', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ managerId: '',
+ planId: remotePlan.id,
+ authMode: 'remote',
+ billingStatus: 'suspended',
+ externalSubscriptionStatus: 5,
+ })
+
+ const result = await machineBillingService.beginPlanCheckout(
+ binding.machineId, binding.userId, remotePlan.id, '[email protected]', 'sso-token', 'https://app.example.com',
+ )
+
+ expect(result.action).toBe('subscribe')
+ expect(db.attemptCreate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({ targetPlanId: remotePlan.id, externalPlanId: 40 }),
+ }))
+ })
+
+ it('does not activate or provision when subscription identity mismatches', async () => {
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', llmApiKey: 'secret', subscription: exactSubscription(39) })
+
+ await expect(machineBillingService.activate(
+ binding.machineId, binding.userId, '[email protected]', 'sso-token', 'http://localhost:3000', 'checkout-1',
+ )).rejects.toMatchObject({ code: 'PAYMENT_NOT_VERIFIED' })
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('encrypts the campaign key, activates, and provisions after exact verification', async () => {
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', llmApiKey: 'secret', subscription: exactSubscription() })
+
+ await machineBillingService.activate(
+ binding.machineId, binding.userId, '[email protected]', 'sso-token', 'http://localhost:3000', 'checkout-1',
+ )
+
+ expect(db.bindingUpdate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({ billingStatus: 'active', llmApiKeyEncrypted: 'encrypted-key' }),
+ }))
+ await vi.waitFor(() => expect(provision).toHaveBeenCalledWith(
+ 'mgr-1', 'create', expect.objectContaining({ apiKey: 'agent-key' }),
+ ))
+ })
+
+ it('claims and activates Free only after the hosted checkout callback is verified', async () => {
+ const pendingFree = { ...binding, planId: freePlan.id }
+ const freeAttempt = {
+ ...attempt,
+ externalPlanId: 37,
+ sourcePlanId: freePlan.id,
+ targetPlanId: freePlan.id,
+ }
+ db.bindingFind.mockResolvedValue(pendingFree)
+ db.bindingUpdate.mockImplementation(async ({ data }: { data: object }) => ({ ...pendingFree, ...data }))
+ db.attemptFindFirst.mockResolvedValue(freeAttempt)
+ db.freeFind.mockResolvedValue({
+ userId: binding.userId,
+ machineId: binding.machineId,
+ status: 'reserved',
+ claimedAt: null,
+ })
+ bff.getDevice.mockResolvedValue({
+ deviceId: 'device-1',
+ llmApiKey: 'free-secret',
+ subscription: exactSubscription(37),
+ })
+
+ await expect(machineBillingService.complete(
+ binding.machineId, binding.userId, 'sso-token', 'operation-1', 'success',
+ )).resolves.toMatchObject({ billingStatus: 'active' })
+
+ expect(db.freeUpdate).toHaveBeenCalledWith({
+ where: { userId_autonomousEnv: { userId: binding.userId, autonomousEnv: 'prod' } },
+ data: { status: 'claimed', claimedAt: expect.any(Date) },
+ })
+ expect(db.bindingUpdate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({
+ billingStatus: 'active',
+ externalSubscriptionId: 'sub-1',
+ externalSubscriptionStatus: 2,
+ llmApiKeyEncrypted: 'encrypted-key',
+ }),
+ }))
+ await vi.waitFor(() => expect(provision).toHaveBeenCalledWith(
+ 'mgr-1', 'create', expect.objectContaining({ apiKey: 'agent-key' }),
+ ))
+ })
+
+ it('keeps the Free reservation and machine pending when card setup is cancelled', async () => {
+ const pendingFree = { ...binding, planId: freePlan.id }
+ const freeAttempt = {
+ ...attempt,
+ externalPlanId: 37,
+ sourcePlanId: freePlan.id,
+ targetPlanId: freePlan.id,
+ }
+ db.bindingFind.mockResolvedValue(pendingFree)
+ db.attemptFindFirst.mockResolvedValue(freeAttempt)
+
+ await expect(machineBillingService.complete(
+ binding.machineId, binding.userId, 'sso-token', 'operation-1', 'cancelled',
+ )).resolves.toMatchObject({ billingStatus: 'pending' })
+
+ expect(db.attemptUpdate).toHaveBeenCalledWith({
+ where: { id: freeAttempt.id }, data: { status: 'cancelled' },
+ })
+ expect(db.freeUpdate).not.toHaveBeenCalled()
+ expect(db.freeDeleteMany).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('adopts a renewed paid plan and clears the previous cancellation timestamp', async () => {
+ const cancelledAt = new Date('2026-07-20T00:00:00.000Z')
+ const renewedEndAt = new Date('2026-08-24T00:00:00.000Z')
+ const active = {
+ ...binding,
+ billingStatus: 'active',
+ externalSubscriptionId: 'sub-1',
+ externalSubscriptionStatus: 3,
+ externalSubscriptionEndAt: withinGrace,
+ externalSubscriptionCancelledAt: cancelledAt,
+ }
+ db.bindingFind.mockResolvedValue(active)
+ db.planFindFirst.mockResolvedValue(maxPlan)
+ db.bindingUpdate.mockImplementation(async ({ data }: { data: object }) => ({ ...active, ...data }))
+
+ await expect(machineBillingService.syncSubscription(binding.machineId, {
+ id: 'sub-1',
+ campaignCode: 'ai-harness-device',
+ planId: 39,
+ status: 2,
+ endAt: renewedEndAt,
+ }, 'sub-1')).resolves.toMatchObject({ changed: true })
+
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId },
+ data: {
+ planId: maxPlan.id,
+ externalSubscriptionStatus: 2,
+ externalSubscriptionEndAt: renewedEndAt,
+ externalSubscriptionCancelledAt: null,
+ },
+ })
+ })
+
+ it('does not rewrite unchanged subscription metadata on every worker pass', async () => {
+ const active = {
+ ...binding,
+ billingStatus: 'active',
+ externalSubscriptionId: 'sub-1',
+ externalSubscriptionStatus: 2,
+ externalSubscriptionEndAt: future,
+ }
+ db.bindingFind.mockResolvedValue(active)
+
+ await expect(machineBillingService.syncSubscription(
+ binding.machineId,
+ exactSubscription(),
+ 'sub-1',
+ )).resolves.toMatchObject({ changed: false })
+
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ })
+
+ it('does not apply a stale snapshot after checkout replaces the subscription id', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ billingStatus: 'active',
+ externalSubscriptionId: 'sub-new',
+ })
+
+ await expect(machineBillingService.syncSubscription(
+ binding.machineId,
+ exactSubscription(),
+ 'sub-old',
+ )).resolves.toBeNull()
+
+ expect(db.planFindFirst).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ })
+
+ it('returns fresh daily usage and plan limits with the billing view', async () => {
+ const planWithQuota = { ...proPlan, externalMetadata: { daily_token_limit: 50_000_000 } }
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ db.planFind.mockResolvedValue(planWithQuota)
+ db.planFindMany.mockResolvedValue([
+ { ...freePlan, externalMetadata: { daily_token_limit: 10_000_000 } },
+ planWithQuota,
+ { ...maxPlan, externalMetadata: { daily_token_limit: 0 } },
+ ])
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', dailyUsage: 230_946 })
+
+ const result = await machineBillingService.getBilling(binding.machineId, binding.userId, 'sso-token')
+
+ expect(result.stale).toBe(false)
+ expect(result.usage.dailyTokens).toBe(230_946)
+ expect(result.usage.dailyVoiceSeconds).toBe(380)
+ expect(result.usage.voiceResetAt).toBe('2026-07-25T00:00:00.000Z')
+ expect(result.currentPlan?.dailyTokenLimit).toBe(50_000_000)
+ expect(result.currentPlan?.dailyVoiceLimitSeconds).toBe(1800)
+ expect(result.plans.map((plan) => [plan.name, plan.dailyTokenLimit])).toEqual([
+ ['Free', 10_000_000], ['Pro', 50_000_000], ['Max', 0],
+ ])
+ expect(result.plans.map((plan) => [plan.name, plan.dailyVoiceLimitSeconds])).toEqual([
+ ['Free', 600], ['Pro', 1800], ['Max', 0],
+ ])
+ })
+
+ it('does not mark billing stale or block actions when only usage refresh fails', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+ bff.getDevice.mockRejectedValue(new Error('device usage unavailable'))
+
+ const result = await machineBillingService.getBilling(binding.machineId, binding.userId, 'sso-token')
+
+ expect(result.stale).toBe(false)
+ expect(result.usage.dailyTokens).toBeNull()
+ })
+
+ it('keeps fresh usage visible when subscription refresh falls back to cached billing', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockRejectedValue(new Error('subscription service unavailable'))
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', dailyUsage: 125_268 })
+
+ const result = await machineBillingService.getBilling(binding.machineId, binding.userId, 'sso-token')
+
+ expect(result.stale).toBe(true)
+ expect(result.usage.dailyTokens).toBe(125_268)
+ })
+
+ it('uses the authoritative subscription list when the device projection is delayed', async () => {
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', llmApiKey: 'secret' })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+
+ await machineBillingService.complete(binding.machineId, binding.userId, 'sso-token', 'operation-1', 'success')
+
+ expect(db.bindingUpdate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({ billingStatus: 'active', externalSubscriptionId: 'sub-1' }),
+ }))
+ })
+
+ it('verifies the immutable attempt plan if the catalog changes during checkout', async () => {
+ db.planFind.mockResolvedValue({ ...proPlan, externalPlanId: 99 })
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', llmApiKey: 'secret', subscription: exactSubscription(38) })
+
+ await expect(machineBillingService.complete(
+ binding.machineId, binding.userId, 'sso-token', 'operation-1', 'success',
+ )).resolves.toMatchObject({ billingStatus: 'active' })
+ expect(bff.getDevice).toHaveBeenCalled()
+ })
+
+ it('supports a legacy provider session callback with no operationId or targetPlanId', async () => {
+ const legacy = { ...attempt, operationId: null, targetPlanId: null, sessionId: 'checkout-legacy', providerSessionId: null }
+ db.attemptFindFirst.mockImplementation(async ({ where }: { where?: { OR?: unknown } }) => where?.OR ? legacy : null)
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', llmApiKey: 'secret', subscription: exactSubscription() })
+
+ await expect(machineBillingService.activate(
+ binding.machineId, binding.userId, '[email protected]', 'sso-token', 'http://localhost:3000', 'checkout-legacy',
+ )).resolves.toBeUndefined()
+ expect(db.bindingUpdate).toHaveBeenCalledWith(expect.objectContaining({
+ data: expect.objectContaining({ billingStatus: 'active' }),
+ }))
+ })
+
+ it('rejects a success callback from a superseded checkout', async () => {
+ db.attemptFindFirst.mockResolvedValue({ ...attempt, status: 'cancelled' })
+
+ await expect(machineBillingService.complete(
+ binding.machineId, binding.userId, 'sso-token', 'operation-1', 'success',
+ )).rejects.toMatchObject({ code: 'CHECKOUT_SUPERSEDED' })
+ expect(bff.getDevice).not.toHaveBeenCalled()
+ })
+
+ it('keeps the machine pending while its campaign credential is not ready', async () => {
+ bff.getDevice.mockResolvedValue({ deviceId: 'device-1', subscription: exactSubscription() })
+
+ await expect(machineBillingService.complete(
+ binding.machineId, binding.userId, 'sso-token', 'operation-1', 'success',
+ )).rejects.toMatchObject({ code: 'CAMPAIGN_CREDENTIAL_NOT_READY' })
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('blocks every downgrade to Free', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active', externalSubscriptionStatus: 2 })
+
+ await expect(machineBillingService.beginPlanCheckout(
+ binding.machineId, binding.userId, freePlan.id, '[email protected]', 'sso-token', 'http://localhost:3000',
+ )).rejects.toMatchObject({ code: 'FREE_DOWNGRADE_NOT_ALLOWED' })
+ })
+
+ it('rejects a new plan-change checkout when its callback is not HTTPS', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active', externalSubscriptionStatus: 2 })
+
+ await expect(machineBillingService.beginPlanCheckout(
+ binding.machineId, binding.userId, maxPlan.id, '[email protected]', 'sso-token', 'http://localhost:3000',
+ )).rejects.toMatchObject({ code: 'CHECKOUT_CALLBACK_HTTPS_REQUIRED' })
+ expect(db.attemptCreate).not.toHaveBeenCalled()
+ expect(bff.createCheckout).not.toHaveBeenCalled()
+ })
+
+ it('enforces the account-level one-time Free entitlement', async () => {
+ db.freeCreate.mockRejectedValueOnce(new Error('duplicate key'))
+ db.freeFind.mockResolvedValue({ userId: binding.userId, machineId: 'another-machine', status: 'claimed' })
+
+ await expect(machineBillingService.reserveFreeEntitlement(binding.userId, binding.machineId, freePlan))
+ .rejects.toMatchObject({ code: 'FREE_PLAN_ALREADY_USED' })
+ })
+
+ it('cancels a paid subscription at period end without stopping the machine immediately', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active', externalSubscriptionStatus: 2 })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription(38, 2)])
+
+ const result = await machineBillingService.cancel(binding.machineId, binding.userId, 'sso-token')
+
+ expect(bff.cancelSubscription).toHaveBeenCalledWith('prod', 'sso-token', 'sub-1')
+ expect(result.subscription.status).toBe(3)
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('renews a cancellation only before its current period ends', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding, billingStatus: 'active', externalSubscriptionId: 'sub-1',
+ externalSubscriptionStatus: 3, externalSubscriptionEndAt: future,
+ })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription(38, 3)])
+
+ const result = await machineBillingService.renew(binding.machineId, binding.userId, 'sso-token')
+
+ expect(bff.renewSubscription).toHaveBeenCalledWith('prod', 'sso-token', 'sub-1')
+ expect(result.subscription.status).toBe(2)
+ })
+
+ it('suspends a managed machine when endAt is overdue by more than one hour without changing upstream status', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding, billingStatus: 'active', externalSubscriptionStatus: 2, externalSubscriptionEndAt: overdue,
+ })
+
+ await expect(machineBillingService.suspendIfDue(binding.machineId)).resolves.toBe(true)
+ // The guard is an AND of two ORs: "not soft-deleted" (which must accept a legacy row that lacks
+ // the field entirely) and "overdue". As sibling keys one `OR` would overwrite the other, so the
+ // nesting is the assertion — a bare `deletedAt: null` here silently skipped every legacy machine.
+ expect(db.bindingUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
+ where: expect.objectContaining({
+ billingStatus: 'active',
+ authMode: { in: ['managed', 'remote', 'provider'] },
+ AND: [
+ { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] },
+ {
+ OR: [
+ { externalSubscriptionEndAt: { lte: expect.any(Date) } },
+ { externalSubscriptionStatus: 5 },
+ ],
+ },
+ ],
+ }),
+ data: { billingStatus: 'suspended' },
+ }))
+ expect(provision).toHaveBeenCalledWith('mgr-1', 'stop', { machineId: binding.machineId })
+ })
+
+ it('does not suspend before the one-hour endAt grace has elapsed', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding, billingStatus: 'active', externalSubscriptionStatus: 2, externalSubscriptionEndAt: withinGrace,
+ })
+
+ await expect(machineBillingService.suspendIfDue(binding.machineId)).resolves.toBe(false)
+ expect(db.bindingUpdateMany).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('does not stop the runtime when endAt changes before the guarded update', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding, billingStatus: 'active', externalSubscriptionStatus: 2, externalSubscriptionEndAt: overdue,
+ })
+ db.bindingUpdateMany.mockResolvedValue({ count: 0 })
+
+ await expect(machineBillingService.suspendIfDue(binding.machineId)).resolves.toBe(false)
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('also suspends when the provider already advanced the subscription to Expired', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding, billingStatus: 'active', externalSubscriptionStatus: 5,
+ externalSubscriptionEndAt: null,
+ })
+
+ await expect(machineBillingService.suspendIfDue(binding.machineId)).resolves.toBe(true)
+ expect(provision).toHaveBeenCalledWith('mgr-1', 'stop', { machineId: binding.machineId })
+ })
+
+ it('disconnects an overdue Remote adapter without stopping a manager runtime', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ managerId: '',
+ planId: remotePlan.id,
+ authMode: 'remote',
+ billingStatus: 'active',
+ externalSubscriptionStatus: 2,
+ externalSubscriptionEndAt: overdue,
+ })
+
+ await expect(machineBillingService.suspendIfDue(binding.machineId)).resolves.toBe(true)
+ expect(publishDown).toHaveBeenCalledWith(binding.machineId, {
+ connId: '', frame: { type: '__billing_suspended' },
+ })
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it.each([
+ ['self-auth', { authMode: 'self-auth', billingStatus: 'active', deletedAt: null }],
+ ['pending', { authMode: 'managed', billingStatus: 'pending', deletedAt: null }],
+ ['deleted', { authMode: 'managed', billingStatus: 'active', deletedAt: new Date() }],
+ ['already suspended', { authMode: 'managed', billingStatus: 'suspended', deletedAt: null }],
+ ])('does not process an overdue %s machine', async (_case, state) => {
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ ...state,
+ externalSubscriptionStatus: 2,
+ externalSubscriptionEndAt: overdue,
+ })
+
+ await expect(machineBillingService.suspendIfDue(binding.machineId)).resolves.toBe(false)
+ expect(db.bindingUpdateMany).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ expect(publishDown).not.toHaveBeenCalled()
+ })
+
+ it('fires the external device before soft-deleting a pending machine', async () => {
+ await machineBillingService.cancelPending(binding.machineId, binding.userId, 'sso-token')
+
+ expect(bff.fireDevice).toHaveBeenCalledWith('prod', 'sso-token', 'device-1')
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ })
+
+ it('cancels an active paid subscription and fires its device before local soft delete', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+
+ await machineBillingService.deleteCampaignMachine(binding.machineId, binding.userId, 'sso-token')
+
+ expect(bff.cancelSubscription).toHaveBeenCalledWith('prod', 'sso-token', 'sub-1')
+ expect(bff.fireDevice).toHaveBeenCalledWith('prod', 'sso-token', 'device-1')
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ expect(bff.cancelSubscription.mock.invocationCallOrder[0]).toBeLessThan(bff.fireDevice.mock.invocationCallOrder[0])
+ expect(bff.fireDevice.mock.invocationCallOrder[0]).toBeLessThan(db.bindingUpdate.mock.invocationCallOrder[0])
+ })
+
+ it('soft-deletes after cancellation when fire-intern rejects the now-cancelled subscription', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+ bff.fireDevice.mockRejectedValue(new AppError(
+ 'We’re sorry, but we are unable to process your request.', 503, 'BILLING_UPSTREAM_ERROR',
+ ))
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).resolves.toBeUndefined()
+
+ expect(bff.cancelSubscription).toHaveBeenCalledWith('prod', 'sso-token', 'sub-1')
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ })
+
+ it('keeps the local machine when upstream subscription cancellation fails', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+ bff.cancelSubscription.mockRejectedValue(new Error('provider unavailable'))
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).rejects.toThrow('provider unavailable')
+
+ expect(bff.fireDevice).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ })
+
+ it('soft-deletes when the provider reports no subscription for the device and then rejects fire-intern', async () => {
+ // "No subscription exists" is the strongest possible proof that nothing renews, but it used to
+ // leave renewalDisabled false, so a fire-intern 503 made the machine undeletable forever.
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockResolvedValue([])
+ bff.fireDevice.mockRejectedValue(new AppError(
+ 'We’re sorry, but we are unable to process your request.', 503, 'BILLING_UPSTREAM_ERROR',
+ ))
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).resolves.toBeUndefined()
+
+ expect(bff.cancelSubscription).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ })
+
+ it('deletes a never-activated machine whose subscription lookup the provider rejects', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'pending' })
+ bff.listSubscriptions.mockRejectedValue(new AppError(
+ 'We’re sorry, but we are unable to process your request.', 503, 'BILLING_UPSTREAM_ERROR',
+ ))
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).resolves.toBeUndefined()
+
+ expect(bff.fireDevice).toHaveBeenCalledWith('prod', 'sso-token', 'device-1')
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ })
+
+ it('keeps an activated machine when its subscription lookup cannot be verified', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding, billingStatus: 'active', externalSubscriptionId: 'sub-1', externalSubscriptionStatus: 2,
+ })
+ bff.listSubscriptions.mockRejectedValue(new AppError(
+ 'We’re sorry, but we are unable to process your request.', 503, 'BILLING_UPSTREAM_ERROR',
+ ))
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).rejects.toMatchObject({ code: 'BILLING_UPSTREAM_ERROR' })
+
+ expect(bff.fireDevice).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ })
+
+ it('keeps the machine when a proven live subscription cannot be cancelled', async () => {
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+ bff.cancelSubscription.mockRejectedValue(new AppError(
+ 'We’re sorry, but we are unable to process your request.', 503, 'BILLING_UPSTREAM_ERROR',
+ ))
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).rejects.toMatchObject({ code: 'BILLING_UPSTREAM_ERROR' })
+
+ expect(bff.fireDevice).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ })
+
+ it('deletes a machine whose plan left the catalog, with nothing upstream to cancel', async () => {
+ // A retired/re-synced plan (or a changed campaign code) used to fail the delete with
+ // PLAN_UNAVAILABLE forever — the owner could never remove the machine.
+ db.planFind.mockResolvedValue(null)
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active', externalDeviceId: null })
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).resolves.toBeUndefined()
+
+ expect(bff.cancelSubscription).not.toHaveBeenCalled()
+ expect(bff.fireDevice).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ })
+
+ it('still cancels upstream truth when the plan left the catalog but a device remains', async () => {
+ db.planFind.mockResolvedValue(null)
+ db.bindingFind.mockResolvedValue({ ...binding, billingStatus: 'active' })
+ bff.listSubscriptions.mockResolvedValue([exactSubscription()])
+
+ await machineBillingService.deleteCampaignMachine(binding.machineId, binding.userId, 'sso-token')
+
+ expect(bff.cancelSubscription).toHaveBeenCalledWith('prod', 'sso-token', 'sub-1')
+ expect(bff.fireDevice).toHaveBeenCalledWith('prod', 'sso-token', 'device-1')
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: binding.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ })
+
+ it('still refuses to hide a plan-less machine that has a subscription but no device', async () => {
+ db.planFind.mockResolvedValue(null)
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ billingStatus: 'active',
+ externalDeviceId: null,
+ externalSubscriptionId: 'sub-1',
+ })
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).rejects.toMatchObject({ code: 'BILLING_CLEANUP_REQUIRED' })
+
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ })
+
+ it('refuses to hide an active paid machine when its billing device reference is missing', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...binding,
+ billingStatus: 'active',
+ externalDeviceId: null,
+ externalSubscriptionId: 'sub-1',
+ })
+
+ await expect(machineBillingService.deleteCampaignMachine(
+ binding.machineId, binding.userId, 'sso-token',
+ )).rejects.toMatchObject({ code: 'BILLING_CLEANUP_REQUIRED' })
+
+ expect(bff.cancelSubscription).not.toHaveBeenCalled()
+ expect(bff.fireDevice).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ })
+})
diff --git a/backend/src/services/MachineBillingService.ts b/backend/src/services/MachineBillingService.ts
new file mode 100644
index 000000000..d60029fd5
--- /dev/null
+++ b/backend/src/services/MachineBillingService.ts
@@ -0,0 +1,1109 @@
+import type { Machine, SubscriptionPlan } from '@prisma/client'
+import { randomUUID } from 'node:crypto'
+import { env } from '../config/env.js'
+import { AppError, ForbiddenError, NotFoundError } from '../errors/index.js'
+import {
+ cancelCampaignSubscription,
+ createCampaignDevice,
+ createCheckout,
+ fireCampaignDevice,
+ getCampaignDevice,
+ listCampaignSubscriptions,
+ renewCampaignSubscription,
+ type CampaignSubscription,
+ type CheckoutInput,
+} from '../lib/autonomousBff.js'
+import { pub, publishDeviceMachineListChanged, publishDown } from '../lib/bus.js'
+import { REMOTE_BILLING_SUSPENDED_FRAME, subscriptionMatches } from '../lib/billingState.js'
+import { dailyTokenLimitForPlan } from '../lib/billingPlanMetadata.js'
+import { encryptMachineCredential } from '../lib/machineCredential.js'
+import { selectManagerId } from '../lib/managers.js'
+import { machineAlive, prisma } from '../lib/prisma.js'
+import { provisionViaManager } from '../lib/provision.js'
+import { logger } from '../utils/logger.js'
+import { voiceQuotaService } from '../lib/voiceQuota.js'
+import {
+ storedAutonomousEnvironment,
+ type AutonomousEnvironment,
+} from '../lib/autonomousEnvironment.js'
+
+const LOCK_TTL_MS = 90_000
+const LOCK_WAIT_MS = 10_000
+const SUBSCRIPTION_PAID = 2
+const SUBSCRIPTION_CANCELLED = 3
+const SUBSCRIPTION_EXPIRED = 5
+const SUBSCRIPTION_FREE_TRIAL = 6
+
+export type BillingAction = 'subscribe' | 'upgrade' | 'downgrade'
+
+export interface CheckoutView {
+ operationId: string
+ sessionId?: string
+ redirectUrl?: string
+ action: BillingAction
+}
+
+export interface BillingPlanView {
+ id: string
+ name: string
+ priceUsd: number
+ cpus: string
+ memory: string
+ maxAgents: number
+ dailyTokenLimit: number | null
+ dailyVoiceLimitSeconds: number
+ isDefault: boolean
+ eligible: boolean
+ ineligibilityReason?: string
+}
+
+export interface MachineBillingView {
+ billingStatus: 'pending' | 'active' | 'suspended'
+ currentPlan: BillingPlanView | null
+ plans: BillingPlanView[]
+ subscription: {
+ id: string | null
+ status: number | null
+ endAt: Date | null
+ cancelledAt: Date | null
+ }
+ usage: {
+ dailyTokens: number | null
+ dailyVoiceSeconds: number | null
+ voiceResetAt: string | null
+ }
+ freeEligible: boolean
+ stale: boolean
+}
+
+function callbackUrl(
+ origin: string,
+ machineId: string,
+ operationId: string,
+ outcome: 'success' | 'cancelled',
+): string {
+ const configured = env.HARNESS_CHECKOUT_CALLBACK_URL.trim()
+ const url = new URL(configured || '/machine-checkout', origin)
+ url.searchParams.set('machineId', machineId)
+ url.searchParams.set('operationId', operationId)
+ url.searchParams.set('checkout', outcome)
+ return url.toString()
+}
+
+function checkoutInput(
+ email: string,
+ plan: SubscriptionPlan,
+ binding: Machine,
+ origin: string,
+ operationId: string,
+): CheckoutInput {
+ if (!plan.externalPlanId || !binding.externalDeviceId) {
+ throw new AppError('Machine checkout is not initialized', 409, 'CHECKOUT_NOT_READY')
+ }
+ return {
+ email,
+ planId: plan.externalPlanId,
+ referenceId: binding.externalDeviceId,
+ successUrl: callbackUrl(origin, binding.machineId, operationId, 'success'),
+ failureUrl: callbackUrl(origin, binding.machineId, operationId, 'cancelled'),
+ origin,
+ }
+}
+
+function requireSecurePlanChangeCallback(successUrl: string): void {
+ if (new URL(successUrl).protocol === 'https:') return
+ throw new AppError(
+ 'Plan changes require an HTTPS checkout callback. Configure HARNESS_CHECKOUT_CALLBACK_URL with an HTTPS URL.',
+ 503,
+ 'CHECKOUT_CALLBACK_HTTPS_REQUIRED',
+ )
+}
+
+export async function withMachineBillingLock<T>(machineId: string, action: () => Promise<T>): Promise<T> {
+ const key = `machine-billing-lock:${machineId}`
+ const token = randomUUID()
+ const deadline = Date.now() + LOCK_WAIT_MS
+ let acquired = false
+ while (!acquired && Date.now() < deadline) {
+ acquired = (await pub.set(key, token, 'PX', LOCK_TTL_MS, 'NX')) === 'OK'
+ if (!acquired) await new Promise((resolve) => setTimeout(resolve, 100))
+ }
+ if (!acquired) throw new AppError('Another billing operation is in progress', 409, 'BILLING_OPERATION_IN_PROGRESS')
+ try {
+ return await action()
+ } finally {
+ await pub.eval(
+ "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
+ 1,
+ key,
+ token,
+ ).catch(() => { /* TTL is the fallback */ })
+ }
+}
+
+export const BILLING_EXPIRY_GRACE_MS = 60 * 60 * 1000
+
+function bindingEnvironment(binding: Machine): AutonomousEnvironment {
+ return storedAutonomousEnvironment(binding.autonomousEnv)
+}
+
+/**
+ * Which machine modes carry a subscription.
+ *
+ * This used to be spelled out as `authMode === 'managed' || authMode === 'remote'` at a dozen sites,
+ * and several places collapsed the world to those two with a ternary. Adding `provider` as a third
+ * billed mode meant touching every one of them, so the predicate lives here now — a fourth billed
+ * mode should be one edit, not twelve.
+ */
+const BILLED_MODES: ReadonlySet<string> = new Set(['managed', 'remote', 'provider'])
+const isBilled = (v: string | null | undefined): boolean => BILLED_MODES.has(v ?? '')
+/** Billed modes with no container of ours: no manager reservation, no campaign device record. */
+const NODELESS_BILLED: ReadonlySet<string> = new Set(['remote', 'provider'])
+const isNodelessBilled = (v: string | null | undefined): boolean => NODELESS_BILLED.has(v ?? '')
+
+/** The plan-catalog bucket a binding shops in. Managed and the nodeless modes have separate tiers. */
+function planAuthMode(binding: { authMode?: string | null }): string {
+ return isNodelessBilled(binding.authMode) ? binding.authMode! : 'managed'
+}
+
+function isCampaignPlan(
+ plan: SubscriptionPlan | null | undefined,
+ autonomousEnv?: AutonomousEnvironment,
+): plan is SubscriptionPlan {
+ return !!plan?.externalPlanId &&
+ isBilled(plan.authMode) &&
+ plan.campaignCode === env.HARNESS_CAMPAIGN_CODE &&
+ (!autonomousEnv || storedAutonomousEnvironment(plan.autonomousEnv) === autonomousEnv)
+}
+
+function isFreePlan(plan: SubscriptionPlan | null | undefined): boolean {
+ return isCampaignPlan(plan) && plan.authMode === 'managed' && plan.priceUsd === 0
+}
+
+/** The provider refused the call itself (rejected body / malformed payload) rather than the network
+ * or our own logic failing. Only this shape is ever tolerated during a delete. */
+function isUpstreamRejection(err: unknown): err is AppError {
+ return err instanceof AppError && err.code === 'BILLING_UPSTREAM_ERROR'
+}
+
+function isEntitled(subscription: CampaignSubscription | undefined): boolean {
+ return !!subscription && (
+ subscription.status === undefined ||
+ subscription.status === SUBSCRIPTION_PAID ||
+ subscription.status === SUBSCRIPTION_FREE_TRIAL
+ )
+}
+
+function subscriptionFor(
+ subscriptions: CampaignSubscription[],
+ binding: Machine,
+ externalPlanId?: number,
+): CampaignSubscription | undefined {
+ const exact = subscriptions.filter((subscription) =>
+ subscription.campaignCode === env.HARNESS_CAMPAIGN_CODE &&
+ subscription.referenceId === binding.externalDeviceId &&
+ (externalPlanId === undefined || subscription.planId === externalPlanId))
+ return exact.sort((a, b) => {
+ const priority = (status?: number) => status === SUBSCRIPTION_PAID || status === SUBSCRIPTION_FREE_TRIAL
+ ? 3
+ : status === SUBSCRIPTION_CANCELLED
+ ? 2
+ : status === SUBSCRIPTION_EXPIRED
+ ? 1
+ : 0
+ return priority(b.status) - priority(a.status) || (b.endAt?.getTime() ?? 0) - (a.endAt?.getTime() ?? 0)
+ })[0]
+}
+
+async function ownedBinding(
+ machineId: string,
+ userId: string,
+ requestedEnvironment?: AutonomousEnvironment,
+): Promise<Machine> {
+ const binding = await prisma.machine.findUnique({ where: { machineId } })
+ if (!binding || binding.deletedAt) throw new NotFoundError('Machine')
+ if (binding.userId !== userId) throw new ForbiddenError('Not your machine')
+ if (requestedEnvironment && bindingEnvironment(binding) !== requestedEnvironment) {
+ throw new AppError('Machine belongs to another Autonomous environment', 403, 'MACHINE_ENV_MISMATCH')
+ }
+ return binding
+}
+
+/** The plan row is LOCAL catalog data — it disappears when the catalog is re-synced, the campaign
+ * code changes, or a tier is retired. Callers that need the plan to price an operation must fail
+ * (`planForBinding`); deletion must not, or a de-catalogued plan traps the owner in a machine they
+ * can never remove. */
+async function planOrNull(binding: Machine): Promise<SubscriptionPlan | null> {
+ const plan = binding.planId ? await prisma.subscriptionPlan.findUnique({ where: { id: binding.planId } }) : null
+ return isCampaignPlan(plan, bindingEnvironment(binding)) ? plan : null
+}
+
+async function planForBinding(binding: Machine): Promise<SubscriptionPlan> {
+ const plan = await planOrNull(binding)
+ if (!plan) throw new AppError('Machine plan is no longer available', 409, 'PLAN_UNAVAILABLE')
+ return plan
+}
+
+async function ownedPending(
+ machineId: string,
+ userId: string,
+ requestedEnvironment?: AutonomousEnvironment,
+): Promise<{ binding: Machine; plan: SubscriptionPlan }> {
+ const binding = await ownedBinding(machineId, userId, requestedEnvironment)
+ if (binding.billingStatus === 'active') throw new AppError('Machine is already active', 409, 'MACHINE_ALREADY_ACTIVE')
+ if (binding.billingStatus === 'suspended') throw new AppError('Machine subscription is suspended', 409, 'MACHINE_SUBSCRIPTION_REQUIRED')
+ if (binding.billingStatus !== 'pending') throw new AppError('Machine does not require checkout', 400, 'CHECKOUT_NOT_REQUIRED')
+ return { binding, plan: await planForBinding(binding) }
+}
+
+async function reservationManager(binding: Machine): Promise<string> {
+ if (binding.managerId) {
+ const manager = await prisma.manager.findUnique({ where: { managerId: binding.managerId } })
+ if (manager?.lastSeenAt && manager.lastSeenAt.getTime() >= Date.now() - 90_000) return manager.managerId
+ }
+ const picked = await selectManagerId()
+ await prisma.machine.update({ where: { machineId: binding.machineId }, data: { managerId: picked.managerId } })
+ return picked.managerId
+}
+
+function provisionActivatedMachine(binding: Machine, managerId: string, wake: boolean): void {
+ const cmd = wake ? 'start' : 'create'
+ const payload = wake
+ ? { machineId: binding.machineId }
+ : { userId: binding.userId, workspaceId: binding.workspaceId ?? undefined, apiKey: binding.apiKey }
+ void provisionViaManager(managerId, cmd, payload).then(() => {
+ logger.info(wake ? 'resubscribed machine started' : 'managed machine provisioned', { machineId: binding.machineId, managerId })
+ }).catch((err) => {
+ logger.error('activated machine provision failed; manager reconcile owns healing', err instanceof Error ? err : new Error(String(err)), {
+ machineId: binding.machineId,
+ managerId,
+ wake,
+ })
+ })
+}
+
+function actionFor(current: SubscriptionPlan, target: SubscriptionPlan, suspended: boolean): BillingAction {
+ if (suspended || current.priceUsd === 0) return 'subscribe'
+ return target.priceUsd > current.priceUsd ? 'upgrade' : 'downgrade'
+}
+
+async function freeEligible(
+ userId: string,
+ autonomousEnv: AutonomousEnvironment,
+ machineId?: string,
+): Promise<boolean> {
+ const entitlement = await prisma.machineFreeEntitlement.findUnique({
+ where: { userId_autonomousEnv: { userId, autonomousEnv } },
+ })
+ return !entitlement || (entitlement.status === 'reserved' && entitlement.machineId === machineId)
+}
+
+async function plansView(
+ userId: string,
+ autonomousEnv: AutonomousEnvironment,
+ authMode: string,
+ machineId?: string,
+): Promise<BillingPlanView[]> {
+ const [plans, eligible] = await Promise.all([
+ prisma.subscriptionPlan.findMany({
+ where: { autonomousEnv, available: true, authMode, campaignCode: env.HARNESS_CAMPAIGN_CODE },
+ orderBy: { priceUsd: 'asc' },
+ }),
+ authMode === 'managed' ? freeEligible(userId, autonomousEnv, machineId) : Promise.resolve(false),
+ ])
+ return plans.map((plan) => ({
+ id: plan.id,
+ name: plan.name,
+ priceUsd: plan.priceUsd,
+ cpus: plan.cpus,
+ memory: plan.memory,
+ maxAgents: plan.maxAgents,
+ dailyTokenLimit: dailyTokenLimitForPlan(plan),
+ dailyVoiceLimitSeconds: Math.max(0, plan.dailyVoiceLimitSeconds ?? 0),
+ isDefault: plan.isDefault,
+ eligible: plan.priceUsd > 0 || eligible,
+ ...(plan.priceUsd === 0 && !eligible ? { ineligibilityReason: 'Free plan already used' } : {}),
+ }))
+}
+
+async function buildBillingView(
+ binding: Machine,
+ stale: boolean,
+ dailyTokens: number | null = null,
+ dailyVoiceSeconds: number | null = null,
+ voiceResetAt: string | null = null,
+): Promise<MachineBillingView> {
+ const autonomousEnv = bindingEnvironment(binding)
+ const authMode = planAuthMode(binding)
+ const [plan, plans, eligible] = await Promise.all([
+ binding.planId ? prisma.subscriptionPlan.findUnique({ where: { id: binding.planId } }) : null,
+ plansView(binding.userId, autonomousEnv, authMode, binding.machineId),
+ authMode === 'managed' ? freeEligible(binding.userId, autonomousEnv, binding.machineId) : Promise.resolve(false),
+ ])
+ const currentPlan = plan
+ ? {
+ id: plan.id,
+ name: plan.name,
+ priceUsd: plan.priceUsd,
+ cpus: plan.cpus,
+ memory: plan.memory,
+ maxAgents: plan.maxAgents,
+ dailyTokenLimit: dailyTokenLimitForPlan(plan),
+ dailyVoiceLimitSeconds: Math.max(0, plan.dailyVoiceLimitSeconds ?? 0),
+ isDefault: plan.isDefault,
+ eligible: true,
+ }
+ : null
+ return {
+ billingStatus: binding.billingStatus === 'pending' || binding.billingStatus === 'suspended'
+ ? binding.billingStatus
+ : 'active',
+ currentPlan,
+ plans,
+ subscription: {
+ id: binding.externalSubscriptionId ?? null,
+ status: binding.externalSubscriptionStatus ?? null,
+ endAt: binding.externalSubscriptionEndAt ?? null,
+ cancelledAt: binding.externalSubscriptionCancelledAt ?? null,
+ },
+ usage: { dailyTokens, dailyVoiceSeconds, voiceResetAt },
+ freeEligible: eligible,
+ stale,
+ }
+}
+
+async function startCheckoutOperation(
+ binding: Machine,
+ currentPlan: SubscriptionPlan,
+ targetPlan: SubscriptionPlan,
+ action: BillingAction,
+ userId: string,
+ email: string,
+ token: string,
+ origin: string,
+): Promise<CheckoutView> {
+ // A checkout URL is disposable UI state, not a lock on the machine. Every explicit user action
+ // gets a fresh provider session; older tabs/callbacks are superseded and cannot mutate billing.
+ await prisma.machineCheckoutAttempt.updateMany({
+ where: { machineId: binding.machineId, status: { in: ['creating', 'pending'] } },
+ data: { status: 'cancelled', error: 'Superseded by a newer checkout' },
+ })
+
+ const operationId = randomUUID()
+ const input = checkoutInput(email, targetPlan, binding, origin, operationId)
+ // The campaign provider accepts localhost for an initial subscription, but Stripe-hosted plan
+ // changes reject an HTTP success_url with a generic status:-1 response. Fail locally with an
+ // actionable configuration error instead. Local E2E testing should use an HTTPS tunnel.
+ if (binding.billingStatus !== 'pending') requireSecurePlanChangeCallback(input.successUrl)
+ const attempt = await prisma.machineCheckoutAttempt.create({
+ data: {
+ machineId: binding.machineId,
+ userId,
+ autonomousEnv: bindingEnvironment(binding),
+ externalPlanId: targetPlan.externalPlanId!,
+ externalDeviceId: binding.externalDeviceId!,
+ // Preserve the legacy required/unique column. New callbacks use operationId; providerSessionId
+ // stores the real Stripe/BFF session when one exists.
+ sessionId: operationId,
+ operationId,
+ operationType: binding.billingStatus === 'pending' ? 'subscribe' : 'plan_change',
+ sourcePlanId: currentPlan.id,
+ targetPlanId: targetPlan.id,
+ checkoutEmail: input.email,
+ successUrl: input.successUrl,
+ failureUrl: input.failureUrl,
+ webOrigin: input.origin,
+ status: 'creating',
+ },
+ })
+ try {
+ const checkout = await createCheckout(bindingEnvironment(binding), token, input)
+ if (isFreePlan(targetPlan) && !checkout.redirectUrl) {
+ throw new AppError(
+ 'Autonomous billing service did not return a Free card setup URL',
+ 503,
+ 'BILLING_UPSTREAM_ERROR',
+ )
+ }
+ await prisma.machineCheckoutAttempt.update({
+ where: { id: attempt.id },
+ data: {
+ providerSessionId: checkout.sessionId ?? null,
+ redirectUrl: checkout.redirectUrl ?? null,
+ status: 'pending',
+ },
+ })
+ return { operationId, ...checkout, action }
+ } catch (err) {
+ await prisma.machineCheckoutAttempt.update({
+ where: { id: attempt.id },
+ data: { status: 'failed', error: err instanceof Error ? err.message.slice(0, 500) : String(err).slice(0, 500) },
+ }).catch(() => {})
+ throw err
+ }
+}
+
+function sameDate(left: Date | null, right: Date | null): boolean {
+ return left?.getTime() === right?.getTime()
+}
+
+async function syncFromSubscription(
+ binding: Machine,
+ subscription: CampaignSubscription,
+): Promise<{ binding: Machine; changed: boolean }> {
+ const plan = subscription.planId
+ ? await prisma.subscriptionPlan.findFirst({
+ where: {
+ externalPlanId: subscription.planId,
+ campaignCode: env.HARNESS_CAMPAIGN_CODE,
+ authMode: planAuthMode(binding),
+ autonomousEnv: bindingEnvironment(binding),
+ },
+ })
+ : null
+ // Persist the provider truth, but leave the active -> suspended transition to the singleton
+ // billing worker. That transition also stops the runtime and must not be performed partially by
+ // an arbitrary clustered HTTP process serving GET /billing.
+ const shouldAdoptPlan = !!plan && subscription.status !== SUBSCRIPTION_EXPIRED
+ const nextPlanId = shouldAdoptPlan ? plan.id : binding.planId
+ const nextSubscriptionId = subscription.id ?? binding.externalSubscriptionId
+ const nextStatus = subscription.status ?? binding.externalSubscriptionStatus
+ const nextEndAt = subscription.endAt ?? binding.externalSubscriptionEndAt
+ const nextCancelledAt = nextStatus === SUBSCRIPTION_PAID || nextStatus === SUBSCRIPTION_FREE_TRIAL
+ ? null
+ : subscription.cancelledAt ?? binding.externalSubscriptionCancelledAt
+ const changed = nextPlanId !== binding.planId ||
+ nextSubscriptionId !== binding.externalSubscriptionId ||
+ nextStatus !== binding.externalSubscriptionStatus ||
+ !sameDate(nextEndAt, binding.externalSubscriptionEndAt) ||
+ !sameDate(nextCancelledAt, binding.externalSubscriptionCancelledAt)
+ if (!changed) return { binding, changed: false }
+ if (subscription.planId && !plan) {
+ logger.warn('campaign subscription plan unavailable; keeping current machine plan', {
+ machineId: binding.machineId,
+ autonomousEnv: bindingEnvironment(binding),
+ externalPlanId: subscription.planId,
+ })
+ }
+ const updated = await prisma.machine.update({
+ where: { machineId: binding.machineId },
+ data: {
+ ...(nextPlanId !== binding.planId ? { planId: nextPlanId } : {}),
+ ...(nextSubscriptionId !== binding.externalSubscriptionId
+ ? { externalSubscriptionId: nextSubscriptionId }
+ : {}),
+ ...(nextStatus !== binding.externalSubscriptionStatus ? { externalSubscriptionStatus: nextStatus } : {}),
+ ...(!sameDate(nextEndAt, binding.externalSubscriptionEndAt) ? { externalSubscriptionEndAt: nextEndAt } : {}),
+ ...(!sameDate(nextCancelledAt, binding.externalSubscriptionCancelledAt)
+ ? { externalSubscriptionCancelledAt: nextCancelledAt }
+ : {}),
+ },
+ })
+ return { binding: updated, changed: true }
+}
+
+async function syncSubscription(
+ machineId: string,
+ subscription: CampaignSubscription,
+ expectedSubscriptionId?: string,
+): Promise<{ binding: Machine; changed: boolean } | null> {
+ return withMachineBillingLock(machineId, async () => {
+ const binding = await prisma.machine.findUnique({ where: { machineId } })
+ const billedMachine = isBilled(binding?.authMode)
+ if (!binding || binding.deletedAt || !billedMachine) return null
+ // A checkout may replace the subscription between the worker's candidate scan and this lock.
+ // Never let an older campaign snapshot overwrite the newer subscription in that race.
+ if (expectedSubscriptionId && binding.externalSubscriptionId !== expectedSubscriptionId) return null
+ const result = await syncFromSubscription(binding, subscription)
+ if (result.changed) {
+ await publishDeviceMachineListChanged(binding.userId, { reason: 'updated' }).catch(() => {})
+ }
+ return result
+ })
+}
+
+export const machineBillingService = {
+ isFreePlan,
+ syncSubscription,
+
+ async reserveFreeEntitlement(userId: string, machineId: string, plan: SubscriptionPlan): Promise<void> {
+ if (!isFreePlan(plan)) return
+ const autonomousEnv = storedAutonomousEnvironment(plan.autonomousEnv)
+ try {
+ await prisma.machineFreeEntitlement.create({ data: { userId, autonomousEnv, machineId, status: 'reserved' } })
+ } catch {
+ const existing = await prisma.machineFreeEntitlement.findUnique({
+ where: { userId_autonomousEnv: { userId, autonomousEnv } },
+ })
+ if (existing?.status === 'reserved' && existing.machineId === machineId) return
+ throw new AppError('Free plan has already been used for this account', 409, 'FREE_PLAN_ALREADY_USED')
+ }
+ },
+
+ async releaseFreeReservation(userId: string, machineId: string): Promise<void> {
+ await prisma.machineFreeEntitlement.deleteMany({ where: { userId, machineId, status: 'reserved' } })
+ },
+
+ async freeEligibility(
+ userId: string,
+ autonomousEnv: AutonomousEnvironment,
+ ): Promise<{ eligible: boolean; reason?: string }> {
+ const eligible = await freeEligible(userId, autonomousEnv)
+ return { eligible, ...(!eligible ? { reason: 'Free plan already used' } : {}) }
+ },
+
+ async beginCheckout(
+ machineId: string,
+ userId: string,
+ email: string,
+ token: string,
+ origin: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<CheckoutView> {
+ return withMachineBillingLock(machineId, async () => {
+ let { binding, plan } = await ownedPending(machineId, userId, requestedEnvironment)
+ try {
+ if (!binding.externalDeviceId) {
+ const externalDeviceId = await createCampaignDevice(bindingEnvironment(binding), token)
+ binding = await prisma.machine.update({
+ where: { machineId },
+ data: { externalDeviceId, billingError: null, billingErrorAt: null },
+ })
+ }
+ return await startCheckoutOperation(binding, plan, plan, 'subscribe', userId, email, token, origin)
+ } catch (err) {
+ await prisma.machine.updateMany({
+ where: { machineId, billingStatus: 'pending' },
+ data: { billingError: err instanceof Error ? err.message.slice(0, 500) : 'Checkout failed', billingErrorAt: new Date() },
+ }).catch(() => {})
+ throw err
+ }
+ })
+ },
+
+ async beginPlanCheckout(
+ machineId: string,
+ userId: string,
+ targetPlanId: string,
+ email: string,
+ token: string,
+ origin: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<CheckoutView> {
+ return withMachineBillingLock(machineId, async () => {
+ const binding = await ownedBinding(machineId, userId, requestedEnvironment)
+ if (binding.billingStatus !== 'active' && binding.billingStatus !== 'suspended') {
+ throw new AppError('Machine setup must be completed first', 409, 'MACHINE_PAYMENT_PENDING')
+ }
+ if (!isBilled(binding.authMode) || !binding.externalDeviceId) {
+ throw new AppError('This machine does not use campaign billing', 400, 'BILLING_NOT_APPLICABLE')
+ }
+ const [currentPlan, targetPlan] = await Promise.all([
+ planForBinding(binding),
+ prisma.subscriptionPlan.findUnique({ where: { id: targetPlanId } }),
+ ])
+ if (binding.authMode === 'remote' && binding.billingStatus === 'active') {
+ throw new AppError('Remote machines cannot change plans', 409, 'REMOTE_PLAN_CHANGE_NOT_ALLOWED')
+ }
+ if (binding.authMode === 'remote' && targetPlanId !== currentPlan.id) {
+ throw new AppError('Remote machines can only re-subscribe to their current plan', 409, 'REMOTE_PLAN_CHANGE_NOT_ALLOWED')
+ }
+ if (binding.externalSubscriptionStatus === SUBSCRIPTION_CANCELLED &&
+ (!binding.externalSubscriptionEndAt || binding.externalSubscriptionEndAt.getTime() > Date.now())) {
+ throw new AppError('Renew the cancelled subscription before changing plan', 409, 'SUBSCRIPTION_CANCELLED')
+ }
+ if (!isCampaignPlan(targetPlan, bindingEnvironment(binding)) || targetPlan.available !== true ||
+ targetPlan.authMode !== binding.authMode) {
+ throw new AppError('Target plan is unavailable', 409, 'PLAN_UNAVAILABLE')
+ }
+ if (targetPlan.priceUsd === 0) {
+ throw new AppError('Paid machines cannot downgrade to Free', 409, 'FREE_DOWNGRADE_NOT_ALLOWED')
+ }
+ if (binding.billingStatus === 'active' && currentPlan.id === targetPlan.id) {
+ throw new AppError('Machine is already on this plan', 409, 'PLAN_ALREADY_ACTIVE')
+ }
+ const action = actionFor(currentPlan, targetPlan, binding.billingStatus === 'suspended')
+ return startCheckoutOperation(binding, currentPlan, targetPlan, action, userId, email, token, origin)
+ })
+ },
+
+ async complete(
+ machineId: string,
+ userId: string,
+ token: string,
+ operationId: string,
+ outcome: 'success' | 'cancelled',
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<MachineBillingView> {
+ return withMachineBillingLock(machineId, async () => {
+ let binding = await ownedBinding(machineId, userId, requestedEnvironment)
+ // operationId is the new stable callback key. Fall back to the legacy/provider session
+ // columns so checkout URLs created before this rollout can still be completed safely.
+ const attempt = await prisma.machineCheckoutAttempt.findFirst({
+ where: {
+ OR: [
+ { operationId },
+ { sessionId: operationId },
+ { providerSessionId: operationId },
+ ],
+ },
+ orderBy: { createdAt: 'desc' },
+ })
+ if (!attempt || attempt.machineId !== machineId || attempt.userId !== userId) {
+ throw new AppError('Billing operation not found', 404, 'CHECKOUT_NOT_FOUND')
+ }
+ if (storedAutonomousEnvironment(attempt.autonomousEnv) !== bindingEnvironment(binding)) {
+ throw new AppError('Billing operation belongs to another Autonomous environment', 409, 'BILLING_ENV_MISMATCH')
+ }
+ if (outcome === 'cancelled') {
+ if (attempt.status !== 'completed') {
+ await prisma.machineCheckoutAttempt.update({ where: { id: attempt.id }, data: { status: 'cancelled' } })
+ }
+ return buildBillingView(binding, false)
+ }
+ if (attempt.status === 'completed') return buildBillingView(binding, false)
+ if (attempt.status === 'cancelled' || attempt.status === 'failed') {
+ throw new AppError('This checkout was replaced by a newer one', 409, 'CHECKOUT_SUPERSEDED')
+ }
+ const targetPlanId = attempt.targetPlanId ?? binding.planId
+ if (!targetPlanId) throw new AppError('Billing operation is incomplete', 409, 'CHECKOUT_NOT_READY')
+ const targetPlan = await prisma.subscriptionPlan.findUnique({ where: { id: targetPlanId } })
+ // The checkout attempt's externalPlanId is immutable. Catalog sync may update the local plan
+ // row while the user is on Stripe; completion must still verify the plan that was purchased.
+ if (!isCampaignPlan(targetPlan, bindingEnvironment(binding))) {
+ throw new AppError('Billing operation target is unavailable', 409, 'PLAN_UNAVAILABLE')
+ }
+ if (targetPlan.authMode !== binding.authMode) {
+ throw new AppError('Billing operation cannot change machine runtime type', 409, 'BILLING_OPERATION_STALE')
+ }
+ if (attempt.operationType === 'plan_change' && attempt.sourcePlanId &&
+ binding.planId !== attempt.sourcePlanId && binding.planId !== targetPlanId) {
+ throw new AppError('Billing operation is stale', 409, 'BILLING_OPERATION_STALE')
+ }
+
+ const autonomousEnv = bindingEnvironment(binding)
+ const device = await getCampaignDevice(autonomousEnv, token, binding.externalDeviceId!)
+ const expected = {
+ campaignCode: env.HARNESS_CAMPAIGN_CODE,
+ referenceId: binding.externalDeviceId!,
+ planId: attempt.externalPlanId,
+ }
+ let subscription = subscriptionMatches(device.subscription, expected) ? device.subscription : undefined
+ if (!subscription || !isEntitled(subscription)) {
+ const subscriptions = await listCampaignSubscriptions(autonomousEnv, token, env.HARNESS_CAMPAIGN_CODE, binding.externalDeviceId!)
+ subscription = subscriptionFor(subscriptions, binding, attempt.externalPlanId)
+ }
+ if (!subscription || !subscriptionMatches(subscription, expected) || !isEntitled(subscription)) {
+ throw new AppError('Payment is not active for this machine and plan', 409, 'PAYMENT_NOT_VERIFIED')
+ }
+ if (targetPlan.authMode === 'managed' && !device.llmApiKey) {
+ throw new AppError('Campaign credential is not ready yet', 409, 'CAMPAIGN_CREDENTIAL_NOT_READY')
+ }
+
+ if (isFreePlan(targetPlan)) {
+ const entitlement = await prisma.machineFreeEntitlement.findUnique({
+ where: { userId_autonomousEnv: { userId, autonomousEnv } },
+ })
+ if (entitlement && entitlement.machineId !== machineId) {
+ throw new AppError('Free plan has already been used for this account', 409, 'FREE_PLAN_ALREADY_USED')
+ }
+ if (entitlement) {
+ await prisma.machineFreeEntitlement.update({
+ where: { userId_autonomousEnv: { userId, autonomousEnv } },
+ data: { status: 'claimed', claimedAt: entitlement.claimedAt ?? new Date() },
+ })
+ } else {
+ await prisma.machineFreeEntitlement.create({
+ data: { userId, autonomousEnv, machineId, status: 'claimed', claimedAt: new Date() },
+ })
+ }
+ }
+
+ const wasPending = binding.billingStatus === 'pending'
+ const wasSuspended = binding.billingStatus === 'suspended'
+ const remote = isNodelessBilled(targetPlan.authMode)
+ const managerId = remote ? '' : wasPending ? await reservationManager(binding) : binding.managerId
+ binding = await prisma.machine.update({
+ where: { machineId },
+ data: {
+ managerId,
+ planId: targetPlan.id,
+ billingStatus: 'active',
+ externalSubscriptionId: subscription.id ?? binding.externalSubscriptionId,
+ externalSubscriptionStatus: subscription.status ?? SUBSCRIPTION_PAID,
+ externalSubscriptionEndAt: subscription.endAt ?? null,
+ externalSubscriptionCancelledAt: null,
+ billingActivatedAt: binding.billingActivatedAt ?? new Date(),
+ billingError: null,
+ billingErrorAt: null,
+ llmApiKeyEncrypted: remote ? null : encryptMachineCredential(device.llmApiKey!),
+ },
+ })
+ await prisma.machineCheckoutAttempt.update({
+ where: { id: attempt.id },
+ data: { status: 'completed', completedAt: new Date(), error: null },
+ })
+ await publishDeviceMachineListChanged(userId, { reason: wasPending ? 'created' : 'updated' }).catch(() => {})
+ if (!remote && (wasPending || wasSuspended)) provisionActivatedMachine(binding, managerId, wasSuspended)
+ return buildBillingView(binding, false)
+ })
+ },
+
+ /** Backward-compatible activation for checkout URLs created before operationId was introduced. */
+ async activate(
+ machineId: string,
+ userId: string,
+ _email: string,
+ token: string,
+ _origin: string,
+ sessionId?: string,
+ _referenceCode?: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<void> {
+ const attempt = sessionId
+ ? await prisma.machineCheckoutAttempt.findFirst({
+ where: { OR: [{ operationId: sessionId }, { providerSessionId: sessionId }, { sessionId }] },
+ orderBy: { createdAt: 'desc' },
+ })
+ : await prisma.machineCheckoutAttempt.findFirst({ where: { machineId }, orderBy: { createdAt: 'desc' } })
+ if (!attempt) throw new AppError('Checkout session not found', 404, 'CHECKOUT_NOT_FOUND')
+ const operationId = attempt.operationId ?? attempt.sessionId
+ await this.complete(machineId, userId, token, operationId, 'success', requestedEnvironment)
+ },
+
+ async getBilling(
+ machineId: string,
+ userId: string,
+ token: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<MachineBillingView> {
+ let binding = await ownedBinding(machineId, userId, requestedEnvironment)
+ if (!isBilled(binding.authMode) || !binding.externalDeviceId) {
+ throw new AppError('This machine does not use campaign billing', 400, 'BILLING_NOT_APPLICABLE')
+ }
+ await planForBinding(binding)
+ const autonomousEnv = bindingEnvironment(binding)
+ const [subscriptionsResult, usageResult, voiceUsageResult] = await Promise.allSettled([
+ listCampaignSubscriptions(autonomousEnv, token, env.HARNESS_CAMPAIGN_CODE, binding.externalDeviceId),
+ binding.authMode === 'managed'
+ ? getCampaignDevice(autonomousEnv, token, binding.externalDeviceId)
+ : Promise.resolve(null),
+ voiceQuotaService.snapshotForMachine(binding.machineId),
+ ])
+
+ let stale = false
+ if (subscriptionsResult.status === 'fulfilled') {
+ try {
+ const subscription = subscriptionFor(subscriptionsResult.value, binding)
+ if (subscription) {
+ const synced = await syncSubscription(machineId, subscription)
+ if (synced) binding = synced.binding
+ }
+ } catch (err) {
+ stale = true
+ logger.warn('machine billing refresh failed; returning cached metadata', {
+ machineId,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ }
+ } else {
+ if (subscriptionsResult.reason instanceof AppError && subscriptionsResult.reason.code === 'UNAUTHORIZED') {
+ throw subscriptionsResult.reason
+ }
+ stale = true
+ logger.warn('machine billing refresh failed; returning cached metadata', {
+ machineId,
+ error: subscriptionsResult.reason instanceof Error
+ ? subscriptionsResult.reason.message
+ : String(subscriptionsResult.reason),
+ })
+ }
+
+ let dailyTokens: number | null = null
+ if (usageResult.status === 'fulfilled') {
+ if (usageResult.value) dailyTokens = Math.floor(usageResult.value.dailyUsage ?? 0)
+ } else {
+ if (usageResult.reason instanceof AppError && usageResult.reason.code === 'UNAUTHORIZED') throw usageResult.reason
+ logger.warn('machine daily token usage unavailable', {
+ machineId,
+ error: usageResult.reason instanceof Error ? usageResult.reason.message : String(usageResult.reason),
+ })
+ }
+ let dailyVoiceSeconds: number | null = null
+ let voiceResetAt: string | null = null
+ if (voiceUsageResult.status === 'fulfilled') {
+ dailyVoiceSeconds = voiceUsageResult.value.usedSeconds
+ voiceResetAt = voiceUsageResult.value.resetAt
+ } else {
+ logger.warn('machine daily voice usage unavailable', {
+ machineId,
+ error: voiceUsageResult.reason instanceof Error
+ ? voiceUsageResult.reason.message
+ : String(voiceUsageResult.reason),
+ })
+ }
+ return buildBillingView(binding, stale, dailyTokens, dailyVoiceSeconds, voiceResetAt)
+ },
+
+ async cancel(
+ machineId: string,
+ userId: string,
+ token: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<MachineBillingView> {
+ return withMachineBillingLock(machineId, async () => {
+ let binding = await ownedBinding(machineId, userId, requestedEnvironment)
+ if (binding.billingStatus !== 'active') throw new AppError('Machine subscription is not active', 409, 'SUBSCRIPTION_NOT_ACTIVE')
+ const plan = await planForBinding(binding)
+ if (plan.priceUsd <= 0) throw new AppError('Free plan cannot be cancelled', 409, 'FREE_PLAN_NOT_CANCELLABLE')
+ const autonomousEnv = bindingEnvironment(binding)
+ const subscriptions = await listCampaignSubscriptions(autonomousEnv, token, env.HARNESS_CAMPAIGN_CODE, binding.externalDeviceId!)
+ const subscription = subscriptionFor(subscriptions, binding, plan.externalPlanId!)
+ if (!subscription?.id) throw new AppError('Subscription was not found', 409, 'SUBSCRIPTION_NOT_FOUND')
+ if (!subscription.endAt) throw new AppError('Subscription period end is unavailable', 409, 'BILLING_PERIOD_UNKNOWN')
+ if (subscription.status !== SUBSCRIPTION_CANCELLED) {
+ await cancelCampaignSubscription(autonomousEnv, token, subscription.id)
+ }
+ binding = await prisma.machine.update({
+ where: { machineId },
+ data: {
+ externalSubscriptionId: subscription.id,
+ externalSubscriptionStatus: SUBSCRIPTION_CANCELLED,
+ externalSubscriptionEndAt: subscription.endAt,
+ externalSubscriptionCancelledAt: subscription.cancelledAt ?? new Date(),
+ },
+ })
+ await publishDeviceMachineListChanged(userId, { reason: 'updated' }).catch(() => {})
+ return buildBillingView(binding, false)
+ })
+ },
+
+ async renew(
+ machineId: string,
+ userId: string,
+ token: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<MachineBillingView> {
+ return withMachineBillingLock(machineId, async () => {
+ let binding = await ownedBinding(machineId, userId, requestedEnvironment)
+ if (binding.billingStatus !== 'active' || binding.externalSubscriptionStatus !== SUBSCRIPTION_CANCELLED) {
+ throw new AppError('Subscription is not cancelled', 409, 'SUBSCRIPTION_NOT_CANCELLED')
+ }
+ if (!binding.externalSubscriptionEndAt || binding.externalSubscriptionEndAt.getTime() <= Date.now()) {
+ throw new AppError('Subscription has already expired', 409, 'SUBSCRIPTION_EXPIRED')
+ }
+ const autonomousEnv = bindingEnvironment(binding)
+ const subscriptions = await listCampaignSubscriptions(autonomousEnv, token, env.HARNESS_CAMPAIGN_CODE, binding.externalDeviceId!)
+ const subscription = subscriptionFor(subscriptions, binding)
+ if (!subscription?.id || subscription.status !== SUBSCRIPTION_CANCELLED) {
+ throw new AppError('Subscription is not cancelled', 409, 'SUBSCRIPTION_NOT_CANCELLED')
+ }
+ if (!subscription.endAt || subscription.endAt.getTime() <= Date.now()) {
+ throw new AppError('Subscription has already expired', 409, 'SUBSCRIPTION_EXPIRED')
+ }
+ await renewCampaignSubscription(autonomousEnv, token, subscription.id)
+ binding = await prisma.machine.update({
+ where: { machineId },
+ data: {
+ externalSubscriptionStatus: SUBSCRIPTION_PAID,
+ externalSubscriptionEndAt: subscription.endAt,
+ externalSubscriptionCancelledAt: null,
+ },
+ })
+ await publishDeviceMachineListChanged(userId, { reason: 'updated' }).catch(() => {})
+ return buildBillingView(binding, false)
+ })
+ },
+
+ /** Cancel every renewable upstream billing resource before hiding the machine locally. The local
+ * soft delete is intentionally last: an upstream error leaves the machine visible and retryable. */
+ async deleteCampaignMachine(
+ machineId: string,
+ userId: string,
+ token: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<void> {
+ return withMachineBillingLock(machineId, async () => {
+ const binding = await ownedBinding(machineId, userId, requestedEnvironment)
+ if (!isBilled(binding.authMode)) {
+ throw new AppError('This machine does not use campaign billing', 400, 'BILLING_NOT_APPLICABLE')
+ }
+ // Deletion never requires a resolvable plan: the plan row is local catalog data, while the
+ // thing that actually bills lives upstream. When it is gone we cannot read a price, so we
+ // assume the machine MAY be paid and fall through to provider truth (cancel + fire-intern)
+ // below — strictly more cleanup than a known-free plan gets, and never a refusal.
+ const plan = await planOrNull(binding)
+ const maybePaid = plan ? plan.priceUsd > 0 : true
+
+ // Was this machine ever activated upstream? `complete()` always stamps a subscription status
+ // and `billingActivatedAt`, so the absence of every reference proves no subscription was ever
+ // established for it — nothing can be renewing, whatever the provider says about the device.
+ const everActivated = !!binding.externalSubscriptionId || !!binding.externalSubscriptionStatus ||
+ !!binding.externalSubscriptionEndAt || !!binding.externalSubscriptionCancelledAt ||
+ !!binding.billingActivatedAt
+
+ const missingDeviceIsInconsistent = plan
+ ? plan.priceUsd > 0 && binding.billingStatus !== 'pending'
+ // Unknown plan: only upstream evidence proves a subscription ever existed. Without it there
+ // is provably nothing to cancel, so the local row must not be held hostage to the catalog.
+ : everActivated
+ if (missingDeviceIsInconsistent && !binding.externalDeviceId) {
+ // An activated paid machine without its provider reference is inconsistent. Never hide it:
+ // ops must recover the device/subscription link so renewal can be cancelled authoritatively.
+ throw new AppError(
+ 'Billing device is missing; subscription cancellation cannot be verified',
+ 409,
+ 'BILLING_CLEANUP_REQUIRED',
+ )
+ }
+
+ if (binding.externalDeviceId) {
+ const autonomousEnv = bindingEnvironment(binding)
+ // "We know nothing can renew after this point." Only that justifies hiding the local row
+ // when the provider then refuses to delete its device.
+ let renewalDisabled = !maybePaid || binding.billingStatus === 'pending'
+ if (maybePaid) {
+ // Re-read provider truth instead of trusting cached status: a checkout callback or renew
+ // may have completed in another tab. Explicitly cancel Paid/FreeTrial before fire-intern.
+ let subscriptions: CampaignSubscription[] | undefined
+ try {
+ subscriptions = await listCampaignSubscriptions(autonomousEnv, token, env.HARNESS_CAMPAIGN_CODE, binding.externalDeviceId)
+ } catch (err) {
+ // The provider refuses to even look the device up (unknown/already-removed device,
+ // campaign-code drift). A machine that was never activated has no subscription to
+ // protect, so an unverifiable lookup must not make it permanently undeletable —
+ // fire-intern is still attempted below and would cancel anything that did slip through.
+ if (everActivated || !isUpstreamRejection(err)) throw err
+ logger.warn('campaign subscription lookup rejected for a never-activated machine; continuing delete', {
+ machineId, externalDeviceId: binding.externalDeviceId, autonomousEnv, error: err.message,
+ })
+ }
+ if (subscriptions) {
+ const subscription = subscriptionFor(subscriptions, binding)
+ if (subscription?.id && isEntitled(subscription)) {
+ // A live subscription is PROVEN here, so a failure to cancel it always aborts the
+ // delete — no local state may excuse leaving a renewing charge behind.
+ await cancelCampaignSubscription(autonomousEnv, token, subscription.id)
+ }
+ // Either we just cancelled it, or the provider itself reports no entitled subscription
+ // for this device (none at all, cancelled, or expired). Both are authoritative proof
+ // that nothing renews — including the "no subscription found" case, which used to be
+ // read as "unverified" and left every such machine undeletable on a fire-intern 503.
+ renewalDisabled = true
+ }
+ }
+ // fire-intern is the provider's billing-safe delete. It cancels any remaining subscription
+ // (including a pending/racing one), releases plan allocation, then deletes the device.
+ try {
+ await fireCampaignDevice(autonomousEnv, token, binding.externalDeviceId)
+ } catch (err) {
+ // Some provider deployments reject fire-intern after the explicit cancel because the
+ // subscription is no longer Paid. Once cancellation is confirmed — or the machine was
+ // never activated at all — recurring billing is already disabled: keep the
+ // externalDeviceId on the soft-deleted audit row for later provider cleanup, but do not
+ // trap the user in an undeletable local machine.
+ if (!((renewalDisabled || !everActivated) && isUpstreamRejection(err))) throw err
+ logger.warn('campaign device cleanup rejected; continuing soft delete', {
+ machineId,
+ externalDeviceId: binding.externalDeviceId,
+ autonomousEnv,
+ everActivated,
+ renewalDisabled,
+ error: err.message,
+ })
+ }
+ }
+
+ // Only now is it safe to hide the local machine. If any upstream call above throws, this write
+ // is never reached and the user can retry deletion without losing the subscription record.
+ await prisma.machine.update({ where: { machineId }, data: { deletedAt: new Date() } })
+ await prisma.machineCheckoutAttempt.updateMany({
+ where: { machineId, status: { in: ['creating', 'pending'] } },
+ data: { status: 'cancelled', error: 'Machine deleted by owner' },
+ })
+ // Unconditional: the release is scoped to this machine AND `status: 'reserved'`, so an
+ // activated Free machine (status 'claimed') keeps its lifetime entitlement spent. Not gated on
+ // the plan, or a de-catalogued Free tier would strand the reservation and permanently block
+ // the account's next Free machine.
+ await this.releaseFreeReservation(userId, machineId)
+ await publishDeviceMachineListChanged(userId, { reason: 'deleted' }).catch(() => {})
+ })
+ },
+
+ async suspendIfDue(machineId: string): Promise<boolean> {
+ return withMachineBillingLock(machineId, async () => {
+ const binding = await prisma.machine.findUnique({ where: { machineId } })
+ const overdueCutoff = new Date(Date.now() - BILLING_EXPIRY_GRACE_MS)
+ const endAtOverdue = !!binding?.externalSubscriptionEndAt &&
+ binding.externalSubscriptionEndAt.getTime() <= overdueCutoff.getTime()
+ const providerExpired = binding?.externalSubscriptionStatus === SUBSCRIPTION_EXPIRED
+ const billedMachine = isBilled(binding?.authMode)
+ if (!binding || binding.deletedAt || !billedMachine || binding.billingStatus !== 'active' ||
+ (!endAtOverdue && !providerExpired)) return false
+ const updated = await prisma.machine.updateMany({
+ where: {
+ machineId,
+ billingStatus: 'active',
+ authMode: { in: [...BILLED_MODES] },
+ // AND, not two sibling `OR`s: the alive filter is itself an OR (schema.prisma — a legacy row
+ // LACKS `deletedAt` entirely, and `{deletedAt: null}` does not match absent), and spreading it
+ // beside the overdue OR would have one silently overwrite the other.
+ AND: [
+ machineAlive,
+ {
+ OR: [
+ { externalSubscriptionEndAt: { lte: overdueCutoff } },
+ { externalSubscriptionStatus: SUBSCRIPTION_EXPIRED },
+ ],
+ },
+ ],
+ },
+ data: { billingStatus: 'suspended' },
+ })
+ if (!updated.count) return false
+ await publishDeviceMachineListChanged(binding.userId, { reason: 'updated' }).catch(() => {})
+ if (binding.managerId) {
+ await provisionViaManager(binding.managerId, 'stop', { machineId }).catch((err) => {
+ logger.warn('suspended machine stop failed; manager reconcile will retry', {
+ machineId,
+ managerId: binding.managerId,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ })
+ } else if (isNodelessBilled(binding.authMode)) {
+ // No container to stop. For `remote` this frame closes the adapter's live socket without
+ // revoking its token, so its retry loop then gets HTTP 402 until billing is restored.
+ //
+ // For `provider` there is no socket at all — the link is request-per-turn — so the frame is
+ // simply not delivered anywhere, and enforcement rests entirely on `billingStatus`, which
+ // `providerLink` consults before dialling. Publishing it anyway keeps the two modes on one
+ // path and costs nothing when nobody is subscribed.
+ await publishDown(machineId, {
+ connId: '',
+ frame: { type: REMOTE_BILLING_SUSPENDED_FRAME },
+ }).catch((err) => {
+ logger.warn('suspended machine disconnect publish failed', {
+ machineId,
+ authMode: binding.authMode,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ })
+ }
+ logger.info('machine subscription expired; machine suspended', { machineId, userId: binding.userId })
+ return true
+ })
+ },
+
+ async cancelPending(
+ machineId: string,
+ userId: string,
+ token: string,
+ requestedEnvironment?: AutonomousEnvironment,
+ ): Promise<void> {
+ const { binding } = await ownedPending(machineId, userId, requestedEnvironment)
+ if (!isBilled(binding.authMode)) {
+ throw new AppError('Machine does not require checkout', 400, 'CHECKOUT_NOT_REQUIRED')
+ }
+ await this.deleteCampaignMachine(machineId, userId, token, requestedEnvironment)
+ },
+}
diff --git a/backend/src/services/MachineBillingWorkerService.test.ts b/backend/src/services/MachineBillingWorkerService.test.ts
new file mode 100644
index 000000000..cc5b37158
--- /dev/null
+++ b/backend/src/services/MachineBillingWorkerService.test.ts
@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const findMany = vi.hoisted(() => vi.fn())
+const syncSubscription = vi.hoisted(() => vi.fn())
+const suspendIfDue = vi.hoisted(() => vi.fn())
+const listSubscriptions = vi.hoisted(() => vi.fn())
+const hasApiKey = vi.hoisted(() => vi.fn())
+const cleanupVoiceQuota = vi.hoisted(() => vi.fn())
+
+vi.mock('../config/env.js', () => ({ env: { HARNESS_CAMPAIGN_CODE: 'ai-harness-device' } }))
+vi.mock('../lib/prisma.js', () => ({
+ prisma: { machine: { findMany } },
+ machineAlive: { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] },
+}))
+vi.mock('../lib/bus.js', () => ({ pub: { set: vi.fn(), eval: vi.fn(async () => 1) } }))
+vi.mock('../lib/autonomousCampaign.js', () => ({
+ CAMPAIGN_REFERENCE_BATCH_SIZE: 100,
+ hasCampaignSubscriptionApiKey: hasApiKey,
+ listCampaignSubscriptionsByApiKey: listSubscriptions,
+}))
+vi.mock('../lib/autonomousEnvironment.js', () => ({
+ storedAutonomousEnvironment: (value: unknown) => value === 'prod' ? 'prod' : 'stag',
+}))
+vi.mock('./MachineBillingService.js', () => ({
+ BILLING_EXPIRY_GRACE_MS: 60 * 60 * 1000,
+ machineBillingService: { syncSubscription, suspendIfDue },
+}))
+vi.mock('../lib/voiceQuota.js', () => ({
+ voiceQuotaService: { cleanup: cleanupVoiceQuota },
+}))
+vi.mock('../utils/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }))
+
+import { machineBillingWorkerService } from './MachineBillingWorkerService.js'
+
+const alive = { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] }
+
+describe('machine billing worker', () => {
+ beforeEach(() => {
+ vi.useFakeTimers()
+ vi.setSystemTime(new Date('2026-07-24T00:00:00.000Z'))
+ vi.clearAllMocks()
+ findMany.mockResolvedValue([])
+ hasApiKey.mockReturnValue(true)
+ listSubscriptions.mockResolvedValue([])
+ syncSubscription.mockResolvedValue({ changed: false })
+ suspendIfDue.mockResolvedValue(false)
+ cleanupVoiceQuota.mockResolvedValue({ released: 0, deleted: 0 })
+ })
+
+ afterEach(() => vi.useRealTimers())
+
+ it('syncs active subscriptions while now-endAt is between -10 and +30 minutes', async () => {
+ findMany
+ .mockResolvedValueOnce([{
+ machineId: 'machine-1',
+ autonomousEnv: 'stag',
+ externalDeviceId: 'device-1',
+ externalSubscriptionId: 'sub-1',
+ }])
+ .mockResolvedValueOnce([])
+ listSubscriptions.mockResolvedValue([{
+ id: 'sub-1',
+ campaignCode: 'ai-harness-device',
+ planId: 38,
+ status: 2,
+ endAt: new Date('2026-08-24T00:00:00.000Z'),
+ }])
+ syncSubscription.mockResolvedValue({ changed: true })
+
+ await expect(machineBillingWorkerService.runOnce()).resolves.toEqual({ synced: 1, suspended: 0 })
+
+ expect(findMany).toHaveBeenNthCalledWith(1, expect.objectContaining({
+ where: {
+ billingStatus: 'active',
+ authMode: { in: ['managed', 'remote', 'provider'] },
+ externalSubscriptionId: { not: null },
+ externalSubscriptionEndAt: {
+ gte: new Date('2026-07-23T23:30:00.000Z'),
+ lte: new Date('2026-07-24T00:10:00.000Z'),
+ },
+ ...alive,
+ },
+ orderBy: { machineId: 'asc' },
+ take: 100,
+ }))
+ expect(listSubscriptions).toHaveBeenCalledWith('stag', 'ai-harness-device', ['device-1'])
+ expect(syncSubscription).toHaveBeenCalledWith('machine-1', expect.objectContaining({ id: 'sub-1' }), 'sub-1')
+ expect(cleanupVoiceQuota).toHaveBeenCalledOnce()
+ })
+
+ it('checks matching subscriptions again on the next one-minute pass', async () => {
+ const candidate = {
+ machineId: 'machine-1',
+ autonomousEnv: 'prod',
+ externalDeviceId: 'device-1',
+ externalSubscriptionId: 'sub-1',
+ }
+ findMany
+ .mockResolvedValueOnce([candidate]).mockResolvedValueOnce([])
+ .mockResolvedValueOnce([candidate]).mockResolvedValueOnce([])
+ listSubscriptions.mockResolvedValue([{ id: 'sub-1', status: 2 }])
+
+ await machineBillingWorkerService.runOnce()
+ await machineBillingWorkerService.runOnce()
+
+ expect(listSubscriptions).toHaveBeenCalledTimes(2)
+ expect(syncSubscription).toHaveBeenCalledTimes(2)
+ })
+
+ it('keeps the one-hour local suspend fallback when upstream sync fails', async () => {
+ findMany
+ .mockResolvedValueOnce([{
+ machineId: 'machine-sync',
+ autonomousEnv: 'prod',
+ externalDeviceId: 'device-sync',
+ externalSubscriptionId: 'sub-sync',
+ }])
+ .mockResolvedValueOnce([{ machineId: 'machine-expired' }])
+ listSubscriptions.mockRejectedValue(new Error('upstream unavailable'))
+ suspendIfDue.mockResolvedValue(true)
+
+ await expect(machineBillingWorkerService.runOnce()).resolves.toEqual({ synced: 0, suspended: 1 })
+ expect(suspendIfDue).toHaveBeenCalledWith('machine-expired')
+ expect(findMany).toHaveBeenNthCalledWith(2, expect.objectContaining({
+ where: {
+ billingStatus: 'active',
+ authMode: { in: ['managed', 'remote', 'provider'] },
+ ...alive,
+ AND: [{
+ OR: [
+ { externalSubscriptionEndAt: { lte: new Date('2026-07-23T23:00:00.000Z') } },
+ { externalSubscriptionStatus: 5 },
+ ],
+ }],
+ },
+ take: 100,
+ }))
+ })
+
+ it('skips only the environment whose API key is missing', async () => {
+ findMany
+ .mockResolvedValueOnce([{
+ machineId: 'machine-1',
+ autonomousEnv: 'stag',
+ externalDeviceId: 'device-1',
+ externalSubscriptionId: 'sub-1',
+ }])
+ .mockResolvedValueOnce([])
+ hasApiKey.mockImplementation((autonomousEnv: string) => autonomousEnv === 'prod')
+
+ await expect(machineBillingWorkerService.runOnce()).resolves.toEqual({ synced: 0, suspended: 0 })
+ expect(listSubscriptions).not.toHaveBeenCalled()
+ expect(syncSubscription).not.toHaveBeenCalled()
+ })
+
+ it('chunks targeted device filters at 100 reference ids', async () => {
+ const candidates = Array.from({ length: 101 }, (_, index) => ({
+ machineId: `machine-${index}`,
+ autonomousEnv: 'prod',
+ externalDeviceId: `device-${index}`,
+ externalSubscriptionId: `sub-${index}`,
+ }))
+ findMany
+ .mockResolvedValueOnce(candidates.slice(0, 100))
+ .mockResolvedValueOnce(candidates.slice(100))
+ .mockResolvedValueOnce([])
+ listSubscriptions.mockImplementation(async (
+ _autonomousEnv: string,
+ _campaignCode: string,
+ referenceIds: string[],
+ ) => referenceIds.map((referenceId) => {
+ const index = referenceId.slice('device-'.length)
+ return { id: `sub-${index}`, referenceId, status: 2 }
+ }))
+ syncSubscription.mockResolvedValue({ changed: true })
+
+ await expect(machineBillingWorkerService.runOnce()).resolves.toEqual({ synced: 101, suspended: 0 })
+
+ expect(listSubscriptions).toHaveBeenCalledTimes(2)
+ expect(listSubscriptions.mock.calls[0]?.[2]).toHaveLength(100)
+ expect(listSubscriptions.mock.calls[1]?.[2]).toEqual(['device-100'])
+ })
+
+ it('does not apply a subscription whose returned reference id belongs to another device', async () => {
+ findMany
+ .mockResolvedValueOnce([{
+ machineId: 'machine-1',
+ autonomousEnv: 'prod',
+ externalDeviceId: 'device-1',
+ externalSubscriptionId: 'sub-1',
+ }])
+ .mockResolvedValueOnce([])
+ listSubscriptions.mockResolvedValue([{
+ id: 'sub-1',
+ referenceId: 'device-other',
+ status: 2,
+ }])
+
+ await expect(machineBillingWorkerService.runOnce()).resolves.toEqual({ synced: 0, suspended: 0 })
+ expect(syncSubscription).not.toHaveBeenCalled()
+ })
+
+ it('never falls back to an unfiltered request when a machine has no external device id', async () => {
+ findMany
+ .mockResolvedValueOnce([{
+ machineId: 'machine-1',
+ autonomousEnv: 'prod',
+ externalDeviceId: null,
+ externalSubscriptionId: 'sub-1',
+ }])
+ .mockResolvedValueOnce([])
+
+ await expect(machineBillingWorkerService.runOnce()).resolves.toEqual({ synced: 0, suspended: 0 })
+ expect(listSubscriptions).not.toHaveBeenCalled()
+ })
+})
diff --git a/backend/src/services/MachineBillingWorkerService.ts b/backend/src/services/MachineBillingWorkerService.ts
new file mode 100644
index 000000000..7159ae499
--- /dev/null
+++ b/backend/src/services/MachineBillingWorkerService.ts
@@ -0,0 +1,267 @@
+import { randomUUID } from 'node:crypto'
+import { env } from '../config/env.js'
+import {
+ CAMPAIGN_REFERENCE_BATCH_SIZE,
+ hasCampaignSubscriptionApiKey,
+ listCampaignSubscriptionsByApiKey,
+} from '../lib/autonomousCampaign.js'
+import {
+ storedAutonomousEnvironment,
+ type AutonomousEnvironment,
+} from '../lib/autonomousEnvironment.js'
+import { pub } from '../lib/bus.js'
+import { machineAlive, prisma } from '../lib/prisma.js'
+import { logger } from '../utils/logger.js'
+import { BILLING_EXPIRY_GRACE_MS, machineBillingService } from './MachineBillingService.js'
+import { voiceQuotaService } from '../lib/voiceQuota.js'
+
+const INTERVAL_MS = 60_000
+const LEASE_MS = 70_000
+const BATCH_SIZE = 100
+const LEASE_KEY = 'machine-billing-expiry-worker'
+const SYNC_BEFORE_END_MS = 10 * 60_000
+const SYNC_AFTER_END_MS = 30 * 60_000
+const SUBSCRIPTION_EXPIRED = 5
+
+interface SyncCandidate {
+ machineId: string
+ autonomousEnv: string
+ externalDeviceId: string | null
+ externalSubscriptionId: string | null
+}
+
+interface BillingWorkerResult {
+ synced: number
+ suspended: number
+}
+
+class MachineBillingWorkerService {
+ private timer: NodeJS.Timeout | undefined
+ private running = false
+
+ start(): void {
+ if (this.timer) return
+ for (const autonomousEnv of ['prod', 'stag'] as const) {
+ if (!hasCampaignSubscriptionApiKey(autonomousEnv)) {
+ logger.warn('campaign subscription sync disabled; API key is not configured', { autonomousEnv })
+ }
+ }
+ void this.tick()
+ this.timer = setInterval(() => void this.tick(), INTERVAL_MS)
+ this.timer.unref?.()
+ logger.info('machine billing worker started', {
+ intervalMs: INTERVAL_MS,
+ syncBeforeEndMs: SYNC_BEFORE_END_MS,
+ syncAfterEndMs: SYNC_AFTER_END_MS,
+ })
+ }
+
+ stop(): void {
+ if (this.timer) clearInterval(this.timer)
+ this.timer = undefined
+ }
+
+ async runOnce(): Promise<BillingWorkerResult> {
+ // Refresh provider truth first so a renewal observed in this pass moves endAt forward before the
+ // local one-hour fallback evaluates the cached value.
+ const synced = await this.syncDueSubscriptions()
+ const suspended = await this.suspendExpiredSubscriptions()
+ try {
+ const voiceCleanup = await voiceQuotaService.cleanup()
+ if (voiceCleanup.released || voiceCleanup.deleted) {
+ logger.info('voice quota cleanup completed', voiceCleanup)
+ }
+ } catch (err) {
+ // Quota cleanup is independent from subscription reconciliation; retry next minute without
+ // turning a transient cleanup failure into a missed billing pass.
+ logger.error('voice quota cleanup failed', err)
+ }
+ return { synced, suspended }
+ }
+
+ private async findSyncCandidates(): Promise<SyncCandidate[]> {
+ const now = Date.now()
+ // now - endAt ∈ [-10m, +30m] ⇔ endAt ∈ [now - 30m, now + 10m].
+ const earliestEndAt = new Date(now - SYNC_AFTER_END_MS)
+ const latestEndAt = new Date(now + SYNC_BEFORE_END_MS)
+ const candidates: SyncCandidate[] = []
+ let cursor: string | undefined
+ while (true) {
+ const page = await prisma.machine.findMany({
+ where: {
+ billingStatus: 'active',
+ authMode: { in: BILLED_MODES },
+ externalSubscriptionId: { not: null },
+ externalSubscriptionEndAt: { gte: earliestEndAt, lte: latestEndAt },
+ ...machineAlive,
+ },
+ orderBy: { machineId: 'asc' },
+ take: BATCH_SIZE,
+ ...(cursor ? { cursor: { machineId: cursor }, skip: 1 } : {}),
+ select: {
+ machineId: true,
+ autonomousEnv: true,
+ externalDeviceId: true,
+ externalSubscriptionId: true,
+ },
+ })
+ candidates.push(...page)
+ if (page.length < BATCH_SIZE) break
+ cursor = page.at(-1)?.machineId
+ if (!cursor) break
+ }
+ return candidates
+ }
+
+ private async syncDueSubscriptions(): Promise<number> {
+ const candidates = await this.findSyncCandidates()
+ const byEnvironment = new Map<AutonomousEnvironment, SyncCandidate[]>()
+ for (const candidate of candidates) {
+ const autonomousEnv = storedAutonomousEnvironment(candidate.autonomousEnv)
+ const group = byEnvironment.get(autonomousEnv) ?? []
+ group.push(candidate)
+ byEnvironment.set(autonomousEnv, group)
+ }
+
+ let synced = 0
+ for (const [autonomousEnv, environmentCandidates] of byEnvironment) {
+ if (!hasCampaignSubscriptionApiKey(autonomousEnv)) continue
+ const candidatesWithDevice = environmentCandidates.filter(
+ (candidate): candidate is SyncCandidate & { externalDeviceId: string } => !!candidate.externalDeviceId,
+ )
+ const missingDeviceId = environmentCandidates.length - candidatesWithDevice.length
+ if (missingDeviceId) {
+ logger.warn('campaign subscription sync skipped machines without a device id', {
+ autonomousEnv,
+ missingDeviceId,
+ })
+ }
+ const referenceIds = [...new Set(candidatesWithDevice.map((candidate) => candidate.externalDeviceId))]
+ let missingSubscription = 0
+ let mismatchedReference = 0
+ for (let offset = 0; offset < referenceIds.length; offset += CAMPAIGN_REFERENCE_BATCH_SIZE) {
+ const referenceBatch = referenceIds.slice(offset, offset + CAMPAIGN_REFERENCE_BATCH_SIZE)
+ const referenceSet = new Set(referenceBatch)
+ const batchCandidates = candidatesWithDevice.filter(
+ (candidate) => referenceSet.has(candidate.externalDeviceId),
+ )
+ try {
+ const subscriptions = await listCampaignSubscriptionsByApiKey(
+ autonomousEnv,
+ env.HARNESS_CAMPAIGN_CODE,
+ referenceBatch,
+ )
+ const byId = new Map(subscriptions.flatMap((subscription) =>
+ subscription.id ? [[subscription.id, subscription] as const] : []))
+ for (const candidate of batchCandidates) {
+ if (!candidate.externalSubscriptionId) continue
+ const subscription = byId.get(candidate.externalSubscriptionId)
+ if (!subscription) {
+ missingSubscription++
+ continue
+ }
+ if (subscription.referenceId && subscription.referenceId !== candidate.externalDeviceId) {
+ mismatchedReference++
+ continue
+ }
+ try {
+ const result = await machineBillingService.syncSubscription(
+ candidate.machineId,
+ subscription,
+ candidate.externalSubscriptionId,
+ )
+ if (result?.changed) synced++
+ } catch (err) {
+ logger.error('machine subscription snapshot reconcile failed', err, {
+ machineId: candidate.machineId,
+ autonomousEnv,
+ })
+ }
+ }
+ } catch (err) {
+ // Keep batches and environments isolated. One malformed/missing device must not block the
+ // remaining candidates, and upstream failure must not prevent the +1h local fallback.
+ logger.error('campaign subscription sync batch failed', err, {
+ autonomousEnv,
+ referenceCount: referenceBatch.length,
+ })
+ }
+ }
+ if (missingSubscription) {
+ logger.warn('campaign subscription snapshot omitted active machine subscriptions', {
+ autonomousEnv,
+ missing: missingSubscription,
+ })
+ }
+ if (mismatchedReference) {
+ logger.warn('campaign subscription snapshot returned mismatched reference ids', {
+ autonomousEnv,
+ mismatchedReference,
+ })
+ }
+ }
+ return synced
+ }
+
+ private async suspendExpiredSubscriptions(): Promise<number> {
+ const overdueCutoff = new Date(Date.now() - BILLING_EXPIRY_GRACE_MS)
+ const due = await prisma.machine.findMany({
+ where: {
+ billingStatus: 'active',
+ authMode: { in: BILLED_MODES },
+ ...machineAlive,
+ AND: [
+ {
+ OR: [
+ { externalSubscriptionEndAt: { lte: overdueCutoff } },
+ // Upstream may advance Cancelled -> Expired before our next pass. Expired is terminal
+ // even if an older record omitted endAt, so it must not remain locally active.
+ { externalSubscriptionStatus: SUBSCRIPTION_EXPIRED },
+ ],
+ },
+ ],
+ },
+ orderBy: { externalSubscriptionEndAt: 'asc' },
+ take: BATCH_SIZE,
+ select: { machineId: true },
+ })
+ const results = await Promise.allSettled(due.map(({ machineId }) => machineBillingService.suspendIfDue(machineId)))
+ let suspended = 0
+ for (const [index, result] of results.entries()) {
+ if (result.status === 'fulfilled') {
+ if (result.value) suspended++
+ } else {
+ logger.error('machine billing expiry reconcile failed', result.reason, { machineId: due[index]?.machineId })
+ }
+ }
+ return suspended
+ }
+
+ private async tick(): Promise<void> {
+ if (this.running) return
+ this.running = true
+ const token = randomUUID()
+ try {
+ if (await pub.set(LEASE_KEY, token, 'PX', LEASE_MS, 'NX') !== 'OK') return
+ const result = await this.runOnce()
+ if (result.synced || result.suspended) logger.info('machine billing pass completed', { ...result })
+ } catch (err) {
+ logger.error('machine billing expiry tick failed', err)
+ } finally {
+ await pub.eval(
+ "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
+ 1,
+ LEASE_KEY,
+ token,
+ ).catch(() => {})
+ this.running = false
+ }
+ }
+}
+
+/** Machine modes that carry a subscription, so the worker sweeps them for renewal and expiry.
+ * Kept as one list because it is used by two separate queries below — see the same set in
+ * MachineBillingService. */
+const BILLED_MODES: string[] = ['managed', 'remote', 'provider']
+
+export const machineBillingWorkerService = new MachineBillingWorkerService()
diff --git a/backend/src/services/MachineService.billing.test.ts b/backend/src/services/MachineService.billing.test.ts
new file mode 100644
index 000000000..2d86b4e34
--- /dev/null
+++ b/backend/src/services/MachineService.billing.test.ts
@@ -0,0 +1,238 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const db = vi.hoisted(() => ({
+ plan: vi.fn(),
+ plans: vi.fn(),
+ bindingCreate: vi.fn(),
+ bindingFind: vi.fn(),
+ bindingFindFirst: vi.fn(),
+ bindingUpdate: vi.fn(),
+}))
+const selectManager = vi.hoisted(() => vi.fn())
+const provision = vi.hoisted(() => vi.fn())
+const publishMachineList = vi.hoisted(() => vi.fn())
+const publishDown = vi.hoisted(() => vi.fn())
+const clearPresence = vi.hoisted(() => vi.fn())
+const billing = vi.hoisted(() => ({
+ reserveFreeEntitlement: vi.fn(),
+ releaseFreeReservation: vi.fn(),
+ cancelPending: vi.fn(),
+ deleteCampaignMachine: vi.fn(),
+}))
+
+vi.mock('../config/env.js', () => ({ env: { HARNESS_BILLING_ENABLED: true, HARNESS_CAMPAIGN_CODE: 'ai-harness-device' } }))
+vi.mock('../lib/prisma.js', () => ({
+ machineAlive: { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] },
+ prisma: {
+ subscriptionPlan: { findUnique: db.plan, findMany: db.plans },
+ machine: {
+ create: db.bindingCreate,
+ findUnique: db.bindingFind,
+ findFirst: db.bindingFindFirst,
+ update: db.bindingUpdate,
+ },
+ },
+}))
+vi.mock('../lib/managers.js', () => ({ selectManagerId: selectManager }))
+vi.mock('../lib/provision.js', () => ({ provisionViaManager: provision }))
+vi.mock('../lib/bus.js', () => ({
+ getAgentPresence: vi.fn(), clearAgentPresence: clearPresence, publishDown,
+ publishDeviceMachineListChanged: publishMachineList,
+}))
+vi.mock('../utils/crypto.js', () => ({ generateApiKey: vi.fn(() => 'agent-key'), machineIdFromKey: vi.fn(() => 'a'.repeat(32)) }))
+vi.mock('../utils/logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }))
+vi.mock('../lib/machineLifecycle.js', () => ({ ensureMachineReady: vi.fn(), publishMachineLifecycle: vi.fn() }))
+vi.mock('./MachineBillingService.js', () => ({ machineBillingService: billing }))
+
+import { machineService } from './MachineService.js'
+
+const plan = {
+ id: 'plan-1', name: 'Pro', authMode: 'managed', available: true,
+ autonomousEnv: 'prod',
+ externalPlanId: 38, campaignCode: 'ai-harness-device',
+}
+const created = {
+ id: 'binding-1', userId: 'user-1', machineId: 'a'.repeat(32), apiKey: 'agent-key',
+ managerId: 'mgr-1', workspaceId: null, planId: 'plan-1', authMode: 'managed',
+ autonomousEnv: 'prod',
+ name: null, billingStatus: 'pending', externalDeviceId: null,
+ externalSubscriptionId: null, billingActivatedAt: null, billingError: null,
+ billingErrorAt: null, llmApiKeyEncrypted: null, deletedAt: null, createdAt: new Date(),
+}
+const remotePlan = {
+ ...plan,
+ id: 'plan-remote',
+ name: 'Remote',
+ authMode: 'remote',
+ externalPlanId: 40,
+}
+const remoteCreated = {
+ ...created,
+ planId: remotePlan.id,
+ authMode: 'remote',
+ managerId: '',
+}
+
+describe('managed machine reservation', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ db.plan.mockResolvedValue(plan)
+ db.plans.mockResolvedValue([plan])
+ selectManager.mockResolvedValue({ managerId: 'mgr-1' })
+ db.bindingCreate.mockResolvedValue(created)
+ db.bindingUpdate.mockResolvedValue(created)
+ publishMachineList.mockResolvedValue(1)
+ publishDown.mockResolvedValue(undefined)
+ clearPresence.mockResolvedValue(undefined)
+ billing.reserveFreeEntitlement.mockResolvedValue(undefined)
+ billing.releaseFreeReservation.mockResolvedValue(undefined)
+ billing.deleteCampaignMachine.mockResolvedValue(undefined)
+ provision.mockResolvedValue(undefined)
+ })
+
+ it('writes only a payment-pending binding and never provisions Docker before checkout', async () => {
+ await expect(machineService.create('user-1', undefined, { planId: 'plan-1', autonomousEnv: 'prod' }))
+ .resolves.toMatchObject({ machineId: 'a'.repeat(32), billingStatus: 'pending', status: 'payment_pending' })
+ expect(db.bindingCreate).toHaveBeenCalledWith({
+ data: expect.objectContaining({ managerId: 'mgr-1', billingStatus: 'pending', authMode: 'managed' }),
+ })
+ expect(provision).not.toHaveBeenCalled()
+ expect(billing.reserveFreeEntitlement).toHaveBeenCalledWith('user-1', 'a'.repeat(32), plan)
+ expect(publishMachineList).toHaveBeenCalledWith('user-1', { reason: 'created' })
+ })
+
+ it('creates a paid Remote machine as pending without manager placement or Docker', async () => {
+ db.plan.mockResolvedValue(remotePlan)
+ db.bindingCreate.mockResolvedValue(remoteCreated)
+
+ await expect(machineService.create('user-1', undefined, { planId: remotePlan.id, autonomousEnv: 'prod' }))
+ .resolves.toMatchObject({
+ machineId: 'a'.repeat(32), authMode: 'remote', billingStatus: 'pending', status: 'payment_pending',
+ })
+
+ expect(db.bindingCreate).toHaveBeenCalledWith({
+ data: expect.objectContaining({ managerId: '', billingStatus: 'pending', authMode: 'remote' }),
+ })
+ expect(selectManager).not.toHaveBeenCalled()
+ expect(billing.reserveFreeEntitlement).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('rejects grandfathered plans even when their rows remain in Mongo', async () => {
+ db.plan.mockResolvedValue({ ...plan, name: 'Managed', available: false, externalPlanId: null })
+ await expect(machineService.create('user-1', undefined, { planId: 'plan-1', autonomousEnv: 'prod' }))
+ .rejects.toMatchObject({ code: 'PLAN_UNAVAILABLE' })
+ expect(db.bindingCreate).not.toHaveBeenCalled()
+ })
+
+ it('delegates managed billing cleanup before tearing down an active machine', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...created, billingStatus: 'active', externalDeviceId: 'device-1', externalSubscriptionId: 'sub-1',
+ })
+ await machineService.destroy(created.machineId, { sub: 'user-1', role: 'user', autonomousEnv: 'prod' }, 'sso-token')
+
+ expect(billing.deleteCampaignMachine).toHaveBeenCalledWith(created.machineId, 'user-1', 'sso-token', 'prod')
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ await vi.waitFor(() => expect(provision).toHaveBeenCalledWith('mgr-1', 'destroy', { machineId: created.machineId }))
+ })
+
+ it('resolves an external campaign device only inside the caller owner and environment', async () => {
+ db.bindingFindFirst.mockResolvedValue({ ...created, externalDeviceId: 'device-1' })
+
+ await expect(machineService.resolveByExternalDeviceId(
+ 'device-1',
+ { sub: 'user-1', role: 'user', autonomousEnv: 'prod' },
+ )).resolves.toMatchObject({
+ machineId: created.machineId,
+ planName: 'Pro',
+ billingStatus: 'pending',
+ status: 'payment_pending',
+ })
+
+ expect(db.bindingFindFirst).toHaveBeenCalledWith({
+ where: {
+ externalDeviceId: 'device-1',
+ userId: 'user-1',
+ autonomousEnv: 'prod',
+ OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }],
+ },
+ orderBy: { createdAt: 'desc' },
+ })
+ })
+
+ it('does not resolve an external campaign device outside the caller scope', async () => {
+ db.bindingFindFirst.mockResolvedValue(null)
+
+ await expect(machineService.resolveByExternalDeviceId(
+ 'device-other',
+ { sub: 'user-1', role: 'user', autonomousEnv: 'prod' },
+ )).rejects.toMatchObject({ code: 'NOT_FOUND' })
+
+ expect(db.plans).not.toHaveBeenCalled()
+ })
+
+ it('does not soft-delete or tear down when upstream billing cleanup fails', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...created, billingStatus: 'active', externalDeviceId: 'device-1', externalSubscriptionId: 'sub-1',
+ })
+ billing.deleteCampaignMachine.mockRejectedValue(new Error('provider unavailable'))
+
+ await expect(machineService.destroy(
+ created.machineId, { sub: 'user-1', role: 'user', autonomousEnv: 'prod' }, 'sso-token',
+ )).rejects.toThrow('provider unavailable')
+
+ expect(db.bindingUpdate).not.toHaveBeenCalled()
+ expect(provision).not.toHaveBeenCalled()
+ })
+
+ it('deletes a legacy Managed machine locally when it has no campaign billing metadata', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...created,
+ billingStatus: null,
+ externalDeviceId: null,
+ externalSubscriptionId: null,
+ externalSubscriptionStatus: null,
+ externalSubscriptionEndAt: null,
+ externalSubscriptionCancelledAt: null,
+ billingActivatedAt: null,
+ })
+
+ await machineService.destroy(
+ created.machineId,
+ { sub: 'user-1', role: 'user', autonomousEnv: 'prod' },
+ )
+
+ expect(billing.deleteCampaignMachine).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: created.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ expect(publishMachineList).toHaveBeenCalledWith('user-1', { reason: 'deleted' })
+ await vi.waitFor(() => expect(provision).toHaveBeenCalledWith(
+ 'mgr-1', 'destroy', { machineId: created.machineId },
+ ))
+ })
+
+ it('runs billing cleanup for a new paid Remote machine without touching Docker', async () => {
+ db.bindingFind.mockResolvedValue({
+ ...remoteCreated, billingStatus: 'active', externalDeviceId: 'device-remote', externalSubscriptionId: 'sub-remote',
+ })
+
+ await machineService.destroy(remoteCreated.machineId, { sub: 'user-1', role: 'user', autonomousEnv: 'prod' }, 'sso-token')
+
+ expect(billing.deleteCampaignMachine).toHaveBeenCalledWith(remoteCreated.machineId, 'user-1', 'sso-token', 'prod')
+ expect(provision).not.toHaveBeenCalled()
+ expect(publishDown).toHaveBeenCalledWith(remoteCreated.machineId, { connId: '', frame: { type: 'machine_revoked' } })
+ })
+
+ it('keeps grandfathered Remote deletion local and does not require upstream billing', async () => {
+ db.bindingFind.mockResolvedValue({ ...remoteCreated, billingStatus: 'not_required', externalDeviceId: null })
+
+ await machineService.destroy(remoteCreated.machineId, { sub: 'user-1', role: 'user', autonomousEnv: 'prod' })
+
+ expect(billing.deleteCampaignMachine).not.toHaveBeenCalled()
+ expect(db.bindingUpdate).toHaveBeenCalledWith({
+ where: { machineId: remoteCreated.machineId }, data: { deletedAt: expect.any(Date) },
+ })
+ expect(provision).not.toHaveBeenCalled()
+ })
+})
diff --git a/backend/src/services/MachineService.list.test.ts b/backend/src/services/MachineService.list.test.ts
new file mode 100644
index 000000000..36f61557b
--- /dev/null
+++ b/backend/src/services/MachineService.list.test.ts
@@ -0,0 +1,118 @@
+/**
+ * The soft-delete filter on the machine list.
+ *
+ * This is the one line standing between a deleted machine and an app-store binary: `/api/mobile/v1/overview`
+ * builds its whole machine list from `machineService.listForUser` (routes/mobile.ts), and the mobile route's
+ * own test mocks that call away — so nothing else in the suite proves a deleted machine cannot reach it.
+ *
+ * `prisma.machine.findMany` is mocked to genuinely EVALUATE the where-clause with Mongo semantics rather
+ * than echo it back, because the bug this guards against is exactly the semantic Prisma+Mongo gets wrong:
+ * a MISSING field is not null, so `{deletedAt: null}` alone silently drops every legacy row.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const findMany = vi.hoisted(() => vi.fn())
+const groupBy = vi.hoisted(() => vi.fn())
+const planFindMany = vi.hoisted(() => vi.fn())
+const runCommandRaw = vi.hoisted(() => vi.fn())
+const getAgentPresence = vi.hoisted(() => vi.fn())
+
+vi.mock('../lib/prisma.js', () => ({
+ // The REAL helper — the thing under test is whether listForUser applies it, so stubbing it would
+ // test the stub.
+ machineAlive: { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] },
+ prisma: {
+ machine: { findMany },
+ machineAgent: { groupBy },
+ subscriptionPlan: { findMany: planFindMany },
+ $runCommandRaw: runCommandRaw,
+ },
+}))
+vi.mock('../lib/bus.js', () => ({
+ getAgentPresence,
+ clearAgentPresence: vi.fn(),
+ publishDown: vi.fn(),
+ publishDeviceMachineListChanged: vi.fn(),
+}))
+vi.mock('../config/env.js', () => ({ env: { HARNESS_BILLING_ENABLED: true, HARNESS_CAMPAIGN_CODE: 'ai-harness-device' } }))
+vi.mock('../lib/managers.js', () => ({ selectManagerId: vi.fn() }))
+vi.mock('../lib/provision.js', () => ({ provisionViaManager: vi.fn() }))
+vi.mock('../lib/machineLifecycle.js', () => ({ ensureMachineReady: vi.fn(), publishMachineLifecycle: vi.fn() }))
+vi.mock('../lib/machineCredential.js', () => ({ encryptMachineCredential: vi.fn() }))
+vi.mock('./MachineBillingService.js', () => ({ machineBillingService: {} }))
+
+const { machineService } = await import('./MachineService.js')
+
+type Row = Record<string, unknown>
+type Where = Record<string, unknown>
+
+/**
+ * Mongo matching semantics, deliberately faithful on the one point that matters: an ABSENT key is not
+ * null. `{deletedAt: null}` matches an explicit null only — which is why `machineAlive` is an OR.
+ */
+function matches(row: Row, where: Where): boolean {
+ return Object.entries(where).every(([key, cond]) => {
+ if (key === 'OR') return (cond as Where[]).some((c) => matches(row, c))
+ if (key === 'AND') return (cond as Where[]).every((c) => matches(row, c))
+ const present = key in row
+ if (cond && typeof cond === 'object' && !(cond instanceof Date)) {
+ const c = cond as Record<string, unknown>
+ if ('isSet' in c) return c.isSet === present
+ if ('in' in c) return present && (c.in as unknown[]).includes(row[key])
+ }
+ if (cond === null) return present && row[key] === null
+ return present && row[key] === cond
+ })
+}
+
+const base = { authMode: 'self', billingStatus: 'active', planId: null, createdAt: new Date('2026-01-01') }
+
+/** One of each shape a real collection holds after years of schema drift. */
+const ROWS: Row[] = [
+ // Legacy: the field was never written. This is the row `{deletedAt: null}` alone would lose.
+ { ...base, machineId: 'legacy', userId: 'u1' },
+ { ...base, machineId: 'explicit-null', userId: 'u1', deletedAt: null },
+ { ...base, machineId: 'deleted', userId: 'u1', deletedAt: new Date('2026-08-01') },
+ { ...base, machineId: 'someone-else', userId: 'u2' },
+]
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ findMany.mockImplementation(async ({ where }: { where: Where }) => ROWS.filter((r) => matches(r, where)))
+ groupBy.mockResolvedValue([])
+ planFindMany.mockResolvedValue([])
+ runCommandRaw.mockResolvedValue({ cursor: { firstBatch: [] } })
+ getAgentPresence.mockResolvedValue(null)
+})
+
+const listedIds = async (env?: 'prod' | 'stag') =>
+ (await machineService.listForUser('u1', env)).map((m) => m.machineId)
+
+describe('listForUser — what the mobile app is allowed to see', () => {
+ it('never returns a soft-deleted machine', async () => {
+ expect(await listedIds()).not.toContain('deleted')
+ })
+
+ it('still returns a legacy row that has no deletedAt field at all', async () => {
+ // The regression that filtering with a bare `{deletedAt: null}` would cause: every pre-soft-delete
+ // machine vanishes from the list, which reads to the owner as their machines being gone.
+ expect(await listedIds()).toContain('legacy')
+ })
+
+ it('returns a row whose deletedAt is an explicit null', async () => {
+ expect(await listedIds()).toContain('explicit-null')
+ })
+
+ it('returns exactly the caller-s live machines', async () => {
+ expect((await listedIds()).sort()).toEqual(['explicit-null', 'legacy'])
+ })
+
+ it('keeps the delete filter when an environment filter is also applied', async () => {
+ // Both are spread into one where-clause; the alive filter is an OR, so a future sibling OR would
+ // silently overwrite it. Assert the combination, not just the simple case.
+ await listedIds('prod')
+ const where = findMany.mock.calls[0]![0].where as Where
+ expect(where.autonomousEnv).toBe('prod')
+ expect(where.OR).toEqual([{ deletedAt: null }, { deletedAt: { isSet: false } }])
+ })
+})
diff --git a/backend/src/services/MachineService.ts b/backend/src/services/MachineService.ts
new file mode 100644
index 000000000..1427221f1
--- /dev/null
+++ b/backend/src/services/MachineService.ts
@@ -0,0 +1,629 @@
+import type { Machine } from '@prisma/client'
+import { prisma, machineAlive } from '../lib/prisma.js'
+import { selectManagerId } from '../lib/managers.js'
+import { provisionViaManager } from '../lib/provision.js'
+import { getAgentPresence, clearAgentPresence, publishDown, publishDeviceMachineListChanged, pub } from '../lib/bus.js'
+import { randomUUID } from 'node:crypto'
+import { generateApiKey, machineIdFromKey } from '../utils/crypto.js'
+import { assertMachineId, isMachineId } from '../utils/slug.js'
+import { AppError, ForbiddenError, NotFoundError } from '../errors/index.js'
+import { logger } from '../utils/logger.js'
+import { ensureMachineReady, publishMachineLifecycle } from '../lib/machineLifecycle.js'
+import { assertMachineBillingActive, billingStatusOf, type MachineBillingStatus } from '../lib/billingState.js'
+import { env } from '../config/env.js'
+import { encryptMachineCredential } from '../lib/machineCredential.js'
+import { machineBillingService } from './MachineBillingService.js'
+import { storedAutonomousEnvironment, type AutonomousEnvironment } from '../lib/autonomousEnvironment.js'
+
+/** The agent's tier / how it runs Claude, resolved through its plan.
+ * 'self' | 'managed' = a docker agent-node on a manager host; 'remote' = the user's own computer
+ * paired via the machine-adapter CLI; 'provider' = a third-party endpoint the owner pointed us at.
+ * The last two have no manager and no node — the binding is the whole machine. */
+export type AgentAuthMode = 'self' | 'managed' | 'remote' | 'provider'
+export type AgentEngine = 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'hermes' | 'commandcode' | 'devin'
+
+/** Modes with no container of ours: no manager reservation, no docker node, nothing to start or stop. */
+export const NODELESS_MODES: ReadonlySet<AgentAuthMode> = new Set(['remote', 'provider'])
+export const isNodeless = (v: string | null | undefined): boolean => NODELESS_MODES.has(toAuthMode(v))
+
+function toAuthMode(v: string | null | undefined): AgentAuthMode {
+ return v === 'managed' || v === 'remote' || v === 'provider' ? v : 'self'
+}
+
+/**
+ * Owner view of a binding. Machine API keys remain server-internal; browser and adapter
+ * transports authenticate with the owner's SSO access token.
+ */
+export interface OwnerMachine {
+ machineId: string
+ computerId: string | null
+ workspaceId: string | null
+ planId: string | null
+ autonomousEnv: AutonomousEnvironment
+ // The agent's tier / how it authenticates with Claude, resolved through its plan.
+ authMode: AgentAuthMode
+ planName: string | null
+ billingStatus: MachineBillingStatus
+ createdAt: Date
+ status: string
+ agentCount: number
+ // The agent's CLI engine (from the manager's AgentNode.engine); drives the web's engine-aware UI
+ // so opening the agent renders the right badge/affordances immediately.
+ engine: AgentEngine
+ // The machine's display name (user-editable). Null until named or seeded from a connect.
+ name: string | null
+ // Hostname of the COMPUTER on its last connect (remote machines) — secondary detail on the card,
+ // never the name. Null if no computer has ever connected.
+ hostname: string | null
+}
+
+interface PlanInfo {
+ authMode: AgentAuthMode
+ name: string | null
+}
+
+interface MachineRequester {
+ sub: string
+ role: string
+ autonomousEnv?: AutonomousEnvironment
+}
+
+function assertRequesterEnvironment(binding: Machine, requester: MachineRequester): void {
+ if (requester.autonomousEnv && storedAutonomousEnvironment(binding.autonomousEnv) !== requester.autonomousEnv) {
+ throw new AppError('Machine belongs to another Autonomous environment', 403, 'MACHINE_ENV_MISMATCH')
+ }
+}
+
+function toOwner(b: Machine, status = 'unknown', agentCount = 0, plan?: PlanInfo, engine = 'claude'): OwnerMachine {
+ return {
+ machineId: b.machineId,
+ computerId: b.computerId ?? null,
+ workspaceId: b.workspaceId,
+ planId: b.planId,
+ autonomousEnv: storedAutonomousEnvironment(b.autonomousEnv),
+ authMode: plan?.authMode ?? 'self',
+ planName: plan?.name ?? null,
+ billingStatus: billingStatusOf(b),
+ createdAt: b.createdAt,
+ status,
+ agentCount,
+ engine: normalizeEngine(engine),
+ name: b.name ?? null,
+ hostname: b.hostname ?? null,
+ }
+}
+
+const COMPUTER_CREATE_LOCK_TTL_MS = 15_000
+const COMPUTER_CREATE_LOCK_WAIT_MS = 10_000
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
+
+function computerCreateLockKey(userId: string, computerId: string): string {
+ return `machine:create:${userId}:${computerId}`
+}
+
+/**
+ * Serialize the rare first-login create path across backend replicas. The machine schema cannot
+ * use a simple unique key because older rows can share a nullable computer id, so re-checking
+ * under a short Redis lock prevents concurrent adapter upgrades from minting duplicate rows.
+ */
+async function withComputerCreateLock<T>(userId: string, computerId: string, action: () => Promise<T>): Promise<T> {
+ const key = computerCreateLockKey(userId, computerId)
+ const owner = randomUUID()
+ const deadline = Date.now() + COMPUTER_CREATE_LOCK_WAIT_MS
+ let acquired = false
+ while (Date.now() < deadline) {
+ try {
+ acquired = (await pub.set(key, owner, 'PX', COMPUTER_CREATE_LOCK_TTL_MS, 'NX')) === 'OK'
+ } catch (err) {
+ logger.error('computer create lock unavailable', err, { userId, computerId })
+ throw new AppError('Could not reserve this computer. Please retry.', 503, 'COMPUTER_LOCK_UNAVAILABLE')
+ }
+ if (acquired) break
+ await sleep(40)
+ }
+ if (!acquired) throw new AppError('Computer setup is already in progress. Please retry.', 409, 'COMPUTER_SETUP_BUSY')
+ try {
+ return await action()
+ } finally {
+ // Never delete a successor's lock if this process stalled beyond the TTL.
+ try {
+ const current = await pub.get(key)
+ if (current === owner) await pub.del(key)
+ } catch (err) {
+ logger.warn('computer create lock release failed', { userId, computerId, err })
+ }
+ }
+}
+
+function firstUsableComputerMachine(rows: Machine[]): Machine | undefined {
+ return rows.find((machine) => {
+ const status = billingStatusOf(machine)
+ return status === 'active' || status === 'not_required'
+ })
+}
+
+/** Resolve each agent's plan display name via its binding's planId. authMode comes from the BINDING
+ * (denormalized at create, backfilled at boot) — never from the plan, so a later plan-doc edit can't
+ * flip a live agent's mode. Missing/legacy → self. */
+async function plansByMachine(bindings: Machine[]): Promise<Map<string, PlanInfo>> {
+ const out = new Map<string, PlanInfo>()
+ const planIds = [...new Set(bindings.map((b) => b.planId).filter((id): id is string => !!id))]
+ const plans = planIds.length ? await prisma.subscriptionPlan.findMany({ where: { id: { in: planIds } } }) : []
+ const byId = new Map(plans.map((p) => [p.id, p]))
+ for (const b of bindings) {
+ const p = b.planId ? byId.get(b.planId) : undefined
+ out.set(b.machineId, { authMode: toAuthMode(b.authMode), name: p?.name ?? null })
+ }
+ return out
+}
+
+/** Project count per machineId, from the proxy-populated `machine_agents` collection. */
+async function countByMachine(ids: string[]): Promise<Map<string, number>> {
+ const out = new Map<string, number>()
+ if (ids.length === 0) return out
+ const grouped = await prisma.machineAgent.groupBy({
+ by: ['machineId'],
+ where: { machineId: { in: ids } },
+ _count: { _all: true },
+ })
+ for (const g of grouped) out.set(g.machineId, g._count._all)
+ return out
+}
+
+function normalizeEngine(v: unknown): AgentEngine {
+ return v === 'codex' || v === 'cursor' || v === 'opencode' || v === 'pi' || v === 'hermes' || v === 'commandcode' || v === 'devin' ? v : 'claude'
+}
+
+/**
+ * Legacy Managed machines predate campaign billing. Their retired plan rows still say
+ * `authMode=managed`, but they have no billing lifecycle or provider references. Treating every
+ * Managed machine as externally billed sends those rows through plan/subscription cancellation and
+ * makes them undeletable once the legacy plan is no longer in the campaign catalog.
+ *
+ * Any lifecycle state or provider reference is billing evidence and keeps the billing-safe delete
+ * path intact, so a real renewable subscription can never be hidden without cancellation.
+ */
+function hasManagedCampaignBilling(binding: Machine): boolean {
+ return binding.authMode === 'managed' && (
+ binding.billingStatus === 'pending'
+ || binding.billingStatus === 'active'
+ || binding.billingStatus === 'suspended'
+ || binding.externalDeviceId != null
+ || binding.externalSubscriptionId != null
+ || binding.externalSubscriptionStatus != null
+ || binding.externalSubscriptionEndAt != null
+ || binding.externalSubscriptionCancelledAt != null
+ || binding.billingActivatedAt != null
+ )
+}
+
+/** Best-effort node status + engine per machineId, read directly from the shared Mongo `machine_nodes`
+ * collection (the agent-manager owns writes; the backend just reads). `machine_nodes.engine` is an
+ * optional per-machine override; when absent, fall back to the owning manager's MACHINE_ENGINE mirror. */
+async function nodeInfoByAgent(bindings: Machine[]): Promise<Map<string, { status: string; engine: string }>> {
+ const out = new Map<string, { status: string; engine: string }>()
+ const ids = bindings.map((b) => b.machineId)
+ if (!ids.length) return out
+ try {
+ const raw = (await prisma.$runCommandRaw({
+ find: 'machine_nodes',
+ filter: { machineId: { $in: ids } },
+ projection: { machineId: 1, status: 1, engine: 1, managerId: 1, _id: 0 },
+ })) as { cursor?: { firstBatch?: Array<{ machineId?: string; status?: string; engine?: string; managerId?: string }> } }
+ const nodes = raw?.cursor?.firstBatch ?? []
+ const managerIds = [...new Set(nodes.map((n) => n.managerId).filter((id): id is string => typeof id === 'string'))]
+ const managerEngines = new Map<string, AgentEngine>()
+ if (managerIds.length) {
+ const managers = await prisma.manager.findMany({
+ where: { managerId: { in: managerIds } },
+ select: { managerId: true, agentEngine: true },
+ })
+ for (const m of managers) managerEngines.set(m.managerId, normalizeEngine(m.agentEngine))
+ }
+ for (const n of nodes) {
+ if (typeof n.machineId === 'string') {
+ const fallback = n.managerId ? managerEngines.get(n.managerId) : undefined
+ out.set(n.machineId, { status: n.status ?? 'unknown', engine: normalizeEngine(n.engine ?? fallback) })
+ }
+ }
+ } catch { /* best effort — leave unresolved agents as unknown */ }
+ for (const b of bindings) if (!out.has(b.machineId)) out.set(b.machineId, { status: 'unknown', engine: 'claude' })
+ return out
+}
+
+/** Remote agents have no agent_nodes row — their liveness is the adapter's presence key
+ * (`agent:{id}:mgr`, set by /api/adapter-ws while the machine is connected). Patch `info` in place. */
+async function applyRemoteStatus(
+ bindings: Machine[],
+ plans: Map<string, PlanInfo>,
+ info: Map<string, { status: string; engine: string }>,
+): Promise<void> {
+ const remote = bindings.filter((b) => plans.get(b.machineId)?.authMode === 'remote')
+ await Promise.all(
+ remote.map(async (b) => {
+ const online = !!(await getAgentPresence(b.machineId))
+ info.set(b.machineId, { status: online ? 'running' : 'offline', engine: 'claude' })
+ }),
+ )
+}
+
+async function ownerViewForBinding(binding: Machine): Promise<OwnerMachine> {
+ const machineId = binding.machineId
+ if (billingStatusOf(binding) === 'pending') {
+ const plans = await plansByMachine([binding])
+ return toOwner(binding, 'payment_pending', 0, plans.get(machineId), 'claude')
+ }
+ const [info, counts, plans] = await Promise.all([
+ nodeInfoByAgent([binding]),
+ countByMachine([machineId]),
+ plansByMachine([binding]),
+ ])
+ await applyRemoteStatus([binding], plans, info)
+ const ni = info.get(machineId)
+ return toOwner(binding, ni?.status ?? 'unknown', counts.get(machineId) ?? 0, plans.get(machineId), ni?.engine)
+}
+
+/** Best-effort background container teardown for a deleted managed machine. The row is already gone
+ * (the user got their response); this just reaps the container + node row. `destroy` is idempotent
+ * on the manager, so we retry a few times to survive a momentarily-busy/unreachable manager. If
+ * every attempt fails, the row/container is orphaned (reconcile won't reap binding-less rows) —
+ * log loudly for ops. */
+async function destroyNodeWithRetry(machineId: string, managerId: string, attempts = 3): Promise<void> {
+ for (let i = 1; i <= attempts; i++) {
+ try {
+ await provisionViaManager(managerId, 'destroy', { machineId: machineId })
+ logger.info('agent-node container destroyed', { machineId, managerId, attempt: i })
+ return
+ } catch (err) {
+ if (i === attempts) {
+ logger.error('agent-node teardown failed after retries — may leave an orphan container/row',
+ err instanceof Error ? err : new Error(String(err)), { machineId, managerId })
+ return
+ }
+ logger.warn('agent-node teardown attempt failed, retrying', { machineId, attempt: i, error: String(err) })
+ await new Promise((r) => setTimeout(r, i * 3000)) // 3s, 6s backoff
+ }
+ }
+}
+
+/** Provider details, encrypted at rest. The credential is never stored or logged in the clear. */
+function providerFields(provider?: { url: string; credential: string }): Record<string, string> {
+ if (!provider) return {}
+ return {
+ providerUrl: provider.url,
+ providerCredentialEncrypted: encryptMachineCredential(provider.credential),
+ }
+}
+
+export const machineService = {
+ /** Provision a machine for a user (N allowed). Managed tiers: pick a manager (best-fit) → bind (on a
+ * plan) → create a docker node. Remote tier: write ONLY the binding — the user pairs their own
+ * machine (machine-adapter CLI) with the apiKey; no placement, no node, no docker. */
+ async create(
+ userId: string,
+ workspaceId: string | undefined,
+ opts: {
+ planId: string
+ autonomousEnv: AutonomousEnvironment
+ /** provider tier only — already probed by the route, stored encrypted here. */
+ provider?: { url: string; credential: string }
+ },
+ ): Promise<OwnerMachine> {
+ // The caller must pick a plan (required); it decides authMode (self/managed/remote) and, for managed
+ // tiers, the manager resolves cpus/memory through it.
+ const plan = await prisma.subscriptionPlan.findUnique({ where: { id: opts.planId } })
+ if (!plan) throw new AppError('Unknown plan', 400, 'NO_PLAN')
+ if (plan.available !== true) throw new AppError('Plan is not available for new machines', 409, 'PLAN_UNAVAILABLE')
+ if (storedAutonomousEnvironment(plan.autonomousEnv) !== opts.autonomousEnv) {
+ throw new AppError('Plan belongs to another Autonomous environment', 409, 'PLAN_ENV_MISMATCH')
+ }
+
+ const apiKey = generateApiKey()
+ const machineId = machineIdFromKey(apiKey)
+ const planInfo: PlanInfo = { authMode: toAuthMode(plan.authMode), name: plan.name }
+ const campaignBilled = env.HARNESS_BILLING_ENABLED && !!plan.externalPlanId &&
+ plan.campaignCode === env.HARNESS_CAMPAIGN_CODE
+
+ if (planInfo.authMode === 'remote' && !campaignBilled) {
+ if (env.HARNESS_BILLING_ENABLED) {
+ throw new AppError('Remote machine billing is unavailable', 503, 'BILLING_DISABLED')
+ }
+ // Remote = pair the user's own machine. managerId '' marks "no owning manager"; the binding
+ // is the whole agent. This immediate path exists only for the explicit billing rollback flag;
+ // normal catalog-backed Remote machines start pending and use hosted checkout below.
+ const binding = await prisma.machine.create({
+ data: {
+ userId, machineId: machineId, apiKey, managerId: '', workspaceId: workspaceId ?? null,
+ autonomousEnv: opts.autonomousEnv,
+ planId: plan.id, authMode: planInfo.authMode, billingStatus: 'not_required',
+ ...providerFields(opts.provider),
+ },
+ })
+ await publishDeviceMachineListChanged(userId, { reason: 'created' }).catch(() => { /* best effort */ })
+ logger.info('remote agent created (binding only)', { userId, machineId, planId: plan.id })
+ return toOwner(binding, 'offline', 0, planInfo, 'claude')
+ }
+
+ if (!campaignBilled) {
+ throw new AppError('Machine billing is unavailable', 503, 'BILLING_DISABLED')
+ }
+
+ // Remote has no manager reservation or Docker runtime. Managed uses capacity-aware placement.
+ // Remote and provider have no manager reservation and no Docker runtime; '' marks "no owning
+ // manager" and the binding is the whole machine. Managed uses capacity-aware placement.
+ const managerId = NODELESS_MODES.has(planInfo.authMode) ? '' : (await selectManagerId()).managerId
+
+ // Free is an account-lifetime entitlement. Reserve it before committing the pending binding so
+ // two concurrent tabs cannot create two Free machines. A binding-create failure releases only the
+ // still-unclaimed reservation; once upstream activation succeeds the ledger is permanent.
+ if (planInfo.authMode === 'managed') {
+ await machineBillingService.reserveFreeEntitlement(userId, machineId, plan)
+ }
+
+ // Write the binding FIRST: the manager reads the plan (via planId) from it, and refuses to
+ // create a node without a binding.
+ let binding: Machine
+ try {
+ binding = await prisma.machine.create({
+ data: {
+ userId, machineId: machineId, apiKey, managerId,
+ autonomousEnv: opts.autonomousEnv,
+ workspaceId: workspaceId ?? null, planId: plan.id, authMode: planInfo.authMode,
+ billingStatus: 'pending',
+ ...providerFields(opts.provider),
+ },
+ })
+ } catch (err) {
+ if (planInfo.authMode === 'managed') {
+ await machineBillingService.releaseFreeReservation(userId, machineId).catch(() => {})
+ }
+ throw err
+ }
+ // New managed machines reserve a manager slot but intentionally have no MachineNode/Docker until
+ // Autonomous confirms the exact campaign/device/plan subscription.
+ // The invalidation is safe for hardware devices because their machine query filters pending rows;
+ // web tabs still need it so Resume/Cancel appears immediately everywhere.
+ await publishDeviceMachineListChanged(userId, { reason: 'created' }).catch(() => { /* best effort */ })
+ logger.info('pending campaign machine reserved', {
+ userId,
+ machineId,
+ managerId,
+ authMode: planInfo.authMode,
+ planId: plan.id,
+ })
+ return toOwner(binding, 'payment_pending', 0, planInfo, 'claude')
+ },
+
+ /**
+ * The machine a computer connects to through `harness login`: the one already bound to this
+ * computerId, else a brand-new Remote machine.
+ *
+ * Deliberately does NOT go through `create()`. That path is the *purchase* path — it demands an
+ * available plan and, with billing on, sends every Remote plan through a hosted checkout. Approving
+ * a computer is not a purchase, so the machine is written straight as `not_required`: no checkout,
+ * no campaign subscription, no manager reservation (Remote is nodeless, `managerId: ''`).
+ *
+ * `computerId` is normalized by the caller — the reuse lookup below is an
+ * equality match, so a dashed uuid and its de-dashed twin must never both reach this.
+ */
+ async resolveOrCreateForComputer(
+ userId: string,
+ autonomousEnv: AutonomousEnvironment,
+ computerId: string,
+ label: string,
+ claimedMachineId?: string,
+ ): Promise<{ machine: Machine; created: boolean }> {
+ // A caller that still holds a machine id we have DELETED must be told so, never quietly given a
+ // new machine. Deletion is soft, so `machineAlive` below simply does not find the old row — and
+ // without this guard the call falls through to `create` and mints a fresh machineId for the same
+ // (userId, computerId). That is what made deleting a machine do nothing at all whenever its
+ // computer was offline at the time: it reconnected moments later as a brand-new machine and
+ // carried on, credentials intact.
+ //
+ // 403 is deliberate: the harness CLI already maps 403 on the adapter-ws upgrade to `onRevoked`,
+ // which clears its SSO session and stops the daemon. A caller with NO claim (a fresh login, whose
+ // session was cleared by exactly that revocation) is untouched and still pairs normally.
+ if (claimedMachineId && isMachineId(claimedMachineId)) {
+ const claimed = await prisma.machine.findUnique({ where: { machineId: claimedMachineId } })
+ if (claimed && claimed.userId === userId && claimed.deletedAt) {
+ throw new AppError('This machine was removed from the account', 403, 'MACHINE_REVOKED')
+ }
+ }
+ const findExisting = (): Promise<Machine[]> => prisma.machine.findMany({
+ where: { userId, computerId, authMode: 'remote', ...machineAlive },
+ orderBy: { createdAt: 'asc' },
+ })
+ // Avoid Redis on the overwhelmingly common reconnect path. A half-bought row never becomes the
+ // answer — the adapter would only get 402 on connect.
+ const reusable = firstUsableComputerMachine(await findExisting())
+ if (reusable) return { machine: reusable, created: false }
+
+ return withComputerCreateLock(userId, computerId, async () => {
+ // Another backend may have completed this computer's first login while this request waited.
+ const afterLock = firstUsableComputerMachine(await findExisting())
+ if (afterLock) return { machine: afterLock, created: false }
+
+ if (env.HARNESS_DEVICE_AUTH_MACHINE_LIMIT > 0) {
+ // Hygiene, not a security control: this path is free, and the computer id behind it is
+ // self-declared, so a loop of fresh ids would otherwise mint unbounded rows. Rows are cheap
+ // (no container), hence a generous ceiling rather than a tight one.
+ const owned = await prisma.machine.count({
+ where: { userId, authMode: 'remote', billingStatus: 'not_required', ...machineAlive },
+ })
+ if (owned >= env.HARNESS_DEVICE_AUTH_MACHINE_LIMIT) {
+ throw new AppError('Too many connected computers on this account', 409, 'TOO_MANY_MACHINES')
+ }
+ }
+
+ const apiKey = generateApiKey()
+ const machineId = machineIdFromKey(apiKey)
+ // Best-effort: the catalog may have no Remote plan in this plane. planId is optional everywhere —
+ // plansByMachine only reads it for the display name, and authMode is denormalized on the row.
+ const plan = await prisma.subscriptionPlan.findFirst({
+ where: { autonomousEnv, authMode: 'remote' },
+ orderBy: { createdAt: 'asc' },
+ select: { id: true },
+ })
+ const machine = await prisma.machine.create({
+ data: {
+ userId,
+ machineId,
+ apiKey,
+ managerId: '',
+ autonomousEnv,
+ planId: plan?.id ?? null,
+ authMode: 'remote',
+ billingStatus: 'not_required',
+ computerId,
+ // Seeded from the computer's hostname so the card is never a bare id. The owner can rename it;
+ // a later connect only ever refreshes `hostname`, never this.
+ name: label.trim().slice(0, 120) || null,
+ },
+ })
+ await publishDeviceMachineListChanged(userId, { reason: 'created' }).catch(() => { /* best effort */ })
+ logger.info('remote machine created for computer', { userId, machineId, computerId })
+ return { machine, created: true }
+ })
+ },
+
+ /** List a user's agents (with best-effort live status). Includes the api key (owner only). */
+ async listForUser(userId: string, autonomousEnv?: AutonomousEnvironment): Promise<OwnerMachine[]> {
+ const rows = await prisma.machine.findMany({
+ where: { userId, ...(autonomousEnv ? { autonomousEnv } : {}), ...machineAlive },
+ orderBy: { createdAt: 'desc' },
+ })
+ if (rows.length === 0) return []
+ const ids = rows.map((b) => b.machineId)
+ const [info, counts, plans] = await Promise.all([nodeInfoByAgent(rows), countByMachine(ids), plansByMachine(rows)])
+ await applyRemoteStatus(rows, plans, info)
+ return rows.map((b) => {
+ if (billingStatusOf(b) === 'pending') return toOwner(b, 'payment_pending', 0, plans.get(b.machineId), 'claude')
+ const ni = info.get(b.machineId)
+ return toOwner(b, ni?.status ?? 'unknown', counts.get(b.machineId) ?? 0, plans.get(b.machineId), ni?.engine)
+ })
+ },
+
+ /** Fetch one agent (incl. its data-plane apiKey). Owner or admin only. */
+ async get(machineId: string, requester: MachineRequester): Promise<OwnerMachine> {
+ assertMachineId(machineId)
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt) throw new NotFoundError('Machine')
+ if (binding.userId !== requester.sub && requester.role !== 'admin') {
+ throw new ForbiddenError('Not your machine')
+ }
+ assertRequesterEnvironment(binding, requester)
+ return ownerViewForBinding(binding)
+ },
+
+ /** Resolve an Autonomous campaign device id to the caller's machine. This is owner- and
+ * environment-scoped so a deep link can never reveal another account's machine. */
+ async resolveByExternalDeviceId(externalDeviceId: string, requester: MachineRequester): Promise<OwnerMachine> {
+ const binding = await prisma.machine.findFirst({
+ where: {
+ externalDeviceId,
+ userId: requester.sub,
+ ...(requester.autonomousEnv ? { autonomousEnv: requester.autonomousEnv } : {}),
+ ...machineAlive,
+ },
+ orderBy: { createdAt: 'desc' },
+ })
+ if (!binding) throw new NotFoundError('Machine')
+ return ownerViewForBinding(binding)
+ },
+
+ /** Owner-triggered on-demand wake. Remote machines have no Docker node and are rejected. */
+ async start(machineId: string, requester: MachineRequester): Promise<void> {
+ assertMachineId(machineId)
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt) throw new NotFoundError('Machine')
+ if (binding.userId !== requester.sub && requester.role !== 'admin') throw new ForbiddenError('Not your machine')
+ assertRequesterEnvironment(binding, requester)
+ assertMachineBillingActive(binding)
+ if (isNodeless(binding.authMode) || !binding.managerId) throw new AppError('This machine has no node for the backend to start', 400, 'REMOTE_MACHINE')
+ await ensureMachineReady(binding)
+ },
+
+ /** Owner-triggered manual stop. The manager keeps the container and persistent volume intact. */
+ async stop(machineId: string, requester: MachineRequester): Promise<void> {
+ assertMachineId(machineId)
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt) throw new NotFoundError('Machine')
+ if (binding.userId !== requester.sub && requester.role !== 'admin') throw new ForbiddenError('Not your machine')
+ assertRequesterEnvironment(binding, requester)
+ assertMachineBillingActive(binding)
+ if (isNodeless(binding.authMode) || !binding.managerId) throw new AppError('This machine has no node for the backend to stop', 400, 'REMOTE_MACHINE')
+ publishMachineLifecycle(binding.machineId, 'stopping', 'manual_stop')
+ try {
+ await provisionViaManager(binding.managerId, 'stop', { machineId: binding.machineId })
+ // Covers an already-disconnected node where no unregister frame exists to announce the stop.
+ publishMachineLifecycle(binding.machineId, 'stopped', 'manual_stop')
+ } catch (err) {
+ publishMachineLifecycle(binding.machineId, await getAgentPresence(binding.machineId) ? 'running' : 'offline', 'stop_failed')
+ throw err
+ }
+ },
+
+ /** Rename a machine. Owner or admin only. Writes `name` — the display surface shows
+ * `name || machine-<id8>`. `null` clears it back to the default (a remote machine gets its name
+ * re-seeded from the computer's hostname on the adapter's next connect).
+ * Fans the change out to live clients: devices re-snapshot via devmachines, a connected adapter
+ * gets a `machine_meta` down-frame, web tabs re-fetch on the forwarded `machines_changed`. */
+ async rename(machineId: string, requester: MachineRequester, name: string | null): Promise<void> {
+ assertMachineId(machineId)
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt) throw new NotFoundError('Machine')
+ if (binding.userId !== requester.sub && requester.role !== 'admin') {
+ throw new ForbiddenError('Not your machine')
+ }
+ assertRequesterEnvironment(binding, requester)
+ assertMachineBillingActive(binding)
+ await prisma.machine.update({ where: { machineId }, data: { name } })
+ await publishDeviceMachineListChanged(binding.userId, { reason: 'renamed' }).catch(() => { /* best effort */ })
+ if (binding.managerId === '') {
+ // Remote machine: a live adapter mirrors the name locally (`machine status`) — push it the new one.
+ await publishDown(machineId, { connId: '', frame: { type: 'machine_meta', payload: { name } } }).catch(() => { /* best effort */ })
+ }
+ logger.info('machine renamed', { machineId, by: requester.sub, named: !!name })
+ },
+
+ /** Destroy a node. Owner or admin only. The binding row is SOFT-deleted (stamped `deletedAt`,
+ * kept for audit/restore) — every read path treats it as absent — while the physical resources
+ * (container/node row, adapter session, presence) are still torn down for real. */
+ async destroy(machineId: string, requester: MachineRequester, accessToken?: string): Promise<void> {
+ assertMachineId(machineId)
+ const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
+ if (!binding || binding.deletedAt) throw new NotFoundError('Machine')
+ if (binding.userId !== requester.sub && requester.role !== 'admin') {
+ throw new ForbiddenError('Not your machine')
+ }
+ assertRequesterEnvironment(binding, requester)
+ const externallyBilled = hasManagedCampaignBilling(binding) ||
+ (binding.authMode === 'remote' && billingStatusOf(binding) !== 'not_required')
+ if (externallyBilled) {
+ // Campaign devices/subscriptions belong to the owner's SSO account. Never use an admin's
+ // token to cancel another user's billing. Billing cleanup must finish before local deletion.
+ if (binding.userId !== requester.sub) throw new ForbiddenError('Billed machines must be deleted by their owner')
+ if (!accessToken) throw new AppError('SSO access token required to cancel machine billing', 401, 'UNAUTHORIZED')
+ await machineBillingService.deleteCampaignMachine(machineId, binding.userId, accessToken, requester.autonomousEnv)
+ } else {
+ // Non-billed Remote/legacy machines have no upstream subscription. Stamp the record now; the
+ // physical cleanup below remains asynchronous.
+ await prisma.machine.update({ where: { machineId: machineId }, data: { deletedAt: new Date() } }).catch(() => { /* already gone */ })
+ await publishDeviceMachineListChanged(binding.userId, { reason: 'deleted' }).catch(() => { /* best effort */ })
+ }
+
+ if (binding.managerId === '') {
+ // Remote agents have no node/container — just drop presence so the list goes offline immediately.
+ // Also PUSH a machine_revoked down-frame so a LIVE adapter clears its saved token and stops now,
+ // instead of only finding out (as a hard auth failure) on its next reconnect. adapterWs forwards
+ // down-frames to the adapter socket; connId '' = not client-scoped.
+ await publishDown(machineId, { connId: '', frame: { type: 'machine_revoked' } }).catch(() => { /* best effort */ })
+ await clearAgentPresence(machineId).catch(() => { /* best effort */ })
+ } else {
+ // Managed: reap the container + node row in the background (idempotent on the manager → retryable).
+ void destroyNodeWithRetry(machineId, binding.managerId)
+ }
+ logger.info('agent destroyed', { machineId, by: requester.sub, remote: binding.managerId === '', billingCancelled: externallyBilled })
+ },
+}
diff --git a/backend/src/services/UserService.test.ts b/backend/src/services/UserService.test.ts
new file mode 100644
index 000000000..f8aa1089b
--- /dev/null
+++ b/backend/src/services/UserService.test.ts
@@ -0,0 +1,226 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const findUnique = vi.hoisted(() => vi.fn())
+const create = vi.hoisted(() => vi.fn())
+const update = vi.hoisted(() => vi.fn())
+const remove = vi.hoisted(() => vi.fn())
+const updateManyDevices = vi.hoisted(() => vi.fn())
+const transaction = vi.hoisted(() => vi.fn())
+
+vi.mock('../lib/prisma.js', () => ({
+ prisma: {
+ user: { findUnique, create, update, delete: remove },
+ deviceBinding: { updateMany: updateManyDevices },
+ $transaction: transaction,
+ },
+}))
+vi.mock('../config/env.js', () => ({ ADMIN_EMAILS: new Set<string>(['[email protected]']) }))
+vi.mock('../lib/password.js', () => ({ hashPassword: (p: string) => `hashed:${p}` }))
+
+import {
+ isProvisionalUserEmail,
+ normalizeUserEmail,
+ provisionalEmailForExternalId,
+ userService,
+} from './UserService.js'
+
+const row = (over: Record<string, unknown> = {}): Record<string, unknown> => ({
+ id: 'u1',
+ email: '[email protected]',
+ externalId: 'prod-sub-1',
+ stagExternalId: null,
+ name: 'A',
+ role: 'user',
+ autonomousEnv: 'prod',
+ ...over,
+})
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ create.mockImplementation(({ data }: { data: Record<string, unknown> }) => ({ id: 'new', ...data }))
+ update.mockImplementation(({ data }: { data: Record<string, unknown> }) => row(data))
+ remove.mockResolvedValue({})
+ updateManyDevices.mockResolvedValue({ count: 1 })
+ transaction.mockImplementation(async (operations: Array<Promise<unknown>>) => Promise.all(operations))
+})
+
+describe('SSO user identity', () => {
+ it('normalizes email and uses it as the lookup key', async () => {
+ findUnique.mockResolvedValue(row())
+
+ const user = await userService.upsertFromSso({
+ externalId: 'prod-sub-1',
+ email: ' [email protected] ',
+ autonomousEnv: 'prod',
+ })
+
+ expect(findUnique).toHaveBeenCalledWith({ where: { email: '[email protected]' } })
+ expect(update).not.toHaveBeenCalled()
+ expect(user).toMatchObject({ id: 'u1' })
+ })
+
+ it('stores the SSO subject in stagExternalId for staging', async () => {
+ findUnique.mockResolvedValue(row({ autonomousEnv: 'stag' }))
+
+ await userService.upsertFromSso({
+ externalId: 'stag-sub-1',
+ email: '[email protected]',
+ autonomousEnv: 'stag',
+ })
+
+ expect(update).toHaveBeenCalledWith(expect.objectContaining({
+ data: { stagExternalId: 'stag-sub-1' },
+ }))
+ })
+
+ it('claims a prod device provisional row by externalId', async () => {
+ const provisional = row({
+ email: provisionalEmailForExternalId('prod-sub-1'),
+ name: null,
+ })
+ findUnique.mockResolvedValueOnce(null).mockResolvedValueOnce(provisional)
+
+ await userService.upsertFromSso({
+ externalId: 'prod-sub-1',
+ email: '[email protected]',
+ autonomousEnv: 'prod',
+ name: 'Owner',
+ })
+
+ expect(update).toHaveBeenCalledWith(expect.objectContaining({
+ where: { id: 'u1' },
+ data: { email: '[email protected]', name: 'Owner' },
+ }))
+ })
+
+ it('merges a conflicting provisional device row into the email user', async () => {
+ const actual = row({ id: 'real', externalId: 'local-prod-real' })
+ const provisional = row({
+ id: 'pending',
+ email: provisionalEmailForExternalId('prod-sub-1'),
+ })
+ findUnique.mockResolvedValueOnce(actual).mockResolvedValueOnce(provisional)
+
+ await userService.upsertFromSso({
+ externalId: 'prod-sub-1',
+ email: '[email protected]',
+ autonomousEnv: 'prod',
+ })
+
+ expect(updateManyDevices).toHaveBeenCalledWith({
+ where: { userId: 'pending' },
+ data: { userId: 'real' },
+ })
+ expect(remove).toHaveBeenCalledWith({ where: { id: 'pending' } })
+ expect(update).toHaveBeenCalledWith(expect.objectContaining({
+ where: { id: 'real' },
+ data: { externalId: 'prod-sub-1' },
+ }))
+ })
+
+ it('promotes to admin from the ADMIN_EMAILS allowlist', async () => {
+ findUnique.mockResolvedValue(row({ email: '[email protected]' }))
+
+ await userService.upsertFromSso({
+ externalId: 'prod-sub-1',
+ email: '[email protected]',
+ autonomousEnv: 'prod',
+ })
+
+ expect(update).toHaveBeenCalledWith(expect.objectContaining({ data: { role: 'admin' } }))
+ })
+
+ it('creates a staging user with a local prod placeholder', async () => {
+ findUnique.mockResolvedValue(null)
+
+ const user = await userService.upsertFromSso({
+ externalId: 'stag-sub-1',
+ email: '[email protected]',
+ autonomousEnv: 'stag',
+ })
+
+ expect(user).toMatchObject({
+ email: '[email protected]',
+ stagExternalId: 'stag-sub-1',
+ autonomousEnv: 'stag',
+ })
+ expect(String((user as Record<string, unknown>).externalId)).toMatch(/^local-prod-[0-9a-f-]{36}$/)
+ })
+
+ it('does not adopt a prod subject already owned by another real email', async () => {
+ const other = row({ id: 'other', email: '[email protected]' })
+ findUnique
+ .mockResolvedValueOnce(null)
+ .mockResolvedValueOnce(other)
+ .mockResolvedValueOnce(null)
+ .mockResolvedValueOnce(other)
+ create.mockRejectedValueOnce(Object.assign(new Error('Unique constraint failed'), { code: 'P2002' }))
+
+ await expect(userService.upsertFromSso({
+ externalId: 'prod-sub-1',
+ email: '[email protected]',
+ autonomousEnv: 'prod',
+ })).rejects.toThrow(/assigned to another email/i)
+ })
+})
+
+describe('provisional identity helpers', () => {
+ it('builds a deterministic non-deliverable email', () => {
+ expect(provisionalEmailForExternalId('ABC123')).toBe('[email protected]')
+ expect(isProvisionalUserEmail('[email protected]')).toBe(true)
+ expect(isProvisionalUserEmail('[email protected]')).toBe(false)
+ expect(normalizeUserEmail(' [email protected] ')).toBe('[email protected]')
+ })
+
+ it('creates one prod provisional identity and returns the race winner', async () => {
+ findUnique.mockResolvedValueOnce(null)
+ create.mockResolvedValueOnce(row({
+ id: 'pending',
+ email: provisionalEmailForExternalId('prod-sub-1'),
+ }))
+
+ await expect(userService.findOrCreateProdProvisional('prod-sub-1')).resolves.toMatchObject({
+ id: 'pending',
+ email: provisionalEmailForExternalId('prod-sub-1'),
+ })
+ })
+})
+
+describe('campaign device identity', () => {
+ it('creates an email-keyed prod user before the first SSO login', async () => {
+ findUnique.mockResolvedValue(null)
+
+ await userService.findOrCreateProdDeviceOwner('prod-sub-1', ' [email protected] ')
+
+ expect(findUnique).toHaveBeenCalledWith({ where: { email: '[email protected]' } })
+ expect(create).toHaveBeenCalledWith({
+ data: {
+ email: '[email protected]',
+ externalId: 'prod-sub-1',
+ name: undefined,
+ role: 'user',
+ autonomousEnv: 'prod',
+ },
+ })
+ })
+})
+
+describe('create — locally-created accounts', () => {
+ it('uses normalized unique email and a namespaced prod externalId', async () => {
+ findUnique.mockResolvedValue(null)
+
+ await userService.create({ email: ' [email protected] ', password: 'pw' })
+
+ const data = create.mock.calls[0][0].data as Record<string, unknown>
+ expect(String(data.externalId)).toMatch(/^local-[0-9a-f-]{36}$/)
+ expect(data.email).toBe('[email protected]')
+ expect(data.passwordHash).toBe('hashed:pw')
+ })
+
+ it('rejects an existing email through the unique lookup', async () => {
+ findUnique.mockResolvedValue(row())
+
+ await expect(userService.create({ email: '[email protected]', password: 'pw' })).rejects.toThrow(/already exists/i)
+ expect(findUnique).toHaveBeenCalledWith({ where: { email: '[email protected]' } })
+ })
+})
diff --git a/backend/src/services/UserService.ts b/backend/src/services/UserService.ts
new file mode 100644
index 000000000..d0c166cec
--- /dev/null
+++ b/backend/src/services/UserService.ts
@@ -0,0 +1,219 @@
+import type { User } from '@prisma/client'
+import { randomUUID } from 'crypto'
+import { prisma } from '../lib/prisma.js'
+import { ADMIN_EMAILS } from '../config/env.js'
+import { hashPassword } from '../lib/password.js'
+import { ConflictError, NotFoundError } from '../errors/index.js'
+import type { AutonomousEnvironment } from '../lib/autonomousEnvironment.js'
+
+export type PublicUser = Omit<User, 'passwordHash'>
+
+function toPublic(u: User): PublicUser {
+ const { passwordHash: _omit, ...rest } = u
+ return rest
+}
+
+function roleForEmail(email: string): string {
+ return ADMIN_EMAILS.has(email.toLowerCase()) ? 'admin' : 'user'
+}
+
+const PROVISIONAL_EMAIL_DOMAIN = 'pending.harness.invalid'
+
+export function normalizeUserEmail(email: string): string {
+ return email.trim().toLowerCase()
+}
+
+export function provisionalEmailForExternalId(externalId: string): string {
+ return `device-${externalId.trim().toLowerCase()}@${PROVISIONAL_EMAIL_DOMAIN}`
+}
+
+export function isProvisionalUserEmail(email: string): boolean {
+ return normalizeUserEmail(email).endsWith(`@${PROVISIONAL_EMAIL_DOMAIN}`)
+}
+
+interface SsoUserInput {
+ externalId: string
+ email: string
+ autonomousEnv: AutonomousEnvironment
+ name?: string
+ roles?: string[]
+}
+
+async function mergeProdProvisionalUser(provisional: User, user: User): Promise<void> {
+ if (provisional.id === user.id) return
+ if (!isProvisionalUserEmail(provisional.email)) {
+ throw new Error('Production SSO subject is already assigned to another user')
+ }
+ await prisma.$transaction([
+ prisma.deviceBinding.updateMany({
+ where: { userId: provisional.id },
+ data: { userId: user.id },
+ }),
+ prisma.user.delete({ where: { id: provisional.id } }),
+ ])
+}
+
+export const userService = {
+ toPublic,
+
+ /** Production subject lookup used by the prod-only SDS device plane. */
+ findByExternal(externalId: string): Promise<User | null> {
+ return prisma.user.findUnique({ where: { externalId } })
+ },
+
+ /** SSO identity lookup. All callers must normalize through this boundary. */
+ findByEmail(email: string): Promise<User | null> {
+ return prisma.user.findUnique({ where: { email: normalizeUserEmail(email) } })
+ },
+
+ /**
+ * Mirror an authenticated SSO profile. Email is the account identity; the selected environment
+ * decides which SSO subject field is refreshed. Production additionally claims a device-created
+ * provisional row whose externalId already equals the authenticated subject.
+ */
+ async upsertFromSso(input: SsoUserInput): Promise<User> {
+ const externalId = input.externalId.trim()
+ const em = normalizeUserEmail(input.email)
+ if (!externalId || !em) throw new Error('SSO profile is missing its subject or email')
+ const wantAdmin = input.roles?.includes('admin') || ADMIN_EMAILS.has(em)
+ let existing = await prisma.user.findUnique({ where: { email: em } })
+
+ if (!existing && input.autonomousEnv === 'prod') {
+ const byExternal = await prisma.user.findUnique({ where: { externalId } })
+ if (byExternal && isProvisionalUserEmail(byExternal.email)) existing = byExternal
+ }
+
+ if (existing) {
+ if (input.autonomousEnv === 'prod' && existing.externalId !== externalId) {
+ const currentOwner = await prisma.user.findUnique({ where: { externalId } })
+ if (currentOwner && currentOwner.id !== existing.id) {
+ await mergeProdProvisionalUser(currentOwner, existing)
+ }
+ }
+ const role = existing.role === 'admin' || wantAdmin ? 'admin' : 'user'
+ const data = {
+ ...(existing.email !== em ? { email: em } : {}),
+ ...(input.name && existing.name !== input.name ? { name: input.name } : {}),
+ ...(existing.role !== role ? { role } : {}),
+ ...(input.autonomousEnv === 'prod' && existing.externalId !== externalId ? { externalId } : {}),
+ ...(input.autonomousEnv === 'stag' && existing.stagExternalId !== externalId
+ ? { stagExternalId: externalId }
+ : {}),
+ }
+ // SSO profile auth runs on every control-plane request. Avoid turning that validation into a
+ // write-per-request DB hot path when the mirrored user record is already current.
+ if (Object.keys(data).length === 0) return existing
+ return prisma.user.update({
+ where: { id: existing.id },
+ data,
+ })
+ }
+
+ const data = {
+ email: em,
+ externalId: input.autonomousEnv === 'prod' ? externalId : `local-prod-${randomUUID()}`,
+ ...(input.autonomousEnv === 'stag' ? { stagExternalId: externalId } : {}),
+ name: input.name,
+ role: wantAdmin ? 'admin' : 'user',
+ autonomousEnv: input.autonomousEnv,
+ }
+ try {
+ return await prisma.user.create({ data })
+ } catch (err) {
+ // REST and web-ws validate the same fresh token concurrently. Unique email/prod-subject indexes
+ // elect one creator; the loser re-reads and applies the same idempotent mirror update.
+ const racedByEmail = await prisma.user.findUnique({ where: { email: em } })
+ if (racedByEmail) return this.upsertFromSso(input)
+ if (input.autonomousEnv === 'prod') {
+ const racedByExternal = await prisma.user.findUnique({ where: { externalId } })
+ if (racedByExternal && isProvisionalUserEmail(racedByExternal.email)) {
+ return this.upsertFromSso(input)
+ }
+ if (racedByExternal) {
+ throw new Error('Production SSO subject is already assigned to another email')
+ }
+ }
+ throw err
+ }
+ },
+
+ /**
+ * Resolve the authoritative identity pair returned by the campaign device API before the owner has
+ * necessarily signed in to Machine. Reuse the same email-keyed merge path as production SSO so a later
+ * sign-in claims this exact row instead of creating a second user.
+ */
+ async findOrCreateProdDeviceOwner(externalId: string, email: string): Promise<User> {
+ return this.upsertFromSso({
+ externalId,
+ email,
+ autonomousEnv: 'prod',
+ })
+ },
+
+ /** Prod-only device ownership: create a claimable user before its first SSO login. */
+ async findOrCreateProdProvisional(externalId: string): Promise<User> {
+ const subject = externalId.trim()
+ const existing = await prisma.user.findUnique({ where: { externalId: subject } })
+ if (existing) return existing
+ try {
+ return await prisma.user.create({
+ data: {
+ externalId: subject,
+ email: provisionalEmailForExternalId(subject),
+ role: 'user',
+ autonomousEnv: 'prod',
+ },
+ })
+ } catch (err) {
+ const raced = await prisma.user.findUnique({ where: { externalId: subject } })
+ if (raced) return raced
+ throw err
+ }
+ },
+
+ get(id: string): Promise<User | null> {
+ return prisma.user.findUnique({ where: { id } })
+ },
+
+ list(): Promise<User[]> {
+ return prisma.user.findMany({ orderBy: { createdAt: 'desc' } })
+ },
+
+ async create(input: { email: string; password: string; name?: string; role?: string; autonomousEnv?: AutonomousEnvironment }): Promise<User> {
+ const email = normalizeUserEmail(input.email)
+ if (await prisma.user.findUnique({ where: { email } })) {
+ throw new ConflictError('Email already exists')
+ }
+ return prisma.user.create({
+ data: {
+ // Locally-created (non-SSO) accounts still need the identity key. Mint a namespaced one so it
+ // can never collide with an Autonomous SSO subject, and so two of them can coexist (a MISSING
+ // field would collide on Mongo's unique index — absent counts as a value there).
+ externalId: `local-${randomUUID()}`,
+ email,
+ passwordHash: hashPassword(input.password),
+ name: input.name,
+ role: input.role ?? roleForEmail(email),
+ autonomousEnv: input.autonomousEnv ?? 'prod',
+ },
+ })
+ },
+
+ async update(id: string, input: { name?: string; password?: string; role?: string; autonomousEnv?: AutonomousEnvironment }): Promise<User> {
+ if (!(await prisma.user.findUnique({ where: { id } }))) throw new NotFoundError('User')
+ return prisma.user.update({
+ where: { id },
+ data: {
+ ...(input.name !== undefined ? { name: input.name } : {}),
+ ...(input.role !== undefined ? { role: input.role } : {}),
+ ...(input.autonomousEnv !== undefined ? { autonomousEnv: input.autonomousEnv } : {}),
+ ...(input.password ? { passwordHash: hashPassword(input.password) } : {}),
+ },
+ })
+ },
+
+ async remove(id: string): Promise<void> {
+ if (!(await prisma.user.findUnique({ where: { id } }))) throw new NotFoundError('User')
+ await prisma.user.delete({ where: { id } })
+ },
+}
diff --git a/backend/src/services/index.ts b/backend/src/services/index.ts
new file mode 100644
index 000000000..40c73a4ba
--- /dev/null
+++ b/backend/src/services/index.ts
@@ -0,0 +1,5 @@
+export * from './UserService.js'
+export * from './MachineService.js'
+export * from './DeviceService.js'
+export * from './MachineBillingService.js'
+export * from './MachineBillingWorkerService.js'
diff --git a/backend/src/types/analytics.ts b/backend/src/types/analytics.ts
new file mode 100644
index 000000000..feb1bf0c4
--- /dev/null
+++ b/backend/src/types/analytics.ts
@@ -0,0 +1,163 @@
+/**
+ * Harness Analytics — the canonical, versioned contract.
+ *
+ * This file is the shared vocabulary between every collector (remote CLI, machine-node, provider)
+ * and the backend ingest. It is duplicated verbatim in `apps/machine-node/api/src/types/analytics.ts`
+ * and in `autonomous-harness/cli` — there is no shared package in this monorepo, so the copies are
+ * kept in sync by the conformance tests, not by the module system.
+ *
+ * Design: docs/design/harness-analytics.md
+ *
+ * The one rule that shapes everything here: ADDITIVE counters and NON-ADDITIVE metrics travel in
+ * different shapes. `DailyBucket` may be split by engine/mode/origin and re-summed; `MachineDay`
+ * may not, so it exists once per (machine, day) and is computed locally where every interval is
+ * visible.
+ */
+
+export const ANALYTICS_SCHEMA_VERSION = 1
+
+export const ENGINES = [
+ 'claude', 'codex', 'cursor', 'opencode', 'pi', 'hermes',
+ 'commandcode', 'devin', 'muse', 'amp', 'kilo', 'grok', 'agy', 'copilot',
+] as const
+export type Engine = (typeof ENGINES)[number]
+
+export const MODES = ['self', 'managed', 'remote', 'provider'] as const
+export type Mode = (typeof MODES)[number]
+
+export const ORIGINS = ['human', 'scheduled', 'system', 'api'] as const
+export type Origin = (typeof ORIGINS)[number]
+
+export const TURN_OUTCOMES = ['completed', 'failed', 'cancelled', 'input_required'] as const
+export type TurnOutcome = (typeof TURN_OUTCOMES)[number]
+
+/**
+ * Collection is ON by default and can be turned off; there is no pending state.
+ *
+ * An earlier design held every upload until the account owner had acknowledged a field list. That
+ * gate was removed deliberately: it put a full-page interstitial in front of the dashboard, and the
+ * disclosure now lives as a non-blocking panel instead.
+ */
+export const CONSENT_STATES = ['on', 'off'] as const
+export type ConsentState = (typeof CONSENT_STATES)[number]
+
+/**
+ * Canonical activity events, emitted at the normalization boundary — before E2EE sealing on the
+ * remote CLI, because the relay cannot tell a real instruction from a duplicated control frame.
+ *
+ * `agentId` NEVER leaves the machine. It is present so the local reducer can compute a distinct
+ * active-agent count; only the resulting integer is uploaded.
+ */
+export type AnalyticsEventV1 =
+ | { type: 'instruction'; eventId: string; at: string; engine: Engine; origin: Origin }
+ | { type: 'turn_started'; turnId: string; at: string; engine: Engine; origin: Origin; agentId: string }
+ | { type: 'turn_finished'; turnId: string; at: string; outcome: TurnOutcome }
+
+/** ADDITIVE counters for one (day, engine, mode, origin). Safe to sum along any dimension. */
+export interface DailyBucketPayload {
+ engine: Engine
+ mode: Mode
+ origin: Origin
+ instructions: number
+ turnsStarted: number
+ turnsCompleted: number
+ turnsFailed: number
+ turnsCancelled: number
+ turnsInputNeeded: number
+ /** Sum of terminal turn durations. Concurrent agents overlap here by design. */
+ agentRuntimeMs: number
+}
+
+/**
+ * NON-ADDITIVE metrics for one (machine, day), plus the reporting heartbeat.
+ *
+ * Emitted for EVERY day the collector was alive, including an all-zero day: that is what lets the
+ * dashboard tell "up and idle" from "no data". A missing day is missing information, never zero.
+ */
+export interface MachineDayPayload {
+ /** Union of turn intervals — computed here, where the whole set is visible, and never split. */
+ wallClockActiveMs: number
+ /** Distinct agents with at least one accepted human instruction. */
+ activeAgents: number
+ /** Denominator for utilization. 0 when not meaningful (provider mode has no container). */
+ uptimeMs: number
+ reported: boolean
+}
+
+export interface DailyReportPayload {
+ /** Midnight UTC of the day, ISO-8601 (`2026-08-11` or a full timestamp). */
+ dayUtc: string
+ machineDay: MachineDayPayload
+ buckets: DailyBucketPayload[]
+}
+
+export interface CollectorInfo {
+ version: string
+ /** Engines this collector actually instruments. */
+ engineCoverage: Engine[]
+ /**
+ * Engines the collector can SEE on this machine (registered agents, discovered binaries).
+ *
+ * Coverage alone cannot answer "is anything being missed": an engine absent from `engineCoverage`
+ * is either uninstrumented or simply not installed, and reporting every engine the product knows
+ * about as "not instrumented" would be noise on every machine. The difference
+ * `enginesPresent - engineCoverage` is the honest set, and it is the only one the UI shows.
+ */
+ enginesPresent: Engine[]
+}
+
+/** Request body of `POST /api/analytics/report`. */
+export interface AnalyticsReportRequest {
+ schemaVersion: number
+ /** Account deletion epoch the collector last saw. An older epoch is refused. */
+ epoch: number
+ /** Client monotonic stamp; the server clamps it against its own clock. */
+ generatedAt: string
+ collector: CollectorInfo
+ days: DailyReportPayload[]
+}
+
+/**
+ * Response of `POST /api/analytics/report`. This doubles as the control channel: it is the only way
+ * a headless collector learns that the owner turned collection off or deleted the history.
+ */
+export interface AnalyticsReportResponse {
+ consent: ConsentState
+ epoch: number
+ serverTime: string
+ accepted: number
+ quarantined: number
+}
+
+/**
+ * How far a client stamp may sit from the server clock before its records are quarantined rather
+ * than stored. A machine whose clock is years off would otherwise write into a bucket far outside
+ * the range and take over every chart.
+ */
+export const CLOCK_SKEW_TOLERANCE_MS = 48 * 60 * 60 * 1000
+
+/** Days accepted in one report. A backlog flush after a long offline period needs several. */
+export const MAX_DAYS_PER_REPORT = 120
+
+/** Central retention for daily records: 13 months, so year-over-year views have a comparison. */
+export const RETENTION_DAYS = 396
+
+/** Buckets accepted for one day: 12 engines x 4 modes x 4 origins, with headroom. */
+export const MAX_BUCKETS_PER_DAY = 240
+
+/** Below this many terminal turns, a completion rate is suppressed instead of shown. */
+export const MIN_SAMPLE_FOR_RATE = 30
+
+/** Days of history required before an anomaly baseline is meaningful. */
+export const MIN_DAYS_FOR_BASELINE = 14
+
+/** Midnight UTC of the day containing `at`. The single definition of a day, used on both sides. */
+export function utcDayStart(at: Date | string): Date {
+ const d = typeof at === 'string' ? new Date(at) : at
+ return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))
+}
+
+/** `2026-08-11` — the wire form of a day key. */
+export function utcDayKey(at: Date | string): string {
+ return utcDayStart(at).toISOString().slice(0, 10)
+}
diff --git a/backend/src/types/index.ts b/backend/src/types/index.ts
new file mode 100644
index 000000000..8a3b070de
--- /dev/null
+++ b/backend/src/types/index.ts
@@ -0,0 +1,14 @@
+import type { AuthUser } from '../lib/ssoAuth.js'
+
+export interface ApiResponse<T> {
+ success: boolean
+ data?: T
+ error?: { code: string; message: string }
+}
+
+// The internal identity resolved from the SSO access token by the auth middleware.
+declare module 'fastify' {
+ interface FastifyRequest {
+ user?: AuthUser
+ }
+}
diff --git a/backend/src/utils/crypto.ts b/backend/src/utils/crypto.ts
new file mode 100644
index 000000000..0887c5a30
--- /dev/null
+++ b/backend/src/utils/crypto.ts
@@ -0,0 +1,49 @@
+import { createHash, randomBytes, randomInt } from 'crypto'
+import type { IncomingMessage } from 'http'
+
+/** The agent api-key from an HTTP header (`x-api-key`) or the first WS subprotocol token. */
+export function extractKey(req: IncomingMessage): string | undefined {
+ const header = req.headers['x-api-key']
+ if (typeof header === 'string' && header) return header
+ const proto = req.headers['sec-websocket-protocol']
+ if (typeof proto === 'string' && proto) return proto.split(',')[0]?.trim()
+ return undefined
+}
+
+/** A fresh per-agent api key: 32 random bytes, hex (64 chars, ≥16 required by the manager). */
+export function generateApiKey(): string {
+ return randomBytes(32).toString('hex')
+}
+
+/** sha256(value) as hex — deterministic lookup hash for high-entropy secrets (device tokens/codes). */
+export function sha256hex(value: string): string {
+ return createHash('sha256').update(value).digest('hex')
+}
+
+/** A short human pairing code from an unambiguous alphabet (no 0/O/1/I/L). Default 6 chars. */
+export function generateUserCode(len = 6): string {
+ const alphabet = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'
+ let out = ''
+ for (let i = 0; i < len; i++) out += alphabet[randomInt(alphabet.length)]
+ return out
+}
+
+/**
+ * A random DNS-safe subdomain label: first char a letter, rest lowercase alnum. Default 12 chars.
+ * The user never picks a subdomain — the backend generates one at register (collision-retried).
+ */
+export function generateSubdomain(len = 12): string {
+ const letters = 'abcdefghijklmnopqrstuvwxyz'
+ const alnum = 'abcdefghijklmnopqrstuvwxyz0123456789'
+ let out = letters[randomInt(letters.length)]
+ for (let i = 1; i < len; i++) out += alnum[randomInt(alnum.length)]
+ return out
+}
+
+/**
+ * machineId = sha256(apiKey)[:32] — IDENTICAL to the agent-manager's derivation
+ * (`utils/crypto.ts`), so the id the backend stores matches the manager's record.
+ */
+export function machineIdFromKey(key: string): string {
+ return createHash('sha256').update(key).digest('hex').slice(0, 32)
+}
diff --git a/backend/src/utils/logger.ts b/backend/src/utils/logger.ts
new file mode 100644
index 000000000..3e83f2bfd
--- /dev/null
+++ b/backend/src/utils/logger.ts
@@ -0,0 +1,44 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+interface LogContext {
+ [key: string]: unknown
+}
+
+class Logger {
+ private isDevelopment = process.env.NODE_ENV === 'development'
+
+ private formatMessage(level: LogLevel, message: string, context?: LogContext): string {
+ const timestamp = new Date().toISOString()
+ const contextStr = context ? ` ${JSON.stringify(context)}` : ''
+ return `[${timestamp}] [${level.toUpperCase()}] ${message}${contextStr}`
+ }
+
+ debug(message: string, context?: LogContext): void {
+ if (this.isDevelopment) console.debug(this.formatMessage('debug', message, context))
+ }
+
+ info(message: string, context?: LogContext): void {
+ console.log(this.formatMessage('info', message, context))
+ }
+
+ warn(message: string, context?: LogContext): void {
+ console.warn(this.formatMessage('warn', message, context))
+ }
+
+ error(message: string, error?: Error | unknown, context?: LogContext): void {
+ let errorContext: LogContext
+ if (error instanceof Error) {
+ errorContext = { ...context, error: error.message, stack: this.isDevelopment ? error.stack : undefined }
+ } else if (error && typeof error === 'object') {
+ const errorObj = error as Record<string, unknown>
+ errorContext = { ...context, error: errorObj.message || errorObj.code || JSON.stringify(error) }
+ } else if (error !== undefined) {
+ errorContext = { ...context, error: String(error) }
+ } else {
+ errorContext = { ...context }
+ }
+ console.error(this.formatMessage('error', message, errorContext))
+ }
+}
+
+export const logger = new Logger()
diff --git a/backend/src/utils/response.ts b/backend/src/utils/response.ts
new file mode 100644
index 000000000..790ad4ad9
--- /dev/null
+++ b/backend/src/utils/response.ts
@@ -0,0 +1,16 @@
+import type { FastifyReply } from 'fastify'
+import type { ApiResponse } from '../types/index.js'
+
+export function sendSuccess<T>(reply: FastifyReply, data: T, statusCode = 200): void {
+ const response: ApiResponse<T> = { success: true, data }
+ reply.code(statusCode).send(response)
+}
+
+export function sendError(reply: FastifyReply, message: string, code: string, statusCode = 500): void {
+ const response: ApiResponse<null> = { success: false, error: { code, message } }
+ reply.code(statusCode).send(response)
+}
+
+export function sendCreated<T>(reply: FastifyReply, data: T): void {
+ sendSuccess(reply, data, 201)
+}
diff --git a/backend/src/utils/slug.ts b/backend/src/utils/slug.ts
new file mode 100644
index 000000000..5cc6665d4
--- /dev/null
+++ b/backend/src/utils/slug.ts
@@ -0,0 +1,14 @@
+import { ValidationError } from '../errors/index.js'
+
+const AGENT_ID_RE = /^[a-f0-9]{32}$/
+
+export function isMachineId(value: string): boolean {
+ return AGENT_ID_RE.test(value)
+}
+
+/** Guard before an machineId is interpolated into a manager URL path. */
+export function assertMachineId(value: string): void {
+ if (!isMachineId(value)) {
+ throw new ValidationError(`Invalid machineId: ${value}`)
+ }
+}
diff --git a/backend/src/worker.ts b/backend/src/worker.ts
new file mode 100644
index 000000000..ef7926b5a
--- /dev/null
+++ b/backend/src/worker.ts
@@ -0,0 +1,55 @@
+import 'dotenv/config'
+import { closeBus } from './lib/bus.js'
+import { backfillMachineFreeEntitlements } from './lib/db/freeEntitlement.js'
+import {
+ backfillMachineAuthMode,
+ ensureSchema,
+ migrateAutonomousEnvironment,
+ migrateMachineRename,
+ migrateUserIdentityByEmail,
+ pruneLegacyDeviceBindings,
+} from './lib/db/migrate.js'
+import { ensurePlans } from './lib/db/seed.js'
+import { prisma } from './lib/prisma.js'
+import { machineBillingWorkerService } from './services/MachineBillingWorkerService.js'
+import { logger } from './utils/logger.js'
+
+// Singleton background process. HTTP/WS server.ts runs as a PM2 cluster and must never own schema
+// writes, catalog syncs, migrations or periodic jobs; otherwise every live server worker races them.
+async function start(): Promise<void> {
+ // Existing production data was created against staging upstreams. Stamp it before Prisma swaps
+ // the old global unique indexes for their per-environment replacements.
+ await migrateAutonomousEnvironment()
+ await migrateUserIdentityByEmail()
+ ensureSchema()
+ // AFTER the push: it creates the new collections + their unique indexes, and the copy uses $merge
+ // so those indexes survive. Copying first would leave the unique index build to fail silently.
+ await migrateMachineRename()
+ // The copy can materialize rows from a collection the first pass never saw — stamp those too.
+ await migrateAutonomousEnvironment()
+ await ensurePlans()
+ await backfillMachineAuthMode()
+ await pruneLegacyDeviceBindings()
+ await backfillMachineFreeEntitlements()
+
+ const shutdown = (signal: string): void => {
+ logger.info(`Received ${signal}, stopping backend worker...`)
+ const hardExit = setTimeout(() => process.exit(0), 5000)
+ hardExit.unref()
+ machineBillingWorkerService.stop()
+ void Promise.allSettled([prisma.$disconnect(), closeBus()]).finally(() => process.exit(0))
+ }
+ process.on('SIGINT', () => shutdown('SIGINT'))
+ process.on('SIGTERM', () => shutdown('SIGTERM'))
+
+ machineBillingWorkerService.start()
+ // PM2 wait_ready gates the singleton worker's "online" state on schema/catalog/backfill startup.
+ // Plain node/tsx runs do not provide process.send and simply continue.
+ process.send?.('ready')
+ logger.info('backend worker started')
+}
+
+start().catch((err) => {
+ logger.error('Failed to start backend worker', err)
+ process.exit(1)
+})
diff --git a/backend/tsconfig.json b/backend/tsconfig.json
new file mode 100644
index 000000000..b15391f19
--- /dev/null
+++ b/backend/tsconfig.json
@@ -0,0 +1,18 @@
+{
+ "compilerOptions": {
+ "target": "ES2023",
+ "lib": ["ES2023"],
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "esModuleInterop": true,
+ "strict": true,
+ "skipLibCheck": true,
+ "outDir": "dist",
+ "rootDir": "src",
+ "declaration": true,
+ "incremental": true,
+ "tsBuildInfoFile": ".tsbuildinfo"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist", ".tsbuildinfo"]
+}
diff --git a/backend/vitest.config.ts b/backend/vitest.config.ts
new file mode 100644
index 000000000..9e7951b2d
--- /dev/null
+++ b/backend/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+ test: {
+ include: ['src/**/*.test.ts'],
+ exclude: ['dist/**', 'node_modules/**'],
+ },
+})
diff --git a/cli/scripts/release-cli.sh b/cli/scripts/release-cli.sh
index f71651cf4..1fd300a36 100755
--- a/cli/scripts/release-cli.sh
+++ b/cli/scripts/release-cli.sh
@@ -1,7 +1,9 @@
#!/usr/bin/env bash
# Cut a CLI release: work out the next version, tag it, push the tag. CI does everything else —
# .github/workflows/release.yml bundles the CLI, publishes it to GCS, and creates the GitHub Release.
-# The tag IS the version; CI never bumps on its own.
+# The tag IS the version; CI never bumps on its own. Tags are "vX.Y.Z_cli" — the "_cli" suffix is
+# stripped by release.yml before anything treats it as a version; it exists only so this tag never
+# also triggers the backend's "vX.Y.Z_api" release (.github/workflows/production-be-build.yaml).
#
# Usage:
# bash cli/scripts/release-cli.sh # bump the patch and release
@@ -104,12 +106,15 @@ fi
# --- current version, source 1: the highest release tag in git ---
# The brace group keeps `set -e` from killing the script when grep legitimately matches nothing.
-TAG_VER="$(git tag -l 'v*' \
- | { grep -E '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$' || true; } \
- | sed -E 's/^v//' \
+# Tags are "vX.Y.Z_cli" — the suffix only exists so release.yml's tag trigger never collides with
+# the backend's "vX.Y.Z_api" tags now that both live in one repo. Strip "v" and "_cli" so TAG_VER
+# is always a bare X.Y.Z for the version-comparison logic below.
+TAG_VER="$(git tag -l 'v*_cli' \
+ | { grep -E '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)_cli$' || true; } \
+ | sed -E 's/^v//; s/_cli$//' \
| sort -V | tail -1)"
LAST_TAG=""
-[ -z "$TAG_VER" ] || LAST_TAG="v${TAG_VER}"
+[ -z "$TAG_VER" ] || LAST_TAG="v${TAG_VER}_cli"
TAG_VER="${TAG_VER:-0.0.0}"
# --- current version, source 2: the version actually being served ---
@@ -158,7 +163,7 @@ if [[ ! "$VER" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
exit 1
fi
-TAG="v${VER}"
+TAG="v${VER}_cli"
# The last gate against a release no daemon can install.
if ! version_gt "$VER" "$GCS_VER"; then
diff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.ts
index 464e7ac8d..b7730ab08 100644
--- a/cli/src/lib/remoteRelay.ts
+++ b/cli/src/lib/remoteRelay.ts
@@ -145,7 +145,7 @@ function p2pPolicy(value: unknown): TerminalP2pPolicy | null {
// (buildResponderEntry in terminalP2p.ts) caps at 10 — since the offer only ever carries what THIS
// cap let through, half of whatever the backend configured was silently dropped before an offer was
// ever built, and the responder's higher ceiling was unreachable in practice. Kept in step with that
- // one and with the backend's own default list length (autonomous-harness-backend/src/config/env.ts).
+ // one and with the backend's own default list length (backend/src/config/env.ts).
const stunUrls = Array.isArray(raw.stunUrls)
? raw.stunUrls.filter((url): url is string => typeof url === 'string' && /^stuns?:/i.test(url)).slice(0, 10)
: []