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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.ScheduleRureason: 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.tsindex 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.tsindex 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<TTtry {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.tsindex 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 checkconst { 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.tsnew file mode 100644index 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.tsindex 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<Databascreated_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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 = zcreated_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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.pyindex 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] = Noneschedule_id: strscheduled_for: dt.datetime+ session_id: typing.Optional[str] = Nonestatus: ScheduleRunStatustriggered_at: typing.Optional[dt.datetime] = Noneupdated_at: dt.datetime