Skip to content

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.yml
index 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: postgres
POSTGRES_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.example
index 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's
diff --git a/packages/server/.env.test b/packages/server/.env.test
index b71dd426c..2de9f673d 100644
--- a/packages/server/.env.test
+++ b/packages/server/.env.test
@@ -4,6 +4,5 @@ POSTGRES_PASSWORD=test
POSTGRES_DB=test
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
-REDIS_URL=redis://localhost:6379
MODEL_API_KEY=test
REGISTRY_DIR=registry-example
diff --git a/packages/server/package.json b/packages/server/package.json
index 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.ts
index 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-session
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.json
new file mode 100644
index 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.json
deleted file mode 100644
index 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.ts
new file mode 100644
index 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.ts
similarity index 98%
rename from packages/server/src/runtime/activeTurns.test.ts
rename to packages/server/tests/unit/runtime/activeTurns.test.ts
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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": ["**/*"]
+}