@vertesia/common 0.81.1 → 1.0.0-dev.20260203.130115Z

package/src/store/workflow.ts

@@ -1,5 +1,5 @@
 import { JSONSchema4 } from "json-schema";
-import { ConversationVisibility, InteractionRef } from "../interaction.js";
+import { ConversationVisibility, InteractionRef, UserChannel } from "../interaction.js";
 
 export enum ContentEventName {
     create = "create",
@@ -19,6 +19,15 @@ export interface Queue {
     queue_full_name?: string; // full name
 }
 
+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.
@@ -69,14 +78,20 @@ export interface WorkflowExecutionBaseParams<T = Record<string, any>> {
     notify_endpoints?: (string | WebHookSpec)[];
 
     /** If this is a child workflow, parent contains parent's ids  */
-    parent?: {
-        run_id: string;
-        workflow_id: string;
-        /**
-         * the depth of nested parent workflows
-         */
-        run_depth?: number;
-    };
+    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.
@@ -185,6 +200,13 @@ export interface ExecuteWorkflowPayload {
      * Timeout for the workflow execution to complete, in seconds.
      */
     timeout?: number; //timeout in seconds
+
+    /**
+     * Schedule the workflow to run at a specific time (ISO 8601 datetime).
+     * Example: "2024-02-15T16:00:00Z"
+     * If in the past or not provided, workflow runs immediately.
+     */
+    run_at?: string;
 }
 
 export interface ListWorkflowRunsPayload {
@@ -251,11 +273,44 @@ export interface ListWorkflowRunsPayload {
      * The page token for Temporal pagination.
      */
     next_page_token?: string;
+
+    /**
+     * Filter by whether the workflow has reported errors (TemporalReportedProblems).
+     */
+    has_reported_errors?: boolean;
+}
+
+/**
+ * Signal event properties for workflow events
+ */
+export interface SignalEventProperties {
+    direction: 'receiving' | 'sending';
+    signalName?: string;
+    input?: any;
+    sender?: {
+        workflowId?: string;
+        runId?: string;
+    };
+    recipient?: {
+        workflowId?: string;
+        runId?: string;
+    };
+    initiatedEventId?: string;
 }
 
-interface WorkflowRunEvent {
+/**
+ * Error information from failed workflow events
+ */
+export interface EventError {
+    message?: string;
+    source?: string;
+    stacktrace?: string;
+    type?: string;
+}
+
+export interface WorkflowRunEvent {
     event_id: number;
-    event_time: number;
+    event_time: string | null;
     event_type: string;
     task_id?: string;
     attempt: number;
@@ -278,31 +333,90 @@ interface WorkflowRunEvent {
         result?: any,
     };
 
-    signal?: {
-        direction: "receiving" | "sending";
-        signalName?: string,
-        input?: any,
-        sender?: {
-            workflowId?: string,
-            runId?: string
-        }
-        recipient?: {
-            workflowId?: string,
-            runId?: string
-        },
-        initiatedEventId?: string,
-    }
+    signal?: SignalEventProperties;
 
-    error?: {
-        message?: string;
-        source?: string;
-        stacktrace?: string;
-        type?: string;
-    };
+    error?: EventError;
 
     result?: any;
 }
 
+// Task status enum for processed history
+export enum TaskStatus {
+    SCHEDULED = 'scheduled',
+    RUNNING = 'running',
+    COMPLETED = 'completed',
+    FAILED = 'failed',
+    CANCELED = 'canceled',
+    TIMED_OUT = 'timed_out',
+    TERMINATED = 'terminated',
+    SENT = 'sent',        // for signals
+    RECEIVED = 'received', // for signals
+}
+
+// Task type enum
+export enum TaskType {
+    ACTIVITY = 'activity',
+    CHILD_WORKFLOW = 'childWorkflow',
+    SIGNAL = 'signal',
+}
+
+// Base task interface
+interface TaskBase {
+    type: TaskType;
+    activityId: string;
+    activityName?: string;
+    input?: any;
+    scheduled: string | null;
+    status: TaskStatus;
+    attempts: number;
+    started: string | null;
+    completed: string | null;
+    error: string | null;
+    result: any;
+}
+
+// Activity-specific task
+export interface ActivityTask extends TaskBase {
+    type: TaskType.ACTIVITY;
+}
+
+// Child workflow-specific task
+export interface ChildWorkflowTask extends TaskBase {
+    type: TaskType.CHILD_WORKFLOW;
+    workflowType?: string;
+    runId?: string;
+}
+
+// Signal-specific task
+export interface SignalTask extends TaskBase {
+    type: TaskType.SIGNAL;
+    signalName?: string;
+    direction?: 'sending' | 'receiving';
+    sender?: {
+        workflowId?: string;
+        runId?: string;
+    };
+    recipient?: {
+        workflowId?: string;
+        runId?: string;
+    };
+}
+
+// Union type for all processed tasks
+export type WorkflowTask =
+    | ActivityTask
+    | ChildWorkflowTask
+    | SignalTask;
+
+// History format discriminated union
+export type WorkflowHistory =
+    | { type: 'events'; events: WorkflowRunEvent[] }
+    | { type: 'tasks'; tasks: WorkflowTask[] }
+    | { type: 'agent'; data: any };  // Placeholder for future agent format
+
+// History format query parameter type
+export type HistoryFormat = 'events' | 'tasks' | 'agent';
+
 export interface WorkflowRun {
     status?: WorkflowExecutionStatus | string;
     /**
@@ -311,8 +425,8 @@ export interface WorkflowRun {
      * @see https://docs.temporal.io/workflows
      */
     type?: string;
-    started_at?: number;
-    closed_at?: number;
+    started_at: string | null;
+    closed_at: string | null;
     execution_duration?: number;
     run_id?: string;
     workflow_id?: string;
@@ -321,6 +435,7 @@ export interface WorkflowRun {
     input?: any;
     result?: any;
     error?: any,
+    has_reported_errors?: boolean;
     raw?: any;
     /**
      * The Vertesia Workflow Type of this Workflow Run.
@@ -345,19 +460,21 @@ export interface WorkflowRun {
     topic?: string;
 }
 
+export interface PendingActivity {
+    activityId?: string;
+    activityType?: string;
+    attempt: number;
+    maximumAttempts: number;
+    lastFailure?: string;
+    lastStartedTime: string | null;
+}
+
 export interface WorkflowRunWithDetails extends WorkflowRun {
-    history?: WorkflowRunEvent[];
+    history?: WorkflowHistory;
     memo?: {
         [key: string]: any;
     } | null;
-    pendingActivities?: {
-        activityId?: string;
-        activityType?: string;
-        attempt: number;
-        maximumAttempts: number;
-        lastFailure?: string;
-        lastStartedTime?: number;
-    }[];
+    pendingActivities?: PendingActivity[];
 }
 export interface ListWorkflowRunsResponse {
     runs: WorkflowRun[];
@@ -376,6 +493,11 @@ export interface WorkflowInteractionVars {
     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: {
@@ -442,18 +564,369 @@ export interface AgentMessage {
 }
 
 export enum AgentMessageType {
-    SYSTEM = "system",
-    THOUGHT = "thought",
-    PLAN = "plan",
-    UPDATE = "update",
-    COMPLETE = "complete",
-    WARNING = "warning",
+    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;
+    /** Activity ID for deduplication with final THOUGHT/ANSWER message */
+    activity_id?: string;
+}
+
+// ============================================
+// COMPACT MESSAGE FORMAT
+// ============================================
+
+/**
+ * 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;
+    /** Activity ID for deduplication between streaming chunks and final messages */
+    i?: string;
+}
+
+/**
+ * Legacy message format for backward compatibility.
+ * @deprecated Use CompactMessage instead
+ */
+export type LegacyAgentMessage = AgentMessage;
+
+// ============================================
+// TYPE GUARDS
+// ============================================
+
+/**
+ * Check if a message is in compact format
+ */
+export function isCompactMessage(msg: unknown): msg is CompactMessage {
+    return typeof msg === 'object' && msg !== null && 't' in msg;
+}
+
+/**
+ * Check if a message is in legacy format
+ */
+export function isLegacyMessage(msg: unknown): msg is LegacyAgentMessage {
+    return typeof msg === 'object' && msg !== null && 'type' in msg && !('t' in msg);
+}
+
+// ============================================
+// CONVERTERS
+// ============================================
+
+/**
+ * Map old string enum values to AgentMessageType
+ */
+const STRING_TO_TYPE_MAP: Record<string, AgentMessageType> = {
+    'system': AgentMessageType.SYSTEM,
+    'thought': AgentMessageType.THOUGHT,
+    'plan': AgentMessageType.PLAN,
+    'update': AgentMessageType.UPDATE,
+    'complete': AgentMessageType.COMPLETE,
+    'warning': AgentMessageType.WARNING,
+    'error': AgentMessageType.ERROR,
+    'answer': AgentMessageType.ANSWER,
+    'question': AgentMessageType.QUESTION,
+    'request_input': AgentMessageType.REQUEST_INPUT,
+    'idle': AgentMessageType.IDLE,
+    'terminated': AgentMessageType.TERMINATED,
+    'streaming_chunk': AgentMessageType.STREAMING_CHUNK,
+    'batch_progress': AgentMessageType.BATCH_PROGRESS,
+};
+
+/**
+ * Map integer values to AgentMessageType (primary format)
+ */
+const INT_TO_TYPE_MAP: Record<number, AgentMessageType> = {
+    0: AgentMessageType.SYSTEM,
+    1: AgentMessageType.THOUGHT,
+    2: AgentMessageType.PLAN,
+    3: AgentMessageType.UPDATE,
+    4: AgentMessageType.COMPLETE,
+    5: AgentMessageType.WARNING,
+    6: AgentMessageType.ERROR,
+    7: AgentMessageType.ANSWER,
+    8: AgentMessageType.QUESTION,
+    9: AgentMessageType.REQUEST_INPUT,
+    10: AgentMessageType.IDLE,
+    11: AgentMessageType.TERMINATED,
+    12: AgentMessageType.STREAMING_CHUNK,
+    13: AgentMessageType.BATCH_PROGRESS,
+};
+
+/**
+ * Normalize message type from string or number to AgentMessageType
+ */
+export function normalizeMessageType(type: string | number | AgentMessageType): AgentMessageType {
+    // Handle integer type (current format and AgentMessageType enum values)
+    if (typeof type === 'number') {
+        return INT_TO_TYPE_MAP[type] ?? AgentMessageType.UPDATE;
+    }
+    // Handle string type (legacy messages from Redis with 90-day TTL)
+    if (typeof type === 'string') {
+        return STRING_TO_TYPE_MAP[type] ?? AgentMessageType.UPDATE;
+    }
+    return AgentMessageType.UPDATE;
+}
+
+/**
+ * Convert legacy AgentMessage to CompactMessage
+ */
+export function toCompactMessage(legacy: LegacyAgentMessage): CompactMessage {
+    const compact: CompactMessage = {
+        t: normalizeMessageType(legacy.type),
+    };
+
+    if (legacy.message) compact.m = legacy.message;
+    if (legacy.workstream_id && legacy.workstream_id !== 'main') compact.w = legacy.workstream_id;
+    if (legacy.timestamp) compact.ts = legacy.timestamp;
+
+    // Handle legacy streaming chunk details
+    if (compact.t === AgentMessageType.STREAMING_CHUNK && legacy.details) {
+        const d = legacy.details as StreamingChunkDetails;
+        if (d.is_final) compact.f = 1;
+        // streaming_id and chunk_index are no longer needed
+    } else if (legacy.details) {
+        compact.d = legacy.details;
+    }
+
+    return compact;
+}
+
+/**
+ * Parse any message format (compact or legacy) into CompactMessage.
+ * Use this as the entry point for all received messages.
+ */
+export function parseMessage(data: string | object): CompactMessage {
+    const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+    if (isCompactMessage(parsed)) return parsed;
+    if (isLegacyMessage(parsed)) return toCompactMessage(parsed);
+    throw new Error('Unknown message format');
+}
+
+/**
+ * Create a compact message (convenience function for server-side)
+ */
+export function createCompactMessage(
+    type: AgentMessageType,
+    options: {
+        message?: string;
+        workstreamId?: string;
+        details?: unknown;
+        isFinal?: boolean;
+        timestamp?: number;
+    } = {}
+): CompactMessage {
+    const compact: CompactMessage = { t: type };
+
+    if (options.message) compact.m = options.message;
+    if (options.workstreamId && options.workstreamId !== 'main') compact.w = options.workstreamId;
+    if (options.details) compact.d = options.details;
+    if (options.isFinal) compact.f = 1;
+    if (options.timestamp) compact.ts = options.timestamp;
+
+    return compact;
+}
+
+/**
+ * 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 function toAgentMessage(compact: CompactMessage, workflowRunId: string = ''): AgentMessage {
+    const message: AgentMessage = {
+        type: compact.t,
+        timestamp: compact.ts || Date.now(),
+        workflow_run_id: workflowRunId,
+        message: compact.m || '',
+        workstream_id: compact.w || 'main',
+    };
+
+    if (compact.d !== undefined) message.details = compact.d;
+
+    // For streaming chunks, restore is_final and streaming_id in details
+    // (streaming_id removed from wire format, use workstream_id as grouping key)
+    if (compact.t === AgentMessageType.STREAMING_CHUNK) {
+        message.details = {
+            ...(typeof compact.d === 'object' ? compact.d : {}),
+            streaming_id: compact.w || 'main', // Use workstream_id as streaming_id
+            is_final: compact.f === 1,
+            activity_id: compact.i, // For deduplication with final THOUGHT/ANSWER
+        };
+    }
+
+    return message;
+}
+
+/**
+ * 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 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",
-    ANSWER = "answer",
-    QUESTION = "question",
-    REQUEST_INPUT = "request_input",
-    IDLE = "idle",
-    TERMINATED = "terminated",
+}
+
+/**
+ * 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 function getWorkflowChannel(workflowRunId: string): string {
+    return `workflow:${workflowRunId}:channel`;
+}
+
+/**
+ * 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 function getWorkflowUpdatesKey(workflowRunId: string): string {
+    return `workflow:${workflowRunId}:updates`;
 }
 
 export interface PlanTask {
@@ -519,3 +992,89 @@ export interface WorkflowActionPayload {
      */
     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;
+}