@vertesia/common 0.24.0-dev.202601221707

package/lib/types/store/workflow.d.ts

@@ -0,0 +1,730 @@
+import { JSONSchema4 } from "json-schema";
+import { ConversationVisibility, InteractionRef, UserChannel } from "../interaction.js";
+export declare enum ContentEventName {
+    create = "create",
+    change_type = "change_type",
+    update = "update",
+    revision_created = "revision_created",
+    delete = "delete",
+    workflow_finished = "workflow_finished",
+    workflow_execution_request = "workflow_execution_request",
+    api_request = "api_request"
+}
+export interface Queue {
+    name: string;
+    queue_suffix?: string;
+    queue_full_name?: string;
+}
+export interface WorkflowAncestor {
+    run_id: string;
+    workflow_id: string;
+    /**
+     * the depth of nested parent workflows
+     */
+    run_depth: number;
+}
+export interface WorkflowExecutionBaseParams<T = Record<string, any>> {
+    /**
+     * The ref of the user who initiated the workflow.
+     */
+    initiated_by?: string;
+    /**
+     * The account ID of the user who created the activity.
+     * This is useful to select the right database to work on.
+     */
+    account_id: string;
+    /**
+     * The project ID of the account who created the activity.
+     */
+    project_id: string;
+    /**
+     * The vars field is mainly used to pass the user input to the workflow.
+     * The user input ar custom user options that can be used to configure the workflow.
+     * You can see the user input as the arguments for a command line app.
+     *
+     * In the case of workflows started by events (e.g. using a a workflow rule) the user input vars will be initialized with the workflow rule configuration field.
+     *
+     * In case of dsl workflows the workflow execution payload vars will be applied over the default vars values stored in the DSL vars field.
+     */
+    vars: T;
+    /**
+     * Auth Token to access Zeno and Composable from the workers
+     */
+    auth_token?: string;
+    /**
+     * The configuration for the workflow execution.
+     */
+    config?: {
+        studio_url: string;
+        store_url: string;
+        slack_app_url?: string;
+        enabled_integrations?: string[];
+    };
+    /**
+     * The list of endpoints to notify when the workflow finishes.
+     * It is handled by a sub-workflow execution, so the main workflow will not wait for the notification to be sent.
+     */
+    notify_endpoints?: (string | WebHookSpec)[];
+    /** If this is a child workflow, parent contains parent's ids  */
+    parent?: WorkflowAncestor;
+    /**
+     * Full ancestry chain from root to immediate parent (for hierarchical aggregation)
+     */
+    ancestors?: WorkflowAncestor[];
+    /**
+     * If true, copy workspace artifacts (scripts/, files/, skills/, docs/, out/)
+     * from parent workflow to this workflow on startup.
+     * Defaults to true when spawning child workflows.
+     * conversation.json and tools.json are never copied.
+     */
+    inherit_artifacts?: boolean;
+    /**
+     *  List of enabled processing queues. Managed by the application.
+     */
+    _enabled_queues?: Queue[];
+}
+export interface WebHookSpec {
+    /**
+     * The webhook URL to call using POST method
+     */
+    url: string;
+    /**
+     * the API version to use if any
+     */
+    version?: number;
+    /**
+     * Custom headers to include in the webhook request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Additional custom data to include in the webhook body.
+     * When custom data is provided, the workflow result will always be nested
+     * to prevent field collisions. Use result_path to control where it's nested.
+     */
+    data?: Record<string, any>;
+    /**
+     * Path where the workflow result should be nested in the webhook body.
+     * Defaults to "result" when custom data is provided.
+     *
+     * Example: With result_path="workflow_result" and data={customer_id: "123"}:
+     * {
+     *   "workflow_result": { ...workflow result... },
+     *   "customer_id": "123"
+     * }
+     *
+     * Example: With data={customer_id: "123"} but no result_path (uses default):
+     * {
+     *   "result": { ...workflow result... },
+     *   "customer_id": "123"
+     * }
+     */
+    result_path?: string;
+}
+export interface WorkflowExecutionPayload<T = Record<string, any>> extends WorkflowExecutionBaseParams<T> {
+    /**
+     * The event which started the workflow who created the activity.
+     */
+    event: ContentEventName;
+    wf_rule_name?: string;
+    /**
+     * The ID of the target objects processed by the workflow.
+     */
+    objectIds: string[];
+    /**
+     * Auth Token to access Zeno and Composable from the workers
+     */
+    auth_token: string;
+}
+export declare function getDocumentIds(payload: WorkflowExecutionPayload): string[];
+export interface ExecuteWorkflowPayload {
+    /**
+     * The task queue to assign the workflow to. Deprecated, queues are choosend server side
+     */
+    task_queue?: string;
+    /**
+     * Docuument IDs pon which the workflow will be executed, deprecated, replaced params in vars
+     */
+    objectIds?: string[];
+    /**
+     * Parameters to pass to the workflow
+     */
+    vars?: Record<string, any>;
+    /**
+     * Make the workflow ID unique by always adding a random token to the ID.
+     */
+    unique?: boolean;
+    /**
+     * A custom ID to use for the workflow execution id instead of the generated one.
+     */
+    custom_id?: string;
+    /**
+     * Timeout for the workflow execution to complete, in seconds.
+     */
+    timeout?: number;
+}
+export interface ListWorkflowRunsPayload {
+    /**
+     * The document ID passed to a workflow run.
+     */
+    document_id?: string;
+    /**
+     * The event name that triggered the workflow.
+     */
+    event_name?: string;
+    /**
+     * The workflow rule ID that triggered the workflow.
+     */
+    rule_id?: string;
+    /**
+     * The start time for filtering workflow runs.
+     */
+    start?: string;
+    /**
+     * The end time for filtering workflow runs.
+     */
+    end?: string;
+    /**
+     * The status of the workflow run.
+     */
+    status?: string;
+    /**
+     * search term to filter on workflow id and run id
+     */
+    search_term?: string;
+    /**
+     * The user or service account that initiated the workflow run.
+     */
+    initiated_by?: string;
+    /**
+     * The interaction name used to filter conversations.
+     */
+    interaction?: string;
+    /**
+     * Lucene query string to search for the workflow runs.
+     * This is a full text search on the workflow run history.
+     */
+    query?: string;
+    type?: string;
+    /**
+     * The maximum number of results to return per page.
+     */
+    page_size?: number;
+    /**
+     * The page token for Temporal pagination.
+     */
+    next_page_token?: string;
+}
+interface WorkflowRunEvent {
+    event_id: number;
+    event_time: number;
+    event_type: string;
+    task_id?: string;
+    attempt: number;
+    activity?: {
+        name?: string;
+        id?: string;
+        input?: any;
+        scheduledEventId?: string;
+        startedEventId?: string;
+    };
+    childWorkflow?: {
+        workflowId?: string;
+        workflowType?: string;
+        runId?: string;
+        scheduledEventId?: string;
+        startedEventId?: string;
+        input?: any;
+        result?: any;
+    };
+    signal?: {
+        direction: "receiving" | "sending";
+        signalName?: string;
+        input?: any;
+        sender?: {
+            workflowId?: string;
+            runId?: string;
+        };
+        recipient?: {
+            workflowId?: string;
+            runId?: string;
+        };
+        initiatedEventId?: string;
+    };
+    error?: {
+        message?: string;
+        source?: string;
+        stacktrace?: string;
+        type?: string;
+    };
+    result?: any;
+}
+export interface WorkflowRun {
+    status?: WorkflowExecutionStatus | string;
+    /**
+     * The Temporal Workflow Type of this Workflow Run.
+     *
+     * @see https://docs.temporal.io/workflows
+     */
+    type?: string;
+    started_at?: number;
+    closed_at?: number;
+    execution_duration?: number;
+    run_id?: string;
+    workflow_id?: string;
+    initiated_by?: string;
+    interaction_name?: string;
+    input?: any;
+    result?: any;
+    error?: any;
+    raw?: any;
+    /**
+     * The Vertesia Workflow Type of this Workflow Run.
+     *  - For DSL workflows (`type:dslWorkflow`), the vertesia_type refers to the "Workflow Rule Name" specified in the
+     *    DSL. For example, "Standard Document Intake" or "Standard Image Intake".
+     *  - For non-DSL workflows, the vertesia_type is the name of the Temporal Workflow Type.
+     */
+    vertesia_workflow_type?: string;
+    /**
+     * An interaction is used to start the agent, the data is stored on temporal "vars"
+     */
+    interactions?: InteractionRef[];
+    /**
+     * The visibility of the workflow run.
+     * - 'private': Only visible to the user who initiated the workflow
+     * - 'project': Visible to all users in the project
+     */
+    visibility?: ConversationVisibility;
+    /**
+     * A brief summary of the conversation workflow.
+     */
+    topic?: string;
+}
+export interface WorkflowRunWithDetails extends WorkflowRun {
+    history?: WorkflowRunEvent[];
+    memo?: {
+        [key: string]: any;
+    } | null;
+    pendingActivities?: {
+        activityId?: string;
+        activityType?: string;
+        attempt: number;
+        maximumAttempts: number;
+        lastFailure?: string;
+        lastStartedTime?: number;
+    }[];
+}
+export interface ListWorkflowRunsResponse {
+    runs: WorkflowRun[];
+    next_page_token?: string;
+    has_more?: boolean;
+}
+export interface ListWorkflowInteractionsResponse {
+    workflow_id: string;
+    run_id: string;
+    interaction: WorkflowInteractionVars;
+}
+export interface WorkflowInteractionVars {
+    type: string;
+    interaction: string;
+    interactive: boolean;
+    debug_mode?: boolean;
+    /**
+     * Array of channels to use for user communication.
+     * Multiple channels can be active simultaneously.
+     */
+    user_channels?: UserChannel[];
+    data?: Record<string, any>;
+    tool_names: string[];
+    config: {
+        environment: string;
+        model: string;
+    };
+    interactionParamsSchema?: JSONSchema4;
+    collection_id?: string;
+    /**
+     * Optional version of the interaction to use when restoring conversations.
+     * If not specified, the latest version will be used.
+     */
+    version?: number;
+}
+export interface MultiDocumentsInteractionParams extends Omit<WorkflowExecutionPayload, "config"> {
+    config: {
+        interactionName: string;
+        action: DocumentActionConfig;
+        data: Record<string, any>;
+    };
+}
+export interface DocumentActionConfig {
+    contentTypeName?: string;
+    setAsProperties: boolean;
+    setAsText: string;
+    setNameFrom: string;
+    upsert: boolean;
+    documentId?: string;
+    parentId?: string;
+}
+export declare enum WorkflowExecutionStatus {
+    UNKNOWN = 0,
+    RUNNING = 1,
+    COMPLETED = 2,
+    FAILED = 3,
+    CANCELED = 4,
+    TERMINATED = 5,
+    CONTINUED_AS_NEW = 6,
+    TIMED_OUT = 7
+}
+/**
+ * Basic response for anything run with an async workflow
+ */
+export interface WorkflowRunStatus {
+    workflow_id: string | null;
+    workflow_run_id: string | null;
+    status: WorkflowExecutionStatus;
+}
+/**
+ * Workflow Update Message
+ */
+export interface AgentMessage {
+    timestamp: number;
+    workflow_run_id: string;
+    type: AgentMessageType;
+    message: string;
+    details?: any;
+    workstream_id?: string;
+}
+export declare enum AgentMessageType {
+    SYSTEM = 0,
+    THOUGHT = 1,
+    PLAN = 2,
+    UPDATE = 3,
+    COMPLETE = 4,
+    WARNING = 5,
+    ERROR = 6,
+    ANSWER = 7,
+    QUESTION = 8,
+    REQUEST_INPUT = 9,
+    IDLE = 10,
+    TERMINATED = 11,
+    STREAMING_CHUNK = 12,
+    BATCH_PROGRESS = 13
+}
+/**
+ * Details for STREAMING_CHUNK messages used for real-time LLM response streaming
+ * @deprecated Use CompactMessage with f field for streaming chunks
+ */
+export interface StreamingChunkDetails {
+    /** Unique identifier grouping chunks from the same stream */
+    streaming_id: string;
+    /** Order of this chunk within the stream (0-indexed) */
+    chunk_index: number;
+    /** True if this is the final chunk of the stream */
+    is_final: boolean;
+}
+/**
+ * Compact message format for efficient wire transfer.
+ * Primary type used throughout the system.
+ * ~85% smaller than legacy AgentMessage format.
+ */
+export interface CompactMessage {
+    /** Message type (integer enum) */
+    t: AgentMessageType;
+    /** Message content */
+    m?: string;
+    /** Workstream ID (only when not "main") */
+    w?: string;
+    /** Type-specific details */
+    d?: unknown;
+    /** Is final chunk (only for STREAMING_CHUNK, 0 or 1) */
+    f?: 0 | 1;
+    /** Timestamp (only for stored/persisted messages) */
+    ts?: number;
+}
+/**
+ * Legacy message format for backward compatibility.
+ * @deprecated Use CompactMessage instead
+ */
+export type LegacyAgentMessage = AgentMessage;
+/**
+ * Check if a message is in compact format
+ */
+export declare function isCompactMessage(msg: unknown): msg is CompactMessage;
+/**
+ * Check if a message is in legacy format
+ */
+export declare function isLegacyMessage(msg: unknown): msg is LegacyAgentMessage;
+/**
+ * Normalize message type from string or number to AgentMessageType
+ */
+export declare function normalizeMessageType(type: string | number | AgentMessageType): AgentMessageType;
+/**
+ * Convert legacy AgentMessage to CompactMessage
+ */
+export declare function toCompactMessage(legacy: LegacyAgentMessage): CompactMessage;
+/**
+ * Parse any message format (compact or legacy) into CompactMessage.
+ * Use this as the entry point for all received messages.
+ */
+export declare function parseMessage(data: string | object): CompactMessage;
+/**
+ * Create a compact message (convenience function for server-side)
+ */
+export declare function createCompactMessage(type: AgentMessageType, options?: {
+    message?: string;
+    workstreamId?: string;
+    details?: unknown;
+    isFinal?: boolean;
+    timestamp?: number;
+}): CompactMessage;
+/**
+ * Convert CompactMessage back to AgentMessage (for UI components).
+ * This allows UI to continue using familiar field names while wire format is compact.
+ * @param compact The compact message to convert
+ * @param workflowRunId Optional workflow_run_id (known from SSE context, not in compact format)
+ */
+export declare function toAgentMessage(compact: CompactMessage, workflowRunId?: string): AgentMessage;
+/**
+ * Status of a single item in a batch execution
+ */
+export interface BatchItemStatus {
+    /** Unique identifier for this batch item */
+    id: string;
+    /** Current status of the item */
+    status: "pending" | "running" | "success" | "error";
+    /** Optional message (e.g., error message or result summary) */
+    message?: string;
+    /** Execution duration in milliseconds (when completed) */
+    duration_ms?: number;
+}
+/**
+ * Details for BATCH_PROGRESS messages used for batch tool execution progress
+ */
+export interface BatchProgressDetails {
+    /** Unique identifier for this batch execution */
+    batch_id: string;
+    /** Name of the tool being batch executed */
+    tool_name: string;
+    /** Total number of items in the batch */
+    total: number;
+    /** Number of items completed */
+    completed: number;
+    /** Number of items that succeeded */
+    succeeded: number;
+    /** Number of items that failed */
+    failed: number;
+    /** Status of individual items */
+    items: BatchItemStatus[];
+    /** Timestamp when batch started */
+    started_at: number;
+    /** Timestamp when batch completed (if done) */
+    completed_at?: number;
+}
+/**
+ * Status of a file being processed for conversation use.
+ */
+export declare enum FileProcessingStatus {
+    /** File is being uploaded to artifact storage */
+    UPLOADING = "uploading",
+    /** File uploaded, text extraction in progress */
+    PROCESSING = "processing",
+    /** File is ready for use in conversation */
+    READY = "ready",
+    /** File processing failed */
+    ERROR = "error"
+}
+/**
+ * Represents a file being processed in a conversation workflow.
+ */
+export interface ConversationFile {
+    /** Unique ID for tracking this file (generated client-side) */
+    id: string;
+    /** Original filename */
+    name: string;
+    /** MIME type */
+    content_type: string;
+    /** Size in bytes */
+    size: number;
+    /** Current processing status */
+    status: FileProcessingStatus;
+    /** Artifact path (e.g., "files/document.pdf") - set after upload */
+    artifact_path?: string;
+    /** Full artifact reference URI (e.g., "artifact:files/document.pdf") */
+    reference?: string;
+    /** Path to extracted text markdown (e.g., "files/document.pdf.md") */
+    md_path?: string;
+    /** Whether text extraction completed successfully */
+    text_extracted?: boolean;
+    /** Error message if status is ERROR */
+    error?: string;
+    /** Timestamp when upload started */
+    started_at: number;
+    /** Timestamp when processing completed */
+    completed_at?: number;
+}
+/**
+ * Details for file processing SYSTEM messages.
+ * Used when type is AgentMessageType.SYSTEM with system_type: 'file_processing'.
+ */
+export interface FileProcessingDetails {
+    /** Discriminator for SYSTEM message subtypes */
+    system_type: 'file_processing';
+    /** Batch ID for grouping related file operations */
+    batch_id: string;
+    /** All files in this batch with their current status */
+    files: ConversationFile[];
+    /** Number of files still being processed */
+    pending_count: number;
+    /** Number of files ready for use */
+    ready_count: number;
+    /** Number of files that failed */
+    error_count: number;
+}
+/**
+ * Reference to a file uploaded via the UI for conversation use.
+ */
+export interface ConversationFileRef {
+    /** Client-generated unique ID */
+    id: string;
+    /** Original filename */
+    name: string;
+    /** MIME type */
+    content_type: string;
+    /** Artifact reference (e.g., "artifact:files/document.pdf") */
+    reference: string;
+    /** Artifact path without prefix (e.g., "files/document.pdf") */
+    artifact_path: string;
+}
+/**
+ * Get the Redis pub/sub channel name for workflow messages.
+ * Used by both publishers (workflow activities, studio-server) and subscribers (zeno-server, clients).
+ * @param workflowRunId - The Temporal workflow run ID (NOT the interaction execution run ID)
+ */
+export declare function getWorkflowChannel(workflowRunId: string): string;
+/**
+ * Get the Redis list key for storing workflow message history.
+ * Messages are stored here for retrieval by reconnecting clients.
+ * @param workflowRunId - The Temporal workflow run ID (NOT the interaction execution run ID)
+ */
+export declare function getWorkflowUpdatesKey(workflowRunId: string): string;
+export interface PlanTask {
+    id: number;
+    goal: string;
+    instructions: string[];
+    comment?: string;
+    status?: "pending" | "in_progress" | "completed" | "skipped";
+}
+export interface Plan {
+    plan: PlanTask[];
+    comment?: string;
+}
+export declare const LOW_PRIORITY_TASK_QUEUE = "low_priority";
+/**
+ * WebSocket message types for bidirectional communication
+ */
+export interface WebSocketSignalMessage {
+    type: 'signal';
+    signalName: string;
+    data: any;
+    requestId?: string | number;
+}
+export interface WebSocketPingMessage {
+    type: 'ping';
+}
+export interface WebSocketPongMessage {
+    type: 'pong';
+}
+export interface WebSocketAckMessage {
+    type: 'ack';
+    requestId: string | number;
+}
+export interface WebSocketErrorMessage {
+    type: 'error';
+    requestId?: string | number;
+    error: string;
+}
+export type WebSocketClientMessage = WebSocketSignalMessage | WebSocketPingMessage;
+export type WebSocketServerMessage = WebSocketPongMessage | WebSocketAckMessage | WebSocketErrorMessage | AgentMessage;
+/**
+ * Payload for applying actions to a workflow run (e.g., cancel, terminate).
+ */
+export interface WorkflowActionPayload {
+    /**
+     * Optional reason for the action.
+     */
+    reason?: string;
+}
+/**
+ * Parameters for the AgentIntakeWorkflow.
+ * This workflow uses an intelligent agent to process documents:
+ * - Select or create appropriate content types
+ * - Extract properties using schema-enforced interactions
+ * - File documents into relevant collections
+ */
+export interface AgentIntakeWorkflowParams {
+    /**
+     * The interaction to use for document intake agent.
+     * Defaults to "sys:DocumentIntakeAgent" if not specified.
+     * Can be overridden with a project-level interaction.
+     */
+    intakeInteraction?: string;
+    /**
+     * The interaction to use for property extraction.
+     * Defaults to "sys:ExtractInformation" if not specified.
+     * Can be overridden with a project-level interaction.
+     */
+    extractionInteraction?: string;
+    /**
+     * Whether to generate table of contents for documents.
+     * Defaults to true for documents, false for images/videos.
+     */
+    generateTableOfContents?: boolean;
+    /**
+     * Whether to generate embeddings after processing.
+     * Defaults to true.
+     */
+    generateEmbeddings?: boolean;
+    /**
+     * Max iterations for the agent workflow.
+     * Defaults to 50.
+     */
+    maxIterations?: number;
+    /**
+     * Environment ID for LLM execution.
+     */
+    environment?: string;
+    /**
+     * Model to use for the agent.
+     */
+    model?: string;
+    /**
+     * Additional model options.
+     */
+    model_options?: Record<string, unknown>;
+    /**
+     * Whether to use semantic layer (MagicPDF) for PDF processing.
+     */
+    useSemanticLayer?: boolean;
+    /**
+     * Whether to use vision for image-based extraction.
+     */
+    useVision?: boolean;
+}
+/**
+ * Result of the AgentIntakeWorkflow
+ */
+export interface AgentIntakeWorkflowResult {
+    /** The object ID that was processed */
+    objectId: string;
+    /** Whether text was extracted */
+    hasText: boolean;
+    /** Whether table of contents was generated */
+    hasTableOfContents: boolean;
+    /** The type ID assigned to the document */
+    typeId?: string;
+    /** Whether properties were extracted */
+    hasProperties: boolean;
+    /** Collection IDs the document was added to */
+    collectionIds?: string[];
+    /** Whether embeddings were generated */
+    hasEmbeddings: boolean;
+}
+export {};