fix(webapp,core,cli): handle task ids that contain a slash

Task ids that contain a slash (for example `types/zod`, or an id that
starts with a slash) now work across more of the product:

- Switching environments keeps you on the current page instead of
dropping you back to the list.
- The test page for a webhook task whose id contains a slash opens
correctly.
- Triggering a task whose id cannot be represented in a URL (for example
one containing an unpaired surrogate) now fails with a clear error
naming the task id, instead of a cryptic URI error.

The HTTP API reference also notes that a task id must be percent-encoded
in the request path when it contains reserved characters such as a
slash.

Mono-RevId: e5209c0dabe872f3527221a5ac42112f2d05fc25

Author: ericallam

.changeset/task-id-url-encoding.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Triggering a task whose id cannot be represented in a URL (for example an id containing an unpaired surrogate) now fails with a clear error naming the task id, instead of a cryptic URI error.

.server-changes/task-ids-with-slashes.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Switching environments now keeps you on the current page when a task's id contains a slash, instead of dropping you back to the list. The test page for a webhook task whose id contains a slash also opens correctly now.

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.test.tasks.$taskParam/route.tsx

@@ -139,7 +139,9 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
 
     if (result.foundTask && result.triggerSource === "WEBHOOK") {
       throw redirect(
-        `/orgs/${organizationSlug}/projects/${projectParam}/env/${envParam}/webhooks/${taskParam}?tab=console`
+        `/orgs/${organizationSlug}/projects/${projectParam}/env/${envParam}/webhooks/${encodeURIComponent(
+          taskParam
+        )}?tab=console`
       );
     }
 

apps/webapp/app/utils/pageSwitching.test.ts

@@ -468,14 +468,22 @@ describe("pages named after something the environment did not issue", () => {
     expect(organizationPortablePage("models/gpt-5")).toBe("models");
   });
 
-  it("keep nothing but a single plain name in that last segment", () => {
+  it("carry a percent-encoded slash in the last segment verbatim", () => {
+    expect(environmentPortablePage("test/tasks/types%2Fzod")).toBe("test/tasks/types%2Fzod");
+    expect(environmentPortablePage("test/tasks/%2Fmy-task")).toBe("test/tasks/%2Fmy-task");
+    expect(environmentPortablePage("models/my%2Fmodel")).toBe("models/my%2Fmodel");
+    expect(environmentPortablePage("models/%2f%2fevil.example.com")).toBe(
+      "models/%2f%2fevil.example.com"
+    );
+  });
+
+  it("drop an empty or traversal-shaped last segment to the list page", () => {
     expect(environmentPortablePage("tasks/standard/..%2f..%2flogin")).toBe("");
     expect(environmentPortablePage("tasks/standard/../../login")).toBe("");
     expect(environmentPortablePage("agents/%2e%2e")).toBe("agents");
     expect(environmentPortablePage("agents/..")).toBe("agents");
     expect(environmentPortablePage("agents/%zz")).toBe("agents");
     expect(environmentPortablePage("agents/")).toBe("agents");
-    expect(environmentPortablePage("models/my%2Fmodel")).toBe("models");
     expect(environmentPortablePage("prompts/my-prompt/extra")).toBe("prompts");
   });
 });
@@ -552,7 +560,6 @@ describe("a page suffix that is not a plain relative page", () => {
       "..%2fbranches",
       "tasks/standard/../../login",
       "agents/..%2f..%2flogin",
-      "models/%2f%2fevil.example.com",
       "dashboards/custom/..%2f..%2flogin",
     ];
 

apps/webapp/app/utils/pageSwitching.ts

@@ -91,9 +91,12 @@ function nearestPage(suffix: string, pages: ReadonlySet<string>): string {
 }
 
 /**
- * `suffix` itself when its last segment names the same thing in every environment, as long as that
- * segment is a single plain one — a traversal or an encoded path in its place falls through to the
- * list page above it.
+ * `suffix` itself when its last segment names the same thing in every environment. The last segment
+ * is carried through verbatim (still percent-encoded), so an id that decodes to one containing a `/`
+ * (e.g. a task id like `types/zod`, or one that starts with a slash, encoded as `types%2Fzod` /
+ * `%2Fmy-task`) keeps its page: the encoded slash stays inside the one segment and never becomes a
+ * nested path. Only a decoded segment that is empty or shaped like a traversal (a `.` or `..` path
+ * segment, or a backslash) falls through to the list page above it.
  */
 function environmentNeutralPage(suffix: string): string | undefined {
   const boundary = suffix.lastIndexOf("/");
@@ -111,7 +114,10 @@ function environmentNeutralPage(suffix: string): string | undefined {
     return undefined;
   }
 
-  return slug !== "" && !/^\.+$/.test(slug) && !/[/\\]/.test(slug) ? suffix : undefined;
+  if (slug === "" || slug.includes("\\")) return undefined;
+  if (slug.split("/").some((part) => part === "." || part === "..")) return undefined;
+
+  return suffix;
 }
 
 /** The page to keep when only the environment changes. */

docs/v3-openapi.yaml

@@ -3912,7 +3912,10 @@ components:
       required: true
       schema:
         type: string
-      description: The id of a task
+      description: |
+        The id of a task. If the id contains characters that are reserved in a URL path, such as a
+        slash (`/`), percent-encode it when building the request path (e.g. `types/zod` becomes
+        `types%2Fzod`).
       example: my-task
     runsFilterWithEnv:
       in: query

packages/cli-v3/src/apiClient.ts

@@ -47,6 +47,7 @@ import {
   ApiBranchListResponseBody,
   GenerateRegistryCredentialsResponseBody,
   RemoteBuildProviderStatusResponseBody,
+  encodeTaskIdForPath,
 } from "@trigger.dev/core/v3";
 import {
   ReportViewModelSchema,
@@ -743,11 +744,15 @@ export class CliApiClient {
       throw new Error("triggerTaskRun: No access token");
     }
 
-    return wrapZodFetch(TriggerTaskResponse, `${this.apiURL}/api/v1/tasks/${taskId}/trigger`, {
-      method: "POST",
-      headers: this.getHeaders(),
-      body: JSON.stringify(body ?? {}),
-    });
+    return wrapZodFetch(
+      TriggerTaskResponse,
+      `${this.apiURL}/api/v1/tasks/${encodeTaskIdForPath(taskId)}/trigger`,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(body ?? {}),
+      }
+    );
   }
 
   get dev() {

packages/core/src/v3/apiClient/encodeTaskIdForPath.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { encodeTaskIdForPath } from "./encodeTaskIdForPath.js";
+
+describe("encodeTaskIdForPath", () => {
+  it("percent-encodes a plain id unchanged", () => {
+    expect(encodeTaskIdForPath("my-task")).toBe("my-task");
+  });
+
+  it("percent-encodes a slash so the id stays a single path segment", () => {
+    expect(encodeTaskIdForPath("types/zod")).toBe("types%2Fzod");
+    expect(encodeTaskIdForPath("/jobs/my-task")).toBe("%2Fjobs%2Fmy-task");
+  });
+
+  it("throws a clear error for an id that cannot be encoded into a URL", () => {
+    expect(() => encodeTaskIdForPath("bad\uD800id")).toThrowError(/Invalid task id/);
+  });
+});

packages/core/src/v3/apiClient/encodeTaskIdForPath.ts

@@ -0,0 +1,20 @@
+/**
+ * Percent-encode a task id for use as a single URL path segment. `encodeURIComponent` throws a
+ * `URIError` for a string that cannot be represented in a URL (an unpaired UTF-16 surrogate);
+ * rethrow it as a clear, actionable error naming the id instead of a cryptic "URI malformed".
+ */
+export function encodeTaskIdForPath(taskId: string): string {
+  try {
+    return encodeURIComponent(taskId);
+  } catch (error) {
+    if (error instanceof URIError) {
+      throw new Error(
+        `Invalid task id ${JSON.stringify(
+          taskId
+        )}: it contains characters that cannot be encoded into a URL (for example an unpaired surrogate). Rename the task to use valid characters.`
+      );
+    }
+
+    throw error;
+  }
+}

packages/core/src/v3/apiClient/index.ts

@@ -109,6 +109,7 @@ import {
   zodfetchCursorPage,
   zodfetchOffsetLimitPage,
 } from "./core.js";
+import { encodeTaskIdForPath } from "./encodeTaskIdForPath.js";
 import { ApiConnectionError, ApiError, BatchNotSealedError } from "./errors.js";
 import { refreshAccessTokenOnce, type RefreshAccessTokenFn } from "./refreshAccessToken.js";
 import {
@@ -207,6 +208,7 @@ export type {
 };
 
 export * from "./getBranch.js";
+export { encodeTaskIdForPath } from "./encodeTaskIdForPath.js";
 
 export type CreatePublicTokenRequestBody = {
   scopes: string[];
@@ -358,7 +360,7 @@ export class ApiClient {
     clientOptions?: ClientTriggerOptions,
     requestOptions?: TriggerRequestOptions
   ) {
-    const encodedTaskId = encodeURIComponent(taskId);
+    const encodedTaskId = encodeTaskIdForPath(taskId);
 
     return zodfetch(
       TriggerTaskResponse,