feat(sdk): allow a ttl on session-triggered runs

Author: kathiekiwi

.changeset/chat-session-run-ttl.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Chat server sessions can now set a `ttl` on the runs they trigger, so a run that is never picked up expires instead of waiting indefinitely.

packages/core/src/v3/schemas/api.ts

@@ -1824,6 +1824,11 @@ export const SessionTriggerConfig = z.object({
   lockToVersion: z.string().optional(),
   /** Region to schedule runs in. Forwarded to `TaskRunOptions.region`. */
   region: z.string().optional(),
+  /**
+   * How long a run may sit undequeued before it expires (duration string
+   * like `"2m"`, or seconds). Forwarded to `TaskRunOptions.ttl`.
+   */
+  ttl: z.string().or(z.number().nonnegative().int()).optional(),
   /** Convenience field surfaced to chat.agent via the wire payload. */
   idleTimeoutInSeconds: z.number().int().positive().max(3600).optional(),
 });

packages/trigger-sdk/src/v3/ai.ts

@@ -10448,6 +10448,7 @@ function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(
     const maxDuration = params.triggerConfig?.maxDuration ?? options?.triggerConfig?.maxDuration;
     const idleTimeoutInSeconds =
       params.triggerConfig?.idleTimeoutInSeconds ?? options?.triggerConfig?.idleTimeoutInSeconds;
+    const ttl = params.triggerConfig?.ttl ?? options?.triggerConfig?.ttl;
 
     const triggerConfig: SessionTriggerConfig = {
       basePayload: {
@@ -10470,6 +10471,7 @@ function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(
       ...(options?.triggerConfig?.region || params.triggerConfig?.region
         ? { region: params.triggerConfig?.region ?? options?.triggerConfig?.region }
         : {}),
+      ...(ttl !== undefined ? { ttl } : {}),
       ...(options?.triggerConfig?.lockToVersion || params.triggerConfig?.lockToVersion
         ? {
             lockToVersion:

packages/trigger-sdk/src/v3/chat-server.test.ts

@@ -216,7 +216,7 @@ describe("chat.headStart (route handler)", () => {
     expect(body.triggerConfig.basePayload.idleTimeoutInSeconds).toBe(60);
   });
 
-  it("merges triggerConfig tags and queue into createSession", async () => {
+  it("merges triggerConfig tags, queue and ttl into createSession", async () => {
     const requests: CapturedRequest[] = [];
     global.fetch = vi.fn().mockImplementation(async (url: string | URL, init?: RequestInit) => {
       const urlStr = typeof url === "string" ? url : url.toString();
@@ -248,6 +248,7 @@ describe("chat.headStart (route handler)", () => {
       triggerConfig: {
         tags: ["org:acme", "agentic-run:xyz"],
         queue: "my-queue",
+        ttl: "2m",
       },
       run: async ({ chat: chatHelper }) => {
         return streamText({
@@ -276,6 +277,7 @@ describe("chat.headStart (route handler)", () => {
     const body = JSON.parse(sessionCreate!.init!.body as string);
     expect(body.triggerConfig.tags).toEqual(["chat:chat-1", "org:acme", "agentic-run:xyz"]);
     expect(body.triggerConfig.queue).toBe("my-queue");
+    expect(body.triggerConfig.ttl).toBe("2m");
     expect(body.triggerConfig.basePayload.trigger).toBe("handover-prepare");
     expect(body.triggerConfig.basePayload.chatId).toBe("chat-1");
   });

packages/trigger-sdk/src/v3/chat-server.ts

@@ -550,6 +550,7 @@ async function openHandoverSession(opts: {
       ? { maxDuration: opts.triggerConfig.maxDuration }
       : {}),
     ...(opts.triggerConfig?.region ? { region: opts.triggerConfig.region } : {}),
+    ...(opts.triggerConfig?.ttl !== undefined ? { ttl: opts.triggerConfig.ttl } : {}),
     ...(opts.triggerConfig?.lockToVersion
       ? { lockToVersion: opts.triggerConfig.lockToVersion }
       : {}),

packages/trigger-sdk/src/v3/createStartSessionAction.test.ts

@@ -115,21 +115,32 @@ describe("chat.createStartSessionAction — runtime", () => {
     ]);
   });
 
-  it("forwards maxDuration, region, and lockToVersion from triggerConfig", async () => {
+  it("forwards maxDuration, region, lockToVersion, and ttl from triggerConfig", async () => {
     installStartFixture();
 
     const start = chat.createStartSessionAction("fake-chat", {
       triggerConfig: {
         maxDuration: 120,
         region: "us-east-1",
         lockToVersion: "20260101.1",
+        ttl: "2m",
       },
     });
     await start({ chatId: "chat-parity" });
 
     expect(lastStartBody?.triggerConfig.maxDuration).toBe(120);
     expect(lastStartBody?.triggerConfig.region).toBe("us-east-1");
     expect(lastStartBody?.triggerConfig.lockToVersion).toBe("20260101.1");
+    expect(lastStartBody?.triggerConfig.ttl).toBe("2m");
+  });
+
+  it("omits ttl when triggerConfig does not set it", async () => {
+    installStartFixture();
+
+    const start = chat.createStartSessionAction("fake-chat");
+    await start({ chatId: "chat-no-ttl" });
+
+    expect(lastStartBody?.triggerConfig).not.toHaveProperty("ttl");
   });
 
   it("server-mints override tokens for additional API keys", async () => {