@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
@@ -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`.
@@ -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"
         ],
 
@@ -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"
         ],
 
@@ -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;
 
@@ -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;
 
@@ -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"),
 
@@ -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',
 
@@ -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,
     );
 
@@ -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();
+}
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@truefoundry/trueforge-sdk": patch
 +---
++
 +Regenerate SDK from updated OpenAPI spec.