@vertesia/workflow 1.2.0 → 1.3.0-dev.20260620.061059Z

package/src/errors.ts

@@ -1,13 +1,16 @@
-import { ApplicationFailure } from "@temporalio/workflow";
-import { DSLActivitySpec, DSLWorkflowSpec } from "@vertesia/common";
+import { ApplicationFailure } from '@temporalio/workflow';
+import type { DSLActivitySpec, DSLWorkflowSpec } from '@vertesia/common';
 
 export class DocumentNotFoundError extends ApplicationFailure {
-    constructor(message: string, public ids?: string[]) {
+    constructor(
+        message: string,
+        public ids?: string[],
+    ) {
         super(
             message,
-            "DocumentNotFoundError",
+            'DocumentNotFoundError',
             true, // non-retryable
-        )
+        );
     }
 }
 
@@ -18,7 +21,7 @@ export class ActivityParamNotFoundError extends ApplicationFailure {
     ) {
         super(
             `Required parameter ${paramName} not found in activity ${activity.name}`,
-            "ActivityParamNotFoundError",
+            'ActivityParamNotFoundError',
             true, // non-retryable
         );
     }
@@ -31,8 +34,8 @@ export class ActivityParamInvalidError extends ApplicationFailure {
         reason?: string,
     ) {
         super(
-            `${paramName} in activity ${activity.name} is invalid${reason ? ` ${reason}` : ""}`,
-            "ActivityParamInvalidError",
+            `${paramName} in activity ${activity.name} is invalid${reason ? ` ${reason}` : ''}`,
+            'ActivityParamInvalidError',
             true, // non-retryable
         );
     }
@@ -45,7 +48,7 @@ export class WorkflowParamNotFoundError extends ApplicationFailure {
     ) {
         super(
             `Required parameter ${paramName} not found in workflow ${workflow?.name}`,
-            "WorkflowParamNotFoundError",
+            'WorkflowParamNotFoundError',
             true, // non-retryable
         );
     }
@@ -57,8 +60,8 @@ export class ResourceExhaustedError extends ApplicationFailure {
         message?: string,
     ) {
         super(
-            message || "Resource exhausted - rate limit exceeded",
-            "ResourceExhaustedError",
+            message || 'Resource exhausted - rate limit exceeded',
+            'ResourceExhaustedError',
             true, // non-retryable
         );
     }
@@ -72,7 +75,7 @@ export class InvalidContentTypeError extends ApplicationFailure {
     ) {
         super(
             `Document ${objectId} has invalid content type. Expected ${expectedType}, got ${actualType}`,
-            "InvalidContentTypeError",
+            'InvalidContentTypeError',
             true, // non-retryable
         );
     }
@@ -84,8 +87,8 @@ export class TokenExpiredError extends ApplicationFailure {
         message?: string,
     ) {
         super(
-            message || "Token expired: Authentication required",
-            "TokenExpiredError",
+            message || 'Token expired: Authentication required',
+            'TokenExpiredError',
             true, // non-retryable
         );
     }
@@ -98,19 +101,24 @@ export class WorkflowExecutionError extends ApplicationFailure {
     ) {
         super(
             message,
-            "WorkflowExecutionError",
+            'WorkflowExecutionError',
             true, // non-retryable
         );
     }
 }
 
 export const WF_NON_RETRYABLE_ERRORS = [
-    "DocumentNotFoundError",
-    "ActivityParamInvalidError",
-    "ActivityParamNotFoundError",
-    "WorkflowParamNotFoundError",
-    "InvalidContentTypeError",
-    "TokenExpiredError",
-    "ZenoClientNotFoundError",
-    "WorkflowExecutionError",
+    'DocumentNotFoundError',
+    'ActivityParamInvalidError',
+    'ActivityParamNotFoundError',
+    'WorkflowParamNotFoundError',
+    'InvalidContentTypeError',
+    'TokenExpiredError',
+    'ZenoClientNotFoundError',
+    'WorkflowExecutionError',
+    // Temporal raises NotFoundError when an activity isn't registered on the worker
+    // (e.g. a new tool whose activity barrel export was missed). Retrying can never
+    // make it appear within a worker version, and the retried failure carries the
+    // full activity list which blows the payload size limit — so fail fast.
+    'NotFoundError',
 ];

package/src/index.ts

@@ -6,37 +6,32 @@
  * 3. Here we export the API to be used to validate workflows and the types required to create workflow TS definitions.
  */
 
+export * from './activities/advanced/createDocumentTypeFromInteractionRun.js';
+export * from './activities/advanced/createOrUpdateDocumentFromInteractionRun.js';
+export * from './activities/advanced/updateDocumentFromInteractionRun.js';
+export * from './activities/chunkDocument.js';
+export * from './activities/executeInteraction.js';
+export * from './activities/extractDocumentText.js';
+export * from './activities/generateDocumentProperties.js';
+export * from './activities/generateEmbeddings.js';
+export * from './activities/generateOrAssignContentType.js';
+export * from './activities/media/prepareAudio.js';
+export * from './activities/media/prepareVideo.js';
+export * from './activities/notifyWebhook.js';
+export * from './activities/rateLimiter.js';
+export * from './activities/renditions/generateImageRendition.js';
+export * from './activities/renditions/generateVideoRendition.js';
+export * from './activities/setDocumentStatus.js';
+export * from './conversion/image.js';
 //TODO remove this - it is only for backward compat - iot is used from old workflows
-export { dslWorkflow } from "./dsl/dsl-workflow.js";
-export * from "./iterative-generation/iterativeGenerationWorkflow.js";
-
-export * from "./activities/advanced/createDocumentTypeFromInteractionRun.js";
-export * from "./activities/advanced/createOrUpdateDocumentFromInteractionRun.js";
-export * from "./activities/advanced/updateDocumentFromInteractionRun.js";
-export * from "./activities/chunkDocument.js";
-export * from "./activities/executeInteraction.js";
-export * from "./activities/extractDocumentText.js";
-export * from "./activities/generateDocumentProperties.js";
-export * from "./activities/generateEmbeddings.js";
-export * from "./activities/generateOrAssignContentType.js";
-export * from "./activities/media/prepareAudio.js";
-export * from "./activities/media/prepareVideo.js";
-export * from "./activities/notifyWebhook.js";
-export * from "./activities/rateLimiter.js";
-export * from "./activities/renditions/generateImageRendition.js";
-export * from "./activities/renditions/generateVideoRendition.js";
-export * from "./activities/setDocumentStatus.js";
-export * from "./iterative-generation/activities/index.js";
-
-export * from "./dsl/setup/ActivityContext.js";
-export * from "./errors.js";
-export * from "./result-types.js";
-export * from "./utils/blobs.js";
-export * from "./utils/client.js";
-export * from "./utils/memory.js";
-export * from "./utils/renditions.js";
-export * from "./utils/storage.js";
-export * from "./utils/text-preview-utils.js";
-export * from "./utils/tokens.js";
-
-export * from "./conversion/image.js";
+export { dslWorkflow } from './dsl/dsl-workflow.js';
+export * from './dsl/setup/ActivityContext.js';
+export * from './errors.js';
+export * from './result-types.js';
+export * from './utils/activity-info.js';
+export * from './utils/blobs.js';
+export * from './utils/client.js';
+export * from './utils/renditions.js';
+export * from './utils/storage.js';
+export * from './utils/text-preview-utils.js';
+export * from './utils/tokens.js';

package/src/result-types.ts

@@ -1,15 +1,12 @@
-
-
-
 /**
  * The result of a text extraction operation.
  */
 export interface TextExtractionResult {
     objectId?: string;
-    file?: {   
+    file?: {
         source_url: string;
         result_url?: string;
-    }
+    };
     status: TextExtractionStatus;
     hasText: boolean;
     message?: string;
@@ -23,7 +20,7 @@ export interface TextExtractionResult {
 }
 
 export enum TextExtractionStatus {
-    skipped = "skipped",
-    success = "success",
-    error = "error",
-}
+    skipped = 'skipped',
+    success = 'success',
+    error = 'error',
+}

package/src/system/notifyWebhookWorkflow.ts

@@ -1,14 +1,11 @@
+import { log, workflowInfo } from '@temporalio/workflow';
+import type { WebHookSpec, WorkflowExecutionPayload } from '@vertesia/common';
+import type * as activities from '../activities/notifyWebhook.js';
+import { dslProxyActivities } from '../dsl/dslProxyActivities.js';
+import { WF_NON_RETRYABLE_ERRORS } from '../errors.js';
 
-import { log, workflowInfo } from "@temporalio/workflow";
-import { WebHookSpec, WorkflowExecutionPayload } from "@vertesia/common";
-import * as activities from "../activities/notifyWebhook.js";
-import { dslProxyActivities } from "../dsl/dslProxyActivities.js";
-import { WF_NON_RETRYABLE_ERRORS } from "../errors.js";
-
-const {
-    notifyWebhook
-} = dslProxyActivities<typeof activities>("notifyWebhookWorkflow", {
-    startToCloseTimeout: "5 minute",
+const { notifyWebhook } = dslProxyActivities<typeof activities>('notifyWebhookWorkflow', {
+    startToCloseTimeout: '5 minute',
     retry: {
         initialInterval: '5s',
         backoffCoefficient: 2,
@@ -20,18 +17,22 @@ const {
 
 export interface NotifyWebhookWorfklowParams {
     workflow_type: string;
-    endpoints: (string | WebHookSpec)[],
-    data: Record<string, any>
+    endpoints: (string | WebHookSpec)[];
+    data: Record<string, unknown>;
 }
 
-
-export async function notifyWebhookWorkflow(payload: WorkflowExecutionPayload<NotifyWebhookWorfklowParams>): Promise<any> {
-
+export async function notifyWebhookWorkflow(
+    payload: WorkflowExecutionPayload<NotifyWebhookWorfklowParams>,
+): Promise<unknown> {
     const info = workflowInfo();
     const { objectIds, vars } = payload;
     const notifications = [];
-    const endpoints = vars.endpoints ?? (vars as any).webhooks ?? [];
-    const data = vars.data ?? (vars as any).webhook_data ?? undefined;
+    const legacyVars = vars as NotifyWebhookWorfklowParams & {
+        webhooks?: (string | WebHookSpec)[];
+        webhook_data?: Record<string, unknown>;
+    };
+    const endpoints = legacyVars.endpoints ?? legacyVars.webhooks ?? [];
+    const data = legacyVars.data ?? legacyVars.webhook_data ?? undefined;
     const workflow_type = vars.workflow_type ?? info.workflowType;
     const eventName = payload.event;
 
@@ -40,7 +41,7 @@ export async function notifyWebhookWorkflow(payload: WorkflowExecutionPayload<No
 
     if (!endpoints.length) {
         log.info(`No webhooks to notify`);
-        return { notifications: [], message: "No webhooks to notify" };
+        return { notifications: [], message: 'No webhooks to notify' };
     }
 
     for (const ep of endpoints) {
@@ -53,9 +54,9 @@ export async function notifyWebhookWorkflow(payload: WorkflowExecutionPayload<No
             event_name: eventName,
             detail: {
                 object_ids: objectIds,
-                data
-            }
-        }).then(res => {
+                data,
+            },
+        }).then((res) => {
             log.info(`Webhook notified at ${ep} with response code: ${res.status}`, { res });
             return res;
         });
@@ -65,6 +66,5 @@ export async function notifyWebhookWorkflow(payload: WorkflowExecutionPayload<No
     const res = await Promise.all(notifications);
     log.info(`Webhooks notified`);
 
-    return { notifications: res, message: "Webhooks notified" };
-
+    return { notifications: res, message: 'Webhooks notified' };
 }

package/src/system/recalculateEmbeddingsWorkflow.ts

@@ -1,13 +1,10 @@
+import { SupportedEmbeddingTypes, type WorkflowExecutionPayload } from '@vertesia/common';
+import type * as activities from '../activities/index-dsl.js';
+import { dslProxyActivities } from '../dsl/dslProxyActivities.js';
+import { WF_NON_RETRYABLE_ERRORS } from '../errors.js';
 
-import { SupportedEmbeddingTypes, WorkflowExecutionPayload } from "@vertesia/common";
-import * as activities from "../activities/index-dsl.js";
-import { dslProxyActivities } from "../dsl/dslProxyActivities.js";
-import { WF_NON_RETRYABLE_ERRORS } from "../errors.js";
-
-const {
-    generateEmbeddings,
-} = dslProxyActivities<typeof activities>("recalculateEmbeddingsWorkflow", {
-    startToCloseTimeout: "5 minute",
+const { generateEmbeddings } = dslProxyActivities<typeof activities>('recalculateEmbeddingsWorkflow', {
+    startToCloseTimeout: '5 minute',
     retry: {
         initialInterval: '10s',
         backoffCoefficient: 2,
@@ -18,24 +15,24 @@ const {
 });
 
 export async function recalculateEmbeddingsWorkflow(payload: WorkflowExecutionPayload) {
-
     const embeddings = [];
     const payloadType = payload.vars?.type as SupportedEmbeddingTypes;
 
     if (payloadType && !Object.values(SupportedEmbeddingTypes).includes(payloadType)) {
-        throw new Error("Embedding type must be text, image, or properties");
+        throw new Error('Embedding type must be text, image, or properties');
     }
     const types = payloadType ? [payloadType] : Object.values(SupportedEmbeddingTypes);
 
     for (const type of types) {
-        embeddings.push(generateEmbeddings(payload, {
-            force: true,
-            type
-        }))
+        embeddings.push(
+            generateEmbeddings(payload, {
+                force: true,
+                type,
+            }),
+        );
     }
 
     const res = await Promise.all(embeddings);
 
     return res;
-
-}
+}

package/src/utils/activity-info.ts

@@ -0,0 +1,15 @@
+import { activityInfo, type Info } from '@temporalio/activity';
+
+/**
+ * Temporal SDK 1.17 changed {@link Info.workflowExecution} to be optional.
+ * Inside an activity it is always populated, so this asserts its presence and
+ * returns it, letting callers read `runId` / `workflowId` without unsafe access
+ * on a possibly-undefined value.
+ */
+export function activityWorkflowExecution(info: Info = activityInfo()) {
+    const execution = info.workflowExecution;
+    if (!execution) {
+        throw new Error('Activity is running without workflowExecution info');
+    }
+    return execution;
+}

package/src/utils/auth.ts

@@ -1,4 +1,4 @@
-import { AuthTokenPayload, ProjectRef } from '@vertesia/common';
+import type { AuthTokenPayload, ProjectRef } from '@vertesia/common';
 import jwt from 'jsonwebtoken';
 
 export function decodeAuthToken(token: string): AuthTokenPayload {

package/src/utils/blobs.ts

@@ -1,29 +1,30 @@
-import { VertesiaClient } from "@vertesia/client";
-import crypto from "crypto";
-import { createWriteStream } from "fs";
-import { Readable } from "stream";
-import { pipeline } from "stream/promises";
-import tmp from "tmp";
-import { DocumentNotFoundError } from "../errors.js";
+import crypto from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { VertesiaClient } from '@vertesia/client';
+import tmp from 'tmp';
+import { DocumentNotFoundError } from '../errors.js';
 
 tmp.setGracefulCleanup();
 
 export async function fetchBlobAsStream(client: VertesiaClient, blobUri: string): Promise<ReadableStream<Uint8Array>> {
     try {
         return await client.files.downloadFile(blobUri);
-    } catch (err: any) {
-        if (err.message.includes("not found")) {
+    } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
             //TODO improve error handling with a fetch fail error class in the client
-            throw new DocumentNotFoundError(`Not found at ${blobUri}: ${err.message}`, []);
-        } else if (err.message.includes("forbidden")) {
-            throw new DocumentNotFoundError(`Forbidden at ${blobUri}: ${err.message}`);
+            throw new DocumentNotFoundError(`Not found at ${blobUri}: ${message}`, []);
+        } else if (message.includes('forbidden')) {
+            throw new DocumentNotFoundError(`Forbidden at ${blobUri}: ${message}`);
         } else {
-            throw new Error(`Failed to download blob ${blobUri}: ${err.message}`);
+            throw new Error(`Failed to download blob ${blobUri}: ${message}`);
         }
     }
 }
 export async function fetchBlobAsBuffer(client: VertesiaClient, blobUri: string): Promise<Buffer> {
-    let stream = await fetchBlobAsStream(client, blobUri);
+    const stream = await fetchBlobAsStream(client, blobUri);
     const buffers: Uint8Array[] = [];
     for await (const data of stream) {
         buffers.push(data);
@@ -33,7 +34,7 @@ export async function fetchBlobAsBuffer(client: VertesiaClient, blobUri: string)
 
 export async function fetchBlobAsBase64(client: VertesiaClient, blobUri: string): Promise<string> {
     const buffer = await fetchBlobAsBuffer(client, blobUri);
-    return buffer.toString("base64");
+    return buffer.toString('base64');
 }
 
 async function saveBlobToFile(client: VertesiaClient, blobUri: string, toFile: string): Promise<void> {
@@ -47,13 +48,13 @@ async function saveBlobToFile(client: VertesiaClient, blobUri: string, toFile: s
 
 export async function saveBlobToTempFile(client: VertesiaClient, blobUri: string, fileExt?: string): Promise<string> {
     const tmpFile = tmp.fileSync({
-        prefix: "vertesia-activity-",
-        postfix: fileExt ? "." + fileExt : "",
+        prefix: 'vertesia-activity-',
+        postfix: fileExt ? `.${fileExt}` : '',
     });
     await saveBlobToFile(client, blobUri, tmpFile.name);
     return tmpFile.name;
 }
 
 export function md5(contents: string) {
-    return crypto.createHash("md5").update(contents).digest("hex");
+    return crypto.createHash('md5').update(contents).digest('hex');
 }

package/src/utils/chunks.ts

@@ -1,17 +1,16 @@
-
 export interface DocPart {
-    line_number_start: number
-    line_number_end: number
-    name: string
-    type: string
+    line_number_start: number;
+    line_number_end: number;
+    name: string;
+    type: string;
 }
 
 export const getContentPart = (content: string, part: DocPart): string => {
     const lines = content.split('\n');
     const text = lines.filter((_l, i) => i >= part.line_number_start && i <= part.line_number_end).join('\n');
     return text;
-}
+};
 
 export const getContentParts = (content: string, parts: DocPart[]): string[] => {
-    return parts.map(part => getContentPart(content, part));
-}
+    return parts.map((part) => getContentPart(content, part));
+};

package/src/utils/client.ts

@@ -2,36 +2,37 @@
  * get a zeno client for a given token
  */
 
-import {
-    decodeJWT,
-    VertesiaClient,
-    VertesiaClientProps,
-} from "@vertesia/client";
-import { WorkflowExecutionBaseParams } from "@vertesia/common";
-import { WorkflowParamNotFoundError } from "../errors.js";
-
-export function getVertesiaClient(payload: WorkflowExecutionBaseParams) {
+import { decodeJWT, VertesiaClient, type VertesiaClientProps } from '@vertesia/client';
+import type { WorkflowExecutionBaseParams } from '@vertesia/common';
+import { WorkflowParamNotFoundError } from '../errors.js';
+
+// Short default timeout for ordinary workflow -> server/store calls (object GETs, status updates,
+// etc.). A stale/dead pooled connection (a server pod scaled down/rolled mid-request) used to hang
+// for the whole 30-minute undici headersTimeout; this bounds it to seconds so it fails fast and the
+// activity is retried. The long path — synchronous interaction execution, which blocks on the model —
+// sets its own long per-request timeout in @vertesia/client (executeInteraction*), overriding this.
+// Override the default via VERTESIA_WORKFLOW_FETCH_TIMEOUT_MS (0/false disables it).
+const DEFAULT_WORKFLOW_FETCH_TIMEOUT_MS = 60 * 1000;
+const WORKFLOW_FETCH_TIMEOUT_ENV = 'VERTESIA_WORKFLOW_FETCH_TIMEOUT_MS';
+
+export function getVertesiaClient(payload: WorkflowExecutionBaseParams<unknown>) {
     return new VertesiaClient(getVertesiaClientOptions(payload));
 }
 
-export function getVertesiaClientOptions(
-    payload: WorkflowExecutionBaseParams,
-): VertesiaClientProps {
+export function getVertesiaClientOptions(payload: WorkflowExecutionBaseParams<unknown>): VertesiaClientProps {
     if (!payload.auth_token) {
-        throw new WorkflowParamNotFoundError(
-            "Authentication Token is missing from WorkflowExecutionPayload.authToken",
-        );
+        throw new WorkflowParamNotFoundError('Authentication Token is missing from WorkflowExecutionPayload.authToken');
     }
 
     if (!payload.config?.studio_url) {
         throw new WorkflowParamNotFoundError(
-            "Content Store URL is missing from WorkflowExecutionPayload.servers.storeUrl",
+            'Content Store URL is missing from WorkflowExecutionPayload.servers.storeUrl',
         );
     }
 
     if (!payload.config?.store_url) {
         throw new WorkflowParamNotFoundError(
-            "Content Store URL is missing from WorkflowExecutionPayload.servers.storeUrl",
+            'Content Store URL is missing from WorkflowExecutionPayload.servers.storeUrl',
         );
     }
 
@@ -42,5 +43,32 @@ export function getVertesiaClientOptions(
         storeUrl: payload.config.store_url,
         tokenServerUrl: token.iss,
         apikey: payload.auth_token,
+        timeout: parseWorkflowFetchTimeoutMs(),
     };
 }
+
+function parseWorkflowFetchTimeoutMs(): number | false {
+    const raw = typeof process !== 'undefined' ? process.env?.[WORKFLOW_FETCH_TIMEOUT_ENV] : undefined;
+    if (!raw) {
+        return DEFAULT_WORKFLOW_FETCH_TIMEOUT_MS;
+    }
+
+    // Only an explicit 0/false disables the fail-fast timeout.
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === '0' || normalized === 'false') {
+        return false;
+    }
+
+    // Require a plain positive integer count of milliseconds. parseInt() is too lenient — it
+    // reads "30s" as 30 (i.e. 30ms, off by 1000x) and "60000ms" as 60000 — so validate the raw
+    // string first. Any other garbage (typo, negative, unit suffix) keeps the fail-fast default
+    // rather than silently disabling the timeout, which would reintroduce the multi-minute hang.
+    if (!/^\d+$/.test(normalized) || Number.parseInt(normalized, 10) <= 0) {
+        console.warn(
+            `[workflow] Invalid ${WORKFLOW_FETCH_TIMEOUT_ENV}="${raw}"; ` +
+                `expected a positive integer in milliseconds. Falling back to ${DEFAULT_WORKFLOW_FETCH_TIMEOUT_MS}ms`,
+        );
+        return DEFAULT_WORKFLOW_FETCH_TIMEOUT_MS;
+    }
+    return Number.parseInt(normalized, 10);
+}

package/src/utils/expand-vars.ts

@@ -1,4 +1,3 @@
-
 const VARS_RX = /\${\s*([^}]+)\s*}/g;
 
 /**
@@ -7,7 +6,7 @@ const VARS_RX = /\${\s*([^}]+)\s*}/g;
  * @param expr
  * @param vars
  */
-export function expandVars(expr: string, vars: Record<string, any>) {
+export function expandVars(expr: string, vars: Record<string, unknown>) {
     return expr.replace(VARS_RX, (_: string, name: string) => {
         const path = name.split('.');
         const value = resolveProp(vars, path);
@@ -19,13 +18,17 @@ export function expandVars(expr: string, vars: Record<string, any>) {
     });
 }
 
-function resolveProp(object: object, path: string[]) {
-    let value: any = object;
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object';
+}
+
+function resolveProp(object: Record<string, unknown>, path: string[]) {
+    let value: unknown = object;
     for (const part of path) {
-        if (value === undefined) {
+        if (!isRecord(value)) {
             return undefined;
         }
         value = value[part];
     }
     return value;
-}
+}