@trigger.dev/sdk 0.0.0-chat-prerelease-20260520150857 → 0.0.0-chat-prerelease-20260521151946

package/dist/commonjs/v3/ai.d.ts

@@ -2591,9 +2591,17 @@ export type CreateChatStartSessionActionOptions = {
 /**
  * Params for the function returned by {@link createChatStartSessionAction}.
  */
-export type ChatStartSessionParams = {
+export type ChatStartSessionParams<TChat extends AnyTask = AnyTask> = {
     /** Conversation id (mapped to the Session's `externalId`). */
     chatId: string;
+    /**
+     * Typed client data — folded into the first run's `payload.metadata` so
+     * `onPreload`, `onChatStart`, etc. see the same `clientData` shape on the
+     * first turn as subsequent turns get via the transport's `clientData`
+     * option. Typed via the agent's `clientDataSchema` when the action is
+     * parameterised with `createStartSessionAction<typeof myChat>(...)`.
+     */
+    clientData?: InferChatClientData<TChat>;
     /**
      * Per-call trigger config. Shallow-merged over the action's default
      * `triggerConfig`. `basePayload` is the customer's wire payload (for
@@ -2601,7 +2609,11 @@ export type ChatStartSessionParams = {
      * which the runtime injects automatically).
      */
     triggerConfig?: Partial<SessionTriggerConfig>;
-    /** Pass-through metadata folded into the session row. */
+    /**
+     * Opaque session-level metadata stored on the Session row. Separate from
+     * the per-turn `clientData` above. Use this when you want to attach
+     * server-side metadata that doesn't go through the agent's `clientDataSchema`.
+     */
     metadata?: Record<string, unknown>;
 };
 /**
@@ -2627,29 +2639,33 @@ export type ChatStartSessionResult = {
  * Wrap in a Next.js server action (or any server-side handler) so the
  * customer's secret key never crosses to the browser.
  *
+ * Parameterise the action with `<typeof yourChatAgent>` to type the
+ * `clientData` field against your agent's `clientDataSchema`.
+ *
  * @example
  * ```ts
  * // actions.ts
  * "use server";
  * import { chat } from "@trigger.dev/sdk/ai";
+ * import type { myChat } from "@/trigger/chat";
  *
- * export const startChatSession = chat.createStartSessionAction("my-chat", {
- *   triggerConfig: { machine: "small-1x" },
- * });
+ * export const startChatSession = chat.createStartSessionAction<typeof myChat>(
+ *   "my-chat",
+ *   { triggerConfig: { machine: "small-1x" } }
+ * );
  * ```
  *
- * Then in the browser:
+ * Then in the browser, threading the typed `clientData` from the transport:
  * ```tsx
- * const transport = useTriggerChatTransport({
+ * const transport = useTriggerChatTransport<typeof myChat>({
  *   task: "my-chat",
- *   accessToken: async ({ chatId }) => {
- *     const { publicAccessToken } = await startChatSession({ chatId });
- *     return publicAccessToken;
- *   },
+ *   accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+ *   startSession: ({ chatId, clientData }) =>
+ *     startChatSession({ chatId, clientData }),
  * });
  * ```
  */
-declare function createChatStartSessionAction(taskId: string, options?: CreateChatStartSessionActionOptions): (params: ChatStartSessionParams) => Promise<ChatStartSessionResult>;
+declare function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(taskId: string, options?: CreateChatStartSessionActionOptions): (params: ChatStartSessionParams<TChat>) => Promise<ChatStartSessionResult>;
 export declare const chat: {
     /** Create a chat agent. See {@link chatAgent}. */
     agent: typeof chatAgent;

package/dist/commonjs/v3/ai.js

@@ -114,19 +114,6 @@ async function findLatestSessionInCursor(chatId) {
     }
     return latestCursor;
 }
-/**
- * S3 key suffix for a session's snapshot blob. The webapp's presigned-URL
- * routes prefix this with `packets/{projectRef}/{envSlug}/` server-side, so
- * the final S3 key lands at
- * `packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json`.
- *
- * Stable per session: the friendlyId persists across `chat.requestUpgrade`
- * continuations and idle-suspend restarts.
- * @internal
- */
-function snapshotFilename(sessionId) {
-    return `sessions/${sessionId}/snapshot.json`;
-}
 let readChatSnapshotImpl;
 function __setReadChatSnapshotImplForTests(impl) {
     readChatSnapshotImpl = impl;
@@ -155,7 +142,7 @@ async function readChatSnapshot(sessionId) {
     const apiClient = v3_1.apiClientManager.clientOrThrow();
     let presignedUrl;
     try {
-        const resp = await apiClient.getPayloadUrl(snapshotFilename(sessionId));
+        const resp = await apiClient.getChatSnapshotUrl(sessionId);
         presignedUrl = resp.presignedUrl;
     }
     catch (error) {
@@ -230,7 +217,7 @@ async function writeChatSnapshot(sessionId, snapshot) {
     const apiClient = v3_1.apiClientManager.clientOrThrow();
     let presignedUrl;
     try {
-        const resp = await apiClient.createUploadPayloadUrl(snapshotFilename(sessionId));
+        const resp = await apiClient.createChatSnapshotUploadUrl(sessionId);
         presignedUrl = resp.presignedUrl;
     }
     catch (error) {
@@ -5778,25 +5765,29 @@ function chatLocal(options) {
  * Wrap in a Next.js server action (or any server-side handler) so the
  * customer's secret key never crosses to the browser.
  *
+ * Parameterise the action with `<typeof yourChatAgent>` to type the
+ * `clientData` field against your agent's `clientDataSchema`.
+ *
  * @example
  * ```ts
  * // actions.ts
  * "use server";
  * import { chat } from "@trigger.dev/sdk/ai";
+ * import type { myChat } from "@/trigger/chat";
  *
- * export const startChatSession = chat.createStartSessionAction("my-chat", {
- *   triggerConfig: { machine: "small-1x" },
- * });
+ * export const startChatSession = chat.createStartSessionAction<typeof myChat>(
+ *   "my-chat",
+ *   { triggerConfig: { machine: "small-1x" } }
+ * );
  * ```
  *
- * Then in the browser:
+ * Then in the browser, threading the typed `clientData` from the transport:
  * ```tsx
- * const transport = useTriggerChatTransport({
+ * const transport = useTriggerChatTransport<typeof myChat>({
  *   task: "my-chat",
- *   accessToken: async ({ chatId }) => {
- *     const { publicAccessToken } = await startChatSession({ chatId });
- *     return publicAccessToken;
- *   },
+ *   accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+ *   startSession: ({ chatId, clientData }) =>
+ *     startChatSession({ chatId, clientData }),
  * });
  * ```
  */
@@ -5811,20 +5802,22 @@ function createChatStartSessionAction(taskId, options) {
         // `onPreload` fires, the runtime opens its `.in` subscription, the
         // first user message arrives moments later via `.in/append`.
         //
-        // `metadata` is the customer's transport-level `clientData`,
-        // threaded through so the agent's `clientDataSchema` validates on
-        // the very first turn (the typical schema requires `userId` etc.).
+        // `clientData` is folded into `basePayload.metadata` so the agent's
+        // `clientDataSchema` validates on the very first turn against the same
+        // shape per-turn `metadata` carries via the transport.
         // Auto-tag every chat.agent run with `chat:{chatId}` so the dashboard /
         // run-list filter by chat works without the customer having to wire it
         // up. Mirrors the browser-mediated `TriggerChatTransport.doStart` path.
         const userTags = params.triggerConfig?.tags ?? options?.triggerConfig?.tags ?? [];
         const tags = [`chat:${params.chatId}`, ...userTags].slice(0, 5);
+        const clientDataMetadata = params.clientData !== undefined ? { metadata: params.clientData } : {};
         const triggerConfig = {
             basePayload: {
                 messages: [],
                 trigger: "preload",
                 ...(options?.triggerConfig?.basePayload ?? {}),
                 ...(params.triggerConfig?.basePayload ?? {}),
+                ...clientDataMetadata,
                 chatId: params.chatId,
             },
             ...(options?.triggerConfig?.machine || params.triggerConfig?.machine