Skip to content

Commit 4ced8ef

Browse files
heerambavi1998Heer Ambavicursoragenttrueforge-dev-bot[bot]
authored
Dispatch schedule runs through the session and turn HTTP APIs. (#517)
* add session get-or-create-by-external-id endpoint * make it explicit * Regenerate OpenAPI document and TypeScript SDK * address comment * remove success log for sqlite * more fixes * fix import * add session and turn creation to scheduler * minor fixes * add session and turn creation to scheduler * minor fixes * remove * no longer distfree --------- Co-authored-by: Heer Ambavi <heer@Heers-MacBook-Pro.local> Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: trueforge-dev-bot[bot] <trueforge-dev-bot[bot]@users.noreply.github.com>
1 parent ef316d2 commit 4ced8ef

13 files changed

Lines changed: 229 additions & 116 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@truefoundry/trueforge": patch
3+
---
4+
5+
Dispatch schedule runs through the session/turn API: get-or-create a session keyed by run id, then create a turn only when that session has none.

‎packages/trueforge/package.json‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,11 @@
4242
"migrate": "NODE_OPTIONS='--conditions=trueforge-dev' STANDALONE=false tsx --env-file=.env src/db/postgres/migrate-cli.ts",
4343
"openapi:write": "pnpm run build:gen && NODE_OPTIONS='--conditions=trueforge-dev' tsx --env-file=.env.test scripts/write-openapi.ts",
4444
"pack:dry": "pnpm pack --dry-run",
45-
"predev:no-watch": "pnpm --filter @truefoundry/trueforge-core build:gen && pnpm run build:gen",
46-
"predev": "pnpm --filter @truefoundry/trueforge-core build:gen && pnpm run build:gen",
45+
"predev:no-watch": "pnpm run sdk:build && pnpm --filter @truefoundry/trueforge-core build:gen && pnpm run build:gen",
46+
"predev": "pnpm run sdk:build && pnpm --filter @truefoundry/trueforge-core build:gen && pnpm run build:gen",
47+
"pretest": "pnpm run sdk:build",
48+
"pretypecheck": "pnpm run sdk:build",
49+
"sdk:build": "pnpm --filter @truefoundry/trueforge-sdk build",
4750
"test:eventsub": "jest --config jest.eventsub.config.cjs",
4851
"test:store:postgres": "jest --config jest.store.postgres.config.cjs",
4952
"test:store:sqlite": "jest --config jest.store.sqlite.config.cjs",
@@ -62,6 +65,7 @@
6265
"@hono/zod-openapi": "^1.6.1",
6366
"@modelcontextprotocol/sdk": "^1.30.0",
6467
"@truefoundry/trueforge-core": "workspace:*",
68+
"@truefoundry/trueforge-sdk": "workspace:*",
6569
"better-sqlite3": "^13.0.3",
6670
"cron-parser": "^5.4.0",
6771
"env-paths": "^4.0.0",
Lines changed: 41 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,47 @@
1-
/**
2-
* Controller entry point — the control loops as their own process.
3-
*
4-
* Distributed mode only. Server replicas run no loops, so this deployment is the sole
5-
* controller for the database. Loops assume no peer runs alongside them,
6-
* so it MUST have exactly one replica.
7-
*
8-
* In standalone mode the controller runs inside the server instead — one process owns
9-
* everything, and this entry point refuses to start.
10-
*/
11-
import { extractErrorLogFields } from '@truefoundry/trueforge-core/core';
12-
13-
let configuration: typeof import('./config').default;
14-
15-
try {
16-
({ default: configuration } = await import('./config'));
17-
} catch (error) {
18-
console.error(
19-
'Failed to start controller: Failed to load configuration:',
20-
error instanceof Error ? error.message : error,
21-
);
22-
process.exit(1);
23-
}
24-
1+
import { TrueForge } from '@truefoundry/trueforge-sdk';
2+
import type { Logger } from 'winston';
253
import { Controller } from './controller/Controller';
26-
import { createScheduleDispatchLoop, logTriggeredRun } from './controller/scheduleDispatch';
27-
import { createDb } from './db/postgres/client';
28-
import { PostgresScheduleStore } from './db/postgres/schedule-store/PostgresScheduleStore';
29-
import { createServerLogger } from './logger';
30-
import { PACKAGE_VERSION } from './packageVersion';
31-
32-
try {
33-
const logger = createServerLogger({
34-
level: configuration.LOG_LEVEL,
35-
standalone: configuration.STANDALONE,
36-
version: PACKAGE_VERSION,
37-
});
4+
import { scheduleDispatchLoop } from './controller/scheduleDispatch';
5+
import type { IScheduleStore } from './db/scheduleStore';
6+
import type { WithTransaction } from './db/transaction';
387

39-
// Narrow through a const: the config union is keyed on STANDALONE, and only the
40-
// distributed variant carries the Postgres connection settings.
41-
const config = configuration;
42-
if (config.STANDALONE) {
43-
throw new Error(
44-
'The controller process is for distributed mode only. ' +
45-
'In standalone mode the server runs the control loops in-process.',
46-
);
47-
}
48-
49-
const db = createDb({
50-
connectionString: config.DATABASE_URL,
51-
poolMax: config.DATABASE_POOL_MAX,
52-
statementTimeoutMs: config.POSTGRES_STATEMENT_TIMEOUT_MS,
53-
idleInTransactionSessionTimeoutMs: config.POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS,
54-
});
55-
const controller = new Controller({
8+
/**
9+
* The loops the controller runs.
10+
*/
11+
export function createController<TTransaction>(params: {
12+
scheduleStore: IScheduleStore<TTransaction>;
13+
withTransaction: WithTransaction<TTransaction>;
14+
logger: Logger;
15+
baseUrl: string;
16+
}): Controller {
17+
const { scheduleStore, withTransaction, logger, baseUrl } = params;
18+
return new Controller({
5619
loops: [
57-
createScheduleDispatchLoop({
58-
scheduleStore: new PostgresScheduleStore(db),
59-
withTransaction: callback => db.transaction().execute(callback),
60-
onTriggered: logTriggeredRun(logger),
20+
scheduleDispatchLoop({
21+
scheduleStore,
22+
client: new TrueForge({ baseUrl, auth: false }),
23+
withTransaction,
6124
logger,
6225
}),
6326
],
6427
logger,
6528
});
29+
}
6630

67-
logger.info('TrueForge controller starting', { mode: 'distributed' });
31+
/**
32+
* Runs the controller: starts the loops and drains them on SIGTERM/SIGINT.
33+
*/
34+
export function runController<TTransaction>(params: {
35+
scheduleStore: IScheduleStore<TTransaction>;
36+
withTransaction: WithTransaction<TTransaction>;
37+
logger: Logger;
38+
baseUrl: string;
39+
gracefulTimeoutSeconds: number;
40+
/** Releases what the caller opened for the loops, e.g. its database pool. */
41+
onStopped?: () => Promise<void>;
42+
}): Controller {
43+
const { logger, gracefulTimeoutSeconds, onStopped } = params;
44+
const controller = createController(params);
6845
controller.start();
6946

7047
let shuttingDown = false;
@@ -75,17 +52,14 @@ try {
7552
shuttingDown = true;
7653
logger.info(`Received ${signal}, stopping control loops`);
7754

78-
// Start the deadline at the top of shutdown; unref so this timer alone cannot keep the process
79-
// alive. Passes only hold short transactions, so this should never elapse.
55+
// Passes only hold short transactions, so the deadline should never elapse.
8056
setTimeout(() => {
81-
logger.warn(`Controller drain timed out after ${String(configuration.GRACEFUL_TIMEOUT_SECONDS)}s, exiting`);
57+
logger.warn(`Controller drain timed out after ${String(gracefulTimeoutSeconds)}s, exiting`);
8258
process.exit(1);
83-
}, configuration.GRACEFUL_TIMEOUT_SECONDS * 1000).unref();
59+
}, gracefulTimeoutSeconds * 1000).unref();
8460

8561
await controller.stop();
86-
await db.destroy().catch((error: unknown) => {
87-
logger.warn('Error closing the database pool during shutdown', extractErrorLogFields(error));
88-
});
62+
await onStopped?.();
8963
process.exit(0);
9064
};
9165
process.on('SIGTERM', signal => {
@@ -94,7 +68,6 @@ try {
9468
process.on('SIGINT', signal => {
9569
void shutdown(signal);
9670
});
97-
} catch (error) {
98-
console.error('Failed to start controller:', error instanceof Error ? error.message : error);
99-
process.exit(1);
71+
72+
return controller;
10073
}

‎packages/trueforge/src/controller/Controller.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*
77
* The controller runs in exactly ONE process per database. In standalone mode that is
88
* the server itself; when `STANDALONE=false` it is the dedicated single-replica
9-
* process in `src/controller.ts`. Loops are written assuming this.
9+
* process. Loops are written assuming this.
1010
*/
1111
import type { Logger } from 'winston';
1212

‎packages/trueforge/src/controller/scheduleDispatch.ts‎

Lines changed: 34 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { TrueForge } from '@truefoundry/trueforge-sdk';
12
import type { Logger } from 'winston';
23
import {
34
cronRunName,
@@ -31,6 +32,34 @@ const SCHEDULE_DISPATCH_INTERVAL_MS = 60_000;
3132
/** The loop's name. */
3233
const SCHEDULE_DISPATCH_LOOP_NAME = 'schedule-dispatch';
3334

35+
type ScheduleRunApiClient = Pick<TrueForge, 'sessions' | 'internal'>;
36+
37+
/**
38+
* Hands a due schedule run to the API:
39+
* 1. Get or create a session keyed by `run.id`.
40+
* 2. Create a non-streaming turn only when that session has no turns.
41+
*
42+
* This call is hence idempotent.
43+
*/
44+
function executeScheduledRun(client: ScheduleRunApiClient): (item: ScheduleDispatchItem) => Promise<void> {
45+
return async ({ run, schedule }) => {
46+
const { data: session } = await client.internal.sessions.getOrCreateByExternalId({
47+
externalId: run.id,
48+
agent: { name: schedule.agent_name },
49+
});
50+
51+
const turns = await client.sessions.listTurns(session.id, { limit: 1 });
52+
if (turns.data.length > 0) {
53+
return;
54+
}
55+
56+
await client.sessions.createTurn(session.id, {
57+
input: [{ type: 'user.message', content: schedule.manifest.task }],
58+
previousTurnId: 'none',
59+
});
60+
};
61+
}
62+
3463
/**
3564
* Mark the current run with `status`, then add the schedule's next scheduled run
3665
* if the schedule is still active and its cron still has a later trigger time.
@@ -113,7 +142,7 @@ async function finishScheduledRun<TTransaction>(params: {
113142
*
114143
* - **pause**: drops the pending run in its own transaction, and stops the advance.
115144
* It never cancels a row that still exists: whatever pause did not delete is
116-
* executed (or recorded `missed`) so history has no unexplained gap.
145+
* executed (and recorded `triggered` or `failed`) so history has no unexplained gap.
117146
* If pause commits first, the row is gone and there is nothing to run.
118147
* If dispatch commits first, the run triggers and pause deletes the pending row
119148
* dispatch just added, so triggering stops from the next tick — at most one extra run.
@@ -202,41 +231,20 @@ export async function dispatchScheduledRuns<TTransaction>(params: {
202231
return { dispatched, failed };
203232
}
204233

205-
/**
206-
* Stand-in until the run executor lands: records the hand-off and drops it.
207-
*
208-
* Called before the row is marked `triggered`; if nothing commits afterward the
209-
* same scheduled row will be offered again on the next pass.
210-
*
211-
* TODO(executor): replace with the real executor. Note it runs in the controller's
212-
* process, so the dedicated deployment will need everything a turn needs — model
213-
* provider credentials, MCP egress, sandbox access — not just database reach.
214-
*/
215-
export function logTriggeredRun(logger: Logger): (item: ScheduleDispatchItem) => void | Promise<void> {
216-
return item => {
217-
logger.warn('Schedule run triggered but no executor is configured; run will not execute', {
218-
schedule_id: item.schedule.id,
219-
run_id: item.run.id,
220-
agent_name: item.schedule.agent_name,
221-
scheduled_for: item.run.scheduled_for,
222-
});
223-
};
224-
}
225-
226-
export function createScheduleDispatchLoop<TTransaction>(params: {
234+
export function scheduleDispatchLoop<TTransaction>(params: {
227235
scheduleStore: IScheduleStore<TTransaction>;
228-
onTriggered: (item: ScheduleDispatchItem) => void | Promise<void>;
236+
client: ScheduleRunApiClient;
229237
logger: Logger;
230238
withTransaction: WithTransaction<TTransaction>;
231239
}): ControlLoop {
232-
const { scheduleStore, withTransaction, onTriggered, logger } = params;
240+
const { scheduleStore, client, withTransaction, logger } = params;
233241
return {
234242
name: SCHEDULE_DISPATCH_LOOP_NAME,
235243
intervalMs: SCHEDULE_DISPATCH_INTERVAL_MS,
236244
async tick(signal: AbortSignal): Promise<void> {
237245
const result = await dispatchScheduledRuns({
238246
store: scheduleStore,
239-
onTriggered,
247+
onTriggered: executeScheduledRun(client),
240248
logger,
241249
withTransaction,
242250
signal,
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/** Partial unique index on `session (tenant_id, external_id) WHERE external_id IS NOT NULL`. */
2+
export const SESSION_EXTERNAL_ID_UQ = 'session_external_id_uq';
Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { sql, type Kysely } from 'kysely';
2+
import { SESSION_EXTERNAL_ID_UQ } from '../../indexes';
23

34
/**
45
* Optional session `external_id`, unique within a tenant when set.
@@ -8,14 +9,14 @@ export async function up(db: Kysely<unknown>): Promise<void> {
89
await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
910
await db.schema.alterTable('session').addColumn('external_id', 'text').execute();
1011
await sql`
11-
CREATE UNIQUE INDEX ${sql.raw('session_external_id_uq')}
12+
CREATE UNIQUE INDEX ${sql.raw(SESSION_EXTERNAL_ID_UQ)}
1213
ON session (tenant_id, external_id)
1314
WHERE external_id IS NOT NULL
1415
`.execute(db);
1516
}
1617

1718
export async function down(db: Kysely<unknown>): Promise<void> {
1819
await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
19-
await sql`DROP INDEX IF EXISTS ${sql.raw('session_external_id_uq')}`.execute(db);
20+
await sql`DROP INDEX IF EXISTS ${sql.raw(SESSION_EXTERNAL_ID_UQ)}`.execute(db);
2021
await db.schema.alterTable('session').dropColumn('external_id').execute();
2122
}

‎packages/trueforge/src/db/postgres/session-store/queries/sessions.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
SessionStoreInvariantError,
2020
} from '@truefoundry/trueforge-core/agent-session/store/SessionStoreErrors';
2121
import { sql, type Kysely } from 'kysely';
22+
import { SESSION_EXTERNAL_ID_UQ } from '../../../indexes';
2223
import { sessionAgentFromColumns, sessionAgentToColumns } from '../../../sessionAgentColumns';
2324
import { isPgConstraint, isUniqueViolation } from '../../client';
2425
import { json } from '../../sqlExpressions';
@@ -107,7 +108,7 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
107108
.execute();
108109
} catch (error) {
109110
if (isUniqueViolation(error)) {
110-
if (isPgConstraint(error, 'session_external_id_uq') && input.external_id) {
111+
if (isPgConstraint(error, SESSION_EXTERNAL_ID_UQ) && input.external_id) {
111112
throw new SessionExternalIdConflictError(input.external_id, { cause: error });
112113
}
113114
throw new SessionAlreadyExistsError(input.session_id, { cause: error });

‎packages/trueforge/src/db/sqlite/migrations/20260831_000001_session_external_id.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { type Kysely, sql } from 'kysely';
2+
import { SESSION_EXTERNAL_ID_UQ } from '../../indexes';
23

34
/**
45
* Optional session `external_id`, unique within a tenant when set.
@@ -8,7 +9,7 @@ export async function up(db: Kysely<unknown>): Promise<void> {
89
await db.transaction().execute(async trx => {
910
await sql`ALTER TABLE session ADD COLUMN external_id TEXT`.execute(trx);
1011
await sql`
11-
CREATE UNIQUE INDEX ${sql.raw('session_external_id_uq')}
12+
CREATE UNIQUE INDEX ${sql.raw(SESSION_EXTERNAL_ID_UQ)}
1213
ON session (tenant_id, external_id)
1314
WHERE external_id IS NOT NULL
1415
`.execute(trx);
@@ -17,7 +18,7 @@ export async function up(db: Kysely<unknown>): Promise<void> {
1718

1819
export async function down(db: Kysely<unknown>): Promise<void> {
1920
await db.transaction().execute(async trx => {
20-
await sql`DROP INDEX IF EXISTS ${sql.raw('session_external_id_uq')}`.execute(trx);
21+
await sql`DROP INDEX IF EXISTS ${sql.raw(SESSION_EXTERNAL_ID_UQ)}`.execute(trx);
2122
await sql`ALTER TABLE session DROP COLUMN external_id`.execute(trx);
2223
});
2324
}

‎packages/trueforge/src/main.ts‎

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,7 @@ import { ModelCatalog } from './catalog/ModelCatalog';
5151
import { SandboxCatalog } from './catalog/SandboxCatalog';
5252
import { SkillCatalog } from './catalog/SkillCatalog';
5353
import { type DistributedServerConfiguration } from './config';
54-
import { Controller } from './controller/Controller';
55-
import { createScheduleDispatchLoop, logTriggeredRun } from './controller/scheduleDispatch';
54+
import { createController } from './controller';
5655
import type { IAgentStore } from './db/agentStore';
5756
import type { IMcpServerStore } from './db/mcpServerStore';
5857
import type { IModelProviderStore } from './db/modelProviderStore';
@@ -233,16 +232,11 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
233232

234233
// Standalone is one process, so it owns the control loops too.
235234
const controller = configuration.STANDALONE
236-
? new Controller({
237-
loops: [
238-
createScheduleDispatchLoop({
239-
scheduleStore,
240-
withTransaction,
241-
onTriggered: logTriggeredRun(logger),
242-
logger,
243-
}),
244-
],
235+
? createController({
236+
scheduleStore,
237+
withTransaction,
245238
logger,
239+
baseUrl: `http://localhost:${String(configuration.PORT)}`,
246240
})
247241
: undefined;
248242

@@ -269,8 +263,6 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
269263
oidcClient,
270264
});
271265

272-
controller?.start();
273-
274266
return { activeTurns, app, controller, destroyDb, redis, requestReplyRouter };
275267
}
276268

@@ -353,6 +345,8 @@ try {
353345

354346
const server = serve({ fetch: app.fetch, port: configuration.PORT, hostname: configuration.HOST }, info => {
355347
logger.info(`Agent server listening on http://${configuration.HOST}:${String(info.port)} (docs at /api/v1/docs)`);
348+
// The controller calls this server over HTTP.
349+
controller?.start();
356350
});
357351

358352
server.on('error', (error: unknown) => {

0 commit comments

Comments
 (0)