Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: Store schedule run errors (#614)

Srajan Asthanabb8d3d33f1a8
diff --git a/.changeset/schedule-run-reason.md b/.changeset/schedule-run-reason.md
new file mode 100644
index 000000000..73fb0c948
--- /dev/null
+++ b/.changeset/schedule-run-reason.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Persist optional `reason` on schedule runs when hand-off fails. Exposed on ScheduleRun responses as nullable string.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 90bb22259..55efcb49e 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -3216,6 +3216,12 @@
"name": {
"type": "string"
},
+ "reason": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
"schedule_id": {
"type": "string"
},
@@ -3246,6 +3252,7 @@
"status",
"created_by_subject",
"triggered_at",
+ "reason",
"created_at",
"updated_at"
],
diff --git a/docs/openapi.json b/docs/openapi.json
index 90bb22259..55efcb49e 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -3216,6 +3216,12 @@
"name": {
"type": "string"
},
+ "reason": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
"schedule_id": {
"type": "string"
},
@@ -3246,6 +3252,7 @@
"status",
"created_by_subject",
"triggered_at",
+ "reason",
"created_at",
"updated_at"
],
diff --git a/packages/trueforge-sdk/src/api/types/ScheduleRun.ts b/packages/trueforge-sdk/src/api/types/ScheduleRun.ts
index 8e4841b18..b6cb04424 100644
--- a/packages/trueforge-sdk/src/api/types/ScheduleRun.ts
+++ b/packages/trueforge-sdk/src/api/types/ScheduleRun.ts
@@ -7,6 +7,7 @@ export interface ScheduleRun {
createdBySubject: TrueForge.CreatedBySubject;
id: string;
name: string;
+ reason: string | null;
scheduleId: string;
scheduledFor: Date;
status: TrueForge.ScheduleRunStatus;
diff --git a/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts b/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts
index d5a097c3a..da6875551 100644
--- a/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts
+++ b/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts
@@ -12,6 +12,7 @@ export const ScheduleRun: core.serialization.ObjectSchema<serializers.ScheduleRu
createdBySubject: core.serialization.property("created_by_subject", CreatedBySubject),
id: core.serialization.string(),
name: core.serialization.string(),
+ reason: core.serialization.string().nullable(),
scheduleId: core.serialization.property("schedule_id", core.serialization.string()),
scheduledFor: core.serialization.property("scheduled_for", core.serialization.date()),
status: ScheduleRunStatus,
@@ -25,6 +26,7 @@ export declare namespace ScheduleRun {
created_by_subject: CreatedBySubject.Raw;
id: string;
name: string;
+ reason?: string | null;
schedule_id: string;
scheduled_for: string;
status: ScheduleRunStatus.Raw;
diff --git a/packages/trueforge-sdk/tests/wire/schedules.test.ts b/packages/trueforge-sdk/tests/wire/schedules.test.ts
index 51bf027bc..deaa5e6b3 100644
--- a/packages/trueforge-sdk/tests/wire/schedules.test.ts
+++ b/packages/trueforge-sdk/tests/wire/schedules.test.ts
@@ -249,6 +249,7 @@ describe("SchedulesClient", () => {
},
id: "id",
name: "name",
+ reason: "reason",
schedule_id: "schedule_id",
scheduled_for: "2024-01-15T09:30:00Z",
status: "scheduled",
@@ -279,6 +280,7 @@ describe("SchedulesClient", () => {
},
id: "id",
name: "name",
+ reason: "reason",
scheduleId: "schedule_id",
scheduledFor: new Date("2024-01-15T09:30:00.000Z"),
status: "scheduled",
@@ -720,6 +722,7 @@ describe("SchedulesClient", () => {
},
id: "id",
name: "name",
+ reason: "reason",
schedule_id: "schedule_id",
scheduled_for: "2024-01-15T09:30:00Z",
status: "scheduled",
@@ -749,6 +752,7 @@ describe("SchedulesClient", () => {
},
id: "id",
name: "name",
+ reason: "reason",
scheduleId: "schedule_id",
scheduledFor: new Date("2024-01-15T09:30:00.000Z"),
status: "scheduled",
diff --git a/packages/trueforge/src/apis/schedules.ts b/packages/trueforge/src/apis/schedules.ts
index dafd9b0aa..2bc40fb4d 100644
--- a/packages/trueforge/src/apis/schedules.ts
+++ b/packages/trueforge/src/apis/schedules.ts
@@ -6,7 +6,7 @@ import { InvalidPageTokenError, type Sessions } from '@truefoundry/trueforge-cor
import type { Context } from 'hono';
import type { Authorizer } from '../auth/authorizer';
import { createdBySubjectFromRequestContext, type RequestContext, type ResolveRequestContext } from '../auth/identity';
-import { ScheduleAgentNotFoundError, startScheduleRun } from '../controller/scheduleDispatch';
+import { ScheduleAgentNotFoundError, scheduleRunFailureReason, startScheduleRun } from '../controller/scheduleDispatch';
import type { AgentRecord, IAgentStore } from '../db/agentStore';
import {
manualRunName,
@@ -68,6 +68,7 @@ function toWireScheduleRun(record: ScheduleRunRecord): ScheduleRun {
status: record.status,
created_by_subject: record.created_by_subject,
triggered_at: record.triggered_at,
+ reason: record.reason,
created_at: record.created_at,
updated_at: record.updated_at,
};
@@ -231,6 +232,7 @@ export function createSchedulesRouter<TTransaction>(deps: SchedulesRouterDeps<TT
tenant_id: requestContext.tenant_id,
id: run.id,
status: 'failed',
+ reason: scheduleRunFailureReason(error),
});
if (error instanceof ScheduleAgentNotFoundError) {
diff --git a/packages/trueforge/src/controller/scheduleDispatch.ts b/packages/trueforge/src/controller/scheduleDispatch.ts
index c3320f3a3..98b554285 100644
--- a/packages/trueforge/src/controller/scheduleDispatch.ts
+++ b/packages/trueforge/src/controller/scheduleDispatch.ts
@@ -22,6 +22,11 @@ import type { ControlLoop } from './Controller';
*/
export const DISPATCH_BATCH_LIMIT = 20;
+/** Human-readable failure detail for a `failed` schedule run. */
+export function scheduleRunFailureReason(error: unknown): string {
+ return error instanceof Error && error.message.trim() !== '' ? error.message : 'Schedule run failed';
+}
+
/**
* Gap between loop passes.
*
@@ -140,13 +145,17 @@ async function finishScheduledRun<TTransaction>(params: {
run: ScheduleRunRecord;
now: Date;
status: ScheduleRunStatus;
+ reason?: string | null;
withTransaction: WithTransaction<TTransaction>;
}): Promise<void> {
- const { store, withTransaction, run, status, now } = params;
+ const { store, withTransaction, run, status, reason, now } = params;
await withTransaction(async txn => {
const latest = await store.getScheduleForUpdate({ tenant_id: run.tenant_id, id: run.schedule_id }, txn);
- const updated = await store.updateRunStatus({ tenant_id: run.tenant_id, id: run.id, status }, txn);
+ const updated = await store.updateRunStatus(
+ { tenant_id: run.tenant_id, id: run.id, status, reason: reason ?? null },
+ txn,
+ );
if (updated === undefined) {
return;
}
@@ -270,6 +279,7 @@ export async function dispatchScheduledRuns<TTransaction>(params: {
run,
now,
status: 'failed',
+ reason: scheduleRunFailureReason(error),
withTransaction,
});
failed += 1;
diff --git a/packages/trueforge/src/db/postgres/migrations/20260907_000001_schedule_run_reason.ts b/packages/trueforge/src/db/postgres/migrations/20260907_000001_schedule_run_reason.ts
new file mode 100644
index 000000000..8e2a5d259
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260907_000001_schedule_run_reason.ts
@@ -0,0 +1,14 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Optional failure detail on `schedule_run`. Null unless status is `failed`.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.alterTable('schedule_run').addColumn('reason', 'text').execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.alterTable('schedule_run').dropColumn('reason').execute();
+}
diff --git a/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts b/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
index 212241ede..310c6a83b 100644
--- a/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
+++ b/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
@@ -57,6 +57,7 @@ function toRunRecord(row: Selectable<ScheduleRunTable>): ScheduleRunRecord {
status: row.status,
created_by_subject: CreatedBySubjectSchema.parse(row.created_by_subject),
triggered_at: row.triggered_at === null ? null : row.triggered_at.toISOString(),
+ reason: row.reason,
created_at: row.created_at.toISOString(),
updated_at: row.updated_at.toISOString(),
};
@@ -293,6 +294,7 @@ export class PostgresScheduleStore implements IScheduleStore<Transaction<Databas
status: input.status,
created_by_subject: json(input.created_by_subject),
triggered_at: input.triggered_at ?? null,
+ reason: input.reason ?? null,
created_at: now(),
updated_at: now(),
})
@@ -312,10 +314,12 @@ export class PostgresScheduleStore implements IScheduleStore<Transaction<Databas
transaction?: Transaction<Database>,
): Promise<ScheduleRunRecord | undefined> {
const db = transaction ?? this.#db;
+ const timestamp = now();
+ const reason = input.status === 'failed' ? (input.reason ?? null) : null;
const patch =
input.status === 'triggered'
- ? { status: input.status, triggered_at: now(), updated_at: now() }
- : { status: input.status, updated_at: now() };
+ ? { status: input.status, triggered_at: timestamp, reason, updated_at: timestamp }
+ : { status: input.status, reason, updated_at: timestamp };
const row = await db
.updateTable('schedule_run')
.set(patch)
diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.ts
index 7c1423ef7..17475d47e 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -430,6 +430,7 @@ export interface ScheduleRunTable {
status: ScheduleRunStatus;
created_by_subject: JSONColumnType<CreatedBySubject, CreatedBySubject, CreatedBySubject>;
triggered_at: Date | null;
+ reason: string | null;
created_at: Date;
updated_at: Date;
}
diff --git a/packages/trueforge/src/db/scheduleStore.ts b/packages/trueforge/src/db/scheduleStore.ts
index 60e486689..a5af138f4 100644
--- a/packages/trueforge/src/db/scheduleStore.ts
+++ b/packages/trueforge/src/db/scheduleStore.ts
@@ -63,6 +63,7 @@ export interface ScheduleRunRecord {
status: ScheduleRunStatus;
created_by_subject: CreatedBySubject;
triggered_at: string | null;
+ reason: string | null;
created_at: string;
updated_at: string;
}
@@ -150,6 +151,7 @@ export interface CreateScheduleRunInput {
created_by_subject: CreatedBySubject;
status: ScheduleRunStatus;
triggered_at?: Date | null;
+ reason?: string | null;
}
export interface ListScheduledRunsInput {
@@ -172,6 +174,7 @@ export interface UpdateScheduleRunStatusInput {
tenant_id: string;
id: string;
status: ScheduleRunStatus;
+ reason?: string | null;
}
export class ScheduleRunConflictError extends Error {
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260907_000001_schedule_run_reason.ts b/packages/trueforge/src/db/sqlite/migrations/20260907_000001_schedule_run_reason.ts
new file mode 100644
index 000000000..8203b344a
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260907_000001_schedule_run_reason.ts
@@ -0,0 +1,16 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Optional failure detail on `schedule_run`. Null unless status is `failed`.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`ALTER TABLE schedule_run ADD COLUMN reason TEXT`.execute(trx);
+ });
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`ALTER TABLE schedule_run DROP COLUMN reason`.execute(trx);
+ });
+}
diff --git a/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts b/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
index b8b1bb57e..ca0880107 100644
--- a/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
+++ b/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
@@ -63,6 +63,7 @@ function runColumns(eb: ExpressionBuilder<Database, 'schedule_run'>) {
'status' as const,
jsonText<CreatedBySubject>(eb.ref('created_by_subject')).as('created_by_subject'),
'triggered_at' as const,
+ 'reason' as const,
'created_at' as const,
'updated_at' as const,
];
@@ -90,6 +91,7 @@ interface RunRow {
status: ScheduleRunStatus;
created_by_subject: CreatedBySubject;
triggered_at: string | null;
+ reason: string | null;
created_at: string;
updated_at: string;
}
@@ -346,6 +348,7 @@ export class SqliteScheduleStore implements IScheduleStore<Transaction<Database>
status: input.status,
created_by_subject: jsonbBind(input.created_by_subject),
triggered_at: input.triggered_at?.toISOString() ?? null,
+ reason: input.reason ?? null,
created_at: timestamp,
updated_at: timestamp,
})
@@ -366,10 +369,11 @@ export class SqliteScheduleStore implements IScheduleStore<Transaction<Database>
): Promise<ScheduleRunRecord | undefined> {
const db = transaction ?? this.#db;
const timestamp = nowIso();
+ const reason = input.status === 'failed' ? (input.reason ?? null) : null;
const patch =
input.status === 'triggered'
- ? { status: input.status, triggered_at: timestamp, updated_at: timestamp }
- : { status: input.status, updated_at: timestamp };
+ ? { status: input.status, triggered_at: timestamp, reason, updated_at: timestamp }
+ : { status: input.status, reason, updated_at: timestamp };
const row = await db
.updateTable('schedule_run')
.set(patch)
diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.ts
index a6adab314..476047b5d 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -272,6 +272,7 @@ export interface ScheduleRunTable {
status: ScheduleRunStatus;
created_by_subject: JsonbColumn<CreatedBySubject>;
triggered_at: string | null;
+ reason: string | null;
created_at: string;
updated_at: string;
}
diff --git a/packages/trueforge/src/schemas/schedule.ts b/packages/trueforge/src/schemas/schedule.ts
index d2c2d5b3b..712d6b286 100644
--- a/packages/trueforge/src/schemas/schedule.ts
+++ b/packages/trueforge/src/schemas/schedule.ts
@@ -146,6 +146,7 @@ export const ScheduleRunSchema = z
status: ScheduleRunStatusSchema,
created_by_subject: CreatedBySubjectSchema,
triggered_at: NullableIsoTimestamp,
+ reason: z.string().nullable(),
created_at: IsoTimestamp,
updated_at: IsoTimestamp,
})
diff --git a/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts b/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
index ac35be5e0..4d87c2df2 100644
--- a/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
+++ b/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
@@ -231,6 +231,7 @@ export function runScheduleDispatchContractSuite<TTransaction>(deps: {
expect.objectContaining({
id: run.id,
status: 'failed',
+ reason: 'executor unavailable',
}),
);
@@ -389,10 +390,10 @@ export function runScheduleDispatchContractSuite<TTransaction>(deps: {
expect(handedOff).toEqual([thrower.run.id, healthy.run.id]);
expect(await store.getRun({ tenant_id: TENANT, id: thrower.run.id })).toEqual(
- expect.objectContaining({ status: 'failed', triggered_at: null }),
+ expect.objectContaining({ status: 'failed', triggered_at: null, reason: 'executor unavailable' }),
);
const healthyUpdated = await store.getRun({ tenant_id: TENANT, id: healthy.run.id });
- expect(healthyUpdated).toEqual(expect.objectContaining({ status: 'triggered' }));
+ expect(healthyUpdated).toEqual(expect.objectContaining({ status: 'triggered', reason: null }));
expect(typeof healthyUpdated?.triggered_at).toBe('string');
// Every schedule advances, whatever its run's outcome, and never onto a past time.
diff --git a/packages/trueforge/tests/db/scheduleStoreContractSuite.ts b/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
index fb5a57aff..707873f7e 100644
--- a/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
+++ b/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
@@ -765,6 +765,7 @@ export function runScheduleStoreContractSuite(deps: {
const toTrigger = await seedScheduled(new Date('2026-08-27T10:00:00.000Z'));
expect(toTrigger.triggered_at).toBeNull();
+ expect(toTrigger.reason).toBeNull();
const triggered = await store.updateRunStatus({
tenant_id: TENANT,
id: toTrigger.id,
@@ -774,6 +775,7 @@ export function runScheduleStoreContractSuite(deps: {
expect.objectContaining({
id: toTrigger.id,
status: 'triggered',
+ reason: null,
}),
);
if (triggered === undefined) {
@@ -788,12 +790,58 @@ export function runScheduleStoreContractSuite(deps: {
tenant_id: TENANT,
id: toFail.id,
status: 'failed',
+ reason: 'hand-off blew up',
});
expect(failed).toEqual(
expect.objectContaining({
id: toFail.id,
status: 'failed',
triggered_at: null,
+ reason: 'hand-off blew up',
+ }),
+ );
+
+ const toFailWithoutReason = await store.createRun({
+ tenant_id: TENANT,
+ schedule_id: schedule.id,
+ name: cronRunName(new Date('2026-08-27T13:00:00.000Z')),
+ scheduled_for: new Date('2026-08-27T13:00:00.000Z'),
+ status: 'scheduled',
+ created_by_subject: USER_SUBJECT,
+ });
+ const failedWithoutReason = await store.updateRunStatus({
+ tenant_id: TENANT,
+ id: toFailWithoutReason.id,
+ status: 'failed',
+ });
+ expect(failedWithoutReason).toEqual(
+ expect.objectContaining({
+ id: toFailWithoutReason.id,
+ status: 'failed',
+ reason: null,
+ }),
+ );
+
+ const toClearReason = await store.createRun({
+ tenant_id: TENANT,
+ schedule_id: schedule.id,
+ name: cronRunName(new Date('2026-08-27T14:00:00.000Z')),
+ scheduled_for: new Date('2026-08-27T14:00:00.000Z'),
+ status: 'scheduled',
+ created_by_subject: USER_SUBJECT,
+ reason: 'stale failure',
+ });
+ expect(toClearReason.reason).toBe('stale failure');
+ const cleared = await store.updateRunStatus({
+ tenant_id: TENANT,
+ id: toClearReason.id,
+ status: 'triggered',
+ });
+ expect(cleared).toEqual(
+ expect.objectContaining({
+ id: toClearReason.id,
+ status: 'triggered',
+ reason: null,
}),
);
diff --git a/packages/trueforge/tests/unit/apis/schedules.test.ts b/packages/trueforge/tests/unit/apis/schedules.test.ts
index 76e615fa2..3c0137a28 100644
--- a/packages/trueforge/tests/unit/apis/schedules.test.ts
+++ b/packages/trueforge/tests/unit/apis/schedules.test.ts
@@ -288,6 +288,7 @@ describe('create schedule run', () => {
expect.objectContaining({
schedule_id: scheduleId,
status: 'triggered',
+ reason: null,
created_by_subject: {
subject_id: 'alice',
subject_type: 'user',
@@ -343,6 +344,7 @@ describe('create schedule run', () => {
const runs = await scheduleStore.listRuns({ tenant_id: 'default', schedule_id: scheduleId });
const runNow = runs.find(r => r.name.startsWith('manual-'));
expect(runNow?.status).toBe('failed');
+ expect(runNow?.reason).toBe('Agent not found: reporter');
});
it('returns 404 when creating a schedule for an agent the caller cannot use', async () => {
diff --git a/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts b/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
index 51de78ce2..6d7fffefa 100644
--- a/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
+++ b/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
@@ -1,11 +1,24 @@
import {
ScheduleAgentNotFoundError,
scheduleDispatchLoop,
+ scheduleRunFailureReason,
startScheduleRun,
} from '../../../src/controller/scheduleDispatch';
import type { ScheduleDispatchItem, ScheduleRunRecord } from '../../../src/db/scheduleStore';
import { ScheduleManifestSchema } from '../../../src/schemas/schedule';
+describe('scheduleRunFailureReason', () => {
+ it('uses Error.message when non-empty', () => {
+ expect(scheduleRunFailureReason(new Error('executor unavailable'))).toBe('executor unavailable');
+ });
+
+ it('falls back when message is blank or value is not an Error', () => {
+ expect(scheduleRunFailureReason(new Error(' '))).toBe('Schedule run failed');
+ expect(scheduleRunFailureReason('boom')).toBe('Schedule run failed');
+ expect(scheduleRunFailureReason(null)).toBe('Schedule run failed');
+ });
+});
+
function item(): ScheduleDispatchItem {
return {
run: {
@@ -17,6 +30,7 @@ function item(): ScheduleDispatchItem {
status: 'scheduled',
created_by_subject: { subject_id: 'tester', subject_type: 'user', subject_display_name: 'tester' },
triggered_at: null,
+ reason: null,
created_at: '2026-08-31T00:00:00.000Z',
updated_at: '2026-08-31T00:00:00.000Z',
},