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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.yamlnew file mode 100644index 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.ymlindex 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: Releaseon: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 1fimeta="${INPUT_METADATA_PATH:-harness/cli/metadata.json}"diff --git a/backend/.dockerignore b/backend/.dockerignorenew file mode 100644index 000000000..08240eddf--- /dev/null+++ b/backend/.dockerignore@@ -0,0 +1,7 @@+**/node_modules+**/dist+**/.git+**/.env+**/.env.*+**/*.log+**/.tsbuildinfodiff --git a/backend/.env.example b/backend/.env.examplenew file mode 100644index 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/.gitignorenew file mode 100644index 000000000..0d7af1a82--- /dev/null+++ b/backend/.gitignore@@ -0,0 +1,4 @@+node_modules+dist+.tsbuildinfo+.envdiff --git a/backend/Dockerfile b/backend/Dockerfilenew file mode 100644index 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.k8snew file mode 100644index 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.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.ymlnew file mode 100644index 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-stoppeddiff --git a/backend/ecosystem.config.cjs b/backend/ecosystem.config.cjsnew file mode 100644index 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.dockernew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.prismanew file mode 100644index 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.mjsnew file mode 100755index 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.mjsnew file mode 100644index 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.shnew file mode 100755index 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.mjsnew file mode 100755index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 * 1024diff --git a/backend/src/lib/provider/events.test.ts b/backend/src/lib/provider/events.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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 = 20diff --git a/backend/src/lib/provider/history.ts b/backend/src/lib/provider/history.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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,+ '[email protected]',+ '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,+ '[email protected]',+ '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,+ '[email protected]',+ '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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.shindex 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]+$ ]]; thenexit 1fi-TAG="v${VER}"+TAG="v${VER}_cli"# The last gate against a release no daemon can install.if ! version_gt "$VER" "$GCS_VER"; thendiff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.tsindex 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): []