The open-source agent harness - the runtime layer that turns an LLM into a working agent.
feat: Entrypoint for schedule controller (#542)
Sujai Kumar Gupta55cc5e700b9b
diff --git a/.changeset/controller-entry-point.md b/.changeset/controller-entry-point.mdnew file mode 100644index 000000000..8b358c301--- /dev/null+++ b/.changeset/controller-entry-point.md@@ -0,0 +1,5 @@+---+"@truefoundry/trueforge": patch+---++Add a dedicated controller entry point (`dist/controller-main.js`) that runs the periodic control loops (schedule dispatch) as a single-replica process for distributed mode (`STANDALONE=false`). It targets the server API via the new `SERVER_URL` env (default `http://localhost:$PORT`). Standalone mode keeps running the controller inside the server process.diff --git a/.railway/railway.ts b/.railway/railway.tsindex 563a190c3..264b7409c 100644--- a/.railway/railway.ts+++ b/.railway/railway.ts@@ -60,7 +60,32 @@ export default defineRailway(_ctx => {},});+ // Schedule controller: a second service off the same repo/image that runs the+ // periodic control loops (schedule dispatch). Must run as exactly one replica.+ // It talks to Postgres and hands due runs to the app over Railway's private+ // network (SERVER_URL); it needs no public domain or healthcheck.+ const controller = service('trueforge-controller', {+ source: github('truefoundry/trueforge'),+ startCommand: 'node dist/controller-main.js',+ replicas: 1,+ deploy: {+ restartPolicyType: 'ON_FAILURE',+ restartPolicyMaxRetries: 5,+ // Single-owner invariant: never run old + new controller at once on redeploy.+ overlapSeconds: 0,+ // Above GRACEFUL_TIMEOUT_SECONDS (30) so SIGKILL does not cut off loop drain.+ drainingSeconds: 35,+ },+ env: {+ RAILWAY_DOCKERFILE_PATH: 'Dockerfile.dev',+ STANDALONE: 'false',+ DATABASE_URL: db.env.DATABASE_URL,+ // Reaches the app over Railway private networking (no public egress).+ SERVER_URL: 'http://${{trueforge.RAILWAY_PRIVATE_DOMAIN}}:${{trueforge.PORT}}',+ },+ });+return project('trueforge', {- resources: [group('TrueForge', [db, cache, app])],+ resources: [group('TrueForge', [db, cache, app, controller])],});});diff --git a/charts/trueforge/README.md b/charts/trueforge/README.mdindex a264a60b3..029b30cbb 100644--- a/charts/trueforge/README.md+++ b/charts/trueforge/README.md@@ -195,7 +195,7 @@ extraObjects:| Value | Default | Description || --------------------- | ----------------------------------- | ------------------------------------- |-| `replicaCount` | `1` | Number of server replicas. |+| `server.replicaCount` | `1` | Number of server replicas. || `image.repository` | `tfy.jfrog.io/tfy-images/trueforge` | Image repository. || `image.tag` | chart `appVersion` | Image tag; stamped on release. || `server.publicBaseUrl`| `""` | Public origin for OAuth/OIDC callbacks (required for MCP OAuth / OIDC). |@@ -211,7 +211,10 @@ extraObjects:| `securityContext` | read-only root FS + drop all capabilities | Container-level restricted security defaults. || `resources` | 100m/256Mi requests, 200m/512Mi limits | Container CPU, memory, and ephemeral-storage requests/limits. |-Also available (defaults inert): `strategy`, `priorityClassName`,+The server uses a RollingUpdate strategy by default (`server.strategy`); the+controller is fixed to a single replica with `Recreate` and exposes neither.++Also available (defaults inert): `priorityClassName`,`topologySpreadConstraints`, `initContainers`, `extraContainers`,`extraVolumes`, `extraVolumeMounts`, `service.annotations`, `service.labels`,`startupProbe`.diff --git a/charts/trueforge/templates/_helpers.tpl b/charts/trueforge/templates/_helpers.tplindex a8e398b8b..a5618d7f9 100644--- a/charts/trueforge/templates/_helpers.tpl+++ b/charts/trueforge/templates/_helpers.tpl@@ -48,6 +48,41 @@ app.kubernetes.io/name: {{ include "trueforge.name" . }}app.kubernetes.io/instance: {{ .Release.Name }}{{- end }}+{{/*+Controller selector labels. A distinct app name (…-controller) keeps the server+Service (which selects trueforge.selectorLabels) from ever routing HTTP traffic+to controller pods, which run no HTTP server.+*/}}+{{- define "trueforge.controller.selectorLabels" -}}+app.kubernetes.io/name: {{ include "trueforge.name" . }}-controller+app.kubernetes.io/instance: {{ .Release.Name }}+{{- end }}++{{/*+Controller labels.+*/}}+{{- define "trueforge.controller.labels" -}}+helm.sh/chart: {{ include "trueforge.chart" . }}+{{ include "trueforge.controller.selectorLabels" . }}+{{- if .Chart.AppVersion }}+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}+{{- end }}+app.kubernetes.io/managed-by: {{ .Release.Service }}+app.kubernetes.io/component: controller+{{- end }}++{{/*+Base URL the controller uses to reach the server API. Defaults to the in-cluster+server Service when controller.serverUrl is empty.+*/}}+{{- define "trueforge.controller.serverUrl" -}}+{{- if .Values.controller.serverUrl -}}+{{- .Values.controller.serverUrl -}}+{{- else -}}+{{- printf "http://%s:%v" (include "trueforge.fullname" .) .Values.service.port -}}+{{- end -}}+{{- end }}+{{/*Service account name.*/}}diff --git a/charts/trueforge/templates/controller-deployment.yaml b/charts/trueforge/templates/controller-deployment.yamlnew file mode 100644index 000000000..d0f59ab0a--- /dev/null+++ b/charts/trueforge/templates/controller-deployment.yaml@@ -0,0 +1,99 @@+{{- if .Values.controller.enabled }}+apiVersion: apps/v1+kind: Deployment+metadata:+ name: {{ include "trueforge.fullname" . }}-controller+ labels:+ {{- include "trueforge.controller.labels" . | nindent 4 }}+spec:+ # The controller MUST run as exactly one replica per database, so it is never+ # scaled or autoscaled. Recreate avoids two controllers overlapping mid-rollout.+ replicas: 1+ strategy:+ type: Recreate+ selector:+ matchLabels:+ {{- include "trueforge.controller.selectorLabels" . | nindent 6 }}+ template:+ metadata:+ labels:+ {{- include "trueforge.controller.selectorLabels" . | nindent 8 }}+ {{- with .Values.podLabels }}+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.podAnnotations }}+ annotations:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ spec:+ {{- with .Values.imagePullSecrets }}+ imagePullSecrets:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ serviceAccountName: {{ include "trueforge.serviceAccountName" . }}+ {{- with .Values.podSecurityContext }}+ securityContext:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.priorityClassName }}+ priorityClassName: {{ . | quote }}+ {{- end }}+ # Above the controller's GRACEFUL_TIMEOUT_SECONDS so SIGKILL does not cut off loop drain.+ terminationGracePeriodSeconds: {{ add .Values.server.gracefulTimeoutSeconds 5 }}+ containers:+ - name: controller+ image: {{ include "trueforge.image" . | quote }}+ imagePullPolicy: {{ .Values.image.pullPolicy }}+ command:+ {{- toYaml .Values.controller.command | nindent 12 }}+ {{- with .Values.securityContext }}+ securityContext:+ {{- toYaml . | nindent 12 }}+ {{- end }}+ env:+ {{- include "trueforge.server.env" . | nindent 12 }}+ - name: SERVER_URL+ value: {{ include "trueforge.controller.serverUrl" . | quote }}+ {{- with .Values.controller.extraEnv }}+ {{- toYaml . | nindent 12 }}+ {{- end }}+ {{- with .Values.controller.resources }}+ resources:+ {{- toYaml . | nindent 12 }}+ {{- end }}+ volumeMounts:+ - name: tmp+ mountPath: /tmp+ {{- with .Values.extraVolumeMounts }}+ {{- toYaml . | nindent 12 }}+ {{- end }}+ {{- $resources := default dict .Values.controller.resources }}+ {{- $limits := default dict (index $resources "limits") }}+ volumes:+ - name: tmp+ {{- with index $limits "ephemeral-storage" }}+ emptyDir:+ sizeLimit: {{ . | quote }}+ {{- else }}+ emptyDir: {}+ {{- end }}+ {{- with .Values.extraVolumes }}+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.nodeSelector }}+ nodeSelector:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.affinity }}+ affinity:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.tolerations }}+ tolerations:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.topologySpreadConstraints }}+ topologySpreadConstraints:+ {{- toYaml . | nindent 8 }}+ {{- end }}+{{- end }}diff --git a/charts/trueforge/templates/deployment.yaml b/charts/trueforge/templates/deployment.yamlindex 14a86c767..d749fd3f0 100644--- a/charts/trueforge/templates/deployment.yaml+++ b/charts/trueforge/templates/deployment.yaml@@ -6,9 +6,9 @@ metadata:{{- include "trueforge.labels" . | nindent 4 }}spec:{{- if not .Values.autoscaling.enabled }}- replicas: {{ .Values.replicaCount }}+ replicas: {{ .Values.server.replicaCount }}{{- end }}- {{- with .Values.strategy }}+ {{- with .Values.server.strategy }}strategy:{{- toYaml . | nindent 4 }}{{- end }}diff --git a/charts/trueforge/values.yaml b/charts/trueforge/values.yamlindex f5f3cb379..5b13fad53 100644--- a/charts/trueforge/values.yaml+++ b/charts/trueforge/values.yaml@@ -1,6 +1,5 @@# Default values for the trueforge chart.-replicaCount: 1image:repository: tfy.jfrog.io/tfy-images/trueforge# Tag defaults to chart appVersion when empty. Prod chart-release PRs set this@@ -34,13 +33,6 @@ securityContext:- ALL# Optional PriorityClass for the server pods.priorityClassName: ""-# Rolling update controls (omit keys you do not want to set).-strategy: {}-# strategy:-# type: RollingUpdate-# rollingUpdate:-# maxUnavailable: 0-# maxSurge: 1service:type: ClusterIP@@ -50,6 +42,14 @@ service:# Server runtime configuration. Keys map to environment variables read in# packages/trueforge/src/config.ts.server:+ # Number of server replicas (ignored when autoscaling.enabled is true).+ replicaCount: 1+ # Rolling update strategy for the server Deployment.+ strategy:+ type: RollingUpdate+ rollingUpdate:+ maxUnavailable: 0+ maxSurge: 1# Container port the server listens on (PORT).port: 8790# Public origin for MCP OAuth / OIDC callbacks (PUBLIC_BASE_URL).@@ -61,6 +61,32 @@ server:# Escape hatch for knobs not covered by configs.*. Each entry is a full env# item: {name, value} or {name, valueFrom: {secretKeyRef|configMapKeyRef: ...}}.extraEnv: []+# Schedule controller. A dedicated, single-replica Deployment that runs the+# periodic control loops (schedule dispatch). It MUST run as exactly one replica+# per database, so it is never autoscaled. It calls the server API over HTTP and+# reuses the server's Postgres/Redis env; it exposes no port and no Service.+controller:+ # Set false to skip the controller Deployment (schedules will not fire).+ enabled: true+ # Container command. Runs the controller entry from the published package inside+ # the image (root Dockerfile layout: /app/node_modules/@truefoundry/trueforge).+ command:+ - node+ - node_modules/@truefoundry/trueforge/dist/controller-main.js+ # Base URL the controller uses to reach the server (SERVER_URL).+ # Empty → the in-cluster server Service (http://<fullname>:<service.port>).+ serverUrl: ""+ # Extra env for the controller only; same item shape as server.extraEnv.+ extraEnv: []+ resources:+ requests:+ cpu: 50m+ memory: 128Mi+ ephemeral-storage: 128Mi+ limits:+ cpu: 100m+ memory: 256Mi+ ephemeral-storage: 256Mi# Application feature config (maps to env vars in packages/trueforge/src/config.ts).# clientSecret (and other secret-like fields) accept a string or# { valueFrom: { secretKeyRef: ... } }.diff --git a/docker-compose.yml b/docker-compose.ymlindex 0b3f3224b..577286c56 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -87,3 +87,30 @@ services:# cut off turn drain.stop_grace_period: 35srestart: unless-stopped++ # Schedule controller: runs the periodic control loops (schedule dispatch) as a separate service.+ controller:+ build:+ context: .+ dockerfile: Dockerfile.dev+ image: truefoundry-server:latest+ command: ['node', 'dist/controller-main.js']+ environment:+ NODE_ENV: production+ STANDALONE: 'false'+ POSTGRES_HOST: postgres+ POSTGRES_PORT: 5432+ # The controller is its own container, so localhost would be itself; `server` is+ # the compose DNS name that resolves to the server container.+ SERVER_URL: http://server:8790+ env_file:+ - path: packages/trueforge/.env+ required: true+ depends_on:+ postgres:+ condition: service_healthy+ server:+ condition: service_healthy+ # Above GRACEFUL_TIMEOUT_SECONDS (30) so SIGKILL does not cut off loop drain.+ stop_grace_period: 35s+ restart: unless-stoppeddiff --git a/package.json b/package.jsonindex 238f8811b..fbbf93b24 100644--- a/package.json+++ b/package.json@@ -36,6 +36,7 @@"standalone:dev": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge --filter frontend dev","standalone:start": "STANDALONE=true NODE_ENV=production pnpm --filter @truefoundry/trueforge start","start": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/trueforge start",+ "start:controller": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/trueforge start:controller","push-sandbox-image-to-daytona": "pnpm --filter @truefoundry/trueforge push-sandbox-image-to-daytona","test:frontend": "pnpm --filter frontend test","test:chart-version": "bash tests/scripts/resolve-chart-version.test.sh",diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.exampleindex 7d075ecf5..8aaa335d9 100644--- a/packages/trueforge/.env.example+++ b/packages/trueforge/.env.example@@ -98,6 +98,12 @@ REDIS_URL=redis://localhost:6379## fixed callback routes for server OIDC and MCP OAuth/DCR.# PUBLIC_BASE_URL=http://localhost:3000+## Base URL the dedicated controller process (dist/controller-main.js) uses to+## reach the server API. Only used when running the controller as its own process+## (STANDALONE=false). Defaults to http://localhost:$PORT; point it at the server+## Service in a split server/controller deployment.+# SERVER_URL=http://localhost:8790+## ---------------------------------------------------------------------------## MCP knobs.## ---------------------------------------------------------------------------diff --git a/packages/trueforge/package.json b/packages/trueforge/package.jsonindex 6b455e65d..fadc511c3 100644--- a/packages/trueforge/package.json+++ b/packages/trueforge/package.json@@ -35,9 +35,13 @@"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=trueforge-dev' NODE_ENV=development tsx watch --env-file=.env src/main.ts",- "dev": "pnpm run \"/^(build:gen:watch|dev:serve)$/\"",- "dev:no-watch": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx --env-file=.env src/main.ts",+ "dev": "pnpm run \"/^(build:gen:watch|dev:serve|dev:controller)$/\"",+ "dev:no-watch": "pnpm run \"/^(dev:serve:no-watch|dev:controller:no-watch)$/\"",+ "dev:serve:no-watch": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx --env-file=.env src/main.ts",+ "dev:controller": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx watch --env-file=.env src/controller-main.ts",+ "dev:controller:no-watch": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx --env-file=.env src/controller-main.ts","start": "NODE_ENV=production node --env-file=.env dist/main.js",+ "start:controller": "NODE_ENV=production node --env-file=.env dist/controller-main.js","push-sandbox-image-to-daytona": "node scripts/push-sandbox-image-to-daytona.mjs","migrate": "NODE_OPTIONS='--conditions=trueforge-dev' STANDALONE=false tsx --env-file=.env src/db/postgres/migrate-cli.ts","openapi:write": "pnpm run build:gen && NODE_OPTIONS='--conditions=trueforge-dev' tsx --env-file=.env.test scripts/write-openapi.ts",diff --git a/packages/trueforge/src/config.ts b/packages/trueforge/src/config.tsindex 5c87d6355..619844167 100644--- a/packages/trueforge/src/config.ts+++ b/packages/trueforge/src/config.ts@@ -432,6 +432,14 @@ export interface SharedServerConfiguration {* outside standalone development. Env: `PUBLIC_BASE_URL`.*/PUBLIC_BASE_URL: string;+ /**+ * Base URL the controller uses to reach the server's HTTP API when it runs as its+ * own process (`STANDALONE=false`, `dist/controller-main.js`). The control loops call+ * the server over HTTP. Env: `SERVER_URL`. Default: `http://localhost:$PORT`,+ * so in-cluster deployments MUST point this at the server Service. Unused in standalone+ * mode, where the server process owns the controller and targets itself on localhost.+ */+ SERVER_URL: string;/*** When set, models are listed from the TrueFoundry ServiceFoundry server and invoked* via the AI Gateway with the caller's token. Unset = local model-provider store.@@ -609,6 +617,8 @@ const shared: SharedServerConfiguration = {defaultValue: 500,}),PUBLIC_BASE_URL: getEnv('PUBLIC_BASE_URL', { defaultValue: '' }) ?? '',+ SERVER_URL:+ getEnv('SERVER_URL', { defaultValue: `http://localhost:${String(port)}` }) ?? `http://localhost:${String(port)}`,TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL: getEnv('TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL', { required: false }),TRUEFOUNDRY_MTLS_ENABLED: parseBoolean({envKey: 'TRUEFOUNDRY_MTLS_ENABLED',diff --git a/packages/trueforge/src/controller-main.ts b/packages/trueforge/src/controller-main.tsnew file mode 100644index 000000000..63fd27aec--- /dev/null+++ b/packages/trueforge/src/controller-main.ts@@ -0,0 +1,59 @@+/**+ * Controller entry point (`dist/controller-main.js`).+ *+ * Runs the periodic control loops (schedule dispatch, …) as a dedicated,+ * single-replica process for distributed mode (`STANDALONE=false`). The controller+ * must run in exactly ONE process per database (see `controller/Controller.ts`);+ * in standalone mode the server process already owns it, so this entry refuses to+ * start there.+ *+ * Migrations are owned by the server (`main.ts`). This process only connects to the+ * already-migrated database; the loops have per-pass error boundaries, so they retry+ * each tick until the schema is present. The loops call the server over HTTP at+ * `SERVER_URL`, so no Redis peering is wired here.+ */+import configuration from './config';+import { runController } from './controller';+import { createDb } from './db/postgres/client';+import { PostgresScheduleStore } from './db/postgres/schedule-store/PostgresScheduleStore';+import { createControllerLogger } from './logger';+import { PACKAGE_VERSION } from './packageVersion';++try {+ const logger = createControllerLogger({+ level: configuration.LOG_LEVEL,+ standalone: configuration.STANDALONE,+ version: PACKAGE_VERSION,+ });++ if (configuration.STANDALONE) {+ // Not an error: in standalone the server process owns the controller in-process, so a+ // dedicated controller has nothing to do. Exit cleanly (e.g. `pnpm standalone:dev` also+ // starts this script). Run with STANDALONE=false to use it as a dedicated process.+ logger.warn('Standalone mode (STANDALONE=true): the server runs the controller in-process; nothing to do here.');+ process.exit(0);+ }++ 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,+ });++ logger.info('Controller starting', {+ serverUrl: configuration.SERVER_URL,+ });++ runController({+ scheduleStore: new PostgresScheduleStore(db),+ withTransaction: callback => db.transaction().execute(callback),+ logger,+ baseUrl: configuration.SERVER_URL,+ gracefulTimeoutSeconds: configuration.GRACEFUL_TIMEOUT_SECONDS,+ onStopped: () => db.destroy(),+ });+} catch (error) {+ console.error('Failed to start controller:', error instanceof Error ? error.message : error);+ process.exit(1);+}diff --git a/packages/trueforge/src/logger.ts b/packages/trueforge/src/logger.tsindex 0c6479e57..2a4229350 100644--- a/packages/trueforge/src/logger.ts+++ b/packages/trueforge/src/logger.ts@@ -1,10 +1,12 @@/*** Process logger: human-readable lines in standalone mode, JSON otherwise.- * Both formats include `version` (defaultMeta) so hosted aggregators can filter.+ * JSON output carries `version` and `component` ('server' | 'controller') in defaultMeta+ * so hosted aggregators can tell the two processes apart; both are omitted from the+ * human-readable standalone format to keep local logs terse.*/import winston, { type Logger } from 'winston';-const STANDALONE_META_SKIP = new Set(['level', 'message', 'timestamp', 'version', 'stack', 'splat']);+const STANDALONE_META_SKIP = new Set(['level', 'message', 'timestamp', 'version', 'component', 'stack', 'splat']);export function shouldColorize(): boolean {const noColor = process.env['NO_COLOR'];@@ -69,11 +71,24 @@ function serverLogFormat(options: { standalone: boolean }): winston.Logform.Formreturn jsonFormat();}-export function createServerLogger(options: { level: string; standalone: boolean; version: string }): Logger {+function createLogger(options: {+ level: string;+ standalone: boolean;+ version: string;+ component: 'server' | 'controller';+}): Logger {return winston.createLogger({level: options.level,- defaultMeta: { version: options.version },+ defaultMeta: { version: options.version, component: options.component },format: serverLogFormat({ standalone: options.standalone }),transports: [new winston.transports.Console()],});}++export function createServerLogger(options: { level: string; standalone: boolean; version: string }): Logger {+ return createLogger({ ...options, component: 'server' });+}++export function createControllerLogger(options: { level: string; standalone: boolean; version: string }): Logger {+ return createLogger({ ...options, component: 'controller' });+}diff --git a/packages/trueforge/tsup.config.ts b/packages/trueforge/tsup.config.tsindex 6156c2f75..4e38e5256 100644--- a/packages/trueforge/tsup.config.ts+++ b/packages/trueforge/tsup.config.ts@@ -36,6 +36,7 @@ export default defineConfig([...shared,entry: {main: 'src/main.ts',+ 'controller-main': 'src/controller-main.ts',// Emit both engines under dist/{postgres,sqlite}/migrations/.// Runtime selects migrations via STANDALONE (false → postgres, true → sqlite)....migrationEntries('postgres'),