@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

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

@@ -1,5 +1,5 @@
 import { AnyTask, type MachinePresetName, type RealtimeDefinedInputStream, type RealtimeDefinedStream, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskRunContext, type TaskWithSchema } from "@trigger.dev/core/v3";
-import type { FinishReason, LanguageModelUsage, ModelMessage, Tool, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
+import type { FinishReason, LanguageModelUsage, ModelMessage, ProviderMetadata, Tool, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
 type ToolCallOptions = {
     toolCallId: string;
     messages?: ModelMessage[];
@@ -259,6 +259,57 @@ export type ChatTaskRunPayload<TClientData = unknown, TTools extends ToolSet = T
      */
     tools: TTools;
 };
+/**
+ * Signal received by a `handover-prepare` agent run waiting on
+ * `session.in`. Either the customer's first-turn `streamText` finished
+ * with pending tool calls (`"handover"` — agent picks up from tool
+ * execution), or it finished pure-text (`"handover-skip"` — agent
+ * exits cleanly without making an LLM call).
+ *
+ * Returned by `chat.waitForHandover()` for custom-agent loops.
+ */
+export type HandoverSignal = {
+    kind: "handover";
+    partialAssistantMessage: ModelMessage[];
+    messageId?: string;
+    /**
+     * Whether the customer's step 1 is the final response. When
+     * true, the agent's turn loop runs hooks but skips the LLM
+     * call (the partial IS the response). When false, the agent
+     * runs `streamText` which executes pending tool-calls via the
+     * approval round and continues from step 2.
+     */
+    isFinal: boolean;
+} | {
+    kind: "handover-skip";
+};
+/**
+ * Wait for a `chat.headStart` handover signal inside a custom-agent loop or
+ * `chat.createSession`. Returns:
+ * - `null` — this run is not a `handover-prepare` boot, or the wait idled out /
+ *   the warm handler crashed before signaling. Treat as "no handover".
+ * - `{ kind: "handover-skip" }` — the warm handler aborted; exit without a turn.
+ * - `{ kind: "handover", partialAssistantMessage, messageId?, isFinal }` — splice
+ *   the partial (`chat.MessageAccumulator.applyHandover`) and, when `isFinal` is
+ *   false, fall through to `streamText` to run the handed-over tool round.
+ *
+ * For the common case prefer `accumulator.consumeHandover()`, which also seeds
+ * `payload.headStartMessages` and applies the partial for you.
+ *
+ * Must be called at turn 0 before any `chat.messages.waitWithIdleTimeout` —
+ * that facade consumes and discards non-message chunks, which would swallow the
+ * handover signal.
+ */
+declare function waitForHandover(options: {
+    /** The run's wire payload (only `trigger` / `idleTimeoutInSeconds` are read). */
+    payload: {
+        trigger?: string;
+        idleTimeoutInSeconds?: number;
+    };
+    idleTimeoutInSeconds?: number;
+    timeout?: string;
+    spanName?: string;
+}): Promise<HandoverSignal | null>;
 /** Convenience re-export of the AI SDK's `LanguageModelUsage` type. */
 export type ChatTurnUsage = LanguageModelUsage;
 /**
@@ -718,11 +769,29 @@ export type ChatPromptValue = ResolvedPrompt | {
         };
     };
 };
+/**
+ * Options for `chat.prompt.set()`.
+ */
+export type SetChatPromptOptions = {
+    /**
+     * Provider options attached to the system prompt so a provider can cache it.
+     * The most common use is an Anthropic prompt-cache breakpoint on the (large,
+     * stable) system block — see the prompt-caching guide. Carried through to
+     * `chat.toStreamTextOptions()` automatically; a `systemProviderOptions` /
+     * `cacheControl` passed there overrides this.
+     *
+     * @example
+     * chat.prompt.set(SYSTEM_PROMPT, {
+     *   providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
+     * });
+     */
+    providerOptions?: ProviderMetadata;
+};
 /**
  * Store a resolved prompt (or plain string) for the current run.
  * Call from any hook (`onPreload`, `onChatStart`, `onTurnStart`) or `run()`.
  */
-declare function setChatPrompt(resolved: ResolvedPrompt | string): void;
+declare function setChatPrompt(resolved: ResolvedPrompt | string, options?: SetChatPromptOptions): void;
 /**
  * Read the stored prompt. Throws if `chat.prompt.set()` has not been called.
  */
@@ -770,6 +839,40 @@ export type ToStreamTextOptionsOptions = {
      * your tools here.
      */
     tools?: Record<string, Tool>;
+    /**
+     * Provider options attached to the system prompt so a provider can cache it.
+     * When set (or when {@link cacheControl} or `chat.prompt.set`'s
+     * `providerOptions` is set), `system` is returned as a structured
+     * `SystemModelMessage` carrying these options instead of a plain string —
+     * letting providers like Anthropic apply prompt caching to the (large,
+     * stable) system block, which is the single highest-value cache target.
+     *
+     * Overrides any `providerOptions` set on `chat.prompt.set()`.
+     *
+     * @example
+     * chat.toStreamTextOptions({
+     *   systemProviderOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
+     * });
+     */
+    systemProviderOptions?: ProviderMetadata;
+    /**
+     * Anthropic-only convenience for {@link systemProviderOptions}: caches the
+     * system prompt with the given cache breakpoint. Equivalent to
+     * `systemProviderOptions: { anthropic: { cacheControl } }`. For other
+     * providers (e.g. Amazon Bedrock's `cachePoint`), use `systemProviderOptions`.
+     *
+     * @example
+     * chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } });
+     */
+    cacheControl?: SystemCacheControl;
+};
+/**
+ * Anthropic prompt-cache breakpoint shape (`providerOptions.anthropic.cacheControl`).
+ * `ttl` defaults to the 5-minute cache; `"1h"` selects the 1-hour cache.
+ */
+export type SystemCacheControl = {
+    type: "ephemeral";
+    ttl?: "5m" | "1h";
 };
 /**
  * Returns an options object ready to spread into `streamText()`.
@@ -1263,6 +1366,13 @@ export type TurnCompleteEvent<TClientData = unknown, TUIM extends UIMessage = UI
      * manual `pipeChat()` or an aborted stream).
      */
     finishReason?: FinishReason;
+    /**
+     * Set when the turn failed (the `run()` body or a lifecycle hook threw).
+     * On an errored turn `responseMessage` is undefined or partial and
+     * `finishReason` is `"error"`. Use this to mark the turn failed in your
+     * persistence. Undefined on a successful turn.
+     */
+    error?: unknown;
 };
 /**
  * Event passed to the `onBeforeTurnComplete` callback.
@@ -2373,6 +2483,7 @@ declare function chatWriteTurnComplete(options?: {
 declare function pipeChatAndCapture(source: UIMessageStreamable, options?: {
     signal?: AbortSignal;
     spanName?: string;
+    originalMessages?: UIMessage[];
 }): Promise<UIMessage | undefined>;
 /**
  * Accumulates conversation messages across turns.
@@ -2416,6 +2527,42 @@ declare class ChatMessageAccumulator {
      * Converts UIMessages to ModelMessages internally.
      */
     setMessages(uiMessages: UIMessage[]): Promise<void>;
+    /**
+     * Splice a `chat.headStart` handover partial into the accumulator (the warm
+     * step-1 response). Dedups by `messageId` so a seeded/hydrated history that
+     * already carries the partial isn't doubled. Seed any prior history first
+     * (e.g. `setMessages(payload.headStartMessages)`). Low-level — see
+     * `consumeHandover` for the wait+seed+apply convenience.
+     */
+    applyHandover(signal: {
+        partialAssistantMessage: ModelMessage[];
+        messageId?: string;
+    }): void;
+    /**
+     * One-call `chat.headStart` handover for a custom-agent loop: waits for the
+     * handover signal, seeds prior history from `payload.headStartMessages`,
+     * applies the warm step-1 partial, and reports what to do next.
+     *
+     * Returns `{ isFinal, skipped }`:
+     * - `skipped: true` — not a `handover-prepare` run, the wait idled out, or the
+     *   warm handler aborted. Exit the run without a turn.
+     * - `isFinal: true` — step 1 IS the response (pure text). Write turn-complete
+     *   and continue; do not call `streamText`.
+     * - `isFinal: false` — fall through to `streamText`, which runs the pending
+     *   tool round handed over from step 1.
+     */
+    consumeHandover(options: {
+        payload: {
+            trigger?: string;
+            idleTimeoutInSeconds?: number;
+            headStartMessages?: UIMessage[];
+        };
+        idleTimeoutInSeconds?: number;
+        timeout?: string;
+    }): Promise<{
+        isFinal: boolean;
+        skipped: boolean;
+    }>;
     addResponse(response: UIMessage): Promise<void>;
     /**
      * Queue a message for injection via `prepareStep`. Call from a
@@ -2491,6 +2638,15 @@ export type ChatTurn = {
     previousTurnUsage?: LanguageModelUsage;
     /** Cumulative token usage across all completed turns so far. */
     totalUsage: LanguageModelUsage;
+    /**
+     * Set on the first turn of a `chat.headStart` handover; `null` otherwise.
+     * When `isFinal` is true the warm step-1 IS the response — call
+     * `turn.complete()` with no argument (don't call `streamText`). When false,
+     * call `streamText` as usual; it runs the handed-over tool round.
+     */
+    handover: {
+        isFinal: boolean;
+    } | null;
     /**
      * Replace accumulated messages (for compaction). Takes UIMessages and
      * converts to ModelMessages internally. After calling this, `turn.messages`
@@ -2500,8 +2656,11 @@ export type ChatTurn = {
     /**
      * Easy path: pipe stream, capture response, accumulate it,
      * clean up aborted parts if stopped, and write turn-complete chunk.
+     *
+     * Call with no argument on a head-start final turn (`turn.handover?.isFinal`)
+     * — the warm step-1 partial is already the response, so there's nothing to pipe.
      */
-    complete(source: UIMessageStreamable): Promise<UIMessage | undefined>;
+    complete(source?: UIMessageStreamable): Promise<UIMessage | undefined>;
     /**
      * Manual path: just write turn-complete chunk.
      * Use when you've already piped and accumulated manually.
@@ -2531,14 +2690,18 @@ export type ChatTurn = {
  * signaling, and idle/suspend between turns. You control: initialization,
  * model/tool selection, persistence, and any custom per-turn logic.
  *
+ * Call from inside a `chat.customAgent()` run — the wrapper binds the
+ * backing Session that the iterator's stop signal and message channels
+ * resolve to. (A plain `task()` does not bind it, so `createSession`
+ * would throw "session handle is not initialized".)
+ *
  * @example
  * ```ts
- * import { task } from "@trigger.dev/sdk";
  * import { chat, type ChatTaskWirePayload } from "@trigger.dev/sdk/ai";
  * import { streamText } from "ai";
  * import { openai } from "@ai-sdk/openai";
  *
- * export const myChat = task({
+ * export const myChat = chat.customAgent({
  *   id: "my-chat",
  *   run: async (payload: ChatTaskWirePayload, { signal }) => {
  *     const session = chat.createSession(payload, { signal });
@@ -2814,10 +2977,20 @@ export declare const chat: {
     MessageAccumulator: typeof ChatMessageAccumulator;
     /** Create a chat session (async iterator). See {@link createChatSession}. */
     createSession: typeof createChatSession;
+    /**
+     * Wait for a `chat.headStart` handover signal inside a `chat.customAgent`
+     * loop (turn 0). See {@link waitForHandover}. For most loops prefer the
+     * `chat.MessageAccumulator.consumeHandover()` convenience, which also seeds
+     * `payload.headStartMessages` and applies the partial.
+     */
+    waitForHandover: typeof waitForHandover;
     /**
      * Store and retrieve a resolved prompt for the current run.
      *
      * - `chat.prompt.set(resolved)` — store a `ResolvedPrompt` or plain string
+     * - `chat.prompt.set(resolved, { providerOptions })` — also attach provider
+     *   options to the system block so a provider can cache it (e.g. Anthropic
+     *   prompt caching). See the prompt-caching guide.
      * - `chat.prompt()` — read the stored prompt (throws if not set)
      */
     prompt: typeof getChatPrompt & {