feat(sdk,webapp): tag chat sessions, and tag dashboard agent chats by org, project, env and user

```ts
await startChatSession({
  chatId,
  clientData,
  tags: [`org:${org.slug}`, `user:${user.id}`], // the Session's own tags
  triggerConfig: { tags: [`org:${org.slug}`] }, // tags on its runs, as before
});
```

`chat.createStartSessionAction`, `chat.headStart` and
`chat.startHeadStart` now accept `tags` for the Session itself. Until
now they only forwarded `triggerConfig.tags`, which tag the session's
runs, so chat sessions couldn't be filtered on the Sessions page.

The dashboard agent uses this to tag every chat's session and runs by
organization, project, environment and user. Run tags come from the
session's trigger config, so runs the session starts later carry them
too.

Mono-RevId: af4ac8b786f6f6b13b2f5c5aab8a6af4e2ab5113

Author: ericallam

.changeset/chat-session-tags.md

@@ -0,0 +1,9 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+`chat.createStartSessionAction`, `chat.headStart` and `chat.startHeadStart` now accept `tags` for the Session itself, so chat sessions can be filtered by tag on the Sessions page. `triggerConfig.tags` still tags the session's runs.
+
+```ts
+await startChatSession({ chatId, clientData, tags: [`org:${org.slug}`, `user:${user.id}`] });
+```

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.dashboard-agent.ts

@@ -51,6 +51,7 @@ import {
   resolveDashboardAgentRepoSnapshot,
   startDashboardAgentSession,
 } from "~/services/dashboardAgent.server";
+import { dashboardAgentTags } from "~/services/dashboardAgentTags";
 import { dashboardAgentEnvironmentAddress } from "~/services/dashboardAgentEnvironmentAddress.server";
 import { wellFormMessageText } from "~/services/dashboardAgentMessageText.server";
 import { watchErrorStatus } from "~/services/dashboardAgentWatchErrorStatus.server";
@@ -366,6 +367,12 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
     const runtimeEnv = await findEnvironmentBySlug(project.id, envParam, userId);
     if (!runtimeEnv) return json({ error: "Environment not found" }, { status: 404 });
     const environmentAddress = dashboardAgentEnvironmentAddress(runtimeEnv);
+    const tags = dashboardAgentTags({
+      organizationSlug,
+      projectRef: project.externalRef,
+      environmentSlug: runtimeEnv.slug,
+      userId,
+    });
 
     const chatId = generateFriendlyId("chat");
     try {
@@ -416,6 +423,7 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
             mode: repoSnapshot ? "code" : "assistant",
             metadata: headStartMetadata,
             watchEnabled,
+            tags,
           });
         } else {
           // Cold start: the client sends the first message through the `in` proxy, which
@@ -424,6 +432,7 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
           // delegated token on the first turn.
           await startDashboardAgentSession({
             chatId,
+            tags,
             clientData: {
               ...clientContext,
               watchEnabled,
@@ -660,6 +669,12 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
         // is fetched and extracted on the worker).
         await startDashboardAgentSession({
           chatId,
+          tags: dashboardAgentTags({
+            organizationSlug,
+            projectRef: project.externalRef,
+            environmentSlug: runtimeEnv.slug,
+            userId,
+          }),
           clientData: {
             ...pickAgentClientMetadata(clientData),
             // Server-resolved, like every other field here: the resumed run's first turn

apps/webapp/app/services/dashboardAgent.server.ts

@@ -101,13 +101,15 @@ export function isDashboardAgentConfigured(): boolean {
 // when DASHBOARD_AGENT_VERSION is set; unset runs on the env's current version.
 // `ttl` always applies, so an agent run that never gets dequeued expires
 // instead of sitting in the queue indefinitely.
-export function dashboardAgentTriggerConfig(): {
+export function dashboardAgentTriggerConfig(tags: string[] = []): {
   lockToVersion?: string;
   ttl: string;
+  tags?: string[];
 } {
   return {
     ...(env.DASHBOARD_AGENT_VERSION ? { lockToVersion: env.DASHBOARD_AGENT_VERSION } : {}),
     ttl: env.DASHBOARD_AGENT_RUN_TTL,
+    ...(tags.length > 0 ? { tags } : {}),
   };
 }
 
@@ -116,14 +118,19 @@ export function dashboardAgentTriggerConfig(): {
 export async function startDashboardAgentSession(params: {
   chatId: string;
   clientData?: Record<string, unknown>;
+  tags?: string[];
 }): Promise<void> {
   const config = dashboardAgentConfig();
   if (!config) throw new Error("DASHBOARD_AGENT_SECRET_KEY is not set");
   const startSession = chat.createStartSessionAction(TASK_ID, {
     apiClient: config,
-    triggerConfig: dashboardAgentTriggerConfig(),
+    triggerConfig: dashboardAgentTriggerConfig(params.tags),
+  });
+  await startSession({
+    chatId: params.chatId,
+    clientData: params.clientData,
+    ...(params.tags ? { tags: params.tags } : {}),
   });
-  await startSession({ chatId: params.chatId, clientData: params.clientData });
 }
 
 // Read is narrowed to the `.out` stream (`read:sessions:{chatId}:out`): `.in` records carry

apps/webapp/app/services/dashboardAgentHeadStart.server.ts

@@ -91,6 +91,7 @@ export async function startDashboardAgentHeadStart(params: {
   mode: "assistant" | "code";
   metadata: Record<string, unknown>;
   watchEnabled: boolean;
+  tags?: string[];
 }): Promise<void> {
   // The same assembly the agent run uses, so both sides hand the provider one prefix.
   const tools = toolSchemasFor(params.mode, { watchEnabled: params.watchEnabled });
@@ -101,7 +102,8 @@ export async function startDashboardAgentHeadStart(params: {
     chatId: params.chatId,
     messages: params.messages,
     metadata: params.metadata,
-    triggerConfig: dashboardAgentTriggerConfig(),
+    triggerConfig: dashboardAgentTriggerConfig(params.tags),
+    ...(params.tags ? { tags: params.tags } : {}),
     // Scopes session creation and the agent trigger to the agent's own environment.
     apiClient: {
       baseURL: dashboardAgentApiOrigin(),

apps/webapp/app/services/dashboardAgentTags.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+
+const MAX_TAG_LENGTH = 128;
+const HASH_LENGTH = 8;
+
+/** A tag over the limit keeps its prefix and swaps the tail for a hash of the whole, so two long values never share one. */
+function boundedTag(tag: string): string {
+  if (tag.length <= MAX_TAG_LENGTH) return tag;
+  const hash = createHash("sha256").update(tag).digest("hex").slice(0, HASH_LENGTH);
+  return `${tag.slice(0, MAX_TAG_LENGTH - HASH_LENGTH - 1)}~${hash}`;
+}
+
+/**
+ * Tags for finding a chat's session and runs in the agent project's dashboard by who
+ * started it and where. Session and run tags both get them.
+ */
+export function dashboardAgentTags(params: {
+  organizationSlug: string;
+  projectRef: string;
+  environmentSlug: string;
+  userId: string;
+}): string[] {
+  return [
+    `org:${params.organizationSlug}`,
+    `project:${params.projectRef}`,
+    `env:${params.environmentSlug}`,
+    `user:${params.userId}`,
+  ].map(boundedTag);
+}

apps/webapp/test/dashboardAgentClientMetadata.test.ts

@@ -119,6 +119,30 @@ async function startChat(clientData: Record<string, unknown>) {
   return mocks.startSession.mock.calls[0][0].clientData as Record<string, unknown>;
 }
 
+describe("dashboard agent start intent — tags", () => {
+  beforeEach(() => {
+    mocks.findEnvironmentBySlug.mockReset().mockResolvedValue({
+      id: "env_real",
+      slug: "dev",
+      type: "DEVELOPMENT",
+      branchName: null,
+    });
+    mocks.chatExists.mockReset().mockResolvedValue(true);
+    mocks.startSession.mockReset().mockResolvedValue(undefined);
+  });
+
+  it("tags the session it starts for an existing chat like a new one", async () => {
+    await startChat({});
+
+    expect(mocks.startSession.mock.calls[0][0].tags).toEqual([
+      "org:acme",
+      "project:proj_ref_real",
+      "env:dev",
+      "user:usr_real",
+    ]);
+  });
+});
+
 describe.each([
   ["in proxy", appendTurn],
   ["start intent", startChat],

apps/webapp/test/dashboardAgentTags.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { dashboardAgentTags } from "~/services/dashboardAgentTags";
+
+const SCOPE = { organizationSlug: "acme", projectRef: "proj_abc", userId: "user_1" };
+
+describe("dashboard agent tags", () => {
+  it("tags a chat by organization, project, environment and user", () => {
+    expect(dashboardAgentTags({ ...SCOPE, environmentSlug: "prod" })).toEqual([
+      "org:acme",
+      "project:proj_abc",
+      "env:prod",
+      "user:user_1",
+    ]);
+  });
+
+  it("keeps two long branch slugs with a shared prefix apart, within the limit", () => {
+    const shared = "feature-".repeat(20);
+    const [alpha] = dashboardAgentTags({ ...SCOPE, environmentSlug: `${shared}alpha` }).filter(
+      (tag) => tag.startsWith("env:")
+    );
+    const [beta] = dashboardAgentTags({ ...SCOPE, environmentSlug: `${shared}beta` }).filter(
+      (tag) => tag.startsWith("env:")
+    );
+
+    expect(alpha!.length).toBeLessThanOrEqual(128);
+    expect(beta!.length).toBeLessThanOrEqual(128);
+    expect(alpha).not.toBe(beta);
+    expect(dashboardAgentTags({ ...SCOPE, environmentSlug: `${shared}alpha` })).toContain(alpha);
+  });
+});

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

@@ -13204,6 +13204,11 @@ export type ChatStartSessionParams<TChat extends AnyTask = AnyTask> = {
    * server-side metadata that doesn't go through the agent's `clientDataSchema`.
    */
   metadata?: Record<string, unknown>;
+  /**
+   * Up to 10 tags on the Session row, for filtering sessions in the dashboard.
+   * Run tags go in `triggerConfig.tags`.
+   */
+  tags?: string[];
 };
 
 /**
@@ -13361,6 +13366,7 @@ function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(
       taskIdentifier: taskId,
       triggerConfig,
       metadata: params.metadata,
+      ...(params.tags !== undefined ? { tags: params.tags } : {}),
     };
 
     const baseURLOption = options?.baseURL;

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

@@ -716,6 +716,36 @@ describe("chat.startHeadStart (detached)", () => {
     expect(body.triggerConfig.basePayload.headStartMessages[0].id).toBe("m1");
   });
 
+  it("puts session tags on the created session", async () => {
+    const requests: CapturedRequest[] = [];
+    wireFetch(requests);
+
+    const result = await withApiContext(() =>
+      chat.startHeadStart({
+        agentId: "test-agent",
+        chatId: "chat-tags",
+        messages: userMessages,
+        tags: ["org:acme", "project:proj_1"],
+        triggerConfig: { tags: ["org:acme"] },
+        run: async ({ chat: chatHelper }) =>
+          streamText({
+            ...chatHelper.toStreamTextOptions(),
+            model: new MockLanguageModelV3({
+              doStream: async () => ({ stream: textStream("hi back") }),
+            }),
+          }),
+      })
+    );
+    await result.completion;
+
+    const sessionCreate = requests.find(
+      (r) => r.url.endsWith("/api/v1/sessions") || r.url.endsWith("/api/v1/sessions/")
+    );
+    const body = JSON.parse(sessionCreate!.init!.body as string);
+    expect(body.tags).toEqual(["org:acme", "project:proj_1"]);
+    expect(body.triggerConfig.tags).toEqual(["chat:chat-tags", "org:acme"]);
+  });
+
   it("dispatches a final handover (isFinal: true) on a pure-text step 1", async () => {
     const requests: CapturedRequest[] = [];
     wireFetch(requests);

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

@@ -285,6 +285,11 @@ export type HeadStartHandlerOptions<TTools extends Record<string, Tool>> = {
    * the tag length limit (see `chatRunTags`).
    */
   triggerConfig?: Partial<SessionTriggerConfigInput>;
+  /**
+   * Up to 10 tags on the Session itself, for filtering sessions in the dashboard.
+   * Run tags go in `triggerConfig.tags`.
+   */
+  tags?: string[];
   /**
    * API client config (base URL + access token) for creating the session
    * and triggering the agent run. When set, the handler runs under this
@@ -309,6 +314,8 @@ export type StartHeadStartOptions<TTools extends Record<string, Tool>> = {
   idleTimeoutInSeconds?: number;
   /** Run options for the auto-triggered `handover-prepare` run (tags, queue, machine, …). */
   triggerConfig?: Partial<SessionTriggerConfigInput>;
+  /** Up to 10 tags on the Session itself, for filtering sessions in the dashboard. */
+  tags?: string[];
   /** API client config for session creation + trigger when the agent lives in another project/env. */
   apiClient?: ApiClientConfiguration;
   /** Metadata merged into the run's wire payload (auth tokens, context, …). Never sent to the browser. */
@@ -352,6 +359,7 @@ export const chat = {
         agentId: opts.agentId,
         idleTimeoutInSeconds: opts.idleTimeoutInSeconds,
         triggerConfig: opts.triggerConfig,
+        tags: opts.tags,
       });
 
       const helper: HeadStartChatHelper<TTools> = {
@@ -427,6 +435,7 @@ export const chat = {
         agentId: opts.agentId,
         idleTimeoutInSeconds: opts.idleTimeoutInSeconds,
         triggerConfig: opts.triggerConfig,
+        tags: opts.tags,
       });
 
     // Scope session creation + the agent trigger to `apiClient`'s env when
@@ -594,6 +603,8 @@ async function openHandoverSession(opts: {
   agentId: string;
   idleTimeoutInSeconds?: number;
   triggerConfig?: Partial<SessionTriggerConfigInput>;
+  /** Tags on the Session row. */
+  tags?: string[];
   /** Request-lifecycle signal on the HTTP path; omitted on the detached path. */
   requestSignal?: AbortSignal;
 }): Promise<InternalSession> {
@@ -674,6 +685,7 @@ async function openHandoverSession(opts: {
       externalId: chatId,
       taskIdentifier: opts.agentId,
       triggerConfig,
+      ...(opts.tags !== undefined ? { tags: opts.tags } : {}),
     })
   );
   const sessionPublicAccessToken = created.publicAccessToken;