@trigger.dev/sdk 0.0.0-prerelease-20260908122921 → 0.0.0-prerelease-20260909071038

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

@@ -1,5 +1,6 @@
 import { type AnyTask, type Task, type ApiClientConfiguration, type inferSchemaIn, type inferSchemaOut, type MachinePresetName, type RealtimeDefinedInputStream, type RealtimeDefinedStream, type TaskIdentifier, type TaskOptions, type TaskRunContext, type TaskSchema, type TaskWithSchema, type AnySessionChannel, type SessionChannelName } from "@trigger.dev/core/v3";
 import type { streamText as aiStreamTextSignature, FinishReason, LanguageModelUsage, ModelMessage, SystemModelMessage, ProviderMetadata, Tool, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
+import { type TranscriptLoadResult, type TranscriptStorage } from "./transcriptStorage.js";
 import { type ChatInputChunk, type ChatTaskWirePayload, type InferChatClientData, type InferChatUIMessage, type InferChatUIMessageFromTools, PENDING_MESSAGE_INJECTED_TYPE, upsertIncomingMessage } from "./ai-shared.js";
 import { locals } from "./locals.js";
 import type { ResolvedPrompt } from "./prompt.js";
@@ -33,8 +34,8 @@ type ChatTurnContext<TClientData = unknown> = {
     continuation: boolean;
     clientData?: TClientData;
 };
-export declare function __setReadChatSnapshotImplForTests(impl: ReadChatSnapshotImpl | undefined): void;
-export declare function __setWriteChatSnapshotImplForTests(impl: WriteChatSnapshotImpl | undefined): void;
+export { __readChatSnapshotProductionPathForTests, __setReadChatSnapshotImplForTests, __setWriteChatSnapshotImplForTests, __writeChatSnapshotProductionPathForTests, } from "./chatSnapshotIo.js";
+export { defaultStorage, memoryTranscriptStorage, reduceTranscriptChanges, snapshotTranscriptStorage, type LoadContextEvent, type MemoryTranscriptStorage, type TranscriptChange, type TranscriptChangeReason, type TranscriptChangeset, type TranscriptCursors, type TranscriptLoadOptions, type TranscriptLoadResult, type TranscriptScope, type TranscriptState, type TranscriptStorage, type TranscriptStorageContext, } from "./transcriptStorage.js";
 type ReplaySessionOutTailImpl = <TUIMessage extends UIMessage>(sessionId: string, options?: {
     lastEventId?: string;
 }) => Promise<ReplaySessionOutTailResult<TUIMessage>>;
@@ -1162,8 +1163,9 @@ export type RecoveryPendingToolCall = {
  * `chat.endRun()` with no buffered user messages, fresh chat, OOM retry
  * after a successful turn-complete with no in-flight tail).
  *
- * Does NOT fire when `hydrateMessages` is registered (the customer owns
- * persistence; recovery decisions live in their own DB query).
+ * Fires regardless of who owns the model's context. With `hydrateMessages`
+ * or a storage `loadContext`, the recovered tail reaches that hook in
+ * `previousMessages` on the next turn.
  */
 export type RecoveryBootEvent<TUIM extends UIMessage = UIMessage> = {
     /** Task run context — same as `task({ run })` second-argument `ctx`. */
@@ -1232,8 +1234,9 @@ export type RecoveryBootResult<TUIM extends UIMessage = UIMessage> = {
      * context, mutate its tool parts to inject synthesized results,
      * collapse history, etc.
      *
-     * Ignored when `hydrateMessages` is registered (the hydrate hook
-     * runs per-turn and overwrites the chain).
+     * With `hydrateMessages` or a storage `loadContext`, this chain is what
+     * the hook receives as `previousMessages` on the next turn; the hook's
+     * return value is the chain the model sees.
      */
     chain?: TUIM[];
     /**
@@ -1768,9 +1771,9 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * continuation after `chat.endRun()` with no buffered user, a fresh
      * chat, or an OOM retry on top of a complete snapshot.
      *
-     * Does NOT fire when `hydrateMessages` is registered — that hook owns
-     * the per-turn chain and overlapping recovery decisions belong in the
-     * customer's DB.
+     * Fires regardless of who owns the model's context; a `hydrateMessages`
+     * hook or a storage `loadContext` receives the recovered tail in
+     * `previousMessages` on the next turn.
      *
      * Defaults (returned when the hook is omitted or returns no field):
      *   - With two or more in-flight users, the partial and the user it
@@ -1900,6 +1903,32 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * ```
      */
     hydrateMessages?: (event: HydrateMessagesEvent<inferSchemaOut<TClientDataSchema>, TUIMessage>) => TUIMessage[] | Promise<TUIMessage[]>;
+    /**
+     * Where the conversation is persisted. The runtime calls `save` after
+     * every turn, failed turn and history-changing action with the changes
+     * since the last save, and `load` once when a new run boots to continue
+     * the conversation.
+     *
+     * Defaults to `defaultStorage`, the platform's snapshot in object storage
+     * that the Sessions dashboard renders. Bring your own to write each change
+     * to your database; `memoryTranscriptStorage()` is the reference
+     * implementation and `runTranscriptStorageTests` from
+     * `@trigger.dev/sdk/ai/test` checks yours against the contract.
+     *
+     * A storage with `loadContext` also owns the model's context on every
+     * turn, which is what `hydrateMessages` did. The two cannot be combined.
+     *
+     * @example
+     * ```ts
+     * chat.agent({
+     *   id: "my-chat",
+     *   storage: myPostgresTranscriptStorage,
+     *   run: async ({ messages, signal, streamText }) =>
+     *     streamText({ model, messages, abortSignal: signal }),
+     * });
+     * ```
+     */
+    storage?: TranscriptStorage<inferSchemaOut<TClientDataSchema>>;
     /**
      * Called at the start of every turn, after message accumulation and `onChatStart` (turn 0),
      * but before the `run` function executes.
@@ -3274,6 +3303,42 @@ export type ChatStartSessionResult = {
  * ```
  */
 declare function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(taskId: string, options?: CreateChatStartSessionActionOptions): (params: ChatStartSessionParams<TChat>) => Promise<ChatStartSessionResult>;
+export type CreateChatLoadTranscriptActionOptions = {
+    /**
+     * Scope the action to a specific API client configuration (secret key,
+     * base URL) instead of the process-wide one. The default storage reads
+     * through this client.
+     */
+    apiClient?: ApiClientConfiguration;
+    /** Page size when the caller passes none. */
+    limit?: number;
+};
+export type ChatLoadTranscriptParams<TClientData = unknown> = {
+    chatId: string;
+    clientData?: TClientData;
+    limit?: number;
+    before?: string;
+};
+/**
+ * Creates a server-side helper that reads a conversation from a transcript
+ * storage, for rendering history before the chat connects. Works the same
+ * for every storage, the platform default included, so the browser never
+ * reads a store directly and the secret key stays on the server.
+ *
+ * Wrap it in a Next.js server action (or any server-side handler), scope it
+ * to the authenticated user through `clientData`, and pass the result to
+ * `useLoadTranscript` in the browser.
+ *
+ * @example
+ * ```ts
+ * // actions.ts
+ * "use server";
+ * import { chat, defaultStorage } from "@trigger.dev/sdk/ai";
+ *
+ * export const loadTranscript = chat.createLoadTranscriptAction(defaultStorage, { limit: 50 });
+ * ```
+ */
+declare function createChatLoadTranscriptAction<TClientData = unknown>(storage: TranscriptStorage<TClientData>, options?: CreateChatLoadTranscriptActionOptions): (params: ChatLoadTranscriptParams<TClientData>) => Promise<TranscriptLoadResult>;
 export declare const chat: {
     /** Create a chat agent. See {@link chatAgent}. */
     agent: typeof chatAgent;
@@ -3285,6 +3350,8 @@ export declare const chat: {
     withClientData: typeof withClientData;
     /** Create a server-side helper for starting (or resuming) a Session for a chatId. See {@link createChatStartSessionAction}. */
     createStartSessionAction: typeof createChatStartSessionAction;
+    /** Returns a server-side helper that reads a conversation from a transcript storage. */
+    createLoadTranscriptAction: typeof createChatLoadTranscriptAction;
     /** Pipe a stream to the chat transport. See {@link pipeChat}. */
     pipe: typeof pipeChat;
     /** Return from `onAction` to run a turn on the edited history. See {@link chatTurn}. */