@trigger.dev/sdk 0.0.0-chat-prerelease-20260401212829 → 0.0.0-chat-prerelease-20260402124815

package/dist/commonjs/v3/chat-client.d.ts

@@ -1,31 +1,18 @@
 /**
- * Server-side chat client for interacting with Trigger.dev chat agents.
- * Works inside tasks (agent-to-agent), server handlers, and standalone scripts.
+ * Server-side API for chatting with Trigger.dev agents.
  *
  * @example
  * ```ts
- * import { ChatClient } from "@trigger.dev/sdk/chat";
- * import type { prReviewChat } from "./trigger/pr-review";
+ * import { AgentChat } from "@trigger.dev/sdk/chat";
  *
- * const client = new ChatClient<typeof prReviewChat>({
- *   task: "pr-review",
- *   clientData: { userId: "user_123", githubUrl: "https://..." }, // ← typed!
+ * const chat = new AgentChat<typeof myAgent>({
+ *   agent: "my-agent",
+ *   clientData: { userId: "user_123" },
  * });
  *
- * const conv = client.conversation("conv-1");
- * await conv.preload();
- *
- * // Stream with typed chunks
- * const turn = await conv.send("Review PR #1");
- * for await (const chunk of turn) {
- *   if (chunk.type === "text-delta") process.stdout.write(chunk.textDelta);
- * }
- *
- * // Or just get the text
- * const fix = await conv.textResponse("Fix the bug");
- * console.log(conv.messages); // ← typed UIMessage[]
- *
- * await conv.close();
+ * const stream = await chat.sendMessage("Review PR #1");
+ * const text = await stream.text();
+ * await chat.close();
  * ```
  */
 import type { Task } from "@trigger.dev/core/v3";
@@ -35,16 +22,43 @@ import type { ChatTaskWirePayload } from "./ai.js";
 export type InferChatClientData<T> = T extends Task<any, ChatTaskWirePayload<any, infer TMetadata>, any> ? unknown extends TMetadata ? Record<string, unknown> : TMetadata : Record<string, unknown>;
 /** Extract the UIMessage type from a chat agent task. */
 export type InferChatUIMessage<T> = T extends Task<any, ChatTaskWirePayload<infer TUIMessage, any>, any> ? TUIMessage : UIMessage;
+/** Persistable session state — store this to resume across requests. */
 export type ChatSession = {
     runId: string;
-    publicAccessToken: string;
     lastEventId?: string;
 };
-export type ChatClientOptions<TAgent = unknown> = {
-    /** The task ID to trigger. */
-    task: string;
-    /** Default client data included in every request. Typed from the agent's clientDataSchema. */
+export type AgentChatOptions<TAgent = unknown> = {
+    /** The agent task ID to trigger. */
+    agent: string;
+    /**
+     * Conversation ID. Used for tagging runs and correlating messages.
+     * @default crypto.randomUUID()
+     */
+    id?: string;
+    /** Client data included in every request. Typed from the agent's clientDataSchema. */
     clientData?: InferChatClientData<TAgent>;
+    /**
+     * Restore a previous session. Pass the runId (and optionally lastEventId)
+     * from a previous request to resume the same agent run.
+     */
+    session?: ChatSession;
+    /**
+     * Called when a new run is triggered (first message or preload).
+     * Use this to persist the session for later resumption.
+     */
+    onTriggered?: (event: {
+        runId: string;
+        chatId: string;
+    }) => void | Promise<void>;
+    /**
+     * Called when a turn completes (the agent's response stream ends).
+     * Use this to persist the lastEventId for stream resumption.
+     */
+    onTurnComplete?: (event: {
+        runId: string;
+        chatId: string;
+        lastEventId?: string;
+    }) => void | Promise<void>;
     /** Stream key for output stream. @default "chat" */
     streamKey?: string;
     /** SSE timeout in seconds. @default 120 */
@@ -58,173 +72,129 @@ export type ChatClientOptions<TAgent = unknown> = {
         priority?: number;
     };
 };
-type UIMessageLike = {
-    id: string;
-    role: string;
-    parts?: unknown[];
-    [key: string]: unknown;
-};
 /** Parsed tool call from the stream. */
 export type ChatToolCall = {
     toolName: string;
     toolCallId: string;
-    args: unknown;
+    input: unknown;
 };
 /** Parsed tool result from the stream. */
 export type ChatToolResult = {
-    toolName: string;
     toolCallId: string;
-    result: unknown;
+    output: unknown;
 };
-/** The accumulated result after a stream completes. */
+/** Accumulated result after a stream completes. */
 export type ChatStreamResult = {
     text: string;
     toolCalls: ChatToolCall[];
     toolResults: ChatToolResult[];
 };
 /**
- * Typed wrapper around a single turn's response stream.
- * Yields `UIMessageChunk` from the AI SDK.
+ * A single turn's response stream from an agent.
  *
- * @example
- * ```ts
- * const stream = new ChatStream(rawStream);
- *
- * // Iterate with typed UIMessageChunk
- * for await (const chunk of stream) {
- *   if (chunk.type === "text-delta") process.stdout.write(chunk.textDelta);
- *   if (chunk.type === "tool-call") console.log(chunk.toolName, chunk.args);
- * }
- *
- * // Or consume and get the structured result
- * const { text, toolCalls, toolResults } = await stream.result();
- * ```
+ * Pick one consumption mode:
+ * - `for await (const chunk of stream)` — typed UIMessageChunk iteration
+ * - `await stream.result()` — accumulated `{ text, toolCalls, toolResults }`
+ * - `await stream.text()` — just the text
+ * - `yield* stream.messages()` — sub-agent pattern (yields UIMessage snapshots)
  */
 export declare class ChatStream {
-    private readonly stream;
-    private teed;
+    private readonly _stream;
     private resultPromise;
     constructor(stream: ReadableStream<UIMessageChunk>);
-    /** Async iterate over typed UIMessageChunk values. */
+    /** The raw ReadableStream for direct use with AI SDK utilities. */
+    get stream(): ReadableStream<UIMessageChunk>;
     [Symbol.asyncIterator](): AsyncIterableIterator<UIMessageChunk>;
     /**
-     * Consume the entire stream and return the accumulated result.
-     * Can only be called once (consumes the stream).
+     * Yields accumulated UIMessage snapshots for the sub-agent tool pattern.
+     *
+     * @example
+     * ```ts
+     * const stream = await chat.sendMessage("Research this topic");
+     * yield* stream.messages();
+     * ```
      */
+    messages(): AsyncGenerator<UIMessage, void, unknown>;
+    /** Consume the stream and return the accumulated result. */
     result(): Promise<ChatStreamResult>;
-    /** Shorthand: consume the stream and return just the text. */
+    /** Consume the stream and return just the text. */
     text(): Promise<string>;
     private consumeStream;
 }
 /**
- * High-level multi-turn conversation interface.
- * Manages the turn lifecycle, accumulates messages, and returns typed streams.
+ * A chat conversation with a Trigger.dev agent.
  *
  * @example
  * ```ts
- * const conv = client.conversation("chat-1", { clientData: { userId: "u1" } });
- * await conv.preload();
- *
- * const turn = await conv.send("Review PR #1");
- * const { text, toolCalls } = await turn.result();
+ * // Simple usage
+ * const chat = new AgentChat<typeof myAgent>({ agent: "my-agent" });
+ * const text = await (await chat.sendMessage("Hello")).text();
+ * await chat.close();
  *
- * const followUp = await conv.textResponse("Fix the bug");
- *
- * console.log(conv.messages); // Full conversation as typed UIMessage[]
- * await conv.close();
- * ```
- */
-export declare class ChatConversation<TAgent = unknown> {
-    private readonly client;
-    private readonly chatId;
-    private readonly clientData?;
-    private _messages;
-    constructor(client: ChatClient<TAgent>, chatId: string, clientData?: InferChatClientData<TAgent> | undefined);
-    /** The accumulated conversation messages (user + assistant). */
-    get messages(): readonly InferChatUIMessage<TAgent>[];
-    /** Preload the agent — initialize before the first message. */
-    preload(options?: {
-        idleTimeoutInSeconds?: number;
-    }): Promise<ChatSession>;
-    /**
-     * Send a text message and return a typed ChatStream for the response.
-     * The user message and assistant response are accumulated in `messages`.
-     */
-    send(text: string, options?: {
-        abortSignal?: AbortSignal;
-    }): Promise<ChatStream>;
-    /** Send a text message and return the full text response. */
-    textResponse(text: string): Promise<string>;
-    /** Send a text message and return the full structured result. */
-    fullResponse(text: string): Promise<ChatStreamResult>;
-    /** Send a steering/pending message during an active stream. */
-    steer(text: string): Promise<boolean>;
-    /** Stop the current generation. */
-    stop(): Promise<void>;
-    /** Close the conversation — agent exits gracefully. */
-    close(): Promise<boolean>;
-    /** Get the current session. */
-    get session(): ChatSession | undefined;
-    private accumulateResponse;
-}
-/**
- * Server-side chat client for interacting with Trigger.dev chat agents.
- *
- * Pass the agent type for full type inference:
- * ```ts
- * const client = new ChatClient<typeof myAgent>({ task: "my-agent" });
+ * // Stateless request handler — persist and restore session
+ * const chat = new AgentChat<typeof myAgent>({
+ *   agent: "my-agent",
+ *   id: chatId,
+ *   session: { runId: savedRunId, lastEventId: savedLastEventId },
+ *   onTriggered: ({ runId }) => db.save(chatId, { runId }),
+ *   onTurnComplete: ({ lastEventId }) => db.update(chatId, { lastEventId }),
+ * });
  * ```
  */
-export declare class ChatClient<TAgent = unknown> {
+export declare class AgentChat<TAgent = unknown> {
     private readonly taskId;
+    private readonly chatId;
     private readonly streamKey;
     private readonly streamTimeoutSeconds;
-    private readonly defaultClientData;
+    private readonly clientData;
     private readonly triggerOptions;
-    private sessions;
-    constructor(options: ChatClientOptions<TAgent>);
-    /**
-     * Create a conversation handle for multi-turn interaction.
-     * Accumulates messages and provides typed stream access.
-     */
-    conversation(chatId: string, options?: {
-        clientData?: InferChatClientData<TAgent>;
-    }): ChatConversation<TAgent>;
+    private readonly onTriggered;
+    private readonly onTurnComplete;
+    private session;
+    constructor(options: AgentChatOptions<TAgent>);
+    /** The conversation ID. */
+    get id(): string;
+    /** The current run session, if active. */
+    get run(): ChatSession | undefined;
     /**
-     * Eagerly trigger a run before the first message is sent.
-     * No-op if a session already exists for this chatId.
+     * Preload the agent — start the run before the first message.
+     * The agent's `onPreload` hook fires immediately.
+     * No-op if already has a session.
      */
-    preload(chatId: string, options?: {
-        clientData?: InferChatClientData<TAgent>;
+    preload(options?: {
         idleTimeoutInSeconds?: number;
     }): Promise<ChatSession>;
     /**
-     * Send messages and subscribe to the response stream.
-     * Returns a raw `ReadableStream<UIMessageChunk>`.
-     * For higher-level access, use `conversation()`.
+     * Send a text message and get the response stream.
+     *
+     * @example
+     * ```ts
+     * const stream = await chat.sendMessage("Review PR #1");
+     * const text = await stream.text();
+     * ```
      */
-    sendMessages(chatId: string, messages: UIMessageLike[], options?: {
+    sendMessage(text: string, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<ChatStream>;
+    /** Send raw UIMessage-like objects. Use `sendMessage()` for simple text. */
+    sendRaw(messages: Array<{
+        id: string;
+        role: string;
+        parts?: unknown[];
+        [key: string]: unknown;
+    }>, options?: {
         trigger?: "submit-message" | "regenerate-message";
-        clientData?: InferChatClientData<TAgent>;
         abortSignal?: AbortSignal;
     }): Promise<ReadableStream<UIMessageChunk>>;
-    /**
-     * Send a steering/pending message without starting a new response stream.
-     * @returns `true` if sent, `false` if no active session.
-     */
-    sendPendingMessage(chatId: string, message: UIMessageLike, clientData?: Record<string, unknown>): Promise<boolean>;
-    /** Send a stop signal to the running agent. */
-    stop(chatId: string): Promise<void>;
-    /** Signal the agent to stop waiting and exit gracefully. */
-    close(chatId: string): Promise<boolean>;
-    /** Reconnect to an existing session's response stream. */
-    reconnect(chatId: string, abortSignal?: AbortSignal): Promise<ReadableStream<UIMessageChunk> | null>;
-    getSession(chatId: string): ChatSession | undefined;
-    setSession(chatId: string, session: ChatSession): void;
-    deleteSession(chatId: string): void;
-    private mergeClientData;
-    private createStreamApiClient;
+    /** Send a steering message during an active stream. */
+    steer(text: string): Promise<boolean>;
+    /** Stop the current generation (agent stays alive for next turn). */
+    stop(): Promise<void>;
+    /** Close the conversation — agent exits its loop gracefully. */
+    close(): Promise<boolean>;
+    /** Reconnect to the response stream (e.g. after a disconnect). */
+    reconnect(abortSignal?: AbortSignal): Promise<ReadableStream<UIMessageChunk> | null>;
+    private createApiClient;
     private triggerNewRun;
     private subscribeToStream;
 }
-export {};