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

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,19 @@ 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;
     };
 }
 
@@ -382,8 +378,8 @@ export interface BulkIndexResult {
  */
 export interface CreateReindexTargetResult {
     created: boolean;
-    indexName: string;
-    aliasName: string;
+    index_name: string;
+    alias_name: string;
     version: number;
 }
 
@@ -404,7 +400,7 @@ export interface FetchBatchResult {
         id: string;
         document: ElasticsearchDocumentData;
     }>;
-    nextCursor: string | null;
+    next_cursor: string | null;
     done: boolean;
 }
 
@@ -415,7 +411,16 @@ export interface IndexBatchResult {
     successful: number;
     failed: number;
     processed: number;
-    nextCursor: string | null;
+    next_cursor: string | null;
+    done: boolean;
+}
+
+/**
+ * Result from discovering the next cursor boundary for batch partitioning
+ */
+export interface NextIndexCursorResult {
+    next_cursors: string[];
+    count: number;
     done: boolean;
 }
 
@@ -425,9 +430,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 +443,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 +466,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 +532,7 @@ export interface FetchDocumentsByIdsResult {
         id: string;
         document: ElasticsearchDocumentData;
     }>;
-    notFound: string[];
+    not_found: string[];
 }
 
 /**
@@ -555,17 +560,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;

package/src/store/agent-run.ts

@@ -0,0 +1,347 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}

package/src/store/conversation-state.ts

@@ -136,6 +136,20 @@ export interface ConversationState {
 
     /** LLM stop reason from the latest call (e.g., "stop", "length", "tool_use") */
     finish_reason?: string;
+
+    /**
+     * The AgentRun ID (MongoDB _id) that owns this conversation.
+     * Used for artifact storage paths: agents/{agent_run_id}/
+     * Undefined for legacy workflows started before the AgentRun system.
+     */
+    agent_run_id?: string;
+
+    /**
+     * For workstreams: the launch ID assigned by the parent workflow.
+     * When set, artifacts are stored under agents/{agent_run_id}/workstreams/{launch_id}/
+     * to consolidate all artifacts under the parent agent run.
+     */
+    launch_id?: string;
 }
 
 /** Skill metadata collected at workflow start for upfront sandbox hydration */
@@ -146,6 +160,25 @@ export interface AvailableSkill {
     src: string;
 }
 
+/**
+ * Compute the storage ID for a conversation's artifacts.
+ * - Root workflows:   `{agent_run_id}`  (or fallbackRunId if no agent_run_id)
+ * - Workstreams:      `{agent_run_id}/workstreams/{launch_id}`
+ *
+ * Both studio-server and workflow activities must use the same logic so
+ * parent and child conversations don't overwrite each other.
+ */
+export function getConversationStorageId(
+    state: Pick<ConversationState, 'agent_run_id' | 'launch_id'> | undefined,
+    fallbackRunId: string,
+): string {
+    const baseId = state?.agent_run_id || fallbackRunId;
+    if (state?.launch_id && state?.agent_run_id) {
+        return `${baseId}/workstreams/${state.launch_id}`;
+    }
+    return baseId;
+}
+
 /** Skill metadata tracked when a skill is used */
 export interface UsedSkill {
     /** Skill name (e.g., "analyze_data") */

package/src/store/dsl-workflow.ts

@@ -1,4 +1,5 @@
 import { StringValue } from "ms";
+import { ToolExecutionMetadata } from "../tool-execution.js";
 import { BaseObject } from "./common.js";
 import { WorkflowExecutionPayload } from "./index.js";
 import { ParentClosePolicyType } from "./temporalio.js";
@@ -221,12 +222,6 @@ export interface DSLChildWorkflowStep extends DSLWorkflowStepBase {
      * If spec is defined then the name must be "dslWorkflow"
      */
     spec?: DSLWorkflowSpec;
-    /**
-     * If true, copy the parent's workspace artifacts (scripts/, files/, skills/, docs/, out/)
-     * to the child workflow's agent space before execution. Defaults to true.
-     * conversation.json and tools.json are never copied.
-     */
-    inherit_artifacts?: boolean;
     options?: {
         memo?: Record<string, any>;
         retry?: DSLRetryPolicy;
@@ -312,3 +307,28 @@ export interface WorkflowDefinitionRef {
 }
 
 export const WorkflowDefinitionRefPopulate = "id name description tags created_at updated_at"
+
+/**
+ * Payload sent to a remote activity endpoint on a tool server.
+ * This is POSTed by the `executeRemoteActivity` bridge activity.
+ */
+export interface RemoteActivityExecutionPayload<ParamsT extends Record<string, any> = Record<string, any>> {
+    /** The activity name (unprefixed, as known by the tool server) */
+    activity_name: string;
+    /** The resolved activity parameters */
+    params: ParamsT;
+    /** Execution metadata (same shape as tool execution metadata) */
+    metadata?: ToolExecutionMetadata;
+}
+
+/**
+ * Response from a remote activity endpoint on a tool server.
+ */
+export interface RemoteActivityExecutionResponse {
+    /** The result data (stored into workflow vars via the step's `output` field) */
+    result: any;
+    /** Whether the execution failed */
+    is_error?: boolean;
+    /** Error message if is_error is true */
+    error?: string;
+}