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.mdnew file mode 100644index 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.ScheduleRucreatedBySubject: 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.tsindex 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.tsindex 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-corimport 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<TTtenant_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.tsindex 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.tsnew file mode 100644index 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.tsindex 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<Databasstatus: 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<Databastransaction?: 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex d2c2d5b3b..712d6b286 100644--- a/packages/trueforge/src/schemas/schedule.ts+++ b/packages/trueforge/src/schemas/schedule.ts@@ -146,6 +146,7 @@ export const ScheduleRunSchema = zstatus: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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',},