The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Standalone mode for `npx @truefoundry/utils` (#47)
Chirag Jain2946f690bd58
diff --git a/.github/workflows/generate-sdk.yaml b/.github/workflows/generate-sdk.yamlindex 3b6719869..f3b1eef79 100644--- a/.github/workflows/generate-sdk.yaml+++ b/.github/workflows/generate-sdk.yaml@@ -62,7 +62,7 @@ jobs:run: pnpm --filter @truefoundry/utils-core build- name: Write OpenAPI document- run: pnpm --filter @truefoundry/server openapi:write+ run: pnpm --filter @truefoundry/utils openapi:write# Generation and its Docker pull are the slow part, so skip everything below# when neither the document nor the generator config moved.diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex a37a53019..da8598f72 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -21,15 +21,17 @@ jobs:registry-url: https://registry.npmjs.org# OIDC trusted publishing requires npm >= 11.5.1; node 22 bundles npm 10.x.+ # npm 11 also refuses prerelease publishes without an explicit --tag.- run: npm install -g npm@latest- run: pnpm install --frozen-lockfile- run: pnpm build- run: pnpm test- # Guard: tag must match package.json version.- # npm publishes what's in package.json, not the tag name.- - name: Verify tag matches package version+ # Guard: git tag must match @truefoundry/utils-core (library is the version authority).+ # npm publishes what's in package.json, not the tag name. @truefoundry/utils may+ # use an independent version; bump it in the same release PR when the app changes.+ - name: Verify tag matches utils-core versionworking-directory: packages/harnessrun: |PKG_VERSION="v$(node -p "require('./package.json').version")"@@ -38,9 +40,8 @@ jobs:exit 1fi- # Publish from the staged dist/: dist/package.json is- # generated by the build with dist-relative paths, so the tarball root is- # the compiled file tree and deep imports have no dist/ segment.+ # Library first: utils pins workspace:* → this concrete version on publish.+ # Prereleases (e.g. 0.1.9-rc.1) must pass --tag (npm 11); first preid → dist-tag (rc).- name: Publish @truefoundry/utils-coreworking-directory: packages/harness/distrun: |@@ -56,3 +57,14 @@ jobs:fi# TODO(oss): add --provenance once the repo is public. Do NOT add it now:# provenance publicly attests the source repo and commit.++ # TODO: Publish @truefoundry/utils++ # # Root build copies FE into packages/server/dist/_frontend; refuse an API-only tarball.+ # - name: Verify packaged UI is present+ # run: |+ # test -f packages/server/dist/cli.js+ # test -f packages/server/dist/_frontend/index.html++ # App + CLI from package root (dist/ includes dist/_frontend/).+ # pnpm publish rewrites workspace:* deps to the utils-core version just published.diff --git a/.gitignore b/.gitignoreindex e3127999c..feb8fbc1d 100644--- a/.gitignore+++ b/.gitignore@@ -4,7 +4,6 @@ dist/.DS_Store*.log.env-packages/server/registry/coverage/.turbo/*.tsbuildinfodiff --git a/Dockerfile b/Dockerfileindex 2117e6353..d6c6047ed 100644--- a/Dockerfile+++ b/Dockerfile@@ -1,6 +1,6 @@# syntax=docker/dockerfile:1#-# Multi-stage build for @truefoundry/server, which also serves the UI: the only image the stack needs.+# Multi-stage build for @truefoundry/utils, which also serves the UI: the only image the stack needs.## Lives at the repository root because the build needs the whole pnpm workspace# as its context: the server depends on the workspace package @truefoundry/utils-core.@@ -45,10 +45,10 @@ COPY packages/harness/src/core/sandbox/scripts packages/harness/src/core/sandbox# ---------------------------------------------------------------------------FROM workspace AS builderRUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --filter @truefoundry/server...+ pnpm install --frozen-lockfile --offline --filter @truefoundry/utils...COPY packages/harness packages/harnessCOPY packages/server packages/server-RUN pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/server build+RUN pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/utils build# ---------------------------------------------------------------------------# frontend-builder: build the UI the server serves (parallel to builder above).@@ -71,7 +71,7 @@ RUN pnpm --filter frontend build# ---------------------------------------------------------------------------FROM workspace AS prod-depsRUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/server...+ pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/utils...# ---------------------------------------------------------------------------# runner: minimal image with prod node_modules + built artifacts.@@ -88,16 +88,16 @@ COPY --from=prod-deps /app/packages/server/node_modules ./packages/server/node_mCOPY --from=builder /app/packages/harness/package.json ./packages/harness/package.jsonCOPY --from=builder /app/packages/harness/dist ./packages/harness/dist-# Built server.+# Built server (JS). UI is copied below from the parallel frontend stage into+# dist/_frontend — same path as the npm tarball / `pnpm build` copy step.COPY --from=builder /app/packages/server/package.json ./packages/server/package.jsonCOPY --from=builder /app/packages/server/dist ./packages/server/dist--# The UI, at an absolute path so it resolves from any working directory.-COPY --from=frontend-builder /app/packages/frontend/dist ./packages/frontend/dist-ENV FRONTEND_DIR=/app/packages/frontend/dist+# Frontend builds in a parallel stage; place it at the same path as the npm tarball.+COPY --from=frontend-builder /app/packages/frontend/dist ./packages/server/dist/_frontendWORKDIR /app/packages/serverEXPOSE 8790+# Launch-only (matches root `pnpm start` / `standalone:start`). Image already contains dist.CMD ["node", "dist/main.js"]diff --git a/README.md b/README.mdindex 09ff28ccc..f3de21993 100644--- a/README.md+++ b/README.md@@ -1,103 +1,121 @@-# TrueFoundry harness workspace+# TrueForge-pnpm workspace with:+TrueForge is an open-source agent harness: the runtime layer that turns an LLM into a working agent. It runs the execution loop — model calls, tool use, context, and session state — and exposes the result as a chat UI, an HTTP API, and a TypeScript library.-| Package | Path | Role |-| ------------------------- | ---------------------------------------- | ------------------------------------------------------ |-| `@truefoundry/utils-core` | [`packages/harness`](packages/harness) | Published library (`core` + `agent-session`) |-| `@truefoundry/server` | [`packages/server`](packages/server) | HTTP server + UI host (private; depends on utils-core) |-| `frontend` | [`packages/frontend`](packages/frontend) | Private draft-only agent chat UI (not published) |+Out of the box you get multi-turn sessions with streaming, MCP tool servers (including OAuth), skills, sandboxed code execution, human-in-the-loop approvals, and subagents. Configure providers in the UI or via the settings APIs; run as a single process on SQLite, or scale out with Postgres and Redis.-## Development+> Note: Package and folder names will be renamed soon to match the release names below. They have been intentionally named "utils" to not leak before announcement.++| Package | Release Name | Path | What it is |+| ------------------------- | ----------------------------- | ---------------------------------------- | ----------------------------------------------------------- |+| `@truefoundry/utils` | `@truefoundry/trueforge` | `[packages/server](packages/server)` | Agent server + bundled UI |+| `@truefoundry/utils-core` | `@truefoundry/trueforge-core` | `[packages/harness](packages/harness)` | Library: agent core, sessions, and streaming |+| `trueharness` | `@truefoundry/trueforge-sdk` | `[packages/sdk](packages/sdk)` | Generated TypeScript SDK |+| `frontend` | — | `[packages/frontend](packages/frontend)` | Chat UI (bundled into the server; not published on its own) |-The API and frontend run on the host with hot reload. Postgres and Redis run in Docker.+Requires **Node.js 22.13+** and **pnpm**.-### One-time setup+## Run from source```bashpnpm installcp packages/server/.env.example packages/server/.env```-Fill in any required secrets in `packages/server/.env`. The copied defaults already connect the host server to the Compose services.--### Day-to-day+### Standalone (local, zero infra)-Terminal 1:+SQLite only — good for trying the product or single-process use.```bash-pnpm dev:infra # Postgres + Redis (data in ./data/dev/postgres); Ctrl+C stops them+pnpm standalone:dev```-Terminal 2:--```bash-pnpm dev # API on :8790 and Vite on :3000-```+- UI (Vite): [http://localhost:3000](http://localhost:3000) — proxies `/api/*` to the API+- API: [http://localhost:8790](http://localhost:8790)-Open `http://localhost:3000`. Frontend changes update through Vite HMR; server changes automatically restart the API on `:8790`. Vite proxies `/api/*` to the API. Local server scripts resolve `@truefoundry/utils-core` from source (`exports.development`), so a utils-core `dist/` build is not required for `pnpm dev`. For drain testing without server hot reload, use `pnpm dev:no-watch` instead of `pnpm dev`.+### Multi-replica (Postgres + Redis)-The workspace utils-core package is ESM so the host server and source schemas share one ESM dependency graph. `NODE_OPTIONS=--conditions=development` selects `src/` at runtime, and TypeScript uses the same condition for source-based static analysis. Development, lint, typecheck, tests, OpenAPI generation, and migrations do not read or recreate `packages/harness/dist`; release builds, package checks, and Docker smoke tests create it intentionally.+Use this when you need more than one server process (cancels and turn streams peer over Redis).-Server dev scripts regenerate the embedded sandbox Python helpers before startup. Root `pnpm dev` also watches those Python files, regenerates the TypeScript source module after edits, and lets the server watcher restart normally. Neither path builds `dist`.+Terminal 1 — start Postgres (`:5432`) and Redis (`:6379`):-| Script | Runs |-| ------------------- | ---------------------------------------------------------------------------------- |-| `pnpm dev:infra` | Postgres + Redis in the foreground |-| `pnpm dev` | Sandbox helper generator + server (`tsx watch`) + Vite |-| `pnpm dev:no-watch` | Same, but API without hot reload (`NODE_ENV=production`) so Ctrl+C exercises drain |-| `pnpm clean` | Workspace build outputs and the ESLint cache |-| `pnpm clean:all` | The same outputs plus all workspace `node_modules` directories |+```bash+pnpm dev:infra+```-Migrations run automatically on server startup. To migrate without starting HTTP:+Terminal 2:```bash-pnpm --filter @truefoundry/server migrate+pnpm dev```-Workspace checks:+- UI (Vite): [http://localhost:3000](http://localhost:3000) — proxies `/api/*` to the API+- API: [http://localhost:8790](http://localhost:8790)++| | Standalone | Multi-replica |+| --------- | -------------------------------------- | ----------------------------------------------- |+| Process | One server | One or more replicas with Redis peering |+| Database | SQLite | Postgres |+| Infra | None | Postgres + Redis (`pnpm dev:infra` or your own) |+| Dev | `pnpm standalone:dev` | `pnpm dev` (after infra) |+| Prod-like | `pnpm build` → `pnpm standalone:start` | `pnpm build` → `pnpm start` |++Migrations run on server startup. To run Postgres migrations without starting HTTP:```bash-pnpm build-pnpm test-pnpm typecheck+pnpm --filter @truefoundry/utils migrate```-Root `build` / `typecheck` (and CI) include utils-core, server, and frontend. `FRONTEND_PORT` moves Vite off `:3000`, `VITE_SERVER_URL` points it at another API. See [`packages/frontend/README.md`](packages/frontend/README.md).+That script sets `STANDALONE=false` and uses `POSTGRES_*` from `packages/server/.env`. It will not run in standalone mode (SQLite migrations happen on boot instead).-## Serving the UI from the server+### Serving the UI from the server-Deployments are one process on one origin: `/api/*` (including `/api/v1/docs` and `/api/v1/openapi.json`) and-`/healthz` are the API, everything else resolves to the UI. `FRONTEND_DIR` points at the build (default-`../frontend/dist`; the image sets an absolute path). It is not required: with no build there the server-logs a warning and serves the API only, which is what running the server behind Vite needs.+Dev and production-like runs use different process topologies. Standalone vs multi-replica only changes storage/peering (`STANDALONE`); it does not change how the UI is served.-## Docker Compose smoke test+**Development** — `pnpm standalone:dev` / `pnpm dev` run two processes in parallel: Vite (UI, with live reload) and the Hono API. The browser talks to Vite; Vite proxies `/api/`* to Hono.-Full stack in containers — built server image serves API + UI (no Vite HMR):+```+ browser Vite (:3000) Hono (:8790)+ │ │ │+ │ GET / (UI) │ │+ │────────────────────────────>│ │+ │ │ │+ │ /api/* │ proxy │+ │────────────────────────────>│─────────────────────────────>│+```-```bash-pnpm smoke # build, wait for healthy services, then check /healthz and the UI app shell-pnpm smoke:down # stop the stack+**Production-like** — after `pnpm build`, `pnpm standalone:start` / `pnpm start` run a single Hono process. It serves the built frontend bundle for non-API routes and handles `/api/`* itself. The Docker container works the same way: one process, one origin.++```+ browser Hono (:8790)+ │ │+ │ GET / (static UI from dist/_frontend) │+ │───────────────────────────────────────────>│+ │ │+ │ /api/* │+ │───────────────────────────────────────────>│```-Open `http://localhost:8791`. Secrets and Postgres credentials come from `packages/server/.env`. Host ports and in-network DB/Redis targets are fixed in Compose so they do not collide with development: Postgres `:5433`, Redis `:6380`, app `:8791` (vs `pnpm dev:infra` on `:5432`/`:6379` and `pnpm dev` on `:8790`/`:3000`).+Open the UI on `:3000` in dev, or on the API port (`:8790`) when the server is serving the bundle.-Requires `packages/server/.env`. `.env` and `data/` are gitignored. Development infra stores Postgres under `./data/dev/postgres`.+## Configuration-## SDK generation+Model providers, MCP servers, skills, and sandboxes are configured in the UI under **Settings**, or via the settings APIs. Discovery presets come from the `*/catalog` endpoints. Interactive API docs are at `/api/v1/docs`.-`packages/sdk` and `fern/openapi/openapi.json` are both generated by-[Fern](https://buildwithfern.com) and committed — edit `packages/server/src/routes/`, never the-output. [`generate-sdk.yaml`](.github/workflows/generate-sdk.yaml) regenerates them on every change;-see its comments for the flags if you need to run it by hand (Docker required):+See `[packages/server/.env.example](packages/server/.env.example)` for every env var.-```bash-pnpm openapi:write-fern check && fern generate --group ts-sdk --version 0.0.0 --local --generate-tests-```+Useful overrides:-## Library imports+- `PORT` — API port (default `8790`)+- `FRONTEND_PORT` — Vite UI port in dev (default `3000`); see `[packages/frontend/README.md](packages/frontend/README.md)`+- `VITE_SERVER_URL` — point the Vite proxy at a different API+- `FRONTEND_DIR` — directory of a built UI for the server to serve+- `SQLITE_PATH` — SQLite file location in standalone mode+- `REDIS_URL` / `POSTGRES_*` — used when `STANDALONE=false`++On one origin (start / Docker): `/api/*` (including OpenAPI) and `/healthz` are the API; everything else is the UI. The server prefers a packaged `dist/_frontend`, then `packages/frontend/dist`. With no UI build present it serves the API only (normal for Vite-backed `pnpm dev`). See [Serving the UI from the server](#serving-the-ui-from-the-server).++## Use as a library```tsimport { AgentThread } from '@truefoundry/utils-core/core';@@ -110,6 +128,44 @@ Or namespaced:import { core, agentSession } from '@truefoundry/utils-core';```-Workspace-only `development` exports are removed from the published package. Its staged `dist/package.json` remains CommonJS so `require()` uses `.js`, while ESM consumers use `.mjs`. After switching from `@truefoundry/utils` to `@truefoundry/utils-core`, consumers such as `tfy-llm-gateway` keep the same deep-import and CJS/ESM layout. Consumer compatibility is checked against a packed artifact, including root, barrel, deep skill imports, and both CJS and ESM loading.+The published package supports both CommonJS and ESM. Server-only dependencies (Hono, SQLite, Postgres, Redis, etc.) stay in `@truefoundry/utils` and are not pulled in by library consumers.++## Development++| Script | Purpose |+| ---------------------------------------------------- | ----------------------------------------------------- |+| `pnpm standalone:dev` / `pnpm dev` | Local UI + API (see modes above) |+| `pnpm standalone:dev:no-watch` / `pnpm dev:no-watch` | Same, but the server does not restart on file changes |+| `pnpm dev:server:ui` | Packed UI + watched API (no Vite) |+| `pnpm build` | Build all packages |+| `pnpm test` / `pnpm typecheck` | Workspace checks |+| `pnpm smoke` / `pnpm smoke:down` | Full Docker Compose stack |+| `pnpm clean` / `pnpm clean:all` | Remove build outputs (+ `node_modules` for `:all`) |++Local server scripts resolve `@truefoundry/utils-core` from source, so you do not need a utils-core `dist/` build for `pnpm dev` / `standalone:dev`.++### Smoke test (Docker)++Full stack in containers — built server image serves API + UI. Forces multi-replica mode (`STANDALONE=false`):++```bash+pnpm smoke # build, wait for healthy services, check /healthz and UI+pnpm smoke:down+```++Open [http://localhost:8791](http://localhost:8791). Credentials come from `packages/server/.env`. Host ports differ from local dev so they do not collide: Postgres `:5433`, Redis `:6380`, app `:8791`.++### Entry points++| File | Used by | Role |+| -------------- | --------------------------------------------- | ------------------------------------------- |+| `dist/main.js` | Docker, `pnpm start`, `pnpm standalone:start` | Env-only server boot |+| `dist/cli.js` | `npx @truefoundry/trueforge` | CLI (`--help`, `--port`), then loads `main` |-Server-only deps (`hono`, `@hono/node-server`, `@hono/swagger-ui`, `yaml`) live in `packages/server` and never reach library consumers.+### Generated SDK and OpenAPI++`packages/sdk` and `fern/openapi/openapi.json` are generated by [Fern](https://buildwithfern.com) and committed. Edit route handlers under `packages/server/src/routes/`, not the generated output. CI regenerates them; to run locally (Docker required):++```bash+pnpm sdk:generate+```diff --git a/RELEASING.md b/RELEASING.mdindex 2c1ae84f2..4fac312d1 100644--- a/RELEASING.md+++ b/RELEASING.md@@ -1,3 +1,22 @@+# Releasing++Two public packages ship from this repo:++| Package | Source | How it publishes |+| ------------------------- | ------------------ | --------------------------------------------------------------- |+| `@truefoundry/utils-core` | `packages/harness` | From staged `packages/harness/dist` (library) |+| `@truefoundry/utils` | `packages/server` | From package root (`dist/`, including `dist/_frontend/` for UI) |++The git tag `v*` must match **`packages/harness` (`@truefoundry/utils-core`) version**.+`@truefoundry/utils` may use an independent version — bump it in the same release PR+whenever the app/CLI changes. CI publishes **core first**, then utils (so+`workspace:*` rewrites to the core version that just landed on npm).++> **Currently only `@truefoundry/utils-core` publishes.** The `@truefoundry/utils`+> publish step in `release.yml` is deferred (`TODO`); CI still builds and tests it.++---+# Releasing `@truefoundry/utils-core`Interim setup for the fast development phase: the library in@@ -32,14 +51,18 @@ root is the compiled file tree. Consequences:## Per-release flow-1. **Bump the version via PR** (direct pushes to `main` are blocked by org+1. **Bump versions via PR** (direct pushes to `main` are blocked by orgruleset):```bashgit checkout -b release/v0.x.ycd packages/harness- npm version 0.x.y --no-git-tag-version # edits packages/harness/package.json only- git commit -am "chore: release v0.x.y"+ npm version 0.x.y --no-git-tag-version # or 0.x.y-rc.N for a prerelease+ cd ../server+ npm version 0.x.y --no-git-tag-version # bump when the app/CLI changes; may differ from core+ cd ../..+ git add packages/harness/package.json packages/server/package.json+ git commit -m "chore: release v0.x.y"git push -u origin release/v0.x.y```@@ -49,15 +72,21 @@ root is the compiled file tree. Consequences:```bashgit checkout main && git pull- git tag v0.x.y+ git tag v0.x.y # must equal packages/harness version (e.g. v0.1.9-rc.1)git push origin v0.x.y```3. **CI publishes automatically.** `.github/workflows/release.yml` installs,- builds (which stages `dist/` with its own package.json and smoke-tests- it), tests, verifies the tag matches `packages/harness/package.json`, and- runs `npm publish` **from `packages/harness/dist`** via trusted publishing- (OIDC — no NPM_TOKEN anywhere). Watch it under the repo's Actions tab.+ builds, tests, verifies the tag matches `packages/harness/package.json`, then+ runs `npm publish` **from `packages/harness/dist`**. (The `@truefoundry/utils`+ publish is deferred — see the note above.)++ Auth is trusted publishing (OIDC — no `NPM_TOKEN`). Watch the repo Actions tab.++ **Dist-tags:** npm 11 requires an explicit `--tag` for prereleases. CI derives+ it from the semver prerelease id (`0.2.0-rc.1` → `--tag rc`). Stable releases+ publish to `latest`. Install with `npx @truefoundry/utils@rc` or+ `@0.2.0-rc.1`; bare `npx @truefoundry/utils` stays on `latest`.4. **Bump the pinned version in the gateway.** Pin exact versions (no `^`)during the fast 0.x churn:@@ -66,25 +95,41 @@ root is the compiled file tree. Consequences:"@truefoundry/utils-core": "0.x.y"```+## Why core must publish before utils++`@truefoundry/utils` depends on `@truefoundry/utils-core: workspace:*`. On+publish, pnpm rewrites that to the **version in `packages/harness/package.json`**.+If that core version is missing from npm (or is an older build without exports+the server imports), `npx @truefoundry/utils` fails at runtime. Always ship+matching core+utils together when the app uses new core APIs.+## Local iteration without publishingFor tight loops, skip the publish round-trip:```bash+pnpm clean && pnpm build && pnpm standalone:start+# or pack only:cd packages/harness && pnpm build && cd dist && pnpm pack+cd packages/server && pnpm pack```-Point the gateway at the tarball via a `file:` dependency (or use `yalc`).+Point consumers at a tarball via a `file:` dependency (or use `yalc`).Publish a real version when CI or teammates need it.## Troubleshooting+- **Publish fails requiring a tag**: prerelease versions need `--tag` (npm 11).+ CI handles this; for local publishes use e.g. `pnpm publish --tag rc`.- **Publish fails with 403/E403**: version already published (npm versionsare immutable — bump and re-tag), or the trusted publisher config doesn'tmatch the workflow filename/repo exactly.- **Tag/version mismatch failure**: the guard step caught a tag that doesn'tmatch `packages/harness/package.json`. Delete the tag(`git push origin :refs/tags/vX.Y.Z`), fix the version via PR, re-tag.+- **Missing `dist/_frontend/index.html`**: root `pnpm build` must build+ `frontend` before `@truefoundry/utils`; the release job fails closed if the+ copy is absent.- **OIDC/auth error in the publish step**: trusted publishing requiresnpm >= 11.5.1; the workflow upgrades npm globally before publishing —check that step ran.diff --git a/docker-compose.yml b/docker-compose.ymlindex e10d42eeb..404617139 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -1,7 +1,7 @@# Full-stack smoke test. Reads packages/server/.env for secrets and# credentials; host ports and in-network DB/Redis targets are opinionated here# so they do not collide with or inherit host-dev values.-name: harness+name: trueforgeservices:postgres:@@ -54,9 +54,9 @@ services:POSTGRES_HOST: postgresPOSTGRES_PORT: 5432# Compose runs one replica but keeps peering on so the peered cancel path- # stays exercised in development. A single-process deployment can set this- # to true and drop the redis service entirely.- SINGLE_BINARY: 'false'+ # stays exercised. STANDALONE=false ⇒ Postgres + Redis.+ # A single-process deployment can set STANDALONE=true and drop redis.+ STANDALONE: 'false'REDIS_URL: redis://redis:6379# Secrets and Postgres credentials (POSTGRES_USER, …).# `environment` above overrides any colliding keys from this file.diff --git a/package.json b/package.jsonindex e708c3acc..df5683153 100644--- a/package.json+++ b/package.json@@ -6,32 +6,34 @@"node": ">=22.13.0"},"scripts": {- "build": "pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/server build && pnpm --filter frontend build",- "clean": "node scripts/clean.mjs",+ "build": "pnpm --filter @truefoundry/utils-core build && pnpm --filter frontend build && pnpm --filter @truefoundry/utils build","clean:all": "node scripts/clean.mjs --dependencies",- "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/server typecheck && pnpm --filter frontend typecheck",- "lint": "eslint . --fix --cache --cache-location .eslintcache",- "lint:ci": "eslint . --cache --cache-location .eslintcache",- "format": "prettier --write . --cache --config .prettierrc",+ "clean": "node scripts/clean.mjs",+ "dev": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils --filter frontend dev",+ "dev:no-watch": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/utils --filter frontend dev:no-watch",+ "dev:infra": "docker compose -f docker-compose.dev.yml up",+ "dev:server:ui": "pnpm --filter frontend build && pnpm --filter @truefoundry/utils build:frontend-assets && STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils dev",+ "standalone:dev": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils --filter frontend dev",+ "standalone:dev:no-watch": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/utils --filter frontend dev:no-watch",+ "start": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/utils start",+ "standalone:start": "STANDALONE=true NODE_ENV=production pnpm --filter @truefoundry/utils start","format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --error-on-unmatched-pattern --config .prettierrc","format:fix": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --config .prettierrc",- "test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/server test && pnpm --filter frontend test",- "test:store:local": "bash scripts/test-store-local.sh",- "dev": "pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/server --filter frontend dev",- "dev:no-watch": "pnpm --parallel --filter @truefoundry/server --filter frontend dev:no-watch",- "dev:infra": "docker compose -f docker-compose.dev.yml up",- "dev:server": "pnpm --filter @truefoundry/server dev",- "dev:frontend": "pnpm --filter frontend dev",- "dev:server:ui": "pnpm --filter frontend build && pnpm dev:server",- "smoke": "docker compose up --build --wait && node -e \"Promise.all([fetch('http://127.0.0.1:8791/healthz'), fetch('http://127.0.0.1:8791/')]).then(async ([health, ui]) => { if (!health.ok) throw new Error('healthz returned ' + health.status); const html = await ui.text(); if (!ui.ok || !html.includes('id=\\\"root\\\"')) throw new Error('UI did not return its app shell'); console.log('healthz and UI OK'); })\"",- "smoke:down": "docker compose down",- "openapi:write": "pnpm --filter @truefoundry/server openapi:write",+ "format": "prettier --write . --cache --config .prettierrc",+ "lint:ci": "eslint . --cache --cache-location .eslintcache",+ "lint": "eslint . --fix --cache --cache-location .eslintcache",+ "openapi:write": "pnpm --filter @truefoundry/utils openapi:write",+ "pack:dry": "pnpm --filter @truefoundry/utils-core pack:dry && pnpm --filter @truefoundry/utils pack:dry",+ "postinstall": "pnpm --filter @truefoundry/utils-core build:gen",+ "prepare": "husky || true","sdk:generate": "bash scripts/generate-sdk.sh",- "ui:shot": "node ui-shots/shot.mjs",+ "smoke:down": "docker compose down",+ "smoke": "docker compose up --build --wait && node -e \"Promise.all([fetch('http://127.0.0.1:8791/healthz'), fetch('http://127.0.0.1:8791/')]).then(async ([health, ui]) => { if (!health.ok) throw new Error('healthz returned ' + health.status); const html = await ui.text(); if (!ui.ok || !html.includes('id=\\\"root\\\"')) throw new Error('UI did not return its app shell'); console.log('healthz and UI OK'); })\"",+ "test:store:local": "bash scripts/test-store-local.sh",+ "test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/utils test && pnpm --filter frontend test",+ "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/utils typecheck && pnpm --filter frontend typecheck","ui:clean": "node ui-shots/clean.mjs",- "pack:dry": "pnpm --filter @truefoundry/utils-core pack:dry",- "postinstall": "pnpm --filter @truefoundry/utils-core build:gen",- "prepare": "husky || true"+ "ui:shot": "node ui-shots/shot.mjs"},"devDependencies": {"@eslint-react/eslint-plugin": "^5.18.0",diff --git a/packages/frontend/README.md b/packages/frontend/README.mdindex 1df57b937..58cd102a9 100644--- a/packages/frontend/README.md+++ b/packages/frontend/README.md@@ -19,12 +19,14 @@ No login is required.## Local development-For the full host workflow (Compose Postgres/Redis, then API + Vite), see the root-[`README.md`](../../README.md#development).+For the full host workflow (standalone or non-standalone), see the root+[`README.md`](../../README.md).```bash-pnpm dev # API on :8790 and Vite on :3000 together (after `pnpm dev:infra`)-pnpm dev:frontend # or Vite alone, against an API that is already up+pnpm standalone:dev # zero-env: SQLite, Vite :3000 + API :8790+# or:+pnpm dev:infra # then in another terminal:+pnpm dev # Postgres + Redis, Vite :3000 + API :8790```Open `http://localhost:3000`: Vite serves the UI from source (edits hot-reload, no rebuild or serverdiff --git a/packages/harness/package.json b/packages/harness/package.jsonindex c3623fe70..440f2f118 100644--- a/packages/harness/package.json+++ b/packages/harness/package.json@@ -69,9 +69,9 @@"dist"],"scripts": {- "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:js && pnpm run build:dts && pnpm run build:pkg && pnpm run build:check","build:gen": "node scripts/generate-sandbox-scripts.mjs","build:gen:watch": "node --watch-path=src/core/sandbox/scripts scripts/generate-sandbox-scripts.mjs",+ "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:js && pnpm run build:dts && pnpm run build:pkg && pnpm run build:check","dev": "pnpm run build:gen:watch","build:js": "tsup","build:dts": "tsc -p tsconfig.build.json --emitDeclarationOnly",diff --git a/packages/server/.env.example b/packages/server/.env.exampleindex 0741ec09f..e362b144b 100644--- a/packages/server/.env.example+++ b/packages/server/.env.example@@ -3,6 +3,11 @@## Copy to .env and fill in the values. The server validates all of these at# startup and refuses to boot on any invalid value (bad JSON, bad URL, etc.).+#+# Topology (STANDALONE) and NODE_ENV are set by root pnpm scripts+# (`pnpm dev`, `pnpm standalone:dev`, `pnpm start`, …). Those process env+# values win over this file. Uncomment STANDALONE below only when running the+# server package directly (e.g. `node dist/main.js` or `tsx src/main.ts`).# ---------------------------------------------------------------------------# HTTP port the server listens on. Optional, defaults to 8790.@@ -24,22 +29,27 @@ PORT=8790# When unset, the catalog inlined at build time (src/catalog/sandbox-catalog.yaml) is used.# SANDBOX_CATALOG_PATH=/path/to/sandbox-catalog.yaml-# Frontend build the server serves alongside the API. Optional, defaults to-# ../frontend/dist relative to the working directory. With no build there the-# server logs a warning and serves the API only.-# FRONTEND_DIR=../frontend/dist+# Frontend build the server serves alongside the API. Optional; defaults to+# packages/server/dist/_frontend (after build) or monorepo packages/frontend/dist.+# With no build there the server logs a warning and serves the API only.+# FRONTEND_DIR=/absolute/path/to/frontend/dist++# Deployment topology: single process (true, default) uses SQLite and+# disables Redis/executor peering; false uses Postgres + Redis so cancels+# that land on the wrong replica still work. Prefer root scripts+# (`pnpm standalone:*` vs `pnpm dev` / `pnpm start`) over setting this here.+# STANDALONE=false-# Declares the deployment topology. true (the default) asserts exactly one-# server process: Redis is never contacted and REDIS_URL is ignored even if set.-# Set it to false before running more than one replica, otherwise a cancel that-# lands on the wrong replica silently stops nothing.-SINGLE_BINARY=true+# Absolute path to the SQLite database file. Used when STANDALONE=true;+# defaults to the OS data dir from env-paths (app name "truefoundry-utils"):+# macOS: ~/Library/Application Support/truefoundry-utils/db.sqlite+# Linux: ~/.local/share/truefoundry-utils/db.sqlite+# Windows: %LOCALAPPDATA%\truefoundry-utils\Data\db.sqlite+# SQLITE_PATH=-# Required when SINGLE_BINARY=false, ignored otherwise. Redis connection URL-# shared by all server replicas; carries executor peering so a cancel that lands-# on one replica reaches the replica running the turn. Use localhost for host-# `pnpm dev`; `docker-compose.yml` overrides this to redis://redis:6379 for the-# server container.+# Used when STANDALONE=false (ignored in standalone). Redis connection URL for+# executor peering. Defaults to redis://localhost:6379 if unset.+# `docker-compose.yml` overrides this to redis://redis:6379 for the server container.REDIS_URL=redis://localhost:6379# Resumable turn stream settings. All are optional.@@ -51,11 +61,12 @@ REDIS_URL=redis://localhost:6379# TURN_SUBSCRIBE_TIMEOUT_MS=600000# ----------------------------------------------------------------------------# MCP OAuth (DCR). PUBLIC_BASE_URL is required — origin of the fixed callback route-# {PUBLIC_BASE_URL}/api/v1/mcp-servers/oauth/callback (not trimmed). OAUTH_CLIENT_NAME is-# the RFC 7591 client_name on the consent screen (default: truefoundry-harness).+# MCP OAuth (DCR). PUBLIC_BASE_URL is the origin of the fixed callback route+# {PUBLIC_BASE_URL}/api/v1/mcp-servers/oauth/callback (not trimmed). Optional;+# defaults to http://localhost:${PORT}. OAUTH_CLIENT_NAME is the RFC 7591+# client_name on the consent screen (default: truefoundry-harness).# ----------------------------------------------------------------------------PUBLIC_BASE_URL=http://localhost:8790+# PUBLIC_BASE_URL=http://localhost:8790# OAUTH_CLIENT_NAME=truefoundry-harness# ---------------------------------------------------------------------------@@ -69,8 +80,9 @@ PUBLIC_BASE_URL=http://localhost:8790# SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD=20971520# ----------------------------------------------------------------------------# Postgres (required). Used by the server pool and by Compose postgres-# services (via env_file). Keep localhost here for host `pnpm dev`;+# Postgres (used when STANDALONE=false; also read by Compose postgres+# services via env_file). Config defaults match these values if unset.+# Keep localhost here for host `pnpm dev`;# `docker-compose.yml` overrides POSTGRES_HOST/PORT for the server container.# ---------------------------------------------------------------------------POSTGRES_USER=harnessdiff --git a/packages/server/.env.test b/packages/server/.env.testindex 442731292..b7d1080f3 100644--- a/packages/server/.env.test+++ b/packages/server/.env.test@@ -1,4 +1,5 @@# Dummy values so config.ts loads in unit tests; no service is contacted.+# STANDALONE defaults to true → SQLite (Postgres env below is unused).POSTGRES_USER=testPOSTGRES_PASSWORD=testPOSTGRES_DB=testdiff --git a/packages/server/package.json b/packages/server/package.jsonindex 8ca71ea23..d72857162 100644--- a/packages/server/package.json+++ b/packages/server/package.json@@ -1,28 +1,35 @@{- "name": "@truefoundry/server",- "version": "0.1.0",- "description": "TrueFoundry agent server (CLI/HTTP). Not published yet.",+ "name": "@truefoundry/utils",+ "version": "0.2.0-rc.2",+ "description": "TrueFoundry agent server + UI (npx @truefoundry/utils)","author": "Truefoundry","license": "UNLICENSED",- "private": true,+ "private": false,"type": "module",+ "bin": "./dist/cli.js",+ "files": [+ "dist"+ ],"scripts": {- "build:gen": "node scripts/generate-catalog.mjs",+ "build:frontend-assets": "node scripts/copy-frontend.mjs","build:gen:watch": "node --watch-path=src/catalog/model-catalog.yaml --watch-path=src/catalog/mcp-catalog.yaml --watch-path=src/catalog/skill-catalog.yaml --watch-path=src/catalog/sandbox-catalog.yaml scripts/generate-catalog.mjs",- "build": "pnpm run build:gen && tsc --noEmit && tsup",- "predev": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",- "dev": "pnpm run \"/^(catalog-watch|dev:serve)$/\"",- "catalog-watch": "pnpm run build:gen:watch",+ "build:gen": "node scripts/generate-catalog.mjs",+ "build:clean": "rm -rf dist",+ "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:clean && tsup && chmod +x dist/cli.js && pnpm run build:frontend-assets","dev:serve": "NODE_OPTIONS='--conditions=development' NODE_ENV=development tsx watch --env-file=.env src/main.ts",- "predev:no-watch": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",- "dev:no-watch": "NODE_OPTIONS='--conditions=development' NODE_ENV=production tsx --env-file=.env src/main.ts",- "migrate": "NODE_OPTIONS='--conditions=development' tsx --env-file=.env src/db/postgres/migrate-cli.ts",- "typecheck": "pnpm run build:gen && tsc --noEmit && tsc --noEmit -p tests/db/tsconfig.json && tsc --noEmit -p tests/unit/tsconfig.json",+ "dev": "pnpm run \"/^(build:gen:watch|dev:serve)$/\"",+ "dev:no-watch": "NODE_OPTIONS='--conditions=development' NODE_ENV=development tsx --env-file=.env src/main.ts",+ "start": "NODE_ENV=production node --env-file=.env dist/main.js",+ "migrate": "NODE_OPTIONS='--conditions=development' STANDALONE=false tsx --env-file=.env src/db/postgres/migrate-cli.ts","openapi:write": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' tsx --env-file=.env.test scripts/write-openapi.ts",- "test": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs",+ "pack:dry": "pnpm pack --dry-run",+ "predev:no-watch": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",+ "predev": "pnpm --filter @truefoundry/utils-core build:gen && pnpm run build:gen",+ "test:eventsub": "jest --config jest.eventsub.config.cjs","test:store:postgres": "jest --config jest.store.postgres.config.cjs","test:store:sqlite": "jest --config jest.store.sqlite.config.cjs",- "test:eventsub": "jest --config jest.eventsub.config.cjs"+ "test": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs",+ "typecheck": "pnpm run build:gen && tsc --noEmit && tsc --noEmit -p tests/db/tsconfig.json && tsc --noEmit -p tests/unit/tsconfig.json"},"dependencies": {"@daytona/sdk": "^0.190.0",@@ -32,6 +39,7 @@"@modelcontextprotocol/sdk": "^1.29.0","@truefoundry/utils-core": "workspace:*","better-sqlite3": "^13.0.2",+ "env-paths": "^4.0.0","hono": "^4.12.34","kysely": "^0.29.4","pg": "^8.22.0",diff --git a/packages/server/scripts/copy-frontend.mjs b/packages/server/scripts/copy-frontend.mjsnew file mode 100644index 000000000..4453dad1c--- /dev/null+++ b/packages/server/scripts/copy-frontend.mjs@@ -0,0 +1,26 @@+/**+ * Copies the monorepo frontend build into `dist/_frontend` so the published+ * `@truefoundry/utils` tarball (and local `node dist/main.js` / `pnpm start`) can serve the UI+ * from next to the server bundle. Cleared by `pnpm clean` with the rest of dist/.+ *+ * Root `pnpm build` builds frontend before this package; a missing source only+ * skips (Docker builder builds frontend in a parallel stage).+ */+import { cpSync, existsSync, rmSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const source = path.resolve(packageRoot, '../frontend/dist');+const destination = path.join(packageRoot, 'dist', '_frontend');++if (!existsSync(path.join(source, 'index.html'))) {+ console.warn(+ `Skipping frontend copy: no build at ${source}. Run \`pnpm --filter frontend build\` first for a UI-capable package.`,+ );+ process.exit(0);+}++rmSync(destination, { recursive: true, force: true });+cpSync(source, destination, { recursive: true });+console.log(`Copied frontend build to ${destination}`);diff --git a/packages/server/src/app.ts b/packages/server/src/app.tsindex 3e1d83f50..b3268309b 100644--- a/packages/server/src/app.ts+++ b/packages/server/src/app.ts@@ -47,18 +47,18 @@ function routeNotFound(c: Context) {export interface ServerDeps {modelCatalog: ModelCatalog;- modelProviderStore: IModelProviderStore;mcpCatalog: McpCatalog;+ skillCatalog: SkillCatalog;+ sandboxCatalog: SandboxCatalog;+ modelProviderStore: IModelProviderStore;mcpServerStore: IMcpServerStore;tokenStore: IOAuthTokenStore;- skillCatalog: SkillCatalog;skillStore: ISkillStore;- sandboxCatalog: SandboxCatalog;sandboxProviderStore: ISandboxProviderStore;sessionStore: ISessionStore;sessions: Sessions;activeTurns: ActiveTurnRegistry;- /** Primary Redis client (server-owned); undefined in single-binary mode. */+ /** Primary Redis client (server-owned); undefined in standalone mode. */redis?: RedisClientType | undefined;/** Request-reply dispatch table served by this replica's executor. */requestReplyRouter: RequestReplyRouter;diff --git a/packages/server/src/cli.ts b/packages/server/src/cli.tsnew file mode 100644index 000000000..c800a71dd--- /dev/null+++ b/packages/server/src/cli.ts@@ -0,0 +1,59 @@+/**+ * CLI entry for `@truefoundry/utils` (`package.json` `bin` → `dist/cli.js`).+ *+ * Kept separate from `main.ts` so Docker / `pnpm start` can boot with env only+ * (`node dist/main.js`), while `npx @truefoundry/utils` gets a shebang, `--help`,+ * and `--port`. Flags must be applied before importing `./main` because config+ * reads `process.env` at module load.+ *+ * Topology defaults from env / config (`STANDALONE=true` unless set): standalone+ * uses SQLite with no Redis; `STANDALONE=false` uses Postgres + Redis peering.+ */+import { parseArgs } from 'node:util';++function printUsage(): void {+ console.log(`Usage:+ npx @truefoundry/utils+ npx @truefoundry/utils --port <n>++Start the agent server. Defaults to standalone mode (SQLite, no Redis).+Set STANDALONE=false with Postgres and Redis for multi-replica peering.++Options:+ --port <n> HTTP port (default: 8790, or PORT env)+ -h, --help Show this help+`);+}++function applyPort(raw: string | undefined): void {+ if (raw === undefined) {+ return;+ }+ const port = Number(raw);+ if (!Number.isInteger(port) || port < 1 || port > 65535) {+ throw new Error(`Invalid --port "${raw}" (expected integer 1–65535)`);+ }+ process.env['PORT'] = String(port);+}++try {+ const { values } = parseArgs({+ args: process.argv.slice(2),+ options: {+ port: { type: 'string' },+ help: { type: 'boolean', short: 'h', default: false },+ },+ allowPositionals: false,+ strict: true,+ });++ if (values.help) {+ printUsage();+ } else {+ applyPort(values.port);+ await import('./main.js');+ }+} catch (error) {+ console.error(error instanceof Error ? error.message : error);+ process.exit(1);+}diff --git a/packages/server/src/config.ts b/packages/server/src/config.tsindex 74dd79525..f1dd7dea6 100644--- a/packages/server/src/config.ts+++ b/packages/server/src/config.ts@@ -5,8 +5,36 @@* `configuration` object exported as default. Any invalid value throws at* import time, so a misconfigured server fails fast at boot instead of* mid-run.+ *+ * `STANDALONE` is a discriminated mode selector:+ * - `true` (default): SQLite only; no Redis / executor peering.+ * - `false`: Postgres + Redis (defaults to local harness credentials /+ * `redis://localhost:6379`).*/+import { existsSync } from 'node:fs';import path from 'node:path';+import { fileURLToPath } from 'node:url';++import envPaths from 'env-paths';++const DEFAULT_PORT = 8790;+/**+ * Package root whether this module runs as `src/config.ts` (tsx) or is bundled+ * into `dist/main.js` / `dist/cli.js` (`import.meta` → `dist/` → parent).+ */+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+/** Turn ids minted by a standalone process; no peer can ever own them. */+const LOCAL_EXECUTOR_ID = 'local';+/** OS-standard data dir for SQLite in standalone mode. */+const ENV_PATHS_APP_NAME = 'truefoundry-utils';+const DEFAULT_SQLITE_FILENAME = 'db.sqlite';++const DEFAULT_POSTGRES_USER = 'harness';+const DEFAULT_POSTGRES_PASSWORD = 'harness';+const DEFAULT_POSTGRES_DB = 'harness';+const DEFAULT_POSTGRES_HOST = 'localhost';+const DEFAULT_POSTGRES_PORT = 5432;+const DEFAULT_REDIS_URL = 'redis://localhost:6379';// ============================================================================// HELPER FUNCTIONS@@ -17,7 +45,7 @@ export interface GetEnvOptions {required?: boolean;}-export const getEnv = (key: string, options?: GetEnvOptions): string | undefined => {+function getEnv(key: string, options?: GetEnvOptions): string | undefined {const value = process.env[key];if (value !== undefined) {return value;@@ -33,13 +61,13 @@ export const getEnv = (key: string, options?: GetEnvOptions): string | undefined}return undefined;-};+}function randomAlphanumeric(length: number): string {return Array.from({ length }, () => Math.floor(Math.random() * 36).toString(36)).join('');}-export const parsePort = (raw: string | undefined): number => {+function parsePort(raw: string | undefined): number {if (raw === undefined || raw.trim() === '') {return DEFAULT_PORT;}@@ -48,14 +76,10 @@ export const parsePort = (raw: string | undefined): number => {throw new Error(`Environment variable PORT must be an integer between 1 and 65535, got "${raw}"`);}return port;-};+}/** Parses a positive-integer env var, falling back to `defaultValue` when unset/blank. */-export const parsePositiveInt = (options: {- envKey: string;- raw: string | undefined;- defaultValue: number;-}): number => {+function parsePositiveInt(options: { envKey: string; raw: string | undefined; defaultValue: number }): number {const { envKey, raw, defaultValue } = options;if (raw === undefined || raw.trim() === '') {return defaultValue;@@ -65,10 +89,10 @@ export const parsePositiveInt = (options: {throw new Error(`Environment variable ${envKey} must be a positive integer, got "${raw}"`);}return value;-};+}/** Parses a boolean env var; anything but `true`/`false` throws instead of reading as `false`. */-const parseBoolean = (options: { envKey: string; raw: string | undefined; defaultValue: boolean }): boolean => {+function parseBoolean(options: { envKey: string; raw: string | undefined; defaultValue: boolean }): boolean {const { envKey, raw, defaultValue } = options;if (raw === undefined || raw.trim() === '') {return defaultValue;@@ -77,60 +101,118 @@ const parseBoolean = (options: { envKey: string; raw: string | undefined; defaulif (value === 'true') return true;if (value === 'false') return false;throw new Error(`Environment variable ${envKey} must be "true" or "false", got "${raw}"`);-};+}-/** Required env var that also rejects blank strings. */-export const requireNonEmptyEnv = (key: string): string => {- const value = getEnv(key, { required: true });- if (value === undefined || value.trim() === '') {- throw new Error(`Environment variable ${key} is required but was not specified.`);+/**+ * Prefer `dist/_frontend` shipped in the npm tarball (npx / `pnpm start`).+ * Fall back to the monorepo sibling `../frontend/dist` (host-dev before a copy).+ */+function resolveDefaultFrontendDir(): string {+ const packaged = path.join(PACKAGE_ROOT, 'dist', '_frontend');+ if (existsSync(path.join(packaged, 'index.html'))) {+ return packaged;}- return value;-};+ return path.join(PACKAGE_ROOT, '..', 'frontend', 'dist');+}++function resolveFrontendDir(): string {+ const override = getEnv('FRONTEND_DIR');+ if (override !== undefined && override.trim() !== '') {+ return path.resolve(override);+ }+ return resolveDefaultFrontendDir();+}++/** Absolute path from an optional env override; unset/blank → `undefined`. */+function resolveOptionalPathEnv(envKey: string): string | undefined {+ const override = getEnv(envKey);+ if (override === undefined || override.trim() === '') {+ return undefined;+ }+ return path.resolve(override);+}++/**+ * Absolute SQLite file path for standalone mode.+ * Env: `SQLITE_PATH` (optional). Default: `{env-paths data}/db.sqlite`.+ */+function resolveSqlitePath(): string {+ const override = getEnv('SQLITE_PATH');+ if (override !== undefined && override.trim() !== '') {+ return path.resolve(override);+ }+ const paths = envPaths(ENV_PATHS_APP_NAME, { suffix: '' });+ return path.join(paths.data, DEFAULT_SQLITE_FILENAME);+}++/** Redis peering URL for distributed mode. Env: `REDIS_URL`. */+function resolveRedisUrl(): string {+ const raw = getEnv('REDIS_URL', { defaultValue: DEFAULT_REDIS_URL }) ?? DEFAULT_REDIS_URL;+ if (raw.trim() === '') {+ throw new Error('Environment variable REDIS_URL must be non-empty when STANDALONE=false.');+ }+ return raw;+}++/** Postgres connection string derived from `POSTGRES_*` for distributed mode. */+function resolvePostgresDatabaseUrl(): string {+ const postgresUser = getEnv('POSTGRES_USER', { defaultValue: DEFAULT_POSTGRES_USER }) ?? DEFAULT_POSTGRES_USER;+ const postgresPassword =+ getEnv('POSTGRES_PASSWORD', { defaultValue: DEFAULT_POSTGRES_PASSWORD }) ?? DEFAULT_POSTGRES_PASSWORD;+ const postgresDb = getEnv('POSTGRES_DB', { defaultValue: DEFAULT_POSTGRES_DB }) ?? DEFAULT_POSTGRES_DB;+ const postgresHost = getEnv('POSTGRES_HOST', { defaultValue: DEFAULT_POSTGRES_HOST }) ?? DEFAULT_POSTGRES_HOST;+ const postgresPort = parsePositiveInt({+ envKey: 'POSTGRES_PORT',+ raw: getEnv('POSTGRES_PORT'),+ defaultValue: DEFAULT_POSTGRES_PORT,+ });+ if (+ postgresUser.trim() === '' ||+ postgresPassword.trim() === '' ||+ postgresDb.trim() === '' ||+ postgresHost.trim() === ''+ ) {+ throw new Error(+ 'POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and POSTGRES_HOST must be non-empty when STANDALONE=false.',+ );+ }+ return buildPostgresConnectionString({+ user: postgresUser,+ password: postgresPassword,+ host: postgresHost,+ port: postgresPort,+ database: postgresDb,+ });+}/** Builds a Postgres connection URL from discrete `POSTGRES_*` parts. */-export const buildPostgresConnectionString = (parts: {+function buildPostgresConnectionString(parts: {user: string;password: string;host: string;port: number;database: string;-}): string => {+}): string {return `postgres://${encodeURIComponent(parts.user)}:${encodeURIComponent(parts.password)}@${parts.host}:${String(parts.port)}/${encodeURIComponent(parts.database)}`;-};--// ============================================================================-// CONFIGURATION INTERFACE-// ============================================================================--export const DEFAULT_PORT = 8790;--/** Relative to the working directory; the image sets an absolute FRONTEND_DIR. */-const DEFAULT_FRONTEND_DIR = '../frontend/dist';--/** Turn ids minted by a single-binary process; no peer can ever own them. */-const LOCAL_EXECUTOR_ID = 'local';+}-/** Dropped in single-binary mode so nothing downstream can connect to a Redis it must not use. */-const resolveRedisUrl = (singleBinary: boolean): string | undefined => {- if (singleBinary) {- return undefined;+/** Defaults to `http://localhost:${PORT}` so local standalone boots without an env file. */+function resolvePublicBaseUrl(port: number): string {+ const override = getEnv('PUBLIC_BASE_URL');+ if (override !== undefined && override.trim() !== '') {+ return override;}- return requireNonEmptyEnv('REDIS_URL');-};+ return `http://localhost:${String(port)}`;+}-/** Always longer than `LOCAL_EXECUTOR_ID`, so a peer can never be mistaken for a local owner. */-const resolveExecutorId = (singleBinary: boolean): string => {- if (singleBinary) {- return LOCAL_EXECUTOR_ID;- }- return randomAlphanumeric(6);-};+// ============================================================================+// CONFIGURATION TYPES+// ============================================================================-export interface ServerConfiguration {+export interface SharedServerConfiguration {/** HTTP port the server listens on. Env: `PORT`. */PORT: number;- /** Peering identity embedded in the turn ids this process mints; `local` in single-binary mode. */+ /** Peering identity embedded in the turn ids this process mints; `local` in standalone mode. */EXECUTOR_ID: string;/*** Optional override for the model catalog YAML (discovery presets for@@ -158,7 +240,8 @@ export interface ServerConfiguration {SANDBOX_CATALOG_PATH: string | undefined;/*** Frontend build served alongside the API; a missing directory leaves the server API-only.- * Env: `FRONTEND_DIR`, defaults to `../frontend/dist` relative to the working directory.+ * Env: `FRONTEND_DIR`. Default: packaged `dist/_frontend` (npx tarball) or+ * monorepo `packages/frontend/dist` — always absolute, independent of CWD.*/FRONTEND_DIR: string;/** Max milliseconds for one MCP request. Env: `MCP_REQUEST_TIMEOUT_MS`. Default 4 minutes. */@@ -168,7 +251,7 @@ export interface ServerConfiguration {/*** Public base URL of this server used as the origin of the MCP OAuth callback* (`{PUBLIC_BASE_URL}/api/v1/mcp-servers/oauth/callback`). Not trimmed.- * Env: `PUBLIC_BASE_URL` (required).+ * Env: `PUBLIC_BASE_URL`. Default: `http://localhost:${PORT}`.*/PUBLIC_BASE_URL: string;/**@@ -192,120 +275,126 @@ export interface ServerConfiguration {*/SERVER_EXECUTION_TIMEOUT_SECONDS: number;/**- * Postgres connection string derived from `POSTGRES_*` (not read from env directly).- * Form: `postgres://USER:PASSWORD@HOST:PORT/DB` with user/password URL-encoded.+ * TTL for a running turn's resumable event stream.+ * Env: `TURN_STREAM_TTL_SECONDS`. Default execution timeout + 300.*/- DATABASE_URL: string;- /** Max connections in the `pg` Pool. Env: `DATABASE_POOL_MAX`. Default 10. */- DATABASE_POOL_MAX: number;+ TURN_STREAM_TTL_SECONDS: number;/**- * Postgres `statement_timeout` for app and migrations (same pool).- * Env: `POSTGRES_STATEMENT_TIMEOUT_MS`. Default 60000.+ * TTL retained after `turn.done` so subscribers can drain remaining events.+ * Env: `TURN_STREAM_POST_COMPLETION_TTL_SECONDS`. Default 300.*/- POSTGRES_STATEMENT_TIMEOUT_MS: number;+ TURN_STREAM_POST_COMPLETION_TTL_SECONDS: number;/**- * Postgres `idle_in_transaction_session_timeout` for app and migrations (same pool).- * Env: `POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`. Default 60000.+ * Max ms to keep a turn subscription open.+ * Env: `TURN_SUBSCRIBE_TIMEOUT_MS`. Default 600000.*/- POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: number;- /** Peering URL shared by all replicas; undefined in single-binary mode. Env: `REDIS_URL`. */- REDIS_URL: string | undefined;+ TURN_SUBSCRIBE_TIMEOUT_MS: number;/*** Max ms to wait for a peer executor's reply before failing with 424.* Env: `REDIS_REQUEST_REPLY_TIMEOUT_MS`. Default 60000.+ * Only used when a Redis client is wired (distributed mode).*/REDIS_REQUEST_REPLY_TIMEOUT_MS: number;/*** How often this process refreshes its peering heartbeat key.* Env: `REDIS_REQUEST_REPLY_HEARTBEAT_INTERVAL_MS`. Default 5000.+ * Only used when a Redis client is wired (distributed mode).*/REDIS_REQUEST_REPLY_HEARTBEAT_INTERVAL_MS: number;/*** TTL for reply values so abandoned reply keys are reclaimed.* Env: `REDIS_REQUEST_REPLY_REPLY_TTL_MS`. Default 120000.+ * Only used when a Redis client is wired (distributed mode).*/REDIS_REQUEST_REPLY_REPLY_TTL_MS: number;/*** Sleep between reply poll attempts while waiting on a peer.* Env: `REDIS_REQUEST_REPLY_POLL_INTERVAL_MS`. Default 500.+ * Only used when a Redis client is wired (distributed mode).*/REDIS_REQUEST_REPLY_POLL_INTERVAL_MS: number;+}++export type StandaloneServerConfiguration = SharedServerConfiguration & {/**- * TTL for a running turn's resumable event stream.- * Env: `TURN_STREAM_TTL_SECONDS`. Default execution timeout + 300.+ * Single-process topology: SQLite persistence, no Redis / executor peering.+ * Env: `STANDALONE`. Default: true.*/- TURN_STREAM_TTL_SECONDS: number;+ STANDALONE: true;/**- * TTL retained after `turn.done` so subscribers can drain remaining events.- * Env: `TURN_STREAM_POST_COMPLETION_TTL_SECONDS`. Default 300.+ * Absolute SQLite database file path.+ * Env: `SQLITE_PATH` (optional). Default: env-paths data dir + `db.sqlite`.*/- TURN_STREAM_POST_COMPLETION_TTL_SECONDS: number;+ SQLITE_PATH: string;+};++export type DistributedServerConfiguration = SharedServerConfiguration & {/**- * Max ms to keep a turn subscription open.- * Env: `TURN_SUBSCRIBE_TIMEOUT_MS`. Default 600000.+ * Multi-replica topology: Postgres persistence + Redis executor peering.+ * Env: `STANDALONE`. Default: true (so this branch requires an explicit `false`).*/- TURN_SUBSCRIBE_TIMEOUT_MS: number;-}+ STANDALONE: false;+ /**+ * Postgres connection string derived from `POSTGRES_*` (not read from env directly).+ * Form: `postgres://USER:PASSWORD@HOST:PORT/DB` with user/password URL-encoded.+ */+ DATABASE_URL: string;+ /** Max connections in the `pg` Pool. Env: `DATABASE_POOL_MAX`. Default 10. */+ DATABASE_POOL_MAX: number;+ /**+ * Postgres `statement_timeout` for app and migrations (same pool).+ * Env: `POSTGRES_STATEMENT_TIMEOUT_MS`. Default 60000.+ */+ POSTGRES_STATEMENT_TIMEOUT_MS: number;+ /**+ * Postgres `idle_in_transaction_session_timeout` for app and migrations (same pool).+ * Env: `POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`. Default 60000.+ */+ POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: number;+ /** Peering URL shared by all replicas. Env: `REDIS_URL`. Default `redis://localhost:6379`. */+ REDIS_URL: string;+};++export type ServerConfiguration = StandaloneServerConfiguration | DistributedServerConfiguration;// ============================================================================// CONFIGURATION VALUES// ============================================================================-const postgresUser = requireNonEmptyEnv('POSTGRES_USER');-const postgresPassword = requireNonEmptyEnv('POSTGRES_PASSWORD');-const postgresDb = requireNonEmptyEnv('POSTGRES_DB');-const postgresHost = requireNonEmptyEnv('POSTGRES_HOST');-const postgresPort = parsePositiveInt({- envKey: 'POSTGRES_PORT',- raw: requireNonEmptyEnv('POSTGRES_PORT'),- defaultValue: 5432,-});const serverExecutionTimeoutSeconds = parsePositiveInt({envKey: 'SERVER_EXECUTION_TIMEOUT_SECONDS',raw: getEnv('SERVER_EXECUTION_TIMEOUT_SECONDS'),defaultValue: 600,});-const singleBinary = parseBoolean({- envKey: 'SINGLE_BINARY',- raw: getEnv('SINGLE_BINARY'),+const standalone = parseBoolean({+ envKey: 'STANDALONE',+ raw: getEnv('STANDALONE'),defaultValue: true,});-const mcpRequestTimeoutMs = parsePositiveInt({- envKey: 'MCP_REQUEST_TIMEOUT_MS',- raw: getEnv('MCP_REQUEST_TIMEOUT_MS'),- defaultValue: 4 * 60 * 1000,-});-const mcpConnectTimeoutMs = parsePositiveInt({- envKey: 'MCP_CONNECT_TIMEOUT_MS',- raw: getEnv('MCP_CONNECT_TIMEOUT_MS'),- defaultValue: 30 * 1000,-});+const port = parsePort(getEnv('PORT'));++const shared: SharedServerConfiguration = {+ PORT: port,+ EXECUTOR_ID: standalone ? LOCAL_EXECUTOR_ID : randomAlphanumeric(6),+ MODEL_CATALOG_PATH: resolveOptionalPathEnv('MODEL_CATALOG_PATH'),+ MCP_CATALOG_PATH: resolveOptionalPathEnv('MCP_CATALOG_PATH'),+ SKILL_CATALOG_PATH: resolveOptionalPathEnv('SKILL_CATALOG_PATH'),+ SANDBOX_CATALOG_PATH: resolveOptionalPathEnv('SANDBOX_CATALOG_PATH'),+ FRONTEND_DIR: resolveFrontendDir(),+ PUBLIC_BASE_URL: resolvePublicBaseUrl(port),-const configuration: ServerConfiguration = {- PORT: parsePort(getEnv('PORT')),- EXECUTOR_ID: resolveExecutorId(singleBinary),- MODEL_CATALOG_PATH: (() => {- const override = getEnv('MODEL_CATALOG_PATH');- return override === undefined || override === '' ? undefined : path.resolve(override);- })(),- MCP_CATALOG_PATH: (() => {- const override = getEnv('MCP_CATALOG_PATH');- return override === undefined || override === '' ? undefined : path.resolve(override);- })(),- SKILL_CATALOG_PATH: (() => {- const override = getEnv('SKILL_CATALOG_PATH');- return override === undefined || override === '' ? undefined : path.resolve(override);- })(),- SANDBOX_CATALOG_PATH: (() => {- const override = getEnv('SANDBOX_CATALOG_PATH');- return override === undefined || override === '' ? undefined : path.resolve(override);- })(),- FRONTEND_DIR: path.resolve(getEnv('FRONTEND_DIR', { defaultValue: DEFAULT_FRONTEND_DIR }) ?? DEFAULT_FRONTEND_DIR),- MCP_REQUEST_TIMEOUT_MS: mcpRequestTimeoutMs,- MCP_CONNECT_TIMEOUT_MS: mcpConnectTimeoutMs,- PUBLIC_BASE_URL: requireNonEmptyEnv('PUBLIC_BASE_URL'),+ MCP_REQUEST_TIMEOUT_MS: parsePositiveInt({+ envKey: 'MCP_REQUEST_TIMEOUT_MS',+ raw: getEnv('MCP_REQUEST_TIMEOUT_MS'),+ defaultValue: 4 * 60 * 1000,+ }),+ MCP_CONNECT_TIMEOUT_MS: parsePositiveInt({+ envKey: 'MCP_CONNECT_TIMEOUT_MS',+ raw: getEnv('MCP_CONNECT_TIMEOUT_MS'),+ defaultValue: 30 * 1000,+ }),OAUTH_CLIENT_NAME: getEnv('OAUTH_CLIENT_NAME', { defaultValue: 'truefoundry-harness' }) ?? 'truefoundry-harness',SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD: parsePositiveInt({envKey: 'SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD',@@ -318,29 +407,21 @@ const configuration: ServerConfiguration = {defaultValue: 30,}),SERVER_EXECUTION_TIMEOUT_SECONDS: serverExecutionTimeoutSeconds,- DATABASE_URL: buildPostgresConnectionString({- user: postgresUser,- password: postgresPassword,- host: postgresHost,- port: postgresPort,- database: postgresDb,- }),- DATABASE_POOL_MAX: parsePositiveInt({- envKey: 'DATABASE_POOL_MAX',- raw: getEnv('DATABASE_POOL_MAX'),- defaultValue: 10,+ TURN_STREAM_TTL_SECONDS: parsePositiveInt({+ envKey: 'TURN_STREAM_TTL_SECONDS',+ raw: getEnv('TURN_STREAM_TTL_SECONDS'),+ defaultValue: serverExecutionTimeoutSeconds + 300,}),- POSTGRES_STATEMENT_TIMEOUT_MS: parsePositiveInt({- envKey: 'POSTGRES_STATEMENT_TIMEOUT_MS',- raw: getEnv('POSTGRES_STATEMENT_TIMEOUT_MS'),- defaultValue: 60_000,+ TURN_STREAM_POST_COMPLETION_TTL_SECONDS: parsePositiveInt({+ envKey: 'TURN_STREAM_POST_COMPLETION_TTL_SECONDS',+ raw: getEnv('TURN_STREAM_POST_COMPLETION_TTL_SECONDS'),+ defaultValue: 300,}),- POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: parsePositiveInt({- envKey: 'POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS',- raw: getEnv('POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS'),- defaultValue: 60_000,+ TURN_SUBSCRIBE_TIMEOUT_MS: parsePositiveInt({+ envKey: 'TURN_SUBSCRIBE_TIMEOUT_MS',+ raw: getEnv('TURN_SUBSCRIBE_TIMEOUT_MS'),+ defaultValue: 600_000,}),- REDIS_URL: resolveRedisUrl(singleBinary),REDIS_REQUEST_REPLY_TIMEOUT_MS: parsePositiveInt({envKey: 'REDIS_REQUEST_REPLY_TIMEOUT_MS',raw: getEnv('REDIS_REQUEST_REPLY_TIMEOUT_MS'),@@ -361,21 +442,34 @@ const configuration: ServerConfiguration = {raw: getEnv('REDIS_REQUEST_REPLY_POLL_INTERVAL_MS'),defaultValue: 500,}),- TURN_STREAM_TTL_SECONDS: parsePositiveInt({- envKey: 'TURN_STREAM_TTL_SECONDS',- raw: getEnv('TURN_STREAM_TTL_SECONDS'),- defaultValue: serverExecutionTimeoutSeconds + 300,- }),- TURN_STREAM_POST_COMPLETION_TTL_SECONDS: parsePositiveInt({- envKey: 'TURN_STREAM_POST_COMPLETION_TTL_SECONDS',- raw: getEnv('TURN_STREAM_POST_COMPLETION_TTL_SECONDS'),- defaultValue: 300,- }),- TURN_SUBSCRIBE_TIMEOUT_MS: parsePositiveInt({- envKey: 'TURN_SUBSCRIBE_TIMEOUT_MS',- raw: getEnv('TURN_SUBSCRIBE_TIMEOUT_MS'),- defaultValue: 600_000,- }),-} as const;+};++const configuration: ServerConfiguration = standalone+ ? {+ ...shared,+ STANDALONE: true,+ SQLITE_PATH: resolveSqlitePath(),+ }+ : {+ ...shared,+ STANDALONE: false,+ DATABASE_URL: resolvePostgresDatabaseUrl(),+ DATABASE_POOL_MAX: parsePositiveInt({+ envKey: 'DATABASE_POOL_MAX',+ raw: getEnv('DATABASE_POOL_MAX'),+ defaultValue: 10,+ }),+ POSTGRES_STATEMENT_TIMEOUT_MS: parsePositiveInt({+ envKey: 'POSTGRES_STATEMENT_TIMEOUT_MS',+ raw: getEnv('POSTGRES_STATEMENT_TIMEOUT_MS'),+ defaultValue: 60_000,+ }),+ POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: parsePositiveInt({+ envKey: 'POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS',+ raw: getEnv('POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS'),+ defaultValue: 60_000,+ }),+ REDIS_URL: resolveRedisUrl(),+ };export default configuration;diff --git a/packages/server/src/db/migrateSqlite.ts b/packages/server/src/db/migrateSqlite.tsindex b2e275932..0bfc98eb2 100644--- a/packages/server/src/db/migrateSqlite.ts+++ b/packages/server/src/db/migrateSqlite.ts@@ -9,8 +9,7 @@ import type { Database } from './sqlite/types';/*** Runs all pending SQLite migrations.*- * Test / packaging helper only — do not import from `main` or `migrate-cli`.- * Production startup and `pnpm migrate` run Postgres via `migratePostgres`.+ * Used at sqlite startup and by SQLite store tests.* Resolves `…/sqlite/migrations` next to this module (source or `dist/`).*/export async function migrateSqliteToLatest(db: Kysely<Database>): Promise<void> {diff --git a/packages/server/src/db/postgres/migrate-cli.ts b/packages/server/src/db/postgres/migrate-cli.tsindex dc779a8cb..a566e82cc 100644--- a/packages/server/src/db/postgres/migrate-cli.ts+++ b/packages/server/src/db/postgres/migrate-cli.ts@@ -1,12 +1,18 @@/*** Run pending Postgres migrations and exit.- * Usage: `pnpm migrate` from packages/server.- * SQLite migrations are built into dist for packaging but are not run here.+ * Usage: `pnpm migrate` from packages/server with `STANDALONE=false`.+ * SQLite migrations run automatically when the server boots in standalone mode.*/import configuration from '../../config';import { migrateToLatest } from '../migratePostgres';import { createDb } from './client';+if (configuration.STANDALONE) {+ throw new Error(+ 'pnpm migrate targets Postgres only; set STANDALONE=false (and provide POSTGRES_* / Redis env as needed). SQLite migrations run on standalone server boot.',+ );+}+const db = createDb({connectionString: configuration.DATABASE_URL,poolMax: configuration.DATABASE_POOL_MAX,diff --git a/packages/server/src/main.ts b/packages/server/src/main.tsindex 1275bb0bf..dcf8c9075 100644--- a/packages/server/src/main.ts+++ b/packages/server/src/main.ts@@ -1,58 +1,172 @@/**- * Server entry point: validates config, migrates Postgres, wires DB stores- * and starts the HTTP server. Any config, migration, or store error aborts startup.- * SQLite migrations are packaged under dist/ but are not run at startup.+ * Server entry point: validates config, migrates the selected database, wires+ * stores, and starts the HTTP server. Any config, migration, or store error+ * aborts startup.+ *+ * `STANDALONE=true` (default): SQLite, no Redis. `STANDALONE=false`: Postgres + Redis.+ *+ * Config is validated at import time (`./config`). Runtime startup failures+ * (migrate, Redis, listen) are caught below and exit non-zero. SQLite vs+ * Postgres store modules stay dynamic so only the active engine is loaded.*/+import { mkdir } from 'node:fs/promises';+import path from 'node:path';++let configuration: typeof import('./config').default;++try {+ ({ default: configuration } = await import('./config'));+} catch (error) {+ console.error(+ 'Failed to start server: Failed to load configuration:',+ error instanceof Error ? error.message : error,+ );+ process.exit(1);+}+import { serve } from '@hono/node-server';-import type { TurnStreamingEvent } from '@truefoundry/utils-core/agent-session';+import {+ CancellationReason,+ Sessions,+ type ISessionStore,+ type TurnStreamingEvent,+} from '@truefoundry/utils-core/agent-session';+import { RequestReplyExecutor, RequestReplyRouter } from '@truefoundry/utils-core/request-reply';import type { RedisClientType } from 'redis';-import winston from 'winston';+import winston, { type Logger } from 'winston';-try {+import { createServerApp } from './app';+import { McpCatalog } from './catalog/McpCatalog';+import { ModelCatalog } from './catalog/ModelCatalog';+import { SandboxCatalog } from './catalog/SandboxCatalog';+import { SkillCatalog } from './catalog/SkillCatalog';+import { type DistributedServerConfiguration } from './config';+import type { IMcpServerStore } from './db/mcpServerStore';+import type { IModelProviderStore } from './db/modelProviderStore';+import type { ISandboxProviderStore } from './db/sandboxProviderStore';+import type { ISkillStore } from './db/skillStore';+import { mountFrontend } from './frontend';+import type { IOAuthTokenStore } from './mcp/auth/types';+import { ActiveTurnRegistry } from './runtime/activeTurns';+import { EventSubscriptionRegistry } from './runtime/event-subscription';++/** Persistence + optional Redis wired for the selected topology. */+interface ServerPersistence {+ sessionStore: ISessionStore;+ modelProviderStore: IModelProviderStore;+ mcpServerStore: IMcpServerStore;+ tokenStore: IOAuthTokenStore;+ skillStore: ISkillStore;+ sandboxProviderStore: ISandboxProviderStore;+ destroyDb: () => Promise<void>;+ redis: RedisClientType | undefined;+}++/** SQLite stores; Redis unused (executor peering disabled). */+async function createStandalonePersistence(options: {+ sqlitePath: string;+ logger: Logger;+}): Promise<ServerPersistence> {+ const { sqlitePath, logger } = options;+ await mkdir(path.dirname(sqlitePath), { recursive: true });+ const [{ createSqliteDb }, { migrateSqliteToLatest }, sqliteStores] = await Promise.all([+ import('./db/sqlite/client'),+ import('./db/migrateSqlite'),+ Promise.all([+ import('./db/sqlite/session-store/SqliteSessionStore'),+ import('./db/sqlite/model-provider-store/SqliteModelProviderStore'),+ import('./db/sqlite/mcp-server-store/SqliteMcpServerStore'),+ import('./db/sqlite/token-store/SqliteOAuthTokenStore'),+ import('./db/sqlite/skill-store/SqliteSkillStore'),+ import('./db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore'),+ ]),+ ]);+ const [+ { SqliteSessionStore },+ { SqliteModelProviderStore },+ { SqliteMcpServerStore },+ { SqliteOAuthTokenStore },+ { SqliteSkillStore },+ { SqliteSandboxProviderStore },+ ] = sqliteStores;++ const db = createSqliteDb(sqlitePath);+ await migrateSqliteToLatest(db);+ logger.info(`Standalone mode: sqlite at ${sqlitePath}`);+ logger.info('Standalone mode: executor peering disabled and Redis unused');++ return {+ sessionStore: new SqliteSessionStore(db),+ modelProviderStore: new SqliteModelProviderStore(db),+ mcpServerStore: new SqliteMcpServerStore(db),+ tokenStore: new SqliteOAuthTokenStore(db),+ skillStore: new SqliteSkillStore(db),+ sandboxProviderStore: new SqliteSandboxProviderStore(db),+ destroyDb: () => db.destroy(),+ redis: undefined,+ };+}++/** Postgres stores + Redis for executor peering. */+async function createDistributedPersistence(options: {+ configuration: DistributedServerConfiguration;+ logger: Logger;+}): Promise<ServerPersistence> {+ const { configuration, logger } = options;+ const {+ DATABASE_URL: databaseUrl,+ DATABASE_POOL_MAX: databasePoolMax,+ POSTGRES_STATEMENT_TIMEOUT_MS: statementTimeoutMs,+ POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: idleInTransactionSessionTimeoutMs,+ REDIS_URL: redisUrl,+ EXECUTOR_ID: executorId,+ } = configuration;++ const [{ createDb }, { migrateToLatest }, { connectRedis }, postgresStores] = await Promise.all([+ import('./db/postgres/client'),+ import('./db/migratePostgres'),+ import('./runtime/redis'),+ Promise.all([+ import('./db/postgres/session-store/PostgresSessionStore'),+ import('./db/postgres/model-provider-store/PostgresModelProviderStore'),+ import('./db/postgres/mcp-server-store/PostgresMcpServerStore'),+ import('./db/postgres/token-store/PostgresOAuthTokenStore'),+ import('./db/postgres/skill-store/PostgresSkillStore'),+ import('./db/postgres/sandbox-provider-store/PostgresSandboxProviderStore'),+ ]),+ ]);const [- { createServerApp },- { mountFrontend },- { default: configuration },- { createDb },- { migrateToLatest },- { Sessions, CancellationReason },- { ActiveTurnRegistry },- { connectRedis },- { RequestReplyExecutor, RequestReplyRouter },{ PostgresSessionStore },- { EventSubscriptionRegistry },- { ModelCatalog },{ PostgresModelProviderStore },- { McpCatalog },{ PostgresMcpServerStore },{ PostgresOAuthTokenStore },- { SkillCatalog },{ PostgresSkillStore },- { SandboxCatalog },{ PostgresSandboxProviderStore },- ] = await Promise.all([- import('./app'),- import('./frontend'),- import('./config'),- import('./db/postgres/client'),- import('./db/migratePostgres'),- import('@truefoundry/utils-core/agent-session'),- import('./runtime/activeTurns'),- import('./runtime/redis'),- import('@truefoundry/utils-core/request-reply'),- import('./db/postgres/session-store/PostgresSessionStore'),- import('./runtime/event-subscription'),- import('./catalog/ModelCatalog'),- import('./db/postgres/model-provider-store/PostgresModelProviderStore'),- import('./catalog/McpCatalog'),- import('./db/postgres/mcp-server-store/PostgresMcpServerStore'),- import('./db/postgres/token-store/PostgresOAuthTokenStore'),- import('./catalog/SkillCatalog'),- import('./db/postgres/skill-store/PostgresSkillStore'),- import('./catalog/SandboxCatalog'),- import('./db/postgres/sandbox-provider-store/PostgresSandboxProviderStore'),- ]);+ ] = postgresStores;+ const db = createDb({+ connectionString: databaseUrl,+ poolMax: databasePoolMax,+ statementTimeoutMs,+ idleInTransactionSessionTimeoutMs,+ });+ await migrateToLatest(db);+ logger.info('Distributed mode: postgres');+ logger.info(`Executor id: ${executorId}`);++ return {+ sessionStore: new PostgresSessionStore(db),+ modelProviderStore: new PostgresModelProviderStore(db),+ mcpServerStore: new PostgresMcpServerStore(db),+ tokenStore: new PostgresOAuthTokenStore(db),+ skillStore: new PostgresSkillStore(db),+ sandboxProviderStore: new PostgresSandboxProviderStore(db),+ destroyDb: () => db.destroy(),+ redis: await connectRedis({ url: redisUrl, logger }),+ };+}++try {// Console logger shared by the server runtime (harness components require one).const logger = winston.createLogger({level: process.env['LOG_LEVEL'] ?? 'info',@@ -60,38 +174,33 @@ try {transports: [new winston.transports.Console()],});- const db = createDb({- connectionString: configuration.DATABASE_URL,- poolMax: configuration.DATABASE_POOL_MAX,- statementTimeoutMs: configuration.POSTGRES_STATEMENT_TIMEOUT_MS,- idleInTransactionSessionTimeoutMs: configuration.POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS,- });- await migrateToLatest(db);+ const {+ sessionStore,+ modelProviderStore,+ mcpServerStore,+ tokenStore,+ skillStore,+ sandboxProviderStore,+ destroyDb,+ redis,+ } = configuration.STANDALONE+ ? await createStandalonePersistence({ sqlitePath: configuration.SQLITE_PATH, logger })+ : await createDistributedPersistence({ configuration, logger });- const sessionStore = new PostgresSessionStore(db);- const skillStore = new PostgresSkillStore(db);const activeTurns = new ActiveTurnRegistry();-- let redis: RedisClientType | undefined;- if (configuration.REDIS_URL === undefined) {- logger.info('Single-binary mode: executor peering disabled and Redis unused');- } else {- logger.info(`Executor id: ${configuration.EXECUTOR_ID}`);- redis = await connectRedis({ url: configuration.REDIS_URL, logger });- }const requestReplyRouter = new RequestReplyRouter();const eventSubscriptions = new EventSubscriptionRegistry<TurnStreamingEvent>(redis);const app = createServerApp({modelCatalog: ModelCatalog.load(),- modelProviderStore: new PostgresModelProviderStore(db),mcpCatalog: McpCatalog.load(),- mcpServerStore: new PostgresMcpServerStore(db),- tokenStore: new PostgresOAuthTokenStore(db),skillCatalog: SkillCatalog.load(),- skillStore,sandboxCatalog: SandboxCatalog.load(),- sandboxProviderStore: new PostgresSandboxProviderStore(db),+ modelProviderStore,+ mcpServerStore,+ tokenStore,+ skillStore,+ sandboxProviderStore,sessionStore,sessions: new Sessions({ sessionStore }),activeTurns,@@ -106,7 +215,7 @@ try {} else {logger.warn(`No frontend build at ${configuration.FRONTEND_DIR}: serving the API only. ` +- 'Run `pnpm --filter frontend build` to serve the UI from here, or `pnpm dev:frontend` for UI work.',+ 'Run `pnpm --filter frontend build` (and copy via build:frontend-assets) to serve the UI, or `pnpm standalone:dev` / `pnpm dev` for Vite.',);}@@ -117,7 +226,7 @@ try {// the initial subscribe + heartbeat — the replica is reachable for peering// before the HTTP server starts.let requestReplySubscriber: RedisClientType | undefined;- let requestReplyExecutor: InstanceType<typeof RequestReplyExecutor> | undefined;+ let requestReplyExecutor: RequestReplyExecutor | undefined;if (redis) {requestReplySubscriber = redis.duplicate();requestReplySubscriber.on('error', (error: Error) => {@@ -186,7 +295,7 @@ try {error: error instanceof Error ? error.message : String(error),});});- await db.destroy();+ await destroyDb();process.exit(0);};process.on('SIGTERM', signal => {diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.tsindex 1787d1113..9ea6ba650 100644--- a/packages/server/tsup.config.ts+++ b/packages/server/tsup.config.ts@@ -2,7 +2,7 @@ import { readdirSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';-import { defineConfig } from 'tsup';+import { defineConfig, type Options } from 'tsup';const packageDir = path.dirname(fileURLToPath(import.meta.url));const srcDbDir = path.join(packageDir, 'src/db');@@ -19,19 +19,38 @@ function migrationEntries(engine: 'postgres' | 'sqlite'): Record<string, string>);}-export default defineConfig({- entry: {- main: 'src/main.ts',- // Emit both engines under dist/{postgres,sqlite}/migrations/.- // Only Postgres is applied at runtime (main) and via `pnpm migrate`.- ...migrationEntries('postgres'),- ...migrationEntries('sqlite'),- },+const shared: Options = {format: ['esm'],dts: false,splitting: false,sourcemap: true,- clean: true,target: 'esnext',outDir: 'dist',-});+};++// tsup builds every config here concurrently, so neither may use `clean`: it wipes the+// shared dist/ mid-flight and can delete the sibling config's output. The build script+// clears dist/ before invoking tsup instead.+export default defineConfig([+ {+ ...shared,+ entry: {+ main: 'src/main.ts',+ // Emit both engines under dist/{postgres,sqlite}/migrations/.+ // Runtime selects migrations via STANDALONE (false → postgres, true → sqlite).+ ...migrationEntries('postgres'),+ ...migrationEntries('sqlite'),+ },+ },+ {+ ...shared,+ entry: {+ cli: 'src/cli.ts',+ },+ // Keep cli as a thin launcher that dynamically imports ./main.js.+ external: ['./main.js'],+ banner: {+ js: '#!/usr/bin/env node',+ },+ },+]);diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 08afe18fc..6f6b3fb99 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -222,6 +222,9 @@ importers:better-sqlite3:specifier: ^13.0.2version: 13.0.2+ env-paths:+ specifier: ^4.0.0+ version: 4.0.0hono:specifier: ^4.12.34version: 4.13.0@@ -3653,6 +3656,10 @@ packages:resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}engines: {node: '>=0.12'}+ resolution: {integrity: sha512-pxP8eL2SwwaTRi/KHYwLYXinDs7gL3jxFcBYmEdYfZmZXbaVDvdppd0XBU8qVz03rDfKZMXg1omHCbsJjZrMsw==}+ engines: {node: '>=20'}+resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}engines: {node: '>=18'}@@ -4226,6 +4233,10 @@ packages:resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}+ resolution: {integrity: sha512-4SrR7AdnY11LHfDKTZY1u6Ga3RuxZdl3YKWWShO5iyuG5h8QS4GD2tOb04peBJ5I7pXbR+CGBNEhTcwK+FzN3g==}+ engines: {node: '>=20'}+resolution: {integrity: sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==}engines: {node: '>=8'}@@ -9459,6 +9470,10 @@ snapshots:+ dependencies:+ is-safe-filename: 0.1.1+@@ -10212,6 +10227,8 @@ snapshots:+ [email protected]: {}+