Skip to content

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

feat: link schedule runs to the session they created (AGE-2144) (#1085)

Hary Ahuja5bb093e1ff3c
diff --git a/.changeset/20261016133543-regenerate-sdk-from-openapi.md b/.changeset/20261016133543-regenerate-sdk-from-openapi.md
new file mode 100644
index 000000000..efd8ff00f
--- /dev/null
+++ b/.changeset/20261016133543-regenerate-sdk-from-openapi.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
diff --git a/.changeset/schedule-run-session-id.md b/.changeset/schedule-run-session-id.md
new file mode 100644
index 000000000..c11c0cad4
--- /dev/null
+++ b/.changeset/schedule-run-session-id.md
@@ -0,0 +1,6 @@
+---
+'@truefoundry/trueforge': patch
+---
+
+Schedule runs now return `session_id`, the session each run created, so clients can open a run's
+session. Existing runs are backfilled; runs without a session return `null`.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index e99bf663c..6ac1913e5 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -3901,6 +3901,12 @@
"format": "date-time",
"type": "string"
},
+ "session_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
"status": {
"$ref": "#/components/schemas/ScheduleRunStatus"
},
@@ -3925,6 +3931,7 @@
"created_by_subject",
"triggered_at",
"reason",
+ "session_id",
"created_at",
"updated_at"
],
diff --git a/docs/openapi.json b/docs/openapi.json
index e99bf663c..6ac1913e5 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -3901,6 +3901,12 @@
"format": "date-time",
"type": "string"
},
+ "session_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
"status": {
"$ref": "#/components/schemas/ScheduleRunStatus"
},
@@ -3925,6 +3931,7 @@
"created_by_subject",
"triggered_at",
"reason",
+ "session_id",
"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 b6cb04424..3b6a40e2d 100644
--- a/packages/trueforge-sdk/src/api/types/ScheduleRun.ts
+++ b/packages/trueforge-sdk/src/api/types/ScheduleRun.ts
@@ -10,6 +10,7 @@ export interface ScheduleRun {
reason: string | null;
scheduleId: string;
scheduledFor: Date;
+ sessionId: string | null;
status: TrueForge.ScheduleRunStatus;
triggeredAt: Date | null;
updatedAt: Date;
diff --git a/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts b/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts
index da6875551..f838b837f 100644
--- a/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts
+++ b/packages/trueforge-sdk/src/serialization/types/ScheduleRun.ts
@@ -15,6 +15,7 @@ export const ScheduleRun: core.serialization.ObjectSchema<serializers.ScheduleRu
reason: core.serialization.string().nullable(),
scheduleId: core.serialization.property("schedule_id", core.serialization.string()),
scheduledFor: core.serialization.property("scheduled_for", core.serialization.date()),
+ sessionId: core.serialization.property("session_id", core.serialization.string().nullable()),
status: ScheduleRunStatus,
triggeredAt: core.serialization.property("triggered_at", core.serialization.date().nullable()),
updatedAt: core.serialization.property("updated_at", core.serialization.date()),
@@ -29,6 +30,7 @@ export declare namespace ScheduleRun {
reason?: string | null;
schedule_id: string;
scheduled_for: string;
+ session_id?: string | null;
status: ScheduleRunStatus.Raw;
triggered_at?: string | null;
updated_at: string;
diff --git a/packages/trueforge-sdk/tests/wire/schedules.test.ts b/packages/trueforge-sdk/tests/wire/schedules.test.ts
index 0519b0944..7e03bc72c 100644
--- a/packages/trueforge-sdk/tests/wire/schedules.test.ts
+++ b/packages/trueforge-sdk/tests/wire/schedules.test.ts
@@ -252,6 +252,7 @@ describe("SchedulesClient", () => {
reason: "reason",
schedule_id: "schedule_id",
scheduled_for: "2024-01-15T09:30:00Z",
+ session_id: "session_id",
status: "scheduled",
triggered_at: "2024-01-15T09:30:00Z",
updated_at: "2024-01-15T09:30:00Z",
@@ -283,6 +284,7 @@ describe("SchedulesClient", () => {
reason: "reason",
scheduleId: "schedule_id",
scheduledFor: new Date("2024-01-15T09:30:00.000Z"),
+ sessionId: "session_id",
status: "scheduled",
triggeredAt: new Date("2024-01-15T09:30:00.000Z"),
updatedAt: new Date("2024-01-15T09:30:00.000Z"),
@@ -725,6 +727,7 @@ describe("SchedulesClient", () => {
reason: "reason",
schedule_id: "schedule_id",
scheduled_for: "2024-01-15T09:30:00Z",
+ session_id: "session_id",
status: "scheduled",
triggered_at: "2024-01-15T09:30:00Z",
updated_at: "2024-01-15T09:30:00Z",
@@ -755,6 +758,7 @@ describe("SchedulesClient", () => {
reason: "reason",
scheduleId: "schedule_id",
scheduledFor: new Date("2024-01-15T09:30:00.000Z"),
+ sessionId: "session_id",
status: "scheduled",
triggeredAt: new Date("2024-01-15T09:30:00.000Z"),
updatedAt: new Date("2024-01-15T09:30:00.000Z"),
diff --git a/packages/trueforge/src/apis/schedules.ts b/packages/trueforge/src/apis/schedules.ts
index b790267b1..ab255f7a8 100644
--- a/packages/trueforge/src/apis/schedules.ts
+++ b/packages/trueforge/src/apis/schedules.ts
@@ -106,6 +106,7 @@ export async function startScheduleRunOnRequest<TTransaction>(params: {
item,
sessions: deps.sessions,
agentStore: deps.agentStore,
+ scheduleStore: deps.scheduleStore,
});
if (prepared === undefined) {
return;
@@ -152,6 +153,7 @@ function toWireScheduleRun(record: ScheduleRunRecord): ScheduleRun {
created_by_subject: record.created_by_subject,
triggered_at: record.triggered_at,
reason: record.reason,
+ session_id: record.session_id,
created_at: record.created_at,
updated_at: record.updated_at,
};
@@ -349,7 +351,7 @@ export function createSchedulesRouter<TTransaction>(deps: SchedulesRouterDeps<TT
try {
await startScheduleRunOnRequest({ c, item: { run, schedule }, deps });
} catch (error) {
- await deps.scheduleStore.updateRunStatus({
+ await deps.scheduleStore.updateRun({
tenant_id: requestContext.tenant_id,
id: run.id,
status: 'failed',
diff --git a/packages/trueforge/src/controller/scheduleDispatch.ts b/packages/trueforge/src/controller/scheduleDispatch.ts
index 7407d097f..c1dd6797b 100644
--- a/packages/trueforge/src/controller/scheduleDispatch.ts
+++ b/packages/trueforge/src/controller/scheduleDispatch.ts
@@ -86,15 +86,17 @@ export interface PreparedScheduleTurn {
agent: AgentRecord;
}
-export async function startScheduleRun(params: {
+export async function startScheduleRun<TTransaction>(params: {
item: ScheduleDispatchItem;
sessions: Sessions;
agentStore: IAgentStore;
+ scheduleStore: Pick<IScheduleStore<TTransaction>, 'updateRun'>;
}): Promise<PreparedScheduleTurn | undefined> {
const {
item: { run, schedule },
sessions,
agentStore,
+ scheduleStore,
} = params;
const named = await agentStore.getAgent({ tenant_id: schedule.tenant_id, name: schedule.agent_name });
@@ -110,6 +112,14 @@ export async function startScheduleRun(params: {
source: { type: 'schedule', id: schedule.id, run_id: run.id },
});
+ // This is not atomic with session creation so a failure here leaves the run unlinked.
+ // Runs before the idempotency check so retries relink it, at the cost of redundant writes on re-delivery.
+ await scheduleStore.updateRun({
+ tenant_id: schedule.tenant_id,
+ id: run.id,
+ session_id: session.session_id,
+ });
+
// idempotency check
const { data: turns } = await session.listTurns({ limit: 1 });
if (turns.length > 0) {
@@ -164,7 +174,7 @@ async function finishScheduledRun<TTransaction>(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(
+ const updated = await store.updateRun(
{ tenant_id: run.tenant_id, id: run.id, status, reason: reason ?? null },
txn,
);
diff --git a/packages/trueforge/src/db/postgres/migrations/20261016_000001_schedule_run_session_id.ts b/packages/trueforge/src/db/postgres/migrations/20261016_000001_schedule_run_session_id.ts
new file mode 100644
index 000000000..f832be17c
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20261016_000001_schedule_run_session_id.ts
@@ -0,0 +1,22 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Session a schedule run created.
+ * Backfills from `session.external_id`, which is the run id; runs without a session stay NULL.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.alterTable('schedule_run').addColumn('session_id', 'text').execute();
+ await sql`
+ UPDATE schedule_run AS r
+ SET session_id = s.session_id
+ FROM session AS s
+ WHERE s.tenant_id = r.tenant_id
+ AND s.external_id = r.id
+ `.execute(db);
+}
+
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.alterTable('schedule_run').dropColumn('session_id').execute();
+}
diff --git a/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts b/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
index ae7b5a98f..f53fc73fe 100644
--- a/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
+++ b/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
@@ -3,7 +3,7 @@ import {
decodeOffsetPageToken,
paginateOffsetRows,
} from '@truefoundry/trueforge-core/agent-session/store/OffsetPageToken';
-import { sql, type Kysely, type Selectable, type Transaction } from 'kysely';
+import { sql, type Kysely, type Selectable, type Transaction, type UpdateObject } from 'kysely';
import { nextTriggerAfter } from '../../../runtime/cron';
import { newId } from '../../../utils/id';
import {
@@ -28,7 +28,7 @@ import {
type ScheduleRunRecord,
type ScheduleWriteResult,
type UpdateScheduleInput,
- type UpdateScheduleRunStatusInput,
+ type UpdateScheduleRunInput,
} from '../../scheduleStore';
import { isUniqueViolation } from '../client';
import { json, now, whereCreatedByOrAgentIds } from '../sqlExpressions';
@@ -60,6 +60,7 @@ function toRunRecord(row: Selectable<ScheduleRunTable>): ScheduleRunRecord {
created_by_subject: CreatedBySubjectSchema.parse(row.created_by_subject),
triggered_at: row.triggered_at === null ? null : row.triggered_at.toISOString(),
reason: row.reason,
+ session_id: row.session_id,
created_at: row.created_at.toISOString(),
updated_at: row.updated_at.toISOString(),
};
@@ -328,6 +329,7 @@ export class PostgresScheduleStore implements IScheduleStore<Transaction<Databas
created_by_subject: json(input.created_by_subject),
triggered_at: input.triggered_at ?? null,
reason: input.reason ?? null,
+ session_id: null,
created_at: now(),
updated_at: now(),
})
@@ -342,17 +344,23 @@ export class PostgresScheduleStore implements IScheduleStore<Transaction<Databas
}
}
- async updateRunStatus(
- input: UpdateScheduleRunStatusInput,
+ async updateRun(
+ input: UpdateScheduleRunInput,
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: timestamp, reason, updated_at: timestamp }
- : { status: input.status, reason, updated_at: timestamp };
+ const patch: UpdateObject<Database, 'schedule_run'> = { updated_at: timestamp };
+ if (input.status !== undefined) {
+ patch.status = input.status;
+ patch.reason = input.status === 'failed' ? (input.reason ?? null) : null;
+ if (input.status === 'triggered') {
+ patch.triggered_at = timestamp;
+ }
+ }
+ if (input.session_id !== undefined) {
+ patch.session_id = input.session_id;
+ }
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 65e2c877f..8fd0b0033 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -521,6 +521,7 @@ export interface ScheduleRunTable {
created_by_subject: JSONColumnType<CreatedBySubject, CreatedBySubject, CreatedBySubject>;
triggered_at: Date | null;
reason: string | null;
+ session_id: 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 dc850d6dd..a29fec81e 100644
--- a/packages/trueforge/src/db/scheduleStore.ts
+++ b/packages/trueforge/src/db/scheduleStore.ts
@@ -64,6 +64,7 @@ export interface ScheduleRunRecord {
created_by_subject: CreatedBySubject;
triggered_at: string | null;
reason: string | null;
+ session_id: string | null;
created_at: string;
updated_at: string;
}
@@ -183,11 +184,14 @@ export interface GetScheduledRunForInput {
schedule_id: string;
}
-export interface UpdateScheduleRunStatusInput {
+/** Patch for one run; omitted fields are left unchanged. */
+export interface UpdateScheduleRunInput {
tenant_id: string;
id: string;
- status: ScheduleRunStatus;
+ status?: ScheduleRunStatus;
+ /** Only applied with `status`; kept for `failed`, cleared otherwise. */
reason?: string | null;
+ session_id?: string;
}
export class ScheduleRunConflictError extends Error {
@@ -274,13 +278,10 @@ export interface IScheduleStore<TTransaction = never> {
/** Inserts a run. Throws {@link ScheduleRunConflictError} on either unique index. */
createRun(input: CreateScheduleRunInput, transaction?: TTransaction): Promise<ScheduleRunRecord>;
/**
- * Status transition. Stamps `triggered_at` when moving to `triggered`.
+ * Patches a run. A status change stamps `triggered_at` when moving to `triggered`.
* Returns undefined when the row is gone (e.g. pause deleted it).
*/
- updateRunStatus(
- input: UpdateScheduleRunStatusInput,
- transaction?: TTransaction,
- ): Promise<ScheduleRunRecord | undefined>;
+ updateRun(input: UpdateScheduleRunInput, transaction?: TTransaction): Promise<ScheduleRunRecord | undefined>;
/**
* `scheduled` runs with `scheduled_for <= now`, oldest first.
* Triggered / terminal rows are never returned.
diff --git a/packages/trueforge/src/db/sqlite/migrations/20261016_000001_schedule_run_session_id.ts b/packages/trueforge/src/db/sqlite/migrations/20261016_000001_schedule_run_session_id.ts
new file mode 100644
index 000000000..f0ede19fe
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20261016_000001_schedule_run_session_id.ts
@@ -0,0 +1,28 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Mirrors db/postgres/migrations/20261016_000001_schedule_run_session_id.ts.
+ * Backfills from `session.external_id`, which is the run id; runs without a session stay NULL.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`
+ ALTER TABLE schedule_run
+ ADD COLUMN session_id TEXT
+ `.execute(trx);
+ await sql`
+ UPDATE schedule_run
+ SET session_id = (
+ SELECT s.session_id
+ FROM session AS s
+ WHERE s.tenant_id = schedule_run.tenant_id
+ AND s.external_id = schedule_run.id
+ )
+ `.execute(trx);
+ });
+}
+
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ void db;
+ return Promise.reject(new Error('20261016_000001_schedule_run_session_id is not reversible'));
+}
diff --git a/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts b/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
index ab57e1a27..a824b372e 100644
--- a/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
+++ b/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
@@ -7,7 +7,7 @@ import {
decodeOffsetPageToken,
paginateOffsetRows,
} from '@truefoundry/trueforge-core/agent-session/store/OffsetPageToken';
-import { sql, type ExpressionBuilder, type Kysely, type Transaction } from 'kysely';
+import { sql, type ExpressionBuilder, type Kysely, type Transaction, type UpdateObject } from 'kysely';
import { nextTriggerAfter } from '../../../runtime/cron';
import type { ScheduleManifest, ScheduleRunStatus, ScheduleStatus } from '../../../schemas/schedule';
import { newId } from '../../../utils/id';
@@ -33,7 +33,7 @@ import {
type ScheduleRunRecord,
type ScheduleWriteResult,
type UpdateScheduleInput,
- type UpdateScheduleRunStatusInput,
+ type UpdateScheduleRunInput,
} from '../../scheduleStore';
import { isUniqueViolation } from '../client';
import { jsonbBind, jsonText, nowIso, whereCreatedByOrAgentIds } from '../sqlExpressions';
@@ -66,6 +66,7 @@ function runColumns(eb: ExpressionBuilder<Database, 'schedule_run'>) {
jsonText<CreatedBySubject>(eb.ref('created_by_subject')).as('created_by_subject'),
'triggered_at' as const,
'reason' as const,
+ 'session_id' as const,
'created_at' as const,
'updated_at' as const,
];
@@ -94,6 +95,7 @@ interface RunRow {
created_by_subject: CreatedBySubject;
triggered_at: string | null;
reason: string | null;
+ session_id: string | null;
created_at: string;
updated_at: string;
}
@@ -382,6 +384,7 @@ export class SqliteScheduleStore implements IScheduleStore<Transaction<Database>
created_by_subject: jsonbBind(input.created_by_subject),
triggered_at: input.triggered_at?.toISOString() ?? null,
reason: input.reason ?? null,
+ session_id: null,
created_at: timestamp,
updated_at: timestamp,
})
@@ -396,17 +399,23 @@ export class SqliteScheduleStore implements IScheduleStore<Transaction<Database>
}
}
- async updateRunStatus(
- input: UpdateScheduleRunStatusInput,
+ async updateRun(
+ input: UpdateScheduleRunInput,
transaction?: 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, reason, updated_at: timestamp }
- : { status: input.status, reason, updated_at: timestamp };
+ const patch: UpdateObject<Database, 'schedule_run'> = { updated_at: timestamp };
+ if (input.status !== undefined) {
+ patch.status = input.status;
+ patch.reason = input.status === 'failed' ? (input.reason ?? null) : null;
+ if (input.status === 'triggered') {
+ patch.triggered_at = timestamp;
+ }
+ }
+ if (input.session_id !== undefined) {
+ patch.session_id = input.session_id;
+ }
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 277bb85b4..743e005ce 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -355,6 +355,7 @@ export interface ScheduleRunTable {
created_by_subject: JsonbColumn<CreatedBySubject>;
triggered_at: string | null;
reason: string | null;
+ session_id: 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 2c50910ef..e37f09587 100644
--- a/packages/trueforge/src/schemas/schedule.ts
+++ b/packages/trueforge/src/schemas/schedule.ts
@@ -132,7 +132,7 @@ export const DeleteScheduleResponseSchema = z.object({}).openapi('DeleteSchedule
* Run lifecycle.
* - `scheduled` the one pending run; at most one per schedule, enforced by
* `schedule_run_pending_uq`
- * - `triggered` taken by dispatch via `updateRunStatus`
+ * - `triggered` taken by dispatch via `updateRun`
* - `failed` errored, or hand-off to the executor failed
*/
export const ScheduleRunStatusSchema = z.enum(['scheduled', 'triggered', 'failed']).openapi('ScheduleRunStatus');
@@ -147,6 +147,7 @@ export const ScheduleRunSchema = z
created_by_subject: CreatedBySubjectSchema,
triggered_at: NullableIsoTimestamp,
reason: z.string().nullable(),
+ session_id: 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 e7b922036..3664ab818 100644
--- a/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
+++ b/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
@@ -120,7 +120,7 @@ export function runScheduleDispatchContractSuite<TTransaction>(deps: {
});
// Mark the auto-added pending run failed so the exact run can be added.
if (pendingRun !== undefined) {
- await store.updateRunStatus({ tenant_id: TENANT, id: pendingRun.id, status: 'failed' });
+ await store.updateRun({ tenant_id: TENANT, id: pendingRun.id, status: 'failed' });
}
const run = await store.createRun({
tenant_id: TENANT,
diff --git a/packages/trueforge/tests/db/scheduleStoreContractSuite.ts b/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
index 3f2470daa..0939fcfc9 100644
--- a/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
+++ b/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
@@ -323,7 +323,7 @@ export function runScheduleStoreContractSuite(deps: {
status: 'scheduled',
created_by_subject: USER_SUBJECT,
});
- await store.updateRunStatus({
+ await store.updateRun({
tenant_id: TENANT,
id: triggeredSeed.id,
status: 'triggered',
@@ -370,7 +370,7 @@ export function runScheduleStoreContractSuite(deps: {
status: 'scheduled',
created_by_subject: USER_SUBJECT,
});
- await store.updateRunStatus({
+ await store.updateRun({
tenant_id: TENANT,
id: historical.id,
status: 'triggered',
@@ -454,7 +454,7 @@ export function runScheduleStoreContractSuite(deps: {
status: 'scheduled',
created_by_subject: USER_SUBJECT,
});
- await store.updateRunStatus({ tenant_id: TENANT, id: first.id, status: 'triggered' });
+ await store.updateRun({ tenant_id: TENANT, id: first.id, status: 'triggered' });
await expect(
store.createRun({
@@ -785,7 +785,7 @@ export function runScheduleStoreContractSuite(deps: {
expect(page2.pagination.next_page_token).toBeUndefined();
});
- it('updateRunStatus stamps triggered_at only for triggered; returns undefined when gone', async () => {
+ it('updateRun stamps triggered_at only for triggered; returns undefined when gone', async () => {
const store = deps.getScheduleStore();
const agent = await seedAgent();
const { schedule } = await store.createScheduleAndRun({
@@ -812,7 +812,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({
+ const triggered = await store.updateRun({
tenant_id: TENANT,
id: toTrigger.id,
status: 'triggered',
@@ -832,7 +832,7 @@ export function runScheduleStoreContractSuite(deps: {
// Pending unique allows only one scheduled row — finish triggered before seeding failed.
const toFail = await seedScheduled(new Date('2026-08-27T12:00:00.000Z'));
- const failed = await store.updateRunStatus({
+ const failed = await store.updateRun({
tenant_id: TENANT,
id: toFail.id,
status: 'failed',
@@ -855,7 +855,7 @@ export function runScheduleStoreContractSuite(deps: {
status: 'scheduled',
created_by_subject: USER_SUBJECT,
});
- const failedWithoutReason = await store.updateRunStatus({
+ const failedWithoutReason = await store.updateRun({
tenant_id: TENANT,
id: toFailWithoutReason.id,
status: 'failed',
@@ -878,7 +878,7 @@ export function runScheduleStoreContractSuite(deps: {
reason: 'stale failure',
});
expect(toClearReason.reason).toBe('stale failure');
- const cleared = await store.updateRunStatus({
+ const cleared = await store.updateRun({
tenant_id: TENANT,
id: toClearReason.id,
status: 'triggered',
@@ -893,11 +893,57 @@ export function runScheduleStoreContractSuite(deps: {
await store.deleteSchedule({ tenant_id: TENANT, id: schedule.id });
expect(
- await store.updateRunStatus({
+ await store.updateRun({
tenant_id: TENANT,
id: triggered.id,
status: 'failed',
}),
).toBeUndefined();
});
+
+ it('updateRun with only session_id links the run without touching status fields', async () => {
+ const store = deps.getScheduleStore();
+ const agent = await seedAgent();
+ const { schedule } = await store.createScheduleAndRun({
+ tenant_id: TENANT,
+ agent_id: agent.id,
+ agent_name: agent.name,
+ name: 'run-session',
+ manifest: manifest({ status: 'paused' }),
+ created_by_subject: USER_SUBJECT,
+ runFrom: new Date(),
+ });
+ const triggeredAt = new Date('2026-08-27T10:00:00.000Z');
+ const run = await store.createRun({
+ tenant_id: TENANT,
+ schedule_id: schedule.id,
+ name: cronRunName(triggeredAt),
+ scheduled_for: triggeredAt,
+ status: 'failed',
+ created_by_subject: USER_SUBJECT,
+ triggered_at: triggeredAt,
+ reason: 'turn failed',
+ });
+ expect(run.session_id).toBeNull();
+
+ const linked = await store.updateRun({ tenant_id: TENANT, id: run.id, session_id: 'session-1' });
+ expect(linked).toEqual(
+ expect.objectContaining({
+ id: run.id,
+ session_id: 'session-1',
+ status: 'failed',
+ reason: 'turn failed',
+ triggered_at: run.triggered_at,
+ }),
+ );
+ expect(await store.getRun({ tenant_id: TENANT, id: run.id })).toEqual(linked);
+
+ const retriggered = await store.updateRun({ tenant_id: TENANT, id: run.id, status: 'triggered' });
+ expect(retriggered).toEqual(
+ expect.objectContaining({ status: 'triggered', reason: null, session_id: 'session-1' }),
+ );
+
+ await store.deleteSchedule({ tenant_id: TENANT, id: schedule.id });
+ expect(await store.updateRun({ tenant_id: TENANT, id: run.id, session_id: 'session-2' })).toBeUndefined();
+ });
}
diff --git a/packages/trueforge/tests/unit/apis/schedules.test.ts b/packages/trueforge/tests/unit/apis/schedules.test.ts
index 51fa79f64..49194728a 100644
--- a/packages/trueforge/tests/unit/apis/schedules.test.ts
+++ b/packages/trueforge/tests/unit/apis/schedules.test.ts
@@ -318,6 +318,7 @@ describe('create schedule run', () => {
schedule_id: scheduleId,
status: 'triggered',
reason: null,
+ session_id: null,
created_by_subject: {
subject_id: 'alice',
subject_type: 'user',
@@ -347,6 +348,29 @@ describe('create schedule run', () => {
expect(runs.data.map(r => r.status).sort()).toEqual(['scheduled', 'triggered']);
});
+ it('returns the linked session_id from run-now and the runs list', async () => {
+ const { app, asUser, postJson } = await setup();
+ mockedStartScheduleRun.mockImplementation(async ({ item, scheduleStore }) => {
+ await scheduleStore.updateRun({ tenant_id: item.run.tenant_id, id: item.run.id, session_id: 'session-1' });
+ return undefined;
+ });
+
+ asUser(ALICE);
+ const created = await postJson('/', 'POST', scheduleBody);
+ const { id: scheduleId } = ((await created.json()) as { data: { id: string } }).data;
+
+ const res = await postJson('/runs', 'POST', { schedule_id: scheduleId });
+ expect(res.status).toBe(201);
+ const runNow = CreateScheduleRunResponseSchema.parse(await res.json()).data;
+ expect(runNow.session_id).toBe('session-1');
+
+ const list = ListScheduleRunsResponseSchema.parse(await (await app.request(`/${scheduleId}/runs`)).json());
+ expect(list.data.map(run => [run.status, run.session_id]).sort()).toEqual([
+ ['scheduled', null],
+ ['triggered', 'session-1'],
+ ]);
+ });
+
it('does not let an OIDC settings admin trigger another creator schedule', async () => {
const { asUser, postJson } = await setup();
diff --git a/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts b/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
index 15ef6a5ef..bbac54f33 100644
--- a/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
+++ b/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
@@ -35,6 +35,7 @@ function item(): ScheduleDispatchItem {
created_by_subject: { subject_id: 'tester', subject_type: 'user', subject_display_name: 'tester' },
triggered_at: null,
reason: null,
+ session_id: null,
created_at: '2026-08-31T00:00:00.000Z',
updated_at: '2026-08-31T00:00:00.000Z',
},
@@ -67,7 +68,7 @@ function fakeStore(dispatchItem: ScheduleDispatchItem) {
listScheduledRuns: jest.fn().mockResolvedValue([dispatchItem.run]),
getSchedule: jest.fn().mockResolvedValue(dispatchItem.schedule),
getScheduleForUpdate: jest.fn().mockResolvedValue(dispatchItem.schedule),
- updateRunStatus: jest.fn().mockResolvedValue(dispatchItem.run satisfies ScheduleRunRecord),
+ updateRun: jest.fn().mockResolvedValue(dispatchItem.run satisfies ScheduleRunRecord),
createRun: jest.fn().mockResolvedValue(undefined),
};
}
@@ -136,17 +137,20 @@ describe('startScheduleRun', () => {
it('get-or-creates a session and returns a prepared turn with the schedule task', async () => {
const dispatchItem = item();
const listTurns = jest.fn().mockResolvedValue({ data: [] });
- const session = { listTurns };
+ const session = { session_id: 'session-1', listTurns };
const getOrCreateByExternalId = jest.fn().mockResolvedValue({ session, created: true });
const getAgent = jest.fn().mockResolvedValue({ id: 'agent-1', name: 'reporter' });
+ const updateRun = jest.fn().mockResolvedValue(undefined);
const prepared = await startScheduleRun({
item: dispatchItem,
sessions: { getOrCreateByExternalId } as never,
agentStore: { getAgent } as never,
+ scheduleStore: { updateRun },
});
expect(getAgent).toHaveBeenCalledWith({ tenant_id: 'default', name: 'reporter' });
+ expect(updateRun).toHaveBeenCalledWith({ tenant_id: 'default', id: 'run-1', session_id: 'session-1' });
expect(getOrCreateByExternalId).toHaveBeenCalledWith({
tenant_id: 'default',
external_id: 'run-1',
@@ -163,31 +167,37 @@ describe('startScheduleRun', () => {
});
});
- it('returns undefined when the session already has a turn', async () => {
+ it('links the session and returns undefined when the session already has a turn', async () => {
const listTurns = jest.fn().mockResolvedValue({ data: [{ turn_id: 'turn-1' }] });
const getOrCreateByExternalId = jest.fn().mockResolvedValue({
- session: { listTurns },
+ session: { session_id: 'session-1', listTurns },
created: false,
});
const getAgent = jest.fn().mockResolvedValue({ id: 'agent-1', name: 'reporter' });
+ const updateRun = jest.fn().mockResolvedValue(undefined);
const prepared = await startScheduleRun({
item: item(),
sessions: { getOrCreateByExternalId } as never,
agentStore: { getAgent } as never,
+ scheduleStore: { updateRun },
});
expect(prepared).toBeUndefined();
+ expect(updateRun).toHaveBeenCalledWith({ tenant_id: 'default', id: 'run-1', session_id: 'session-1' });
});
- it('throws when the schedule agent is missing', async () => {
+ it('throws without linking when the schedule agent is missing', async () => {
+ const updateRun = jest.fn();
await expect(
startScheduleRun({
item: item(),
sessions: { getOrCreateByExternalId: jest.fn() } as never,
agentStore: { getAgent: jest.fn().mockResolvedValue(undefined) } as never,
+ scheduleStore: { updateRun },
}),
).rejects.toBeInstanceOf(ScheduleAgentNotFoundError);
+ expect(updateRun).not.toHaveBeenCalled();
});
});
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/schedule_run.py b/python/trueforge_sdk/src/trueforge_sdk/types/schedule_run.py
index 9baeaf1cf..a4db3b34f 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/schedule_run.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/schedule_run.py
@@ -18,6 +18,7 @@ class ScheduleRun(UncheckedBaseModel):
reason: typing.Optional[str] = None
schedule_id: str
scheduled_for: dt.datetime
+ session_id: typing.Optional[str] = None
status: ScheduleRunStatus
triggered_at: typing.Optional[dt.datetime] = None
updated_at: dt.datetime