@vertesia/common 1.0.0-dev.20260227.112605Z → 1.0.0-dev.20260331.091034Z

package/src/payload.ts

@@ -9,6 +9,16 @@ import {
     RunSearchQuery,
     SimpleSearchQuery
 } from "./query.js";
+import { ColumnLayout } from "./store/store.js";
+
+export type SortOrder = 'asc' | 'desc';
+
+export interface SortOption {
+    /** Field path to sort by (e.g. 'updated_at', 'name', 'properties.title') */
+    field: string;
+    /** Sort direction. Defaults to 'desc'. */
+    order?: SortOrder;
+}
 
 export interface SearchPayload {
     facets?: FacetSpec[];
@@ -23,6 +33,10 @@ export interface SearchPayload {
     select?: string;
     all_revisions?: boolean;
     from_root?: string;
+    /** Sort criteria. Multiple entries enable multi-field sorting (first entry is primary). */
+    sort?: SortOption[];
+    /** Arbitrary Elasticsearch aggregation definitions. Ignored when search falls back to MongoDB. */
+    aggs?: Record<string, unknown>;
 }
 
 export interface ComputeFacetPayload {
@@ -74,6 +88,7 @@ export interface ExportPropertiesPayload {
     objectIds: string[];
     type: string;
     query?: ComplexSearchQuery;
+    table_layout?: ColumnLayout[];
 }
 
 export interface ExportPropertiesResponse {

package/src/project.ts

@@ -1,5 +1,6 @@
 import { SupportedIntegrations } from "./integrations.js";
 import { ContentObjectTypeRef } from "./store/store.js";
+import { WorkflowRunStatus } from "./store/workflow.js";
 import { AccountRef } from "./user.js";
 
 export interface ICreateProjectPayload {
@@ -157,11 +158,6 @@ export interface ProjectConfiguration {
 
     human_context: string;
 
-    /** @deprecated Use defaults.base - kept for backward compatibility */
-    default_environment?: string;
-    /** @deprecated Use defaults.base - kept for backward compatibility */
-    default_model?: string;
-
     defaults?: ProjectModelDefaults;
 
     default_visibility?: ResourceVisibility;
@@ -285,34 +281,34 @@ export interface EmbeddingsStatusResponse {
  */
 export interface IndexingStatusResponse {
     /** Whether indexing infrastructure is available globally */
-    infrastructureEnabled: boolean;
+    infrastructure_enabled: boolean;
     /** Whether indexing is enabled for this project */
-    indexingEnabled: boolean;
-    /** @deprecated Now derived from indexingEnabled - queries automatically route to index when indexing is enabled */
+    indexing_enabled: boolean;
+    /** @deprecated Now derived from indexing_enabled - queries automatically route to index when indexing is enabled */
     query_enabled: boolean;
     /** Index status */
     index: {
         /** Whether the index exists */
         exists: boolean;
         /** Alias name (used for queries) */
-        aliasName: string;
+        alias_name: string;
         /** Actual index name (versioned) */
-        indexName: string;
+        index_name: string;
         /** Index version (timestamp when created) */
         version: number;
         /** When the current index was created */
-        createdAt: string | null;
+        created_at: string | null;
         /** Number of documents in the index */
-        documentCount: number;
+        document_count: number;
         /** Index size in bytes */
-        sizeBytes: number;
+        size_bytes: number;
     };
     /** MongoDB document count for comparison */
-    mongoDocumentCount: number;
+    mongo_document_count: number;
     /** Whether a reindex is currently in progress */
-    reindexInProgress: boolean;
+    reindex_in_progress: boolean;
     /** Reindex progress (if reindex is in progress) */
-    reindexProgress?: {
+    reindex_progress?: {
         /** Total documents to reindex */
         total: number;
         /** Documents processed so far */
@@ -324,19 +320,29 @@ export interface IndexingStatusResponse {
         /** Current status (e.g., "indexing", "complete") */
         status: string;
         /** Current batch number */
-        currentBatch: number;
+        current_batch: number;
         /** Total number of batches */
-        totalBatches: number;
+        total_batches: number;
         /** Percentage complete (0-100) */
-        percentComplete: number;
+        percent_complete: number;
         /** Batches processed per second */
-        batchesPerSecond: number;
+        batches_per_second: number;
         /** Documents processed per second */
-        docsPerSecond: number;
+        docs_per_second: number;
         /** Elapsed time in seconds */
-        elapsedSeconds: number;
+        elapsed_seconds: number;
         /** Estimated seconds remaining (null if unknown) */
-        estimatedSecondsRemaining: number | null;
+        estimated_seconds_remaining: number | null;
+        /** Total bytes sent to ES */
+        total_bytes?: number;
+        /** Total ES bulk flushes */
+        bulk_flushes?: number;
+        /** Average bytes per ES bulk flush */
+        avg_flush_bytes?: number;
+        /** Configured batch size */
+        batch_size?: number;
+        /** Configured parallel batch count */
+        parallel_batch_count?: number;
     };
 }
 
@@ -382,8 +388,8 @@ export interface BulkIndexResult {
  */
 export interface CreateReindexTargetResult {
     created: boolean;
-    indexName: string;
-    aliasName: string;
+    index_name: string;
+    alias_name: string;
     version: number;
 }
 
@@ -404,7 +410,7 @@ export interface FetchBatchResult {
         id: string;
         document: ElasticsearchDocumentData;
     }>;
-    nextCursor: string | null;
+    next_cursor: string | null;
     done: boolean;
 }
 
@@ -415,7 +421,26 @@ export interface IndexBatchResult {
     successful: number;
     failed: number;
     processed: number;
-    nextCursor: string | null;
+    next_cursor: string | null;
+    done: boolean;
+    /** Number of ES bulk flushes performed */
+    bulk_flushes?: number;
+    /** Total bytes sent to ES */
+    total_bytes?: number;
+    /** Average bytes per ES bulk flush */
+    avg_flush_bytes?: number;
+    /** Duration of the batch in milliseconds */
+    duration_ms?: number;
+    /** Docs per second for this batch */
+    docs_per_second?: number;
+}
+
+/**
+ * Result from discovering the next cursor boundary for batch partitioning
+ */
+export interface NextIndexCursorResult {
+    next_cursors: string[];
+    count: number;
     done: boolean;
 }
 
@@ -425,9 +450,9 @@ export interface IndexBatchResult {
 export interface TriggerReindexResult {
     status: string;
     workflow?: string;
-    workflowId?: string;
-    runId?: string;
-    objectCount?: number;
+    workflow_id?: string;
+    run_id?: string;
+    object_count?: number;
     reason?: string;
     enabled?: boolean;
 }
@@ -438,10 +463,10 @@ export interface TriggerReindexResult {
 export interface ElasticsearchIndexStats {
     enabled: boolean;
     exists?: boolean;
-    documentCount?: number;
-    sizeInBytes?: number;
-    indexName?: string;
-    aliasName?: string;
+    document_count?: number;
+    size_in_bytes?: number;
+    index_name?: string;
+    alias_name?: string;
 }
 
 /**
@@ -461,25 +486,25 @@ export interface EmbeddingTypeConfig {
 export interface IndexConfiguration {
     enabled: boolean;
     exists?: boolean;
-    indexName?: string;
-    aliasName?: string;
+    index_name?: string;
+    alias_name?: string;
     version?: number;
-    documentCount?: number;
-    sizeInBytes?: number;
-    embeddingDimensions?: {
+    document_count?: number;
+    size_in_bytes?: number;
+    embedding_dimensions?: {
         text?: number;
         image?: number;
         properties?: number;
     };
     /** ISO 639-1 language code for text analysis */
     language?: string;
-    fieldMappings?: Record<string, unknown>;
-    projectEmbeddingsConfig?: {
+    field_mappings?: Record<string, unknown>;
+    project_embeddings_config?: {
         text?: EmbeddingTypeConfig;
         image?: EmbeddingTypeConfig;
         properties?: EmbeddingTypeConfig;
     };
-    createdAt?: Date | null;
+    created_at?: Date | null;
 }
 
 /**
@@ -527,7 +552,7 @@ export interface FetchDocumentsByIdsResult {
         id: string;
         document: ElasticsearchDocumentData;
     }>;
-    notFound: string[];
+    not_found: string[];
 }
 
 /**
@@ -555,17 +580,57 @@ export interface EnsureIndexResult {
     language?: string;
 }
 
+export interface AnalyzeDriftBatchResult {
+    processed: number;
+    missing: number;
+    stale: number;
+    next_cursor: string | null;
+    done: boolean;
+    sample_missing_ids: string[];
+    sample_stale_ids: string[];
+}
+
+export interface DriftAnalysisProgress {
+    total: number;
+    processed: number;
+    missing: number;
+    stale: number;
+    status: string;
+    current_batch: number;
+    total_batches: number;
+    percent_complete: number;
+    docs_per_second: number;
+    elapsed_seconds: number;
+    estimated_seconds_remaining: number | null;
+}
+
+export interface DriftAnalysisResult {
+    total: number;
+    processed: number;
+    missing: number;
+    stale: number;
+    sample_missing_ids: string[];
+    sample_stale_ids: string[];
+    completed_at: string;
+}
+
+export interface DriftAnalysisStatusResponse extends WorkflowRunStatus {
+    progress?: DriftAnalysisProgress;
+    result?: DriftAnalysisResult;
+    error?: string;
+}
+
 /**
  * Result from swap alias operation
  */
 export interface SwapAliasResult {
     swapped: boolean;
-    aliasName?: string;
-    newIndexName?: string;
+    alias_name?: string;
+    new_index_name?: string;
     reason?: string;
 }
 
 export interface ProjectIntegrationListEntry {
     id: SupportedIntegrations;
     enabled: boolean;
-}
+}

package/src/query.ts

@@ -44,6 +44,7 @@ export interface SimpleSearchQuery {
 
 export interface ObjectSearchQuery extends SimpleSearchQuery {
     id?: string;
+    ids?: string[];
     createdFrom?: string;
     createdTo?: string;
     updatedFrom?: string;
@@ -89,6 +90,7 @@ export interface RunSearchQuery extends SimpleSearchQuery {
     finish_reason?: string;
     created_by?: string;
     workflow_run_ids?: string[];
+    workflow_ids?: string[];
     run_ids?: string[];
 }
 

package/src/runs.ts

@@ -17,6 +17,21 @@ export interface ExecutionRunDocRef {
 export interface RunCreatePayload extends NamedInteractionExecutionPayload {
 }
 
+/**
+ * Payload for cloning an existing ExecutionRun.
+ * Creates a new run document with the same interaction/config but fresh status.
+ * Used by fork flows to create a new ExecutionRun for the forked workflow.
+ */
+export interface RunClonePayload {
+    /** The _id of the source ExecutionRun to clone */
+    source_run_id: string;
+    /** Temporal workflow reference for the new run */
+    workflow: {
+        run_id: string;
+        workflow_id: string;
+    };
+}
+
 /**
  * To be used as a value for a numeric or date filters
  */

package/src/store/agent-run.ts

@@ -0,0 +1,350 @@
+/**
+ * AgentRun Types
+ *
+ * Defines the stable identity layer for running or completed agents.
+ * Decouples the application from Temporal's internal run lifecycle,
+ * enabling future continueAsNew support without breaking client references.
+ *
+ * The AgentRun is stored in MongoDB and provides a stable ID that doesn't
+ * change when Temporal workflows restart via continueAsNew.
+ *
+ * Client code only ever uses `AgentRun.id` — all Temporal workflow details
+ * (workflowId, runId) are internal server concerns.
+ */
+
+import { AgentSearchScope, ConversationVisibility, InteractionExecutionConfiguration, RunSource } from "../interaction.js";
+import { UserChannel } from "../email.js";
+import { ContentObjectTypeRef } from "./store.js";
+import { ConversationActivityState } from "./workflow.js";
+
+/**
+ * Status of an agent run through its lifecycle.
+ */
+export type AgentRunStatus = 'created' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * How the agent run was created.
+ */
+export type AgentRunType = 'api' | 'schedule';
+
+/**
+ * Shared fields between CreateAgentRunPayload and AgentRun.
+ *
+ * @typeParam TData - The interaction's expected input data type.
+ * @typeParam TProperties - The content type's property schema.
+ */
+export interface AgentRunBase<TData = Record<string, any>, TProperties = Record<string, any>> {
+    /** Interaction ID or code (e.g. "sys:generic_question") */
+    interaction: string;
+
+    /** Input parameters, typed per interaction */
+    data?: TData;
+
+    /** Execution configuration (environment, model, model_options, etc.) */
+    config?: InteractionExecutionConfiguration;
+
+    /** Whether the agent accepts user input */
+    interactive?: boolean;
+
+    /** Tools configured for this run (+/- syntax supported) */
+    tool_names?: string[];
+
+    /** Scoped collection (if any) */
+    collection_id?: string;
+
+    /** Content type linked to this run — defines the schema for `properties` */
+    content_type?: ContentObjectTypeRef;
+
+    /** Conversation visibility */
+    visibility?: ConversationVisibility;
+
+    /** User-defined or system tags for categorization */
+    tags?: string[];
+
+    /** Categories for organizing runs (e.g. "support", "analysis", "generation") */
+    categories?: string[];
+
+    /** Business metadata — typed by the linked content_type schema */
+    properties?: TProperties;
+
+    /** How the run was started */
+    source?: RunSource;
+
+    /** Schedule ID — set when this run was triggered by a Temporal schedule */
+    schedule_id?: string;
+
+    /** How the run was created */
+    type?: AgentRunType;
+}
+
+/**
+ * AgentRun — the client-facing stable identity for a running or completed agent.
+ *
+ * All operations use `id` as the sole identifier.
+ * Temporal workflow internals are never exposed to clients.
+ *
+ * @typeParam TData - The interaction's expected input data type.
+ * @typeParam TProperties - The content type's property schema.
+ */
+export interface AgentRun<TData = Record<string, any>, TProperties = Record<string, any>> extends AgentRunBase<TData, TProperties> {
+    /** The stable identifier used by all client code */
+    id: string;
+
+    /** Account ID */
+    account: string;
+
+    /** Project ID */
+    project: string;
+
+    // --- Temporal workflow references ---
+
+    /** Temporal workflow ID (stable across continueAsNew) */
+    workflow_id?: string;
+
+    /** First Temporal workflow run ID (used for Redis channel and artifact resolution) */
+    first_workflow_run_id?: string;
+
+    // --- Interaction info ---
+
+    /** Human-readable interaction name */
+    interaction_name?: string;
+
+    // --- Lifecycle ---
+
+    /** Current status of the agent run */
+    status: AgentRunStatus;
+
+    /** Whether the agent is currently working or idle (waiting for user input) */
+    activity_state?: ConversationActivityState;
+
+    /** When the run started */
+    started_at: Date;
+
+    /** When the run completed (or failed/cancelled) */
+    completed_at?: Date;
+
+    /** User or service that initiated the run */
+    started_by: string;
+
+    // --- Metadata ---
+
+    /** Conversation title (short, human-readable) */
+    title?: string;
+
+    /** Conversation topic (longer description from topic analysis) */
+    topic?: string;
+
+    /** Lessons learned from the conversation (extracted at completion) */
+    lessons_learned?: string[];
+
+    /** Timestamp when the document was created */
+    created_at: Date;
+
+    /** Timestamp when the document was last updated */
+    updated_at: Date;
+}
+
+/**
+ * Payload to create and start a new agent run.
+ *
+ * @typeParam TData - The interaction's expected input data type.
+ * @typeParam TProperties - The content type's property schema.
+ */
+export interface CreateAgentRunPayload<TData = Record<string, any>, TProperties = Record<string, any>> extends AgentRunBase<TData, TProperties> {
+    /** Search scope for RAG queries */
+    search_scope?: AgentSearchScope;
+
+    /** User communication channels (email, interactive) */
+    user_channels?: UserChannel[];
+
+    /** Token budget for checkpointing */
+    checkpoint_tokens?: number;
+
+    /** Maximum conversation iterations (default: 20) */
+    max_iterations?: number;
+
+    /** Webhook URLs to notify on completion */
+    notify_endpoints?: string[];
+
+    /** Enable debug mode for verbose logging */
+    debug_mode?: boolean;
+
+    /** Principal ref of the user who initiated the run (for server-to-server forwarding) */
+    started_by?: string;
+}
+
+/**
+ * Filters for listing agent runs.
+ */
+export interface ListAgentRunsQuery {
+    /** Filter by agent run ID */
+    id?: string;
+
+    /** Filter by status (single or multiple) */
+    status?: AgentRunStatus | AgentRunStatus[];
+
+    /** Filter by interaction ID or code */
+    interaction?: string;
+
+    /** Filter by user who started the run */
+    started_by?: string;
+
+    /** Only return runs started after this date */
+    since?: Date;
+
+    /** Maximum number of results (default: 50) */
+    limit?: number;
+
+    /** Offset for pagination */
+    offset?: number;
+
+    /** Filter by schedule ID */
+    schedule_id?: string;
+
+    /** Filter by run type */
+    type?: AgentRunType;
+
+    /** Field to sort by */
+    sort?: 'started_at' | 'updated_at';
+
+    /** Sort order */
+    order?: 'asc' | 'desc';
+}
+
+/**
+ * Query for searching agent runs via Elasticsearch.
+ */
+export interface SearchAgentRunsQuery {
+    /** Full-text search across name, title, topic, interaction_name, and content */
+    query?: string;
+
+    /** Filter by status (single or multiple) */
+    status?: AgentRunStatus | AgentRunStatus[];
+
+    /** Filter by interaction ID or code */
+    interaction?: string;
+
+    /** Filter by user who started the run */
+    started_by?: string;
+
+    /** Filter by categories */
+    categories?: string[];
+
+    /** Filter by tags */
+    tags?: string[];
+
+    /** Filter by content type name */
+    content_type_name?: string;
+
+    /** Only return runs started after this date */
+    since?: Date;
+
+    /** Maximum number of results (default: 50) */
+    limit?: number;
+
+    /** Offset for pagination */
+    offset?: number;
+}
+
+/**
+ * A single search hit from Elasticsearch.
+ */
+export interface AgentRunSearchHit {
+    /** Agent run ID */
+    id: string;
+
+    /** Relevance score */
+    score: number;
+
+    /** Interaction ID */
+    interaction: string;
+
+    /** Human-readable interaction name */
+    interaction_name?: string;
+
+    /** Current status */
+    status: AgentRunStatus;
+
+    /** Whether the agent is currently working or idle */
+    activity_state?: ConversationActivityState;
+
+    /** When the run started */
+    started_at: string;
+
+    /** When the run completed */
+    completed_at?: string;
+
+    /** Who started the run */
+    started_by: string;
+
+    /** Conversation title */
+    title?: string;
+
+    /** Conversation topic */
+    topic?: string;
+
+    /** Lessons learned from the conversation */
+    lessons_learned?: string[];
+
+    /** Tags */
+    tags?: string[];
+
+    /** Categories */
+    categories?: string[];
+
+    /** Whether the agent accepts user input */
+    interactive: boolean;
+
+    /** Collection ID */
+    collection_id?: string;
+
+    /** Content type */
+    content_type?: ContentObjectTypeRef;
+
+    /** Tools configured for this run */
+    tool_names?: string[];
+
+    /** Schedule ID (if schedule-triggered) */
+    schedule_id?: string;
+
+    /** How the run was created */
+    type?: AgentRunType;
+
+    /** Created timestamp */
+    created_at: string;
+
+    /** Updated timestamp */
+    updated_at: string;
+}
+
+/**
+ * Response from the agent runs search endpoint.
+ */
+export interface SearchAgentRunsResponse {
+    /** Search results */
+    hits: AgentRunSearchHit[];
+
+    /** Total matching results */
+    total: number;
+}
+
+/**
+ * Internal/Temporal details for an AgentRun.
+ * Includes fields normally stripped from client responses.
+ */
+export interface AgentRunInternals {
+    id: string;
+    workflow_id?: string;
+    first_workflow_run_id?: string;
+    artifacts_path?: string;
+    status: AgentRunStatus;
+    interaction: string;
+    interaction_name?: string;
+    config?: InteractionExecutionConfiguration;
+    interactive: boolean;
+    started_at: Date;
+    completed_at?: Date;
+    started_by: string;
+    created_at: Date;
+    updated_at: Date;
+}