@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/dist/esm/v3/uiMessageChunks.js

@@ -0,0 +1,116 @@
+import { createUIMessageStream } from "../imports/ai-runtime.js";
+/** How long a reduction runs before handing the event loop back to timers and heartbeats. */
+const YIELD_EVERY_MS = 10;
+/**
+ * Reduce recorded `UIMessageChunk`s to the final `UIMessage` they build, with
+ * the AI SDK's own reducer.
+ *
+ * `readUIMessageStream` emits a `structuredClone` of the whole message after
+ * almost every chunk, so draining it just to keep the last snapshot is
+ * quadratic in the length of the message. A long unfinished turn could block
+ * the event loop for minutes. `createUIMessageStream`'s `onFinish` runs the
+ * same reducer over one mutable state and only hands back the end result,
+ * which is cloned once so it shares nothing with the recorded chunks.
+ *
+ * Chunks are written one at a time, each after the previous one comes out of
+ * the stream. Dequeuing from a long web stream queue is linear in its length
+ * on Node, so writing a whole turn up front would make the reduction quadratic
+ * even without any cloning. This relies on the AI SDK passing every chunk
+ * through, which its UI message streams do. Chunks are also copied before they
+ * are written, because the AI SDK writes a missing `messageId` onto `start`
+ * chunks and stores data chunks as message parts.
+ *
+ * Matches the last snapshot `readUIMessageStream` would emit, except that
+ * `step-start` parts pushed after the last snapshot are kept (they are part of
+ * the reducer's final state, which is also what `onFinish` returns on the live
+ * path). Returns `undefined` when no chunk would have emitted a snapshot.
+ *
+ * A malformed chunk (e.g. a delta for a part that never started) errors the
+ * stream, while `readUIMessageStream` keeps everything reduced before it.
+ * Because only one chunk is in flight, the failing chunk is known exactly, and
+ * the chunks before it are reduced again on the same linear path.
+ *
+ * @param options.message - The assistant message the chunks continue. Not mutated.
+ * @internal
+ */
+export async function reduceUIMessageChunks(chunks, options) {
+    let end = chunks.length;
+    while (emitsAnySnapshot(chunks, end)) {
+        const result = await reducePrefix(chunks, end, options?.message);
+        if ("message" in result)
+            return result.message && structuredClone(result.message);
+        if (result.failedAt >= end)
+            return undefined;
+        end = result.failedAt;
+    }
+    return undefined;
+}
+async function reducePrefix(chunks, end, original) {
+    let message;
+    let read = 0;
+    let done = false;
+    let resume;
+    const stream = createUIMessageStream({
+        generateId: () => "",
+        ...(original ? { originalMessages: [original] } : {}),
+        async execute({ writer }) {
+            for (let written = 0; written < end && !done; written++) {
+                writer.write({ ...chunks[written] });
+                if (read <= written) {
+                    await new Promise((resolve) => {
+                        resume = resolve;
+                    });
+                }
+            }
+        },
+        onFinish({ responseMessage }) {
+            message = responseMessage;
+        },
+    });
+    const reader = stream.getReader();
+    let sliceStart = performance.now();
+    try {
+        while (!(await reader.read()).done) {
+            read++;
+            resume?.();
+            resume = undefined;
+            if (performance.now() - sliceStart >= YIELD_EVERY_MS) {
+                await new Promise((resolve) => setImmediate(resolve));
+                sliceStart = performance.now();
+            }
+        }
+    }
+    catch {
+        return { failedAt: read };
+    }
+    finally {
+        done = true;
+        resume?.();
+        reader.releaseLock();
+    }
+    return { message };
+}
+function emitsAnySnapshot(chunks, end) {
+    for (let index = 0; index < end; index++)
+        if (emitsSnapshot(chunks[index]))
+            return true;
+    return false;
+}
+/** Whether `readUIMessageStream` emits a snapshot after this chunk. */
+function emitsSnapshot(chunk) {
+    switch (chunk.type) {
+        case "start":
+            return chunk.messageId != null || chunk.messageMetadata != null;
+        case "finish":
+        case "message-metadata":
+            return chunk.messageMetadata != null;
+        case "start-step":
+        case "finish-step":
+        case "error":
+        case "abort":
+            return false;
+        default:
+            return !(chunk.type.startsWith("data-") && "transient" in chunk && chunk.transient === true);
+    }
+}
+//# sourceMappingURL=uiMessageChunks.js.map

package/dist/esm/v3/uiMessageChunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiMessageChunks.js","sourceRoot":"","sources":["../../../src/v3/uiMessageChunks.ts"],"names":[],"mappings":"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"}

package/dist/esm/v3/usage.js

@@ -38,6 +38,7 @@ export const usage = {
      */
     getCurrent: () => {
         const sample = usageApi.sample();
+        const initialState = usageApi.getInitialState();
         const machine = taskContext.ctx?.machine;
         const run = taskContext.ctx?.run;
         if (!sample) {
@@ -48,12 +49,12 @@ export const usage = {
                         durationMs: 0,
                     },
                     total: {
-                        costInCents: run?.costInCents ?? 0,
-                        durationMs: run?.durationMs ?? 0,
+                        costInCents: initialState.costInCents,
+                        durationMs: initialState.cpuTime,
                     },
                 },
                 baseCostInCents: run?.baseCostInCents ?? 0,
-                totalCostInCents: (run?.costInCents ?? 0) + (run?.baseCostInCents ?? 0),
+                totalCostInCents: initialState.costInCents + (run?.baseCostInCents ?? 0),
             };
         }
         const currentCostInCents = machine?.centsPerMs ? sample.cpuTime * machine.centsPerMs : 0;
@@ -64,12 +65,12 @@ export const usage = {
                     durationMs: sample.cpuTime,
                 },
                 total: {
-                    costInCents: (run?.costInCents ?? 0) + currentCostInCents,
-                    durationMs: (run?.durationMs ?? 0) + sample.cpuTime,
+                    costInCents: currentCostInCents + initialState.costInCents,
+                    durationMs: sample.cpuTime + initialState.cpuTime,
                 },
             },
             baseCostInCents: run?.baseCostInCents ?? 0,
-            totalCostInCents: (run?.costInCents ?? 0) + currentCostInCents + (run?.baseCostInCents ?? 0),
+            totalCostInCents: currentCostInCents + (run?.baseCostInCents ?? 0) + initialState.costInCents,
         };
     },
     /**

package/dist/esm/v3/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/v3/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAiBtE,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,UAAU,EAAE,GAAiB,EAAE;QAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;QACzC,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC;QAEjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,OAAO,EAAE;oBACP,OAAO,EAAE;wBACP,WAAW,EAAE,CAAC;wBACd,UAAU,EAAE,CAAC;qBACd;oBACD,KAAK,EAAE;wBACL,WAAW,EAAE,GAAG,EAAE,WAAW,IAAI,CAAC;wBAClC,UAAU,EAAE,GAAG,EAAE,UAAU,IAAI,CAAC;qBACjC;iBACF;gBACD,eAAe,EAAE,GAAG,EAAE,eAAe,IAAI,CAAC;gBAC1C,gBAAgB,EAAE,CAAC,GAAG,EAAE,WAAW,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,eAAe,IAAI,CAAC,CAAC;aACxE,CAAC;QACJ,CAAC;QAED,MAAM,kBAAkB,GAAG,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAEzF,OAAO;YACL,OAAO,EAAE;gBACP,OAAO,EAAE;oBACP,WAAW,EAAE,kBAAkB;oBAC/B,UAAU,EAAE,MAAM,CAAC,OAAO;iBAC3B;gBACD,KAAK,EAAE;oBACL,WAAW,EAAE,CAAC,GAAG,EAAE,WAAW,IAAI,CAAC,CAAC,GAAG,kBAAkB;oBACzD,UAAU,EAAE,CAAC,GAAG,EAAE,UAAU,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO;iBACpD;aACF;YACD,eAAe,EAAE,GAAG,EAAE,eAAe,IAAI,CAAC;YAC1C,gBAAgB,EAAE,CAAC,GAAG,EAAE,WAAW,IAAI,CAAC,CAAC,GAAG,kBAAkB,GAAG,CAAC,GAAG,EAAE,eAAe,IAAI,CAAC,CAAC;SAC7F,CAAC;IACJ,CAAC;IACD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,EAAE,KAAK,EAAK,EAAoB,EAAiD,EAAE;QACxF,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;QAErC,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAE1B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;QAEzC,MAAM,WAAW,GAAG,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAElF,OAAO;YACL,MAAM;YACN,OAAO,EAAE;gBACP,WAAW;gBACX,UAAU,EAAE,MAAM,CAAC,OAAO;aAC3B;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/v3/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAiBtE,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,UAAU,EAAE,GAAiB,EAAE;QAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,YAAY,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;QACzC,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC;QAEjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,OAAO,EAAE;oBACP,OAAO,EAAE;wBACP,WAAW,EAAE,CAAC;wBACd,UAAU,EAAE,CAAC;qBACd;oBACD,KAAK,EAAE;wBACL,WAAW,EAAE,YAAY,CAAC,WAAW;wBACrC,UAAU,EAAE,YAAY,CAAC,OAAO;qBACjC;iBACF;gBACD,eAAe,EAAE,GAAG,EAAE,eAAe,IAAI,CAAC;gBAC1C,gBAAgB,EAAE,YAAY,CAAC,WAAW,GAAG,CAAC,GAAG,EAAE,eAAe,IAAI,CAAC,CAAC;aACzE,CAAC;QACJ,CAAC;QAED,MAAM,kBAAkB,GAAG,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAEzF,OAAO;YACL,OAAO,EAAE;gBACP,OAAO,EAAE;oBACP,WAAW,EAAE,kBAAkB;oBAC/B,UAAU,EAAE,MAAM,CAAC,OAAO;iBAC3B;gBACD,KAAK,EAAE;oBACL,WAAW,EAAE,kBAAkB,GAAG,YAAY,CAAC,WAAW;oBAC1D,UAAU,EAAE,MAAM,CAAC,OAAO,GAAG,YAAY,CAAC,OAAO;iBAClD;aACF;YACD,eAAe,EAAE,GAAG,EAAE,eAAe,IAAI,CAAC;YAC1C,gBAAgB,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,eAAe,IAAI,CAAC,CAAC,GAAG,YAAY,CAAC,WAAW;SAC9F,CAAC;IACJ,CAAC;IACD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,EAAE,KAAK,EAAK,EAAoB,EAAiD,EAAE;QACxF,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;QAErC,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAE1B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;QAEzC,MAAM,WAAW,GAAG,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAElF,OAAO;YACL,MAAM;YACN,OAAO,EAAE;gBACP,WAAW;gBACX,UAAU,EAAE,MAAM,CAAC,OAAO;aAC3B;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

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

@@ -1,4 +1,185 @@
-export type WaitOptions = {
+import type { ApiPromise, ApiRequestOptions, CreateWaitpointTokenRequestBody, CreateWaitpointTokenResponse, CursorPagePromise, ListWaitpointTokensQueryParams, WaitpointListTokenItem, WaitpointTokenStatus } from "@trigger.dev/core/v3";
+import { ManualWaitpointPromise } from "@trigger.dev/core/v3";
+/**
+ * This creates a waitpoint token.
+ * You can use this to pause a run until you complete the waitpoint (or it times out).
+ *
+ * @example
+ *
+ * **Manually completing a token**
+ *
+ * ```ts
+ * const token = await wait.createToken({
+ *   idempotencyKey: `approve-document-${documentId}`,
+ *   timeout: "24h",
+ *   tags: [`document-${documentId}`],
+ * });
+ *
+ * // Later, in a different part of your codebase, you can complete the waitpoint
+ * await wait.completeToken(token, {
+ *   status: "approved",
+ *   comment: "Looks good to me!",
+ * });
+ * ```
+ *
+ * @example
+ *
+ * **Completing a token with a webhook**
+ *
+ * ```ts
+ * const token = await wait.createToken({
+ *   timeout: "10m",
+ *   tags: ["replicate"],
+ * });
+ *
+ * // Later, in a different part of your codebase, you can complete the waitpoint
+ * await replicate.predictions.create({
+ *   version: "27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478",
+ *   input: {
+ *     prompt: "A painting of a cat by Andy Warhol",
+ *   },
+ *   // pass the provided URL to Replicate's webhook, so they can "callback"
+ *   webhook: token.url,
+ *   webhook_events_filter: ["completed"],
+ * });
+ *
+ * const prediction = await wait.forToken<Prediction>(token).unwrap();
+ * ```
+ *
+ * @param options - The options for the waitpoint token.
+ * @param requestOptions - The request options for the waitpoint token.
+ * @returns The waitpoint token.
+ */
+declare function createToken(options?: CreateWaitpointTokenRequestBody, requestOptions?: ApiRequestOptions): ApiPromise<CreateWaitpointTokenResponse>;
+/**
+ * Lists waitpoint tokens with optional filtering and pagination.
+ * You can iterate over all the items in the result using a for-await-of loop (you don't need to think about pagination).
+ *
+ * @example
+ * Basic usage:
+ * ```ts
+ * // List all tokens
+ * for await (const token of wait.listTokens()) {
+ *   console.log("Token ID:", token.id);
+ * }
+ * ```
+ *
+ * @example
+ * With filters:
+ * ```ts
+ * // List completed tokens from the last 24 hours with specific tags
+ * for await (const token of wait.listTokens({
+ *   status: "COMPLETED",
+ *   period: "24h",
+ *   tags: ["important", "approval"],
+ *   limit: 50
+ * })) {
+ *   console.log("Token ID:", token.id);
+ * }
+ * ```
+ *
+ * @param params - Optional query parameters for filtering and pagination
+ * @param params.status - Filter by token status
+ * @param params.idempotencyKey - Filter by idempotency key
+ * @param params.tags - Filter by tags
+ * @param params.period - Filter by time period (e.g. "24h", "7d")
+ * @param params.from - Filter by start date
+ * @param params.to - Filter by end date
+ * @param params.limit - Number of items per page
+ * @param params.after - Cursor for next page
+ * @param params.before - Cursor for previous page
+ * @param requestOptions - Additional API request options
+ * @returns Waitpoint tokens that can easily be iterated over using a for-await-of loop
+ */
+declare function listTokens(params?: ListWaitpointTokensQueryParams, requestOptions?: ApiRequestOptions): CursorPagePromise<typeof WaitpointListTokenItem>;
+/**
+ * A waitpoint token that has been retrieved.
+ *
+ * If the status is `WAITING`, this means the waitpoint is still pending.
+ * For `COMPLETED` the `output` will be the data you passed in when completing the waitpoint.
+ * For `TIMED_OUT` there will be an `error`.
+ */
+export type WaitpointRetrievedToken<T> = {
+    id: string;
+    /** A URL that you can make a POST request to in order to complete the waitpoint. */
+    url: string;
+    status: WaitpointTokenStatus;
+    completedAt?: Date;
+    timeoutAt?: Date;
+    idempotencyKey?: string;
+    idempotencyKeyExpiresAt?: Date;
+    tags: string[];
+    createdAt: Date;
+    output?: T;
+    error?: Error;
+};
+/**
+ * Retrieves a waitpoint token by its ID.
+ *
+ * @example
+ * ```ts
+ * const token = await wait.retrieveToken("waitpoint_12345678910");
+ * console.log("Token status:", token.status);
+ * console.log("Token tags:", token.tags);
+ * ```
+ *
+ * @param token - The token to retrieve.
+ * This can be a string token ID or an object with an `id` property.
+ * @param requestOptions - Optional API request options.
+ * @returns The waitpoint token details, including the output or error if the waitpoint is completed or timed out.
+ */
+declare function retrieveToken<T>(token: string | {
+    id: string;
+}, requestOptions?: ApiRequestOptions): Promise<WaitpointRetrievedToken<T>>;
+/**
+ * This completes a waitpoint token.
+ * You can use this to complete a waitpoint token that you created earlier.
+ *
+ * @example
+ *
+ * ```ts
+ * await wait.completeToken(token, {
+ *   status: "approved",
+ *   comment: "Looks good to me!",
+ * });
+ * ```
+ *
+ * @param token - The token to complete.
+ * @param data - The data to complete the waitpoint with.
+ * @param requestOptions - The request options for the waitpoint token.
+ * @returns The waitpoint token.
+ */
+declare function completeToken<T>(
+/**
+ * The token to complete.
+ * This can be a string token ID or an object with an `id` property.
+ */
+token: string | {
+    id: string;
+}, 
+/**
+ * The data to complete the waitpoint with.
+ * This will be returned when you wait for the token.
+ */
+data: T, requestOptions?: ApiRequestOptions): Promise<{
+    success: true;
+}>;
+export type CommonWaitOptions = {
+    /**
+     * An optional idempotency key for the waitpoint.
+     * If you use the same key twice (and the key hasn't expired), you will get the original waitpoint back.
+     *
+     * Note: This waitpoint may already be complete, in which case when you wait for it, it will immediately continue.
+     */
+    idempotencyKey?: string;
+    /**
+     * When set, this means the passed in idempotency key will expire after this time.
+     * This means after that time if you pass the same idempotency key again, you will get a new waitpoint.
+     */
+    idempotencyKeyTTL?: string;
+};
+export type WaitForOptions = WaitPeriod & CommonWaitOptions;
+type WaitPeriod = {
     seconds: number;
 } | {
     minutes: number;
@@ -13,10 +194,44 @@ export type WaitOptions = {
 } | {
     years: number;
 };
+export { WaitpointTimeoutError, ManualWaitpointPromise } from "@trigger.dev/core/v3";
 export declare const wait: {
-    for: (options: WaitOptions) => Promise<void>;
+    for: (options: WaitForOptions) => Promise<void>;
     until: (options: {
         date: Date;
         throwIfInThePast?: boolean;
-    }) => Promise<void>;
+    } & CommonWaitOptions) => Promise<void>;
+    createToken: typeof createToken;
+    listTokens: typeof listTokens;
+    completeToken: typeof completeToken;
+    retrieveToken: typeof retrieveToken;
+    /**
+     * This waits for a waitpoint token to be completed.
+     * It can only be used inside a task.run() block.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = await wait.forToken<typeof ApprovalData>(token);
+     * if (!result.ok) {
+     *   // The waitpoint timed out
+     *   throw result.error;
+     * }
+     *
+     * // This will be the type ApprovalData
+     * const approval = result.output;
+     * ```
+     *
+     * @param token - The token to wait for.
+     * @param options - The options for the waitpoint token.
+     * @returns A promise that resolves to the result of the waitpoint. You can use `.unwrap()` to get the result and an error will throw.
+     */
+    forToken: <T>(
+    /**
+     * The token to wait for.
+     * This can be a string token ID or an object with an `id` property.
+     */
+    token: string | {
+        id: string;
+    }) => ManualWaitpointPromise<T>;
 };