The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Add single-replica mode so Redis becomes optional. (#18)
pranjaltrvd9d157f1f2e56
diff --git a/docker-compose.yml b/docker-compose.ymlindex 2c2e6b6f1..73f329f48 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -51,6 +51,10 @@ services:# Compose network hosts — do not use packages/server/.env localhost values.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'REDIS_URL: redis://redis:6379# Secrets and Postgres credentials (MODEL_API_KEY, POSTGRES_USER, …).# `environment` above overrides any colliding keys from this file.diff --git a/packages/server/.env.example b/packages/server/.env.exampleindex 650b4e5a9..e2110da97 100644--- a/packages/server/.env.example+++ b/packages/server/.env.example@@ -19,10 +19,17 @@ PORT=8790# server logs a warning and serves the API only.# FRONTEND_DIR=../frontend/dist-# Required. 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.+# 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++# 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.REDIS_URL=redis://localhost:6379# Required. Default API key for the OpenAI-compatible API at models.yaml'sdiff --git a/packages/server/.env.test b/packages/server/.env.testindex b71dd426c..2de9f673d 100644--- a/packages/server/.env.test+++ b/packages/server/.env.test@@ -4,6 +4,5 @@ POSTGRES_PASSWORD=testPOSTGRES_DB=testPOSTGRES_HOST=localhostPOSTGRES_PORT=5432-REDIS_URL=redis://localhost:6379MODEL_API_KEY=testREGISTRY_DIR=registry-examplediff --git a/packages/server/package.json b/packages/server/package.jsonindex 80837f962..1935ca478 100644--- a/packages/server/package.json+++ b/packages/server/package.json@@ -13,9 +13,9 @@"predev:no-watch": "pnpm --filter @truefoundry/utils 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": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",+ "typecheck": "tsc --noEmit && tsc --noEmit -p tests/db/tsconfig.json && tsc --noEmit -p tests/unit/tsconfig.json","openapi:write": "NODE_OPTIONS='--conditions=development' tsx --env-file=.env.test scripts/write-openapi.ts",- "test": "NODE_OPTIONS='--conditions=development' tsx --env-file=.env.test --test \"src/**/*.test.ts\"",+ "test": "NODE_OPTIONS='--conditions=development' tsx --env-file=.env.test --test \"tests/unit/**/*.test.ts\"","test:store:postgres": "jest --config jest.store.postgres.config.cjs","test:store:sqlite": "jest --config jest.store.sqlite.config.cjs"},diff --git a/packages/server/scripts/write-openapi.ts b/packages/server/scripts/write-openapi.tsindex 558f85ed1..893562819 100644--- a/packages/server/scripts/write-openapi.ts+++ b/packages/server/scripts/write-openapi.ts@@ -9,7 +9,6 @@ import { InMemorySessionStore, Sessions } from '@truefoundry/utils/agent-sessionimport { RequestReplyRouter } from '@truefoundry/utils/request-reply';import { mkdirSync, writeFileSync } from 'node:fs';import path from 'node:path';-import { createClient, type RedisClientType } from 'redis';import winston from 'winston';import { buildOpenApiDocument, createServerApp } from '../src/app';import { ActiveTurnRegistry } from '../src/runtime/activeTurns';@@ -38,7 +37,6 @@ function canonicalise(value: unknown): unknown {// Unconnected stand-ins suffice: route registration never reads a dependency.const sessionStore = new InMemorySessionStore();-const redis: RedisClientType = createClient();const app = createServerApp({modelStore: ModelStore.load(),mcpStore: McpStore.load(),@@ -46,7 +44,6 @@ const app = createServerApp({sessionStore,sessions: new Sessions({ sessionStore }),activeTurns: new ActiveTurnRegistry(),- redis,requestReplyRouter: new RequestReplyRouter(),logger: winston.createLogger({ silent: true }),});diff --git a/packages/server/src/apis/sessions.ts b/packages/server/src/apis/sessions.tsindex 87690e0b6..ae1b403cb 100644--- a/packages/server/src/apis/sessions.ts+++ b/packages/server/src/apis/sessions.ts@@ -102,8 +102,8 @@ export interface SessionsRouterDeps {mcpStore: McpStore;/** Whether a sandbox provider is configured (SANDBOX_SETTINGS); gates spec admission. */sandboxSupported: boolean;- /** Primary Redis client (server-owned); used to reach peer executors. */- redis: RedisClientType;+ /** Reaches peer executors; undefined in single-binary mode. */+ redis?: RedisClientType | undefined;/** Request-reply dispatch table this replica serves; cancel registers here. */requestReplyRouter: RequestReplyRouter;}@@ -143,13 +143,20 @@ export function cancelSessionTurnPeerHandler(activeTurns: ActiveTurnRegistry): R};}+/** A registry to abort in, durable state to read, and a way to reach peers. */+export interface CancelTurnDeps {+ activeTurns: ActiveTurnRegistry;+ sessionStore: Pick<ISessionStore, 'getTurn'>;+ redis?: RedisClientType | undefined;+}+/*** Cancels the turn wherever it runs: locally or on the owning peer over Redis* request-reply. Callers state the motive; default is a plain client cancel.* Owner failures throw HTTPException (412 unreachable, 424 timed out).*/export async function cancelSessionTurn(- deps: Pick<SessionsRouterDeps, 'redis' | 'activeTurns' | 'sessionStore'>,+ deps: CancelTurnDeps,input: { sessionId: string; turnId: string; reason?: CancellationReason },): Promise<void> {const { sessionId, turnId, reason = CancellationReason.ClientCancelled } = input;@@ -165,7 +172,9 @@ export async function cancelSessionTurn(}const owner = executorFromTurnId(turnId);- if (owner !== configuration.EXECUTOR_ID) {+ // Without a Redis client there is no peer to ask, so an id naming another+ // replica falls through to the local lookup and finds nothing.+ if (owner !== configuration.EXECUTOR_ID && deps.redis) {try {const reply = await redisRequest<CancelPeerBody>({redis: deps.redis,diff --git a/packages/server/src/app.ts b/packages/server/src/app.tsindex 325d03950..2b8103c68 100644--- a/packages/server/src/app.ts+++ b/packages/server/src/app.ts@@ -46,8 +46,8 @@ export interface ServerDeps {activeTurns: ActiveTurnRegistry;/** Built at boot from SANDBOX_SETTINGS; undefined = sandbox unsupported. */sandboxFactory?: TurnSandboxFactory;- /** Primary Redis client (server-owned); carries executor peering. */- redis: RedisClientType;+ /** Primary Redis client (server-owned); undefined in single-binary mode. */+ redis?: RedisClientType | undefined;/** Request-reply dispatch table served by this replica's executor. */requestReplyRouter: RequestReplyRouter;logger: Logger;diff --git a/packages/server/src/config.ts b/packages/server/src/config.tsindex ec050f6a7..ddbe87b04 100644--- a/packages/server/src/config.ts+++ b/packages/server/src/config.ts@@ -156,6 +156,18 @@ export const parsePositiveInt = (options: {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 => {+ const { envKey, raw, defaultValue } = options;+ if (raw === undefined || raw.trim() === '') {+ return defaultValue;+ }+ const value = raw.trim().toLowerCase();+ if (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 });@@ -185,6 +197,25 @@ export const DEFAULT_PORT = 8790;/** Relative to the working directory, like REGISTRY_DIR; 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;+ }+ return requireNonEmptyEnv('REDIS_URL');+};++/** 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);+};+export interface ServerConfiguration {/** HTTP port the server listens on. Env: `PORT`. */PORT: number;@@ -263,13 +294,6 @@ export interface ServerConfiguration {DATABASE_URL: string;/** Max connections in the `pg` Pool. Env: `DATABASE_POOL_MAX`. Default 10. */DATABASE_POOL_MAX: number;- /**- * Redis connection URL shared by all replicas; carries executor peering- * (cross-replica turn cancel). Env: `REDIS_URL` (required).- */- REDIS_URL: string;- /** Unique id of this process. Not an env var. */- EXECUTOR_ID: string;/*** Max ms to wait for a peer executor's reply before failing with 424.* Env: `REDIS_REQUEST_REPLY_TIMEOUT_MS`. Default 60000.@@ -290,6 +314,10 @@ export interface ServerConfiguration {* Env: `REDIS_REQUEST_REPLY_POLL_INTERVAL_MS`. Default 500.*/REDIS_REQUEST_REPLY_POLL_INTERVAL_MS: number;+ /** Peering URL shared by all replicas; undefined in single-binary mode. Env: `REDIS_URL`. */+ REDIS_URL: string | undefined;+ /** Peering identity embedded in the turn ids this process mints; `local` in single-binary mode. */+ EXECUTOR_ID: string;}// ============================================================================@@ -306,6 +334,12 @@ const postgresPort = parsePositiveInt({defaultValue: 5432,});+const singleBinary = parseBoolean({+ envKey: 'SINGLE_BINARY',+ raw: getEnv('SINGLE_BINARY'),+ defaultValue: true,+});+const configuration: ServerConfiguration = {PORT: parsePort(getEnv('PORT')),REGISTRY_DIR: path.resolve(getEnv('REGISTRY_DIR', { defaultValue: 'registry' }) ?? 'registry'),@@ -350,8 +384,6 @@ const configuration: ServerConfiguration = {raw: getEnv('DATABASE_POOL_MAX'),defaultValue: 10,}),- REDIS_URL: requireNonEmptyEnv('REDIS_URL'),- EXECUTOR_ID: randomAlphanumeric(6),REDIS_REQUEST_REPLY_TIMEOUT_MS: parsePositiveInt({envKey: 'REDIS_REQUEST_REPLY_TIMEOUT_MS',raw: getEnv('REDIS_REQUEST_REPLY_TIMEOUT_MS'),@@ -372,6 +404,8 @@ const configuration: ServerConfiguration = {raw: getEnv('REDIS_REQUEST_REPLY_POLL_INTERVAL_MS'),defaultValue: 500,}),+ REDIS_URL: resolveRedisUrl(singleBinary),+ EXECUTOR_ID: resolveExecutorId(singleBinary),} as const;export default configuration;diff --git a/packages/server/src/main.ts b/packages/server/src/main.tsindex 97d46bd12..a01951423 100644--- a/packages/server/src/main.ts+++ b/packages/server/src/main.ts@@ -5,6 +5,7 @@* SQLite migrations are packaged under dist/ but are not run at startup.*/import { serve } from '@hono/node-server';+import type { RedisClientType } from 'redis';import winston from 'winston';try {@@ -56,10 +57,13 @@ try {const sandboxFactory = createServerSandboxFactory({ logger });const activeTurns = new ActiveTurnRegistry();- // Executor peering: this process's identity is embedded into turn ids so- // any replica can route a cancel to the owner over Redis request-reply.- logger.info(`Executor id: ${configuration.EXECUTOR_ID}`);- const redis = await connectRedis({ url: configuration.REDIS_URL, logger });+ 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 app = createServerApp({@@ -90,23 +94,27 @@ try {// this process owns its lifecycle. Connect before init() so init() awaits// the initial subscribe + heartbeat — the replica is reachable for peering// before the HTTP server starts.- const requestReplySubscriber = redis.duplicate();- requestReplySubscriber.on('error', (error: Error) => {- logger.error('[RedisSubscriber] Client error', { error: error.message });- });- await requestReplySubscriber.connect();- const requestReplyExecutor = new RequestReplyExecutor({- executorId: configuration.EXECUTOR_ID,- redis,- subscriberClient: requestReplySubscriber,- requestHandler: requestReplyRouter.createRequestHandler(),- logger,- options: {- heartbeatIntervalMs: configuration.REDIS_REQUEST_REPLY_HEARTBEAT_INTERVAL_MS,- replyTtlMs: configuration.REDIS_REQUEST_REPLY_REPLY_TTL_MS,- },- });- await requestReplyExecutor.init();+ let requestReplySubscriber: RedisClientType | undefined;+ let requestReplyExecutor: InstanceType<typeof RequestReplyExecutor> | undefined;+ if (redis) {+ requestReplySubscriber = redis.duplicate();+ requestReplySubscriber.on('error', (error: Error) => {+ logger.error('[RedisSubscriber] Client error', { error: error.message });+ });+ await requestReplySubscriber.connect();+ requestReplyExecutor = new RequestReplyExecutor({+ executorId: configuration.EXECUTOR_ID,+ redis,+ subscriberClient: requestReplySubscriber,+ requestHandler: requestReplyRouter.createRequestHandler(),+ logger,+ options: {+ heartbeatIntervalMs: configuration.REDIS_REQUEST_REPLY_HEARTBEAT_INTERVAL_MS,+ replyTtlMs: configuration.REDIS_REQUEST_REPLY_REPLY_TTL_MS,+ },+ });+ await requestReplyExecutor.init();+ }const server = serve({ fetch: app.fetch, port: configuration.PORT }, info => {console.log(`Agent server listening on http://localhost:${String(info.port)} (docs at /api/v1/docs)`);@@ -145,13 +153,13 @@ try {await closed;// Stop serving peer requests (waits for in-flight replies), then close// the clients this process owns: the subscriber duplicate and the primary.- await requestReplyExecutor.drain();- await requestReplySubscriber.close().catch((error: unknown) => {+ await requestReplyExecutor?.drain();+ await requestReplySubscriber?.close().catch((error: unknown) => {logger.warn('[Redis] Error closing subscriber client during shutdown', {error: error instanceof Error ? error.message : String(error),});});- await redis.close().catch((error: unknown) => {+ await redis?.close().catch((error: unknown) => {logger.warn('[Redis] Error closing client during shutdown', {error: error instanceof Error ? error.message : String(error),});diff --git a/packages/server/src/runtime/peeringIds.ts b/packages/server/src/runtime/peeringIds.tsindex a9f74163b..d384a5e8e 100644--- a/packages/server/src/runtime/peeringIds.ts+++ b/packages/server/src/runtime/peeringIds.ts@@ -2,7 +2,7 @@ import { HTTPException } from 'hono/http-exception';import { ulid } from 'ulid';/**- * Mints a peered turn id owned by `executorId`. The server calls this at turn+ * Mints a turn id owned by `executorId`. The server calls this at turn* creation (the id is opaque to the session library); `executorFromTurnId`* is the matching decoder on the routing path.*/diff --git a/packages/server/tests/db/tsconfig.json b/packages/server/tests/db/tsconfig.jsonnew file mode 100644index 000000000..751b6ef89--- /dev/null+++ b/packages/server/tests/db/tsconfig.json@@ -0,0 +1,4 @@+{+ "extends": "../../tsconfig.json",+ "include": ["**/*"]+}diff --git a/packages/server/tests/tsconfig.json b/packages/server/tests/tsconfig.jsondeleted file mode 100644index a32dd4f23..000000000--- a/packages/server/tests/tsconfig.json+++ /dev/null@@ -1,4 +0,0 @@-{- "extends": "../tsconfig.json",- "include": ["**/*"]-}diff --git a/packages/server/tests/unit/apis/sessions.test.ts b/packages/server/tests/unit/apis/sessions.test.tsnew file mode 100644index 000000000..7b121bf2f--- /dev/null+++ b/packages/server/tests/unit/apis/sessions.test.ts@@ -0,0 +1,107 @@+import type { ISessionStore, TurnRecord, TurnState } from '@truefoundry/utils/agent-session';+import { CancellationReason } from '@truefoundry/utils/agent-session';+import { HTTPException } from 'hono/http-exception';+import assert from 'node:assert/strict';+import { describe, it } from 'node:test';+import { createClient, type RedisClientType } from 'redis';+import { cancelSessionTurn } from '../../../src/apis/sessions';+import configuration from '../../../src/config';+import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';+import { mintPeeredTurnId } from '../../../src/runtime/peeringIds';++const SESSION_ID = 's1';++function turnRecord(turnId: string, state: TurnState): TurnRecord {+ return {+ turn_id: turnId,+ session_id: SESSION_ID,+ first_turn_id: turnId,+ ancestor_ids: [],+ previous_turn_id: null,+ state,+ input: [],+ snapshot: { threads: {}, mcp_servers: null, sandbox_info: null },+ created_at: new Date('2026-07-31T00:00:00.000Z'),+ updated_at: new Date('2026-07-31T00:00:00.000Z'),+ custom: null,+ };+}++/** Only `getTurn` is exercised, which is all CancelTurnDeps asks for. */+function storeReturning(turn: TurnRecord | undefined): Pick<ISessionStore, 'getTurn'> {+ return { getTurn: () => Promise.resolve(turn) };+}++/** Unconnected, so any attempt to reach a peer fails loudly instead of silently passing. */+function unconnectedRedis(): RedisClientType {+ const client: RedisClientType = createClient();+ return client;+}++/** Registers a live run without consuming its stream, mirroring a turn mid-execution. */+function trackRun(registry: ActiveTurnRegistry, turnId: string): AbortController {+ const abortController = new AbortController();+ registry.track({+ sessionId: SESSION_ID,+ turnId,+ abortController,+ stream: (async function* () {+ await new Promise(() => undefined);+ yield 'never';+ })(),+ });+ return abortController;+}++describe('cancelSessionTurn', () => {+ it('aborts a turn running in this process', async () => {+ const activeTurns = new ActiveTurnRegistry();+ const turnId = mintPeeredTurnId(configuration.EXECUTOR_ID);+ const abortController = trackRun(activeTurns, turnId);++ await cancelSessionTurn(+ {+ activeTurns,+ sessionStore: storeReturning(turnRecord(turnId, { status: 'running' })),+ },+ { sessionId: SESSION_ID, turnId },+ );++ assert.equal(abortController.signal.aborted, true);+ assert.equal(abortController.signal.reason, CancellationReason.ClientCancelled);+ });++ it('does not look for a peer without a Redis client', async () => {+ const activeTurns = new ActiveTurnRegistry();+ const turnId = mintPeeredTurnId('other1');++ // A peer hop here would dereference the absent client and throw.+ await assert.doesNotReject(+ cancelSessionTurn(+ {+ activeTurns,+ sessionStore: storeReturning(turnRecord(turnId, { status: 'running' })),+ },+ { sessionId: SESSION_ID, turnId },+ ),+ );+ });++ it('routes to the owning peer when the turn id names another replica', async () => {+ const activeTurns = new ActiveTurnRegistry();+ const turnId = mintPeeredTurnId('other1');++ // The unconnected client makes the hop fail; the point is that it happened.+ await assert.rejects(+ cancelSessionTurn(+ {+ activeTurns,+ sessionStore: storeReturning(turnRecord(turnId, { status: 'running' })),+ redis: unconnectedRedis(),+ },+ { sessionId: SESSION_ID, turnId },+ ),+ (error: unknown) => error instanceof HTTPException,+ );+ });+});diff --git a/packages/server/src/runtime/activeTurns.test.ts b/packages/server/tests/unit/runtime/activeTurns.test.tssimilarity index 98%rename from packages/server/src/runtime/activeTurns.test.tsrename to packages/server/tests/unit/runtime/activeTurns.test.tsindex eccea3675..31ff24814 100644--- a/packages/server/src/runtime/activeTurns.test.ts+++ b/packages/server/tests/unit/runtime/activeTurns.test.ts@@ -1,7 +1,7 @@import { CancellationReason } from '@truefoundry/utils/agent-session';import assert from 'node:assert/strict';import { describe, it } from 'node:test';-import { ActiveTurnRegistry } from './activeTurns';+import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';async function* values<T>(items: T[]): AsyncGenerator<T> {for (const item of items) {diff --git a/packages/server/tests/unit/runtime/peeringIds.test.ts b/packages/server/tests/unit/runtime/peeringIds.test.tsnew file mode 100644index 000000000..133b10805--- /dev/null+++ b/packages/server/tests/unit/runtime/peeringIds.test.ts@@ -0,0 +1,20 @@+import { HTTPException } from 'hono/http-exception';+import assert from 'node:assert/strict';+import { describe, it } from 'node:test';+import { executorFromTurnId, mintPeeredTurnId } from '../../../src/runtime/peeringIds';++describe('turn ids', () => {+ it('decodes back to the owning executor', () => {+ assert.equal(executorFromTurnId(mintPeeredTurnId('abc123')), 'abc123');+ });++ it('rejects ids outside the grammar', () => {+ for (const invalid of ['', '.', 'a.', '.b', 'a.b.c', 'noseparator']) {+ assert.throws(+ () => executorFromTurnId(invalid),+ (error: unknown) => error instanceof HTTPException && error.status === 400,+ `expected ${JSON.stringify(invalid)} to be rejected`,+ );+ }+ });+});diff --git a/packages/server/tests/unit/tsconfig.json b/packages/server/tests/unit/tsconfig.jsonnew file mode 100644index 000000000..e8486b199--- /dev/null+++ b/packages/server/tests/unit/tsconfig.json@@ -0,0 +1,7 @@+{+ // Separate program from tests/db: the harness store contract suite augments+ // AgentPassthroughEventSchemaMap, which widens SessionEventItem and breaks the+ // route handler types of any server source pulled in alongside it.+ "extends": "../../tsconfig.json",+ "include": ["**/*"]+}